Claude
6e458fdd43
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
162 lines
8.3 KiB
Markdown
162 lines
8.3 KiB
Markdown
# Changelog
|
|
|
|
All notable changes to this project are documented in this file.
|
|
|
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
|
|
## [Unreleased]
|
|
|
|
### Performance
|
|
|
|
Profiling the validator showed roughly **half of all validation time** was spent re-deriving
|
|
answers that cannot change: `collectConstraints` (22%), `getOwnMetadata` (12%),
|
|
`getMetadataChain` (9%), `getProperties` (4%) and `getMetadata` (3%), plus 8% garbage
|
|
collection from the allocation churn. The constraint predicates themselves accounted for
|
|
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 (previously constructed fresh for every property
|
|
of every object). `MetadataStorage` carries a version counter that invalidates every cache
|
|
if metadata is registered late, so `registerDecorator` after first use still works.
|
|
|
|
Measured on a customer record with nested address and orders, against `JSON.parse` +
|
|
`JSON.stringify` as a fixed reference point:
|
|
|
|
| Operation | Before | After | Speedup |
|
|
| --- | --- | --- | --- |
|
|
| `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 |
|
|
| `toInstance` (single) | 19.8 us | 8.4 us | 2.4x |
|
|
|
|
### Added
|
|
|
|
- `maxDepth` option (default 64) on every mapping function and on `configure()`. All three
|
|
engines recurse, so a hostile payload nested thousands of levels deep could exhaust the
|
|
call stack; it now raises a `JsonMappingError`. Cycles were already handled, but legitimate
|
|
deep nesting was not bounded.
|
|
- `validate(obj, options?)` accepts options, so `maxDepth` applies to standalone validation.
|
|
|
|
### Changed
|
|
|
|
- `each: true` failures now report which element 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 string messages are still reported verbatim.
|
|
|
|
## [0.1.0] - 2026-08-03
|
|
|
|
The first release with a working test suite. Everything below the "Fixed" heading was
|
|
found by writing tests against the previous release; the suite has grown from 40 tests
|
|
that never executed to 136 that do.
|
|
|
|
### Added
|
|
|
|
**Field-name mapping.** A library whose headline feature is "JSON mapping" could not map
|
|
a name. It can now.
|
|
|
|
- `@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 — applied to properties with no explicit name.
|
|
Acronyms split where a reader expects: `parseHTTPResponse` → `parse_http_response`.
|
|
|
|
**Access control.**
|
|
|
|
- `@JsonIgnore()` — excluded in both directions.
|
|
- `@JsonWriteOnly()` — accepted from input, never echoed back (passwords).
|
|
- `@JsonReadOnly()` — serialized, never settable by a client (server-owned ids).
|
|
|
|
**Transform options**, per call or globally via `configure()`.
|
|
|
|
- `validate: false` maps without validating, for lenient parsing.
|
|
- `unknownKeys: 'allow' | 'strip' | 'error'` decides what happens to undeclared keys.
|
|
- `namingStrategy` selects the JSON naming convention.
|
|
|
|
**Error ergonomics.** Turning the nested `ValidationError` tree into an HTTP 400 body used
|
|
to be the caller's problem.
|
|
|
|
- `flattenErrors(errors)` → `{ "items[0].qty": ["qty must be at least 1"] }`
|
|
- `formatErrors(errors)` → one human-readable line per failure
|
|
- `collectErrorMessages(errors)` → just the messages
|
|
- `validateOrReject(obj)` throws instead of returning an array you might forget to check
|
|
|
|
**30 validation decorators.** `@Equals`, `@NotEquals`, `@IsEmpty`, `@IsEnum`, `@IsInstance`,
|
|
`@Length`, `@IsAlpha`, `@IsAlphanumeric`, `@IsNumberString`, `@IsLowercase`, `@IsUppercase`,
|
|
`@Contains`, `@NotContains`, `@StartsWith`, `@EndsWith`, `@IsUUID`, `@IsJSON`,
|
|
`@IsDateString`, `@IsSemVer`, `@IsHexColor`, `@IsIP`, `@IsDivisibleBy`, `@IsPort`,
|
|
`@IsLatitude`, `@IsLongitude`, `@IsBigInt`, `@MinDate`, `@MaxDate`, `@ArrayUnique`,
|
|
`@ArrayContains`, `@ArrayNotContains`.
|
|
|
|
**Conditional validation.** `@ValidateIf(o => ...)` makes a property's rules depend on the
|
|
rest of the object; `@Allow()` declares a property that needs no rules of its own.
|
|
|
|
**Correctly typed array entry points.** `toInstanceArray()` and `fromJsonArray()`.
|
|
`toInstance`/`fromJson` accept arrays at runtime but type the result as `T`, so callers had
|
|
to cast to reach the elements.
|
|
|
|
**`@JsonPolymorphic` options.** `{ onUnknown: 'error' }` and `{ fallback: SomeClass }`.
|
|
|
|
**`JsonMappingError`** — raised when a value cannot be mapped at all, as distinct from
|
|
mapping fine and failing validation.
|
|
|
|
### Fixed
|
|
|
|
- **Inheritance silently discarded base-class rules.** A subclass re-decorating an inherited
|
|
property registered its constraints against its own prototype, and the engine read only the
|
|
nearest set. Constraints now merge down the whole prototype chain, base first. The
|
|
library's own example was affected: `Media`'s `@IsString() title` had never been enforced
|
|
for `Book`.
|
|
- **A circular reference exhausted the heap.** `serialize()` recursed forever, taking 8 GB
|
|
and the process with it. It now raises a `JsonMappingError` naming the cause. Diamonds
|
|
still serialize; `validate()` skips back-edges.
|
|
- **`@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 property came back `undefined`.
|
|
The raw value is now preserved.
|
|
- **`@JsonSerialize` serializers ran on `null`/`undefined`**, crashing on any unset optional
|
|
property. They now only see real values.
|
|
- **`serialize()` crashed on null-prototype objects.** It read `obj.constructor.prototype`;
|
|
both engines now agree on `Object.getPrototypeOf`.
|
|
- **`__proto__`, `constructor` and `prototype` in untrusted JSON** were copied onto the
|
|
instance, detaching it from its own class. They are dropped.
|
|
- **Caller-supplied messages were mangled** by the `each element in ...` prefix, producing
|
|
sentences like "each element in tags must all be strings".
|
|
- **Two rules sharing a name overwrote each other**, so only one failure was ever reported.
|
|
- **`fromRequest` leaked a raw `SyntaxError`** for a non-JSON body; it now reports a
|
|
`JsonMappingError`.
|
|
- **`@ValidateNested({ each: true })`** was documented in the README but did not compile —
|
|
`ValidateNested()` accepted no arguments. It now does, and asserts the value is an array.
|
|
|
|
### Changed
|
|
|
|
- `toPlain`, `toJson`, `toInstance`, `fromJson`, `fromJsonArray`, `toInstanceArray` and
|
|
`fromRequest` accept an optional trailing options argument. All defaults preserve the
|
|
previous behaviour.
|
|
- `src/example.ts` is no longer published in `dist`. It called `runExample()` at import
|
|
time — an import side effect in a package declaring `"sideEffects": false`.
|
|
- Minimum supported Node is 20.
|
|
|
|
### Infrastructure
|
|
|
|
- **The test suite had never run.** Vitest 4 transpiles with oxc, which does not read
|
|
`experimentalDecorators` from a tsconfig that excludes the files it is transforming, so
|
|
every decorator-using suite failed to parse and was reported as "0 test" rather than as an
|
|
error. A `vitest.config.ts` enabling legacy decorators brought all 40 existing tests back
|
|
to life.
|
|
- Test files are now type-checked, which surfaced 17 strict-mode errors.
|
|
- CI runs lint, coverage tests, build and ESM/CJS entry-point smoke checks across Node
|
|
20/22/24, and `npm ci` works because `package-lock.json` is committed.
|
|
- `npm run build:docs` regenerates the previously hand-maintained `docs/cereale.js`.
|
|
|
|
## [0.0.1]
|
|
|
|
Initial release: mapping and validation decorators, polymorphic types, custom
|
|
serializers/deserializers, and the `toJson` / `fromJson` / `toPlain` / `toInstance` API.
|