avalon-vanguard/cereale
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
24 Commits 4 Branches 6 Tags
7aaef4d388ac8c6f3e9d7f5e5742f4cfd30d4913
Commit Graph
24 Commits
This Branch
This Branch
All Branches
Author SHA1 Message Date
Senrokai 7aaef4d388 Merge pull request #6 from avalon-vanguard/claude/library-development-i46yqm 
0.3.0 — make the silent failures loud, and rebuild the landing page
 2026-08-05 16:48:03 +02:00
Claude 478f852b42 🔒 fix!: refuse names that no longer reach their property 
A rename did not actually take effect. @JsonProperty stopped the old name
from being *mapped*, but not from being *accepted*: unlike @JsonReadOnly,
whose JSON name goes into the blocked set, the old key fell through to the
unknown-key policy, and the default `allow` copied it onto the instance
untouched.

The value therefore landed on a declared property having skipped everything
declared for it:

  @JsonProperty('home_address') @JsonType(() => Addr) @ValidateNested()
  address!: Addr;

  toInstanceSync(Order, { address: { city: 'Paris' } })
    -> address is a plain object, instanceof Addr === false
    -> validateSync() returns []          <- nothing complains

A payload aimed at the previous version of a class was accepted in part, in
silence. Three routes led to the same hole, and all three are now closed:

- the property key of a field renamed with @JsonProperty
- the raw key of a field a naming strategy renders differently
  (`firstName` under snake_case)
- the property key of a field that is both renamed and @JsonReadOnly, which
  was still settable under its own key

Refused, not swallowed. A stale name is a mismatch with whatever produced
the payload, not a deliberate refusal like @JsonReadOnly, so it is kept in
its own map rather than lumped into `blocked`: under unknownKeys: 'error'
it is still reported, and the report now names the property it was reaching
for and what that property is called now.

  "ref" is not a JSON name for Order: property "ref" is mapped to
  "order_ref". Send that name, or add @JsonAlias("ref") to keep
  accepting this one.

@JsonAlias still keeps an old name working, and a key that some *other*
property legitimately answers to is still mapped to that property — both
asserted. The resolution happens once when the name map is built, which is
memoized per class and naming strategy, so deserialization is unchanged at
~45µs for 50 nested orders.

The behaviour this replaces was pinned by tests two commits ago, pending
this decision; those tests now assert the fix, and six more cover the
naming-strategy, read-only, alias and key-collision cases.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SAcqrz3FcadkYr3xG32CjK
 2026-08-05 14:42:44 +00:00
Claude 057f008ac0 🔍 fix: correct the last three findings from the page review 
Of 26 findings raised across five auditors, 23 were refuted on a second
pass. These three survived.

**A renamed property's old key is still writable.** The README, the landing
page and two doc comments all said that once a property carries
@JsonProperty its original name "is no longer accepted on input". It is no
longer *mapped* — but it is not rejected either. Unlike @JsonReadOnly,
whose JSON name goes into the blocked set, the old key falls through to the
unknown-key policy, and the default `allow` copies it onto the instance
untouched. Reproduced against dist:

  @JsonProperty('home_address') @JsonType(() => Addr) @ValidateNested()
  address!: Addr;

  toInstanceSync(Order, { address: { city: 'Paris' } })
    -> address is a plain object, instanceof Addr === false
    -> validateSync() returns []          <- nothing complains
    -> round-trips out as home_address    <- silently accepted

Blocking the old key would fix it, but would also swallow the
`unknownKeys: 'error'` report a strict caller gets today, which is arguably
the more useful signal. That is a judgement call the library has not made,
so this commit states the behaviour accurately everywhere it was stated
wrongly and pins it with five tests covering the default, `strip`, `error`
and the @JsonAlias fix — so it cannot drift either way while the question
is open.

**@IsNotEmpty and @IsEmpty are not complements.** `[]` and `{}` pass BOTH:
isNotEmpty checks only null/undefined/'' while isEmpty also treats empty
arrays and objects as empty. Listed one line apart as "must not be empty" /
"must be empty", they invited exactly the wrong inference.

**unknownKeys is deserialization-only**, in a group whose blurb says these
apply per call or via configure().

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SAcqrz3FcadkYr3xG32CjK
 2026-08-05 10:33:45 +00:00
