@fougere/schema 0.3.0-alpha.0 → 0.4.0-alpha.0

package/src/card/EntityTypeSource.ts

@@ -0,0 +1,90 @@
+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/card/FacadeTypeSource.ts

@@ -0,0 +1,55 @@
+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/card/admission.ts

@@ -0,0 +1,25 @@
+import type { ValidationError } from '../judge/result.js';
+
+/** A card is refused by naming what is wrong AND the remedy — never by a bare throw. */
+export function refuse(what: string, fix: string): never {
+  throw new Error(`This card cannot be read: ${what}.\n  ${fix}`);
+}
+
+/**
+ * A wire value admitted by the axis's OWN judge — legal only where its declared and wire
+ * forms are the same value, which `describe: v => v` states.
+ */
+export function admitWire(
+  judge: (value: unknown, errors: ValidationError[]) => void,
+  value: unknown,
+  slot: string,
+): void {
+  const errors: ValidationError[] = [];
+  judge(value, errors);
+  if (errors.length) {
+    refuse(
+      `${slot} is malformed — ${errors.map((e) => `${e.path}: ${e.message}`).join('; ')}`,
+      'A card states an axis the way a declaration does.',
+    );
+  }
+}

package/src/card/diff.ts

@@ -0,0 +1,56 @@
+import type { BoundaryRef } from '../axis/boundary/Boundary.js';
+import type { LifecycleRules } from '../axis/lifecycle/Lifecycle.js';
+import type { FieldDescriptor, RoleDescriptor } from './Descriptor.js';
+
+/** One named difference, at one place. Each kind exists because a reader asks for it. */
+export type Change =
+  /** DDL: add the column. Codec: the old caller never sends it. Boot: refuse when required. */
+  | { kind: 'added'; field: string; to: FieldDescriptor; required: boolean }
+  /** DDL: drop the column. Codec: the old caller still sends it, and it goes nowhere. */
+  | { kind: 'removed'; field: string; from: FieldDescriptor; required: boolean }
+  /** DDL: rename the column. Codec and ORM: one more entry in the field-to-column map. */
+  | { kind: 'renamed'; from: string; to: string; field: FieldDescriptor }
+  /** DDL: alter the type. Codec: convert the value, when it can. */
+  | { kind: 'retyped'; field: string; from: TypeSet; to: TypeSet }
+  /** Same type, different bounds: a CHECK moves, and a value legal yesterday may not be. */
+  | { kind: 'reshaped'; field: string; from: FieldDescriptor; to: FieldDescriptor }
+  /** NOT NULL in either direction. Boot: an old writer cannot fill what it never knew. */
+  | { kind: 'required'; field: string; from: boolean; to: boolean }
+  /** An axis other than shape was restated. */
+  | { kind: 'restated'; field: string; axis: 'role'; from?: RoleDescriptor; to?: RoleDescriptor }
+  | { kind: 'restated'; field: string; axis: 'lifecycle'; from?: LifecycleRules; to?: LifecycleRules }
+  | { kind: 'restated'; field: string; axis: 'boundary'; from?: BoundaryRef; to?: BoundaryRef };
+
+/** A field's declared types, always represented as a set. */
+export type TypeSet = string[];
+
+/** A removal and an addition that could be one rename: same shape, different name. */
+export interface RenameCandidate {
+  removed: string;
+  added: string;
+}
+
+export interface Diff {
+  changes: Change[];
+  /** Questions the comparison refuses to decide without an explicit rename declaration. */
+  ambiguous: RenameCandidate[];
+}
+
+export interface DiffOptions {
+  /** Renames as declared at the time: old name to new name. */
+  renamed?: Record<string, string>;
+}
+
+export interface SetDiff {
+  /** Entities the target bundle has and the source bundle had not. */
+  entitiesAdded: string[];
+  /** Entities the source bundle had and the target bundle has not. */
+  entitiesRemoved: string[];
+  /** Differences for entities present in both bundles; unchanged entities are absent. */
+  entities: Record<string, Diff>;
+}
+
+export interface SetDiffOptions {
+  /** Declared renames, per entity: `{ post: { body: 'content' } }`. */
+  renamed?: Record<string, Record<string, string>>;
+}

