@fougere/schema 0.5.0-alpha.1 → 0.7.0-alpha.0

package/src/judge/Cases.ts

@@ -1,139 +0,0 @@
-import { Anatomy } from '../axis/shape/Shape.js';
-import { Boundary } from '../axis/boundary/Boundary.js';
-import { Lifecycle } from '../axis/lifecycle/Lifecycle.js';
-import { Role } from '../axis/role/Role.js';
-import type { Field } from '../fields/Field.js';
-import type { SchemaView } from '../schema/SchemaView.js';
-import { RowJudge } from './RowJudge.js';
-import { RowRefusal } from './RowRefusal.js';
-
-/**
- * One input, and what the judge must answer.
- *
- * `expect` carries the PATH of the field at fault and never the message. We know which
- * field must be refused because we are the ones who broke it; naming the message would
- * make this list a second judge, and the two would then have to be kept in step by hand —
- * which is the duplication the whole thing exists to remove.
- */
-export interface Case {
-  /** What this input does, in one clause — carried into the assertion so a failure reads. */
-  why: string;
-  body: unknown;
-  /**
-   * Judged as an update rather than a creation. The two modes refuse different things:
-   * an absence is `Required` on create and legal on patch, an immutable field is legal
-   * on create and refused on patch.
-   */
-  patch: boolean;
-  expect: 'accept' | { reject: string };
-}
-
-/** A value of the wrong type for the declared shape — the one violation every field has. */
-function wrongTypeFor(field: Field): unknown {
-  const declared = (field.shape as { type?: string | readonly string[] }).type;
-  const names = Array.isArray(declared) ? declared : [declared];
-  return names.includes('string') ? 42 : 'not-a-value-of-this-shape';
-}
-
-/** Values that break a stated bound. Empty when the field states none. */
-function outOfBoundsFor(field: Field): { why: string; value: unknown }[] {
-  // Through `Anatomy`, not a cast: the cast admitted any keyword, and it declared
-  // `maxItems` — which no branch below ever produced. In the one function whose job is
-  // to be exhaustive, a bound the type does not carry is a case nobody notices missing.
-  const shape = Anatomy.of(field.shape).base;
-  const out: { why: string; value: unknown }[] = [];
-  if (shape?.type === 'string') {
-    if (typeof shape.minLength === 'number' && shape.minLength > 0)
-      out.push({ why: 'shorter than min', value: 'x'.repeat(shape.minLength - 1) });
-    if (typeof shape.maxLength === 'number')
-      out.push({ why: 'longer than max', value: 'x'.repeat(shape.maxLength + 1) });
-    if (shape.enum) out.push({ why: 'outside the stated set', value: '__not-in-enum__' });
-  }
-  if (shape?.type === 'number' || shape?.type === 'integer') {
-    if (typeof shape.minimum === 'number') out.push({ why: 'below minimum', value: shape.minimum - 1 });
-    if (typeof shape.maximum === 'number') out.push({ why: 'above maximum', value: shape.maximum + 1 });
-  }
-  if (shape?.type === 'array') {
-    if (typeof shape.minItems === 'number' && shape.minItems > 0)
-      out.push({ why: 'fewer items than min', value: [] });
-    if (typeof shape.maxItems === 'number')
-      out.push({ why: 'more items than max', value: Array.from({ length: shape.maxItems + 1 }, () => null) });
-  }
-  return out;
-}
-
-/**
- * The decision table, enumerated on the entity's own fields.
- *
- * Use the complete entity so a derived view cannot hide a divergent field. The caller
- * supplies a valid row; generating data belongs to the testing package.
- */
-export class Cases {
-  private constructor(
-    readonly all: readonly Case[],
-  ) {}
-
-  static of(entity: SchemaView, valid: Record<string, unknown>): Cases {
-    return new Cases(enumerate(entity, valid));
-  }
-
-  /**
-   * Whether a verdict is the one a case expected.
-   *
-   * Takes the RESULT rather than the input so the same reader serves the local judge, the
-   * façade and a door — the three that have to agree.
-   */
-  static holds(expected: Case['expect'], result: { success: boolean; errors?: { path: string }[] }): boolean {
-    if (expected === 'accept') return result.success;
-    if (result.success) return false;
-    return (result.errors ?? []).some((error) => error.path === expected.reject);
-  }
-
-  /** Every way a row is refused for its structure — the closed set this table must cover. */
-  static get refusals(): string[] {
-    return Object.values(RowRefusal);
-  }
-
-  [Symbol.iterator](): Iterator<Case> {
-    return this.all[Symbol.iterator]();
-  }
-}
-
-function enumerate(entity: SchemaView, valid: Record<string, unknown>): Case[] {
-  const fields = entity.getFields();
-  const judge = RowJudge.of(fields);
-  const cases: Case[] = [];
-  const withField = (name: string, value: unknown) => ({ ...valid, [name]: value });
-
-  cases.push({ why: 'a valid body', body: valid, patch: false, expect: 'accept' });
-  cases.push({ why: 'a key outside the contract', body: { ...valid, __unknown__: 'x' }, patch: false, expect: { reject: '__unknown__' } });
-  cases.push({ why: 'not an object at all', body: 'a string', patch: false, expect: { reject: '.' } });
-
-  for (const [name, field] of Object.entries(fields) as [string, Field][]) {
-    // A reference names a row that must exist; the caller supplied its id and we do not
-    // get to invent a second one, so the only case we can state about it is the bound one.
-    const isRef = Role.of(field).isReference;
-
-    if (judge.onAbsent(field) === null && name in valid) {
-      const body = { ...valid };
-      delete body[name];
-      cases.push({ why: `${name} absent`, body, patch: false, expect: { reject: name } });
-    }
-
-    if (Boundary.of(field).readOnly) {
-      cases.push({ why: `${name} supplied although read-only`, body: withField(name, wrongTypeFor(field)), patch: false, expect: { reject: name } });
-    }
-
-    if (Lifecycle.of(field).immutable && !Role.of(field).isPrimary) {
-      cases.push({ why: `${name} supplied on an update`, body: { [name]: valid[name] ?? wrongTypeFor(field) }, patch: true, expect: { reject: name } });
-    }
-
-    if (name in valid && !isRef) {
-      cases.push({ why: `${name} of the wrong type`, body: withField(name, wrongTypeFor(field)), patch: false, expect: { reject: name } });
-      for (const { why, value } of outOfBoundsFor(field))
-        cases.push({ why: `${name} ${why}`, body: withField(name, value), patch: false, expect: { reject: name } });
-    }
-  }
-
-  return cases;
-}