Claude 8c9aea3062 📐 fix: correct what the adversarial review of the page found 
Five auditors read the finished page against the source; a second pass
tried to refute each finding. What survived:

**The esbuild row was wrong, and dangerously so.** It said esbuild takes
"the same settings via tsconfigRaw" as tsc. It does not: esbuild lowers
standard decorators only when its own *top-level* `target` is below
`esnext`. A `target` inside `tsconfigRaw` sets the
`useDefineForClassFields` default and nothing else. I ran it — the
decorator survives verbatim and the module throws SyntaxError on import,
which is the exact silent passthrough the section blames on oxc. The
repo's own vite plugin and toolchain test always passed `target`
top-level, so the executed matrix never backed the advice the docs gave.
Both halves are now asserted in src/toolchain.test.ts.

**"This table is executed by a test" did not cover the oxc row** — the
only ✗, and the row the whole section is built around. It cannot be:
oxc ships as a native binary with no standalone transform API, which the
test file already said in a comment. Fixed on the page and in the README.

Reference corrections, each verified against the source:
- fromRequest has no …Sync twin; the group blurb claimed every entry did
- @IsNotIn does not narrow its field, unlike its five neighbours
- @MinDate/@MaxDate take a Date as well as a thunk
- @Validate has three parameters, not two; defineRule has four
- getConfig() and resetConfig() were missing from a group rendered under
  the heading "Everything cereale exports"

And on the page itself: the vite.config.ts snippet never imported
defineConfig, so pasting it failed; and the plugin note omitted that
.tsx is excluded by default, which would drop a reader straight back
into the 0-test hole the section exists to describe.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SAcqrz3FcadkYr3xG32CjK
 2026-08-05 10:12:29 +00:00
Claude c828f5cfe9 🌾 feat: rebuild the landing page, and stop it from rotting again 
The old page had been quietly broken for some time. It loaded
@babel/standalone from an **unpinned** CDN URL, which rolled over to Babel
8 and dropped the `proposal-class-properties` plugin the page asked for, so
Babel.transform threw before it ever reached the decorators — and the
decorator config it passed was `{ legacy: true }`, which 0.2.0 had already
made wrong. Nothing on the page said so. The copy was still selling the
0.1.0 pitch ("Spring-like"), listed about half the decorators, showed
`npm install cereale` for a package the registry returns 404 for, and
claimed "Zero overhead" against a README that publishes the real
microsecond costs.

The rebuild is one self-contained page: hand-written CSS, no Tailwind CDN,
no CodeMirror, and a vendored compiler pinned by package.json. It loads
nothing from the network. The playground runs the real bundled library
across six examples, all verified in a headless browser. The reference
covers all 68 decorators and the full API, counted from the bundle at
runtime so it cannot drift.

The hero's compiler error is not typed into the HTML. scripts/build-docs.mjs
compiles the snippets with the real tsc and writes the verbatim diagnostics
into docs/diagnostics.js, failing the build if a snippet the page calls a
compile error ever compiles — and two snippets that must compile guard
against the harness passing vacuously.

Three guards keep it honest, all wired into CI:
- check:docs fails on any remote subresource
- build:docs + git diff fails if docs/ is stale against src/
- check:types compiles a consumer against dist/ with no DOM lib, no
  @types/node and no skipLibCheck

That last one found a real packaging defect: `fromRequest` was declared as
taking the global `Request`, so cereale's own published .d.ts raised
"Cannot find name 'Request'" in any project whose lib and types did not
happen to supply it — inside a dependency, in code they may never call, and
unfixable from the outside. It now takes a structural JsonBody, which a
Request still satisfies. The library's own type tests had been hiding it by
enabling both DOM and skipLibCheck.

An adversarial review of the finished page caught four more: the lede
claimed *every* rule is type-checked (@IsDefined and @IsNotIn deliberately
are not), the guarantee section was wrong about the mechanism (a legacy
decorator does get design:type under emitDecoratorMetadata — the real claim
is about its type signature), one sample called a Movie method on a Media[]
and did not compile, and "nested objects come back as real classes" omitted
that you have to declare them. WCAG contrast was measured rather than
eyeballed: seven real failures fixed in the two themes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SAcqrz3FcadkYr3xG32CjK
 2026-08-05 10:03:16 +00:00
