avalon-vanguard/cereale
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #4 from avalon-vanguard/claude/v2-standard-decorators

Browse Source 
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.
This commit is contained in:
Senrokai
2026-08-05 09:56:13 +02:00
committed by GitHub
parent 50c08aa556 305be7a16f
commit c696f10f74
20 changed files with 1281 additions and 1430 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+65 -1
View File
@@ -5,7 +5,71 @@ 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]
## [2.0.0] - 2026-08-04
**Breaking.** Cereale moves to TC39 standard decorators, which is what makes validation rules
type-checked against the fields they are attached to.
### The headline
A rule that does not fit its field is now a compile error:
```ts
class User {
@IsString() name!: string; // fine
@IsString() age!: number; // Type 'number' is not assignable to type 'string'
}
```
Legacy decorators receive `(target: any, key: string)` and lose the field's type entirely, so
this was impossible in v1. Standard decorators receive `ClassFieldDecoratorContext<This, Value>`,
which carries it. Checked rules include:
- scalar rules against scalar fields (`@Min` on a string is rejected)
- `{ each: true }` against arrays (`@IsString({ each: true })` demands a `string[]`, and a bare
`@IsString()` on a `string[]` is rejected)
- `@JsonType(() => Address)` against the field's class
- `@JsonSerialize` / `@JsonDeserialize` against the field's type
- `@IsIn([...])` and `@IsEnum(E)` against the field's value type
17 tests invoke the real compiler to assert these stay rejected.
### Migration
- Remove `"experimentalDecorators": true`; add `"ESNext.Decorators"` to `lib`.
- `registerDecorator({ target, propertyName, validator })` is replaced by
`defineRule(Class, 'field', constraint)`.
- Decorators cannot be applied to `abstract` fields. Declare the field concretely in the base.
- Field types may need tightening where a rule narrows them: `@IsIn(['a','b']) x!: string`
becomes `x!: 'a' | 'b'`.
- `@JsonPolymorphic` takes its base type explicitly to check subtypes:
`@JsonPolymorphic<Media>('type', [...])`.
- `@ValidateIf` takes the class as a type argument: `@ValidateIf<Movie>(m => ...)`.
Everything else — the engine, options, naming strategies, access control, error helpers, the
sync API — is unchanged.
### Removed
- `metadata-storage.ts` and its WeakMap singleton. Metadata now lives on `context.metadata`,
the language's own mechanism, which also removes the dual ESM/CJS double-singleton hazard.
- `registerDecorator`, replaced by `defineRule`.
### Fixed
- Inheritance merging is now structural rather than reconstructed: `context.metadata` inherits
through the prototype chain, so the subclass-shadowing defect fixed by hand in 0.1.0 cannot
reoccur by construction. Identical inherited rules are still collapsed so re-stating a rule
on an override does not double-report.
### Toolchain
Standard decorators are transformed by `tsc` and by esbuild; **oxc does not implement them
yet**. The library builds with `tsc` and consumers bundling with esbuild or Vite are fine, but
the test runner (Vitest 4, which uses oxc) needs an esbuild transform plugin — see
`vitest.config.ts`. Projects on an oxc-based toolchain should stay on 1.x for now.
## [Unreleased] (released as 1.0.0)
### Added
README.md
+102 -71
View File
@@ -1,17 +1,58 @@
# Cereale
Cereale is a lightweight TypeScript library that provides Spring-like decorators for JSON mapping and validation. Built with ZERO external dependencies, it simplifies the process of converting between plain JSON and class instances with full validation support.
**Validated domain objects, not validated data.**
Cereale maps JSON onto your own classes and gives you back real instances — with your methods,
your inheritance, your `instanceof` checks — and type-checks the validation rules against the
fields they are attached to. Zero runtime dependencies.
```typescript
class User {
@JsonProperty('display_name')
@IsString() @MinLength(2)
displayName!: string;
@IsInt() @Min(0)
age!: number;
@IsString()
age2!: number; // ← compile error: Type 'number' is not assignable to type 'string'
greet() { return `Hi ${this.displayName}`; }
}
const user = fromJsonSync(User, body); // a real User
user.greet(); // your methods are still there
```
## Why not Zod?
Zod is excellent, and if a plain validated object is what you want, use it. The difference is
what you get back:
| | Zod | Cereale |
| --- | --- | --- |
| Result of parsing | an anonymous object matching a schema | an instance of **your class** |
| Methods, getters, inheritance | none — data only | preserved |
| Where the type comes from | inferred from the schema | your class declaration |
| Rules checked against the type | not applicable — schema *is* the type | **yes, at compile time** |
| Bidirectional mapping (renaming both ways) | not the focus | first-class |
Cereale does not infer your type from a schema, so you still write the field type and the rule.
What it guarantees is that **the two cannot disagree** — `@IsInt() name!: string` does not
compile. That is the guarantee class-validator has never offered.
Reach for Cereale when your domain model is already a class — a NestJS provider, a TypeORM
entity, anything with behaviour attached. Reach for Zod when you just want the data.
## Features
- **Spring-like Decorators:** Familiar `@JsonProperty`, `@JsonSerialize`, `@JsonDeserialize`, `@JsonType`, and `@JsonPolymorphic`.
- **Field-name Mapping:** Map `first_name` to `firstName` per property or with a naming strategy.
- **Access Control:** Keep passwords out of responses and server-owned ids out of requests.
- **Custom Serializers/Deserializers:** Easily handle complex types like Dates, BigInts, or custom objects.
- **Polymorphism Support:** Native handling of polymorphic types via discriminators.
- **Integrated Validation:** 50+ validation decorators, applied during mapping or on demand.
- **Type Safety:** Fully written in TypeScript for excellent developer experience.
- **Zero Dependencies:** Extremely lightweight and fast.
- **Strongly typed decorators:** a rule that does not fit its field is a compile error.
- **Real instances:** nested objects, polymorphic subtypes and arrays all come back as classes.
- **Field-name mapping:** `@JsonProperty`, `@JsonAlias` and naming strategies, both directions.
- **Access control:** keep passwords out of responses and server-owned ids out of requests.
- **Sync and async:** every entry point has a synchronous twin.
- **Zero dependencies**, ESM + CJS, Node 20+.
## Installation
@@ -19,109 +60,92 @@ Cereale is a lightweight TypeScript library that provides Spring-like decorators
npm install cereale
```
Enable `experimentalDecorators` in your `tsconfig.json`:
Cereale v2 uses **TC39 standard decorators**, so no `experimentalDecorators` flag:
```json
{
"compilerOptions": {
"experimentalDecorators": true,
"target": "ES2022"
"target": "ES2022",
"lib": ["ESNext", "ESNext.Decorators"]
}
}
```
Cereale stores its own metadata, so `reflect-metadata` is not required and
`emitDecoratorMetadata` is not read. Requires Node 20 or later.
Requires TypeScript 5.2+ and Node 20+. `reflect-metadata` is not needed and
`emitDecoratorMetadata` is not read.
> **Toolchain note.** Standard decorators are transformed by `tsc` and by esbuild (so Vite
> works). They are **not** yet transformed by oxc; if your toolchain uses it, decorator syntax
> will fail to parse. v1.x, which uses legacy decorators, remains available for those setups.
## Quick Start
### 1. Define your Models
### 1. Define your model
```typescript
import {
IsString,
IsDate,
ValidateNested,
JsonSerialize,
JsonDeserialize,
JsonPolymorphic,
JsonSerializer,
JsonDeserializer
IsString, IsDate, IsInt, Min, ValidateNested, JsonType,
JsonProperty, JsonWriteOnly, JsonPolymorphic,
} from 'cereale';
// Custom Date Serializer
class DateSerializer implements JsonSerializer<Date, string> {
serialize(value: Date): string {
return value.toISOString().split('T')[0]!;
}
}
class Address {
@IsString() street!: string;
@IsString() city!: string;
class DateDeserializer implements JsonDeserializer<string, Date> {
deserialize(value: string): Date {
return new Date(value);
}
format() { return `${this.street}, ${this.city}`; }
}
abstract class Media {
@IsString()
abstract type: string;
@IsString()
title: string;
// Standard decorators cannot decorate an `abstract` member, so declare it concretely.
@IsString() type: string = '';
@IsString() title: string = '';
}
class Book extends Media {
type = 'book';
@IsString() override type = 'book';
@IsString() author!: string;
@IsString()
author: string;
@JsonSerialize(DateSerializer)
@JsonDeserialize(DateDeserializer)
@JsonProperty('published_at')
@IsDate()
publishedAt: Date;
publishedAt!: Date;
}
class Library {
@IsString()
name: string;
@IsString() name!: string;
@ValidateNested() @JsonType(() => Address)
address!: Address; // the class must match the field
@ValidateNested({ each: true })
@JsonPolymorphic('type', [
{ value: Book, name: 'book' }
])
items: Media[];
@JsonPolymorphic<Media>('type', [{ value: Book, name: 'book' }])
items!: Media[];
}
```
Constraints accumulate down an inheritance chain: `Book` is checked against `Media`'s
`@IsString() title` as well as its own rules.
Constraints accumulate down an inheritance chain: `Book` is checked against `Media`'s rules as
well as its own, and re-stating a rule on an override does not report it twice.
### 2. Map JSON with Validation
### 2. Map JSON, synchronously or not
```typescript
import { fromJson, toJson, JsonValidationError, flattenErrors } from 'cereale';
import { fromJsonSync, toJsonSync, JsonValidationError, flattenErrors } from 'cereale';
async function main() {
const json = '{"name": "Central Library", "items": [{"type": "book", "title": "The Great Gatsby", "author": "F. Scott Fitzgerald", "publishedAt": "1925-04-10"}]}';
try {
// Deserialize JSON to Class Instance
const library = await fromJson(Library, json);
console.log(library.name); // "Central Library"
console.log(library.items[0] instanceof Book); // true
// Serialize Class Instance back to JSON
console.log(await toJson(library));
} catch (error) {
if (error instanceof JsonValidationError) {
console.error(flattenErrors(error.errors));
// { "items[0].title": ["title must be a string"] }
}
try {
const library = fromJsonSync(Library, json);
library.address.format(); // your method, on a real Address
library.items[0] instanceof Book; // true
console.log(toJsonSync(library));
} catch (error) {
if (error instanceof JsonValidationError) {
console.error(flattenErrors(error.errors));
// { "items[0].title": ["title must be a string"] }
}
}
```
Every function has an async form too (`fromJson`, `toJson`, …) for when a serializer,
deserializer or validator of yours returns a Promise.
### 3. Modern Web Frameworks (Request Integration)
Cereale is compatible with Fetch-based frameworks like Hono, Next.js, and Remix. Use the `fromRequest` async helper.
@@ -401,6 +425,13 @@ dominant cost.
## Notes and Limitations
- **Rules are checked, types are not inferred.** You write both the field type and the rule;
cereale guarantees they agree. If you want the type derived from a schema, that is Zod's
model, not this one.
- **`abstract` fields cannot be decorated.** Standard decorators do not apply to abstract
members. Declare the field concretely in the base class instead.
- **oxc does not transform standard decorators yet.** `tsc` and esbuild do.
- **Circular references** are rejected during serialization with a `JsonMappingError`. Break
the cycle with `@JsonIgnore()` on the back-reference.
- **`validate()` on a plain object** returns no errors: rules live on the class, so validate
docs/cereale.js
+2 -2
View File
File diff suppressed because one or more lines are too long
package.json
+11 -6
View File
@@ -1,7 +1,7 @@
{
"name": "cereale",
"version": "0.1.0",
"description": "Spring-like decorators for JSON mapping and validation in TypeScript",
"version": "2.0.0",
"description": "Strongly typed JSON mapping and validation for TypeScript classes \u2014 validated domain objects, not validated data",
"type": "module",
"main": "./dist/cjs/index.js",
"module": "./dist/esm/index.js",
@@ -13,7 +13,10 @@
"require": "./dist/cjs/index.js"
}
},
"sideEffects": false,
"sideEffects": [
"./dist/esm/metadata.js",
"./dist/cjs/metadata.js"
],
"files": [
"dist"
],
@@ -39,11 +42,13 @@
},
"keywords": [
"json",
"mapping",
"validation",
"decorators",
"spring",
"typescript"
"typescript",
"zod-alternative",
"dto",
"serialization",
"class-validator"
],
"author": "Avalon Vanguard",
"license": "MIT",
src/decorators.test.ts
+14 -25
View File
@@ -13,7 +13,7 @@ import {
ArrayMaxSize,
IsNotIn,
Validate,
registerDecorator,
defineRule,
JsonType,
JsonPolymorphic,
JsonMapper,
@@ -244,21 +244,14 @@ describe('Additional Decorators', () => {
describe('registerDecorator', () => {
it('should register a custom decorator with functional validator', async () => {
function IsEven() {
return function (object: any, propertyName: string) {
registerDecorator({
name: 'isEven',
target: object.constructor,
propertyName: propertyName,
validator: (value: any) => typeof value === 'number' && value % 2 === 0,
});
};
}
class Test {
@IsEven()
val: number;
val: number = 0;
}
defineRule(Test, 'val', {
name: 'isEven',
validate: (value: any) => typeof value === 'number' && value % 2 === 0,
message: 'val must be even',
});
const t = new Test();
t.val = 2;
@@ -271,19 +264,15 @@ describe('Additional Decorators', () => {
class MyValidator implements ValidatorConstraintInterface {
validate(v: any) { return v === 'ok'; }
}
function IsOk() {
return function (object: any, propertyName: string) {
registerDecorator({
name: 'isOk',
target: object.constructor,
propertyName: propertyName,
validator: MyValidator,
});
};
}
class Test {
@IsOk() val: string;
val: string = '';
}
const validator = new MyValidator();
defineRule(Test, 'val', {
name: 'isOk',
validate: (v: any) => validator.validate(v),
message: 'val must be ok',
});
const t = new Test();
t.val = 'ok';
expect(await JsonMapper.validate(t)).toHaveLength(0);
src/decorators.ts
+518 -1012
View File
File diff suppressed because it is too large Load Diff
src/example.ts
+12 -19
View File
@@ -25,8 +25,7 @@ import {
Validate,
ValidatorConstraintInterface,
ValidationArguments,
registerDecorator,
ValidationOptions
Matches,
} from './index.js';
// --- Custom Validators ---
@@ -42,17 +41,8 @@ class IsLongerThan implements ValidatorConstraintInterface {
}
}
function IsSlug(options?: ValidationOptions) {
return function (object: any, propertyName: string) {
registerDecorator({
name: 'isSlug',
target: object.constructor,
propertyName: propertyName,
...(options ? { options } : {}),
validator: (value: any) => typeof value === 'string' && /^[a-z0-9-]+$/.test(value)
});
};
}
/** A custom rule is just a decorator that composes an existing one. */
const IsSlug = () => Matches(/^[a-z0-9-]+$/, { message: 'name must be a lowercase slug' });
// --- Custom Serializers ---
@@ -76,12 +66,14 @@ enum Format {
}
abstract class Media {
// Standard decorators cannot be applied to an `abstract` member, so the discriminator is a
// concrete field the subclasses override.
@IsString()
abstract type: string;
type: string = '';
// Declared once here. Subclasses inherit the rule without restating it.
@IsString()
title: string;
title: string = '';
}
class Book extends Media {
@@ -111,7 +103,7 @@ class Movie extends Media {
duration: number;
// Only checked for films that claim to be part of a series.
@ValidateIf((movie: Movie) => movie.duration > 200)
@ValidateIf<Movie>(movie => movie.duration > 200)
@IsString()
intermissionNote?: string;
}
@@ -122,7 +114,7 @@ class Library {
id: string;
@IsString()
@IsSlug({ message: 'name must be a lowercase slug' })
@IsSlug()
name: string;
@JsonProperty('curator_email')
@@ -136,11 +128,12 @@ class Library {
@IsArray()
@ValidateNested({ each: true })
@JsonPolymorphic('type', [
// Naming the base type has the subtype list checked against it.
@JsonPolymorphic<Media>('type', [
{ value: Book, name: 'book' },
{ value: Movie, name: 'movie' }
])
items: Media[];
items: Media[] = [];
}
// --- Execution ---
src/hardening.test.ts
+11 -12
View File
@@ -2,7 +2,7 @@ import { describe, it, expect, afterEach } from 'vitest';
import {
IsString, IsInt, Min, IsIn, ValidateNested, JsonType, JsonSerialize, JsonDeserialize,
JsonSerializer, JsonDeserializer, JsonMappingError,
registerDecorator, validate, toInstance, toPlain, configure, resetConfig,
defineRule, validate, toInstance, toPlain, configure, resetConfig,
} from './index.js';
afterEach(() => resetConfig());
@@ -20,11 +20,10 @@ describe('plan caching', () => {
expect(await validate(before)).toEqual([]);
// Register a rule after the plan has already been built and cached.
registerDecorator({
defineRule(Late, 'value', {
name: 'isEven',
target: Late,
propertyName: 'value',
validator: (v: any) => typeof v === 'number' && v % 2 === 0,
validate: (v: any) => typeof v === 'number' && v % 2 === 0,
message: 'value must be even',
});
const after = new Late();
@@ -148,11 +147,11 @@ describe('each: true error reporting', () => {
it('names the index of the element that failed', async () => {
class Basket {
@IsIn(['a', 'b'], { each: true })
tags: string[];
tags!: ('a' | 'b')[];
}
const basket = new Basket();
basket.tags = ['a', 'b', 'a', 'nope', 'b'];
basket.tags = ['a', 'b', 'a', 'nope' as 'a', 'b'];
const errors = await validate(basket);
expect(errors).toHaveLength(1);
@@ -162,10 +161,10 @@ describe('each: true error reporting', () => {
it('leaves a caller-supplied message untouched', async () => {
class Basket {
@IsIn(['a'], { each: true, message: 'bad tag' })
tags: string[];
tags!: 'a'[];
}
const basket = new Basket();
basket.tags = ['a', 'zzz'];
basket.tags = ['a', 'zzz' as 'a'];
const errors = await validate(basket);
expect(errors[0]!.constraints['isIn']).toBe('bad tag');
@@ -174,10 +173,10 @@ describe('each: true error reporting', () => {
it('gives the failing element to a message function, not the whole array', async () => {
class Basket {
@IsIn(['a'], { each: true, message: (args) => `rejected ${JSON.stringify(args.value)}` })
tags: string[];
tags!: 'a'[];
}
const basket = new Basket();
basket.tags = ['a', 'zzz'];
basket.tags = ['a', 'zzz' as 'a'];
const errors = await validate(basket);
expect(errors[0]!.constraints['isIn']).toBe('rejected "zzz"');
@@ -186,7 +185,7 @@ describe('each: true error reporting', () => {
it('reports nothing when every element passes', async () => {
class Basket {
@IsIn(['a', 'b'], { each: true })
tags: string[];
tags!: ('a' | 'b')[];
}
const basket = new Basket();
basket.tags = ['a', 'b'];
src/index.test.ts
+8 -6
View File
@@ -41,16 +41,18 @@ class DateDeserializer implements JsonDeserializer<string, Date> {
// --- Domain Models ---
abstract class Media {
// Standard decorators cannot be applied to an `abstract` member, so the base declares a
// concrete field the subclasses override.
@IsString()
abstract type: string;
type: string = '';
@IsString()
title: string;
title: string = '';
}
class Book extends Media {
@IsString()
type: string = 'book';
override type: string = 'book';
@IsString()
author: string;
@@ -63,7 +65,7 @@ class Book extends Media {
class Movie extends Media {
@IsString()
type: string = 'movie';
override type: string = 'movie';
@IsInt()
@Min(1)
@@ -162,7 +164,7 @@ describe('JsonMapper', () => {
@ArrayNotEmpty()
@IsIn(['admin', 'user', 'guest'], { each: true })
roles: string[];
roles!: ('admin' | 'user' | 'guest')[];
@IsUrl()
@IsOptional()
@@ -224,7 +226,7 @@ describe('JsonMapper', () => {
user.username = 'johndoe';
user.email = 'john@example.com';
user.active = true;
user.roles = ['superadmin'];
user.roles = ['superadmin' as 'admin'];
const errors = await JsonMapper.validate(user);
expect(errors).toHaveLength(1);
src/index.ts
+1
View File
@@ -1,4 +1,5 @@
export * from './interfaces.js';
export * from './metadata.js';
export * from './naming.js';
export * from './config.js';
export * from './decorators.js';
src/interfaces.ts
+44 -5
View File
@@ -1,13 +1,13 @@
/**
* Interface for custom JSON serializers.
*
*
* @template T - The type of the value to serialize (usually a class instance or a specific field).
* @template R - The type of the serialized value (usually a string, number, or plain object).
*/
export interface JsonSerializer<T = any, R = any> {
/**
* Serializes the value into a representation suitable for JSON output.
*
*
* @param value - The value to be serialized.
* @returns The serialized value or a promise resolving to it.
*/
@@ -16,14 +16,14 @@ export interface JsonSerializer<T = any, R = any> {
/**
* Interface for custom JSON deserializers.
*
*
* @template T - The type of the value to deserialize (usually a string or plain object from JSON).
* @template R - The type of the deserialized value (usually a class instance or a specific field).
*/
export interface JsonDeserializer<T = any, R = any> {
/**
* Deserializes the value from a JSON-like representation back to its original type.
*
*
* @param value - The value to be deserialized.
* @returns The deserialized value or a promise resolving to it.
*/
@@ -32,9 +32,48 @@ export interface JsonDeserializer<T = any, R = any> {
/**
* Represents a class constructor function.
*
*
* @template T - The type of the instance created by this constructor.
*/
export type ClassConstructor<T> = {
new (...args: any[]): T;
};
/**
* A decorator that may only be applied to a field whose type is assignable to `Allowed`.
*
* This is what makes cereale's rules type-checked rather than merely declared. Standard
* decorators receive a `ClassFieldDecoratorContext<This, Value>` that carries the field's
* declared type, so applying `@IsString()` to a `number` field is a compile error rather
* than a runtime surprise:
*
* ```ts
* class User {
* @IsString() name!: string; // fine
* @IsString() age!: number; // Type 'number' is not assignable to type 'string'
* }
* ```
*
* `null` and `undefined` are included in the `Allowed` union of every built-in rule so
* optional fields (`nickname?: string`) still accept the rule that describes them.
*/
export type FieldDecorator<Allowed> = <This, Value extends Allowed>(
target: undefined,
context: ClassFieldDecoratorContext<This, Value>
) => void;
/** A field holding a string, or nothing. */
export type StringField = string | null | undefined;
/** A field holding a number, or nothing. */
export type NumberField = number | null | undefined;
/** A field holding a boolean, or nothing. */
export type BooleanField = boolean | null | undefined;
/** A field holding a bigint, or nothing. */
export type BigIntField = bigint | null | undefined;
/** A field holding a Date, or nothing. */
export type DateField = Date | null | undefined;
/** A field holding an array, or nothing. */
export type ArrayField = readonly unknown[] | null | undefined;
/** The element type of an array field, used by rules that run per element. */
export type ElementOf<T> = T extends readonly (infer E)[] ? E : never;
src/metadata-storage.ts
-147
View File
@@ -1,147 +0,0 @@
export class MetadataStorage {
private static instance: MetadataStorage;
/**
* Bumped whenever any metadata is written.
*
* Decorators run at class-definition time, so in practice this stops changing once the
* application has loaded. Derived structures (see the validation plan cache in utils.ts)
* record the version they were built from and rebuild if it moves, which keeps caching
* safe even for metadata registered late through `registerDecorator`.
*/
private _version = 0;
get version(): number {
return this._version;
}
// Maps a prototype to its property names
private properties = new WeakMap<any, string[]>();
// Maps a prototype and property name to its metadata
// Map<Prototype, Map<PropertyKey, Map<MetadataKey, Value>>>
private propertyMetadata = new WeakMap<any, Map<string, Map<string, any>>>();
// Maps a prototype to its class-level metadata
private classMetadata = new WeakMap<any, Map<string, any>>();
private constructor() {}
static getInstance(): MetadataStorage {
if (!MetadataStorage.instance) {
MetadataStorage.instance = new MetadataStorage();
}
return MetadataStorage.instance;
}
/**
* Defines metadata for a specific property on a target.
*/
defineMetadata(key: string, value: any, target: any, propertyKey?: string) {
this._version++;
if (propertyKey) {
let targetMap = this.propertyMetadata.get(target);
if (!targetMap) {
targetMap = new Map();
this.propertyMetadata.set(target, targetMap);
}
let propertyMap = targetMap.get(propertyKey);
if (!propertyMap) {
propertyMap = new Map();
targetMap.set(propertyKey, propertyMap);
}
propertyMap.set(key, value);
} else {
let targetMap = this.classMetadata.get(target);
if (!targetMap) {
targetMap = new Map();
this.classMetadata.set(target, targetMap);
}
targetMap.set(key, value);
}
}
/**
* Gets metadata for a specific property on a target, including from the prototype chain.
*/
getMetadata(key: string, target: any, propertyKey?: string): any {
let current = target;
while (current) {
const value = this.getOwnMetadata(key, current, propertyKey);
if (value !== undefined) {
return value;
}
current = Object.getPrototypeOf(current);
}
return undefined;
}
/**
* Collects a metadata value from every level of the prototype chain that defines one.
*
* Unlike {@link getMetadata}, which stops at the first (most derived) match, this returns
* every value found, ordered from the BASE class down to the most derived one. It exists
* for metadata that must accumulate across an inheritance chain rather than be overridden —
* validation constraints in particular, where a subclass re-decorating an inherited property
* must add to the base class's rules instead of silently replacing them.
*/
getMetadataChain(key: string, target: any, propertyKey?: string): any[] {
const chain: any[] = [];
let current = target;
while (current) {
const value = this.getOwnMetadata(key, current, propertyKey);
if (value !== undefined) {
// Walking derived -> base, so prepend to end up base-first.
chain.unshift(value);
}
current = Object.getPrototypeOf(current);
}
return chain;
}
/**
* Gets metadata defined directly on the target.
*/
getOwnMetadata(key: string, target: any, propertyKey?: string): any {
if (propertyKey) {
return this.propertyMetadata.get(target)?.get(propertyKey)?.get(key);
} else {
return this.classMetadata.get(target)?.get(key);
}
}
/**
* Registers a property for a target.
*/
registerProperty(target: any, propertyKey: string) {
this._version++;
let props = this.properties.get(target);
if (!props) {
props = [];
this.properties.set(target, props);
}
if (!props.includes(propertyKey)) {
props.push(propertyKey);
}
}
/**
* Gets all registered properties for a target, including from the prototype chain.
*/
getProperties(target: any): string[] {
const allProps = new Set<string>();
let current = target;
while (current) {
const props = this.properties.get(current);
if (props) {
props.forEach(p => allProps.add(p));
}
current = Object.getPrototypeOf(current);
}
return Array.from(allProps);
}
}
export const metadataStorage = MetadataStorage.getInstance();
src/metadata.ts
+186
View File
@@ -0,0 +1,186 @@
import type { ClassConstructor } from './interfaces.js';
/**
* The key decorator metadata is stored under.
*
* Resolved into a binding rather than read as `Symbol.metadata` at each use. If the well-known
* symbol is absent, `Symbol.metadata` evaluates to `undefined` and `clazz[undefined]` quietly
* reads a property literally named "undefined" — `modelOf` would return an empty model and
* every object would validate clean. Silent success is the worst failure mode a validation
* library can have, so the fallback is baked into the value the code actually uses.
*
* `Symbol.for` matches what the decorator transforms emit (esbuild's `__knownSymbol` uses the
* same fallback), and keeps the key identical across duplicate copies of the library, which
* the dual ESM/CJS build can otherwise produce.
*/
const METADATA_KEY: symbol = (Symbol as { metadata?: symbol }).metadata ?? Symbol.for('Symbol.metadata');
// Also installed globally, because a consumer's own compiler emit may read `Symbol.metadata`
// directly. package.json marks this module as having side effects so it survives bundling.
((Symbol as { metadata?: symbol }).metadata as symbol | undefined) ??= METADATA_KEY;
export interface ValidationArguments {
value: any;
object: any;
property: string;
constraints: any[];
}
export interface ValidationOptions {
/** Apply the rule to each element of an array rather than to the array itself. */
each?: boolean;
/** Replaces the built-in message. Reported verbatim — the engine never decorates it. */
message?: string | ((args: ValidationArguments) => string);
}
/** Narrowed form used by the `each: true` decorator overloads. */
export interface EachValidationOptions extends ValidationOptions {
each: true;
}
export type ValidationConstraint = {
name: string;
validate: (value: any, args: ValidationArguments) => boolean | Promise<boolean>;
message: string | ((args: ValidationArguments) => string);
constraints?: any[];
each?: boolean;
/**
* True when the message came from the caller. The engine only decorates its own default
* wording with the "each element in ..." prefix.
*/
hasCustomMessage?: boolean;
};
export interface ValidatorConstraintInterface {
validate(value: any, args: ValidationArguments): boolean | Promise<boolean>;
defaultMessage?(args: ValidationArguments): string;
}
/**
* Which directions a property participates in.
*
* - `readwrite` (default): mapped both ways.
* - `readonly`: written to JSON, never populated from incoming JSON (server-assigned ids).
* - `writeonly`: populated from incoming JSON, never written back out (passwords).
* - `none`: ignored entirely.
*/
export type PropertyAccess = 'readwrite' | 'readonly' | 'writeonly' | 'none';
export interface PolymorphicInfo {
discriminator: string;
subTypes: { value: ClassConstructor<any>; name: string }[];
onUnknown: 'keep' | 'error';
fallback?: ClassConstructor<any>;
}
/** Everything cereale knows about one field. */
export interface PropertyModel {
constraints: ValidationConstraint[];
optional?: boolean;
nested?: boolean;
condition?: (object: any) => boolean;
/** Explicit JSON name from `@JsonProperty`. */
name?: string;
aliases?: string[];
access?: PropertyAccess;
serializer?: ClassConstructor<any>;
deserializer?: ClassConstructor<any>;
type?: () => ClassConstructor<any>;
polymorphic?: PolymorphicInfo;
}
export type ClassModel = Record<string, PropertyModel>;
const MODEL = Symbol.for('cereale.model');
/**
* Bumped whenever a model is written. Derived structures (the plans in engine.ts) record the
* version they were built from and rebuild if it moves, so programmatic registration after a
* class has already been used stays correct.
*/
let version = 0;
export function modelVersion(): number {
return version;
}
/**
* Returns the model owned by this class, creating it if necessary.
*
* `context.metadata` inherits from the base class's metadata through the prototype chain, so
* a subclass starts out seeing everything its base declared. Writing requires an own copy —
* otherwise a subclass would mutate its parent — and the inherited entries are deep-copied so
* that a subclass re-decorating an inherited field *adds to* the base's rules instead of
* replacing them. That inheritance-merging behaviour is structural here; the previous
* WeakMap-based storage had to reconstruct it by walking prototypes on every read.
*/
function ownModel(metadata: DecoratorMetadata): ClassModel {
if (!Object.hasOwn(metadata, MODEL)) {
const inherited = (metadata as Record<symbol, ClassModel | undefined>)[MODEL];
const own: ClassModel = {};
for (const [key, property] of Object.entries(inherited ?? {})) {
own[key] = { ...property, constraints: [...property.constraints] };
}
(metadata as Record<symbol, ClassModel>)[MODEL] = own;
}
return (metadata as Record<symbol, ClassModel>)[MODEL]!;
}
/** Returns (creating if needed) the model entry for one field. */
export function propertyModel(metadata: DecoratorMetadata, property: string): PropertyModel {
version++;
const model = ownModel(metadata);
return (model[property] ??= { constraints: [] });
}
/** Appends a validation rule to a field, honouring `each` and a caller-supplied message. */
export function addConstraint(
metadata: DecoratorMetadata,
property: string,
constraint: ValidationConstraint,
options?: ValidationOptions
): void {
if (options?.each) constraint.each = true;
if (options?.message) {
constraint.message = options.message;
constraint.hasCustomMessage = true;
}
propertyModel(metadata, property).constraints.push(constraint);
}
/** Reads the model declared on a class. Returns an empty model for undecorated classes. */
export function modelOf(clazz: unknown): ClassModel {
if (typeof clazz !== 'function') return {};
const metadata = (clazz as unknown as Record<symbol, DecoratorMetadata | undefined>)[METADATA_KEY];
return (metadata as Record<symbol, ClassModel> | undefined)?.[MODEL] ?? {};
}
/**
* Reads the model that applies to an instance.
*
* Guarded rather than reading `obj.constructor` directly: null-prototype objects have no
* constructor, and an instance whose `constructor` property has been overwritten would lie.
*/
export function modelOfInstance(obj: object): ClassModel {
const prototype = Object.getPrototypeOf(obj);
if (!prototype) return {};
const descriptor = Object.getOwnPropertyDescriptor(prototype, 'constructor');
return modelOf(descriptor?.value);
}
/**
* Registers a rule on a class from outside a decorator.
*
* The escape hatch for rules that cannot be expressed at the declaration site — built from
* configuration, say. Prefer decorators, which are type-checked against the field.
*/
export function defineRule<T>(
clazz: ClassConstructor<T>,
property: keyof T & string,
constraint: ValidationConstraint,
options?: ValidationOptions
): void {
const holder = clazz as unknown as Record<symbol, DecoratorMetadata | undefined>;
holder[METADATA_KEY] ??= Object.create(null) as DecoratorMetadata;
addConstraint(holder[METADATA_KEY]!, property, constraint, options);
}
src/regressions.test.ts
+3 -3
View File
@@ -21,7 +21,7 @@ describe('regressions', () => {
}
class Sub extends Base {
@IsString()
declare name: string;
override name: string = '';
}
const s = new Sub();
@@ -35,7 +35,7 @@ describe('regressions', () => {
it('enforces base constraints that the subclass never restates', async () => {
abstract class Media {
@IsString()
title: string;
title: string = '';
}
class Book extends Media {
@IsString()
@@ -57,7 +57,7 @@ describe('regressions', () => {
}
class Sub extends Base {
@IsString()
declare type: string;
override type: string = '';
}
const s = new Sub();
src/sync.test.ts
+2 -2
View File
@@ -383,14 +383,14 @@ describe('write-only redaction in validation errors', () => {
it('does not redact a value that merely sits next to a secret', async () => {
class Form {
@IsIn(['a', 'b'])
choice: string;
choice!: 'a' | 'b';
@JsonWriteOnly()
@IsString()
token: string;
}
const form = new Form();
form.choice = 'zzz';
form.choice = 'zzz' as 'a';
form.token = 'secret-token';
const errors = await validate(form);
src/type-safety.test.ts
+175
View File
@@ -0,0 +1,175 @@
import { describe, it, expect } from 'vitest';
import { execFileSync } from 'node:child_process';
import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join, resolve } from 'node:path';
/**
* The headline guarantee of v2 is that a rule cannot be attached to a field it does not fit.
* That is a *compile-time* claim, so asserting it needs the compiler: each case below is
* type-checked in isolation and must fail.
*
* These run the real `tsc`, so they are slower than the rest of the suite — but a guarantee
* nobody checks is a guarantee that quietly stops holding.
*/
const TSC = resolve('node_modules/.bin/tsc');
const SRC = resolve('src/index.js').replace(/\.js$/, '');
function typeCheck(body: string): { ok: boolean; output: string } {
const dir = mkdtempSync(join(tmpdir(), 'cereale-types-'));
try {
writeFileSync(join(dir, 'tsconfig.json'), JSON.stringify({
compilerOptions: {
target: 'ES2022', module: 'NodeNext', moduleResolution: 'NodeNext',
// DOM supplies URL/Request, which the library's own signatures reference. A real
// consumer has these from either DOM or @types/node.
lib: ['ESNext', 'ESNext.Decorators', 'DOM'], strict: true,
strictPropertyInitialization: false, noEmit: true, skipLibCheck: true,
},
include: ['case.ts'],
}));
writeFileSync(join(dir, 'case.ts'), `import {\n IsString, IsInt, Min, MinLength, IsArray, ArrayMinSize, ArrayUnique,\n IsDate, MinDate, IsBoolean, IsIn, IsEnum, JsonType, JsonSerialize,\n JsonDeserialize, JsonSerializer, JsonDeserializer,\n} from ${JSON.stringify(SRC + '.js')};\n\n${body}\n`);
try {
execFileSync(process.execPath, [TSC, '-p', dir], { stdio: 'pipe' });
return { ok: true, output: '' };
} catch (error: any) {
return { ok: false, output: String(error.stdout ?? '') + String(error.stderr ?? '') };
}
} finally {
rmSync(dir, { recursive: true, force: true });
}
}
const compiles = (body: string) => {
const result = typeCheck(body);
if (!result.ok) throw new Error(`expected this to compile but it did not:\n${result.output}`);
};
const rejects = (body: string) => {
const result = typeCheck(body);
expect(result.ok, 'expected a compile error, but it compiled').toBe(false);
return result.output;
};
describe('rules are checked against the field type', () => {
it('accepts rules that match the field', () => {
compiles(`
class Ok {
@IsString() @MinLength(2) name!: string;
@IsInt() @Min(0) age!: number;
@IsBoolean() active!: boolean;
@IsDate() @MinDate(new Date(0)) when!: Date;
@IsArray() @ArrayMinSize(1) tags!: string[];
@IsString() nickname?: string;
@IsString() maybe!: string | null;
}
void Ok;
`);
}, 60_000);
it('rejects a string rule on a number field', () => {
expect(rejects(`class Bad { @IsString() age!: number } void Bad;`))
.toMatch(/not assignable|Unable to resolve/);
}, 60_000);
it('rejects a number rule on a string field', () => {
expect(rejects(`class Bad { @Min(0) label!: string } void Bad;`))
.toMatch(/not assignable|Unable to resolve/);
}, 60_000);
it('rejects an array rule on a non-array field', () => {
expect(rejects(`class Bad { @ArrayMinSize(1) count!: number } void Bad;`))
.toMatch(/not assignable|Unable to resolve/);
}, 60_000);
it('rejects a date rule on a string field', () => {
expect(rejects(`class Bad { @MinDate(new Date(0)) when!: string } void Bad;`))
.toMatch(/not assignable|Unable to resolve/);
}, 60_000);
});
describe('each: true moves the rule onto the elements', () => {
it('accepts a matching array field', () => {
compiles(`class Ok { @IsString({ each: true }) tags!: string[] } void Ok;`);
}, 60_000);
it('rejects each:true on a scalar field', () => {
expect(rejects(`class Bad { @IsString({ each: true }) tag!: string } void Bad;`))
.toMatch(/not assignable|Unable to resolve/);
}, 60_000);
it('rejects a bare rule on an array field', () => {
expect(rejects(`class Bad { @IsString() tags!: string[] } void Bad;`))
.toMatch(/not assignable|Unable to resolve/);
}, 60_000);
it('rejects an element-type mismatch', () => {
expect(rejects(`class Bad { @IsString({ each: true }) nums!: number[] } void Bad;`))
.toMatch(/not assignable|Unable to resolve/);
}, 60_000);
});
describe('nested types and converters are checked', () => {
const shapes = `
class Address { street!: string }
class Money { amount!: number }
`;
it('accepts the matching class', () => {
compiles(`${shapes}
class Ok {
@JsonType(() => Address) ship!: Address;
@JsonType(() => Address) history!: Address[];
}
void Ok;`);
}, 60_000);
it('rejects an unrelated class', () => {
expect(rejects(`${shapes}
class Bad { @JsonType(() => Money) ship!: Address }
void Bad;`)).toMatch(/not assignable|Unable to resolve/);
}, 60_000);
it('rejects a serializer whose input does not match the field', () => {
expect(rejects(`
class DateToString implements JsonSerializer<Date, string> {
serialize(v: Date) { return v.toISOString(); }
}
class Bad { @JsonSerialize(DateToString) name!: string }
void Bad;`)).toMatch(/not assignable|Unable to resolve/);
}, 60_000);
it('rejects a deserializer whose output does not match the field', () => {
expect(rejects(`
class StringToDate implements JsonDeserializer<string, Date> {
deserialize(v: string) { return new Date(v); }
}
class Bad { @JsonDeserialize(StringToDate) name!: string }
void Bad;`)).toMatch(/not assignable|Unable to resolve/);
}, 60_000);
});
describe('membership rules narrow the field', () => {
it('accepts a field typed as the allowed union', () => {
compiles(`class Ok { @IsIn(['a', 'b']) choice!: 'a' | 'b' } void Ok;`);
}, 60_000);
it('rejects a field that cannot hold the allowed values', () => {
expect(rejects(`class Bad { @IsIn(['a', 'b']) choice!: number } void Bad;`))
.toMatch(/not assignable|Unable to resolve/);
}, 60_000);
it('rejects an enum rule on a mismatched field', () => {
expect(rejects(`
enum Role { Admin = 'admin' }
class Bad { @IsEnum(Role) role!: number }
void Bad;`)).toMatch(/not assignable|Unable to resolve/);
}, 60_000);
it('accepts an enum rule on the enum field', () => {
compiles(`
enum Role { Admin = 'admin', User = 'user' }
class Ok { @IsEnum(Role) role!: Role }
void Ok;`);
}, 60_000);
});
src/utils.ts
+71 -105
View File
@@ -1,6 +1,9 @@
import { ClassConstructor } from './interfaces.js';
import { METADATA_KEYS, PropertyAccess, ValidationConstraint, ValidationArguments } from './decorators.js';
import { metadataStorage } from './metadata-storage.js';
import {
modelOf, modelOfInstance, modelVersion,
type ClassModel, type PropertyAccess, type PropertyModel,
type ValidationArguments, type ValidationConstraint,
} from './metadata.js';
import { NamingStrategyFn, resolveNamingStrategy } from './naming.js';
import { TransformOptions, UnknownKeyPolicy, resolveOptions } from './config.js';
@@ -62,25 +65,13 @@ interface DeserializeContext {
maxDepth: number;
}
/**
* Resolves the metadata lookup target for a value.
*
* `Object.getPrototypeOf` rather than `obj.constructor.prototype`: the latter throws on
* null-prototype objects (which have no `constructor`) and lies for instances whose
* `constructor` property has been overwritten.
*/
function prototypeOf(obj: any): any {
return Object.getPrototypeOf(obj) ?? undefined;
}
function accessOf(target: any, key: string): PropertyAccess {
return (target ? metadataStorage.getMetadata(METADATA_KEYS.ACCESS, target, key) : undefined) ?? 'readwrite';
function accessOf(model: ClassModel, key: string): PropertyAccess {
return model[key]?.access ?? 'readwrite';
}
/** The name this property takes in JSON: an explicit @JsonProperty, else the naming strategy. */
function outboundName(target: any, key: string, naming: NamingStrategyFn): string {
const explicit = target ? metadataStorage.getMetadata(METADATA_KEYS.NAME, target, key) : undefined;
return explicit ?? naming(key);
function outboundName(model: ClassModel, key: string, naming: NamingStrategyFn): string {
return model[key]?.name ?? naming(key);
}
/** Per-property serialization facts, resolved once instead of per call. */
@@ -93,7 +84,7 @@ interface OutboundProperty {
serializer?: any;
}
const outboundCache = new WeakMap<object, { version: number; byStrategy: Map<unknown, Map<string, OutboundProperty>> }>();
const outboundCache = new WeakMap<ClassModel, { version: number; byStrategy: Map<unknown, Map<string, OutboundProperty>> }>();
/**
* Resolves how one property is written out, memoized per (prototype, naming strategy).
@@ -101,16 +92,11 @@ const outboundCache = new WeakMap<object, { version: number; byStrategy: Map<unk
* Serialization walks the runtime keys of each object, so undeclared properties turn up here
* too; they memoize just as well, since the naming strategy is deterministic.
*/
function outboundFor(target: any, key: string, ctx: SerializeContext): OutboundProperty {
if (!target) {
// Null-prototype object: nothing is declared, so there is nothing to cache against.
return { name: ctx.naming(key), skip: false };
}
let entry = outboundCache.get(target);
if (!entry || entry.version !== metadataStorage.version) {
entry = { version: metadataStorage.version, byStrategy: new Map() };
outboundCache.set(target, entry);
function outboundFor(model: ClassModel, key: string, ctx: SerializeContext): OutboundProperty {
let entry = outboundCache.get(model);
if (!entry || entry.version !== modelVersion()) {
entry = { version: modelVersion(), byStrategy: new Map() };
outboundCache.set(model, entry);
}
let byKey = entry.byStrategy.get(ctx.namingKey);
@@ -121,10 +107,10 @@ function outboundFor(target: any, key: string, ctx: SerializeContext): OutboundP
let resolved = byKey.get(key);
if (!resolved) {
const access = accessOf(target, key);
const serializer = metadataStorage.getMetadata(METADATA_KEYS.SERIALIZER, target, key);
const access = accessOf(model, key);
const serializer = model[key]?.serializer;
resolved = {
name: outboundName(target, key, ctx.naming),
name: outboundName(model, key, ctx.naming),
// `writeonly` is accepted on input but must never be echoed back out.
skip: access === 'none' || access === 'writeonly',
...(serializer ? { serializer } : {}),
@@ -157,7 +143,7 @@ interface InboundNames {
// Name maps are derived purely from decorator metadata, which is fixed once a class is
// declared, so they are cached per (prototype, naming strategy).
const inboundCache = new WeakMap<object, { version: number; byStrategy: Map<unknown, InboundNames> }>();
const inboundCache = new WeakMap<ClassModel, { version: number; byStrategy: Map<unknown, InboundNames> }>();
/**
* Builds the JSON-name -> property-key lookup used when reading a payload.
@@ -167,11 +153,11 @@ const inboundCache = new WeakMap<object, { version: number; byStrategy: Map<unkn
* property therefore stops the old name from being silently accepted — add `@JsonAlias` to
* keep it working for older clients.
*/
function inboundNameMap(target: any, ctx: DeserializeContext): InboundNames {
let entry = inboundCache.get(target);
if (!entry || entry.version !== metadataStorage.version) {
entry = { version: metadataStorage.version, byStrategy: new Map() };
inboundCache.set(target, entry);
function inboundNameMap(model: ClassModel, ctx: DeserializeContext): InboundNames {
let entry = inboundCache.get(model);
if (!entry || entry.version !== modelVersion()) {
entry = { version: modelVersion(), byStrategy: new Map() };
inboundCache.set(model, entry);
}
const cached = entry.byStrategy.get(ctx.namingKey);
if (cached) return cached;
@@ -191,13 +177,10 @@ function inboundNameMap(target: any, ctx: DeserializeContext): InboundNames {
accept.set(external, key);
};
for (const key of metadataStorage.getProperties(target)) {
const names = [
outboundName(target, key, ctx.naming),
...(metadataStorage.getMetadata(METADATA_KEYS.ALIASES, target, key) || []),
];
for (const [key, property] of Object.entries(model)) {
const names = [outboundName(model, key, ctx.naming), ...(property.aliases ?? [])];
const access = accessOf(target, key);
const access = accessOf(model, key);
if (access === 'none' || access === 'readonly') {
for (const name of names) blocked.add(name);
continue;
@@ -205,14 +188,11 @@ function inboundNameMap(target: any, ctx: DeserializeContext): InboundNames {
for (const name of names) claim(name, key);
const deserializer = metadataStorage.getMetadata(METADATA_KEYS.DESERIALIZER, target, key);
const polymorphic = metadataStorage.getMetadata(METADATA_KEYS.POLYMORPHIC, target, key);
const typeFn = metadataStorage.getMetadata(METADATA_KEYS.TYPE, target, key);
if (deserializer || polymorphic || typeFn) {
if (property.deserializer || property.polymorphic || property.type) {
props.set(key, {
...(deserializer ? { deserializer } : {}),
...(polymorphic ? { polymorphic } : {}),
...(typeFn ? { typeFn } : {}),
...(property.deserializer ? { deserializer: property.deserializer } : {}),
...(property.polymorphic ? { polymorphic: property.polymorphic } : {}),
...(property.type ? { typeFn: property.type } : {}),
});
}
}
@@ -295,11 +275,11 @@ function serialize(obj: any, ancestors: Set<any>, ctx: SerializeContext, depth:
return out;
}
const target = prototypeOf(obj);
const model = modelOfInstance(obj);
const result: any = {};
for (const key of Object.keys(obj)) {
const property = outboundFor(target, key, ctx);
const property = outboundFor(model, key, ctx);
if (property.skip) continue;
const value = obj[key];
@@ -347,8 +327,7 @@ function deserialize<T>(clazz: ClassConstructor<T>, plain: any, ctx: Deserialize
if (typeof plain !== 'object') return plain;
const instance = new clazz();
const target = clazz.prototype;
const inbound = inboundNameMap(target, ctx);
const inbound = inboundNameMap(modelOf(clazz), ctx);
for (const incoming of Object.keys(plain)) {
if (FORBIDDEN_KEYS.has(incoming)) continue;
@@ -428,36 +407,6 @@ function deserialize<T>(clazz: ClassConstructor<T>, plain: any, ctx: Deserialize
return instance;
}
/**
* Collects the validation constraints that apply to a property, merged across the whole
* prototype chain.
*
* A subclass that re-decorates an inherited property registers its constraints against its
* own prototype. Reading only the nearest set would silently drop everything the base class
* declared, so the chain is flattened base-first. Constraints that are genuinely identical
* (same rule, same fixed message) are collapsed so that re-stating `@IsString()` on an
* override does not report the same failure twice; anything with a computed message — custom
* validators in particular — is always kept.
*/
function collectConstraints(target: any, key: string): ValidationConstraint[] {
const levels: ValidationConstraint[][] = metadataStorage.getMetadataChain(METADATA_KEYS.VALIDATION, target, key);
const merged: ValidationConstraint[] = [];
const seen = new Set<string>();
for (const level of levels) {
for (const constraint of level) {
if (typeof constraint.message === 'string') {
const identity = `${constraint.name}|${String(constraint.constraints)}|${constraint.message}`;
if (seen.has(identity)) continue;
seen.add(identity);
}
merged.push(constraint);
}
}
return merged;
}
/**
* Everything the validator needs to know about one property, resolved once.
*/
@@ -476,33 +425,53 @@ interface CachedPlan {
plan: PropertyPlan[];
}
// Resolving a class's validation rules means walking its prototype chain several times per
// property, per call — which profiling showed to be roughly half of all validation time,
// recomputing an answer that cannot change. The result is memoized per prototype and
// invalidated by MetadataStorage's version counter, so metadata registered late still works.
const planCache = new WeakMap<object, CachedPlan>();
// Turning a class model into a per-property plan is cheap, but doing it on every call was
// measurably not: profiling showed roughly half of all validation time re-deriving answers
// that cannot change. Plans are memoized per model and invalidated by the model version.
const planCache = new WeakMap<ClassModel, CachedPlan>();
function validationPlan(target: any): PropertyPlan[] {
const cached = planCache.get(target);
if (cached && cached.version === metadataStorage.version) {
/**
* Collapses rules that are genuinely identical.
*
* Inheritance is structural here: a subclass's model starts as a copy of its base's, so
* re-stating `@IsString()` on an override would otherwise report the same failure twice.
* Only rules with a fixed message are compared — anything with a computed message, custom
* validators in particular, is always kept, since two of them can differ while looking alike.
*/
function dedupe(constraints: ValidationConstraint[]): ValidationConstraint[] {
const kept: ValidationConstraint[] = [];
const seen = new Set<string>();
for (const constraint of constraints) {
if (typeof constraint.message === 'string') {
const identity = `${constraint.name}|${String(constraint.constraints)}|${constraint.message}|${constraint.each ?? false}`;
if (seen.has(identity)) continue;
seen.add(identity);
}
kept.push(constraint);
}
return kept;
}
function validationPlan(model: ClassModel): PropertyPlan[] {
const cached = planCache.get(model);
if (cached && cached.version === modelVersion()) {
return cached.plan;
}
const plan: PropertyPlan[] = [];
for (const key of metadataStorage.getProperties(target)) {
const condition = metadataStorage.getMetadata(METADATA_KEYS.CONDITION, target, key);
const access = accessOf(target, key);
for (const [key, property] of Object.entries(model) as [string, PropertyModel][]) {
const access = property.access ?? 'readwrite';
plan.push({
key,
constraints: collectConstraints(target, key),
isOptional: !!metadataStorage.getMetadata(METADATA_KEYS.IS_OPTIONAL, target, key),
isNested: !!metadataStorage.getMetadata(METADATA_KEYS.NESTED, target, key),
constraints: dedupe(property.constraints),
isOptional: !!property.optional,
isNested: !!property.nested,
redact: access === 'writeonly' || access === 'none',
...(condition ? { condition } : {}),
...(property.condition ? { condition: property.condition } : {}),
});
}
planCache.set(target, { version: metadataStorage.version, plan });
planCache.set(model, { version: modelVersion(), plan });
return plan;
}
@@ -644,10 +613,7 @@ function validateInternal(obj: any, ancestors: Set<any>, depth: number, maxDepth
return errors;
}
const target = prototypeOf(obj);
if (!target) return errors;
for (const property of validationPlan(target)) {
for (const property of validationPlan(modelOfInstance(obj))) {
const key = property.key;
const value = obj[key];
src/validators.test.ts
+22 -5
View File
@@ -11,12 +11,29 @@ import {
validate, toInstance,
} from './index.js';
/** Builds a one-property class, assigns `value`, and returns the constraint keys that failed. */
async function check(decorate: (target: any, key: string) => void, value: any): Promise<string[]> {
/**
* Applies a decorator to a synthetic one-field class and reports which rules failed.
*
* Standard decorators are invoked as `(undefined, context)` rather than against a prototype,
* so the context is built by hand here. Only `name` and `metadata` are read by the library;
* the rest satisfies the shape.
*/
async function check(decorator: any, value: any): Promise<string[]> {
const metadata = Object.create(null) as DecoratorMetadata;
decorator(undefined, {
kind: 'field',
name: 'val',
static: false,
private: false,
metadata,
access: { has: () => true, get: (o: any) => o.val, set: (o: any, v: any) => { o.val = v; } },
addInitializer: () => undefined,
});
class Subject {
val: any;
}
decorate(Subject.prototype, 'val');
(Subject as any)[Symbol.metadata] = metadata;
const subject = new Subject();
subject.val = value;
@@ -232,9 +249,9 @@ describe('arrays', () => {
describe('@ValidateIf', () => {
class Payment {
@IsIn(['card', 'invoice'])
method: string;
method!: 'card' | 'invoice';
@ValidateIf(o => o.method === 'card')
@ValidateIf<Payment>(o => o.method === 'card')
@IsString()
cardNumber?: string;
}
tsconfig.json
+4 -2
View File
@@ -8,7 +8,7 @@
// Environment Settings
"module": "NodeNext",
"target": "ES2025",
"lib": ["ESNext"],
"lib": ["ESNext", "ESNext.Decorators"],
"types": ["node"],
// Other Outputs
@@ -33,7 +33,9 @@
"isolatedModules": true,
"skipLibCheck": true,
"experimentalDecorators": true
// NOTE: no `experimentalDecorators`. v2 uses TC39 standard decorators, which is what
// gives ClassFieldDecoratorContext<This, Value> and therefore compile-time checking of
// rules against field types. The two decorator systems cannot coexist in one program.
},
// NOTE: test files are deliberately included here so that `npm run type-check`
// covers them. The two build configs exclude them (and the demo) from `dist`.
vitest.config.ts
+30 -7
View File
@@ -1,13 +1,36 @@
import { defineConfig } from 'vitest/config';
import { transform } from 'esbuild';
/**
* Transpiles test sources with esbuild instead of oxc.
*
* Vitest 4 transforms with oxc, which does not yet implement the TC39 standard decorator
* transform — it leaves the syntax in place and Node then fails to parse it, reporting
* "0 test" rather than an error. esbuild and tsc both implement it, so the library's own
* build (`tsc`) and consumers bundling with esbuild or Vite are unaffected; only the test
* runner needs this. Remove it once oxc gains standard-decorator support.
*/
function standardDecorators() {
return {
name: 'cereale:standard-decorators',
enforce: 'pre' as const,
async transform(code: string, id: string) {
if (!/\.ts$/.test(id) || id.includes('node_modules')) return null;
const result = await transform(code, {
loader: 'ts',
target: 'es2022',
sourcefile: id,
sourcemap: true,
// Standard semantics, not the legacy ones: the library reads context.metadata.
tsconfigRaw: { compilerOptions: { experimentalDecorators: false, useDefineForClassFields: true } },
});
return { code: result.code, map: result.map };
},
};
}
export default defineConfig({
// Vitest 4 transpiles with oxc, which does not read `experimentalDecorators`
// out of tsconfig.json for files the tsconfig does not `include`. Without this
// the decorator syntax in the test files fails to parse and every suite is
// silently reported as "0 test".
oxc: {
decorator: { legacy: true },
},
plugins: [standardDecorators()],
test: {
include: ['src/**/*.test.ts'],
coverage: {