@fougere/schema 0.2.0-alpha.2 → 0.4.0-alpha.0

package/src/judge/ValueJudge.ts

@@ -0,0 +1,72 @@
+import { Validator, format as engineFormats } from '@cfworker/json-schema';
+import { Formats, type FormatPredicate } from '../axis/shape/Formats.js';
+import { Anatomy, type Shape } from '../axis/shape/Shape.js';
+import type { Field } from '../fields/Field.js';
+import type { Checked } from './result.js';
+
+interface ShapePlan {
+  validator: Validator;
+  custom?: FormatPredicate;
+  formatName?: string;
+}
+
+export class ValueJudge {
+  private static readonly plans = new WeakMap<object, ShapePlan>();
+
+  private constructor(private readonly field: Field) {}
+
+  static of(field: Field): ValueJudge {
+    return new ValueJudge(field);
+  }
+
+  check(value: unknown): Checked {
+    const shape = this.field.shape;
+    const base = Anatomy.of(shape).base;
+    if (value !== null) {
+      if (base?.type === 'object' && !base.properties) return { value };
+      if (base?.type === 'string' && base.format === 'date-time' && value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? { error: 'Invalid date' } : { value };
+      }
+      if (
+        (base?.type === 'number' || base?.type === 'integer') &&
+        typeof value === 'number' &&
+        Number.isNaN(value)
+      ) {
+        return { error: 'Expected a number' };
+      }
+    }
+    const plan = ValueJudge.planFor(shape);
+    const result = plan.validator.validate(value);
+    if (!result.valid) return { error: result.errors[0]?.error ?? 'Invalid value' };
+    if (plan.custom && typeof value === 'string' && !plan.custom(value)) {
+      return { error: `String does not match format "${plan.formatName}".` };
+    }
+    return { value };
+  }
+
+  private static planFor(shape: Shape): ShapePlan {
+    let plan = this.plans.get(shape);
+    if (!plan) {
+      const base = Anatomy.of(shape).base;
+      const formatName = base?.type === 'string' ? base.format : undefined;
+      plan = {
+        validator: new Validator(shape as object, '2020-12', true),
+        custom: formatName === undefined ? undefined : this.customFormatOf(formatName),
+        formatName,
+      };
+      this.plans.set(shape, plan);
+    }
+    return plan;
+  }
+
+  private static customFormatOf(name: string): FormatPredicate | undefined {
+    const custom = Formats.resolve(name);
+    if (!custom && !(name in engineFormats)) {
+      throw new Error(
+        `Unknown format: '${name}'. Register it with Formats.register('${name}', …) — ` +
+          `the engine judges ${Object.keys(engineFormats).length} formats natively and this is not one of them.`,
+      );
+    }
+    return custom;
+  }
+}

package/src/judge/options.ts

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

package/src/judge/result.ts

@@ -0,0 +1,10 @@
+export interface ValidationError {
+  path: string;
+  message: string;
+}
+
+export type ValidationResult<T> =
+  | { success: true; data: T }
+  | { success: false; errors: ValidationError[] };
+
+export type Checked = { value: unknown } | { error: string };

package/src/projection/SchemaOrCard.ts

@@ -0,0 +1,18 @@
+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/projection/Visibility.ts

@@ -0,0 +1,47 @@
+import { Boundary } from '../axis/boundary/Boundary.js';
+import { Lifecycle } from '../axis/lifecycle/Lifecycle.js';
+import { Role } from '../axis/role/Role.js';
+import type { Fields } from '../fields/Field.js';
+
+export class Visibility {
+  private constructor(private readonly fields: Fields) {}
+
+  static of(fields: Fields): Visibility {
+    return new Visibility(fields);
+  }
+
+  get input(): Fields {
+    const result: Fields = {};
+    for (const [name, field] of Object.entries(this.fields)) {
+      const role = Role.of(field);
+      if (role.isPrimary) continue;
+      if (Lifecycle.of(field).create === 'now') continue;
+      if (role.isCollection) continue;
+      if (Boundary.of(field).readOnly) continue;
+      result[name] = field;
+    }
+    return result;
+  }
+
+  get output(): Fields {
+    const result: Fields = {};
+    for (const [name, field] of Object.entries(this.fields)) {
+      if (Boundary.of(field).writeOnly) continue;
+      result[name] = field;
+    }
+    return result;
+  }
+
+  encode(record: Record<string, unknown>): Record<string, unknown> {
+    const out: Record<string, unknown> = { ...record };
+    for (const [key, field] of Object.entries(this.fields)) {
+      if (!(key in record)) continue;
+      const boundary = Boundary.of(field);
+      if (boundary.writeOnly) { delete out[key]; continue; }
+      const value = record[key];
+      if (value === null || value === undefined) continue;
+      out[key] = boundary.encode(value);
+    }
+    return out;
+  }
+}

package/src/projection/standard.ts