Claude 0938300477 🔊 feat!: make the three silent failures loud 
Every change here answers one question: where does cereale currently fail
without saying so?

**Vite 8 / Vitest 4 drop decorators silently.** Both transform with oxc,
which does not implement the standard decorator transform and does not
report that. `vitest` prints "0 test" beside a bare SyntaxError, and
`vite build` reports success while emitting a bundle that throws on first
import. Ship the plugin that fixes it as `cereale/vite`, transforming with
esbuild and falling back to tsc — cereale depends on neither. The library's
own suite now runs through it, so it is exercised by every test.

**Legacy decorators died opaquely.** With `experimentalDecorators: true`,
still the default in most existing TypeScript projects, decorators are
invoked as (prototype, "name") and cereale raised "TypeError: Cannot convert
undefined or null to object". All decorators now resolve metadata through
one checkpoint that names the tsconfig setting instead, and reject
application to a method, getter or accessor field.

**Values JSON cannot carry were emptied.** A populated Map serialized to
{}, a Uint8Array to index-keyed noise, a bigint straight through so the
caller's own JSON.stringify threw somewhere unrelated. All now raise
JsonMappingError naming the property path and both ways out. Covers what a
@JsonSerialize serializer returns, sync or async. Circular-reference and
depth errors name the path too.

Also fixed: defineRule on a subclass with no decorators of its own wrote
the rule into its base class, because the base's metadata object is
inherited through the static prototype chain and `??=` found it non-nullish.

The README's toolchain table (tsc, esbuild, swc ✅, oxc ❌) is now executed
by a test rather than asserted, and the positioning leads with
class-validator + class-transformer, the stack cereale actually replaces,
rather than Zod, which it deliberately is not.

193 -> 249 tests.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SAcqrz3FcadkYr3xG32CjK
 2026-08-05 09:11:32 +00:00
Claude d56c47d55c 🔖 chore: number the standard-decorator line 0.2.0, not 2.0.0 
Nothing has been published to npm, so 2.0.0 claimed a 1.0.0 predecessor that no
one could install. Staying on 0.x states what is true — the API may still move —
and under semver a breaking change is then a minor bump, which is precisely the
relationship between the two lines: 0.1.x keeps legacy experimentalDecorators,
0.2.x moves to TC39 standard decorators.

The break itself is unchanged and still documented; only the number and the
references to the other line moved.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SAcqrz3FcadkYr3xG32CjK
 2026-08-05 08:04:28 +00:00
Senrokai c696f10f74 Merge pull request #4 from avalon-vanguard/claude/v2-standard-decorators 
v2: strongly typed decorators on the TC39 standard

Repositions cereale as validated domain objects rather than validated data, and
makes that real by moving to TC39 standard decorators. Legacy decorators receive
(target, key) and lose the field's type; standard decorators receive
ClassFieldDecoratorContext<This, Value>, which carries it. So a rule that does
not fit its field is now a compile error:

    @IsString() age!: number   // Type 'number' is not assignable to 'string'

Checked: scalar rules against scalar fields; { each: true } against arrays in
both directions; element types; @JsonType against the field's class;
@JsonSerialize/@JsonDeserialize against the field's type; @IsIn and @IsEnum
against the field's value type. 17 tests invoke the real compiler to assert the
wrong code stays rejected.

metadata-storage.ts is deleted. Metadata lives on context.metadata, which makes
inheritance merging structural rather than reconstructed on every read, so the
subclass-shadowing defect fixed by hand in 0.1.0 cannot reoccur, and removes the
dual ESM/CJS double-singleton hazard.

Also hardens the metadata key itself: it is resolved once into a binding with
the same Symbol.for fallback the decorator transforms use, so a dropped module
can no longer leave modelOf() returning an empty model and validating every
object clean.

Unchanged: the engine, options, naming strategies, access control, error
helpers, the sync API, and the performance work. 193 tests, green on Node 20,
22 and 24.

Toolchain note: standard decorators are transformed by tsc and esbuild but not
yet by oxc. Projects on an oxc-based toolchain should stay on 1.x.
 2026-08-05 09:56:13 +02:00
