@fougere/schema 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fougere contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+# @fougere/schema
+> The entity and its 4 axes
+An entity declares fields; every field carries four independent axes — `shape` (which
+IS JSON Schema), `role` (primary, ref…), `lifecycle` (who writes the value, and when)
+and `boundary` (readOnly / writeOnly). Everything else in Fougere is a projection of
+them: tables, GraphQL types, form contracts, validation.
+
+This package names no adapter and depends on no engine.
+
+```ts
+import { entity, primary, text, auto, readOnly } from '@fougere/schema';
+
+export default class Post extends entity({
+  id: primary(),
+  title: text(),
+  authorId: readOnly(text()),
+  createdAt: auto(),
+}) {}
+
+Post.validate({ title: 'Bonjour' }); // → { success, data } | { success: false, errors }
+```
+
+## Installation
+```bash
+pnpm add @fougere/schema
+```
+
+---
+
+Part of [Fougere](https://github.com/chok/fougere) — one schema, a gradient from
+monolith to distributed, the same user code.
+Reference documentation: [the site](https://chok.github.io/fougere/) (en/fr).

package/dist/entity.d.ts

@@ -0,0 +1,117 @@
+import { type Field, type Fields } from "./field/index.js";
+import type { Hints } from "./hints.js";
+import { type CompositeUnique, type EntityDeclarations } from "./unique.js";
+import { type ValidationResult, type ValidateOptions } from "./projections/validation.js";
+import type { StandardSchemaV1 } from "./projections/standard.js";
+/** The data shape an entity carries — every field present. */
+export type SchemaViewInfer<TFields extends Fields> = {
+    [K in keyof TFields]: TFields[K] extends Field<infer T, any> ? T : never;
+};
+/** Keys whose value is auto-supplied at creation (primary/auto/default/optional). */
+type AutoKeys<TFields extends Fields> = {
+    [K in keyof TFields]: TFields[K] extends Field<any, true> ? K : never;
+}[keyof TFields];
+/**
+ * Constructor input — like the data shape, but auto-at-creation fields are
+ * optional. `new Post({ title })` works without passing the generated id.
+ */
+export type CtorInput<TFields extends Fields> = Omit<SchemaViewInfer<TFields>, AutoKeys<TFields>> & Partial<Pick<SchemaViewInfer<TFields>, AutoKeys<TFields>>>;
+/**
+ * Fields as seen by a patch input: every field becomes OMISSIBLE (presence axis,
+ * `A = true` → optional in the input), but its nullity does NOT change — `null`
+ * stays governed by the base field (`optional()`). A patch may leave a field
+ * untouched; it may not erase a non-nullable field.
+ */
+type PatchFields<TFields extends Fields> = {
+    [K in keyof TFields]: TFields[K] extends Field<infer T, any> ? Field<T, true> : never;
+};
+/**
+ * A schema constructor returned by Entity.pick(), omit(), partial(), extend().
+ *
+ * - Usable as a base class: `class X extends Post.pick('id') {}`
+ * - Instance type = the data shape (no Infer needed)
+ * - Has static methods: getFields(), validate(), pick(), omit(), partial(), extend()
+ */
+export interface SchemaConstructor<TFields extends Fields> {
+    new (data: CtorInput<TFields>): SchemaViewInfer<TFields>;
+    readonly name: string;
+    readonly '~standard': StandardSchemaV1.Props<Record<string, unknown>, SchemaViewInfer<TFields>>;
+    /** The original Entity class this derivation was created from (undefined for compose() results). */
+    readonly source?: abstract new (...args: never[]) => unknown;
+    getFields(): TFields;
+    /**
+     * Per-consumer hints passed as the 2nd arg of `entity()`. Derivations carry them:
+     * pick/omit filter to surviving fields, rename remaps keys, partial/extend pass through.
+     */
+    getHints(): Hints<TFields> | undefined;
+    /**
+     * Field groups that are unique together, from the 2nd arg of `entity()`.
+     * Derivations carry them; a group loses a member and the group is dropped.
+     */
+    getUnique(): CompositeUnique<TFields> | undefined;
+    /** Validation options of this view (e.g. `patch` set by `partial()`). Derivations carry them. */
+    getOpts(): ValidateOptions;
+    validate(input: unknown): ValidationResult<SchemaViewInfer<TFields>>;
+    from(data: Record<string, unknown>): SchemaViewInfer<TFields>;
+    pick<K extends string & keyof TFields>(...keys: K[]): SchemaConstructor<Pick<TFields, K>>;
+    omit<K extends string & keyof TFields>(...keys: K[]): SchemaConstructor<Omit<TFields, K>>;
+    partial(): SchemaConstructor<PatchFields<TFields>>;
+    extend<E extends Fields>(extra: E): SchemaConstructor<TFields & E>;
+    /** Give an anonymous derivation an explicit runtime name. */
+    named(name: string): SchemaConstructor<TFields>;
+    rename(mapping: Partial<Record<string & keyof TFields, string>>): SchemaConstructor<Fields>;
+}
+/** Create a schema constructor from a field record. */
+/**
+ * The runtime name a derivation carries when no class declaration named it.
+ *
+ * `class Post extends entity({…}) {}` is named by its declaration; `User.pick('id')` has
+ * only the factory's own class to be named after. A reader — the scanner, notably — needs
+ * to tell one from the other, so the name is stamped from here rather than read off a
+ * class whose identifier someone could rename without noticing the other end.
+ */
+export declare const ANONYMOUS_SCHEMA_NAME = "Schema";
+export declare function createSchemaConstructor<TFields extends Fields>(fields: TFields, source?: abstract new (...args: never[]) => unknown, hints?: Hints<TFields>, opts?: ValidateOptions, unique?: CompositeUnique<Fields>): SchemaConstructor<TFields>;
+/**
+ * Define an entity — the factory that produces a schema-carrying class.
+ *
+ * ```ts
+ * class Post extends entity({ id: primary(), title: text({ min: 1 }) }) {}
+ *
+ * new Post({ id, title })   // real instance, data-typed (NOT a bag of Fields)
+ * Post.getFields()          // metadata, no instantiation
+ * Post.pick('title')        // derived view, same static API
+ * function publish(p: Post) // `Post` IS the data type — no Infer needed
+ * ```
+ *
+ * The class carries data + schema metadata only. No business behaviour lives on
+ * an entity — that belongs to handlers/commands (keeps form and behaviour apart).
+ *
+ * An optional 2nd argument carries per-consumer hints (see {@link Hints}) for the
+ * irreducible bits a neutral field can't express — only adapters present in the
+ * compilation are accepted; the field declarations themselves stay adapter-blind.
+ */
+export declare function entity<TFields extends Fields>(fields: TFields, declarations?: EntityDeclarations<TFields>): SchemaConstructor<TFields>;
+/** Anything that exposes its fields — an `entity()` class or a SchemaConstructor. */
+interface HasFields {
+    getFields(): Fields;
+}
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+type FieldsFrom<T> = T extends {
+    getFields(): infer F;
+} ? F : Fields;
+/**
+ * Compose multiple entities/schemas into a single SchemaConstructor.
+ *
+ * ```ts
+ * class User extends compose(UserBase, Timestamps) {}
+ * class SearchPosts extends compose(Post.pick('title'), Pagination) {}
+ * ```
+ *
+ * One merge law for EVERYTHING a schema carries — fields, hints, opts: left to
+ * right, later sources override earlier ones on conflict (hints merge per adapter,
+ * per field key). Use .rename() before compose() to avoid field conflicts.
+ */
+export declare function compose<T extends HasFields[]>(...sources: T): SchemaConstructor<UnionToIntersection<FieldsFrom<T[number]>> & Fields>;
+export {};
+//# sourceMappingURL=entity.d.ts.map

package/dist/entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../src/entity.ts"],"names":[],"mappings":"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"}

package/dist/entity.js

@@ -0,0 +1,285 @@
+import { resolveBoundary } from "./field/index.js";
+import { deriveUnique, deriveUniqueRoles, projectUniqueOntoFields } from "./unique.js";
+import { checkValue, validateFields } from "./projections/validation.js";
+// ─── Factory ────────────────────────────────────
+/**
+ * The single "trust me" point. The schema class is built from a runtime field-map:
+ * its instances get their shape from the constructor *data* (`Object.assign`), not
+ * from members written in the class body, and its derivations rebuild maps on the
+ * fly. TypeScript sees an empty class, so it cannot prove this matches the precise
+ * generic type — one assertion declares that it does. Every schema/mixin library
+ * (Effect's `Schema.Class`, ts-mixer, …) carries this same one line. Keeping it
+ * here, named and explained, keeps it the *only* such assertion in the package.
+ */
+function asSchemaConstructor(impl) {
+    return impl;
+}
+/**
+ * Carry hints across a field-key transform — the schema-level twin of `cloneField`'s
+ * invariant: a derivation preserves everything it doesn't explicitly change. `transform`
+ * maps an old key to its new name, or to `undefined` when the field is dropped; each
+ * adapter's per-field hints follow their fields.
+ */
+function deriveHints(hints, transform) {
+    if (!hints)
+        return undefined;
+    const out = {};
+    for (const [adapter, perField] of Object.entries(hints)) {
+        if (!perField || typeof perField !== 'object')
+            continue;
+        const mapped = {};
+        for (const [key, hint] of Object.entries(perField)) {
+            const next = transform(key);
+            if (next !== undefined)
+                mapped[next] = hint;
+        }
+        if (Object.keys(mapped).length)
+            out[adapter] = mapped;
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+/**
+ * Refuse a key the schema does not carry, naming it and what was expected — the twin of
+ * `assertListOptions` in `@fougere/core`, applied to the derivation algebra.
+ *
+ * `pick` skipped an unknown key and `omit` filtered on a key nothing matched, so a typo
+ * was silently obeyed. `pick('titel')` returned a view without the field, and — the
+ * dangerous half — `omit('ownerUserID')` removed NOTHING: the field stayed in the input
+ * view, so the façade's unknown-key refusal no longer applied to it, and a client could
+ * write the very field the view was written to close. Measured: the view accepted
+ * `ownerUserId: 'someone-else'`.
+ *
+ * TypeScript catches this at the call site when the key is a literal. It does not when
+ * the keys come from a variable, from JSON, or across a package boundary — and a view
+ * that quietly widens is not a thing to leave to the type-checker alone.
+ */
+function assertKnownKeys(operation, keys, fields) {
+    const strangers = keys.filter((key) => !(key in fields));
+    if (strangers.length === 0)
+        return;
+    throw new Error(`${operation}(): unknown field ${strangers.map((s) => `\`${s}\``).join(', ')}. ` +
+        `This schema carries ${Object.keys(fields).join(', ')}.`);
+}
+/** Create a schema constructor from a field record. */
+/**
+ * The runtime name a derivation carries when no class declaration named it.
+ *
+ * `class Post extends entity({…}) {}` is named by its declaration; `User.pick('id')` has
+ * only the factory's own class to be named after. A reader — the scanner, notably — needs
+ * to tell one from the other, so the name is stamped from here rather than read off a
+ * class whose identifier someone could rename without noticing the other end.
+ */
+export const ANONYMOUS_SCHEMA_NAME = 'Schema';
+export function createSchemaConstructor(fields, source, hints, opts = {}, unique) {
+    class Schema {
+        /** Trusted constructor — assigns already-shaped data. Validate untrusted input via `validate()`/`from()` first. */
+        constructor(data) {
+            if (data)
+                Object.assign(this, data);
+        }
+        static get ['~standard']() {
+            return {
+                version: 1,
+                vendor: 'fougere',
+                validate(value) {
+                    const result = validateFields(fields, value, '', opts);
+                    if (result.success) {
+                        return { value: result.data };
+                    }
+                    return {
+                        issues: result.errors.map((e) => ({
+                            message: e.message,
+                            path: e.path && e.path !== '.' ? e.path.split('.').map((key) => ({ key })) : undefined,
+                        })),
+                    };
+                },
+            };
+        }
+        static source = source;
+        static getFields() {
+            return fields;
+        }
+        static getHints() {
+            return hints;
+        }
+        static getUnique() {
+            return unique;
+        }
+        static getOpts() {
+            return opts;
+        }
+        static validate(input) {
+            return validateFields(fields, input, '', opts);
+        }
+        static from(data) {
+            // Trusted projection: keep known keys, drop the rest. Runs the boundary's decode
+            // (the same wire→domain step validate() applies) so the returned value matches
+            // its declared type — a date-string in becomes the `Date` the type promises.
+            // Best-effort: a value that fails to decode is kept as-is rather than dropped.
+            const result = {};
+            for (const [key, field] of Object.entries(fields)) {
+                if (!(key in data))
+                    continue;
+                const value = data[key];
+                if (value === null || value === undefined) {
+                    result[key] = value;
+                    continue;
+                }
+                const decoded = resolveBoundary(field).decode(value);
+                result[key] = 'error' in decoded ? value : decoded.value;
+            }
+            return result;
+        }
+        // Every derivation carries hints and opts — same invariant as cloneField, one
+        // level up: change the fields you mean, keep everything else the view holds.
+        //
+        // `source ?? this` records WHERE a view came from, once, at the first derivation:
+        // `this` is the class the static was called on (`Post`), and a view of a view keeps
+        // the origin rather than the intermediate. The slot existed and was only ever
+        // propagated — `entity()` passes `undefined` — so `describe` read an empty field and
+        // titled a view `Schema`, the anonymous class. One reader assumed it; now two do
+        // (GraphQL names `PostStatus` from it, so an input view and the type share one enum).
+        static pick(...keys) {
+            assertKnownKeys('pick', keys, fields);
+            const picked = {};
+            for (const key of keys) {
+                if (fields[key])
+                    picked[key] = fields[key];
+            }
+            const survives = (k) => (keys.includes(k) ? k : undefined);
+            return createSchemaConstructor(deriveUniqueRoles(picked, survives), source ?? this, deriveHints(hints, survives), opts, deriveUnique(unique, survives));
+        }
+        static omit(...keys) {
+            assertKnownKeys('omit', keys, fields);
+            const omitted = {};
+            for (const [key, value] of Object.entries(fields)) {
+                if (!keys.includes(key))
+                    omitted[key] = value;
+            }
+            const survives = (k) => (keys.includes(k) ? undefined : k);
+            return createSchemaConstructor(deriveUniqueRoles(omitted, survives), source ?? this, deriveHints(hints, survives), opts, deriveUnique(unique, survives));
+        }
+        static partial() {
+            // patch mode: an unsent field is omitted ("don't touch"), enforced by
+            // ValidateOptions.patch — the fields themselves are untouched, so `null`
+            // stays legal only where the base field is nullable. partial() moves the
+            // presence axis, never the nullity axis.
+            return createSchemaConstructor({ ...fields }, source ?? this, hints, { ...opts, patch: true }, unique);
+        }
+        static extend(extra) {
+            return createSchemaConstructor({ ...fields, ...extra }, source ?? this, hints, opts, unique);
+        }
+        static named(name) {
+            if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name)) {
+                throw new Error(`named(): \`${name}\` is not a valid class name.`);
+            }
+            // It renames in place, so it may only name what has no name. On a declared class
+            // `Post.named('Other')` would silently retarget its table, its GraphQL type and
+            // its registration key — every projection reads this name.
+            if (this.name !== ANONYMOUS_SCHEMA_NAME) {
+                throw new Error(`named(): \`${this.name}\` is already named by its class declaration.`);
+            }
+            Object.defineProperty(this, 'name', { value: name, configurable: true });
+            return this;
+        }
+        static rename(mapping) {
+            assertKnownKeys('rename', Object.keys(mapping), fields);
+            const renamed = {};
+            for (const [key, field] of Object.entries(fields)) {
+                renamed[mapping[key] ?? key] = field;
+            }
+            const remap = (k) => mapping[k] ?? k;
+            return createSchemaConstructor(deriveUniqueRoles(renamed, remap), source ?? this, deriveHints(hints, remap), opts, deriveUnique(unique, remap));
+        }
+    }
+    Object.defineProperty(Schema, 'name', { value: ANONYMOUS_SCHEMA_NAME, configurable: true });
+    return asSchemaConstructor(Schema);
+}
+// ─── Public entry ───────────────────────────────
+/**
+ * Define an entity — the factory that produces a schema-carrying class.
+ *
+ * ```ts
+ * class Post extends entity({ id: primary(), title: text({ min: 1 }) }) {}
+ *
+ * new Post({ id, title })   // real instance, data-typed (NOT a bag of Fields)
+ * Post.getFields()          // metadata, no instantiation
+ * Post.pick('title')        // derived view, same static API
+ * function publish(p: Post) // `Post` IS the data type — no Infer needed
+ * ```
+ *
+ * The class carries data + schema metadata only. No business behaviour lives on
+ * an entity — that belongs to handlers/commands (keeps form and behaviour apart).
+ *
+ * An optional 2nd argument carries per-consumer hints (see {@link Hints}) for the
+ * irreducible bits a neutral field can't express — only adapters present in the
+ * compilation are accepted; the field declarations themselves stay adapter-blind.
+ */
+export function entity(fields, declarations) {
+    // This is the only place that knows both the field KEYS and the entity's declarations,
+    // so it is where a composite group becomes readable on each member's role axis. The
+    // declaration remains the source — `getUnique()` still answers it.
+    const projected = projectUniqueOntoFields(fields, declarations?.unique);
+    assertDefaultsAreValid(projected);
+    return createSchemaConstructor(projected, undefined, declarations?.hints, {}, declarations?.unique);
+}
+/**
+ * A declared default must satisfy its own shape — checked once, here.
+ *
+ * `applyCreate` writes it into every row without passing the client judge, which is
+ * correct: the judge asks "is what the CALLER sent legal", and this value comes from the
+ * author. But that means `text({ min: 5, default: 'ab' })` produced rows the entity's own
+ * `validate` refuses — silently on a store that judges nothing, as a constraint violation
+ * on SQL, as a validator error on MongoDB. Three symptoms, one cause, none of them naming
+ * it.
+ *
+ * The value is static and so is the shape, so the answer is static: it belongs at the
+ * declaration, not on every write. `oneOf` closes its own case in the type system; this
+ * catches what no type can — a bound, a pattern, a format.
+ */
+function assertDefaultsAreValid(fields) {
+    for (const [name, field] of Object.entries(fields)) {
+        const create = field.lifecycle?.create;
+        if (typeof create !== 'object' || create === null || !('value' in create))
+            continue;
+        const checked = checkValue(field, create.value);
+        if ('error' in checked) {
+            throw new Error(`Field '${name}': the declared default ${JSON.stringify(create.value)} `
+                + `is not a legal value for it — ${checked.error}. It would be written into every row `
+                + `without passing the judge.`);
+        }
+    }
+}
+/**
+ * Compose multiple entities/schemas into a single SchemaConstructor.
+ *
+ * ```ts
+ * class User extends compose(UserBase, Timestamps) {}
+ * class SearchPosts extends compose(Post.pick('title'), Pagination) {}
+ * ```
+ *
+ * One merge law for EVERYTHING a schema carries — fields, hints, opts: left to
+ * right, later sources override earlier ones on conflict (hints merge per adapter,
+ * per field key). Use .rename() before compose() to avoid field conflicts.
+ */
+export function compose(...sources) {
+    const merged = {};
+    const mergedHints = {};
+    let mergedOpts = {};
+    for (const source of sources) {
+        Object.assign(merged, source.getFields());
+        const carrier = source;
+        const hints = carrier.getHints?.();
+        if (hints) {
+            for (const [adapter, perField] of Object.entries(hints)) {
+                if (!perField || typeof perField !== 'object')
+                    continue;
+                mergedHints[adapter] = { ...mergedHints[adapter], ...perField };
+            }
+        }
+        mergedOpts = { ...mergedOpts, ...carrier.getOpts?.() };
+    }
+    const hints = Object.keys(mergedHints).length ? mergedHints : undefined;
+    return asSchemaConstructor(createSchemaConstructor(merged, undefined, hints, mergedOpts));
+}
+//# sourceMappingURL=entity.js.map

