Release 0.2.0 to main
Brings main up to date. It had been sitting at the initial commit, so anything
installed from main was the pre-repair code: a test suite that never executed
and every defect fixed in #1 still present.
The project stays on 0.x because nothing has been published to npm. Under semver
that says what is true - the API may still move - where a 1.0.0/2.0.0 split
would have claimed a stability and a history that do not exist. A breaking change
is therefore a minor bump, which is exactly the relationship between the lines:
develop / main 0.2.0 TC39 standard decorators, rules type-checked
0.1.x 0.1.0 legacy experimentalDecorators, for oxc toolchains
What lands, across four merged PRs:
- The test suite had never run. Vitest 4 transpiles with oxc, which does not read
experimentalDecorators from a tsconfig excluding the files it transforms, so
every suite failed to parse and was reported as "0 test". Reviving it exposed
eight engine defects, each now pinned by a regression test - among them
inheritance silently discarding base-class rules, and a circular reference
exhausting an 8 GB heap.
- Field-name mapping, access control, transform options, error flattening, and
30 validation decorators.
- Performance: profiling showed roughly half of validation time re-deriving
answers that cannot change while the predicates themselves were under 1%.
Per-class plans are memoized and recursion is bounded.
- A synchronous API, built by making the engines sync internally rather than
duplicating the traversal, which sped up the async path as well.
- Standard decorators, so a rule that does not fit its field is a compile error.
Tests actually executing 0 -> 193
validate (50 orders) 221.6us -> 17.8us
toInstance (50 orders) 255.1us -> 31.7us
Clean fast-forward, no conflicts. Nothing is tagged or published.
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.
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.
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.
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.
Senrokai