Claude 305be7a16f 🔒 fix: resolve the metadata symbol into a binding, not a per-use lookup 
Review on #4 flagged that the Symbol.metadata polyfill is a module-level side
effect while package.json declares "sideEffects": false, so a bundler is
permitted to drop the module.

Checking it narrowed the concern and corrected half of it. The decorator
transforms are not exposed: esbuild's helper is

    __knownSymbol = (name, symbol) =>
      (symbol = Symbol[name]) ? symbol : Symbol.for("Symbol." + name)

which already falls back. The exposure was in this library's own read path,
which used `Symbol.metadata` directly. Had the symbol been absent,
`clazz[undefined]` would read a property literally named "undefined",
modelOf() would return an empty model, and every object would validate clean —
silent success, the worst failure mode a validation library can have.

The key is now resolved once into METADATA_KEY, with the same Symbol.for
fallback the transforms use, and all reads and writes go through it. The global
assignment stays for consumer emit that reads Symbol.metadata directly, and
package.json now lists metadata.js under sideEffects so bundlers keep it.

193 tests pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SAcqrz3FcadkYr3xG32CjK
 2026-08-05 07:20:41 +00:00
Claude 297d3bfe77 ✨ feat!: v2 — strongly typed decorators on the TC39 standard 
BREAKING CHANGE: cereale moves from legacy `experimentalDecorators` to TC39
standard decorators, which is what makes validation rules type-checked against
the fields they are attached to.

    class User {
      @IsString() name!: string;   // fine
      @IsString() age!: number;    // Type 'number' is not assignable to 'string'
    }

Legacy decorators receive (target: any, key: string) and lose the field type
entirely, so this was impossible in v1. Standard decorators receive
ClassFieldDecoratorContext<This, Value>, which carries it. Rules now checked:
scalar rules against scalar fields; { each: true } against arrays, in both
directions; @JsonType against the field's class; @JsonSerialize/@JsonDeserialize
against the field's type; @IsIn and @IsEnum against the field's value type.

17 tests invoke the real compiler to assert the wrong code stays rejected — a
guarantee nobody checks is one that quietly stops holding.

Positioning follows the capability: validated domain objects, not validated
data. The README now leads with the Zod comparison. Cereale does not infer your
type from a schema — you still write the field type and the rule — but it
guarantees the two cannot disagree, which is what class-validator never offered.

Removed
- metadata-storage.ts and its WeakMap singleton. Metadata lives on
  context.metadata now, which also removes the dual ESM/CJS double-singleton
  hazard. Inheritance merging becomes structural rather than reconstructed on
  every read, so the subclass-shadowing defect fixed by hand in 0.1.0 cannot
  reoccur by construction.
- registerDecorator, replaced by defineRule(Class, 'field', constraint).

Unchanged: the engine, options, naming strategies, access control, error
helpers, the sync API, and the performance work. 193 tests pass.

Toolchain note: standard decorators are transformed by tsc and esbuild, but not
yet by oxc. The library builds with tsc and consumers on esbuild/Vite are fine;
Vitest 4 uses oxc, so the test runner needs an esbuild transform plugin. This is
recorded in vitest.config.ts and the README, and is the reason 1.x should stay
available for oxc-based toolchains.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SAcqrz3FcadkYr3xG32CjK
 2026-08-04 20:35:26 +00:00
Senrokai 50c08aa556 Merge pull request #3 from avalon-vanguard/claude/sync-api-and-redaction 
Synchronous API and write-only redaction

Nothing on the default path is genuinely asynchronous - only a serializer,
deserializer or validator the caller supplies can be - so requiring await
everywhere taxed the common case. Rather than duplicating the traversal into a
second sync copy, which would drift from the original, the engines are now
written synchronously and anything a hook makes asynchronous is recorded and
reconciled once at the end. A *Sync call that meets a Promise raises a
JsonMappingError naming the async alternative.

Adds validateSync, validateOrRejectSync, toPlainSync, toJsonSync, toInstanceSync,
toInstanceArraySync, fromJsonSync and fromJsonArraySync. fromRequest has no
synchronous form, since reading a request body is inherently async.

