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

package/src/projection/card/EntityTypeSource.ts

@@ -1,90 +0,0 @@
-import { upperFirst } from '../../utils.js';
-import type { FieldDescriptor, SchemaDescriptor } from './Descriptor.js';
-
-function typeOf(field: FieldDescriptor): string {
-  const types = Array.isArray(field.type) ? field.type : field.type ? [field.type] : [];
-  const nullable = types.includes('null');
-  const base = types.find((t) => t !== 'null');
-  const inner = baseTypeOf(base, field);
-  return nullable ? `${inner} | null` : inner;
-}
-
-function baseTypeOf(base: string | undefined, field: FieldDescriptor): string {
-  if (field.enum?.length) {
-    return field.enum.map((v) => (v === null ? 'null' : JSON.stringify(v))).join(' | ');
-  }
-  switch (base) {
-    case 'string':
-      return field.format === 'date-time' ? 'Date' : 'string';
-    case 'number':
-    case 'integer':
-      return 'number';
-    case 'boolean':
-      return 'boolean';
-    case 'array':
-      return field.items ? `${typeOf(field.items)}[]` : 'string[]';
-    case 'object':
-      return field.properties ? objectTypeOf(field.properties, field.required ?? []) : 'Record<string, unknown>';
-    default:
-      return 'unknown';
-  }
-}
-
-function objectTypeOf(properties: Record<string, FieldDescriptor>, required: readonly string[]): string {
-  const members = Object.entries(properties).map(([name, field]) => {
-    const optional = required.includes(name) ? '' : '?';
-    return `${propertyKey(name)}${optional}: ${typeOf(field)}`;
-  });
-  return `{ ${members.join('; ')} }`;
-}
-
-function propertyKey(name: string): string {
-  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
-}
-
-function docCommentOf(text: string | undefined, indent: string): string {
-  if (!text) return '';
-  return `${indent}/** ${text.replace(/\*\//g, '*\\/')} */\n`;
-}
-
-export interface EntityTypeSourceOptions {
-  name?: string;
-  exported?: boolean;
-}
-
-function shapeTypeOf(descriptor: SchemaDescriptor, indent = ''): string {
-  const entries = Object.entries(descriptor.properties ?? {});
-  if (entries.length === 0) return '{}';
-
-  const lines = entries.map(([key, field]) => {
-    const doc = docCommentOf(field.description, `${indent}  `);
-    return `${doc}${indent}  ${propertyKey(key)}: ${typeOf(field)};`;
-  });
-  return `{\n${lines.join('\n')}\n${indent}}`;
-}
-
-export class EntityTypeSource {
-  private constructor(private readonly descriptor: SchemaDescriptor) {}
-
-  static of(descriptor: SchemaDescriptor): EntityTypeSource {
-    return new EntityTypeSource(descriptor);
-  }
-
-  render(options: EntityTypeSourceOptions = {}): string {
-    const name = identifierOf(options.name ?? upperFirst(this.descriptor.title ?? 'Schema'));
-    const exported = options.exported === false ? '' : 'export ';
-    const card = JSON.stringify(this.descriptor, null, 2)
-      .split('\n')
-      .map((line, i) => (i === 0 ? line : `  ${line}`))
-      .join('\n');
-
-    return `${exported}class ${name} extends Card.fromDescriptor<${shapeTypeOf(this.descriptor)}>(${card}).toSchema() {}`;
-  }
-}
-
-function identifierOf(name: string): string {
-  if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name)) {
-    throw new Error(`'${name}' is not a TypeScript identifier — it cannot name a generated declaration`);
-  }
-  return name;
-}

package/src/projection/card/FacadeTypeSource.ts

