@fougere/schema 0.6.0-alpha.0 → 0.7.0-alpha.0

package/src/{schema/axis → axis}/Axis.ts

@@ -1,12 +1,12 @@
 import { roleAxis } from './role/RoleAxis.js';
 import { lifecycleAxis } from './lifecycle/LifecycleAxis.js';
 import { boundaryAxis } from './boundary/BoundaryAxis.js';
-import type { ValidationError } from '../../judge/result.js';
+import type { ValidationError } from '../validation.js';
 
 export interface Axis<Declared = unknown, Wire = unknown> {
   readonly slot: 'role' | 'lifecycle' | 'boundary';
 
-  judge(value: unknown, errors: ValidationError[]): void;
+  validator(value: unknown, errors: ValidationError[]): void;
 
   describe(value: Declared, key: string): Wire | undefined;
 

package/src/axis/boundary/Boundaries.ts

@@ -0,0 +1,37 @@
+import type { BoundaryRules } from './Boundary.js';
+import { Registry } from '../../lib/Registry.js';
+
+export type Decoder = (value: unknown) => { value: unknown } | { error: string };
+export type Encoder = (value: unknown) => unknown;
+
+/**
+ * `decoders` for a value coming in, `encoders` for one going out, `aliases` for the word
+ * that names a pair. Three registries, so a codec is never half declared.
+ * FR : `decoders` à l'entrée, `encoders` à la sortie, `aliases` pour le mot qui nomme la paire.
+ * `Boundaries.aliases.register('isoDate', { in: { decode: 'isoDate' }, out: { encode: 'isoDate' } })`
+ * → a field saying `boundary: 'isoDate'` decodes to a `Date` and leaves as a string
+ */
+export const Boundaries = {
+  decoders: new Registry<Decoder>(
+    'boundary decoder',
+    'call Boundaries.decoders.register(name, fn)',
+  ),
+  encoders: new Registry<Encoder>(
+    'boundary encoder',
+    'call Boundaries.encoders.register(name, fn)',
+  ),
+  aliases: new Registry<BoundaryRules>('boundary alias'),
+};
+
+Boundaries.decoders.register('isoDate', (value) => {
+  if (value instanceof Date) return { value };
+  if (typeof value === 'string') {
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? { error: 'Invalid date' } : { value: date };
+  }
+  return { error: 'Expected a date' };
+});
+Boundaries.encoders.register('isoDate', (value) =>
+  value instanceof Date ? value.toISOString() : value,
+);
+Boundaries.aliases.register('isoDate', { in: { decode: 'isoDate' }, out: { encode: 'isoDate' } });

package/src/{schema/axis → axis}/boundary/Boundary.ts

@@ -1,7 +1,7 @@
 import type { Decoder, Encoder } from './Boundaries.js';
 import { Boundaries } from './Boundaries.js';
-import type { Field } from '../../fields/Field.js';
-import { Anatomy, type Shape } from '../shape/Shape.js';
+import type { Field } from '../../field/Field.js';
+import { Shapes, type Shape } from '../shape/Shape.js';
 
 export interface BoundaryRules {
   in?: 'closed' | { decode: string };
@@ -29,12 +29,13 @@ export class Boundary implements BoundaryRules {
     this.encode = codecs?.encode ?? identityEncoder;
   }
 
+  /** An unknown alias stops here. */
   static declared(field: Field): Boundary {
     const ref = field.boundary;
     if (ref === undefined) return new Boundary();
     if (typeof ref !== 'string') return new Boundary(ref);
 
-    const alias = Boundaries.alias(ref);
+    const alias = Boundaries.aliases.find(ref);
     if (!alias) throw new Error(`Unknown boundary alias: '${ref}'`);
     return new Boundary(alias);
   }
@@ -49,19 +50,20 @@ export class Boundary implements BoundaryRules {
     return new Boundary(rules, {
       decode:
         typeof rules.in === 'object'
-          ? Boundaries.decoder(rules.in.decode)
+          ? Boundaries.decoders.resolve(rules.in.decode)
           : identityDecoder,
       encode:
         typeof rules.out === 'object'
-          ? Boundaries.encoder(rules.out.encode)
+          ? Boundaries.encoders.resolve(rules.out.encode)
           : identityEncoder,
     });
   }
 
+  /** `date-time` means a `Date` on both sides, without a word in the entity. */
   static forShape(shape: Shape | undefined): Boundary {
-    const base = Anatomy.of(shape).base;
+    const base = Shapes.of(shape).base;
     if (base?.type === 'string' && base.format === 'date-time') {
-      return new Boundary(Boundaries.alias('isoDate')!);
+      return new Boundary(Boundaries.aliases.find('isoDate')!);
     }
     return new Boundary();
   }

package/src/{schema/axis → axis}/boundary/BoundaryAxis.ts

@@ -1,12 +1,12 @@
 import type { Axis } from '../Axis.js';
-import { admitWire } from '../../../projection/card/admission.js';
-import { isObject } from '../../../utils.js';
+import { admitWire } from '../../projection/card/admission.js';
+import { isObject } from '../../lib/utils.js';
 import type { BoundaryRef } from './Boundary.js';
 
 export const boundaryAxis: Axis<BoundaryRef, BoundaryRef> = {
   slot: 'boundary',
 
-  judge(value, errors) {
+  validator(value, errors) {
     if (typeof value === 'string') return; 
     if (!isObject(value)) {
       errors.push({
@@ -26,7 +26,7 @@ export const boundaryAxis: Axis<BoundaryRef, BoundaryRef> = {
 
   describe: (value) => value,
   reconstruct: (wire) => {
-    admitWire(boundaryAxis.judge, wire, 'boundary');
+    admitWire(boundaryAxis.validator, wire, 'boundary');
     return wire;
   },
 };

package/src/{schema/axis → axis}/lifecycle/Clock.ts

@@ -16,7 +16,7 @@ export class Clock {
     return this.reading();
   }
 
-  /** Freeze the instant this clock reads. Returns the gesture that restores it. */
+  /** One substitution moves time for every stamp in the process at once. */
   static freeze(at: number | Date): () => void {
     const previous = this.reading;
     const instant = at instanceof Date ? at.getTime() : at;

package/src/axis/lifecycle/Generators.ts

@@ -0,0 +1,29 @@
+import { createId } from '@paralleldrive/cuid2';
+
+import { Registry } from '../../lib/Registry.js';
+
+export type GeneratorRef = 'cuid2' | 'uuid' | 'nanoid' | (string & {});
+
+const NANOID_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+
+function nanoid(): string {
+  const bytes = new Uint8Array(21);
+  globalThis.crypto.getRandomValues(bytes);
+  return Array.from(bytes, (byte) => NANOID_ALPHABET[byte & 63]).join('');
+}
+
+/**
+ * Who answers a `generate:` name. `cuid2`, `uuid` and `nanoid` are registered like any
+ * other, so `Generators.resolve('ulid')` is refused here and lists the three.
+ * FR : pour qu'un `generate:` soit répondu par un registre, builtins compris.
+ * `Generators.register('ulid', ulid)` → `create: { generate: 'ulid' }` now resolves
+ */
+export const Generators = new Registry<() => string>(
+  'generator',
+  'call Generators.register(name, fn)',
+  [
+    ['cuid2', createId],
+    ['uuid', () => globalThis.crypto.randomUUID()],
+    ['nanoid', nanoid],
+  ],
+);

package/src/{schema/axis → axis}/lifecycle/LifecycleAxis.ts

@@ -1,18 +1,18 @@
 import type { Axis } from '../Axis.js';
-import type { ValidationError } from '../../../judge/result.js';
-import { admitWire, oneOfTokens } from '../../../projection/card/admission.js';
-import { isObject } from '../../../utils.js';
+import type { ValidationError } from '../../validation.js';
+import { admitWire, oneOfTokens } from '../../projection/card/admission.js';
+import { isObject } from '../../lib/utils.js';
 import { CREATE_TOKENS, UPDATE_TOKENS, type LifecycleRules } from './Lifecycle.js';
 
 export const lifecycleAxis: Axis<LifecycleRules, LifecycleRules> = {
   slot: 'lifecycle',
 
-  judge(value, errors) {
+  validator(value, errors) {
     if (!isObject(value)) {
       errors.push({ path: 'lifecycle', message: `Expected an object — got ${JSON.stringify(value)}` });
       return;
     }
-    if (value.create !== undefined) judgeCreate(value.create, errors);
+    if (value.create !== undefined) validateCreate(value.create, errors);
     if (value.update !== undefined && !oneOfTokens(value.update, UPDATE_TOKENS)) {
       errors.push({
         path: 'lifecycle.update',
@@ -23,12 +23,17 @@ export const lifecycleAxis: Axis<LifecycleRules, LifecycleRules> = {
 
   describe: (value) => value,
   reconstruct: (wire) => {
-    admitWire(lifecycleAxis.judge, wire, 'lifecycle');
+    admitWire(lifecycleAxis.validator, wire, 'lifecycle');
     return wire;
   },
 };
 
-function judgeCreate(rule: unknown, errors: ValidationError[]): void {
+/**
+ * So the four legal ways to declare a creation are stated once, and anything else names them.
+ * FR : pour que les quatre façons de déclarer une création soient dites une fois.
+ * `create: 3` → `Expected 'now', 'optional', { value } or { generate } — got 3`
+ */
+function validateCreate(rule: unknown, errors: ValidationError[]): void {
   if (oneOfTokens(rule, CREATE_TOKENS)) return;
   if (isObject(rule)) {
     if ('value' in rule) return;

package/src/axis/lifecycle/apply.ts

@@ -0,0 +1,53 @@
+import { Lifecycle } from './Lifecycle.js';
+import { Generators } from './Generators.js';
+import { Clock } from './Clock.js';
+import { type Field, type Fields } from '../../field/Field.js';
+
+/**
+ * So every storage realizes a create the same way.
+ * FR : pour que chaque storage réalise une création de la même façon.
+ * `applyCreate({ id: primary(), createdAt: created() }, { title: 'a' })`
+ * → `id` generated, `createdAt` stamped, `title` untouched
+ */
+export function applyCreate(fields: Fields, input: Record<string, unknown>): Record<string, unknown> {
+  const values: Record<string, unknown> = { ...input };
+  const instant = Clock.now();
+
+  for (const [name, field] of Object.entries(fields) as [string, Field][]) {
+    if (name in values) continue;
+    const rule = Lifecycle.of(field);
+
+    if (rule.create === 'now') values[name] = new Date(instant);
+    else if (rule.literal) values[name] = freshValue(rule.literal.value);
+    else if (rule.generator) values[name] = Generators.resolve(rule.generator)();
+  }
+
+  return values;
+}
+
+/**
+ * So two rows created from one declared default never end up sharing the same object.
+ * FR : pour que deux lignes nées d'un même défaut ne partagent pas l'objet.
+ * `create: { value: [] }` → each instance gets its own array
+ */
+function freshValue(value: unknown): unknown {
+  if (value === null || typeof value !== 'object') return value;
+  return structuredClone(value);
+}
+
+/**
+ * So `updated()` is stamped by the storage, and no handler has to remember it.
+ * FR : pour qu'`updated()` soit estampé par le storage, pas par le handler.
+ * `applyUpdate(fields, { title: 'b' })` → `updatedAt` added, nothing else
+ */
+export function applyUpdate(fields: Fields, patch: Record<string, unknown>): Record<string, unknown> {
+  const values: Record<string, unknown> = { ...patch };
+  const instant = Clock.now();
+
+  for (const [name, field] of Object.entries(fields) as [string, Field][]) {
+    if (Lifecycle.of(field).stampedOnUpdate && !(name in values))
+      values[name] = new Date(instant);
+  }
+
+  return values;
+}

package/src/{schema/axis → axis}/role/Relation.ts

@@ -10,22 +10,23 @@ export interface Relation {
 }
 
 /**
- * How a relation is built — the one place a target becomes a thunk.
+ * How a relation is built — the one place a target becomes `() => Entity`.
  *
  * A target arrives as the class or as a function returning it, because a cycle between two
  * entities can only be written the second way. Recognised by FORM, `getFields` on the
- * value: a class answers it, a thunk does not.
+ * value: a class answers it, `() => Post` does not.
  */
 export const Relation = {
+  /** `() => Post` so two entities can point at each other. */
   one(target: EntityConstructor | (() => EntityConstructor), cascade?: boolean): Relation {
-    return { to: thunk(target), kind: 'one', onDelete: cascade ? 'cascade' : undefined };
+    return { to: normalizeTarget(target), kind: 'one', onDelete: cascade ? 'cascade' : undefined };
   },
 
   many(target: EntityConstructor | (() => EntityConstructor)): Relation {
-    return { to: thunk(target), kind: 'many' };
+    return { to: normalizeTarget(target), kind: 'many' };
   },
 };
 
-function thunk<E extends EntityConstructor>(target: E | (() => E)): () => E {
+function normalizeTarget<E extends EntityConstructor>(target: E | (() => E)): () => E {
   return 'getFields' in target ? () => target as E : (target as () => E);
 }

package/src/axis/role/Role.ts

@@ -0,0 +1,52 @@
+import type { EntityConstructor, Relation } from './Relation.js';
+
+export interface RoleRules {
+  primary?: boolean;
+  index?: boolean;
+  unique?: boolean;
+  relation?: Relation;
+}
+
+export class Role implements RoleRules {
+  readonly primary?: boolean;
+  readonly index?: boolean;
+  readonly unique?: boolean;
+  readonly relation?: Relation;
+
+  private constructor(rules: RoleRules = {}) {
+    this.primary = rules.primary;
+    this.index = rules.index;
+    this.unique = rules.unique;
+    this.relation = rules.relation;
+  }
+
+  static of(field: { role?: RoleRules }): Role {
+    return new Role(field.role);
+  }
+
+  get isPrimary(): boolean {
+    return this.primary === true;
+  }
+
+  get isIndexed(): boolean {
+    return this.index === true;
+  }
+
+  /** A field unique on its own. A group spanning several belongs to the schema. */
+  get isUnique(): boolean {
+    return this.unique === true;
+  }
+
+  get isCollection(): boolean {
+    return this.relation?.kind === 'many';
+  }
+
+  get isReference(): boolean {
+    return this.relation?.kind === 'one';
+  }
+
+  /** Calls `() => Post` so no caller has to. */
+  get target(): EntityConstructor | undefined {
+    return this.relation?.to();
+  }
+}

package/src/{schema/axis → axis}/role/RoleAxis.ts

@@ -1,22 +1,20 @@
 import type { Axis, Resolver } from '../Axis.js';
-import { refuse, oneOfTokens } from '../../../projection/card/admission.js';
-import { isObject, lowerFirst } from '../../../utils.js';
-import type { ValidationError } from '../../../judge/result.js';
+import { refuse, oneOfTokens } from '../../projection/card/admission.js';
+import { isObject, lowerFirst } from '../../lib/utils.js';
+import type { ValidationError } from '../../validation.js';
 import { ON_DELETE, RELATION_KINDS, type EntityConstructor, type Relation } from './Relation.js';
 import { type RoleRules } from './Role.js';
-import { FieldGroup } from '../../fields/constraint/FieldGroup.js';
-import { Unique } from '../../fields/constraint/Unique.js';
-import type { RoleDescriptor } from '../../../projection/card/Descriptor.js';
+import type { RoleDescriptor } from '../../projection/card/Descriptor.js';
 
 export const roleAxis: Axis<RoleRules, RoleDescriptor> = {
   slot: 'role',
 
-  judge(value, errors) {
+  validator(value, errors) {
     if (!isObject(value)) {
       errors.push({ path: 'role', message: `Expected an object — got ${JSON.stringify(value)}` });
       return;
     }
-    for (const flag of ['primary', 'index'] as const) {
+    for (const flag of ['primary', 'index', 'unique'] as const) {
       if (value[flag] !== undefined && typeof value[flag] !== 'boolean') {
         errors.push({
           path: `role.${flag}`,
@@ -24,48 +22,33 @@ export const roleAxis: Axis<RoleRules, RoleDescriptor> = {
         });
       }
     }
-    if (value.rules !== undefined) {
-      const legal =
-        Array.isArray(value.rules) &&
-        value.rules.every(
-          (rule) =>
-            rule instanceof FieldGroup ||
-            (Array.isArray(rule) && rule.every((member) => typeof member === 'string')),
-        );
-      if (!legal) {
-        errors.push({
-          path: 'role.rules',
-          message: 'Expected field groups, or the member lists they denote — string[][]',
-        });
-      }
-    }
-    if (value.relation !== undefined) judgeRelation(value.relation, errors);
+    if (value.relation !== undefined) validateRelation(value.relation, errors);
   },
 
+  /** A card carries the target's NAME: a class cannot cross a process boundary. */
   describe(role, key) {
-    const out: Mutable<RoleDescriptor> = {};
-    if (role.primary) out.primary = true;
-    const unique = (role.rules ?? []).filter((rule) => rule instanceof Unique);
-    if (unique.length) out.unique = unique.map((rule) => [...rule.resolvedOn(key).members]);
-    if (role.index) out.index = true;
+    const descriptor: Mutable<RoleDescriptor> = {};
+    if (role.primary) descriptor.primary = true;
+    if (role.unique) descriptor.unique = [[key]];
+    if (role.index) descriptor.index = true;
     if (role.relation) {
       const target = role.relation.to() as { name?: string };
-      out.relation = {
+      descriptor.relation = {
         to: lowerFirst(target.name ?? ''),
         kind: role.relation.kind,
         ...(role.relation.onDelete ? { onDelete: role.relation.onDelete } : {}),
       };
     }
-    return Object.keys(out).length ? out : undefined;
+    return Object.keys(descriptor).length ? descriptor : undefined;
   },
 
   reconstruct(wire, resolve?: Resolver) {
-    const out: RoleRules = {};
-    if (wire.primary) out.primary = true;
-    if (wire.unique?.length) out.rules = wire.unique.map((group) => new Unique(group));
-    if (wire.index) out.index = true;
+    const rules: RoleRules = {};
+    if (wire.primary) rules.primary = true;
+    if (wire.unique?.some((group) => group.length === 1)) rules.unique = true;
+    if (wire.index) rules.index = true;
     if (wire.relation) {
-      // `judge` cannot serve here: it demands a thunk where a card carries a name.
+      // `validator` cannot serve here: it demands `() => Post` where a card carries a name.
       if (!oneOfTokens(wire.relation.kind, RELATION_KINDS)) {
         refuse(
           `role.relation.kind is ${JSON.stringify(wire.relation.kind)}`,
@@ -79,17 +62,22 @@ export const roleAxis: Axis<RoleRules, RoleDescriptor> = {
         );
       }
       const name = wire.relation.to;
-      out.relation = {
+      rules.relation = {
         to: () => (resolve?.(name) ?? ({ name } as unknown)) as EntityConstructor,
         kind: wire.relation.kind as Relation['kind'],
         ...(wire.relation.onDelete ? { onDelete: wire.relation.onDelete as Relation['onDelete'] } : {}),
       } as RoleRules['relation'];
     }
-    return out;
+    return rules;
   },
 };
 
-function judgeRelation(relation: unknown, errors: ValidationError[]): void {
+/**
+ * So a relation is validated where `() => Post` is required — a card carries a name.
+ * FR : pour qu'une relation soit jugée là où `() => Post` est exigé, contrairement à une carte.
+ * `{ to: User, kind: 'one' }` → error `Expected a function returning the target entity, such as () => Post`
+ */
+function validateRelation(relation: unknown, errors: ValidationError[]): void {
   if (!isObject(relation)) {
     errors.push({ path: 'role.relation', message: `Expected an object — got ${JSON.stringify(relation)}` });
     return;
@@ -101,7 +89,7 @@ function judgeRelation(relation: unknown, errors: ValidationError[]): void {
     });
   }
   if (typeof relation.to !== 'function') {
-    errors.push({ path: 'role.relation.to', message: 'Expected a thunk returning the target entity' });
+    errors.push({ path: 'role.relation.to', message: 'Expected a function returning the target entity, such as () => Post' });
   }
   if (relation.onDelete !== undefined && !oneOfTokens(relation.onDelete, ON_DELETE)) {
     errors.push({

package/src/axis/shape/Formats.ts

@@ -0,0 +1,20 @@
+import { Registry } from '../../lib/Registry.js';
+
+export type StringFormat =
+  | 'date-time'
+  | 'date'
+  | 'time'
+  | 'email'
+  | 'uuid'
+  | 'uri'
+  | (string & {});
+
+export type FormatPredicate = (value: string) => boolean;
+
+/**
+ * String formats the JSON Schema engine does not know. `find` answers `undefined` for
+ * `email` or `uuid`, which it validates on its own.
+ * FR : les formats de chaîne que le moteur ignore ; `find` rend `undefined` pour les siens.
+ * `Formats.register('siret', (v) => /^\d{14}$/.test(v))`
+ */
+export const Formats = new Registry<FormatPredicate>('format');

package/src/{schema/axis → axis}/shape/Shape.ts

@@ -6,7 +6,7 @@ type Nullably<T extends string> = T | readonly [T, 'null'];
 interface StringConstraints { minLength?: number; maxLength?: number; pattern?: string; enum?: readonly (string | null)[]; format?: StringFormat }
 interface NumericConstraints { minimum?: number; maximum?: number }
 interface ArrayConstraints { items?: Shape; minItems?: number; maxItems?: number }
-interface ObjectConstraints { properties?: Record<string, unknown>; required?: readonly string[] }
+interface ObjectConstraints { properties?: Record<string, unknown>; required?: readonly string[]; additionalProperties?: boolean | Shape; propertyNames?: Shape }
 
 export type Shape =
   | ({ type: Nullably<'string'> } & StringConstraints)
@@ -19,8 +19,8 @@ const SHAPE_TYPES = ['string', 'number', 'integer', 'boolean', 'array', 'object'
 
 function isShapeImpl(value: unknown): value is Shape {
   if (typeof value !== 'object' || value === null) return false;
-  const declared = (value as Shape).type;
-  const names = Array.isArray(declared) ? declared : [declared];
+  const type = (value as Shape).type;
+  const names = Array.isArray(type) ? type : [type];
   return (
     names.some((name) => (SHAPE_TYPES as readonly unknown[]).includes(name)) &&
     names.every((name) => name === 'null' || (SHAPE_TYPES as readonly unknown[]).includes(name))
@@ -36,19 +36,19 @@ type BaseShape =
 
 function nullableShapeImpl(shape: Shape): Shape {
   if (Array.isArray(shape.type)) return shape;
-  const out = { ...shape, type: [shape.type, 'null'] } as unknown as Shape;
-  if ('enum' in out && out.enum && !out.enum.includes(null)) {
-    (out as { enum: readonly (string | null)[] }).enum = [...out.enum, null];
+  const nullable = { ...shape, type: [shape.type, 'null'] } as unknown as Shape;
+  if ('enum' in nullable && nullable.enum && !nullable.enum.includes(null)) {
+    (nullable as { enum: readonly (string | null)[] }).enum = [...nullable.enum, null];
   }
-  return out;
+  return nullable;
 }
 
-interface ShapeAnatomy {
+interface ShapeParts {
   base?: BaseShape;
   nullable: boolean;
 }
 
-export class Anatomy {
+export class Shapes {
   static is(value: unknown): value is Shape {
     return isShapeImpl(value);
   }
@@ -57,26 +57,26 @@ export class Anatomy {
     return nullableShapeImpl(shape);
   }
 
-  private static readonly cache = new WeakMap<object, ShapeAnatomy>();
-  private static readonly none: ShapeAnatomy = { base: undefined, nullable: false };
+  private static readonly cache = new WeakMap<object, ShapeParts>();
+  private static readonly none: ShapeParts = { base: undefined, nullable: false };
 
-  static of(shape?: Shape): ShapeAnatomy {
+  static of(shape?: Shape): ShapeParts {
     if (!shape) return this.none;
-    let a = this.cache.get(shape);
-    if (!a) {
+    let parts = this.cache.get(shape);
+    if (!parts) {
       if (Array.isArray(shape.type)) {
         const baseType = shape.type.find((t) => t !== 'null');
         const base = { ...shape, type: baseType } as BaseShape;
         if ('enum' in base && base.enum) {
           (base as { enum: readonly (string | null)[] }).enum = base.enum.filter((v) => v !== null);
         }
-        a = { base, nullable: true };
+        parts = { base, nullable: true };
       } else {
-        a = { base: shape as BaseShape, nullable: false };
+        parts = { base: shape as BaseShape, nullable: false };
       }
-      this.cache.set(shape, a);
+      this.cache.set(shape, parts);
     }
-    return a;
+    return parts;
   }
 
   static isNullable(shape?: Shape): boolean {

package/src/entity/EntityAdapterSet.ts

@@ -0,0 +1,81 @@
+import type { Fields } from '../field/Field.js';
+import { isObject } from '../lib/utils.js';
+import type { EntityAdapters } from './EntityAdapters.js';
+
+type AdapterConfiguration = Record<string, unknown>;
+type AdapterConfigurations = Record<string, AdapterConfiguration>;
+
+export class EntityAdapterSet {
+  /**
+   * `{ sql: { body: { columnType: { pg: 'tsvector' } } } }`
+   */
+  private constructor(readonly adapters: EntityAdapters<Fields>) {}
+
+  /**
+   * Stops a malformed declaration from propagating, by checking its two levels.
+   * `of({ sql: { body: 3 } })` → passes; `of({ sql: 'oops' })` → throws, naming `adapters.sql`
+   */
+  static of(adapters?: EntityAdapters<Fields>): EntityAdapterSet {
+    if (!adapters) return new EntityAdapterSet({});
+
+    if (!isObject(adapters)) {
+      throw new Error(
+        `adapters: expected an object keyed by adapter name, got ${typeof adapters}.`,
+      );
+    }
+
+    for (const [adapter, fields] of Object.entries(adapters)) {
+      if (!isObject(fields)) {
+        throw new Error(
+          `adapters.${adapter}: expected an object keyed by field name, got ${typeof fields}. ` +
+            `What an adapter is handed is addressed by the field it applies to.`,
+        );
+      }
+    }
+
+    return new EntityAdapterSet(adapters);
+  }
+
+  /** Folds several into one, a later field entry replacing the earlier. Takes sets only, so */
+  static merged(adapterSets: readonly EntityAdapterSet[]): EntityAdapterSet {
+    const configurations: AdapterConfigurations = {};
+
+    for (const adapterSet of adapterSets)
+      for (const [adapter, configuration] of adapterSet.entries)
+        configurations[adapter] = { ...configurations[adapter], ...configuration };
+
+    return new EntityAdapterSet(configurations);
+  }
+
+  private get entries(): [string, AdapterConfiguration][] {
+    return Object.entries(this.adapters);
+  }
+
+  /** Collects every field addressed, so a declaration aimed at a missing field is caught. */
+  get fieldNames(): string[] {
+    return [
+      ...new Set(this.entries.flatMap(([, configuration]) => Object.keys(configuration))),
+    ];
+  }
+
+  /** Follows a derivation — `pick`, `omit` and `rename` are one gesture: what remains, and */
+  rename(transform: (key: string) => string | undefined): EntityAdapterSet {
+    const renamed: AdapterConfigurations = {};
+
+    for (const [adapter, configuration] of this.entries) {
+      const mapped: AdapterConfiguration = {};
+
+      for (const [key, entry] of Object.entries(configuration)) {
+        const newName = transform(key);
+
+        if (newName !== undefined) mapped[newName] = entry;
+      }
+
+      // Drop an adapter left with no field. `Post.pick('id')` would otherwise answer
+      // `{ sql: {} }` — a line the entity never wrote.
+      if (Object.keys(mapped).length) renamed[adapter] = mapped;
+    }
+
+    return new EntityAdapterSet(renamed);
+  }
+}