package/src/judge/ValueForm.ts

@@ -1,7 +0,0 @@
-export const isObject = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value);
-
-export const oneOfTokens = <T extends readonly string[]>(
-  value: unknown,
-  tokens: T,
-): value is T[number] => typeof value === 'string' && (tokens as readonly string[]).includes(value);

package/src/judge/options.ts

@@ -1,3 +0,0 @@
-export interface ValidateOptions {
-  patch?: boolean;
-}

package/src/projection/SchemaOrCard.ts

@@ -1,18 +0,0 @@
-import type { Fields } from '../fields/Field.js';
-import type { SchemaView } from '../schema/SchemaView.js';
-import type { SchemaDescriptor } from '../card/Descriptor.js';
-import { Card } from '../card/Card.js';
-
-export type SchemaOrCard = SchemaView | SchemaDescriptor;
-
-function isDescriptor(source: SchemaOrCard): source is SchemaDescriptor {
-  return typeof (source as SchemaView).getFields !== 'function';
-}
-
-export function schemaOf(source: SchemaOrCard): SchemaView {
-  return isDescriptor(source) ? Card.fromDescriptor(source).toSchema() : source;
-}
-
-export function fieldsOf(source: SchemaOrCard): Fields {
-  return schemaOf(source).getFields();
-}