@@ -1,55 +0,0 @@
-import type { SchemaDescriptor } from './Descriptor.js';
-
-export interface FacadeTypeSourceOptions {
-  name?: string;
-  exported?: boolean;
-  rowType?: string;
-}
-
-export interface OpDescriptor {
-  name: string;
-  description?: string;
-  output?: SchemaDescriptor;
-  cardinality?: 'one' | 'maybe' | 'many' | 'page' | 'none';
-}
-
-function propertyKey(name: string): string {
-  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
-}
-
-function docCommentOf(text: string | undefined, indent: string): string {
-  if (!text) return '';
-  return `${indent}/** ${text.replace(/\*\//g, '*\\/')} */\n`;
-}
-
-function returnTypeOf(op: OpDescriptor, rowType: string): string {
-  switch (op.cardinality) {
-    case 'many': return `${rowType}[]`;
-    case 'page': return `${rowType}[] & { total?: number; endCursor?: string; hasMore?: boolean }`;
-    case 'maybe': return `${rowType} | undefined`;
-    case 'one': return rowType;
-    case 'none': return 'unknown';
-    default: return 'unknown';
-  }
-}
-
-export class FacadeTypeSource {
-  private constructor(private readonly operations: readonly OpDescriptor[]) {}
-
-  static of(operations: readonly OpDescriptor[]): FacadeTypeSource {
-    return new FacadeTypeSource(operations);
-  }
-
-  render(options: FacadeTypeSourceOptions = {}): string {
-    const name = options.name ?? 'Facade';
-    const exported = options.exported === false ? '' : 'export ';
-    const rowType = options.rowType ?? 'unknown';
-    const members = this.operations.map((operation) => {
-      const doc = docCommentOf(operation.description, '  ');
-      return `${doc}  ${propertyKey(operation.name)}(invocation?: Invocation): Promise<${returnTypeOf(operation, rowType)}>;`;
-    });
-
-    if (members.length === 0) return `${exported}interface ${name} {}`;
-    return `${exported}interface ${name} {\n${members.join('\n')}\n}`;
-  }
-}

package/src/schema/SchemaDefinition.ts

@@ -1,150 +0,0 @@
-import { type Fields } from './fields/Field.js';
-import { FieldSet } from './fields/FieldSet.js';
-import {
-  type EntityDeclarations,
-  type PreviousNames,
-} from '../entity/EntityDeclarations.js';
-import { EntityAdapterSet, type EntityAdapters } from '../entity/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,65 +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];
-  }
-}

package/src/schema/axis/boundary/Boundaries.ts

@@ -1,44 +0,0 @@
-import type { BoundaryRules } from './Boundary.js';
-
-export type Decoder = (value: unknown) => { value: unknown } | { error: string };
-export type Encoder = (value: unknown) => unknown;
-
-export class Boundaries {
-  private static readonly decoders = new Map<string, Decoder>();
-  private static readonly encoders = new Map<string, Encoder>();
-  private static readonly aliases = new Map<string, BoundaryRules>();
-
-  static registerDecoder(name: string, fn: Decoder): void { this.decoders.set(name, fn); }
-  static registerEncoder(name: string, fn: Encoder): void { this.encoders.set(name, fn); }
-
-  static registerAlias(name: string, boundary: BoundaryRules): void { this.aliases.set(name, boundary); }
-
-  static alias(name: string): BoundaryRules | undefined { return this.aliases.get(name); }
-
-  static decoder(name: string): Decoder { return this.named(this.decoders, name, 'decoder'); }
-  static encoder(name: string): Encoder { return this.named(this.encoders, name, 'encoder'); }
-
-  private static named<T>(registry: Map<string, T>, name: string, kind: string): T {
-    const fn = registry.get(name);
-    if (!fn) {
-      throw new Error(
-        `Unknown boundary ${kind}: '${name}'. Register it with ` +
-          `Boundaries.register${kind[0].toUpperCase()}${kind.slice(1)}('${name}', …).`,
-      );
-    }
-    return fn;
-  }
-}
-
-Boundaries.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' };
-});
-Boundaries.registerEncoder('isoDate', (value) =>
-  value instanceof Date ? value.toISOString() : value,
-);
-Boundaries.registerAlias('isoDate', { in: { decode: 'isoDate' }, out: { encode: 'isoDate' } });

