TinySource

Completely free TS/JS one-file source code snippets with tests, which can be copied to avoid extra dependencies (contributions welcome).

Snippets

• fsm - Finite state machine.
• hash-djb2a - Fast and good string hash function.
• events - Named events with publication and subscription.
• react-use-boolean - Boolean React states with helpful setters.
• react-use-subject - Subjects as sharable, atomic, React states.
• subject - Subscribable values.
• subject-selector - Subscribable values computed from other subjects.

The case for copying

What if, instead of adding another dependency to your project, or having to write utility code yourself, you just copied some already tested code? You've probably already even done this privately.

Copying isn't a good solution for large dependencies (eg. React), but its definitely feasible for smaller dependencies like: individual RxJS utilities, simple state management, collections, algorithms, validation, string parsing, React hooks, types, etc. Think stack overflow, but curated and tested.

Pros:

• Still leveraging community written code
• Tests are already written
• No risk of supply chain attacks
• No risk of version hell
• No licensing conflicts
• Build-time downleveling and transpiling
• Customizable
• Easier to debug

Cons:

• Possible code duplication in multiple projects
  • Larger source/bundle sizes
  • Diverging implementations
• No versioned updates

Duplication can be mitigated by using a monorepo to locally share code, or by relying on compression to reduce the duplication overhead.

Even though updates aren't as simple as changing a version number, re-copying over a single file is not very much overhead. Also, the code being in your project allows for ad-hoc/custom updates. If the tests still pass after the new code is copied, then the update should be safe.

Requirements for copyable snippets

There are some simple rules of thumb for code that is easy and helpful to copy into your project.

• No runtime dependencies
  • With the exception of a single popular framework, if the snippet is specifically designed for that framework (eg. React)
• One reasonably sized source file (~150 lines)
• One test file (Jest compatible in this repo)
• Free and unencumbered in the public domain (eg. under the CC0-1.0 license)

Contributing to this repository

By contributing code to this repository, you agree to release it into the public domain under the CC0-1.0 license, and that others are free to copy and modify the code as they see fit.

If you agree, then...

• Fork the repository
• Add a new directory containing three files:
  • A source file (eg. foo/foo.ts)
    • Add docblock comments to all exports
    • Please use kebab-case for directory and file names
  • A test file matching the source file (eg. foo/foo.test.ts)
  • A readme file (eg. foo/README.md)
    • Describe what the snippet for
    • Show example use
• Run npm test at the repo root to ensure tests run, pass, and have reasonable (80%) coverage
• Add an entry to the end of the Snippets list
• Open a pull request

Pull requests will be merged after verifying that the code meets the requirements called out in this document.