package/src/schema/Schema.ts

@@ -1,197 +0,0 @@
-import { Boundary } from '../axis/boundary/Boundary.js';
-import { type Fields } from '../fields/Field.js';
-import {
-  type CompositeUnique,
-  type EntityDeclarations,
-  type PreviousNames,
-} from '../EntityDeclarations.js';
-import { EntityAdapterSet, type EntityAdapters } from '../EntityAdapters.js';
-import { FieldGroup } from '../constraint/FieldGroup.js';
-import { Unique } from '../constraint/Unique.js';
-import { RowJudge } from '../judge/RowJudge.js';
-import { SchemaDerivation } from './SchemaDerivation.js';
-import { SchemaDefinition } from './SchemaDefinition.js';
-import { type ValidateOptions } from '../judge/options.js';
-import type { StandardSchemaV1 } from '../projection/standard.js';
-import type { PartialRow, Row, SchemaView } from './SchemaView.js';
-
-export const ANONYMOUS_SCHEMA_NAME = "Schema";
-
-export interface SchemaConstructor<TFields extends Fields> extends SchemaView<TFields> {
-  new (data: PartialRow<TFields>): Row<TFields>;
-  readonly "~standard": StandardSchemaV1.Props<Record<string, unknown>, Row<TFields>>;
-  readonly derivation?: SchemaDerivation;
-  readonly previous?: PreviousNames<TFields>;
-  readonly anchored?: boolean;
-  from(data: Record<string, unknown>): Row<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<TFields>;
-  extend<E extends Fields>(extra: E): SchemaConstructor<TFields & E>;
-  declares(declarations: EntityDeclarations<TFields>): SchemaConstructor<TFields>;
-  anchor(): SchemaConstructor<TFields>;
-  named(name: string): SchemaConstructor<TFields>;
-  rename(mapping: Partial<Record<string & keyof TFields, string>>): SchemaConstructor<Fields>;
-}
-
-export class Schema {
-  /** The one place a schema holds what it is. The readings below are its projections. */
-  static definition: SchemaDefinition = SchemaDefinition.stated({ fields: {} });
-
-  static get fields(): Fields { return this.definition.fields; }
-  static get adapters(): EntityAdapters<Fields> | undefined { return this.definition.adapters; }
-  static get opts(): ValidateOptions { return this.definition.opts; }
-  static get derivation(): SchemaDerivation | undefined { return this.definition.derivation; }
-  static get previous(): PreviousNames<Fields> | undefined { return this.definition.previous; }
-  static get anchored(): boolean { return this.definition.anchored; }
-
-  constructor(data?: Record<string, unknown>) {
-    if (!data) return;
-    for (const [key, value] of Object.entries(data)) {
-      Object.defineProperty(this, key, { value, writable: true, enumerable: true, configurable: true });
-    }
-  }
-
-  static getFields() { return this.fields; }
-  static getAdapters() { return this.adapters; }
-  static getUnique(): CompositeUnique<Fields> | undefined {
-    const groups = FieldGroup.groupsOf(this.fields, Unique);
-    return groups.length ? groups.map((group) => [...group.members]) : undefined;
-  }
-  static getOpts() { return this.opts; }
-
-  static validate(input: unknown) {
-    return RowJudge.of(this.fields, this.opts).check(input);
-  }
-
-  static from(data: Record<string, unknown>) {
-    const out: Record<string, unknown> = {};
-    for (const [key, field] of Object.entries(this.fields)) {
-      if (!(key in data)) continue;
-      const value = data[key];
-      if (value === null || value === undefined) { out[key] = value; continue; }
-      const decoded = Boundary.of(field).decode(value);
-      out[key] = "error" in decoded ? value : decoded.value;
-    }
-    return out;
-  }
-
-  static get ["~standard"](): StandardSchemaV1.Props<Record<string, unknown>> {
-    const { fields, opts } = this;
-    return {
-      version: 1,
-      vendor: "fougere",
-      validate(value: unknown) {
-        const result = RowJudge.of(fields, opts).check(value);
-        if (result.success) return { value: result.data };
-        return {
-          issues: result.errors.map((e) => ({
-            message: e.message,
-            path: e.path && e.path !== "." ? [{ key: e.path }] : undefined,
-          })),
-        };
-      },
-    };
-  }
-
-  static pick(...keys: string[]) {
-    assertKnownKeys("pick", keys, this.fields);
-    const picked: Fields = {};
-    for (const key of keys) if (this.fields[key]) picked[key] = this.fields[key];
-    return this.derive(picked, (k) => (keys.includes(k) ? k : undefined));
-  }
-
-  static omit(...keys: string[]) {
-    assertKnownKeys("omit", keys, this.fields);
-    const kept: Fields = {};
-    for (const [key, field] of Object.entries(this.fields)) if (!keys.includes(key)) kept[key] = field;
-    return this.derive(kept, (k) => (keys.includes(k) ? undefined : k));
-  }
-
-  static rename(mapping: Record<string, string>) {
-    assertKnownKeys("rename", Object.keys(mapping), this.fields);
-    const renamed: Fields = {};
-    for (const [key, field] of Object.entries(this.fields)) renamed[mapping[key] ?? key] = field;
-    return this.derive(renamed, (k) => mapping[k] ?? k);
-  }
-
-  /**
-   * Everything a schema states about ITSELF, available wherever a schema is. `entity(fields, …)`
-   * is this same gesture at the declaration site; the fields do not move, so neither does the type.
-   */
-  static declares(declarations: EntityDeclarations<Fields>) {
-    const addressed = EntityAdapterSet.of(declarations.adapters)?.fieldNames ?? [];
-    assertKnownKeys("declares", [...addressed, ...Object.keys(declarations.previous ?? {})], this.fields);
-
-    return Schema.subclass(this.definition.declaring(declarations));
-  }
-
-  /**
-   * This schema holds rows of its own — every entity is one, and a derivation says so.
-   *
-   * An anchor is where a walk STOPS: `derivation.anchor` climbs to the nearest one, and what
-   * is cut from an anchor roots on it. Two anchors are two entities that happen to share a
-   * shape, never a hierarchy — nothing here subtypes, so a relation between them is `ref()`.
-   */
-  static anchor() {
-    return Schema.subclass(this.definition.anchoring());
-  }
-
-  static partial() {
-    return Schema.subclass(this.definition.patched(this));
-  }
-
-  static extend(extra: Fields) {
-    return Schema.subclass(this.definition.extended(extra, this));
-  }
-
-  static named(name: string) {
-    if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name)) {
-      throw new Error(`named(): \`${name}\` is not a valid class 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 compose<T extends SchemaView[]>(...sources: T): SchemaConstructor<Merged<T>> {
-    return Schema.subclass(SchemaDefinition.merged(sources)) as unknown as SchemaConstructor<Merged<T>>;
-  }
-
-  static of<TFields extends Fields>(stated: {
-    fields: TFields;
-    derivation?: SchemaDerivation;
-    adapters?: EntityAdapters<TFields>;
-    opts?: ValidateOptions;
-    previous?: PreviousNames<TFields>;
-    anchored?: boolean;
-  }): SchemaConstructor<TFields> {
-    return Schema.subclass(SchemaDefinition.stated(stated)) as unknown as SchemaConstructor<TFields>;
-  }
-
-  /** The class a definition becomes. The one place a Schema subclass is born. */
-  private static subclass(definition: SchemaDefinition): SchemaConstructor<Fields> {
-    class Derived extends Schema {}
-    Derived.definition = definition;
-    Object.defineProperty(Derived, "name", { value: ANONYMOUS_SCHEMA_NAME, configurable: true });
-    return Derived as unknown as SchemaConstructor<Fields>;
-  }
-
-  private static derive(fields: Fields, survives: (key: string) => string | undefined) {
-    return Schema.subclass(this.definition.cut(fields, survives, this));
-  }
-}
-
-function assertKnownKeys(operation: string, keys: string[], fields: Fields): void {
-  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(", ")}.`,
-  );
-}
-
-type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
-type Merged<T extends SchemaView[]> = UnionToIntersection<T[number] extends { getFields(): infer F } ? F : Fields> & Fields;