package/src/schema/axis/lifecycle/Generators.ts

@@ -1,46 +0,0 @@
-import { createId } from '@paralleldrive/cuid2';
-
-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` by name — one registry per process, like `Formats` and
- * `Boundaries`.
- *
- * The three builtins are REGISTERED rather than switched on, which is what brings the
- * refusal back inside: a registry whose unknown name is refused by a `default:` branch in
- * its caller does not know what it holds, so it cannot say so.
- */
-export class Generators {
-  private static readonly registry = new Map<string, () => string>([
-    ['cuid2', createId],
-    ['uuid', () => globalThis.crypto.randomUUID()],
-    ['nanoid', nanoid],
-  ]);
-
-  static register(name: string, fn: () => string): void {
-    this.registry.set(name, fn);
-  }
-
-  /** The generator this name stands for, refused by name when nothing does. */
-  static resolve(ref: GeneratorRef): () => string {
-    const found = this.registry.get(ref);
-    if (found) return found;
-    throw new Error(
-      `Unknown generator '${ref}' — register it with Generators.register('${ref}', fn). ` +
-      `This process answers ${[...this.registry.keys()].join(', ')}.`,
-    );
-  }
-
-  /** Whether a name is answered, for a caller that must not throw to find out. */
-  static answers(ref: GeneratorRef): boolean {
-    return this.registry.has(ref);
-  }
-}

package/src/schema/axis/lifecycle/apply.ts

@@ -1,39 +0,0 @@
-import { Lifecycle } from './Lifecycle.js';
-import { Generators } from './Generators.js';
-import { Clock } from './Clock.js';
-import { type Field, type Fields } from '../../fields/Field.js';
-
-type Row = Record<string, unknown>;
-
-export function applyCreate(fields: Fields, input: Row): Row {
-  const out: Row = { ...input };
-  const instant = Clock.now();
-
-  for (const [name, field] of Object.entries(fields) as [string, Field][]) {
-    if (name in out) continue;
-    const rule = Lifecycle.of(field);
-
-    if (rule.create === 'now') out[name] = new Date(instant);
-    else if (rule.literal) out[name] = freshValue(rule.literal.value);
-    else if (rule.generator) out[name] = Generators.resolve(rule.generator)();
-  }
-
-  return out;
-}
-
-function freshValue(value: unknown): unknown {
-  if (value === null || typeof value !== 'object') return value;
-  return structuredClone(value);
-}
-
-export function applyUpdate(fields: Fields, patch: Row): Row {
-  const out: Row = { ...patch };
-  const instant = Clock.now();
-
-  for (const [name, field] of Object.entries(fields) as [string, Field][]) {
-    if (Lifecycle.of(field).stampedOnUpdate && !(name in out))
-      out[name] = new Date(instant);
-  }
-
-  return out;
-}

package/src/schema/axis/role/Role.ts

@@ -1,56 +0,0 @@
-import { FieldGroup } from "../../fields/constraint/FieldGroup.js";
-import { Unique } from "../../fields/constraint/Unique.js";
-import type { EntityConstructor, Relation } from "./Relation.js";
-
-export interface RoleRules {
-  primary?: boolean;
-  index?: boolean;
-  relation?: Relation;
-  rules?: readonly FieldGroup[];
-}
-
-export class Role implements RoleRules {
-  readonly primary?: boolean;
-  readonly index?: boolean;
-  readonly relation?: Relation;
-  readonly rules?: readonly FieldGroup[];
-
-  private constructor(declared: RoleRules = {}) {
-    this.primary = declared.primary;
-    this.index = declared.index;
-    this.relation = declared.relation;
-    this.rules = declared.rules;
-  }
-
-  static of(field: { role?: RoleRules }): Role {
-    return new Role(field.role);
-  }
-
-  /** A group written with no members means "this field": only the key it is declared under resolves it. */
-  static resolvedOn(role: RoleRules | undefined, key?: string): RoleRules | undefined {
-    let rules = FieldGroup.normalize(role?.rules, (members) => new Unique(members));
-    if (rules && key !== undefined && rules.some((group) => group.isSelf))
-      rules = rules.map((group) => group.resolvedOn(key));
-    return rules === role?.rules ? role : { ...role, rules };
-  }
-
-  get isPrimary(): boolean {
-    return this.primary === true;
-  }
-
-  get isIndexed(): boolean {
-    return this.index === true;
-  }
-
-  get isCollection(): boolean {
-    return this.relation?.kind === "many";
-  }
-
-  get isReference(): boolean {
-    return this.relation?.kind === "one";
-  }
-
-  get target(): EntityConstructor | undefined {
-    return this.relation?.to();
-  }
-}

package/src/schema/axis/shape/Formats.ts

@@ -1,22 +0,0 @@
-export type StringFormat =
-  | 'date-time'
-  | 'date'
-  | 'time'
-  | 'email'
-  | 'uuid'
-  | 'uri'
-  | (string & {});
-
-export type FormatPredicate = (value: string) => boolean;
-
-export class Formats {
-  private static readonly registry = new Map<string, FormatPredicate>();
-
-  static register(name: string, predicate: FormatPredicate): void {
-    this.registry.set(name, predicate);
-  }
-
-  static resolve(name: string): FormatPredicate | undefined {
-    return this.registry.get(name);
-  }
-}

package/src/schema/fields/FieldSet.ts

@@ -1,63 +0,0 @@
-import { Role } from '../axis/role/Role.js';
-import { FieldGroup } from './constraint/FieldGroup.js';
-import { Unique } from './constraint/Unique.js';
-import type { CompositeUnique } from '../../entity/EntityDeclarations.js';
-import { Field, type FieldName, type Fields } from './Field.js';
-
-export class FieldSet<TFields extends Fields = Fields> {
-  private constructor(private readonly fields: TFields) {}
-
-  static of<TFields extends Fields>(fields: TFields): FieldSet<TFields> {
-    return new FieldSet(fields);
-  }
-
-  /**
-   * Every entry through the field door, then the groups declared over several of them.
-   * A group written here names its members; one written on a field named itself, and the
-   * key it sat under resolved it.
-   */
-  static declared<TFields extends Fields>(
-    declared: TFields,
-    unique?: CompositeUnique<TFields>,
-  ): TFields {
-    let fields: Fields = {};
-    for (const [key, field] of Object.entries(declared))
-      fields[key] = new Field(field, key);
-    for (const group of unique ?? []) fields = new Unique(group).onto(fields);
-    return fields as TFields;
-  }
-
-  /**
-   * The name of the field that carries `primary`, or `undefined` when none does.
-   *
-   * `Role.of(field).isPrimary` answers about ONE field; this answers about a shape, which
-   * is the question every reader actually had. It was the same three lines spelled five
-   * times — a mirror's key, a form's row identity, GraphQL's node id, the DDL's primary
-   * key and the storage's `findById` column — so a shape with two primaries meant whichever
-   * one that loop happened to see first, five times over.
-   *
-   * The absence is answered and not defaulted: `'id'` is a fine fallback for a form and a
-   * lie for a DDL, so the caller decides.
-   */
-  get primary(): FieldName<TFields> | undefined {
-    const primaries = Object.entries(this.fields)
-      .filter(([, field]) => Role.of(field).isPrimary)
-      .map(([name]) => name);
-
-    if (primaries.length > 1) {
-      throw new Error(
-        `FieldSet.primary: ${primaries.map((name) => JSON.stringify(name)).join(', ')} all declare ` +
-          '`primary`; a field set can have only one primary field.',
-      );
-    }
-
-    return primaries[0] as FieldName<TFields> | undefined;
-  }
-
-  get uniqueGroups(): CompositeUnique<TFields> | undefined {
-    const groups = FieldGroup.groupsOf(this.fields, Unique);
-    return groups.length
-      ? (groups.map((group) => [...group.members]) as unknown as CompositeUnique<TFields>)
-      : undefined;
-  }
-}