ReviewOS

also looking at this

stacks/ts-css

Merge @stacksjs/ts-css into this repo as packages/toolkit

#27
Merged glennmichael123 wants to merge merge/ts-css-toolkit into main
128 files +9797 -201
packages/toolkit/docs/benchmarks.mdadded+91-0
Changes to packages/toolkit/docs/benchmarks.md
@@ -0,0 +1,91 @@
1# Benchmarks
2
3Numbers below are from a representative `~6 KB` CSS fixture
4(reset + utilities + component CSS), measured with
5[`mitata`](https://github.com/evanwashere/mitata) on Bun.
6
7## Run them yourself
8
9```bash
10bun run bench
11```
12
13The bench script lives at `bench/index.bench.ts` and benchmarks every
14public API against the closest community equivalent:
15
16| ts-css module | compared with |
17|---|---|
18| `parse` | `css-tree.parse` |
19| `walk` | `css-tree.walk` |
20| `generate` | `css-tree.generate` |
21| `what.parse`| `css-what.parse` |
22| `selectAll` | `css-select.selectAll` |
23| `minify` | `csso.minify` |
24| **end-to-end**: `minify(source)` | `csso.minify(source)` |
25
26## Latest numbers (Apple M3 Pro, Bun 1.3)
27
28```
29Fixture: ~6 KB stylesheet
30
31parse stylesheet
32 ts-css 83 µs/iter (ts-css 1.10× faster)
33 css-tree 92 µs/iter
34
35generate stylesheet
36 ts-css 19 µs/iter (ts-css 4.0× faster)
37 css-tree 77 µs/iter
38
39walk all nodes
40 ts-css 32 µs/iter (ts-css 1.34× faster)
41 css-tree 43 µs/iter
42
43parse 7 selectors
44 ts-css 1.6 µs/iter (ts-css 1.65× faster)
45 css-what 2.7 µs/iter
46
47selectAll on a 250-node tree
48 ts-css 40 µs/iter (ts-css 1.13× faster)
49 css-select 45 µs/iter
50
51minify stylesheet
52 ts-css 277 µs/iter (ts-css 3.3× faster)
53 csso 907 µs/iter
54
55end-to-end (parse → minify → generate)
56 ts-css 271 µs/iter (ts-css 3.28× faster)
57 csso 890 µs/iter
58```
59
60## Why we win on `generate` and `minify`
61
62- **`generate`** is a tight switch over the AST that walks the doubly
63 linked list directly — no allocations beyond string concatenation, no
64 array materialization to support lookahead, no formatter options.
65- **`minify`** does a single AST walk that combines value compression and
66 whitespace compaction (no second tree traversal), short-circuits
67 declaration dedup on blocks with fewer than two declarations, and uses
68 manual scans where css-select / csso fall back to per-call regex.
69
70## Why we win on `parse` and `selectAll`
71
72- **`parse`** — declaration values and at-rule preludes are parsed
73 directly off the existing token stream by temporarily lowering an
74 in-state `end` index. Re-tokenizing each declaration value text (the
75 obvious approach) is what makes other parsers slower; we never do it.
76- **`selectAll`** — we ship our own iterative `findAll` so the consumer
77 adapter's `findAll` (often a recursive `[].push(...spread)` shape that
78 allocates per node) doesn't gate selector matching. The compile chain
79 uses fail-fast leaves (`ALWAYS_TRUE` short-circuits `&& next(e)` calls)
80 and procedure-cost sorting so the cheapest test in a compound runs
81 first. Compile results are cached two-level (adapter + flags →
82 selector) so per-call key allocation is gone.
83- **`what.parse`** — sticky regex (`/.../y`) lets us match identifier
84 tokens without slicing. `charCodeAt` dispatch instead of `charAt`
85 string allocation.
86
87## End-to-end is what matters
88
89For build-tool pipelines that run parse → walk → mutate → generate, the
90combined pipeline completes in **roughly a third of the time** of the
91csso default — and ships **zero runtime dependencies**.