@zipbul/baker 2.1.0 → 3.0.0

package/dist/src/errors.js

@@ -0,0 +1,52 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// BakerIssue — Individual field error (§12.2)
+// ─────────────────────────────────────────────────────────────────────────────
+// ─────────────────────────────────────────────────────────────────────────────
+// BakerIssueSet — Validation failure return (§12.2)
+// ─────────────────────────────────────────────────────────────────────────────
+/** Symbol tag for isBakerIssueSet() type guard — collision-proof discriminator */
+export const BAKER_ERROR = Symbol.for('baker:error');
+/**
+ * Type guard — narrows deserialize()/validate() result to BakerIssueSet.
+ *
+ * @example
+ * const result = await deserialize(UserDto, input);
+ * if (isBakerIssueSet(result)) {
+ *   result.errors // readonly BakerIssue[]
+ * } else {
+ *   result // UserDto
+ * }
+ */
+export function isBakerIssueSet(value) {
+    return (value != null &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        value[BAKER_ERROR] === true);
+}
+/** @internal — create BakerIssueSet object */
+export function toBakerIssueSet(errors) {
+    return { [BAKER_ERROR]: true, errors };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// BakerError — the single throw channel (§12.2)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * The single error thrown by baker for any developer/config/schema misuse — i.e. anything
+ * discoverable without external input. End-user input-data failures are NOT thrown; they are
+ * returned as a {@link BakerIssueSet}.
+ *
+ * Thrown when, e.g.:
+ * - deserialize()/serialize()/validate() is called on an unsealed class
+ * - configure() is called after seal(), or with an unknown key
+ * - seal-time metadata invariants fail (discriminator, Map keys, banned names, …)
+ * - per-call options contain unsupported keys
+ * - @Field receives a non-rule value, or a rule/transformer factory is misused
+ * - a user @Type/collectionValue thunk throws (wrapped, with the original error as `cause`)
+ * - an optional peer dependency (luxon/moment) is missing
+ */
+export class BakerError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'BakerError';
+    }
+}

package/dist/src/functions/check-call-options.d.ts

@@ -0,0 +1,8 @@
+import type { RuntimeOptions } from '../interfaces';
+/**
+ * @internal — validate per-call options object at public-API entry.
+ * `groups` is the only valid per-call key; everything else is rejected:
+ *   - seal-time keys (BakerConfig / SealOptions) → "move to configure({...})"
+ *   - any other key → "unknown call option"
+ */
+export declare function checkCallOptions(opts: unknown): RuntimeOptions | undefined;

package/dist/src/functions/check-call-options.js

@@ -0,0 +1,51 @@
+import { BakerError } from '../errors.js';
+const CALL_OPTION_KEYS = new Set(['groups']);
+const SEAL_TIME_KEYS = new Set([
+    // BakerConfig (public, configure-time)
+    'autoConvert',
+    'allowClassDefaults',
+    'stopAtFirstError',
+    'forbidUnknown',
+    'debug',
+    // SealOptions (internal, legacy aliases — same set covered by public names)
+    'enableImplicitConversion',
+    'exposeDefaultValues',
+    'whitelist',
+]);
+/**
+ * @internal — validate per-call options object at public-API entry.
+ * `groups` is the only valid per-call key; everything else is rejected:
+ *   - seal-time keys (BakerConfig / SealOptions) → "move to configure({...})"
+ *   - any other key → "unknown call option"
+ */
+export function checkCallOptions(opts) {
+    if (opts === undefined || opts === null) {
+        return undefined;
+    }
+    if (typeof opts !== 'object' || Array.isArray(opts)) {
+        throw new BakerError(`Call options must be a plain object. Received: ${Array.isArray(opts) ? 'array' : typeof opts}.`);
+    }
+    // Strict same-realm plain-object check.
+    // Accept: `{}` (proto === Object.prototype) and `Object.create(null)` (proto === null).
+    // Reject: every other prototype, including class instances whose `constructor.name` is
+    // renamed to 'Object' (trojan), built-ins (Date/Map/Set), cross-realm objects.
+    // Cross-realm consumers can normalize with `Object.assign({}, opts)` before calling.
+    const proto = Object.getPrototypeOf(opts);
+    if (proto !== null && proto !== Object.prototype) {
+        const ctorName = opts.constructor?.name ?? 'unknown';
+        throw new BakerError(`Call options must be a plain object literal. Received instance of ${ctorName}.`);
+    }
+    for (const key of Object.keys(opts)) {
+        if (CALL_OPTION_KEYS.has(key)) {
+            continue;
+        }
+        if (SEAL_TIME_KEYS.has(key)) {
+            throw new BakerError(`Option '${key}' is a seal-time setting and cannot be passed per-call. ` +
+                `Move it to configure({ ${key}: ... }) at app startup. ` +
+                `Per-call options: ${[...CALL_OPTION_KEYS].join(', ')}.`);
+        }
+        throw new BakerError(`Unknown per-call option '${key}'. Valid per-call options: ${[...CALL_OPTION_KEYS].join(', ')}. ` +
+            `Seal-time options go to configure({...}).`);
+    }
+    return opts;
+}