package/src/constraint/FieldGroup.ts

@@ -0,0 +1,91 @@
+import type { Field, Fields } from "../fields/Field.js";
+
+export abstract class FieldGroup {
+  constructor(readonly members: readonly string[]) {}
+
+  protected withMembers(members: readonly string[]): this {
+    return new (this.constructor as new (members: readonly string[]) => this)(
+      members,
+    );
+  }
+
+  get isSelf(): boolean {
+    return this.members.length === 0;
+  }
+
+  resolvedOn(ownKey: string): this {
+    return this.isSelf ? this.withMembers([ownKey]) : this;
+  }
+
+  covers(key: string): boolean {
+    return this.members.includes(key);
+  }
+
+  equals(other: FieldGroup): boolean {
+    return (
+      this.constructor === other.constructor &&
+      this.members.length === other.members.length &&
+      this.members.every((member, i) => member === other.members[i])
+    );
+  }
+
+  onto(fields: Fields): Fields {
+    const missing = this.members.filter((key) => !(key in fields));
+    if (missing.length)
+      throw new Error(
+        `${this.constructor.name.toLowerCase()}: [${this.members.join(", ")}] names ` +
+          `${missing.map((m) => `'${m}'`).join(", ")}, which the entity does not declare.`,
+      );
+
+    const out: Fields = { ...fields };
+    for (const key of this.members) {
+      const field = out[key]!;
+      out[key] = field.with({
+        role: { ...field.role, rules: [...(field.role?.rules ?? []), this] },
+      });
+    }
+    return out;
+  }
+
+  rename(map: (key: string) => string | undefined): this | null {
+    if (this.isSelf) return this;
+    const carried = this.members.map(map);
+    return carried.every((key): key is string => key !== undefined)
+      ? this.withMembers(carried)
+      : null;
+  }
+
+  toJSON(): string[] {
+    return [...this.members];
+  }
+
+  static normalize<R extends FieldGroup>(
+    groups: readonly (R | readonly string[])[] | undefined,
+    make: (members: readonly string[]) => R,
+  ): readonly R[] | undefined {
+    if (!groups) return undefined;
+    return groups.map((group) =>
+      group instanceof FieldGroup ? (group as R) : make(group),
+    );
+  }
+
+  static on<R extends FieldGroup>(
+    field: Field,
+    kind: Function & { prototype: R },
+  ): R[] {
+    return (field.role?.rules ?? []).filter(
+      (rule): rule is R => rule instanceof kind,
+    );
+  }
+
+  static groupsOf<R extends FieldGroup>(
+    fields: Fields,
+    kind: Function & { prototype: R },
+  ): R[] {
+    const seen = new Map<string, R>();
+    for (const field of Object.values(fields))
+      for (const rule of FieldGroup.on(field, kind))
+        if (rule.members.length > 1) seen.set(rule.members.join(" "), rule);
+    return [...seen.values()];
+  }
+}

package/src/constraint/Unique.ts

@@ -0,0 +1,3 @@
+import { FieldGroup } from './FieldGroup.js';
+
+export class Unique extends FieldGroup {}

package/src/entity.ts

@@ -0,0 +1,15 @@
+import { type Fields } from './fields/Field.js';
+import { FieldSet } from './fields/FieldSet.js';
+import { type EntityDeclarations } from './EntityDeclarations.js';
+import { Schema, type SchemaConstructor } from './schema/Schema.js';
+
+export function entity<TFields extends Fields>(
+  originalFields: TFields,
+  { unique, adapters, previous }: EntityDeclarations<TFields> = {},
+): SchemaConstructor<TFields> {
+  return Schema.of({
+    fields: FieldSet.declared(originalFields, unique),
+    adapters,
+    previous,
+  });
+}

