From 1720f2274d565f940a69000019c7d40bd7c41b71 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 7 Aug 2026 13:35:17 +0000 Subject: [PATCH 1/5] =?UTF-8?q?=F0=9F=93=84=20docs:=20bring=20the=20landin?= =?UTF-8?q?g=20page=20up=20to=200.4.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The page still described 0.3.0. Two of the stale strings were in a shell block a visitor is meant to copy โ€” `npm pack # โ†’ cereale-0.3.0.tgz` then `npm install ../cereale/cereale-0.3.0.tgz`, which is an ENOENT for anyone following the install instructions today. Corrected: five version strings (the badge fallback, the pack/install pair, the "lives in the repository" claim, and the diagnosability paragraph, which becomes past tense rather than 0.4.0); seven GitHub URLs using the redirect-only capitalised org name, which the framework table added in 0.4.0 had already stopped doing; NestJS pinned to 11.1 and Bun to 1.3, matching FRAMEWORKS.md, where every other row was already pinned; `tsc` given its 5.2 floor, which the page had never stated anywhere. Added, all of it absent before: - A bundle-size section with the measured table across esbuild, rollup and webpack, the independence of the serializer and deserializer, and why the regression was invisible to a single-bundler measurement. - `cereale/min` in the install section, with the import-map form and the caveat that leads FRAMEWORKS.md โ€” if you have a bundler, do not use it. - Hero: a third shipped format, and the size fact that the 68-decorator chip invites. - The verification date on the framework claim; "the three โœ“ rows" made unambiguous now that the section has a second table. Every figure is quoted from CHANGELOG.md or FRAMEWORKS.md rather than recalled. check:docs passes, the generated files stay in sync, and the markup parses with no unclosed or mismatched tags. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01SAcqrz3FcadkYr3xG32CjK --- docs/index.html | 131 +++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 112 insertions(+), 19 deletions(-) diff --git a/docs/index.html b/docs/index.html index 7367112..df3a0a1 100644 --- a/docs/index.html +++ b/docs/index.html @@ -365,14 +365,15 @@ footer { border-top: 1px solid var(--border); padding-block: 2.5rem; color: var(
- cereale v0.3.0 + cereale v0.4.0
0 runtime dependencies 68 decorators TC39 standard decorators - ESM + CJS + ESM + CJS + single-file Node ≥20 + 1.8 KB for one decorator
@@ -617,7 +619,7 @@ if (first instanceof Movie) {

Diagnosability

Nothing fails quietly

- The 0.3.0 release exists because of this. A mapping layer that loses your data and reports + The 0.3.0 release existed because of this. A mapping layer that loses your data and reports success is worse than one that stops, so every silent failure found in the engine was turned into an error that names the cause and the way out.

@@ -663,7 +665,8 @@ Break the cycle with @JsonIgnore() on the back-reference, or supply a

The toolchain cost, stated plainly

cereale reads the metadata that only a standard decorator transform emits, so - which compiler you use decides whether it works at all. The three โœ“ rows are executed by a + which compiler you use decides whether it works at all. The three โœ“ rows in the first table are + executed by a test on every CI run rather than asserted here โ€” each one compiles a decorated class with that tool and checks the metadata arrived. The โœ— row cannot be: oxc ships inside a native binary with no standalone transform API, so it was established by hand, and the plugin below @@ -678,7 +681,7 @@ Break the cycle with @JsonIgnore() on the back-reference, or supply a TransformerWorksSetting - tscโœ“experimentalDecorators: false, target: ES2022+ + tsc 5.2+โœ“experimentalDecorators: false, target: ES2022+ esbuildโœ“experimentalDecorators: false via tsconfigRaw, plus esbuild's own top-level target: es2022 โ€” its default esnext leaves the decorators in place swcโœ“jsc.transform.decoratorVersion: "2022-03" oxcโœ—used by Vite 8 and Vitest 4 โ€” see below @@ -701,15 +704,16 @@ Break the cycle with @JsonIgnore() on the back-reference, or supply a Angular 21โœ“Flip the scaffolded experimentalDecorators to false โ€” Angular does not need it React, Vue, Svelte…โœ“Any Vite 8 app โ€” add the plugin below - Bunโœ“Nothing + Bun 1.3โœ“Nothing Node + tscโœ“Just the flag Next.js 16~Not inline โ€” keep models in a package compiled by tsc - NestJS 11~Not inline โ€” its DI needs emitDecoratorMetadata; same precompiled route + NestJS 11.1~Not inline โ€” its DI needs emitDecoratorMetadata; same precompiled route

- Each of these was set up and run before it was written down. + Each of these was set up and run before it was written down, on 2026-08-05, against the + versions listed. FRAMEWORKS.md has the full recipe for every one, including the two that need the precompiled route.

@@ -740,7 +744,7 @@ export default defineConfig({

Getting started

-

Two settings, and one caveat

+

Two settings, one caveat, and two ways in

@@ -768,13 +772,13 @@ export default defineConfig({

not on npm yet installing it today

shell
- 
git clone https://github.com/Avalon-Vanguard/cereale
+          
git clone https://github.com/avalon-vanguard/cereale
 cd cereale
 npm install && npm run build
-npm pack                    # โ†’ cereale-0.3.0.tgz
+npm pack                    # โ†’ cereale-0.4.0.tgz
 
 # then, from your own project
-npm install ../cereale/cereale-0.3.0.tgz

+npm install ../cereale/cereale-0.4.0.tgz

npm install cereale does not resolve to @@ -784,6 +788,95 @@ npm install ../cereale/cereale-0.3.0.tgz

+ +
+

No bundler at all

+

+ cereale/min is the whole library flattened into one + minified ES module โ€” 33.9 KB, 9.6 KB gzipped โ€” for import maps, + a bare <script type="module">, Deno and Workers. +

+
+
index.html
+ 
<script type="importmap">
+  { "imports": { "cereale": "./node_modules/cereale/dist/cereale.min.js" } }
+</script>
+<script type="module">
+  import { IsString, toInstanceSync } from 'cereale';
+</script>
+
+

+ If you are using a bundler, do not use it. It is the whole library in one + file, so nothing can be dropped from it. The default entry point tree-shakes; this one + cannot, because there is nothing left to shake. +

+
+ + + + +
+
+
+

Bundle size

+

You pay for the decorators you name

+

+ Sixty-eight decorators is a lot to ship to a browser, so none of the ones you did not + import are shipped. Minified bytes, measured through all three bundlers. +

+
+ +
+ + + + + + + + + + + + + + + + + +
Minified bytes by import, across three bundlers
What you importesbuildrollupwebpack
flattenErrors394367394
one decorator1,8371,8231,818
validateSync3,7223,5543,738
toPlainSync7,7447,7697,771
toInstanceSync7,9007,9427,944
a typical DTO10,39510,40210,360
the whole library26,26625,67126,879
+
+ +
+
+

Reading and writing drop independently

+

+ Import toInstanceSync and you do not pay for the + serializer. The validator stays in both, because + validate defaults to + true โ€” a real reference, not a missed optimisation. +

+
+
+

It did not come for free

+

+ Every rule is a top-level call. rollup proves such a call side-effect-free by reading + the factory; esbuild and webpack will not. Without a + /*#__PURE__*/ on each, one decorator cost + 4,909 bytes instead of 1,837. Nothing failed โ€” the library was just + three times heavier in every bundle, and the only way to find out was to measure. +

+
+
+

rollup alone would have shown nothing

+

+ It was already producing 1,823 bytes and hid the problem. That is the argument for + measuring through more than one bundler, and it is why + a test + now pins the property rather than the prose. +

+
+
@@ -812,7 +905,7 @@ npm install ../cereale/cereale-0.3.0.tgz
@@ -860,7 +953,7 @@ npm install ../cereale/cereale-0.3.0.tgz

It is not on npm yet

-

0.3.0 lives in the repository. npm install cereale does not +

0.4.0 lives in the repository. npm install cereale does not resolve to this library โ€” build it from source until it is published.

@@ -874,9 +967,9 @@ npm install ../cereale/cereale-0.3.0.tgz

cereale โ€” MIT licensed. Built by Avalon Vanguard.

- Source ยท - Changelog ยท - Issues + Source ยท + Changelog ยท + Issues

From c13aff9f2baca034206ac1d9ee63bc11720b4305 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 7 Aug 2026 13:42:46 +0000 Subject: [PATCH 2/5] =?UTF-8?q?=F0=9F=8C=BE=20docs:=20give=20the=20page=20?= =?UTF-8?q?the=20identity=20its=20name=20implies?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The library is called cereale and the page was generic dark-developer-docs with an emoji in the brand mark. Three directions were drafted and scored by separate judges on identity, legibility and craft; this is the disciplined one with the two grafts that fixed its own weaknesses. Palette. Indigo on off-white becomes rye-brown on oat paper, warm in both themes. The accent is deliberately NOT wheat-gold: gold is both the cliche and a collision with --warn, which already owns amber, and two amber families would make "our brand" and "needs your attention" the same colour. One ornament, used three times. A 2px mark repeated every 9px: as a rule above each section head, stood on end as the stalk beside each note, and in place of the three fake macOS traffic lights on every code panel โ€” which were the most generic pixels on the page. The brand emoji and the emoji favicon both go, replaced by the same figure drawn as a five-rect SVG: an ear of grain reduced to its skeleton, which is the section rule stood upright. An emoji is a different picture on every OS, so it is the one brand element you do not control. Grafted from the two directions that lost: - Ruled links. On a palette this warm, --accent-text and --text-muted sit 1.14:1 apart, so colour alone loses a link in prose. Links now keep body colour and carry a 2px accent rule, which satisfies 1.4.1 outright. - --accent-on-code. #editor:focus drew its ring in --accent against the always-dark slab: 2.86:1, a live 1.4.11 failure on the shipped page. The new single-valued token measures 7.03:1. - --border-ui, for icon-only and outlined controls, which were on --border-strong at 1.60:1. Now 3.54:1. - --err-line/--err-text, replacing three loose literals. Two bugs found by rendering rather than by reading. The header overflowed the viewport by 63px across the whole 641-767px band, hidden rather than fixed by body{overflow-x:hidden}; the Size link added in the previous commit widened that to 109px. The nav-link breakpoint moves 640px to 860px, which is where they actually fit. Verified: 72 foreground/background pairs computed in both themes, none below 4.5:1 for text or 3:1 for non-text; no horizontal overflow at any of 20 widths from 320 to 1920; no page errors and no external requests in either theme; the playground still compiles and runs; markup parses with nothing unclosed; check:docs passes and the generated files stay in sync. Not taken: recolouring --t-decorator to the brand. It is the best identity idea in the set โ€” the decorators are what the library is โ€” but the six --t-* tokens are a shared vocabulary, page.js emits their class names, and the playground highlights code the reader pastes in. One token, easy to revisit. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01SAcqrz3FcadkYr3xG32CjK --- docs/index.html | 253 ++++++++++++++++++++++++++++-------------------- 1 file changed, 149 insertions(+), 104 deletions(-) diff --git a/docs/index.html b/docs/index.html index df3a0a1..6da59bf 100644 --- a/docs/index.html +++ b/docs/index.html @@ -7,7 +7,7 @@ - + @@ -22,35 +22,54 @@