@@ -0,0 +1,47 @@
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+
+export declare namespace StandardSchemaV1 {
+  interface Props<Input = unknown, Output = Input> {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (
+      value: unknown,
+    ) => Result<Output> | Promise<Result<Output>>;
+    readonly types?: Types<Input, Output> | undefined;
+  }
+
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+
+  interface SuccessResult<Output> {
+    readonly value: Output;
+    readonly issues?: undefined;
+  }
+
+  interface FailureResult {
+    readonly issues: readonly Issue[];
+  }
+
+  interface Issue {
+    readonly message: string;
+    readonly path?: readonly (PropertyKey | PathSegment)[] | undefined;
+  }
+
+  interface PathSegment {
+    readonly key: PropertyKey;
+  }
+
+  interface Types<Input = unknown, Output = Input> {
+    readonly input: Input;
+    readonly output: Output;
+  }
+
+  type InferInput<Schema extends StandardSchemaV1> = NonNullable<
+    Schema['~standard']['types']
+  >['input'];
+
+  type InferOutput<Schema extends StandardSchemaV1> = NonNullable<
+    Schema['~standard']['types']
+  >['output'];
+}

package/src/schema/Schema.ts

@@ -0,0 +1,167 @@
+import { Boundary } from '../axis/boundary/Boundary.js';
+import { type Fields } from '../fields/Field.js';
+import { type PreviousNames } from '../EntityDeclarations.js';
+import { type EntityAdapters } from '../EntityAdapters.js';
+import { FieldGroup } from '../constraint/FieldGroup.js';
+import { Unique } from '../constraint/Unique.js';
+import { type CompositeUnique } from '../EntityDeclarations.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>;
+  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>;
+  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 five 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; }
+
+  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);
+  }
+
+  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>;
+  }): 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

@@ -0,0 +1,87 @@
+import { type Fields } from '../fields/Field.js';
+import { 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 five members used to be five 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,
+  ) {}
+
+  static stated(said: {
+    fields: Fields;
+    adapters?: EntityAdapters<Fields>;
+    opts?: ValidateOptions;
+    previous?: PreviousNames<Fields>;
+    derivation?: SchemaDerivation;
+  }): SchemaDefinition {
+    return new SchemaDefinition(
+      said.fields, EntityAdapterSet.of(said.adapters)?.stated, said.opts ?? {}, said.previous, said.derivation,
+    );
+  }
+
+  /**
+   * `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),
+    );
+  }
+
+  /** 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),
+    );
+  }
+
+  /** 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),
+    );
+  }
+
+  /** 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);
+  }
+
+  /** The origin this definition already carries, or the one `root` becomes. */
+  private origin(root: SchemaView): SchemaDerivation {
+    return this.derivation ?? SchemaDerivation.first(root, this.fields);
+  }
+}

package/src/schema/SchemaDerivation.ts

@@ -0,0 +1,46 @@
+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;
+  }
+
+  /**
+   * 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/SchemaView.ts

@@ -0,0 +1,25 @@
+import type { Field, Fields } from '../fields/Field.js';
+import type { CompositeUnique, PreviousNames } from '../EntityDeclarations.js';
+import type { EntityAdapters } from '../EntityAdapters.js';
+import type { ValidationResult } from '../judge/result.js';
+import type { ValidateOptions } from '../judge/options.js';
+import type { SchemaDerivation } from './SchemaDerivation.js';
+
+export type Row<TFields extends Fields> = {
+  [K in keyof TFields]: TFields[K] extends Field<infer T> ? T : never;
+};
+
+export type PartialRow<TFields extends Fields> = Partial<Row<TFields>>;
+
+export interface SchemaView<TFields extends Fields = Fields> {
+  readonly name: string;
+  /** What this schema was cut from, when it was cut from anything. */
+  readonly derivation?: SchemaDerivation;
+  /** What its fields were called before, keyed by the names they carry now. */
+  readonly previous?: PreviousNames<TFields>;
+  getFields(): TFields;
+  getAdapters(): EntityAdapters<TFields> | undefined;
+  getUnique(): CompositeUnique<TFields> | undefined;
+  getOpts(): ValidateOptions;
+  validate(input: unknown): ValidationResult<Row<TFields>>;
+}

package/src/utils.ts

@@ -0,0 +1,13 @@
+export function lowerFirst(text: string): string {
+  return text ? text[0].toLowerCase() + text.slice(1) : text;
+}
+
+export function upperFirst(text: string): string {
+  return text ? text[0].toUpperCase() + text.slice(1) : text;
+}
+
+export function clean<T extends Record<string, unknown>>(obj: T): T {
+  for (const key of Object.keys(obj)) if (obj[key] === undefined) delete obj[key];
+
+  return obj;
+}

package/src/vocabulary/bool.ts

