🔖 chore: number the legacy-decorator line 0.1.x, not 1.x

Nothing has been published, so a 1.0.0/2.0.0 split claimed a stability and a
history that do not exist. Staying on 0.x says what is true: the API may still
move. Under semver a breaking change is then a minor bump, which is exactly the
relationship between the two lines — 0.1.x keeps legacy experimentalDecorators,
0.2.x moves to TC39 standard decorators.

Branch renamed 1.x -> 0.1.x to match, along with its CI trigger and the
maintenance-line notice in the README.

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

.github/workflows/ci.yml

@@ -2,9 +2,9 @@ name: CI
 
 on:
   push:
-    branches: [ main, develop ]
+    branches: [ main, develop, 0.1.x ]
   pull_request:
-    branches: [ main, develop ]
+    branches: [ main, develop, 0.1.x ]
 
 jobs:
   verify:

CHANGELOG.md

@@ -5,76 +5,17 @@ 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).
 
-## [0.2.0] - 2026-08-04
-
-> The project stays on 0.x while nothing has been published: under semver that signals the
-> API may still move, which is honest for software with no real-world users. A breaking
-> change is therefore a minor bump, which is why this is 0.2.0 rather than 2.0.0.
-
-**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 0.1.x for now.
-
 ## [0.1.0] - 2026-08-05
 
+The legacy-decorator line, now maintained in parallel with 0.2.x. Functionally identical
+to the previous state; only the maintenance-line notice was added. See the 0.2.x branch
+for standard decorators and compile-time rule checking.
+
+The project stays on 0.x while nothing has been published: under semver that signals the
+API may still move, which is honest for software with no real-world users yet. A breaking
+change is therefore a minor bump — 0.1.x to 0.2.x.
+
+
 ### Added
 
 **Synchronous API.** `validateSync`, `validateOrRejectSync`, `toPlainSync`, `toJsonSync`,

README.md

@@ -1,58 +1,27 @@
 # Cereale
 
-**Validated domain objects, not validated data.**
+> **This is the 0.1.x maintenance line**, which uses TypeScript's legacy
+> `experimentalDecorators`. It is feature-complete and supported for bug fixes.
+>
+> **New projects should use 0.2.x**, which moves to TC39 standard decorators and gains
+> compile-time checking of validation rules against field types — `@IsString() age: number`
+> becomes a compile error rather than a runtime surprise.
+>
+> Stay on 0.1.x if your toolchain transpiles with **oxc**, which does not yet implement the
+> standard decorator transform. `tsc` and esbuild both do, so most projects can move.
 
-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.
+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.
 
 ## Features
 
-- **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+.
+- **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.
 
 ## Installation
 
@@ -60,93 +29,109 @@ entity, anything with behaviour attached. Reach for Zod when you just want the d
 npm install cereale
 ```
 
-Cereale v2 uses **TC39 standard decorators**, so no `experimentalDecorators` flag:
+Enable `experimentalDecorators` in your `tsconfig.json`:
 
 ```json
 {
   "compilerOptions": {
-    "target": "ES2022",
-    "lib": ["ESNext", "ESNext.Decorators"]
+    "experimentalDecorators": true,
+    "target": "ES2022"
   }
 }
 ```
 
-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. The 0.1.x line, which uses legacy decorators, remains available for
-> those setups.
+Cereale stores its own metadata, so `reflect-metadata` is not required and
+`emitDecoratorMetadata` is not read. Requires Node 20 or later.
 
 ## Quick Start
 
-### 1. Define your model
+### 1. Define your Models
 
 ```typescript
 import {
-  IsString, IsDate, IsInt, Min, ValidateNested, JsonType,
-  JsonProperty, JsonWriteOnly, JsonPolymorphic,
+  IsString,
+  IsDate,
+  ValidateNested,
+  JsonSerialize,
+  JsonDeserialize,
+  JsonPolymorphic,
+  JsonSerializer,
+  JsonDeserializer
 } from 'cereale';
 