package/dist/src/functions/deserialize.d.ts

@@ -1,11 +1,19 @@
-import type { BakerErrors } from '../errors';
 import type { RuntimeOptions } from '../interfaces';
+import { type BakerIssueSet } from '../errors';
 /**
  * Converts input to a Class instance + validates.
- * - Auto-seals on first call (batches entire globalRegistry)
- * - Sync DTOs return directly, async DTOs return Promise
+ * - Requires `seal()` to be called beforehand; throws `BakerError` if not sealed
+ * - Sync DTOs return directly; async DTOs return Promise
  * - Success: T
- * - Validation failure: BakerErrors (use isBakerError() to narrow)
- * - Class without decorators: throws SealError
+ * - Validation failure: BakerIssueSet (use isBakerIssueSet() to narrow)
  */
-export declare function deserialize<T>(Class: new (...args: any[]) => T, input: unknown, options?: RuntimeOptions): T | BakerErrors | Promise<T | BakerErrors>;
+export declare function deserialize<T>(Class: new (...args: never[]) => T, input: unknown, options?: RuntimeOptions): T | BakerIssueSet | Promise<T | BakerIssueSet>;
+/**
+ * Sync-asserted deserialize. Throws `BakerError` if Class has any async rule/transform
+ * on the deserialize side.
+ */
+export declare function deserializeSync<T>(Class: new (...args: never[]) => T, input: unknown, options?: RuntimeOptions): T | BakerIssueSet;
+/**
+ * Async-asserted deserialize. Always returns Promise (sync DTOs are wrapped via Promise.resolve).
+ */
+export declare function deserializeAsync<T>(Class: new (...args: never[]) => T, input: unknown, options?: RuntimeOptions): Promise<T | BakerIssueSet>;

package/dist/src/functions/deserialize.js

@@ -0,0 +1,57 @@
+import { isErr } from '@zipbul/result';
+import { toBakerIssueSet, BakerError } from '../errors.js';
+import { ensureSealed } from '../seal/seal.js';
+import { checkCallOptions } from './check-call-options.js';
+export function deserialize(Class, input, options) {
+    const checkedOpts = checkCallOptions(options);
+    const sealed = ensureSealed(Class);
+    if (sealed.isAsync) {
+        return sealed.deserialize(input, checkedOpts).then((result) => {
+            if (isErr(result)) {
+                return toBakerIssueSet(result.data);
+            }
+            return result;
+        });
+    }
+    const result = sealed.deserialize(input, checkedOpts);
+    if (isErr(result)) {
+        return toBakerIssueSet(result.data);
+    }
+    return result;
+}
+/**
+ * Sync-asserted deserialize. Throws `BakerError` if Class has any async rule/transform
+ * on the deserialize side.
+ */
+export function deserializeSync(Class, input, options) {
+    const checkedOpts = checkCallOptions(options);
+    const sealed = ensureSealed(Class);
+    if (sealed.isAsync) {
+        throw new BakerError(`deserializeSync(${Class.name}): DTO has async rules/transforms. Use deserializeAsync() instead.`);
+    }
+    const result = sealed.deserialize(input, checkedOpts);
+    if (isErr(result)) {
+        return toBakerIssueSet(result.data);
+    }
+    return result;
+}
+/**
+ * Async-asserted deserialize. Always returns Promise (sync DTOs are wrapped via Promise.resolve).
+ */
+export function deserializeAsync(Class, input, options) {
+    const checkedOpts = checkCallOptions(options);
+    const sealed = ensureSealed(Class);
+    if (sealed.isAsync) {
+        return sealed.deserialize(input, checkedOpts).then((result) => {
+            if (isErr(result)) {
+                return toBakerIssueSet(result.data);
+            }
+            return result;
+        });
+    }
+    const result = sealed.deserialize(input, checkedOpts);
+    if (isErr(result)) {
+        return Promise.resolve(toBakerIssueSet(result.data));
+    }
+    return Promise.resolve(result);
+}