@@ -0,0 +1,9 @@
+import { Field } from '../fields/Field.js';
+
+export function bool(opts?: { default?: boolean; description?: string }): Field<boolean> {
+  return new Field<boolean>({
+    shape: { type: 'boolean' },
+    lifecycle: opts?.default !== undefined ? { create: { value: opts.default } } : undefined,
+    meta: opts?.description !== undefined ? { description: opts.description } : undefined,
+  });
+}

package/src/vocabulary/created.ts

@@ -0,0 +1,8 @@
+import { Field } from '../fields/Field.js';
+import { date } from './date.js';
+
+export function created(): Field<Date> {
+  return date().with({
+    lifecycle: { create: "now", update: "forbidden" },
+  });
+}

package/src/vocabulary/date.ts

@@ -0,0 +1,5 @@
+import { Field } from '../fields/Field.js';
+
+export function date(): Field<Date> {
+  return new Field<Date>({ shape: { type: 'string', format: 'date-time' } });
+}

package/src/vocabulary/email.ts

@@ -0,0 +1,6 @@
+import { text, type TextOptions } from './text.js';
+import type { Field } from '../fields/Field.js';
+
+export function email(opts?: Omit<TextOptions, 'format'>): Field<string> {
+  return text({ ...opts, format: 'email' });
+}

package/src/vocabulary/immutable.ts

@@ -0,0 +1,6 @@
+import { vocabulary } from './vocabulary.js';
+import { Field } from '../fields/Field.js';
+
+export const immutable: <T>(field: Field<T>) => Field<T> = vocabulary('immutable', () => ({
+  lifecycle: { update: 'forbidden' },
+}));

package/src/vocabulary/indexed.ts

@@ -0,0 +1,4 @@
+import { vocabulary } from './vocabulary.js';
+import { Field } from '../fields/Field.js';
+
+export const indexed: <T>(field: Field<T>) => Field<T> = vocabulary('indexed', () => ({ role: { index: true } }));

package/src/vocabulary/json.ts

@@ -0,0 +1,22 @@
+import { Field } from '../fields/Field.js';
+import type { SchemaView } from '../schema/SchemaView.js';
+import { RowJudge } from '../judge/RowJudge.js';
+
+export function json<T = unknown>(): Field<T>;
+export function json<E extends SchemaView & (new (...args: any[]) => any)>(of: E): Field<InstanceType<E>>;
+export function json(of?: SchemaView): Field<unknown> {
+  if (!of) return new Field({ shape: { type: 'object' } });
+  const fields = of.getFields();
+  const judge = RowJudge.of(fields);
+  const properties: Record<string, unknown> = {};
+  const required: string[] = [];
+  for (const [key, field] of Object.entries(fields)) {
+    properties[key] = field.meta?.description
+      ? { ...field.shape, description: field.meta.description }
+      : field.shape;
+    if (judge.onAbsent(field) === null) required.push(key);
+  }
+  return new Field({
+    shape: { type: 'object', properties, ...(required.length ? { required } : {}) },
+  });
+}

package/src/vocabulary/list.ts

@@ -0,0 +1,13 @@
+import { Field } from '../fields/Field.js';
+
+export interface ListOptions {
+  min?: number;
+  max?: number;
+}
+
+export function list<T>(item: Field<T>, opts?: ListOptions): Field<T[]> {
+  if (item.role?.relation) throw new Error('list() takes a value field (text(), number()…) — a relation has no value shape');
+  return new Field<T[]>({
+    shape: { type: 'array', items: item.shape, minItems: opts?.min, maxItems: opts?.max },
+  });
+}

package/src/vocabulary/many.ts

@@ -0,0 +1,9 @@
+import { Relation, type EntityConstructor } from '../axis/role/Relation.js';
+import { Field } from '../fields/Field.js';
+
+export function many<E extends EntityConstructor>(target: E | (() => E)): Field<InstanceType<E>[]> {
+  return new Field<InstanceType<E>[]>({
+    shape: { type: 'array' },
+    role: { relation: Relation.many(target) },
+  });
+}

package/src/vocabulary/nullable.ts

@@ -0,0 +1,7 @@
+import { vocabulary } from './vocabulary.js';
+import { Anatomy } from '../axis/shape/Shape.js';
+import { type Field } from '../fields/Field.js';
+
+export const nullable: <T>(field: Field<T>) => Field<T | null> = vocabulary('nullable', (field) => ({
+  shape: Anatomy.nullable(field.shape),
+}));

package/src/vocabulary/number.ts

@@ -0,0 +1,17 @@
+import { Field } from '../fields/Field.js';
+
+export interface NumberOptions {
+  min?: number;
+  max?: number;
+  integer?: boolean;
+  default?: number;
+  description?: string;
+}
+
+export function number(opts?: NumberOptions): Field<number> {
+  return new Field<number>({
+    shape: { type: opts?.integer ? 'integer' : 'number', minimum: opts?.min, maximum: opts?.max },
+    lifecycle: opts?.default !== undefined ? { create: { value: opts.default } } : undefined,
+    meta: opts?.description !== undefined ? { description: opts.description } : undefined,
+  });
+}