1# [clover's typescript library]
2
3`lib` is a collection of high-quality typescript libraries for things missing in
4either browsers or node.js. originally, these were helper functions used to
5create my website, <https://paperclover.net>, but i started wanting them across
6projects and at work.
7
8<!--%npm%-->
9
10## contents
11
12all top-level namespaces stand alone as their own projects, and generally do not
13depend on each other. there are no external dependencies; code is easy to audit.
14
15- `array` - trivial helpers
16- `assert` - assertion and type narrowing functions
17- `async` - promise and asynchronous helpers
18- `bytes` - `Uint8Array` helpers
19- `Events` - typed event emitter
20- `exception` - interop with the `unknown` type in error handlers
21- `http` - basic http server and utilities
22- `incremental` - build system with perfect dependency tracking
23- `incremental/visualization` - browser developer tools
24- `log` - logging, terminal i/o, interactive widgets
25- `log/stack` - stack trace parse and formatter
26- `Lru` - least recently used cache
27- `math` - trivial helpers
28- `meta` - head tags from a page's metadata, and back from a parsed document
29- `mime` - trimmed database of ext -> mime types
30- `node` - tree-shakable loaders for Node.js builtins
31- `progress` - cli and dom progress bars, nesting status indication
32- `queue` - priority queue with rescheduling
33- `repl` - interactive prompt for long running programs
34- `stream` - ReadableStream helpers
35- `string` - trivial helpers
36- `string/ansi` - cursor and color constants
37- `subprocess` - rebuilt api for `node:child_process`
38- `subprocess/ffmpeg` - spawn and parse progress output
39- `testing` - stuff used in `@clo/lib`'s unit tests
40- `ts` typescript types and general purpose code
41
42there is currently no hosted documentation site. please refer to the source
43files' comments and the JSR generated documentation.
44
45## usage
46
47unless otherwise noted, it is expected to import modules using a namespace
48import. function names are often concise to avoid repeating redundant words in
49source code.
50
51```ts
52import * as queue from "@clo/lib/queue";
53
54// `run` in the context of `queue` conveys more information
55const result = await queue.run({ ... });
56```
57
58without "barrel" files, using multiple libraries is done by importing each
59library separately:
60
61```ts
62import * as log from "@clo/lib/log";
63// since the namespace cannot be a constructor, capitalized
64// filenames indicate the single export to use.
65import { Lru } from "@clo/lib/Lru";
66```
67
68these patterns developed initially when using a text editor without a language
69server, but i found this pattern to be nicer in general for organizing code. it
70also resulted in fewer lines spent on imports, and making it much easier to
71understand where code comes from. to this extent, all of the library modules are
72named as single words so they can be easily imported.
73
74## versioning
75
76these libraries are published as is, **without versioning or maintenance
77guarantees**. every version is a breaking major release. please upgrade your
78libraries with intent, considering api changes in [readme.changes.md].
79individual modules may annotate their intended api and usage stability.
80
81keep in mind there are [known bugs and missing features] in this release.
82
83## contributions
84
85to contribute, please send bug reports or patches to <dev@paperclover.net>. new
86features may not be accepted if they are complex and don't further my use cases.
87
88[readme.changes.md]: ./readme.changes.md
89[known bugs and missing features]: https://git.paperclover.net/clo/sitegen/issues?state=open&labels=4
90[clover's typescript library]: https://git.paperclover.net/clo/sitegen/src/branch/master/lib