🔊 feat!: make the three silent failures loud

Every change here answers one question: where does cereale currently fail
without saying so?

**Vite 8 / Vitest 4 drop decorators silently.** Both transform with oxc,
which does not implement the standard decorator transform and does not
report that. `vitest` prints "0 test" beside a bare SyntaxError, and
`vite build` reports success while emitting a bundle that throws on first
import. Ship the plugin that fixes it as `cereale/vite`, transforming with
esbuild and falling back to tsc — cereale depends on neither. The library's
own suite now runs through it, so it is exercised by every test.

**Legacy decorators died opaquely.** With `experimentalDecorators: true`,
still the default in most existing TypeScript projects, decorators are
invoked as (prototype, "name") and cereale raised "TypeError: Cannot convert
undefined or null to object". All decorators now resolve metadata through
one checkpoint that names the tsconfig setting instead, and reject
application to a method, getter or accessor field.

**Values JSON cannot carry were emptied.** A populated Map serialized to
{}, a Uint8Array to index-keyed noise, a bigint straight through so the
caller's own JSON.stringify threw somewhere unrelated. All now raise
JsonMappingError naming the property path and both ways out. Covers what a
@JsonSerialize serializer returns, sync or async. Circular-reference and
depth errors name the path too.

Also fixed: defineRule on a subclass with no decorators of its own wrote
the rule into its base class, because the base's metadata object is
inherited through the static prototype chain and `??=` found it non-nullish.

The README's toolchain table (tsc, esbuild, swc ✅, oxc ❌) is now executed
by a test rather than asserted, and the positioning leads with
class-validator + class-transformer, the stack cereale actually replaces,
rather than Zod, which it deliberately is not.

193 -> 249 tests.

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

src/decorators.ts

@@ -2,7 +2,7 @@ import type {
   ClassConstructor, FieldDecorator, JsonDeserializer, JsonSerializer,
 } from './interfaces.js';
 import {
-  addConstraint, propertyModel,
+  addConstraint, fieldMetadata, propertyModel,
   type EachValidationOptions, type PolymorphicInfo, type ValidationArguments,
   type ValidationConstraint, type ValidationOptions, type ValidatorConstraintInterface,
 } from './metadata.js';
@@ -35,7 +35,7 @@ function decorate(
 ): FieldDecorator<unknown> {
   return ((_target: undefined, context: ClassFieldDecoratorContext) => {
     const property = String(context.name);
-    addConstraint(context.metadata, property, build(property), options);
+    addConstraint(fieldMetadata(context), property, build(property), options);
   }) as FieldDecorator<unknown>;
 }
 
@@ -72,7 +72,7 @@ function pattern(name: string, regex: RegExp, message: (property: string) => str
  */
 export function JsonProperty(name: string): FieldDecorator<unknown> {
   return ((_t: undefined, context: ClassFieldDecoratorContext) => {
-    propertyModel(context.metadata, String(context.name)).name = name;
+    propertyModel(fieldMetadata(context), String(context.name)).name = name;
   }) as FieldDecorator<unknown>;
 }
 
@@ -84,14 +84,14 @@ export function JsonProperty(name: string): FieldDecorator<unknown> {
  */
 export function JsonAlias(...names: string[]): FieldDecorator<unknown> {
   return ((_t: undefined, context: ClassFieldDecoratorContext) => {
-    const model = propertyModel(context.metadata, String(context.name));
+    const model = propertyModel(fieldMetadata(context), String(context.name));
     model.aliases = [...(model.aliases ?? []), ...names];
   }) as FieldDecorator<unknown>;
 }
 
 function access(value: 'none' | 'readonly' | 'writeonly'): FieldDecorator<unknown> {
   return ((_t: undefined, context: ClassFieldDecoratorContext) => {
-    propertyModel(context.metadata, String(context.name)).access = value;
+    propertyModel(fieldMetadata(context), String(context.name)).access = value;
   }) as FieldDecorator<unknown>;
 }
 
@@ -123,7 +123,7 @@ export function JsonSerialize<T>(
   serializer: ClassConstructor<JsonSerializer<T, any>>
 ): FieldDecorator<T | null | undefined> {
   return ((_t: undefined, context: ClassFieldDecoratorContext) => {
-    propertyModel(context.metadata, String(context.name)).serializer = serializer;
+    propertyModel(fieldMetadata(context), String(context.name)).serializer = serializer;
   }) as FieldDecorator<T | null | undefined>;
 }
 
@@ -137,7 +137,7 @@ export function JsonDeserialize<R>(
   deserializer: ClassConstructor<JsonDeserializer<any, R>>
 ): FieldDecorator<R | null | undefined> {
   return ((_t: undefined, context: ClassFieldDecoratorContext) => {
-    propertyModel(context.metadata, String(context.name)).deserializer = deserializer;
+    propertyModel(fieldMetadata(context), String(context.name)).deserializer = deserializer;
   }) as FieldDecorator<R | null | undefined>;
 }
 
@@ -151,7 +151,7 @@ export function JsonType<T extends object>(
   typeFunction: () => ClassConstructor<T>
 ): FieldDecorator<T | readonly T[] | null | undefined> {
   return ((_t: undefined, context: ClassFieldDecoratorContext) => {
-    propertyModel(context.metadata, String(context.name)).type = typeFunction;
+    propertyModel(fieldMetadata(context), String(context.name)).type = typeFunction;
   }) as FieldDecorator<T | readonly T[] | null | undefined>;
 }
 
@@ -194,7 +194,7 @@ export function JsonPolymorphic<Base extends object = object>(
       onUnknown: options?.onUnknown ?? 'keep',
       ...(options?.fallback ? { fallback: options.fallback as ClassConstructor<any> } : {}),
     };
-    propertyModel(context.metadata, String(context.name)).polymorphic = info;
+    propertyModel(fieldMetadata(context), String(context.name)).polymorphic = info;
   }) as FieldDecorator<Base | readonly Base[] | null | undefined>;
 }
 