package/src/fields/Field.ts

@@ -0,0 +1,80 @@
+import type { Shape } from "../axis/shape/Shape.js";
+import { Role, type RoleRules } from "../axis/role/Role.js";
+import type { LifecycleRules } from "../axis/lifecycle/Lifecycle.js";
+import type { BoundaryRef } from "../axis/boundary/Boundary.js";
+import type { Meta } from "../axis/Meta.js";
+import type { Axis } from "../axis/Axis.js";
+import { FieldJudge } from "../judge/FieldJudge.js";
+import { ValueJudge } from "../judge/ValueJudge.js";
+
+export type Fields = Record<string, Field>;
+
+/** A key of a field set — the name a declaration addresses a field by. */
+export type FieldName<TFields extends Fields> = Extract<keyof TFields, string>;
+
+/** The carrier, the three extension axes, the annotation — the five the judge reads. */
+export type FieldDeclaration = Pick<Field, "shape" | Axis["slot"] | "meta">;
+
+export class Field<T = unknown> {
+  readonly shape: Shape;
+  readonly role?: RoleRules;
+  readonly lifecycle?: LifecycleRules;
+  readonly boundary?: BoundaryRef;
+  readonly meta?: Meta;
+
+  declare readonly _type?: T;
+
+  constructor(init: FieldDeclaration, key?: string) {
+    const verdict = FieldJudge.of(init).verdict;
+
+    if (!verdict.success) {
+      throw new Error(
+        `${key ? `Field '${key}': ` : ""}` +
+          verdict.errors.map((e) => `${e.path}: ${e.message}`).join("; "),
+      );
+    }
+
+    this.shape = init.shape;
+    this.role = Role.resolvedOn(init.role, key);
+    this.lifecycle = init.lifecycle;
+    this.boundary = init.boundary;
+    this.meta = init.meta;
+
+    const create = this.lifecycle?.create;
+    if (typeof create === "object" && create !== null && "value" in create) {
+      const checked = ValueJudge.of(this).check(create.value);
+      if ("error" in checked)
+        throw new Error(
+          `${key ? `Field '${key}': ` : ""}the declared default ${JSON.stringify(create.value)} ` +
+            `is not a legal value for it — ${checked.error}.`,
+        );
+    }
+  }
+
+  static is(value: unknown): value is Field {
+    return FieldJudge.of(value).verdict.success;
+  }
+
+  with<U = T>(overrides: Partial<FieldDeclaration>): Field<U> {
+    return new Field<U>({ ...this, ...overrides });
+  }
+
+  rename(map: (key: string) => string | undefined): Field<T> {
+    const rules = this.role?.rules;
+    if (!rules?.length) return this;
+
+    const carried = rules
+      .map((group) => group.rename(map))
+      .filter((group) => group !== null);
+    const unchanged =
+      carried.length === rules.length &&
+      carried.every((group, i) => group.equals(rules[i]!));
+    if (unchanged) return this;
+
+    const { rules: _dropped, ...rest } = this.role!;
+    return this.with({
+      role: carried.length ? { ...rest, rules: carried } : rest,
+    });
+  }
+}
+

package/src/fields/FieldSet.ts

@@ -0,0 +1,62 @@
+import { Role } from '../axis/role/Role.js';
+import { FieldGroup } from '../constraint/FieldGroup.js';
+import { Unique } from '../constraint/Unique.js';
+import type { CompositeUnique } from '../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 ORM'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;
+  }
+}

package/src/index.ts

