@zipbul/baker 5.1.0 → 5.2.0

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # @zipbul/baker
 
+## 5.2.0
+
+### Minor Changes
+
+- f768694: Fix four correctness bugs found in a package-wide audit. Two of them change observable behavior for
+  input that previously "worked", so review before upgrading:
+
+  - **`@IsEnum` with numeric enums (behavior change).** TypeScript numeric enums compile to a reverse-mapped
+    object (`{ 0: 'Inactive', 1: 'Active', Active: 1, Inactive: 0 }`), so the previous `Object.values()`
+    lookup wrongly accepted the member-_name_ strings (e.g. `'Active'`) as valid values. Values are now read
+    through the non-numeric keys, so only real members pass — correct for string, numeric, and heterogeneous
+    enums. Input that relied on the member-name strings being accepted will now be rejected.
+
+  - **`momentTransformer` parses in UTC (behavior change).** It now uses `moment.utc(value)` so a zoneless
+    datetime string resolves to the same instant on every host; previously local-time parsing made the
+    serialized output depend on the machine timezone. Zoneless inputs that were parsed in local time will now
+    be parsed as UTC. Matches `luxonTransformer`'s UTC default.
+
+  - **`luxonTransformer` invalid-date passthrough.** An unparseable date string / `Date` now passes through
+    untouched instead of being laundered into an Invalid `DateTime` (which serialized to `null` /
+    `"Invalid DateTime"` and corrupted data). Matches `momentTransformer`'s pass-through contract.
+
+  - **Per-call `groups` option validation.** A non-`string[]` `groups` value now throws a clear `BakerError`
+    at the call boundary instead of silently misbehaving inside the generated executor.
+
+- 26e13af: Fix declared-collection element validation (RED tests added first), speed up collection `validate`, and
+  land an internal layering cleanup. One item changes observable behavior — review before upgrading:
+
+  - **Declared `@Type(() => Set)` / `@Type(() => Map)` now validate their elements (behavior change).** The
+    declared-collection codegen path hand-rolled its per-element loop separately from the canonical
+    (`type: null`) path and had three defects: a declared **Map** dropped every per-element `each` rule
+    entirely; declared Set/Map `each` rules ignored the runtime `groups` filter; and a function `message` on
+    an `each` rule received the whole collection as `value` instead of the failing element. All four sites
+    (Set/Map × deserialize/validate) now route through one shared emitter with the same rule-major ordering,
+    group filtering, per-element `value` binding, and `field[i]` paths as the canonical path. Input that was
+    silently accepted because a Map's element rules never ran will now be validated.
+
+  - **Collection `validate` is ~4.7× faster on large arrays.** The inline-nested validate path eagerly
+    allocated a per-element error-path string (`field[i].`) on every element even for valid input; it is now
+    built only at the (cold) error-push sites. A 1000-element nested-DTO `validate` drops from ~10µs to
+    ~2.2µs (now on par with TypeBox and ahead of Ajv). `deserialize` and all error paths are byte-identical.
+
+  - **`createRule` is now also exported from the `@zipbul/baker/rules` subpath** (it was already exported from
+    the package root).
+
+  - **`luxonTransformer` / `momentTransformer` peer-dep error is now precise.** A genuinely-missing peer still
+    throws the "install it" `BakerError`; a peer that IS installed but throws during evaluation now surfaces
+    its real error instead of the misleading install hint.
+
+  Internal-only (no API change): the seal stage's TypeDef normalization was extracted out of the `sealOne`
+  god-function, large static lookup tables and the `string-format` validators were split into cohesive
+  modules, and several stateless helpers were simplified. Public surface is unchanged except the `createRule`
+  subpath export above (verified by an export-diff).
+
+- 96ed92c: Fix five reproduced correctness bugs (each added as a RED test first) and unify the unknown-key failure
+  model. Several change observable behavior — review before upgrading:
+
+  - **Discriminated arrays now work (was broken).** A field typed `type: () => [Base]` with a `discriminator`
+    previously read the discriminator off the _array itself_ (`undefined`) and rejected every valid input with
+    `invalidDiscriminator`. `deserialize`/`validate` now dispatch the discriminator switch **per element**,
+    reporting nested errors at `field[i].path` and the invalid-discriminator error at the `field[i]` element
+    path. (serialize already handled arrays.)
+
+  - **serialize throws on an unmatched discriminator subtype (behavior change).** When an instance matched no
+    `instanceof` branch, serialize silently emitted the raw, un-serialized object (leaking undeclared fields).
+    It now throws a `BakerError`, symmetric with deserialize rejecting an unknown discriminator value.
+
+  - **`each` rule messages receive the failing element (behavior change).** A `message`/`context` function on
+    an `arrayOf(...)` rule was passed the whole collection as `value` while the path pointed at `field[i]`.
+    It now receives the failing element, consistent with the element-level path.
+
+  - **`isDateString` / `isISO8601({ strict: true })` leap-year for years 0–99.** Calendar validity used
+    `new Date(year, …)`, which remaps a 0–99 year argument to 1900–1999 — so `0000-02-29` (a valid leap date
+    by the 400 rule) was wrongly rejected. Now computed with the proleptic Gregorian rule for all years (and
+    without allocating a `Date`).
+
+  - **`isHash` / `isTaxId` reject an unknown algorithm/locale at construction (behavior change).** They
+    previously returned a rule that always failed at runtime; they now throw a `BakerError` when called with
+    an unsupported key, matching `isMobilePhone`/`isPostalCode`/`isIdentityCard`/`isPassportNumber`.
+
+  - **`isURL` no longer shares its default-protocols array across rules.** With default protocols, every
+    `isURL()` rule exposed the same module-level `['http','https','ftp']` array on `rule.constraints`;
+    mutating one rule's constraints would have corrupted every other. Each rule now owns an independent copy.
+
 ## 5.1.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -1,10 +1,12 @@