package/dist/src/functions/serialize.d.ts

@@ -1,9 +1,16 @@
 import type { RuntimeOptions } from '../interfaces';
 /**
  * Converts a Class instance to a plain object.
- * - Auto-seals on first call (batches entire globalRegistry)
- * - Sync DTOs return directly, async DTOs return Promise
+ * - Requires `seal()` to be called beforehand; throws `BakerError` if not sealed
+ * - Sync DTOs return directly; async DTOs return Promise
  * - No validation — always returns Record<string, unknown>
- * - Class without decorators: throws SealError
  */
 export declare function serialize<T>(instance: T, options?: RuntimeOptions): Record<string, unknown> | Promise<Record<string, unknown>>;
+/**
+ * Sync-asserted serialize. Throws `BakerError` if Class has any async transform on the serialize side.
+ */
+export declare function serializeSync<T>(instance: T, options?: RuntimeOptions): Record<string, unknown>;
+/**
+ * Async-asserted serialize. Always returns Promise (sync DTOs are wrapped via Promise.resolve).
+ */
+export declare function serializeAsync<T>(instance: T, options?: RuntimeOptions): Promise<Record<string, unknown>>;

package/dist/src/functions/serialize.js

@@ -0,0 +1,52 @@
+import { BakerError } from '../errors.js';
+import { ensureSealed } from '../seal/seal.js';
+import { checkCallOptions } from './check-call-options.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// serialize — Public API (§5.2)
+// ─────────────────────────────────────────────────────────────────────────────
+/** Boundary check shared by serialize / serializeSync / serializeAsync. */
+function resolveSerializer(instance, fnName) {
+    if (instance == null || typeof instance !== 'object') {
+        throw new BakerError(`${fnName}: expected a class instance, got ${instance === null ? 'null' : typeof instance}`);
+    }
+    const Class = instance.constructor;
+    if (typeof Class !== 'function') {
+        throw new BakerError(`${fnName}: instance has no constructor`);
+    }
+    // Reject plain objects and forged ones (e.g. `{ constructor: SomeDto }`): a real instance is
+    // `instanceof` its own constructor via the prototype chain; the `constructor` property alone
+    // (which anyone can set) is not trusted.
+    if (Class === Object || !(instance instanceof Class)) {
+        throw new BakerError(`${fnName}: received a plain object. Pass an instance of a DTO class decorated with @Field.`);
+    }
+    return ensureSealed(Class);
+}
+export function serialize(instance, options) {
+    const checkedOpts = checkCallOptions(options);
+    const sealed = resolveSerializer(instance, 'serialize');
+    return sealed.isSerializeAsync
+        ? sealed.serialize(instance, checkedOpts)
+        : sealed.serialize(instance, checkedOpts);
+}
+/**
+ * Sync-asserted serialize. Throws `BakerError` if Class has any async transform on the serialize side.
+ */
+export function serializeSync(instance, options) {
+    const checkedOpts = checkCallOptions(options);
+    const sealed = resolveSerializer(instance, 'serializeSync');
+    if (sealed.isSerializeAsync) {
+        const className = instance.constructor.name;
+        throw new BakerError(`serializeSync(${className}): DTO has async serialize transforms. Use serializeAsync() instead.`);
+    }
+    return sealed.serialize(instance, checkedOpts);
+}
+/**
+ * Async-asserted serialize. Always returns Promise (sync DTOs are wrapped via Promise.resolve).
+ */
+export function serializeAsync(instance, options) {
+    const checkedOpts = checkCallOptions(options);
+    const sealed = resolveSerializer(instance, 'serializeAsync');
+    return sealed.isSerializeAsync
+        ? sealed.serialize(instance, checkedOpts)
+        : Promise.resolve(sealed.serialize(instance, checkedOpts));
+}