Removing the per-property await also sped up the async path. Combined with the
plan caching from #2, against JSON.parse + JSON.stringify (5.8 us) as a fixed
reference:

  validate    (50 orders)   221.6 us -> 17.8 us   12.4x
  validate    (10 orders)    47.8 us ->  4.5 us   10.6x
  toPlain     (50 orders)   294.4 us -> 36.0 us    8.2x
  toInstance  (50 orders)   255.1 us -> 31.7 us    8.0x

A @JsonWriteOnly password that failed @MinLength put the rejected password into
ValidationError.value, and from there into any log recording the error - with a
plausible route to an HTTP response, since the README recommends flattening those
errors into a 400 body. Values of properties that never leave the process are now
replaced with the exported REDACTED placeholder; property name and failure
message are unchanged.

176 tests, up from 150, adding coverage of async hooks through the async API that
the suite had never exercised. That caught a regression this change introduced,
where an async serializer's deferred write changed property order in the output.

No breaking changes. Green on Node 20, 22 and 24.
v0.1.0 		2026-08-04 19:54:15 +02:00
Claude 6d30182ca8 ✨ feat: add a synchronous API and redact write-only values from errors 
Synchronous API
---------------
Nothing on the default path is genuinely asynchronous - only a serializer,
deserializer or validator the caller supplies can be - so requiring `await`
everywhere taxed the common case.

Rather than duplicating the traversal into a second sync copy (the traversal is
exactly where the eight defects fixed in 0.1.0 lived, and two copies would drift),
the engines are now written synchronously and anything a hook makes asynchronous
is recorded and reconciled once at the end. A `*Sync` call that encounters a
Promise raises a JsonMappingError naming the async alternative instead of
returning a half-built object.

Adds validateSync, validateOrRejectSync, toPlainSync, toJsonSync, toInstanceSync,
toInstanceArraySync, fromJsonSync, fromJsonArraySync. fromRequest has no
synchronous form, since reading a request body is inherently async.

Removing the per-property await also sped up the async path substantially. With
the plan caching from the previous release, against JSON.parse + JSON.stringify
(5.8 us) as a fixed reference:

  validate    (50 orders)   221.6 us -> 17.8 us   12.4x
  validate    (10 orders)    47.8 us ->  4.5 us   10.6x
  toPlain     (50 orders)   294.4 us -> 36.0 us    8.2x
  toInstance  (50 orders)   255.1 us -> 31.7 us    8.0x
  toInstance  (single)       19.8 us ->  5.2 us    3.8x

Write-only redaction
--------------------
A @JsonWriteOnly password that failed @MinLength put the rejected password into
ValidationError.value, and from there into any log that recorded the error.
Values of properties that never leave the process - @JsonWriteOnly and
@JsonIgnore - are now replaced with the exported REDACTED placeholder. The
property name and failure message are unchanged, so the error stays actionable.

Tests
-----
176 tests, up from 150. The new suite covers the sync family, its refusal of
async hooks (including that refusing does not leave an unhandled rejection), and
async hooks through the async API - serializers, deserializers, validators, and
async validators under each: true, which the suite had never exercised.

That last group caught a regression this change introduced: with an async
serializer the deferred write appended its key after the synchronous ones,
changing property order in the output. The slot is now claimed before deferring.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SAcqrz3FcadkYr3xG32CjK
 2026-08-04 11:56:05 +00:00
Senrokai 203e5ec27b Merge pull request #2 from avalon-vanguard/claude/consolidation-perf-reliability 
Memoize per-class plans (3-4.5x faster), add depth guard and per-index each reporting

Profiling showed roughly half of all validation time re-deriving answers that
cannot change - collectConstraints 22%, getOwnMetadata 12%, getMetadataChain 9%,
getProperties 4%, getMetadata 3%, plus 8% GC - while the constraint predicates
themselves accounted for under 1%.

Decorator metadata is fixed once classes are declared, so the validation,
serialization and deserialization plans are now memoized per prototype, along
with serializer/deserializer instances that were previously constructed for every
property of every object. A version counter on MetadataStorage invalidates the
caches when metadata is written, so registerDecorator after first use still takes
effect.

  validate    (50 orders)   221.6 us -> 49.6 us   4.5x
  validate    (10 orders)    47.8 us -> 12.9 us   3.7x
  toInstance  (50 orders)   255.1 us -> 74.0 us   3.4x
  toPlain     (50 orders)   294.4 us -> 95.3 us   3.1x