-class Address {
-  @IsString() street!: string;
-  @IsString() city!: string;
+// Custom Date Serializer
+class DateSerializer implements JsonSerializer<Date, string> {
+  serialize(value: Date): string {
+    return value.toISOString().split('T')[0]!;
+  }
+}
 
-  format() { return `${this.street}, ${this.city}`; }
+class DateDeserializer implements JsonDeserializer<string, Date> {
+  deserialize(value: string): Date {
+    return new Date(value);
+  }
 }
 
 abstract class Media {
-  // Standard decorators cannot decorate an `abstract` member, so declare it concretely.
-  @IsString() type: string = '';
-  @IsString() title: string = '';
+  @IsString()
+  abstract type: string;
+
+  @IsString()
+  title: string;
 }
 
 class Book extends Media {
-  @IsString() override type = 'book';
-  @IsString() author!: string;
+  type = 'book';
 
-  @JsonProperty('published_at')
+  @IsString()
+  author: string;
+
+  @JsonSerialize(DateSerializer)
+  @JsonDeserialize(DateDeserializer)
   @IsDate()
-  publishedAt!: Date;
+  publishedAt: Date;
 }
 
 class Library {
-  @IsString() name!: string;
-
-  @ValidateNested() @JsonType(() => Address)
-  address!: Address;              // the class must match the field
+  @IsString()
+  name: string;
 
   @ValidateNested({ each: true })
-  @JsonPolymorphic<Media>('type', [{ value: Book, name: 'book' }])
-  items!: Media[];
+  @JsonPolymorphic('type', [
+    { value: Book, name: 'book' }
+  ])
+  items: Media[];
 }
 ```
 
-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.
+Constraints accumulate down an inheritance chain: `Book` is checked against `Media`'s
+`@IsString() title` as well as its own rules.
 
-### 2. Map JSON, synchronously or not
+### 2. Map JSON with Validation
 
 ```typescript
-import { fromJsonSync, toJsonSync, JsonValidationError, flattenErrors } from 'cereale';
+import { fromJson, toJson, JsonValidationError, flattenErrors } from 'cereale';
 
-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) {
+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"] }
     }