package/dist/src/functions/validate.d.ts

@@ -1,13 +1,18 @@
-import type { BakerErrors } from '../errors';
-import type { EmittableRule } from '../types';
+import type { BakerIssueSet } from '../errors';
 import type { RuntimeOptions } from '../interfaces';
 /**
- * DTO-level validation — validates input against a decorated class.
- * Sync DTOs return directly, async DTOs return Promise.
+ * DTO-level validation — validates `input` against a decorated class's schema.
+ * Sync DTOs return directly; async DTOs return Promise. To validate a single primitive without a
+ * DTO, call the rule directly (e.g. `isEmail()(value)`).
  */
-export declare function validate<T>(Class: new (...args: any[]) => T, input: unknown, options?: RuntimeOptions): true | BakerErrors | Promise<true | BakerErrors>;
+declare function validate<T>(Class: new (...args: never[]) => T, input: unknown, options?: RuntimeOptions): true | BakerIssueSet | Promise<true | BakerIssueSet>;
 /**
- * Ad-hoc validation — validates a single value against one or more rules.
- * Sync rules return directly, async rules return Promise.
+ * Sync-asserted validate. Throws `BakerError` if Class has any async rule/transform
+ * on the deserialize/validate side. Use when caller code assumes sync return.
  */
-export declare function validate(input: unknown, ...rules: EmittableRule[]): true | BakerErrors | Promise<true | BakerErrors>;
+declare function validateSync<T>(Class: new (...args: never[]) => T, input: unknown, options?: RuntimeOptions): true | BakerIssueSet;
+/**
+ * Async-asserted validate. Always returns Promise (sync DTOs are wrapped via Promise.resolve).
+ */
+declare function validateAsync<T>(Class: new (...args: never[]) => T, input: unknown, options?: RuntimeOptions): Promise<true | BakerIssueSet>;
+export { validate, validateSync, validateAsync };

package/dist/src/functions/validate.js

