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- `mime` - trimmed database of ext -> mime types
29- `node` - tree-shakable loaders for Node.js builtins
30- `progress` - cli and dom progress bars, nesting status indication
31- `queue` - priority queue with rescheduling
32- `repl` - interactive prompt for long running programs
33- `stream` - ReadableStream helpers
34- `string` - trival helpers
35- `string/ansi` - cursor and color constants
36- `subprocess` - rebuilt api for `node:child_process`
37- `subprocess/ffmpeg` - spawn and parse progress output
38- `testing` - stuff used in `@clo/lib`'s unit tests
39- `ts` typescript types and general purpose code
40
41there is currently no hosted documentation site. please refer to the source
42files' comments and the JSR generated documentation.
43
44## usage
45
46unless otherwise noted, it is expected to import modules using a namespace
47import. function names are often concise to avoid repeating redundant words in
48source code.
49
50```ts
51import * as queue from "@clo/lib/queue";
52
53// `run` in the context of `queue` conveys more information
54const result = await queue.run({ ... });
55```
56
57without "barrel" files, using multiple libraries is done by importing each
58library separately:
59
60```ts
61import * as log from "@clo/lib/log";
62// since the namespace cannot be a constructor, capitalized
63// filenames indicate the single export to use.
64import { Lru } from "@clo/lib/Lru";
65```
66
67these patterns developed initially when using a text editor without a language
68server, but i found this pattern to be nicer in general for organizing code. it
69also resulted in fewer lines spent on imports, and making it much easier to
70understand where code comes from. to this extent, all of the library modules are
71named as single words so they can be easily imported.
72
73## versioning
74
75these libraries are published as is, **without versioning or maintainance
76guarantees**. every version is a breaking major release. please upgrade your
77libraries with intent, considering api changes in [readme.changes.md].
78individual modules may annotate their intended api and usage stability.
79
80keep in mind there are [known bugs and missing features] in this release.
81
82## contributions
83
84to contribute, please send bug reports or patches to <dev@paperclover.net>. new
85features may not be accepted if they are complex and don't further my use cases.
86
87[readme.changes.md]: ./readme.changes.md
88[known bugs and missing features]: https://git.paperclover.net/clo/sitegen/issues?state=open&labels=4
89[clover's typescript library]: https://git.paperclover.net/clo/sitegen/src/branch/master/lib