✨ feat!: v2 — strongly typed decorators on the TC39 standard

BREAKING CHANGE: cereale moves from legacy `experimentalDecorators` to TC39
standard decorators, which is what makes validation rules type-checked against
the fields they are attached to.

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

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

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

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

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

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

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

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SAcqrz3FcadkYr3xG32CjK

src/decorators.test.ts

@@ -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/example.ts

@@ -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

@@ -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

@@ -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,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

@@ -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

@@ -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

@@ -0,0 +1,174 @@
+import type { ClassConstructor } from './interfaces.js';
+
+// TypeScript's standard-decorator emit reads `Symbol.metadata`. Node does not define it yet,
+// so it is installed here, before any decorated class in the consuming application is
+// evaluated. `Symbol.for` keeps it identical across duplicate copies of the library, which
+// the dual ESM/CJS build can otherwise produce.
+((Symbol as { metadata?: symbol }).metadata as symbol | undefined) ??=
+  Symbol.for('Symbol.metadata');
+
+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 { [Symbol.metadata]?: DecoratorMetadata })[Symbol.metadata];
+  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 { [Symbol.metadata]?: DecoratorMetadata };
+  holder[Symbol.metadata] ??= Object.create(null) as DecoratorMetadata;
+  addConstraint(holder[Symbol.metadata]!, property, constraint, options);
+}

src/regressions.test.ts

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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;
   }