@@ -0,0 +1,49 @@
+import { toBakerIssueSet, BakerError } from '../errors.js';
+import { ensureSealed } from '../seal/seal.js';
+import { checkCallOptions } from './check-call-options.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// validate — Public API (§5.3)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * DTO-level validation — validates `input` against a decorated class's schema.
+ * Sync DTOs return directly; async DTOs return Promise. To validate a single primitive without a
+ * DTO, call the rule directly (e.g. `isEmail()(value)`).
+ */
+function validate(Class, input, options) {
+    const checkedOpts = checkCallOptions(options);
+    const sealed = ensureSealed(Class);
+    if (sealed.isAsync) {
+        return sealed.validate(input, checkedOpts).then((result) => result === null ? true : toBakerIssueSet(result));
+    }
+    const result = sealed.validate(input, checkedOpts);
+    return result === null ? true : toBakerIssueSet(result);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// W14: strict sync/async variants — explicit intent at call site
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Sync-asserted validate. Throws `BakerError` if Class has any async rule/transform
+ * on the deserialize/validate side. Use when caller code assumes sync return.
+ */
+function validateSync(Class, input, options) {
+    const checkedOpts = checkCallOptions(options);
+    const sealed = ensureSealed(Class);
+    if (sealed.isAsync) {
+        throw new BakerError(`validateSync(${Class.name}): DTO has async rules/transforms. Use validateAsync() instead.`);
+    }
+    const result = sealed.validate(input, checkedOpts);
+    return result === null ? true : toBakerIssueSet(result);
+}
+/**
+ * Async-asserted validate. Always returns Promise (sync DTOs are wrapped via Promise.resolve).
+ */
+function validateAsync(Class, input, options) {
+    const checkedOpts = checkCallOptions(options);
+    const sealed = ensureSealed(Class);
+    if (sealed.isAsync) {
+        return sealed.validate(input, checkedOpts).then((r) => r === null ? true : toBakerIssueSet(r));
+    }
+    const result = sealed.validate(input, checkedOpts);
+    return Promise.resolve(result === null ? true : toBakerIssueSet(result));
+}
+export { validate, validateSync, validateAsync };

package/dist/src/interfaces.d.ts

@@ -16,7 +16,7 @@ export interface SealOptions {
     stopAtFirstError?: boolean;
     /**
      * true: reject undeclared fields. Uses the key set from mergeInheritance(Class) as the allowlist.
-     * @Exclude fields are also included in the whitelist — their presence is allowed but they are excluded from the result.
+     * `@Exclude` fields are also included in the whitelist — their presence is allowed but they are excluded from the result.
      * @default false
      */
     whitelist?: boolean;

package/dist/src/interfaces.js

@@ -0,0 +1,4 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// SealOptions — seal() global options (§1.4)
+// ─────────────────────────────────────────────────────────────────────────────
+export {};

package/dist/src/meta-access.d.ts

@@ -0,0 +1,19 @@
+import type { RawClassMeta, SealedExecutors } from './types';
+export declare function getSealed(cls: Function): SealedExecutors<unknown> | undefined;
+/** Same as getSealed but throws if the class is not sealed — for callers that establish the invariant elsewhere. */
+export declare function requireSealed(cls: Function): SealedExecutors<unknown>;
+export declare function setSealed(cls: Function, exec: SealedExecutors<unknown>): void;
+export declare function hasSealedOwn(cls: Function): boolean;
+export declare function deleteSealed(cls: Function): void;
+export declare function deleteRaw(cls: Function): void;
+export declare function getRaw(cls: Function): RawClassMeta | undefined;
+/** Same as getRaw but throws if the class has no @Field decorators — for callers that establish the invariant elsewhere. */
+export declare function requireRaw(cls: Function): RawClassMeta;
+export declare function setRaw(cls: Function, raw: RawClassMeta): 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 mergeInheritance from double-counting inherited fields.
+ */
+export declare function hasRawOwn(cls: Function): boolean;
+export declare function freezeRaw(cls: Function): void;

package/dist/src/meta-access.js

@@ -0,0 +1,75 @@
+import { RAW, SEALED } from './symbols.js';
+/** Returns the metadata object visible on cls (own or inherited via the class prototype chain). */
+function metaOf(cls) {
+    return cls[Symbol.metadata] ?? undefined;
+}
+/** Returns the class's own metadata object, creating one if absent. */
+function ensureOwnMeta(cls) {
+    if (!Object.hasOwn(cls, Symbol.metadata)) {
+        Object.defineProperty(cls, Symbol.metadata, {
+            value: {},
+            writable: true,
+            configurable: true,
+            enumerable: false,
+        });
+    }
+    return cls[Symbol.metadata];
+}
+export function getSealed(cls) {
+    return cls[SEALED];
+}
+/** Same as getSealed but throws if the class is not sealed — for callers that establish the invariant elsewhere. */
+export function requireSealed(cls) {
+    const v = cls[SEALED];
+    if (v === undefined) {
+        throw new Error(`${cls.name || '<anonymous>'}: class is not sealed`);
+    }
+    return v;
+}
+export function setSealed(cls, exec) {
+    cls[SEALED] = exec;
+}
+export function hasSealedOwn(cls) {
+    return Object.hasOwn(cls, SEALED);
+}
+export function deleteSealed(cls) {
+    delete cls[SEALED];
+}
+export function deleteRaw(cls) {
+    if (Object.hasOwn(cls, Symbol.metadata)) {
+        delete cls[Symbol.metadata][RAW];
+    }
+}
+export function getRaw(cls) {
+    return metaOf(cls)?.[RAW];
+}
+/** Same as getRaw but throws if the class has no @Field decorators — for callers that establish the invariant elsewhere. */
+export function requireRaw(cls) {
+    const v = getRaw(cls);
+    if (v === undefined) {
+        throw new Error(`${cls.name || '<anonymous>'}: class has no @Field decorators`);
+    }
+    return v;
+}
+export function setRaw(cls, raw) {
+    ensureOwnMeta(cls)[RAW] = raw;
+}
+/**
+ * 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 mergeInheritance from double-counting inherited fields.
+ */
+export function hasRawOwn(cls) {
+    if (!Object.hasOwn(cls, Symbol.metadata)) {
+        return false;
+    }
+    const meta = cls[Symbol.metadata];
+    return meta != null && Object.hasOwn(meta, RAW);
+}
+export function freezeRaw(cls) {
+    // Guard on own RAW: an inherited-only subclass must not freeze the parent's RAW.
+    if (!hasRawOwn(cls)) {
+        return;
+    }
+    Object.freeze(getRaw(cls));
+}

package/dist/src/registry.js

@@ -0,0 +1,8 @@
+/**
+ * Global registry — automatically registers classes with at least one decorator attached
+ *
+ * - Automatically called from ensureMeta()
+ * - seal() iterates this Set to seal all DTOs
+ * - Metadata is not stored here — used only as an index (which classes are registered)
+ */
+export const globalRegistry = new Set();

package/dist/src/rule-metadata.d.ts

@@ -0,0 +1,11 @@
+import type { EmittableRule, InternalRule, RulePlan } from './types';
+interface RuleMetadata {
+    emit: EmittableRule['emit'];
+    ruleName: string;
+    requiresType?: EmittableRule['requiresType'];
+    constraints?: Record<string, unknown>;
+    isAsync?: boolean;
+    plan?: RulePlan;
+}
+export declare function defineRuleMetadata(fn: InternalRule, meta: RuleMetadata): void;
+export {};

package/dist/src/rule-metadata.js

@@ -0,0 +1,17 @@
+export function defineRuleMetadata(fn, meta) {
+    const target = fn;
+    target.emit = meta.emit;
+    target.ruleName = meta.ruleName;
+    if (meta.requiresType !== undefined) {
+        target.requiresType = meta.requiresType;
+    }
+    if (meta.constraints !== undefined) {
+        target.constraints = meta.constraints;
+    }
+    if (meta.isAsync !== undefined) {
+        target.isAsync = meta.isAsync;
+    }
+    if (meta.plan) {
+        target.plan = meta.plan;
+    }
+}

package/dist/src/rule-plan.d.ts

@@ -0,0 +1,29 @@
+import type { EmitContext, InternalRule, RulePlan, RulePlanCheck, RulePlanExpr } from './types';
+type RulePlanCache = {
+    length?: string;
+    time?: string;
+};
+declare const planValue: () => RulePlanExpr;
+declare const planLength: (object?: RulePlanExpr) => RulePlanExpr;
+declare const planTime: (object?: RulePlanExpr) => RulePlanExpr;
+declare const planLiteral: (value: number) => RulePlanExpr;
+declare const planCompare: (left: RulePlanExpr, op: "<" | "<=" | ">" | ">=" | "===" | "!==", right: number | RulePlanExpr) => RulePlanCheck;
+declare const planOr: (...checks: RulePlanCheck[]) => RulePlanCheck;
+declare function makePlannedRule(options: {
+    name: string;
+    requiresType: 'string' | 'number' | 'boolean' | 'date' | 'array' | 'object';
+    constraints?: Record<string, unknown>;
+    plan: RulePlan;
+    validate: (value: unknown) => boolean;
+}): InternalRule;
+declare function makeRule(options: {
+    name: string;
+    validate: (value: unknown) => boolean | Promise<boolean>;
+    emit: (varName: string, ctx: EmitContext) => string;
+    requiresType?: 'string' | 'number' | 'boolean' | 'date' | 'array' | 'object';
+    constraints?: Record<string, unknown>;
+    isAsync?: boolean;
+    plan?: RulePlan;
+}): InternalRule;
+declare function emitRulePlan(varName: string, ctx: EmitContext, ruleName: string, plan: RulePlan, cache?: RulePlanCache, insideTypeGate?: boolean): string;
+export { planValue, planLength, planTime, planLiteral, planCompare, planOr, makePlannedRule, makeRule, emitRulePlan };

package/dist/src/rule-plan.js

@@ -0,0 +1,117 @@
+import { defineRuleMetadata } from './rule-metadata.js';
+const planValue = () => ({ kind: 'value' });
+const planLength = (object = planValue()) => ({
+    kind: 'member',
+    object,
+    property: 'length',
+});
+const planTime = (object = planValue()) => ({
+    kind: 'call0',
+    object,
+    method: 'getTime',
+});
+const planLiteral = (value) => ({ kind: 'literal', value });
+const planCompare = (left, op, right) => ({
+    kind: 'compare',
+    left,
+    op,
+    right: typeof right === 'number' ? planLiteral(right) : right,
+});
+const planOr = (...checks) => ({ kind: 'or', checks });
+function makePlannedRule(options) {
+    const inner = {
+        name: options.name,
+        requiresType: options.requiresType,
+        plan: options.plan,
+        validate: options.validate,
+        emit: (varName, ctx) => emitRulePlan(varName, ctx, options.name, options.plan, undefined, ctx.insideTypeGate),
+    };
+    if (options.constraints !== undefined) {
+        inner.constraints = options.constraints;
+    }
+    return makeRule(inner);
+}
+function makeRule(options) {
+    const fn = ((value) => options.validate(value));
+    const meta = {
+        emit: options.emit,
+        ruleName: options.name,
+        constraints: options.constraints ?? {},
+    };
+    if (options.requiresType !== undefined) {
+        meta.requiresType = options.requiresType;
+    }
+    if (options.isAsync !== undefined) {
+        meta.isAsync = options.isAsync;
+    }
+    if (options.plan !== undefined) {
+        meta.plan = options.plan;
+    }
+    defineRuleMetadata(fn, meta);
+    return fn;
+}
+function emitRulePlan(varName, ctx, ruleName, plan, cache, insideTypeGate) {
+    const failure = insideTypeGate ? stripSelfComparison(plan.failure) : plan.failure;
+    return `if (${emitPlanCheck(failure, varName, cache)}) ${ctx.fail(ruleName)};`;
+}
+/** Strip `x !== x` / `getTime() !== getTime()` self-comparison guards — redundant inside type gate */
+function stripSelfComparison(check) {
+    if (check.kind === 'compare') {
+        return check;
+    }
+    const filtered = check.checks.filter(c => !isSelfComparison(c));
+    if (filtered.length === 0) {
+        return check;
+    } // safety: don't strip everything
+    if (filtered.length === 1) {
+        return filtered[0];
+    }
+    return { kind: check.kind, checks: filtered };
+}
+function isSelfComparison(check) {
+    if (check.kind !== 'compare' || check.op !== '!==') {
+        return false;
+    }
+    return exprEqual(check.left, check.right);
+}
+function exprEqual(a, b) {
+    if (a.kind !== b.kind) {
+        return false;
+    }
+    switch (a.kind) {
+        case 'value':
+            return true;
+        case 'literal':
+            return a.value === b.value;
+        case 'member':
+            return exprEqual(a.object, b.object);
+        case 'call0':
+            return a.method === b.method && exprEqual(a.object, b.object);
+        default:
+            // Compile-time exhaustiveness: adding a RulePlanExpr.kind without a case fails to compile here.
+            return a;
+    }
+}
+function emitPlanCheck(check, varName, cache) {
+    if (check.kind === 'compare') {
+        return `${emitPlanExpr(check.left, varName, cache)} ${check.op} ${emitPlanExpr(check.right, varName, cache)}`;
+    }
+    const joiner = check.kind === 'and' ? ' && ' : ' || ';
+    return `(${check.checks.map(part => emitPlanCheck(part, varName, cache)).join(joiner)})`;
+}
+function emitPlanExpr(expr, varName, cache) {
+    switch (expr.kind) {
+        case 'value':
+            return varName;
+        case 'literal':
+            return String(expr.value);
+        case 'member':
+            return cache?.length ?? `${emitPlanExpr(expr.object, varName, cache)}.length`;
+        case 'call0':
+            return cache?.time ?? `${emitPlanExpr(expr.object, varName, cache)}.getTime()`;
+        default:
+            // Compile-time exhaustiveness: adding a RulePlanExpr.kind without a case fails to compile here.
+            return expr;
+    }
+}
+export { planValue, planLength, planTime, planLiteral, planCompare, planOr, makePlannedRule, makeRule, emitRulePlan };