package/src/schema/SchemaDefinition.ts

@@ -1,120 +0,0 @@
-import { type Fields } from '../fields/Field.js';
-import { FieldSet } from '../fields/FieldSet.js';
-import { type EntityDeclarations, type PreviousNames } from '../EntityDeclarations.js';
-import { EntityAdapterSet, type EntityAdapters } from '../EntityAdapters.js';
-import { SchemaDerivation } from './SchemaDerivation.js';
-import { type ValidateOptions } from '../judge/options.js';
-import type { SchemaView } from './SchemaView.js';
-
-/**
- * Everything a schema IS, apart from being a class whose instances are rows.
- *
- * The members used to be that many statics assigned side by side, and every derivation
- * re-threaded them by hand — which is how one of them came to be dropped from a list
- * without anyone noticing. A transformation here returns a COMPLETE definition or it does
- * not compile, so no gesture can mix the fields of one with the options of another.
- *
- * Internal: it is not exported from the package and never appears on `SchemaConstructor`.
- * A user derives with `Order.pick(…)`, never `Order.definition.pick(…)`.
- */
-export class SchemaDefinition {
-  private constructor(
-    readonly fields: Fields,
-    readonly adapters: EntityAdapters<Fields> | undefined,
-    readonly opts: ValidateOptions,
-    readonly previous: PreviousNames<Fields> | undefined,
-    readonly derivation: SchemaDerivation | undefined,
-    readonly anchored: boolean,
-  ) {}
-
-  static stated(said: {
-    fields: Fields;
-    adapters?: EntityAdapters<Fields>;
-    opts?: ValidateOptions;
-    previous?: PreviousNames<Fields>;
-    derivation?: SchemaDerivation;
-    anchored?: boolean;
-  }): SchemaDefinition {
-    return new SchemaDefinition(
-      said.fields, EntityAdapterSet.of(said.adapters)?.stated, said.opts ?? {}, said.previous, said.derivation, said.anchored ?? false,
-    );
-  }
-
-  /**
-   * What a schema states about ITSELF, folded into what it already states — one adapter
-   * entry per field wins the later spelling, and a unique group is stamped on its members.
-   */
-  declaring(said: EntityDeclarations<Fields>): SchemaDefinition {
-    return new SchemaDefinition(
-      FieldSet.declared(this.fields, said.unique),
-      EntityAdapterSet.merged([this.adapters, said.adapters])?.stated,
-      this.opts,
-      said.previous ?? this.previous,
-      this.derivation,
-      this.anchored,
-    );
-  }
-
-  /**
-   * The same schema, holding rows of its own. A derivation is an answer until it says this.
-   */
-  anchoring(): SchemaDefinition {
-    return new SchemaDefinition(
-      this.fields, this.adapters, this.opts, this.previous, this.derivation, true,
-    );
-  }
-
-  /**
-   * `pick`, `omit` and `rename` are one gesture: the fields that remain, and what became
-   * of each name. What each adapter was handed follows the same correspondence, and so does the origin.
-   */
-  cut(fields: Fields, survives: (key: string) => string | undefined, root: SchemaView): SchemaDefinition {
-    const renamed: Fields = {};
-    for (const [key, field] of Object.entries(fields)) renamed[key] = field.rename(survives);
-    return new SchemaDefinition(
-      renamed,
-      EntityAdapterSet.of(this.adapters)?.cut(survives)?.stated,
-      this.opts,
-      undefined,
-      this.origin(root).compose(survives),
-      false,
-    );
-  }
-
-  /** The same fields, judged as an update. */
-  patched(root: SchemaView): SchemaDefinition {
-    return new SchemaDefinition(
-      { ...this.fields }, this.adapters, { ...this.opts, patch: true }, undefined, this.origin(root), false,
-    );
-  }
-
-  /** The added fields have no origin, so the derivation is unchanged: it speaks of the root. */
-  extended(extra: Fields, root: SchemaView): SchemaDefinition {
-    return new SchemaDefinition(
-      { ...this.fields, ...extra }, this.adapters, this.opts, undefined, this.origin(root), false,
-    );
-  }
-
-  /** Several views folded into one definition, which therefore has no single origin. */
-  static merged(views: readonly SchemaView[]): SchemaDefinition {
-    const fields: Fields = {};
-    let opts: ValidateOptions = {};
-    for (const view of views) {
-      Object.assign(fields, view.getFields());
-      opts = { ...opts, ...view.getOpts() };
-    }
-    const adapters = EntityAdapterSet.merged(views.map((view) => view.getAdapters()))?.stated;
-
-    return new SchemaDefinition(fields, adapters, opts, undefined, undefined, false);
-  }
-
-  /**
-   * The origin this definition already carries, or the one `root` becomes. A schema that
-   * is an ANCHOR holds rows of its own, so what is cut from it roots on IT and not on its own origin.
-   */
-  private origin(root: SchemaView): SchemaDerivation {
-    if (!this.anchored && this.derivation) return this.derivation;
-
-    return SchemaDerivation.first(root, this.fields);
-  }
-}

