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.
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
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.
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
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.
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
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
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
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
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
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
Senrokai