package/dist/entity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.js","sourceRoot":"","sources":["../src/entity.ts"],"names":[],"mappings":"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"}

package/dist/field/boundary.d.ts

@@ -0,0 +1,75 @@
+import type { AnyField } from './field.js';
+/**
+ * Axis 4 · boundary — HOW AND IN WHICH DIRECTION a value crosses the CLIENT frontier.
+ *
+ * ⚠️ SCOPE — this axis covers the client frontier ONLY. A direction is meaningless
+ * unless stated relative to a centre, and this one is relative to the domain facing a
+ * client: `in` parses a request, `out` renders a response. It does NOT cover storage —
+ * no storage adapter reads it, which is exactly why `bool`, `list`, `json` and a judged
+ * `date` cannot be written today (they reach the driver unconverted). The domain↔column
+ * conversion belongs to the storage adapter, and naming that second frontier is an open
+ * design question — see the axes study.
+ *
+ * The normal form is indexed by DIRECTION. Each direction carries one of the two facets
+ * of the same frontier:
+ * a conversion (`{ decode }` / `{ encode }`, a NAMED rule) or the permission
+ * token `'closed'` — read-only closes `in` (never accepted from a client),
+ * write-only closes `out` (never emitted, e.g. a password). A key absent →
+ * that direction is open, identity conversion. Declarative and named — never
+ * an opaque closure, so adapters stay able to read what a field does.
+ *
+ * Two directional registries (decoders, encoders) are the pure base; an alias is
+ * just a named pair. A field rarely declares a boundary: the default is DERIVED
+ * from `shape` (convention over config). A declared boundary overrides that
+ * default PER DIRECTION — closing `out` on a date field leaves the derived
+ * isoDate decode on `in` intact.
+ */
+/** Inbound: a supplied wire value → domain value. May fail (transformOrFail-style). */
+export type Decoder = (value: unknown) => {
+    value: unknown;
+} | {
+    error: string;
+};
+/** Outbound: a domain value → wire value. Total — a valid domain value always encodes. */
+export type Encoder = (value: unknown) => unknown;
+/** The normal form, indexed by direction. Either direction absent → open, identity. */
+export interface Boundary {
+    in?: 'closed' | {
+        decode: string;
+    };
+    out?: 'closed' | {
+        encode: string;
+    };
+}
+/**
+ * What a field may carry on its `boundary` slot:
+ * - a string — an ALIAS, resolved to a {@link Boundary} in the alias registry
+ * - a {@link Boundary} — directional rules directly (allows asymmetry)
+ *
+ * The bare string literals are the built-in aliases; `(string & {})` keeps
+ * autocomplete on them while leaving the set open to `registerBoundaryAlias`.
+ */
+export type BoundaryRef = 'isoDate' | (string & {}) | Boundary;
+export declare function registerDecoder(name: string, fn: Decoder): void;
+export declare function registerEncoder(name: string, fn: Encoder): void;
+/** Register a named boundary — the alias a field can reference. */
+export declare function registerBoundaryAlias(name: string, boundary: Boundary): void;
+/** The field's DECLARED boundary in normal form (alias resolved) — no derived default. */
+export declare function declaredBoundary(field: AnyField): Boundary;
+/**
+ * The field's EFFECTIVE boundary: declared rules win per direction, the
+ * shape-derived default fills the rest. This is the reader every consumer of
+ * the axis goes through — `boundaryOf(f).in === 'closed'` is the read-only
+ * test, `.out === 'closed'` the write-only one.
+ */
+export declare function boundaryOf(field: AnyField): Boundary;
+/**
+ * A field's effective conversion functions. The permission facet is not read
+ * here: a `'closed'` direction converts as identity — its rejection/omission
+ * happens in the readers (validation, encode) BEFORE any conversion.
+ */
+export declare function resolveBoundary(field: AnyField): {
+    decode: Decoder;
+    encode: Encoder;
+};
+//# sourceMappingURL=boundary.d.ts.map