Also bounds recursion with a maxDepth option (default 64) across all three
engines, closing a stack-exhaustion vector on hostile payloads, and makes
each: true failures name the element that failed.

136 -> 150 tests, no breaking changes, green on Node 20, 22 and 24.
 2026-08-04 13:41:49 +02:00
Claude 6e458fdd43 ⚡ perf: memoize per-class plans; add depth guard and per-index each reporting 
Profiling the validator showed roughly half of all validation time re-deriving
answers that cannot change — collectConstraints 22%, getOwnMetadata 12%,
getMetadataChain 9%, getProperties 4%, getMetadata 3%, plus 8% GC from the
allocation churn. The constraint predicates themselves were under 1%.

Decorator metadata is fixed once classes are declared, so the derived structures
are now memoized per prototype: the validation plan, the serialization plan, the
deserialization plan, and serializer/deserializer instances, which were being
constructed fresh for every property of every object. MetadataStorage carries a
version counter that invalidates the caches when metadata is written, so
registerDecorator after first use still works — covered by a test.

Measured against JSON.parse + JSON.stringify as a fixed reference:

  validate    (50 orders)   221.6 us -> 49.6 us   4.5x
  validate    (10 orders)    47.8 us -> 12.9 us   3.7x
  toInstance  (50 orders)   255.1 us -> 74.0 us   3.4x
  toInstance  (10 orders)    64.6 us -> 19.0 us   3.4x
  toPlain     (50 orders)   294.4 us -> 95.3 us   3.1x

Reliability, in the same pass:

- maxDepth option (default 64) on every mapping function, on validate(), and on
  configure(). All three engines recurse, so a payload nested thousands of levels
  deep could exhaust the call stack. Cycles were already handled; legitimate deep
  nesting was not bounded.
- each: true failures now name the element that failed ("failed at index 3"). A
  bad entry in a 200-item array previously produced a message that could not
  locate it. A message function now receives the failing element as args.value
  rather than the whole array; caller-supplied strings stay verbatim.

150 tests (up from 136), all green on the existing suite unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SAcqrz3FcadkYr3xG32CjK
 2026-08-04 11:36:53 +00:00
Senrokai 26cd6b5707 Merge pull request #1 from avalon-vanguard/claude/library-development-i46yqm 
Repair the test suite, fix eight engine defects, and add field-name mapping (0.1.0)

The test suite had never executed: vitest 4 transpiles with oxc, which does not
read experimentalDecorators from a tsconfig excluding the files it transforms,
so every decorator suite failed to parse and was reported as "0 test". Fixing
that revived 40 tests and exposed eight engine defects, each now pinned by a
regression test: inheritance silently discarding base-class constraints, a
circular reference exhausting the heap, stateful /g regexes in @Matches, an
unmatched polymorphic discriminator dropping data, serializers crashing on unset
optional properties, null-prototype objects, __proto__ from untrusted JSON, and
mangled or overwritten error messages.

Adds field-name mapping (@JsonProperty, @JsonAlias, naming strategies), access
control (@JsonIgnore, @JsonReadOnly, @JsonWriteOnly), transform options,
error-flattening helpers, and 30 validation decorators.

40 tests that never ran -> 136 that do, at 97% statement and 100% function
coverage, green on Node 20, 22 and 24.
 2026-08-04 13:20:48 +02:00
Claude 2acdf3b360 🔧 ci: run the pipeline on develop as well as main 
The PR now targets develop, which was branched from main. The workflow only
triggered on push and pull_request against main, so nothing would have run on
develop or on any future PR into it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SAcqrz3FcadkYr3xG32CjK
 2026-08-04 11:14:58 +00:00
Claude 83ad2a289d 📝 docs: bring README, demo and playground in line with the code; release 0.1.0 
The README described a library that did not exist in places. It showed
@ValidateNested({ each: true }), which did not compile; told users to enable
emitDecoratorMetadata, which the library never reads; and documented none of the
mapping API. Its Quick Start now runs verbatim — verified by compiling and
executing it against the local source.