+  }
 }
 ```
 
-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.
@@ -426,13 +411,6 @@ 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

package.json

@@ -1,7 +1,7 @@
 {
   "name": "cereale",
-  "version": "0.2.0",
-  "description": "Strongly typed JSON mapping and validation for TypeScript classes — validated domain objects, not validated data",
+  "version": "0.1.0",
+  "description": "Spring-like decorators for JSON mapping and validation in TypeScript",
   "type": "module",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -13,10 +13,7 @@
       "require": "./dist/cjs/index.js"
     }
   },
-  "sideEffects": [
-    "./dist/esm/metadata.js",
-    "./dist/cjs/metadata.js"
-  ],
+  "sideEffects": false,
   "files": [
     "dist"
   ],
@@ -42,13 +39,11 @@
   },
   "keywords": [
     "json",
+    "mapping",
     "validation",
     "decorators",
-    "typescript",
-    "zod-alternative",
-    "dto",
-    "serialization",
-    "class-validator"
+    "spring",
+    "typescript"
   ],
   "author": "Avalon Vanguard",
   "license": "MIT",

src/decorators.test.ts

@@ -13,7 +13,7 @@ import {
   ArrayMaxSize, 
   IsNotIn, 
   Validate, 
-  defineRule,
+  registerDecorator,
   JsonType,
   JsonPolymorphic,
   JsonMapper,
@@ -244,14 +244,21 @@ describe('Additional Decorators', () => {
 
   describe('registerDecorator', () => {
     it('should register a custom decorator with functional validator', async () => {
-      class Test {
-        val: number = 0;
-      }
-      defineRule(Test, 'val', {
+      function IsEven() {
+        return function (object: any, propertyName: string) {
+          registerDecorator({
             name: 'isEven',
-        validate: (value: any) => typeof value === 'number' && value % 2 === 0,
-        message: 'val must be even',
+            target: object.constructor,
+            propertyName: propertyName,
+            validator: (value: any) => typeof value === 'number' && value % 2 === 0,
           });
+        };
+      }
+
+      class Test {
+        @IsEven()
+        val: number;
+      }
 
       const t = new Test();
       t.val = 2;
@@ -264,15 +271,19 @@ describe('Additional Decorators', () => {
       class MyValidator implements ValidatorConstraintInterface {
         validate(v: any) { return v === 'ok'; }
       }
-      class Test {
-        val: string = '';
-      }
-      const validator = new MyValidator();
-      defineRule(Test, 'val', {
+      function IsOk() {
+        return function (object: any, propertyName: string) {
+          registerDecorator({
             name: 'isOk',
-        validate: (v: any) => validator.validate(v),
-        message: 'val must be ok',
+            target: object.constructor,
+            propertyName: propertyName,
+            validator: MyValidator,
           });
+        };
+      }
+      class Test {
+        @IsOk() val: string;
+      }
       const t = new Test();
       t.val = 'ok';
       expect(await JsonMapper.validate(t)).toHaveLength(0);

src/example.ts

@@ -25,7 +25,8 @@ import {
   Validate,
   ValidatorConstraintInterface,
   ValidationArguments,
-  Matches,
+  registerDecorator,
+  ValidationOptions
 } from './index.js';
 
 // --- Custom Validators ---
@@ -41,8 +42,17 @@ class IsLongerThan implements ValidatorConstraintInterface {
   }
 }
 
-/** 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' });
+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)
+    });
+  };
+}
 
 // --- Custom Serializers ---
 
@@ -66,14 +76,12 @@ 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()
-  type: string = '';
+  abstract type: string;
 
   // Declared once here. Subclasses inherit the rule without restating it.
   @IsString()
-  title: string = '';
+  title: string;
 }
 
 class Book extends Media {
@@ -103,7 +111,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;
 }
@@ -114,7 +122,7 @@ class Library {
   id: string;
 
   @IsString()
-  @IsSlug()
+  @IsSlug({ message: 'name must be a lowercase slug' })
   name: string;
 
   @JsonProperty('curator_email')
@@ -128,12 +136,11 @@ class Library {
 
   @IsArray()
   @ValidateNested({ each: true })
-  // Naming the base type has the subtype list checked against it.
-  @JsonPolymorphic<Media>('type', [
+  @JsonPolymorphic('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,
-  defineRule, validate, toInstance, toPlain, configure, resetConfig,
+  registerDecorator, validate, toInstance, toPlain, configure, resetConfig,
 } from './index.js';
 
 afterEach(() => resetConfig());
@@ -20,10 +20,11 @@ describe('plan caching', () => {
     expect(await validate(before)).toEqual([]);
 
     // Register a rule after the plan has already been built and cached.
-    defineRule(Late, 'value', {
+    registerDecorator({
       name: 'isEven',
-      validate: (v: any) => typeof v === 'number' && v % 2 === 0,
-      message: 'value must be even',
+      target: Late,
+      propertyName: 'value',
+      validator: (v: any) => typeof v === 'number' && v % 2 === 0,
     });
 
     const after = new Late();
@@ -147,11 +148,11 @@ describe('each: true error reporting', () => {
   it('names the index of the element that failed', async () => {
     class Basket {
       @IsIn(['a', 'b'], { each: true })
-      tags!: ('a' | 'b')[];
+      tags: string[];
     }
 
     const basket = new Basket();
-    basket.tags = ['a', 'b', 'a', 'nope' as 'a', 'b'];
+    basket.tags = ['a', 'b', 'a', 'nope', 'b'];
 
     const errors = await validate(basket);
     expect(errors).toHaveLength(1);
@@ -161,10 +162,10 @@ describe('each: true error reporting', () => {
   it('leaves a caller-supplied message untouched', async () => {
     class Basket {
       @IsIn(['a'], { each: true, message: 'bad tag' })
-      tags!: 'a'[];
+      tags: string[];
     }
     const basket = new Basket();
-    basket.tags = ['a', 'zzz' as 'a'];
+    basket.tags = ['a', 'zzz'];
 
     const errors = await validate(basket);
     expect(errors[0]!.constraints['isIn']).toBe('bad tag');
@@ -173,10 +174,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!: 'a'[];
+      tags: string[];
     }
     const basket = new Basket();
-    basket.tags = ['a', 'zzz' as 'a'];
+    basket.tags = ['a', 'zzz'];
 
     const errors = await validate(basket);
     expect(errors[0]!.constraints['isIn']).toBe('rejected "zzz"');
@@ -185,7 +186,7 @@ describe('each: true error reporting', () => {
   it('reports nothing when every element passes', async () => {
     class Basket {
       @IsIn(['a', 'b'], { each: true })
-      tags!: ('a' | 'b')[];
+      tags: string[];
     }
     const basket = new Basket();
     basket.tags = ['a', 'b'];

src/index.test.ts

@@ -41,18 +41,16 @@ 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()
-  type: string = '';
+  abstract type: string;
 
   @IsString()
-  title: string = '';
+  title: string;
 }
 
 class Book extends Media {
   @IsString()
-  override type: string = 'book';
+  type: string = 'book';
 
   @IsString()
   author: string;
@@ -65,7 +63,7 @@ class Book extends Media {
 
 class Movie extends Media {
   @IsString()
-  override type: string = 'movie';
+  type: string = 'movie';
 
   @IsInt()
   @Min(1)
@@ -164,7 +162,7 @@ describe('JsonMapper', () => {
 
       @ArrayNotEmpty()
       @IsIn(['admin', 'user', 'guest'], { each: true })
-      roles!: ('admin' | 'user' | 'guest')[];
+      roles: string[];
 
       @IsUrl()
       @IsOptional()
@@ -226,7 +224,7 @@ describe('JsonMapper', () => {
       user.username = 'johndoe';
       user.email = 'john@example.com';
       user.active = true;
-      user.roles = ['superadmin' as 'admin'];
+      user.roles = ['superadmin'];
 
       const errors = await JsonMapper.validate(user);
       expect(errors).toHaveLength(1);

src/index.ts

@@ -1,5 +1,4 @@
 export * from './interfaces.js';
-export * from './metadata.js';
 export * from './naming.js';
 export * from './config.js';
 export * from './decorators.js';

src/interfaces.ts

@@ -38,42 +38,3 @@ export interface JsonDeserializer<T = any, R = any> {
 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

@@ -0,0 +1,147 @@
+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

@@ -1,186 +0,0 @@
-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

@@ -21,7 +21,7 @@ describe('regressions', () => {
       }
       class Sub extends Base {
         @IsString()
-        override name: string = '';
+        declare 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()
-        override type: string = '';
+        declare 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!: 'a' | 'b';
+      choice: string;
 
       @JsonWriteOnly()
       @IsString()
       token: string;
     }
     const form = new Form();
-    form.choice = 'zzz' as 'a';
+    form.choice = 'zzz';
     form.token = 'secret-token';
 
     const errors = await validate(form);

src/type-safety.test.ts

@@ -1,175 +0,0 @@
-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,9 +1,6 @@
 import { ClassConstructor } from './interfaces.js';
-import {
-  modelOf, modelOfInstance, modelVersion,
-  type ClassModel, type PropertyAccess, type PropertyModel,
-  type ValidationArguments, type ValidationConstraint,
-} from './metadata.js';
+import { METADATA_KEYS, PropertyAccess, ValidationConstraint, ValidationArguments } from './decorators.js';
+import { metadataStorage } from './metadata-storage.js';
 import { NamingStrategyFn, resolveNamingStrategy } from './naming.js';
 import { TransformOptions, UnknownKeyPolicy, resolveOptions } from './config.js';
 
@@ -65,13 +62,25 @@ interface DeserializeContext {
   maxDepth: number;
 }
 
-function accessOf(model: ClassModel, key: string): PropertyAccess {
-  return model[key]?.access ?? 'readwrite';
+/**
+ * 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';
 }
 
 /** The name this property takes in JSON: an explicit @JsonProperty, else the naming strategy. */
-function outboundName(model: ClassModel, key: string, naming: NamingStrategyFn): string {
-  return model[key]?.name ?? naming(key);
+function outboundName(target: any, key: string, naming: NamingStrategyFn): string {
+  const explicit = target ? metadataStorage.getMetadata(METADATA_KEYS.NAME, target, key) : undefined;
+  return explicit ?? naming(key);
 }
 
 /** Per-property serialization facts, resolved once instead of per call. */
@@ -84,7 +93,7 @@ interface OutboundProperty {
   serializer?: any;
 }
 
-const outboundCache = new WeakMap<ClassModel, { version: number; byStrategy: Map<unknown, Map<string, OutboundProperty>> }>();
+const outboundCache = new WeakMap<object, { version: number; byStrategy: Map<unknown, Map<string, OutboundProperty>> }>();
 
 /**
  * Resolves how one property is written out, memoized per (prototype, naming strategy).
@@ -92,11 +101,16 @@ const outboundCache = new WeakMap<ClassModel, { version: number; byStrategy: Map
  * 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(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);
+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);
   }
 
   let byKey = entry.byStrategy.get(ctx.namingKey);
@@ -107,10 +121,10 @@ function outboundFor(model: ClassModel, key: string, ctx: SerializeContext): Out
 
   let resolved = byKey.get(key);
   if (!resolved) {
-    const access = accessOf(model, key);
-    const serializer = model[key]?.serializer;
+    const access = accessOf(target, key);
+    const serializer = metadataStorage.getMetadata(METADATA_KEYS.SERIALIZER, target, key);
     resolved = {
-      name: outboundName(model, key, ctx.naming),
+      name: outboundName(target, key, ctx.naming),
       // `writeonly` is accepted on input but must never be echoed back out.
       skip: access === 'none' || access === 'writeonly',
       ...(serializer ? { serializer } : {}),
@@ -143,7 +157,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<ClassModel, { version: number; byStrategy: Map<unknown, InboundNames> }>();
+const inboundCache = new WeakMap<object, { version: number; byStrategy: Map<unknown, InboundNames> }>();
 
 /**
  * Builds the JSON-name -> property-key lookup used when reading a payload.
@@ -153,11 +167,11 @@ const inboundCache = new WeakMap<ClassModel, { version: number; byStrategy: Map<
  * property therefore stops the old name from being silently accepted — add `@JsonAlias` to
  * keep it working for older clients.
  */
-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);
+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);
   }
   const cached = entry.byStrategy.get(ctx.namingKey);
   if (cached) return cached;
@@ -177,10 +191,13 @@ function inboundNameMap(model: ClassModel, ctx: DeserializeContext): InboundName
     accept.set(external, key);
   };
 
-  for (const [key, property] of Object.entries(model)) {
-    const names = [outboundName(model, key, ctx.naming), ...(property.aliases ?? [])];
+  for (const key of metadataStorage.getProperties(target)) {
+    const names = [
+      outboundName(target, key, ctx.naming),
+      ...(metadataStorage.getMetadata(METADATA_KEYS.ALIASES, target, key) || []),
+    ];
 
-    const access = accessOf(model, key);
+    const access = accessOf(target, key);
     if (access === 'none' || access === 'readonly') {
       for (const name of names) blocked.add(name);
       continue;
@@ -188,11 +205,14 @@ function inboundNameMap(model: ClassModel, ctx: DeserializeContext): InboundName
 
     for (const name of names) claim(name, key);
 
-    if (property.deserializer || property.polymorphic || property.type) {
+    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) {
       props.set(key, {
-        ...(property.deserializer ? { deserializer: property.deserializer } : {}),
-        ...(property.polymorphic ? { polymorphic: property.polymorphic } : {}),
-        ...(property.type ? { typeFn: property.type } : {}),
+        ...(deserializer ? { deserializer } : {}),
+        ...(polymorphic ? { polymorphic } : {}),
+        ...(typeFn ? { typeFn } : {}),
       });
     }
   }
@@ -275,11 +295,11 @@ function serialize(obj: any, ancestors: Set<any>, ctx: SerializeContext, depth:
       return out;
     }
 
-    const model = modelOfInstance(obj);
+    const target = prototypeOf(obj);
 
     const result: any = {};
     for (const key of Object.keys(obj)) {
-      const property = outboundFor(model, key, ctx);
+      const property = outboundFor(target, key, ctx);
       if (property.skip) continue;
 
       const value = obj[key];
@@ -327,7 +347,8 @@ function deserialize<T>(clazz: ClassConstructor<T>, plain: any, ctx: Deserialize
   if (typeof plain !== 'object') return plain;
 
   const instance = new clazz();
-  const inbound = inboundNameMap(modelOf(clazz), ctx);
+  const target = clazz.prototype;
+  const inbound = inboundNameMap(target, ctx);
 
   for (const incoming of Object.keys(plain)) {
     if (FORBIDDEN_KEYS.has(incoming)) continue;
@@ -407,6 +428,36 @@ 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.
  */
@@ -425,53 +476,33 @@ interface CachedPlan {
   plan: PropertyPlan[];
 }
 
-// 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>();
+// 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>();
 
-/**
- * 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()) {
+function validationPlan(target: any): PropertyPlan[] {
+  const cached = planCache.get(target);
+  if (cached && cached.version === metadataStorage.version) {
     return cached.plan;
   }
 
   const plan: PropertyPlan[] = [];
-  for (const [key, property] of Object.entries(model) as [string, PropertyModel][]) {
-    const access = property.access ?? 'readwrite';
+  for (const key of metadataStorage.getProperties(target)) {
+    const condition = metadataStorage.getMetadata(METADATA_KEYS.CONDITION, target, key);
+    const access = accessOf(target, key);
     plan.push({
       key,
-      constraints: dedupe(property.constraints),
-      isOptional: !!property.optional,
-      isNested: !!property.nested,
+      constraints: collectConstraints(target, key),
+      isOptional: !!metadataStorage.getMetadata(METADATA_KEYS.IS_OPTIONAL, target, key),
+      isNested: !!metadataStorage.getMetadata(METADATA_KEYS.NESTED, target, key),
       redact: access === 'writeonly' || access === 'none',
-      ...(property.condition ? { condition: property.condition } : {}),
+      ...(condition ? { condition } : {}),
     });
   }
 
-  planCache.set(model, { version: modelVersion(), plan });
+  planCache.set(target, { version: metadataStorage.version, plan });
   return plan;
 }
 
@@ -613,7 +644,10 @@ function validateInternal(obj: any, ancestors: Set<any>, depth: number, maxDepth
       return errors;
     }
 
-    for (const property of validationPlan(modelOfInstance(obj))) {
+    const target = prototypeOf(obj);
+    if (!target) return errors;
+
+    for (const property of validationPlan(target)) {
       const key = property.key;
       const value = obj[key];
 

src/validators.test.ts

@@ -11,29 +11,12 @@ import {
   validate, toInstance,
 } from './index.js';
 
-/**
- * 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,
-  });
-
+/** 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[]> {
   class Subject {
     val: any;
   }
-  (Subject as any)[Symbol.metadata] = metadata;
+  decorate(Subject.prototype, 'val');
 
   const subject = new Subject();
   subject.val = value;
@@ -249,9 +232,9 @@ describe('arrays', () => {
 describe('@ValidateIf', () => {
   class Payment {
     @IsIn(['card', 'invoice'])
-    method!: 'card' | 'invoice';
+    method: string;
 
-    @ValidateIf<Payment>(o => o.method === 'card')
+    @ValidateIf(o => o.method === 'card')
     @IsString()
     cardNumber?: string;
   }

tsconfig.json

@@ -8,7 +8,7 @@
     // Environment Settings
     "module": "NodeNext",
     "target": "ES2025",
-    "lib": ["ESNext", "ESNext.Decorators"],
+    "lib": ["ESNext"],
     "types": ["node"],
 
     // Other Outputs
@@ -33,9 +33,7 @@
     "isolatedModules": true,
     "skipLibCheck": 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.
+    "experimentalDecorators": true
   },
   // 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

@@ -1,36 +1,13 @@
 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({
-  plugins: [standardDecorators()],
+  // 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 },
+  },
   test: {
     include: ['src/**/*.test.ts'],
     coverage: {