@@ -0,0 +1,64 @@
+export { Field, type Fields } from './fields/Field.js';
+export { FieldSet } from './fields/FieldSet.js';
+export { type Shape, Anatomy } from './axis/shape/Shape.js';
+export { type StringFormat, type FormatPredicate, Formats } from './axis/shape/Formats.js';
+export { Role, type RoleRules } from './axis/role/Role.js';
+export { type Relation, type EntityConstructor } from './axis/role/Relation.js';
+export { Lifecycle, type LifecycleRules } from './axis/lifecycle/Lifecycle.js';
+export { type GeneratorRef, Generators } from './axis/lifecycle/Generators.js';
+export { Clock } from './axis/lifecycle/Clock.js';
+export { Boundary, type BoundaryRules, type BoundaryRef } from './axis/boundary/Boundary.js';
+export { type Decoder, type Encoder, Boundaries } from './axis/boundary/Boundaries.js';
+export { type Meta } from './axis/Meta.js';
+export { FieldGroup } from './constraint/FieldGroup.js';
+export { Unique } from './constraint/Unique.js';
+
+export { Schema, ANONYMOUS_SCHEMA_NAME, type SchemaConstructor } from './schema/Schema.js';
+export { SchemaDerivation } from './schema/SchemaDerivation.js';
+export { isObject } from './judge/ValueForm.js';
+export { Cases, type Case } from './judge/Cases.js';
+export { RowRefusal } from './judge/RowRefusal.js';
+export { type SchemaView, type Row, type PartialRow } from './schema/SchemaView.js';
+export { type FougereEntityAdapters, type EntityAdapters } from './EntityAdapters.js';
+export { lowerFirst, upperFirst } from './utils.js';
+
+export { primary } from './vocabulary/primary.js';
+export { text } from './vocabulary/text.js';
+export { email } from './vocabulary/email.js';
+export { url } from './vocabulary/url.js';
+export { list } from './vocabulary/list.js';
+export { number } from './vocabulary/number.js';
+export { bool } from './vocabulary/bool.js';
+export { date } from './vocabulary/date.js';
+export { created } from './vocabulary/created.js';
+export { updated } from './vocabulary/updated.js';
+export { oneOf } from './vocabulary/oneOf.js';
+export { ref } from './vocabulary/ref.js';
+export { many } from './vocabulary/many.js';
+export { optional } from './vocabulary/optional.js';
+export { nullable } from './vocabulary/nullable.js';
+export { immutable } from './vocabulary/immutable.js';
+export { unique } from './vocabulary/unique.js';
+export { indexed } from './vocabulary/indexed.js';
+export { readOnly } from './vocabulary/readOnly.js';
+export { writeOnly } from './vocabulary/writeOnly.js';
+export { json } from './vocabulary/json.js';
+
+export { applyCreate, applyUpdate } from './axis/lifecycle/apply.js';
+export { Visibility } from './projection/Visibility.js';
+export { Card } from './card/Card.js';
+export { Bundle } from './card/Bundle.js';
+export type { Change, Diff, DiffOptions, SetDiff, SetDiffOptions, RenameCandidate, TypeSet } from './card/diff.js';
+export { EntityTypeSource, type EntityTypeSourceOptions } from './card/EntityTypeSource.js';
+export { FacadeTypeSource, type FacadeTypeSourceOptions, type OpDescriptor } from './card/FacadeTypeSource.js';
+export { type SchemaBundle, type SchemaDescriptor, type FieldDescriptor, type FieldExtension, type RoleDescriptor, type RelationDescriptor } from './card/Descriptor.js';
+export { type SchemaOrCard, schemaOf, fieldsOf } from './projection/SchemaOrCard.js';
+export type { StandardSchemaV1 } from './projection/standard.js';
+
+export { entity } from './entity.js';
+
+export { FieldJudge } from './judge/FieldJudge.js';
+export { ValueJudge } from './judge/ValueJudge.js';
+export { RowJudge } from './judge/RowJudge.js';
+export { type ValidateOptions } from './judge/options.js';
+export { type ValidationError, type ValidationResult, type Checked } from './judge/result.js';