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