package/dist/field/boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary.d.ts","sourceRoot":"","sources":["../../src/field/boundary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG3C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,uFAAuF;AACvF,MAAM,MAAM,OAAO,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AACjF,0FAA0F;AAC1F,MAAM,MAAM,OAAO,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;AAElD,uFAAuF;AACvF,MAAM,WAAW,QAAQ;IACvB,EAAE,CAAC,EAAE,QAAQ,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACnC,GAAG,CAAC,EAAE,QAAQ,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACrC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,GAAG,QAAQ,CAAC;AAQ/D,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,GAAG,IAAI,CAE/D;AACD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,GAAG,IAAI,CAE/D;AACD,mEAAmE;AACnE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAE5E;AAgCD,0FAA0F;AAC1F,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAS1D;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAIpD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAKrF"}

package/dist/field/boundary.js

@@ -0,0 +1,76 @@
+import { anatomy } from './shape.js';
+// ─── Registries (open, extensible — same spirit as FougereHints) ──
+const decoders = new Map();
+const encoders = new Map();
+const aliases = new Map();
+export function registerDecoder(name, fn) {
+    decoders.set(name, fn);
+}
+export function registerEncoder(name, fn) {
+    encoders.set(name, fn);
+}
+/** Register a named boundary — the alias a field can reference. */
+export function registerBoundaryAlias(name, boundary) {
+    aliases.set(name, boundary);
+}
+// ─── Built-ins ───────────────────────────────────────
+const identityDecoder = (value) => ({ value });
+const identityEncoder = (value) => value;
+// `isoDate`: the only non-identity built-in. Inbound accepts a Date or an ISO-ish
+// string and yields a Date; outbound yields an ISO string. Validity is already
+// guaranteed by `shape` (the date predicate) before decode runs.
+registerDecoder('isoDate', (value) => {
+    if (value instanceof Date)
+        return { value };
+    if (typeof value === 'string') {
+        const d = new Date(value);
+        return Number.isNaN(d.getTime()) ? { error: 'Invalid date' } : { value: d };
+    }
+    return { error: 'Expected a date' };
+});
+registerEncoder('isoDate', (value) => value instanceof Date ? value.toISOString() : value);
+registerBoundaryAlias('isoDate', { in: { decode: 'isoDate' }, out: { encode: 'isoDate' } });
+/** Default boundary derived from a field's shape. A date-time string → isoDate, else identity. */
+function defaultBoundaryForShape(shape) {
+    const base = anatomy(shape).base;
+    if (base && base.type === 'string' && base.format === 'date-time')
+        return aliases.get('isoDate');
+    return {};
+}
+// ─── Resolution ──────────────────────────────────────
+/** The field's DECLARED boundary in normal form (alias resolved) — no derived default. */
+export function declaredBoundary(field) {
+    const ref = field.boundary;
+    if (ref === undefined)
+        return {};
+    if (typeof ref === 'string') {
+        const alias = aliases.get(ref);
+        if (!alias)
+            throw new Error(`Unknown boundary alias: '${ref}'`);
+        return alias;
+    }
+    return ref;
+}
+/**
+ * The field's EFFECTIVE boundary: declared rules win per direction, the
+ * shape-derived default fills the rest. This is the reader every consumer of
+ * the axis goes through — `boundaryOf(f).in === 'closed'` is the read-only
+ * test, `.out === 'closed'` the write-only one.
+ */
+export function boundaryOf(field) {
+    const declared = declaredBoundary(field);
+    const derived = defaultBoundaryForShape(field.shape);
+    return { in: declared.in ?? derived.in, out: declared.out ?? derived.out };
+}
+/**
+ * A field's effective conversion functions. The permission facet is not read
+ * here: a `'closed'` direction converts as identity — its rejection/omission
+ * happens in the readers (validation, encode) BEFORE any conversion.
+ */
+export function resolveBoundary(field) {
+    const boundary = boundaryOf(field);
+    const decode = typeof boundary.in === 'object' ? decoders.get(boundary.in.decode) : undefined;
+    const encode = typeof boundary.out === 'object' ? encoders.get(boundary.out.encode) : undefined;
+    return { decode: decode ?? identityDecoder, encode: encode ?? identityEncoder };
+}
+//# sourceMappingURL=boundary.js.map

package/dist/field/boundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary.js","sourceRoot":"","sources":["../../src/field/boundary.ts"],"names":[],"mappings":"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"}