-export { createRule } from './src/create-rule';
-export { Field, arrayOf } from './src/decorators/index';
-export type { FieldOptions, ArrayOfMarker } from './src/decorators/index';
+export { createRule } from './src/rules';
+export { Field, arrayOf } from './src/decorators';
+export type { FieldOptions, ArrayOfMarker } from './src/decorators';
 export { Baker } from './src/baker';
-export { ExcludeMode, RequiredType } from './src/enums';
-export type { BakerIssue, BakerIssueSet } from './src/errors';
-export { isBakerIssueSet, BakerError } from './src/errors';
-export type { EmittableRule, Transformer, TransformParams } from './src/types';
-export type { BakerConfig } from './src/configure';
-export type { RuntimeOptions } from './src/interfaces';
+export { ExcludeMode } from './src/decorators';
+export { RequiredType } from './src/rules';
+export type { BakerIssue, BakerIssueSet } from './src/common';
+export { isBakerIssueSet, BakerError } from './src/common';
+export type { EmittableRule } from './src/rules';
+export type { Transformer, TransformParams } from './src/transformers';
+export type { BakerConfig } from './src/config';
+export type { RuntimeOptions } from './src/common';

package/dist/index.js

@@ -1 +1 @@
-export{createRule}from"./src/create-rule.js";export{Field,arrayOf}from"./src/decorators/index.js";export{Baker}from"./src/baker.js";export{ExcludeMode,RequiredType}from"./src/enums.js";export{isBakerIssueSet,BakerError}from"./src/errors.js";
+export{createRule}from"./src/rules/index.js";export{Field,arrayOf}from"./src/decorators/index.js";export{Baker}from"./src/baker.js";export{ExcludeMode}from"./src/decorators/index.js";export{RequiredType}from"./src/rules/index.js";export{isBakerIssueSet,BakerError}from"./src/common/index.js";

package/dist/src/baker.d.ts

@@ -1,6 +1,5 @@
-import type { BakerConfig } from './configure';
-import type { BakerIssueSet } from './errors';
-import type { RuntimeOptions } from './interfaces';
+import type { BakerIssueSet, ClassCtor, RuntimeOptions } from './common';
+import type { BakerConfig } from './config';
 /**
  * A baker — an isolated registration + seal + runtime boundary. Each `new Baker()` owns its own
  * registry, config, and compiled executors, so multiple bakers in one process (or a bundler-duplicated
@@ -30,12 +29,12 @@ export declare class Baker {
     readonly Recipe: (value: Function, _context: ClassDecoratorContext) => void;
     /** Seal every root registered to this baker (and its nested DTOs) with this baker's config. */
     readonly seal: () => void;
-    deserialize: <T>(Class: new (...args: never[]) => T, input: unknown, options?: RuntimeOptions) => T | BakerIssueSet | Promise<T | BakerIssueSet>;
-    deserializeSync: <T>(Class: new (...args: never[]) => T, input: unknown, options?: RuntimeOptions) => T | BakerIssueSet;
-    deserializeAsync: <T>(Class: new (...args: never[]) => T, input: unknown, options?: RuntimeOptions) => Promise<T | BakerIssueSet>;
-    validate: <T>(Class: new (...args: never[]) => T, input: unknown, options?: RuntimeOptions) => true | BakerIssueSet | Promise<true | BakerIssueSet>;
-    validateSync: <T>(Class: new (...args: never[]) => T, input: unknown, options?: RuntimeOptions) => true | BakerIssueSet;
-    validateAsync: <T>(Class: new (...args: never[]) => T, input: unknown, options?: RuntimeOptions) => Promise<true | BakerIssueSet>;
+    deserialize: <T>(Class: ClassCtor<T>, input: unknown, options?: RuntimeOptions) => T | BakerIssueSet | Promise<T | BakerIssueSet>;
+    deserializeSync: <T>(Class: ClassCtor<T>, input: unknown, options?: RuntimeOptions) => T | BakerIssueSet;
+    deserializeAsync: <T>(Class: ClassCtor<T>, input: unknown, options?: RuntimeOptions) => Promise<T | BakerIssueSet>;
+    validate: <T>(Class: ClassCtor<T>, input: unknown, options?: RuntimeOptions) => true | BakerIssueSet | Promise<true | BakerIssueSet>;
+    validateSync: <T>(Class: ClassCtor<T>, input: unknown, options?: RuntimeOptions) => true | BakerIssueSet;
+    validateAsync: <T>(Class: ClassCtor<T>, input: unknown, options?: RuntimeOptions) => Promise<true | BakerIssueSet>;
     serialize: <T>(instance: T, options?: RuntimeOptions) => Record<string, unknown> | Promise<Record<string, unknown>>;
     serializeSync: <T>(instance: T, options?: RuntimeOptions) => Record<string, unknown>;
     serializeAsync: <T>(instance: T, options?: RuntimeOptions) => Promise<Record<string, unknown>>;

package/dist/src/baker.js