@@ -205,7 +205,7 @@ export function JsonPolymorphic<Base extends object = object>(
 /** Skips every other rule on this field when the value is `null` or `undefined`. */
 export function IsOptional(): FieldDecorator<unknown> {
   return ((_t: undefined, context: ClassFieldDecoratorContext) => {
-    propertyModel(context.metadata, String(context.name)).optional = true;
+    propertyModel(fieldMetadata(context), String(context.name)).optional = true;
   }) as FieldDecorator<unknown>;
 }
 
@@ -221,7 +221,7 @@ export function IsOptional(): FieldDecorator<unknown> {
  */
 export function ValidateIf<This>(condition: (object: This) => boolean): FieldDecorator<unknown> {
   return ((_t: undefined, context: ClassFieldDecoratorContext) => {
-    propertyModel(context.metadata, String(context.name)).condition = condition as (o: any) => boolean;
+    propertyModel(fieldMetadata(context), String(context.name)).condition = condition as (o: any) => boolean;
   }) as FieldDecorator<unknown>;
 }
 
@@ -233,7 +233,7 @@ export function ValidateIf<This>(condition: (object: This) => boolean): FieldDec
  */
 export function Allow(): FieldDecorator<unknown> {
   return ((_t: undefined, context: ClassFieldDecoratorContext) => {
-    propertyModel(context.metadata, String(context.name));
+    propertyModel(fieldMetadata(context), String(context.name));
   }) as FieldDecorator<unknown>;
 }
 
@@ -244,10 +244,11 @@ export function Allow(): FieldDecorator<unknown> {
  */
 export function ValidateNested(options?: ValidationOptions): FieldDecorator<object | readonly unknown[] | null | undefined> {
   return ((_t: undefined, context: ClassFieldDecoratorContext) => {
+    const metadata = fieldMetadata(context);
     const property = String(context.name);
-    propertyModel(context.metadata, property).nested = true;
+    propertyModel(metadata, property).nested = true;
     if (options?.each) {
-      addConstraint(context.metadata, property, {
+      addConstraint(metadata, property, {
         name: 'nestedEach',
         validate: v => Array.isArray(v),
         message: `${property} must be an array`,

src/hardening.test.ts

@@ -219,3 +219,44 @@ describe('validate() accepts options', () => {
     expect(await validate(order)).toHaveLength(1);
   });
 });
+
+describe('decorator context guards', () => {
+  // Every decorator resolves its metadata through one checkpoint, so one representative
+  // decorator per shape is enough to cover the rule.
+  const shapes: [string, unknown][] = [
+    ['a method', { kind: 'method', name: 'run', metadata: {} }],
+    ['a getter', { kind: 'getter', name: 'total', metadata: {} }],
+    ['an accessor', { kind: 'accessor', name: 'value', metadata: {} }],
+    ['a class', { kind: 'class', name: 'Thing', metadata: {} }],
+  ];
+
+  for (const [label, context] of shapes) {
+    it(`refuses being applied to ${label}`, () => {
+      expect(() => (IsString() as any)(undefined, context)).toThrow(/apply to fields/);
+    });
+  }
+
+  it('explains why `accessor` in particular cannot work', () => {
+    const context = { kind: 'accessor', name: 'value', metadata: {} };
+    expect(() => (IsString() as any)(undefined, context)).toThrow(/private slot/);
+  });
+
+  it('refuses a legacy decorator call shape', () => {
+    // What `experimentalDecorators: true` emits: (prototype, propertyKey).
+    expect(() => (IsString() as any)({}, 'name')).toThrow(/experimentalDecorators/);
+  });
+
+  it('refuses a standard context that carries no metadata', () => {
+    const context = { kind: 'field', name: 'value', metadata: undefined };
+    expect(() => (IsString() as any)(undefined, context)).toThrow(/no metadata object/);
+  });
+
+  it('names the field it could not record', () => {
+    const context = { kind: 'field', name: 'nickname', metadata: null };
+    expect(() => (IsString() as any)(undefined, context)).toThrow(/"nickname"/);
+  });
+
+  it('guards the mapping decorators too, not just the rules', () => {
+    expect(() => (JsonSerialize(class {} as any) as any)({}, 'name')).toThrow(/experimentalDecorators/);
+  });
+});

src/metadata.ts

@@ -126,6 +126,58 @@ function ownModel(metadata: DecoratorMetadata): ClassModel {
   return (metadata as Record<symbol, ClassModel>)[MODEL]!;
 }
 
+/**
+ * Validates a decorator context and returns the metadata object to record into.
+ *
+ * Every decorator goes through here rather than reading `context.metadata` directly, because
+ * each of the three failures below is a configuration mistake with a one-line fix, and the
+ * error you get without the check — `TypeError: Cannot convert undefined or null to object`,
+ * raised somewhere inside cereale — points at none of them.
+ *
+ * Typed as `unknown` deliberately: the whole point is to inspect a context that may not have
+ * the shape the type says it has, because it came from the wrong decorator transform.
+ */
+export function fieldMetadata(context: unknown): DecoratorMetadata {
+  const ctx = context as { kind?: unknown; name?: unknown; metadata?: unknown } | null | undefined;
+
+  // A legacy (`experimentalDecorators: true`) field decorator is invoked as
+  // `(prototype, "propertyName")`, so the second argument is a string, not a context object.
+  if (typeof ctx !== 'object' || ctx === null || typeof ctx.kind !== 'string') {
+    throw new TypeError(
+      'cereale needs TC39 standard decorators, but the compiler emitted legacy ones. ' +
+      'Set "experimentalDecorators": false in tsconfig.json (and drop "emitDecoratorMetadata"). ' +
+      'The two decorator systems cannot coexist in one program, so a project that still needs ' +
+      'legacy decorators for another library cannot use cereale yet.'
+    );
+  }
+
+  if (ctx.kind !== 'field') {
+    throw new TypeError(
+      `cereale decorators apply to fields, but this one was applied to a ${ctx.kind}.` +
+      (ctx.kind === 'accessor'
+        ? ' An `accessor` field keeps its value in a private slot that mapping and validation ' +
+          'cannot reach — declare it as a plain field instead.'
+        : '')
+    );
+  }
+
+  // Standard decorators are specified to always carry a metadata object, but the emitted
+  // helpers create it conditionally: tsc writes `Symbol.metadata ? Object.create(...) : void 0`.
+  // Importing cereale installs the `Symbol.metadata` fallback, so this only fires if the
+  // decorated class somehow evaluates first.
+  if (typeof ctx.metadata !== 'object' || ctx.metadata === null) {
+    throw new TypeError(
+      `The decorator context for "${String(ctx.name)}" carries no metadata object, so cereale ` +
+      'has nowhere to record the rule. The compiler emitted its decorator helpers without ' +
+      'metadata support: make sure cereale is imported before the decorated class is evaluated ' +
+      '(importing it installs the Symbol.metadata fallback) and that the build targets ES2022 ' +
+      'or later.'
+    );
+  }
+
+  return ctx.metadata as DecoratorMetadata;
+}
+
 /** Returns (creating if needed) the model entry for one field. */
 export function propertyModel(metadata: DecoratorMetadata, property: string): PropertyModel {
   version++;
@@ -181,6 +233,13 @@ export function defineRule<T>(
   options?: ValidationOptions
 ): void {
   const holder = clazz as unknown as Record<symbol, DecoratorMetadata | undefined>;
-  holder[METADATA_KEY] ??= Object.create(null) as DecoratorMetadata;
+  // `hasOwn`, not `??=`: a subclass with no decorators of its own *inherits* its base's
+  // metadata object through the static side of the prototype chain, and `??=` would find it
+  // non-nullish and write the rule straight into the base. Creating an own object that
+  // prototype-chains to the inherited one is what the decorator transform itself does, and it
+  // is what lets `ownModel` copy-on-write the base's rules instead of mutating them.
+  if (!Object.hasOwn(holder, METADATA_KEY)) {
+    holder[METADATA_KEY] = Object.create(holder[METADATA_KEY] ?? null) as DecoratorMetadata;
+  }
   addConstraint(holder[METADATA_KEY]!, property, constraint, options);
 }

src/representable.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect } from 'vitest';
+import {
+  IsString, JsonIgnore, JsonSerialize, JsonSerializer, JsonMappingError,
+  toPlain, toPlainSync, defineRule, modelOf, validateSync,
+} from './index.js';
+
+/**
+ * Before 0.3.0 every case in this file produced `{}` (or index-keyed noise, or a bigint that
+ * made the caller's own `JSON.stringify` throw somewhere unrelated) with nothing logged and
+ * no error raised. A mapping layer that loses data quietly is worse than one that stops.
+ */
+describe('values JSON cannot carry', () => {
+  class Basket {
+    // Typed loosely on purpose: the point is what happens at runtime, and the decorators are
+    // deliberately absent so nothing is claiming to handle these.
+    items: any;
+  }
+
+  const withItems = (items: unknown) => Object.assign(new Basket(), { items });
+
+  const cases: [string, unknown, RegExp][] = [
+    ['a Map', new Map([['a', 1]]), /is a Map/],
+    ['a Set', new Set([1, 2]), /is a Set/],
+    ['a WeakMap', new WeakMap(), /is a WeakMap/],
+    ['a WeakSet', new WeakSet(), /is a WeakSet/],
+    ['a Promise', Promise.resolve(1), /is a Promise/],
+    ['a RegExp', /abc/g, /is a RegExp/],
+    ['an Error', new Error('boom'), /is an Error/],
+    ['a TypeError', new TypeError('boom'), /is an Error/],
+    ['an ArrayBuffer', new ArrayBuffer(8), /is an ArrayBuffer/],
+    ['a DataView', new DataView(new ArrayBuffer(8)), /is a DataView/],
+    ['a Uint8Array', new Uint8Array([1, 2, 3]), /is a Uint8Array/],
+    ['a Float64Array', new Float64Array([1.5]), /is a Float64Array/],
+    ['a bigint', 10n, /is a bigint/],
+    ['a symbol', Symbol('x'), /is a symbol/],
+    ['a function', () => 1, /is a function/],
+  ];
+
+  for (const [label, value, expected] of cases) {
+    it(`refuses ${label}`, () => {
+      expect(() => toPlainSync(withItems(value), { validate: false })).toThrow(JsonMappingError);
+      expect(() => toPlainSync(withItems(value), { validate: false })).toThrow(expected);
+    });
+  }
+
+  it('names the property in the message and points at the way out', () => {
+    expect(() => toPlainSync(withItems(new Map()), { validate: false }))
+      .toThrow(/items is a Map.*@JsonSerialize\(\).*@JsonIgnore\(\)/s);
+  });
+
+  it('names the full path through nested objects and arrays', () => {
+    class Line { tags: any }
+    class Order { lines: any }
+    const order = Object.assign(new Order(), {
+      lines: [Object.assign(new Line(), { tags: [] }), Object.assign(new Line(), { tags: [new Set(['a'])] })],
+    });
+
+    expect(() => toPlainSync(order, { validate: false })).toThrow(/lines\[1\]\.tags\[0\] is a Set/);
+  });
+
+  it('reports the root when the offending value is the argument itself', () => {
+    expect(() => toPlainSync(new Map(), { validate: false })).toThrow(/the value passed in is a Map/);
+  });
+
+  it('still allows the built-ins that do map cleanly', () => {
+    class Fine {
+      when = new Date('2024-01-01T00:00:00.000Z');
+      list = [1, 'two', true, null];
+      nested = { deep: { deeper: [{ ok: true }] } };
+      empty = {};
+    }
+
+    expect(toPlainSync(new Fine(), { validate: false })).toEqual({
+      when: '2024-01-01T00:00:00.000Z',
+      list: [1, 'two', true, null],
+      nested: { deep: { deeper: [{ ok: true }] } },
+      empty: {},
+    });
+  });
+
+  it('accepts a Map once a serializer converts it', () => {
+    class TagsSerializer implements JsonSerializer<Map<string, number>, Record<string, number>> {
+      serialize(value: Map<string, number>) { return Object.fromEntries(value); }
+    }
+
+    class Post {
+      @JsonSerialize(TagsSerializer)
+      tags!: Map<string, number>;
+    }
+
+    const post = new Post();
+    post.tags = new Map([['a', 1], ['b', 2]]);
+    expect(toPlainSync(post, { validate: false })).toEqual({ tags: { a: 1, b: 2 } });
+  });
+
+  it('accepts a Map once the property is ignored', () => {
+    class Cache {
+      @IsString() name = 'x';
+      @JsonIgnore() entries = new Map([['a', 1]]);
+    }
+
+    expect(toPlainSync(new Cache(), { validate: false })).toEqual({ name: 'x' });
+  });
+
+  it('refuses a serializer that hands back something unrepresentable', () => {
+    class BadSerializer implements JsonSerializer<string, unknown> {
+      serialize() { return new Set(['still a Set']); }
+    }
+
+    class Thing {
+      @JsonSerialize(BadSerializer)
+      label!: string;
+    }
+
+    const thing = new Thing();
+    thing.label = 'x';
+    expect(() => toPlainSync(thing, { validate: false })).toThrow(/label is a Set/);
+  });
+
+  it('refuses an async serializer that resolves to something unrepresentable', async () => {
+    class SlowBadSerializer implements JsonSerializer<string, unknown> {
+      async serialize() { return new Map([['a', 1]]); }
+    }
+
+    class Thing {
+      @JsonSerialize(SlowBadSerializer)
+      label!: string;
+    }
+
+    const thing = new Thing();
+    thing.label = 'x';
+    await expect(toPlain(thing, { validate: false })).rejects.toThrow(/label is a Map/);
+  });
+});
+
+describe('serialization error paths', () => {
+  it('names where the cycle was found', () => {
+    class Node { name = 'root'; child: any = null; parent: any = null }
+    const root = new Node();
+    const child = new Node();
+    child.name = 'child';
+    child.parent = root;
+    root.child = child;
+
+    expect(() => toPlainSync(root, { validate: false })).toThrow(/at child\.parent/);
+  });
+
+  it('names where the depth limit was hit', () => {
+    class Deep { next: any = null }
+    const root = new Deep();
+    let tip = root;
+    for (let i = 0; i < 5; i++) {
+      tip.next = new Deep();
+      tip = tip.next;
+    }
+
+    expect(() => toPlainSync(root, { validate: false, maxDepth: 3 }))
+      .toThrow(/exceeded while serializing at next\.next\.next/);
+  });
+});
+
+describe('defineRule', () => {
+  // `??=` on an inherited static symbol property finds the base class's metadata object and
+  // never creates an own one, so the rule lands on the base and every sibling inherits it.
+  it('does not write a subclass rule into its base class', () => {
+    class Base {
+      @IsString() name!: string;
+    }
+    class Sub extends Base { extra!: string }
+    class Sibling extends Base { }
+
+    defineRule(Sub, 'extra', {
+      name: 'isShouty',
+      validate: (v: any) => typeof v === 'string' && v === v.toUpperCase(),
+      message: 'extra must be upper case',
+    });
+
+    expect(Object.keys(modelOf(Sub)).sort()).toEqual(['extra', 'name']);
+    expect(Object.keys(modelOf(Base))).toEqual(['name']);
+    expect(Object.keys(modelOf(Sibling))).toEqual(['name']);
+
+    const sibling = Object.assign(new Sibling(), { name: 'ok' });
+    expect(validateSync(sibling)).toEqual([]);
+  });
+});

src/toolchain.test.ts

@@ -0,0 +1,184 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import ts from 'typescript';
+import { transform } from 'esbuild';
+import { transform as swcTransform } from '@swc/core';
+
+import { IsString, modelOf } from './index.js';
+import { standardDecorators } from './vite.js';
+
+/**
+ * The support matrix in the README, executed.
+ *
+ * cereale reads `context.metadata`, which only exists if the compiler emitted TC39 standard
+ * decorators — so which compiler a consumer uses, and how it is configured, decides whether
+ * the library works at all. Claiming that in prose is not worth much; each row below actually
+ * compiles a decorated class with the tool in question and checks the metadata arrived.
+ *
+ * The one row that cannot run here is oxc, the transformer Vite 8 and Vitest 4 use, because it
+ * ships inside a native binary with no standalone transform API. Its behaviour is why
+ * `cereale/vite` exists, and the plugin is covered further down.
+ */
+const PROBE = `
+const Rule = globalThis.__cerealeProbeRule;
+
+export class Probe {
+  @Rule() name;
+}
+`;
+
+/** Compiler options a consumer needs for cereale to work. */
+const STANDARD = { experimentalDecorators: false, useDefineForClassFields: true };
+/** What most existing TypeScript projects still have, because class-validator required it. */
+const LEGACY = { experimentalDecorators: true, useDefineForClassFields: false };
+
+const emit = {
+  tsc(source: string, options: typeof STANDARD): string {
+    return ts.transpileModule(source, {
+      compilerOptions: {
+        target: ts.ScriptTarget.ES2022,
+        module: ts.ModuleKind.ESNext,
+        ...options,
+      },
+    }).outputText;
+  },
+  async esbuild(source: string, options: typeof STANDARD): Promise<string> {
+    const result = await transform(source, {
+      loader: 'ts',
+      target: 'es2022',
+      tsconfigRaw: { compilerOptions: options },
+    });
+    return result.code;
+  },
+  async swc(source: string, options: typeof STANDARD): Promise<string> {
+    const result = await swcTransform(source, {
+      filename: 'probe.ts',
+      jsc: {
+        parser: { syntax: 'typescript', decorators: true },
+        target: 'es2022',
+        // swc spells the choice as a proposal date rather than a boolean.
+        transform: { decoratorVersion: options.experimentalDecorators ? '2021-12' : '2022-03' },
+      },
+      module: { type: 'es6' },
+    });
+    return result.code;
+  },
+};
+
+let workspace: string;
+let counter = 0;
+
+beforeAll(async () => {
+  workspace = await mkdtemp(path.join(tmpdir(), 'cereale-toolchain-'));
+  // The emitted probe reaches the decorator through a global rather than an import, so that
+  // it needs no module resolution back into a package that has not been built yet.
+  (globalThis as Record<string, unknown>).__cerealeProbeRule = IsString;
+});
+
+afterAll(async () => {
+  delete (globalThis as Record<string, unknown>).__cerealeProbeRule;
+  await rm(workspace, { recursive: true, force: true });
+});
+
+/** Writes emitted JavaScript to disk and imports it, the way a consumer's runtime would. */
+async function load(code: string): Promise<{ Probe: unknown }> {
+  const file = path.join(workspace, `probe-${counter++}.mjs`);
+  await writeFile(file, code);
+  return import(pathToFileURL(file).href) as Promise<{ Probe: unknown }>;
+}
+
+describe('compilers that emit standard decorators', () => {
+  it('tsc records the rule', async () => {
+    const { Probe } = await load(emit.tsc(PROBE, STANDARD));
+    expect(Object.keys(modelOf(Probe))).toEqual(['name']);
+  });
+
+  it('esbuild records the rule', async () => {
+    const { Probe } = await load(await emit.esbuild(PROBE, STANDARD));
+    expect(Object.keys(modelOf(Probe))).toEqual(['name']);
+  });
+
+  it('swc records the rule', async () => {
+    const { Probe } = await load(await emit.swc(PROBE, STANDARD));
+    expect(Object.keys(modelOf(Probe))).toEqual(['name']);
+  });
+});
+
+describe('compilers configured for legacy decorators', () => {
+  // Left unguarded, both of these die inside cereale with `TypeError: Cannot convert undefined
+  // or null to object`, which names neither the cause nor the setting that fixes it.
+  it('tsc emit is refused by name', async () => {
+    await expect(load(emit.tsc(PROBE, LEGACY))).rejects.toThrow(/experimentalDecorators/);
+  });
+
+  it('esbuild emit is refused by name', async () => {
+    await expect(load(await emit.esbuild(PROBE, LEGACY))).rejects.toThrow(/experimentalDecorators/);
+  });
+
+  it('swc emit is refused by name', async () => {
+    await expect(load(await emit.swc(PROBE, LEGACY))).rejects.toThrow(/experimentalDecorators/);
+  });
+});
+
+describe('cereale/vite', () => {
+  const plugin = (options?: Parameters<typeof standardDecorators>[0]) => standardDecorators(options);
+
+  it('lowers decorator syntax that oxc would pass through untouched', async () => {
+    const result = await plugin().transform(PROBE, '/app/src/model.ts');
+    expect(result).not.toBeNull();
+    expect(result!.code).not.toMatch(/@Rule\(\)/);
+
+    const { Probe } = await load(result!.code);
+    expect(Object.keys(modelOf(Probe))).toEqual(['name']);
+  });
+
+  it('produces working output through the TypeScript compiler too', async () => {
+    const result = await plugin({ transformer: 'typescript' }).transform(PROBE, '/app/src/model.ts');
+    const { Probe } = await load(result!.code);
+    expect(Object.keys(modelOf(Probe))).toEqual(['name']);
+  });
+
+  it('emits a source map', async () => {
+    const result = await plugin().transform(PROBE, '/app/src/model.ts');
+    expect(result!.map).toBeTruthy();
+  });
+
+  // tsc appends one pointing at a file that was never written; Vite follows it and logs a
+  // failure to read the map for every transformed module.
+  it('does not leave a sourceMappingURL comment behind', async () => {
+    for (const transformer of ['esbuild', 'typescript'] as const) {
+      const result = await plugin({ transformer }).transform(PROBE, '/app/src/model.ts');
+      expect(result!.code, transformer).not.toMatch(/sourceMappingURL/);
+    }
+  });
+
+  for (const id of ['/app/src/model.ts', '/app/src/model.mts', '/app/src/model.cts', '/app/src/model.ts?v=123']) {
+    it(`transforms ${id}`, async () => {
+      expect(await plugin().transform(PROBE, id)).not.toBeNull();
+    });
+  }
+
+  for (const id of ['/app/node_modules/dep/model.ts', '/app/src/model.js', '/app/src/model.tsx', '/app/src/style.css']) {
+    it(`leaves ${id} alone`, async () => {
+      expect(await plugin().transform(PROBE, id)).toBeNull();
+    });
+  }
+
+  it('honours a caller-supplied include', async () => {
+    const onlyModels = plugin({ include: id => id.includes('/models/') });
+    expect(await onlyModels.transform(PROBE, '/app/src/models/user.ts')).not.toBeNull();
+    expect(await onlyModels.transform(PROBE, '/app/src/routes/user.ts')).toBeNull();
+  });
+
+  it('runs before Vite’s own transform', () => {
+    expect(plugin().enforce).toBe('pre');
+  });
+
+  it('rejects a target the compiler does not know', async () => {
+    const bad = plugin({ transformer: 'typescript', target: 'es1999' });
+    await expect(bad.transform(PROBE, '/app/src/model.ts')).rejects.toThrow(/es1999/);
+  });
+});

src/utils.ts

@@ -242,14 +242,113 @@ function refuseAsync(deferred: Deferred, operation: string, asyncName: string):
   );
 }
 
-function serialize(obj: any, ancestors: Set<any>, ctx: SerializeContext, depth: number, deferred: Deferred): any {
-  if (obj === null || obj === undefined || typeof obj !== 'object') {
+/**
+ * Values that carry their data in internal slots rather than in own enumerable properties.
+ *
+ * Walking one of these with `Object.keys` yields `{}` — a populated `Map` becomes an empty
+ * object and nothing anywhere says so. Keyed by `Symbol.toStringTag`, which every one of them
+ * defines on its prototype, so the lookup costs a single property read and still recognises
+ * instances that came from another realm.
+ */
+const UNREPRESENTABLE: Record<string, string> = {
+  Map: 'a Map',
+  Set: 'a Set',
+  WeakMap: 'a WeakMap',
+  WeakSet: 'a WeakSet',
+  WeakRef: 'a WeakRef',
+  Promise: 'a Promise',
+  ArrayBuffer: 'an ArrayBuffer',
+  SharedArrayBuffer: 'a SharedArrayBuffer',
+  DataView: 'a DataView',
+  Generator: 'a generator',
+  AsyncGenerator: 'an async generator',
+};
+
+/**
+ * Describes why a value cannot be represented in JSON, or returns null if it can.
+ *
+ * The alternative to raising this is what the engine used to do: emit `{}` for a `Map`,
+ * index-keyed noise for a `Uint8Array`, and a bigint that makes the caller's own
+ * `JSON.stringify` throw somewhere else entirely. This library's position is that silent
+ * success is the worst failure mode a mapping layer can have, and that has to include its own.
+ */
+function unrepresentableObject(value: object): string | null {
+  const tag = (value as Record<symbol, unknown>)[Symbol.toStringTag];
+  if (typeof tag === 'string') {
+    const known = UNREPRESENTABLE[tag];
+    if (known !== undefined) return known;
+    // Typed arrays are tagged with their own name and would serialize to `{"0":…,"1":…}`.
+    if (ArrayBuffer.isView(value)) return `a ${tag}`;
+  }
+
+  // RegExp and Error get their `Object.prototype.toString` tag from a spec special case
+  // rather than from `Symbol.toStringTag`, so neither is caught above.
+  if (value instanceof RegExp) return 'a RegExp';
+  if (value instanceof Error) return 'an Error, whose message and stack are not enumerable';
+
+  return null;
+}
+
+const BIGINT_REASON = 'a bigint, which JSON has no representation for';
+
+/** The same question for a value of any type. `serialize` inlines the primitive half. */
+function unrepresentable(value: unknown): string | null {
+  switch (typeof value) {
+    case 'bigint': return BIGINT_REASON;
+    case 'symbol': return 'a symbol';
+    case 'function': return 'a function';
+    case 'object': return value === null ? null : unrepresentableObject(value);
+    default: return null;
+  }
+}
+
+/**
+ * The trail of keys walked to reach a value: property names as strings, array positions as
+ * numbers. Numbers are kept unformatted so that walking an array costs no string building.
+ */
+type Path = (string | number)[];
+
+/** Renders a {@link Path} for error messages. */
+function describePath(path: readonly (string | number)[]): string {
+  if (path.length === 0) return 'the value passed in';
+  let out = '';
+  for (const segment of path) {
+    if (typeof segment === 'number') out += `[${segment}]`;
+    else out += out === '' ? segment : `.${segment}`;
+  }
+  return out;
+}
+
+function refuseUnrepresentable(why: string, path: readonly (string | number)[]): never {
+  throw new JsonMappingError(
+    `${describePath(path)} is ${why}, which cannot be serialized to JSON. ` +
+    'Give the property a @JsonSerialize() serializer that converts it, or drop it from the ' +
+    'output with @JsonIgnore().'
+  );
+}
+
+/**
+ * @param path The keys walked to reach `obj`, kept as a stack so that errors can name the
+ * offending property. Pushed and popped rather than concatenated, so the bookkeeping costs
+ * no string building on the way down.
+ */
+function serialize(obj: any, ancestors: Set<any>, ctx: SerializeContext, depth: number, deferred: Deferred, path: Path): any {
+  if (obj === null || obj === undefined) return obj;
+
+  // Primitives dominate the walk, so their check is inline: one `typeof` and, for the three
+  // types JSON cannot carry, a throw. Everything else defers to `unrepresentableObject`,
+  // which is only reached once per object and skipped entirely for arrays and dates.
+  const type = typeof obj;
+  if (type !== 'object') {
+    if (type === 'bigint') refuseUnrepresentable(BIGINT_REASON, path);
+    if (type === 'symbol') refuseUnrepresentable('a symbol', path);
+    if (type === 'function') refuseUnrepresentable('a function', path);
     return obj;
   }
 
   if (depth > ctx.maxDepth) {
     throw new JsonMappingError(
-      `Maximum nesting depth of ${ctx.maxDepth} exceeded while serializing. ` +
+      `Maximum nesting depth of ${ctx.maxDepth} exceeded while serializing at ${describePath(path)}. ` +
       `Raise it with the maxDepth option if this structure is legitimate.`
     );
   }
@@ -258,19 +357,28 @@ function serialize(obj: any, ancestors: Set<any>, ctx: SerializeContext, depth:
     return obj.toISOString();
   }
 
+  const isArray = Array.isArray(obj);
+  if (!isArray) {
+    const why = unrepresentableObject(obj);
+    if (why !== null) refuseUnrepresentable(why, path);
+  }
+
   if (ancestors.has(obj)) {
     throw new JsonMappingError(
-      'Circular reference detected during serialization. Break the cycle with @JsonIgnore() ' +
-      'on the back-reference, or supply a @JsonSerialize() serializer for that property.'
+      `Circular reference detected during serialization at ${describePath(path)}. Break the cycle ` +
+      'with @JsonIgnore() on the back-reference, or supply a @JsonSerialize() serializer for ' +
+      'that property.'
     );
   }
 
   ancestors.add(obj);
   try {
-    if (Array.isArray(obj)) {
+    if (isArray) {
       const out: any[] = [];
-      for (const item of obj) {
-        out.push(serialize(item, ancestors, ctx, depth + 1, deferred));
+      for (let index = 0; index < obj.length; index++) {
+        path.push(index);
+        out.push(serialize(obj[index], ancestors, ctx, depth + 1, deferred, path));
+        path.pop();
       }
       return out;
     }
@@ -283,6 +391,7 @@ function serialize(obj: any, ancestors: Set<any>, ctx: SerializeContext, depth:
       if (property.skip) continue;
 
       const value = obj[key];
+      path.push(key);
 
       // Custom serializers only see real values. Handing a serializer `undefined` for a
       // property that was simply never set turns an optional field into a crash.
@@ -292,14 +401,24 @@ function serialize(obj: any, ancestors: Set<any>, ctx: SerializeContext, depth:
           const slot = property.name;
           // Claim the key now so the deferred write lands in declaration order rather than
           // being appended after every synchronous property.
+          const where = [...path];
           result[slot] = undefined;
-          deferred.push(produced.then((settled: any) => { result[slot] = settled; }));
+          deferred.push(produced.then((settled: any) => {
+            const bad = unrepresentable(settled);
+            if (bad !== null) refuseUnrepresentable(bad, where);
+            result[slot] = settled;
+          }));
         } else {
+          // A serializer that hands back a Map is the same silent `{}` by another route.
+          const bad = unrepresentable(produced);
+          if (bad !== null) refuseUnrepresentable(bad, path);
           result[property.name] = produced;
         }
       } else {
-        result[property.name] = serialize(value, ancestors, ctx, depth + 1, deferred);
+        result[property.name] = serialize(value, ancestors, ctx, depth + 1, deferred, path);
       }
+
+      path.pop();
     }
 
     return result;
@@ -795,7 +914,7 @@ export async function toPlain<T>(obj: T, options?: TransformOptions): Promise<an
   }
 
   const deferred: Deferred = [];
-  const plain = serialize(obj, new Set(), serializeContext(options), 0, deferred);
+  const plain = serialize(obj, new Set(), serializeContext(options), 0, deferred, []);
   await settle(deferred);
   return plain;
 }
@@ -816,7 +935,7 @@ export function toPlainSync<T>(obj: T, options?: TransformOptions): any {
   }
 
   const deferred: Deferred = [];
-  const plain = serialize(obj, new Set(), serializeContext(options), 0, deferred);
+  const plain = serialize(obj, new Set(), serializeContext(options), 0, deferred, []);
   refuseAsync(deferred, 'toPlainSync()', 'toPlain()');
   return plain;
 }

src/vite.ts

@@ -0,0 +1,175 @@
+/**
+ * A Vite plugin that lowers TC39 standard decorators, for projects on Vite 8 or Vitest 4.
+ *
+ * Those versions transform TypeScript with oxc, which does not implement the standard
+ * decorator transform yet. It does not report that: it leaves the decorator syntax in the
+ * output, so `vitest` prints "0 test" next to a bare `SyntaxError`, and `vite build` reports
+ * success while emitting a bundle that throws `SyntaxError` the moment anything imports it.
+ *
+ * Nothing here is specific to cereale — any library built on standard decorators needs it —
+ * but cereale ships it because a consumer's first experience of the library should not be a
+ * syntax error with no obvious cause. Delete it once oxc supports the transform.
+ *
+ * ```ts
+ * // vite.config.ts / vitest.config.ts
+ * import { standardDecorators } from 'cereale/vite';
+ *
+ * export default defineConfig({ plugins: [standardDecorators()] });
+ * ```
+ *
+ * The transform is done by esbuild if it is installed, otherwise by the TypeScript compiler.
+ * cereale depends on neither; one of the two is present in essentially every TypeScript
+ * project, and the plugin says which to install if somehow neither is.
+ */
+
+/**
+ * The shape Vite expects of a plugin, declared here rather than imported.
+ *
+ * `cereale/vite` must not drag `vite` into a consumer's type-checking just to describe its own
+ * return value — this object is structurally assignable to Vite's `Plugin`.
+ */
+export interface StandardDecoratorsPlugin {
+  name: string;
+  enforce: 'pre';
+  transform(code: string, id: string): Promise<{ code: string; map: string } | null>;
+}
+
+export interface StandardDecoratorsOptions {
+  /**
+   * Decides which modules to transform. Receives the resolved module id.
+   *
+   * The default takes `.ts`, `.mts` and `.cts` outside `node_modules`. `.tsx` is excluded
+   * because lowering decorators there means also deciding what happens to the JSX, and
+   * getting that wrong is worse than not handling it; pass an `include` of your own if you
+   * declare decorated classes in `.tsx` files.
+   */
+  include?: (id: string) => boolean;
+  /** ECMAScript target for the emitted code. Defaults to `es2022`, the first with class fields. */
+  target?: string;
+  /**
+   * Which tool does the transform. `'auto'` (the default) prefers esbuild for speed and falls
+   * back to the TypeScript compiler; name one explicitly to keep a build reproducible, or to
+   * fail loudly rather than silently switch if the preferred one is not installed.
+   */
+  transformer?: 'auto' | 'esbuild' | 'typescript';
+}
+
+const DEFAULT_INCLUDE = (id: string): boolean =>
+  /\.[cm]?ts(\?.*)?$/.test(id) && !id.includes('/node_modules/');
+
+type Transformer = (code: string, id: string, target: string) => Promise<{ code: string; map: string }>;
+
+function isMissingModule(error: unknown): boolean {
+  const code = (error as { code?: unknown } | null)?.code;
+  return code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND';
+}
+
+async function esbuildTransformer(): Promise<Transformer | null> {
+  let esbuild: typeof import('esbuild');
+  try {
+    esbuild = await import('esbuild');
+  } catch (error) {
+    if (isMissingModule(error)) return null;
+    throw error;
+  }
+  return async (code, id, target) => {
+    const result = await esbuild.transform(code, {
+      loader: 'ts',
+      target,
+      sourcefile: id,
+      sourcemap: true,
+      // Standard semantics, not the legacy ones: cereale records into `context.metadata`.
+      tsconfigRaw: { compilerOptions: { experimentalDecorators: false, useDefineForClassFields: true } },
+    });
+    return { code: result.code, map: result.map };
+  };
+}
+
+async function typescriptTransformer(): Promise<Transformer | null> {
+  let ts: typeof import('typescript');
+  try {
+    ts = await import('typescript');
+  } catch (error) {
+    if (isMissingModule(error)) return null;
+    throw error;
+  }
+  // `ScriptTarget` members are spelled `ES2022`, `ESNext`; esbuild-style targets are lower
+  // case. Matched case-insensitively rather than upper-casing, which would miss `ESNext`.
+  const targetKey = (target: string) =>
+    Object.keys(ts.ScriptTarget).find(key => key.toLowerCase() === target.toLowerCase());
+
+  return async (code, id, target) => {
+    const key = targetKey(target);
+    if (key === undefined) {
+      throw new Error(`cereale/vite: ${JSON.stringify(target)} is not a target the TypeScript compiler knows.`);
+    }
+    const result = ts.transpileModule(code, {
+      fileName: id.replace(/\?.*$/, ''),
+      compilerOptions: {
+        target: ts.ScriptTarget[key as keyof typeof ts.ScriptTarget],
+        module: ts.ModuleKind.ESNext,
+        experimentalDecorators: false,
+        useDefineForClassFields: true,
+        sourceMap: true,
+        isolatedModules: true,
+      },
+    });
+    // tsc appends `//# sourceMappingURL=<file>.map` even though the map is handed back
+    // separately. Vite would follow that comment and fail to read a file nobody wrote.
+    const output = result.outputText.replace(/\r?\n?\/\/# sourceMappingURL=\S*[ \t]*$/, '');
+    return { code: output, map: result.sourceMapText ?? '' };
+  };
+}
+
+const FACTORIES = { esbuild: esbuildTransformer, typescript: typescriptTransformer };
+
+// Resolution is memoized per choice: the transform hook runs once per module, and neither
+// `import('esbuild')` nor `import('typescript')` is cheap enough to repeat.
+const resolved = new Map<string, Promise<Transformer>>();
+
+function resolveTransformer(choice: 'auto' | 'esbuild' | 'typescript'): Promise<Transformer> {
+  let pending = resolved.get(choice);
+  if (!pending) {
+    pending = (async () => {
+      if (choice !== 'auto') {
+        const only = await FACTORIES[choice]();
+        if (only) return only;
+        throw new Error(
+          `cereale/vite was asked to transform with ${choice}, which is not installed. ` +
+          `Install it (\`npm i -D ${choice}\`) or drop the \`transformer\` option to let the ` +
+          'plugin pick whichever is available.'
+        );
+      }
+      const best = (await esbuildTransformer()) ?? (await typescriptTransformer());
+      if (best) return best;
+      throw new Error(
+        'cereale/vite needs a transformer that understands TC39 standard decorators, and found ' +
+        'neither esbuild nor typescript. Install one of them as a dev dependency: ' +
+        '`npm i -D esbuild`.'
+      );
+    })();
+    resolved.set(choice, pending);
+  }
+  return pending;
+}
+
+/**
+ * Transforms TypeScript sources with esbuild (or tsc) before Vite's own oxc pass sees them.
+ *
+ * `enforce: 'pre'` is what makes this work: the hook runs ahead of Vite's transform, hands
+ * back plain JavaScript, and oxc is then left with nothing it cannot parse.
+ */
+export function standardDecorators(options: StandardDecoratorsOptions = {}): StandardDecoratorsPlugin {
+  const include = options.include ?? DEFAULT_INCLUDE;
+  const target = options.target ?? 'es2022';
+  const choice = options.transformer ?? 'auto';
+
+  return {
+    name: 'cereale:standard-decorators',
+    enforce: 'pre',
+    async transform(code: string, id: string) {
+      if (!include(id)) return null;
+      return (await resolveTransformer(choice))(code, id, target);
+    },
+  };
+}