package/src/schema/SchemaDerivation.ts

@@ -1,57 +0,0 @@
-import { type Fields } from '../fields/Field.js';
-import type { SchemaView } from './SchemaView.js';
-
-/**
- * What a derived schema says about its ORIGIN: the class it was cut from, and what the cut
- * left of each of that class's fields.
- *
- * The origin is the ROOT — `Post.pick(a, b).omit(b)` answers `Post` and never the
- * intermediate — so a chain is flattened rather than journalled, and the two halves cannot
- * disagree: a derivation always carries both, which `source` and `survived` as independent
- * properties could not promise.
- */
-export class SchemaDerivation {
-  private constructor(
-    readonly source: SchemaView,
-    readonly survived: Readonly<Record<string, string | undefined>>,
-  ) {}
-
-  /** The first cut: every field of the origin still answers to its own name. */
-  static first(source: SchemaView, fields: Fields): SchemaDerivation {
-    return new SchemaDerivation(source, Object.fromEntries(Object.keys(fields).map((key) => [key, key])));
-  }
-
-  /** The same origin, seen through one more cut. */
-  compose(survives: (key: string) => string | undefined): SchemaDerivation {
-    return new SchemaDerivation(
-      this.source,
-      Object.fromEntries(
-        Object.entries(this.survived).map(([origin, here]) => [origin, here === undefined ? undefined : survives(here)]),
-      ),
-    );
-  }
-
-  get sourceName(): string {
-    return this.source.name;
-  }
-
-  /**
-   * The anchor whose rows this describes — the nearest one going up, and a schema with no
-   * origin of its own is one. An answer borrows its rows; this says from whom. Whether
-   * those rows carry a key is a separate question: an anchor may have none.
-   */
-  get anchor(): SchemaView {
-    const source = this.source;
-
-    return source.anchored !== undefined || !source.derivation ? source : source.derivation.anchor;
-  }
-
-  /**
-   * What the ROOT calls `key`, translated to the name it carries here — `undefined` when a
-   * cut dropped it. A reader that needs something the root declared about a field asks the
-   * root and comes back through this; it does not keep a copy of the answer.
-   */
-  hereFor(key: string): string | undefined {
-    return this.survived[key];
-  }
-}