@@ -1 +1 @@
-export class Baker{#G=new Set;#F=new Map;#H;#I=!1;constructor(j){this.#H=j===void 0?Object.freeze({}):K(j)}Recipe=(j,F)=>{this.#G.add(j)};seal=()=>{if(this.#I)return;_(this.#G,this.#H,this.#F);this.#I=!0};#j(j){let F=j;while(F){const H=this.#F.get(F);if(H){if(F!==j)this.#F.set(j,H);return H}const J=Object.getPrototypeOf(F);F=typeof J==="function"?J:null}const G=j.name||"<anonymous class>";throw new L(`${G} is not sealed by this baker`)}deserialize=(j,F,G)=>M(this.#j(j),F,G);deserializeSync=(j,F,G)=>N(this.#j(j),j.name,F,G);deserializeAsync=(j,F,G)=>P(this.#j(j),F,G);validate=(j,F,G)=>X(this.#j(j),F,G);validateSync=(j,F,G)=>Y(this.#j(j),j.name,F,G);validateAsync=(j,F,G)=>Z(this.#j(j),F,G);serialize=(j,F)=>Q(this.#j(I(j,"serialize")),j,F);serializeSync=(j,F)=>{const G=I(j,"serializeSync");return U(this.#j(G),G.name,j,F)};serializeAsync=(j,F)=>W(this.#j(I(j,"serializeAsync")),j,F)}import{normalizeConfig as K}from"./configure.js";import{BakerError as L}from"./errors.js";import{runDeserialize as M,runDeserializeSync as N,runDeserializeAsync as P}from"./functions/deserialize.js";import{resolveSerializeClass as I,runSerialize as Q,runSerializeSync as U,runSerializeAsync as W}from"./functions/serialize.js";import{runValidate as X,runValidateSync as Y,runValidateAsync as Z}from"./functions/validate.js";import{sealRegistry as _}from"./seal/seal.js";
+export class Baker{#G=new Set;#F=new Map;#H;#I=!1;constructor(j){this.#H=L(j===void 0?{}:j)}Recipe=(j,F)=>{this.#G.add(j)};seal=()=>{if(this.#I)return;_(this.#G,this.#H,this.#F);this.#I=!0};#j(j){let F=j;while(F){const H=this.#F.get(F);if(H){if(F!==j)this.#F.set(j,H);return H}const J=Object.getPrototypeOf(F);F=typeof J==="function"?J:null}const G=j.name||"<anonymous class>";throw new K(`${G} is not sealed by this baker`)}deserialize=(j,F,G)=>M(this.#j(j),F,G);deserializeSync=(j,F,G)=>N(this.#j(j),j.name,F,G);deserializeAsync=(j,F,G)=>P(this.#j(j),F,G);validate=(j,F,G)=>X(this.#j(j),F,G);validateSync=(j,F,G)=>Y(this.#j(j),j.name,F,G);validateAsync=(j,F,G)=>Z(this.#j(j),F,G);serialize=(j,F)=>Q(this.#j(I(j,"serialize")),j,F);serializeSync=(j,F)=>{const G=I(j,"serializeSync");return U(this.#j(G),G.name,j,F)};serializeAsync=(j,F)=>W(this.#j(I(j,"serializeAsync")),j,F)}import{BakerError as K}from"./common/index.js";import{normalizeConfig as L}from"./config/index.js";import{runDeserialize as M,runDeserializeSync as N,runDeserializeAsync as P,resolveSerializeClass as I,runSerialize as Q,runSerializeSync as U,runSerializeAsync as W,runValidate as X,runValidateSync as Y,runValidateAsync as Z}from"./runtime/index.js";import{sealRegistry as _}from"./seal/index.js";

package/dist/src/common/enums.d.ts

@@ -0,0 +1,10 @@
+/** Direction of a (de)serialization pass. */
+export declare enum Direction {
+    Deserialize = "deserialize",
+    Serialize = "serialize"
+}
+/** Cached accessor a RulePlan reuses across checks. */
+export declare enum CacheKey {
+    Length = "length",
+    Time = "time"
+}

package/dist/src/common/enums.js

@@ -0,0 +1 @@
+export var Direction;((b)=>{b.Deserialize="deserialize";b.Serialize="serialize"})(Direction||={});export var CacheKey;((b)=>{b.Length="length";b.Time="time"})(CacheKey||={});

package/dist/src/common/index.d.ts

@@ -0,0 +1,6 @@
+export { BakerError, isBakerIssueSet, toBakerIssueSet } from './errors';
+export type { BakerIssue, BakerIssueSet } from './errors';
+export { Direction, CacheKey } from './enums';
+export type { ClassCtor } from './types';
+export type { RuntimeOptions } from './interfaces';
+export { isAsyncFunction, isPromiseLike } from './utils';

package/dist/src/common/index.js

@@ -0,0 +1 @@
+export{BakerError,isBakerIssueSet,toBakerIssueSet}from"./errors.js";export{Direction,CacheKey}from"./enums.js";export{isAsyncFunction,isPromiseLike}from"./utils.js";

package/dist/src/common/interfaces.d.ts

@@ -0,0 +1,4 @@
+export interface RuntimeOptions {
+    /** Per-request groups — passed at runtime since they may vary per request */
+    groups?: string[];
+}

package/dist/src/common/types.d.ts

@@ -0,0 +1,2 @@
+/** Generic class constructor — contravariant `never[]` args accept any user constructor */
+export type ClassCtor<T = object> = new (...args: never[]) => T;

package/dist/src/config/config-normalizer.d.ts

@@ -0,0 +1,7 @@
+import type { SealOptions } from '../seal';
+import type { BakerConfig } from './interfaces';
+/**
+ * Validates a {@link BakerConfig} and maps it to the internal {@link SealOptions}. Used by
+ * `new Baker(config)`. Stateless — a plain function (no instance/class needed).
+ */
+export declare function normalizeConfig(config: BakerConfig): SealOptions;

package/dist/src/config/config-normalizer.js

@@ -0,0 +1 @@
+import{BakerError as v}from"../common/index.js";import{BAKER_CONFIG_KEYS as x}from"./constants.js";export function normalizeConfig(j){if(j===null||typeof j!=="object"||Array.isArray(j))throw new v(`[baker] config requires a plain object. Received: ${j===null?"null":Array.isArray(j)?"array":typeof j}.`);for(const q of Object.keys(j))if(!x.has(q))throw new v(`[baker] unknown key '${q}'. Valid keys: ${[...x].join(", ")}.`);return Object.freeze({enableImplicitConversion:j.autoConvert??!1,exposeDefaultValues:j.allowClassDefaults??!1,stopAtFirstError:j.stopAtFirstError??!1,whitelist:j.forbidUnknown??!1,debug:j.debug??!1})}

package/dist/src/config/constants.d.ts

@@ -0,0 +1,6 @@
+import type { BakerConfig } from './interfaces';
+/**
+ * The valid {@link BakerConfig} keys. Shared single source: the ConfigNormalizer rejects unknown keys
+ * with it, and the per-call options guard (runtime) rejects a seal-time config key passed at call time.
+ */
+export declare const BAKER_CONFIG_KEYS: Set<keyof BakerConfig>;

package/dist/src/config/constants.js

@@ -0,0 +1 @@
+export const BAKER_CONFIG_KEYS=new Set(["autoConvert","allowClassDefaults","stopAtFirstError","forbidUnknown","debug"]);

package/dist/src/config/index.d.ts

@@ -0,0 +1,3 @@
+export { normalizeConfig } from './config-normalizer';
+export { BAKER_CONFIG_KEYS } from './constants';
+export type { BakerConfig } from './interfaces';

package/dist/src/config/index.js

@@ -0,0 +1 @@
+export{normalizeConfig}from"./config-normalizer.js";export{BAKER_CONFIG_KEYS}from"./constants.js";

package/dist/src/{configure.d.ts → config/interfaces.d.ts}

@@ -1,5 +1,4 @@
-import type { SealOptions } from './interfaces';
-interface BakerConfig {
+export interface BakerConfig {
     /** Automatic type conversion ("123" → 123). @default false */
     autoConvert?: boolean;
     /** Use class default values when key is missing from input. @default false */
@@ -11,9 +10,3 @@ interface BakerConfig {
     /** Include field exclusion reasons as comments in generated code. @default false */
     debug?: boolean;
 }
-/**
- * Validate a BakerConfig and map it to the internal SealOptions. Used by `new Baker(config)`.
- */
-declare function normalizeConfig(config: BakerConfig): SealOptions;
-export { normalizeConfig };
-export type { BakerConfig };

package/dist/src/decorators/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const ARRAY_OF: unique symbol;
+export declare const FIELD_OPTION_KEYS: ReadonlySet<string>;

package/dist/src/decorators/constants.js

@@ -0,0 +1 @@
+export const ARRAY_OF=Symbol.for("baker:arrayOf");export const FIELD_OPTION_KEYS=new Set(Object.keys({type:!0,discriminator:!0,keepDiscriminatorProperty:!0,rules:!0,optional:!0,nullable:!0,name:!0,deserializeName:!0,serializeName:!0,exclude:!0,groups:!0,when:!0,transform:!0,message:!0,context:!0,mapValue:!0,setValue:!0}));

package/dist/src/decorators/enums.d.ts

@@ -0,0 +1,5 @@
+/** Direction in which a field is excluded. */
+export declare enum ExcludeMode {
+    DeserializeOnly = "deserializeOnly",
+    SerializeOnly = "serializeOnly"
+}

package/dist/src/decorators/enums.js

@@ -0,0 +1 @@
+export var ExcludeMode;((i)=>{i.DeserializeOnly="deserializeOnly";i.SerializeOnly="serializeOnly"})(ExcludeMode||={});

package/dist/src/decorators/field.d.ts

@@ -1,9 +1,6 @@
-import type { ClassCtor, EmittableRule, Transformer } from '../types';
-import { ExcludeMode } from '../enums';
-interface ArrayOfMarker {
-    readonly [key: symbol]: true;
-    readonly rules: EmittableRule[];
-}
+import type { EmittableRule } from '../rules';
+import type { ArrayOfMarker, FieldOptions } from './interfaces';
+import type { FieldDecorator, RuleArg } from './types';
 /**
  * Apply rules to each element of an array.
  *
@@ -14,54 +11,6 @@ interface ArrayOfMarker {
  * ```
  */
 declare function arrayOf(...rules: EmittableRule[]): ArrayOfMarker;
-interface FieldOptions {
-    /** Nested DTO type. Thunk — supports circular references. [Dto] for arrays. */
-    type?: () => ClassCtor | ClassCtor[] | MapConstructor | SetConstructor;
-    /** Polymorphic discriminator configuration — used with type */
-    discriminator?: {
-        property: string;
-        subTypes: {
-            value: Function;
-            name: string;
-        }[];
-    };
-    /** Whether to keep the discriminator property in the result object */
-    keepDiscriminatorProperty?: boolean;
-    /** Validation rules array */
-    rules?: (EmittableRule | ArrayOfMarker)[];
-    /** Allow undefined */
-    optional?: boolean;
-    /** Allow null */
-    nullable?: boolean;
-    /** JSON key mapping (bidirectional) */
-    name?: string;
-    /** Deserialize direction key mapping (cannot be used with name) */
-    deserializeName?: string;
-    /** Serialize direction key mapping (cannot be used with name) */
-    serializeName?: string;
-    /** Field exclusion — true: bidirectional, 'deserializeOnly': deserialization only, 'serializeOnly': serialization only */
-    exclude?: boolean | ExcludeMode;
-    /** Groups — field visibility control + conditional validation rule application */
-    groups?: string[];
-    /** Conditional validation — skip all field validation when false */
-    when?: (obj: Record<string, unknown>) => boolean;
-    /** Transformer or array of transformers (serialize direction applies in reverse order) */
-    transform?: Transformer | Transformer[];
-    /** Error message on validation failure — applied to all rules of the field (rule's own message takes precedence) */
-    message?: string | ((args: {
-        property: string;
-        value: unknown;
-        constraints: Record<string, unknown>;
-    }) => string);
-    /** Error context on validation failure — applied to all rules of the field (rule's own context takes precedence) */
-    context?: unknown;
-    /** Nested DTO class thunk for Map values — used with type: () => Map */
-    mapValue?: () => ClassCtor;
-    /** Nested DTO class thunk for Set elements — used with type: () => Set */
-    setValue?: () => ClassCtor;
-}
-type RuleArg = EmittableRule | ArrayOfMarker;
-type FieldDecorator = (value: undefined, context: ClassFieldDecoratorContext) => void;
 /** `@Field`() — empty field registration */
 declare function Field(): FieldDecorator;
 /** `@Field`(isString(), email()) — variadic rules */

package/dist/src/decorators/field.js

@@ -1 +1 @@
-import{ensureMeta as L}from"../collect.js";import{Direction as h,ExcludeMode as N}from"../enums.js";import{BakerError as X}from"../errors.js";import{isAsyncFunction as P,isPromiseLike as Y}from"../utils.js";const I=Symbol.for("baker:arrayOf");function arrayOf(...q){return{rules:q,[I]:!0}}function $(q){return typeof q==="object"&&q!==null&&q[I]===!0}const j=new Set(["type","discriminator","keepDiscriminatorProperty","rules","optional","nullable","name","deserializeName","serializeName","exclude","groups","when","transform","message","context","mapValue","setValue"]);function S(q){if(typeof q==="function")return!1;if(typeof q!=="object"||q===null)return!1;if($(q))return!1;const C=Object.keys(q);if(C.length===0)return!0;return C.some((b)=>j.has(b))}function V(q,C,b){const J=b?`${C} ${b}`:C;if(typeof q==="function"){const Q=q;if(typeof Q.emit!=="function"||typeof Q.ruleName!=="string"){const G=Q.name?` Did you forget to call '${Q.name}()'? Factories must be invoked (e.g., '${Q.name}()'). Rule constants are passed directly (e.g., 'isString' without parentheses).`:" Use createRule() or import a rule from @zipbul/baker/rules.";throw new X(`@Field on ${J}: argument is not a baker rule.${G} Valid @Field forms: @Field(), @Field(rule, ...), @Field(options), @Field(rule, ..., options).`)}return}throw new X(`@Field on ${J}: expected a baker rule (function with .emit and .ruleName), got ${q===null?"null":typeof q}. Use createRule() or import a rule from @zipbul/baker/rules. Valid @Field forms: @Field(), @Field(rule, ...), @Field(options), @Field(rule, ..., options).`)}function z(q){if(q.length===0)return{rules:[],options:{}};if(q.length===1&&S(q[0])){const b=q[0];return{rules:b.rules??[],options:b}}const C=q[q.length-1];if(S(C)){const b=C;let J=q.slice(0,-1);if(b.rules)J=[...J,...b.rules];return{rules:J,options:b}}return{rules:q,options:{}}}function D(q,C,b){for(const J of C)if($(J))for(const H of J.rules){const Q={rule:H,each:!0};if(b.groups!==void 0)Q.groups=b.groups;if(b.message!==void 0)Q.message=b.message;if(b.context!==void 0)Q.context=b.context;q.validation.push(Q)}else{const H={rule:J};if(b.groups!==void 0)H.groups=b.groups;if(b.message!==void 0)H.message=b.message;if(b.context!==void 0)H.context=b.context;q.validation.push(H)}}function _(q,C){if(C.name){const b={name:C.name};if(C.groups!==void 0)b.groups=C.groups;q.expose.push(b)}else if(C.deserializeName||C.serializeName){if(C.deserializeName){const b={name:C.deserializeName,deserializeOnly:!0};if(C.groups!==void 0)b.groups=C.groups;q.expose.push(b)}if(C.serializeName){const b={name:C.serializeName,serializeOnly:!0};if(C.groups!==void 0)b.groups=C.groups;q.expose.push(b)}}else if(C.groups)q.expose.push({groups:C.groups});else q.expose.push({})}function w(q,C,b){const J=P(b);return{fn:(Q)=>{const G=b(Q);if(!J&&Y(G))throw new X(`@Field(${q}) ${C} transform returned Promise. Declare the transform with async if it is asynchronous.`);return G},isAsync:J}}function T(q,C,b){if(!b.transform)return;const J=Array.isArray(b.transform)?b.transform:[b.transform];for(const H of J){const Q=w(C,h.Deserialize,H.deserialize),G=w(C,h.Serialize,H.serialize);q.transform.push({fn:Q.fn,isAsync:Q.isAsync,options:{deserializeOnly:!0}},{fn:G.fn,isAsync:G.isAsync,options:{serializeOnly:!0}})}}function Field(...q){return(C,b)=>{if(b.static)throw new X("@Field cannot decorate static fields.");if(b.private)throw new X("@Field cannot decorate private fields.");if(typeof b.name==="symbol")throw new X("@Field: symbol property keys are not supported. Use a string property name.");const J=b.name,H=L(b.metadata,J),{rules:Q,options:G}=z(q);if(G.name&&(G.deserializeName||G.serializeName))throw new X(`@Field on ${J}: 'name' cannot be combined with 'deserializeName'/'serializeName'. Use one or the other.`);for(let U=0;U<Q.length;U++){const W=Q[U];if($(W))for(let Z=0;Z<W.rules.length;Z++)V(W.rules[Z],J,`arrayOf[${Z}]`);else V(W,J)}D(H,Q,G);if(G.context!==void 0)H.context=G.context;if(G.message!==void 0)H.message=G.message;if(G.optional)H.flags.isOptional=!0;if(G.nullable)H.flags.isNullable=!0;if(G.when)H.flags.validateIf=G.when;if(G.type){const U={fn:G.type};if(G.discriminator!==void 0)U.discriminator=G.discriminator;if(G.keepDiscriminatorProperty!==void 0)U.keepDiscriminatorProperty=G.keepDiscriminatorProperty;const W=G.mapValue??G.setValue;if(W!==void 0)U.collectionValue=W;H.type=U}_(H,G);if(G.exclude){if(G.exclude===!0)H.exclude={};else if(G.exclude===N.DeserializeOnly)H.exclude={deserializeOnly:!0};else if(G.exclude===N.SerializeOnly)H.exclude={serializeOnly:!0}}T(H,J,G)}}export{arrayOf,Field};
+import{Direction as I,BakerError as X,isAsyncFunction as j,isPromiseLike as z}from"../common/index.js";import{metaStore as _}from"../metadata/index.js";import{ARRAY_OF as h,FIELD_OPTION_KEYS as w}from"./constants.js";import{ExcludeMode as L}from"./enums.js";function arrayOf(...b){return{rules:b,[h]:!0}}function V(b){return typeof b==="object"&&b!==null&&b[h]===!0}function P(b){if(typeof b==="function")return!1;if(typeof b!=="object"||b===null)return!1;if(V(b))return!1;const q=Object.keys(b);if(q.length===0)return!0;return q.some((H)=>w.has(H))}function S(b,q,H){const J=H?`${q} ${H}`:q;if(typeof b==="function"){const U=b;if(typeof U.emit!=="function"||typeof U.ruleName!=="string"){const C=U.name?` Did you forget to call '${U.name}()'? Factories must be invoked (e.g., '${U.name}()'). Rule constants are passed directly (e.g., 'isString' without parentheses).`:" Use createRule() or import a rule from @zipbul/baker/rules.";throw new X(`@Field on ${J}: argument is not a baker rule.${C} Valid @Field forms: @Field(), @Field(rule, ...), @Field(options), @Field(rule, ..., options).`)}return}throw new X(`@Field on ${J}: expected a baker rule (function with .emit and .ruleName), got ${b===null?"null":typeof b}. Use createRule() or import a rule from @zipbul/baker/rules. Valid @Field forms: @Field(), @Field(rule, ...), @Field(options), @Field(rule, ..., options).`)}function M(b){if(b.length===0)return{rules:[],options:{}};if(b.length===1&&P(b[0])){const H=b[0];return{rules:H.rules??[],options:H}}const q=b[b.length-1];if(P(q)){const H=q;let J=b.slice(0,-1);if(H.rules)J=[...J,...H.rules];return{rules:J,options:H}}return{rules:b,options:{}}}function G(b,q){if(q.groups!==void 0)b.groups=q.groups;if(q.message!==void 0)b.message=q.message;if(q.context!==void 0)b.context=q.context;return b}function N(b,q){if(q.groups!==void 0)b.groups=q.groups;return b}function T(b,q,H){for(const J of q)if(V(J))for(const Q of J.rules)b.validation.push(G({rule:Q,each:!0},H));else b.validation.push(G({rule:J},H))}function D(b,q){if(q.name)b.expose.push(N({name:q.name},q));else if(q.deserializeName||q.serializeName){if(q.deserializeName)b.expose.push(N({name:q.deserializeName,deserializeOnly:!0},q));if(q.serializeName)b.expose.push(N({name:q.serializeName,serializeOnly:!0},q))}else if(q.groups)b.expose.push({groups:q.groups});else b.expose.push({})}function Y(b,q,H){const J=j(H);return{fn:(U)=>{const C=H(U);if(!J&&z(C))throw new X(`@Field(${b}) ${q} transform returned Promise. Declare the transform with async if it is asynchronous.`);return C},isAsync:J}}function B(b,q,H){if(!H.transform)return;const J=Array.isArray(H.transform)?H.transform:[H.transform];for(const Q of J){const U=Y(q,I.Deserialize,Q.deserialize),C=Y(q,I.Serialize,Q.serialize);b.transform.push({fn:U.fn,isAsync:U.isAsync,options:{deserializeOnly:!0}},{fn:C.fn,isAsync:C.isAsync,options:{serializeOnly:!0}})}}function Field(...b){return(q,H)=>{if(H.static)throw new X("@Field cannot decorate static fields.");if(H.private)throw new X("@Field cannot decorate private fields.");if(typeof H.name==="symbol")throw new X("@Field: symbol property keys are not supported. Use a string property name.");const J=H.name,Q=_.ensure(H.metadata,J),{rules:U,options:C}=M(b);if(C.name&&(C.deserializeName||C.serializeName))throw new X(`@Field on ${J}: 'name' cannot be combined with 'deserializeName'/'serializeName'. Use one or the other.`);if(C.mapValue!==void 0&&C.setValue!==void 0)throw new X(`@Field on ${J}: 'mapValue' and 'setValue' cannot both be set \u2014 use 'mapValue' for a Map value type and 'setValue' for a Set element type.`);for(let W=0;W<U.length;W++){const Z=U[W];if(V(Z))for(let $=0;$<Z.rules.length;$++)S(Z.rules[$],J,`arrayOf[${$}]`);else S(Z,J)}T(Q,U,C);if(C.context!==void 0)Q.context=C.context;if(C.message!==void 0)Q.message=C.message;if(C.optional)Q.flags.isOptional=!0;if(C.nullable)Q.flags.isNullable=!0;if(C.when)Q.flags.validateIf=C.when;if(C.type){const W={fn:C.type};if(C.discriminator!==void 0)W.discriminator=C.discriminator;if(C.keepDiscriminatorProperty!==void 0)W.keepDiscriminatorProperty=C.keepDiscriminatorProperty;const Z=C.mapValue??C.setValue;if(Z!==void 0)W.collectionValue=Z;Q.type=W}D(Q,C);if(C.exclude){if(C.exclude===!0)Q.exclude={};else if(C.exclude===L.DeserializeOnly)Q.exclude={deserializeOnly:!0};else if(C.exclude===L.SerializeOnly)Q.exclude={serializeOnly:!0}}B(Q,J,C)}}export{arrayOf,Field};

package/dist/src/decorators/index.d.ts

@@ -1,2 +1,2 @@
-export { Field, arrayOf } from './field';
-export type { FieldOptions, ArrayOfMarker } from './field';
+export * from './public';
+export { ExcludeMode } from './enums';

package/dist/src/decorators/index.js

@@ -1 +1 @@
-export{Field,arrayOf}from"./field.js";
+export*from"./public.js";export{ExcludeMode}from"./enums.js";

package/dist/src/decorators/interfaces.d.ts

@@ -0,0 +1,50 @@
+import type { ClassCtor } from '../common';
+import type { DiscriminatorDef } from '../metadata';
+import type { EmittableRule } from '../rules';
+import type { Transformer } from '../transformers';
+import type { ExcludeMode } from './enums';
+import { ARRAY_OF } from './constants';
+export interface ArrayOfMarker {
+    readonly [ARRAY_OF]: true;
+    readonly rules: EmittableRule[];
+}
+export interface FieldOptions {
+    /** Nested DTO type. Thunk — supports circular references. [Dto] for arrays. */
+    type?: () => ClassCtor | ClassCtor[] | MapConstructor | SetConstructor;
+    /** Polymorphic discriminator configuration — used with type */
+    discriminator?: DiscriminatorDef;
+    /** Whether to keep the discriminator property in the result object */
+    keepDiscriminatorProperty?: boolean;
+    /** Validation rules array */
+    rules?: (EmittableRule | ArrayOfMarker)[];
+    /** Allow undefined */
+    optional?: boolean;
+    /** Allow null */
+    nullable?: boolean;
+    /** JSON key mapping (bidirectional) */
+    name?: string;
+    /** Deserialize direction key mapping (cannot be used with name) */
+    deserializeName?: string;
+    /** Serialize direction key mapping (cannot be used with name) */
+    serializeName?: string;
+    /** Field exclusion — true: bidirectional, 'deserializeOnly': deserialization only, 'serializeOnly': serialization only */
+    exclude?: boolean | ExcludeMode;
+    /** Groups — field visibility control + conditional validation rule application */
+    groups?: string[];
+    /** Conditional validation — skip all field validation when false */
+    when?: (obj: Record<string, unknown>) => boolean;
+    /** Transformer or array of transformers (serialize direction applies in reverse order) */
+    transform?: Transformer | Transformer[];
+    /** Error message on validation failure — applied to all rules of the field (rule's own message takes precedence) */
+    message?: string | ((args: {
+        property: string;
+        value: unknown;
+        constraints: Record<string, unknown>;
+    }) => string);
+    /** Error context on validation failure — applied to all rules of the field (rule's own context takes precedence) */
+    context?: unknown;
+    /** Nested DTO class thunk for Map values — used with type: () => Map */
+    mapValue?: () => ClassCtor;
+    /** Nested DTO class thunk for Set elements — used with type: () => Set */
+    setValue?: () => ClassCtor;
+}

package/dist/src/decorators/public.d.ts

@@ -0,0 +1,2 @@
+export { Field, arrayOf } from './field';
+export type { FieldOptions, ArrayOfMarker } from './interfaces';

package/dist/src/decorators/public.js

@@ -0,0 +1 @@
+export{Field,arrayOf}from"./field.js";

package/dist/src/decorators/types.d.ts

@@ -0,0 +1,6 @@
+import type { EmittableRule } from '../rules';
+import type { ArrayOfMarker } from './interfaces';
+/** A positional @Field argument — either a rule or an arrayOf(...) element-rules marker. */
+export type RuleArg = EmittableRule | ArrayOfMarker;
+/** The class-field decorator @Field returns — TC39 field decorators receive `undefined` as the value. */
+export type FieldDecorator = (value: undefined, context: ClassFieldDecoratorContext) => void;

package/dist/src/metadata/enums.d.ts

@@ -0,0 +1,5 @@
+/** Collection container type for a nested field. */
+export declare enum CollectionType {
+    Map = "Map",
+    Set = "Set"
+}

package/dist/src/metadata/enums.js

@@ -0,0 +1 @@
+export var CollectionType;((e)=>{e.Map="Map";e.Set="Set"})(CollectionType||={});

package/dist/src/metadata/index.d.ts

@@ -0,0 +1,3 @@
+export type { RawClassMeta, RawPropertyMeta, RuleDef, TransformDef, ExposeDef, TypeDef, MessageArgs, DiscriminatorDef, } from './interfaces';
+export { CollectionType } from './enums';
+export { MetaStore, metaStore } from './meta-store';

package/dist/src/metadata/index.js

@@ -0,0 +1 @@
+export{CollectionType}from"./enums.js";export{MetaStore,metaStore}from"./meta-store.js";

package/dist/src/metadata/interfaces.d.ts

@@ -0,0 +1,90 @@
+import type { ClassCtor } from '../common';
+import type { InternalRule } from '../rules';
+import type { TransformFunction } from '../transformers';
+import type { CollectionType } from './enums';
+/** Arguments for user-defined message callback */
+export interface MessageArgs {
+    property: string;
+    value: unknown;
+    constraints: Record<string, unknown>;
+}
+export interface RuleDef {
+    rule: InternalRule;
+    each?: boolean;
+    groups?: string[];
+    /** Value to include in BakerIssue.message on validation failure */
+    message?: string | ((args: MessageArgs) => string);
+    /** Arbitrary value to include in BakerIssue.context on validation failure */
+    context?: unknown;
+}
+export interface TransformDef {
+    fn: TransformFunction;
+    isAsync?: boolean;
+    options?: {
+        groups?: string[];
+        deserializeOnly?: boolean;
+        serializeOnly?: boolean;
+    };
+}
+export interface ExposeDef {
+    name?: string;
+    groups?: string[];
+    deserializeOnly?: boolean;
+    serializeOnly?: boolean;
+}
+export interface ExcludeDef {
+    deserializeOnly?: boolean;
+    serializeOnly?: boolean;
+}
+/** A polymorphic discriminator subtype mapping — a class constructor keyed by its wire name. */
+export interface DiscriminatorSubType {
+    value: ClassCtor;
+    name: string;
+}
+/** Polymorphic discriminator config — shared single source between @Field options and the IR TypeDef. */
+export interface DiscriminatorDef {
+    property: string;
+    subTypes: DiscriminatorSubType[];
+}
+export interface TypeDef {
+    fn: () => ClassCtor | ClassCtor[] | MapConstructor | SetConstructor;
+    discriminator?: DiscriminatorDef;
+    keepDiscriminatorProperty?: boolean;
+    /** seal-time normalization result — true if fn() returns an array */
+    isArray?: boolean;
+    /** seal-time normalization result — cached class after resolving fn() (DTOs only, excluding primitives) */
+    resolvedClass?: ClassCtor;
+    /** seal-time normalization result — Map or Set collection type */
+    collection?: CollectionType;
+    /** Nested DTO class thunk for Map value / Set element */
+    collectionValue?: () => ClassCtor;
+    /** seal-time normalization result — cached class after resolving collectionValue */
+    resolvedCollectionValue?: ClassCtor;
+}
+export interface PropertyFlags {
+    /** `@Field({ optional })` — skip all validation when undefined/null */
+    isOptional?: boolean;
+    /** `@Field({ nullable })` — allow and assign null, reject undefined */
+    isNullable?: boolean;
+    /** `@Field({ when })` — skip all field validation when the predicate returns false */
+    validateIf?: (obj: Record<string, unknown>) => boolean;
+    /** Seal-derived — trigger recursive validation for nested `@Field({ type })` DTOs */
+    validateNested?: boolean;
+    /** Seal-derived — validate nested DTOs per array element */
+    validateNestedEach?: boolean;
+}
+export interface RawPropertyMeta {
+    validation: RuleDef[];
+    transform: TransformDef[];
+    expose: ExposeDef[];
+    exclude: ExcludeDef | null;
+    type: TypeDef | null;
+    flags: PropertyFlags;
+    /** Field-level message applied to ALL failures of this field (gate/structural/required/conversion/rule) */
+    message?: string | ((args: MessageArgs) => string);
+    /** Field-level context attached to ALL failures of this field */
+    context?: unknown;
+}
+export interface RawClassMeta {
+    [propertyKey: string]: RawPropertyMeta;
+}

package/dist/src/metadata/meta-store.d.ts

@@ -0,0 +1,49 @@
+import type { RawClassMeta, RawPropertyMeta } from './interfaces';
+import type { MetaObject } from './types';
+import { RAW } from '../symbols';
+/**
+ * The single boundary that bridges symbol-keyed decorator metadata to typed RAW metadata. All RAW
+ * access goes through this one process-wide `metaStore` instance (and, for the seal pipeline, an
+ * injected reference) — no other module touches `Class[Symbol.metadata][this.#rawKey]` directly. The private
+ * `#metaOf`/`#ensureOwnMeta` methods are the actual encapsulation; `RAW` itself is process-global
+ * (`Symbol.for('baker:raw')`), so the value of consolidating access here is one access protocol, not
+ * a "private symbol".
+ *
+ * RAW lives on the TC39 decorator metadata object (`Class[Symbol.metadata][this.#rawKey]`) — where modern field
+ * decorators can write (they receive `context.metadata`, never the class). Sealed executors live in
+ * each Baker's own map, never on the class.
+ */
+declare class MetaStore {
+    #private;
+    constructor(rawKey?: typeof RAW);
+    get(cls: Function): RawClassMeta | undefined;
+    /**
+     * Test-only: like {@link get} but throws if the class has no @Field decorators. Specs use it to
+     * assert metadata presence; production reads go through {@link get}/{@link hasOwn}.
+     */
+    require(cls: Function): RawClassMeta;
+    /**
+     * Test-only: inject RAW metadata directly, bypassing the @Field decorator path. The seal-pipeline
+     * specs use this to author DTOs programmatically; production metadata is written via {@link ensure}.
+     */
+    set(cls: Function, raw: RawClassMeta): void;
+    /** Test-only: drop a class's own RAW slot so specs can reset state between cases. */
+    delete(cls: Function): void;
+    /**
+     * True only when cls has its OWN RAW slot. A subclass without its own @Field decorators resolves
+     * `Class[Symbol.metadata]` to the parent's metadata via the class prototype chain; the dual own-check
+     * keeps inheritance merging from double-counting inherited fields.
+     */
+    hasOwn(cls: Function): boolean;
+    /**
+     * The RawPropertyMeta for `key` on a decorator metadata object — creating the RAW slot and the
+     * per-key default meta if absent. Called by @Field, which receives `context.metadata`.
+     *
+     * The own-RAW check is required: a subclass's metadata inherits the parent's RAW via the metadata
+     * prototype chain, so a bare assignment would pollute the parent. A fresh own RAW (null prototype)
+     * keeps child fields isolated.
+     */
+    ensure(metadata: MetaObject, key: string): RawPropertyMeta;
+}
+export { MetaStore };
+export declare const metaStore: MetaStore;

package/dist/src/metadata/meta-store.js

@@ -0,0 +1 @@
+class MetaStore{#z;constructor(z=I){this.#z=z}#D(z){return z[Symbol.metadata]??void 0}#G(z){if(!Object.hasOwn(z,Symbol.metadata))Object.defineProperty(z,Symbol.metadata,{value:{},writable:!0,configurable:!0,enumerable:!1});return z[Symbol.metadata]}get(z){return this.#D(z)?.[this.#z]}require(z){const D=this.get(z);if(D===void 0)throw new H(`${z.name||"<anonymous>"}: class has no @Field decorators`);return D}set(z,D){this.#G(z)[this.#z]=D}delete(z){if(Object.hasOwn(z,Symbol.metadata))delete z[Symbol.metadata][this.#z]}hasOwn(z){if(!Object.hasOwn(z,Symbol.metadata))return!1;const D=z[Symbol.metadata];return D!=null&&Object.hasOwn(D,this.#z)}ensure(z,D){if(!Object.hasOwn(z,this.#z))z[this.#z]=Object.create(null);const G=z[this.#z];return G[D]??={validation:[],transform:[],expose:[],exclude:null,type:null,flags:{}}}}import{BakerError as H}from"../common/index.js";import{RAW as I}from"../symbols.js";export{MetaStore};export const metaStore=new MetaStore;