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

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,11 @@
+/**
+ * The Standard Schema interface, from the package that owns it.
+ *
+ * This file used to CARRY the spec — 47 lines of hand-copied interface — and the copy had
+ * silently fallen a version behind: v1.1 gave `Props` a base it extends (`StandardTypedV1`)
+ * and gave `validate` a second `options` parameter. Nothing broke, because a realization may
+ * ignore an optional argument, which is exactly why nobody noticed. A standard is owned by
+ * whoever publishes it; the package is types only (`index.js` is zero bytes), so importing
+ * it costs a browser nothing.
+ */
+export type { StandardSchemaV1 } from '@standard-schema/spec';

package/src/schema/Schema.ts

@@ -0,0 +1,197 @@
+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

@@ -0,0 +1,120 @@
+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

@@ -0,0 +1,57 @@
+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/SchemaView.ts

@@ -0,0 +1,27 @@
+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>;
+  /** Does it hold rows of its own? False on a derivation means an answer. */
+  readonly anchored?: boolean;
+  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,
+  });
+}

package/src/vocabulary/oneOf.ts

@@ -0,0 +1,24 @@
+import { Field } from '../fields/Field.js';
+
+interface OneOfOptions<V extends string = string> {
+  description?: string;
+  default?: V;
+}
+
+export function oneOf<const T extends readonly string[]>(...values: [...T]): Field<T[number]>;
+export function oneOf<const T extends readonly string[]>(
+  ...args: [...T, OneOfOptions<T[number]>]
+): Field<T[number]>;
+export function oneOf<const T extends readonly string[]>(
+  ...args: [...T] | [...T, OneOfOptions<T[number]>]
+): Field<T[number]> {
+  const last = args[args.length - 1];
+  const hasOpts = typeof last === 'object' && last !== null && !Array.isArray(last);
+  const values = (hasOpts ? args.slice(0, -1) : args) as unknown as readonly string[];
+  const opts = hasOpts ? (last as OneOfOptions) : {};
+  return new Field<T[number]>({
+    shape: { type: 'string', enum: values },
+    lifecycle: opts.default !== undefined ? { create: { value: opts.default } } : undefined,
+    meta: opts.description !== undefined ? { description: opts.description } : undefined,
+  });
+}

package/src/vocabulary/optional.ts

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