- README: document field-name mapping, access control, options, error helpers
  and the 30 new validators; drop the emitDecoratorMetadata instruction; add a
  Notes and Limitations section covering circular references, validate() on
  plain objects, and the fact that @JsonProperty stops the original name from
  being accepted unless you add @JsonAlias
- CHANGELOG.md: new, covering 0.1.0
- example.ts: rewritten as a tour of the current API — read-only ids, write-only
  secrets, renamed fields, conditional validation, flattened errors, and a
  base-class rule reaching a subclass
- docs: the playground hand-listed its symbol table in three parallel places and
  exposed IsEmail, which is not an export. It now derives scope from the bundle,
  so new decorators work there as soon as they ship. Bundle regenerated
- version 0.1.0

136 tests, 97% statement and 100% function coverage.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SAcqrz3FcadkYr3xG32CjK
 2026-08-03 23:53:09 +00:00
Claude 44c8f28f4b ✨ feat: add 30 validation decorators, @ValidateIf and @Allow 
Rounds out the validator set with the rules an application actually reaches for,
all following the existing decorator style and honouring each/message options.

- equality and presence: @Equals, @NotEquals, @IsEmpty, @IsEnum, @IsInstance
- strings: @Length, @IsAlpha, @IsAlphanumeric, @IsNumberString, @IsLowercase,
  @IsUppercase, @Contains, @NotContains, @StartsWith, @EndsWith
- formats: @IsUUID, @IsJSON, @IsDateString, @IsSemVer, @IsHexColor, @IsIP
- numbers: @IsDivisibleBy, @IsPort, @IsLatitude, @IsLongitude, @IsBigInt
- dates: @MinDate, @MaxDate
- arrays: @ArrayUnique, @ArrayContains, @ArrayNotContains

@ValidateIf(o => ...) makes a property's rules conditional on the rest of the
object, and @Allow() declares a property that needs no rules of its own so it
survives unknownKeys: 'strip'.

Two details worth noting. @IsEnum filters the reverse mapping a numeric enum
compiles to, so 'Low' is not accepted as a value of enum { Low, High }.
@MinDate/@MaxDate accept a thunk, so "not in the past" is evaluated per
validation instead of being frozen when the class was declared.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SAcqrz3FcadkYr3xG32CjK
 2026-08-03 23:48:40 +00:00
Claude 666762a146 ✨ feat: add field-name mapping, access control and transform options 
A library whose headline feature is "JSON mapping" could not map a name: there
was no way to read {"first_name": ...} into firstName, no way to keep a password
out of the response, and no way to parse a payload without validating it.

Name mapping
- @JsonProperty(name) renames a property in both directions
- @JsonAlias(...names) accepts extra names on input only, so a field can be
  renamed without breaking older clients
- naming strategies (snake_case, kebab-case, SCREAMING_SNAKE_CASE, PascalCase,
  camelCase, or your own function) for properties with no explicit name.
  Acronyms split where a reader expects: parseHTTPResponse -> parse_http_response

Access control
- @JsonIgnore()    excluded both ways
- @JsonWriteOnly() accepted from input, never echoed back (passwords)
- @JsonReadOnly()  serialized, never settable by a client (server-owned ids)

Blocked names are dropped explicitly rather than falling through to the unknown
key path, which would otherwise have copied a rejected id straight back on under
the default policy.

Transform options, per call or globally via configure()
- validate: false to map without validating, for lenient parsing
- unknownKeys: 'allow' | 'strip' | 'error'
- namingStrategy

Error ergonomics — the nested ValidationError tree was hard to turn into an HTTP
400 body. flattenErrors() yields {"items[0].qty": ["qty must be at least 1"]},
plus formatErrors() and collectErrorMessages(). Adds validateOrReject().

All defaults preserve existing behaviour; the 68 prior tests pass unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SAcqrz3FcadkYr3xG32CjK
 2026-08-03 23:46:18 +00:00
Claude 6d04b43964 🐛 fix: repair eight correctness defects in the mapping and validation engines 
Each fix is pinned by a regression test in src/regressions.test.ts describing the
old behaviour.

- Inheritance dropped base-class rules. A subclass re-decorating an inherited
  property registered its constraints against its own prototype, and validate()
  read only the nearest set, so everything the base declared was silently lost.
  Constraints are now merged down the whole prototype chain, base first, with
  genuinely identical rules collapsed so restating @IsString() on an override
  does not double-report. The library's own example.ts was affected: Media's
  @IsString() title had never been enforced for Book.
- Circular references exhausted the heap. serialize() recursed forever, taking
  8 GB and the process with it; it now tracks ancestors and raises a
  JsonMappingError naming the cause. Diamonds still serialize. validate() skips
  back-edges instead of recursing.
- @Matches with a g or y flag was stateful: RegExp.test advances lastIndex, so
  validating the same value twice gave different answers. Those flags are
  stripped.
- An unmatched @JsonPolymorphic discriminator silently dropped the value — the
  single-object branch fell through without assigning. The raw value is now
  preserved, with { onUnknown: 'error' } and { fallback } to choose otherwise.
- Custom @JsonSerialize serializers ran on null/undefined, crashing on any unset
  optional property. They now only see real values.
- serialize() read obj.constructor.prototype, which throws for null-prototype
  objects; both engines now agree on Object.getPrototypeOf.
- __proto__, constructor and prototype arriving in untrusted JSON were copied
  onto the instance, detaching it from its own class. They are dropped.
- The "each element in ..." prefix was glued onto caller-supplied messages, and
  two rules sharing a name overwrote each other so only one failure surfaced.

Also adds toInstanceArray/fromJsonArray, since toInstance and fromJson accept
arrays at runtime but type the result as T, and reports a non-JSON request body
in fromRequest as a JsonMappingError rather than a raw SyntaxError.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SAcqrz3FcadkYr3xG32CjK
 2026-08-03 23:41:10 +00:00
Claude 66e19f690f 🔧 fix: repair test, build and CI infrastructure 
The vitest suite silently ran zero tests: vitest 4 transpiles with oxc, which
does not pick up `experimentalDecorators` from a tsconfig that excludes the
files being transformed, so every decorator-using suite failed to parse and was
reported as "0 test". A vitest.config.ts enabling legacy decorators brings all
40 existing tests back to life.

- Add vitest.config.ts (oxc legacy decorators + v8 coverage config)
- Type-check test files: move the test/demo exclusions from the base tsconfig
  onto the two build configs, and fix the strict-mode errors this surfaced
- Stop shipping src/example.ts in dist (it invokes runExample() at import time,
  a side effect in a package declaring "sideEffects": false)
- CI: run lint, tests with coverage, build and entry-point smoke checks; drop
  EOL Node 18, add Node 24; commit package-lock.json so `npm ci` works
- Add `verify`, `test:watch` and `build:docs` scripts, and an engines field;
  `build:docs` regenerates the previously hand-maintained docs/cereale.js

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SAcqrz3FcadkYr3xG32CjK
 2026-08-03 23:14:16 +00:00
Enzo Marioni fa75147e4e ✨ feat: implement core Cereale library for JSON mapping and validation 
- 🎨 add Spring-like decorators (@JsonSerialize, @JsonDeserialize, etc.)
- ⚙️ implement JsonMapper and metadata storage for transformations
- 🧪 add comprehensive test suite using Vitest
- 📝 add README, CONTRIBUTING, and API documentation
- 👷 setup GitHub Actions CI workflow
- 🔧 configure TypeScript and project settings
v0.0.1 		2026-04-18 19:33:19 +02:00
Enzo Marioni 7fe7e8c7c3 ✨ feat: implement core Optimus library for JSON mapping and validation 
- 🎨 add Spring-like decorators (@JsonSerialize, @JsonDeserialize, etc.)
- ⚙️ implement JsonMapper and metadata storage for transformations
- 🧪 add comprehensive test suite using Vitest
- 📝 add README, CONTRIBUTING, and API documentation
- 👷 setup GitHub Actions CI workflow
- 🔧 configure TypeScript and project settings
 2026-04-11 16:58:12 +02:00
Senrokai 45e790a7d0 Initial commit 2026-04-11 16:20:19 +02:00