@ultimat3/schema 1.1.0 → 2.0.0

package/src/errors.ts

@@ -20,6 +20,12 @@ export const SCHEMA_ERROR_CODES: Readonly<Record<string, SchemaErrorCodeDeclarat
   Object.freeze({
     X_VALIDATION_FAILED: { title: 'value did not match its schema' },
     X_SCHEMA_UNSUPPORTED: { title: 'the active schema provider cannot do this' },
+    X_SCHEMA_DISCRIMINANT_INVALID: {
+      title: 'a discriminated union member can never be dispatched to',
+    },
+    X_SCHEMA_DEFAULT_UNSHAREABLE: {
+      title: 'a schema default cannot be copied per parse',
+    },
   });
 
 /**
@@ -127,6 +133,20 @@ export class ValidationFailedError extends SchemaError {
   }
 }
 
+/**
+ * Thrown where the union is BUILT, not where a value is parsed: a member no tag can route to is
+ * wrong for every input, so the first import of the authoring file is the earliest honest place
+ * to say so — never a request that quietly took the wrong branch.
+ */
+export class DiscriminantInvalidError extends SchemaError {
+  static readonly code = 'X_SCHEMA_DISCRIMINANT_INVALID';
+  override readonly name = 'DiscriminantInvalidError';
+
+  constructor(init: Omit<SchemaErrorInit, 'code'>) {
+    super({ ...init, code: DiscriminantInvalidError.code });
+  }
+}
+
 export class SchemaUnsupportedError extends SchemaError {
   static readonly code = 'X_SCHEMA_UNSUPPORTED';
   override readonly name = 'SchemaUnsupportedError';

package/src/index.ts

@@ -7,24 +7,18 @@ export type {
   CheckOk,
   CheckResult,
   Path,
+  Refinement,
   Schema,
   Shape,
   ShapeInput,
   ShapeOutput,
   Simplify,
 } from './builder';
-export {
-  checkOf,
-  describeValue,
-  expected,
-  fail,
-  failWith,
-  makeSchema,
-  pass,
-  VENDOR,
-} from './builder';
+export { checkOf, fail, failWith, makeSchema, pass, VENDOR } from './builder';
 export type { QuerySource } from './coerce';
 export { coerceInput, coerceNode, coerceQuery } from './coerce';
+export { describeValue, expected } from './describe-value';
+export { discriminatedUnionSchema } from './discriminated-union';
 export type {
   SchemaErrorCodeDeclaration,
   SchemaErrorInit,
@@ -32,6 +26,7 @@ export type {
   ValidationIssue,
 } from './errors';
 export {
+  DiscriminantInvalidError,
   isSchemaError,
   SCHEMA_ERROR_CODES,
   SchemaError,
@@ -42,11 +37,19 @@ export {
 export type {
   JsonSchema,
   JsonSchemaDialect,
+  JsonSchemaDiscriminator,
   JsonSchemaType,
   ToJsonSchemaOptions,
 } from './json-schema';
 export { nodeToJsonSchema, toJsonSchema, toMcpInputSchema } from './json-schema';
-export type { SchemaFormat, SchemaKind, SchemaNode } from './node';
+export type { MoneyValue } from './money-value';
+export {
+  CURRENCY_CODE_PATTERN,
+  isCurrencyCode,
+  isMoneyScale,
+  MAX_MONEY_SCALE,
+} from './money-value';
+export type { SchemaFormat, SchemaKind, SchemaNode, SchemaRefinement } from './node';
 export { isSchemaNode, nodeOf, requiredKeys } from './node';
 export type { SchemaProvider } from './provider';
 export {
@@ -83,7 +86,6 @@ export {
 export type { Infer } from './t';
 export { t } from './t';
 export type {
-  MoneyValue,
   NumberSchema,
   ObjectSchema,
   StringSchema,
@@ -98,5 +100,6 @@ export {
   objectSchema,
   optionalSchema,
   recordSchema,
+  refineSchema,
   unionSchema,
 } from './validators';

package/src/json-schema.ts

@@ -2,10 +2,24 @@
 // bodies and MCP tool `inputSchema` are both this function's output, so an agent's view of an
 // action and an HTTP client's view can never drift.
 
-import { requiredKeys, type SchemaNode } from './node';
+import { CURRENCY_CODE_PATTERN, MAX_MONEY_SCALE } from './money-value';
+import { requiredKeys, type SchemaNode, type SchemaRefinement } from './node';
 import { introspect } from './provider';
 
-export type JsonSchemaType = 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array';
+export type JsonSchemaType =
+  | 'string'
+  | 'number'
+  | 'integer'
+  | 'boolean'
+  | 'object'
+  | 'array'
+  /** Only ever emitted as the second branch of a nullable field's `anyOf` — see `annotate`. */
+  | 'null';
+
+/** OpenAPI 3.1's tagged-union hint. `propertyName` alone: the branches here are inline, not `$ref`. */
+export interface JsonSchemaDiscriminator {
+  readonly propertyName: string;
+}
 
 export interface JsonSchema {
   readonly $schema?: string;
@@ -25,7 +39,14 @@ export interface JsonSchema {
   readonly additionalProperties?: boolean | JsonSchema;
   readonly items?: JsonSchema;
   readonly anyOf?: readonly JsonSchema[];
+  readonly discriminator?: JsonSchemaDiscriminator;
   readonly title?: string;
+  /**
+   * The refinements a consumer can act on mechanically. The prose copy also lands in
+   * `description`, because that is the only field an LLM reading an MCP tool schema is
+   * guaranteed to see — the extension is for code generators, the description is for readers.
+   */
+  readonly 'x-ultimate-refinements'?: readonly SchemaRefinement[];
 }
 
 export type JsonSchemaDialect = '2020-12' | 'draft-07';
@@ -64,12 +85,48 @@ function stringNode(node: SchemaNode): JsonSchema {
   };
 }
 
+/**
+ * JSON Schema's `pattern` is an ECMA-262 source with no flag syntax, so a flagged pattern is
+ * stated in prose instead of silently narrowed: a consumer applying `pattern` alone would refuse
+ * values this schema accepts, and there is nowhere honest to hide that.
+ */
+function patternNote(node: SchemaNode): string | undefined {
+  if (node.pattern === undefined) return undefined;
+  const flags = node.patternFlags;
+  return flags === undefined || flags === ''
+    ? undefined
+    : `pattern is applied with RegExp flags "${flags}"`;
+}
+
 function convert(node: SchemaNode): JsonSchema {
-  const annotate = (schema: JsonSchema): JsonSchema => ({
-    ...schema,
-    ...(node.description === undefined ? {} : { description: node.description }),
+  const refinements = node.refinements ?? [];
+  const notes = [
+    node.description,
+    patternNote(node),
+    ...refinements.map((refinement) => refinement.message),
+  ].filter((part): part is string => part !== undefined);
+  const described = notes.length === 0 ? undefined : notes.join(' — ');
+
+  const annotations: JsonSchema = {
+    ...(described === undefined ? {} : { description: described }),
     ...(node.hasDefault === true ? { default: node.default } : {}),
-  });
+    ...(refinements.length === 0 ? {} : { 'x-ultimate-refinements': refinements }),
+  };
+
+  /**
+   * `null` is a VALUE the field holds, so it joins the type union rather than the annotations —
+   * `{ anyOf: [<converted>, { type: 'null' }] }`, which is how OpenAPI 3.1 / JSON Schema 2020-12
+   * spell it (3.0's `nullable: true` keyword is gone). Dropping it published a contract every
+   * surface at once disagreed with: OpenAPI bodies, MCP `inputSchema`, `respondToolFor` and the
+   * typed client all forbade a `null` the action's own `output:` validator returns.
+   *
+   * The annotations stay OUTSIDE the `anyOf` — they describe the field, not one branch of it —
+   * and `requiredKeys` is untouched, because nullable is not optional: the key is still sent.
+   */
+  const annotate = (schema: JsonSchema): JsonSchema =>
+    node.nullable === true
+      ? { anyOf: [schema, { type: 'null' }], ...annotations }
+      : { ...schema, ...annotations };
 
   switch (node.kind) {
     case 'string':
@@ -94,7 +151,14 @@ function convert(node: SchemaNode): JsonSchema {
         items: node.items === undefined ? {} : convert(node.items),
       });
     case 'union':
-      return annotate({ anyOf: (node.anyOf ?? []).map(convert) });
+      return annotate({
+        anyOf: (node.anyOf ?? []).map(convert),
+        // Only when the union actually dispatches on a key: an untagged `t.union` carrying a
+        // `discriminator` would tell a generator to read a property no member declares.
+        ...(node.discriminant === undefined
+          ? {}
+          : { discriminator: { propertyName: node.discriminant } }),
+      });
     case 'record':
       return annotate({
         type: 'object',
@@ -104,8 +168,26 @@ function convert(node: SchemaNode): JsonSchema {
       return annotate({
         type: 'object',
         properties: {
-          minor: { type: 'integer', description: 'amount in minor units, never a float' },
-          currency: { type: 'string', pattern: '^[A-Z]{3}$' },
+          minor: {
+            type: 'integer',
+            description: 'amount in minor units, never a float',
+            // The safe-integer range the validator enforces, so a generated client refuses the
+            // same value the boundary does instead of learning about it from a 500.
+            minimum: -Number.MAX_SAFE_INTEGER,
+            maximum: Number.MAX_SAFE_INTEGER,
+          },
+          // The pattern the validator applies, not a copy of it: this object IS the contract a
+          // generated client checks against, so a widened predicate here would be a client
+          // refusing a code the boundary accepts.
+          currency: { type: 'string', pattern: CURRENCY_CODE_PATTERN },
+          // Optional, never required: `additionalProperties: false` alone would make a generated
+          // client refuse a scaled amount the framework's own validator accepts.
+          scale: {
+            type: 'integer',
+            description: 'decimal places `minor` counts; absent means the currency’s own',
+            minimum: 0,
+            maximum: MAX_MONEY_SCALE,
+          },
         },
         required: ['minor', 'currency'],
         additionalProperties: false,

package/src/money-value.ts

@@ -0,0 +1,142 @@
+// Single responsibility: the framework's ONE money declaration and the validator that guards it.
+// Split out of `validators.ts` because it is the only builtin whose *shape* other packages alias
+// — `@ultimat3/money`'s `Money`, `@ultimat3/entity`'s `MoneyValue` — so it earns a file a reader
+// can open by name instead of scrolling to.
+
+import { fail, failWith, isPlainObject, makeSchema, pass, type Schema } from './builder';
+import { expected } from './describe-value';
+import type { StandardIssue } from './standard';
+
+/**
+ * The shape of an ISO 4217 alphabetic code, as a pattern SOURCE — the one declaration every
+ * projection of that bound derives from. It is a string rather than a `RegExp` because the two
+ * surfaces that cannot call a predicate need the source itself: `json-schema.ts` emits it as the
+ * `pattern` of the published OpenAPI contract, and `@ultimat3/entity`'s `currencyCheck` emits it
+ * inside a Postgres `~` CHECK so a psql session cannot write a code the app would refuse to read.
+ *
+ * Keep it inside the syntax ECMAScript, JSON Schema and POSIX ERE spell identically — anchors,
+ * a literal character class, a bounded repetition. A construct only one of the three understands
+ * (`\d`, a lookahead, a non-greedy quantifier) makes the CHECK stop meaning what `isCurrencyCode`
+ * means, and a real server is the first thing that says so.
+ */
+export const CURRENCY_CODE_PATTERN = '^[A-Z]{3}$';
+
+const CURRENCY_RE = new RegExp(CURRENCY_CODE_PATTERN);
+
+/**
+ * The framework's ONE declaration of a money value. `@ultimat3/money`'s `Money` and
+ * `@ultimat3/entity`'s `MoneyValue` are aliases of this type, not copies of its shape — three
+ * structural restatements are how `minor` became a `number` here and a `bigint` there, which made
+ * a row the entity layer produced fail `t.money` and throw inside `JSON.stringify`.
+ *
+ * It lives at tier 0 because that is the only tier every other package may import, and `number`
+ * rather than `bigint` because money crosses the wire on every surface this framework projects —
+ * `JSON.stringify` refuses a bigint, and this node is also the OpenAPI contract. A value past
+ * `Number.MAX_SAFE_INTEGER` is refused HERE, at the boundary, with the field path — and again
+ * where it is decoded; it is never widened.
+ *
+ * Never a float, and never an amount without its currency.
+ */
+export interface MoneyValue {
+  readonly minor: number;
+  readonly currency: string;
+  /**
+   * Decimal places `minor` counts, when they are not the currency's own. Absent — the shape every
+   * existing value and every existing row still has — means the currency's natural minor unit: 2
+   * for USD, 0 for JPY, 3 for KWD. `{ minor: 2, currency: 'USD', scale: 6 }` is $0.000002.
+   *
+   * It exists because a cents-only value could not name a sub-cent amount at all, so the one
+   * place that needed one — a model call costing $0.00016 — rounded it up to a whole cent and
+   * reported 62x the real spend. The alternative was a second money type, which is the axiom-1
+   * violation this declaration exists to prevent.
+   */
+  readonly scale?: number;
+}
+
+/**
+ * The largest decimal exponent a money value may carry. 10^15 is the last power of ten that is
+ * itself a safe integer, so a finer scale could not name its own unit inside the range `minor` is
+ * already checked against.
+ */
+export const MAX_MONEY_SCALE = 15;
+
+/**
+ * What a legal `MoneyValue.currency` is — declared once, here, beside the type that carries it and
+ * beside `isMoneyScale`, which is the twin of this predicate and the precedent for it. Takes
+ * `unknown` because every caller is a boundary: a row off a `char(3)` column, a body off the wire,
+ * a `registerCurrency` argument from an untyped caller. `String(value).test(…)` on a symbol throws
+ * where a refusal was due, so the `typeof` half belongs in here rather than at each call.
+ */
+export function isCurrencyCode(value: unknown): value is string {
+  return typeof value === 'string' && CURRENCY_RE.test(value);
+}
+
+/** What a legal `MoneyValue.scale` is — declared once, here, beside the type that carries it. */
+export function isMoneyScale(value: unknown): value is number {
+  return (
+    typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= MAX_MONEY_SCALE
+  );
+}
+
+export const moneySchema: Schema<MoneyValue, MoneyValue> = makeSchema<MoneyValue, MoneyValue>(
+  {
+    kind: 'money',
+    description: 'integer minor units plus an ISO 4217 currency code',
+    properties: {
+      minor: {
+        kind: 'number',
+        integer: true,
+        minimum: -Number.MAX_SAFE_INTEGER,
+        maximum: Number.MAX_SAFE_INTEGER,
+      },
+      currency: { kind: 'string', pattern: CURRENCY_CODE_PATTERN },
+      scale: {
+        kind: 'number',
+        integer: true,
+        optional: true,
+        minimum: 0,
+        maximum: MAX_MONEY_SCALE,
+        description: 'decimal places `minor` counts; absent means the currency’s own',
+      },
+    },
+  },
+  (value, path) => {
+    if (!isPlainObject(value)) return fail(path, expected('a Money object', value));
+    const minor = value['minor'];
+    const currency = value['currency'];
+    const scale = value['scale'];
+    const issues: StandardIssue[] = [];
+    // Safe, not merely whole: `money()` and `entity`'s `parseMinor` both demand a safe integer, so
+    // `Number.isInteger` here let 2^53 through the boundary as a 200 and failed at the row write
+    // as a 500 — the same value refused twice, once with a field path and once without.
+    if (typeof minor !== 'number' || !Number.isSafeInteger(minor)) {
+      issues.push({
+        message: expected('a safe integer number of minor units', minor),
+        path: [...path, 'minor'],
+      });
+    }
+    if (!isCurrencyCode(currency)) {
+      issues.push({
+        message: expected('a 3-letter ISO 4217 code', currency),
+        path: [...path, 'currency'],
+      });
+    }
+    if (scale !== undefined && !isMoneyScale(scale)) {
+      issues.push({
+        message: expected(
+          `a whole number of decimal places between 0 and ${MAX_MONEY_SCALE}`,
+          scale,
+        ),
+        path: [...path, 'scale'],
+      });
+    }
+    if (issues.length > 0) return failWith(issues);
+    // The key is carried only when it was sent: a value at the currency's own scale must
+    // round-trip byte-for-byte, or every stored amount in every app changes shape on one parse.
+    return pass({
+      minor: minor as number,
+      currency: currency as string,
+      ...(scale === undefined ? {} : { scale: scale as number }),
+    });
+  },
+);

package/src/node.ts

@@ -27,6 +27,17 @@ export type SchemaFormat =
   | 'locale'
   | 'cursor';
 
+/**
+ * A refinement as the IR carries it: the predicate's *declaration*, never the predicate. A closure
+ * cannot cross into OpenAPI or an MCP tool schema, so what ships is the name and the rule text —
+ * enough for a generated client to state the constraint and for a form to label the failure.
+ */
+export interface SchemaRefinement {
+  readonly name: string;
+  readonly message: string;
+  readonly path?: readonly string[] | undefined;
+}
+
 export interface SchemaNode {
   readonly kind: SchemaKind;
   readonly optional?: boolean | undefined;
@@ -40,6 +51,12 @@ export interface SchemaNode {
   readonly maxLength?: number | undefined;
   /** Source string of the RegExp, so the node stays JSON-serialisable. */
   readonly pattern?: string | undefined;
+  /**
+   * The RegExp's flags, carried beside the source for the same reason. Dropping them made
+   * `t.string.pattern(/^[a-z]+$/i)` reject `ABC` while quoting the pattern that matches it.
+   * JSON Schema's `pattern` has no flags, so `json-schema.ts` states them in `description`.
+   */
+  readonly patternFlags?: string | undefined;
   readonly minimum?: number | undefined;
   readonly maximum?: number | undefined;
   readonly integer?: boolean | undefined;
@@ -48,7 +65,19 @@ export interface SchemaNode {
   readonly values?: readonly (string | number)[] | undefined;
   readonly literal?: string | number | boolean | null | undefined;
   readonly anyOf?: readonly SchemaNode[] | undefined;
+  /**
+   * The key a `union` dispatches on. Additive rather than a `'discriminatedUnion'` kind: every
+   * consumer that switches on `kind` — `json-schema.ts`, `coerce.ts`, `action`'s sample generator,
+   * the admin form generator — already handles `'union'` correctly, and a new kind would have
+   * fallen through each of their `default:` branches to an empty schema without failing anything.
+   */
+  readonly discriminant?: string | undefined;
   readonly valueNode?: SchemaNode | undefined;
+  /**
+   * Rules the structural fields cannot state. Carried beside `kind` rather than wrapping it for
+   * the reason `discriminant` is: a refined string must still read as a string everywhere.
+   */
+  readonly refinements?: readonly SchemaRefinement[] | undefined;
 }
 
 export function isSchemaNode(value: unknown): value is SchemaNode {

package/src/t.ts

@@ -2,16 +2,11 @@
 // Every member delegates to the active provider, so `configureSchemaProvider()` takes effect
 // even for modules that captured `t` at import time.
 
-import type { AnySchema, Schema, Shape } from './builder';
+import type { AnySchema, Refinement, Schema, Shape } from './builder';
+import type { MoneyValue } from './money-value';
 import { schemaProvider } from './provider';
 import type { InferInput, InferOutput, StandardSchemaV1 } from './standard';
-import type {
-  MoneyValue,
-  NumberSchema,
-  ObjectSchema,
-  StringSchema,
-  TNamespace,
-} from './validators';
+import type { NumberSchema, ObjectSchema, StringSchema, TNamespace } from './validators';
 
 function provider(): TNamespace {
   return schemaProvider().t;
@@ -81,6 +76,28 @@ export const t: TNamespace = {
   ): Schema<InferInput<S[number]>, InferOutput<S[number]>> {
     return provider().union(...members);
   },
+  /**
+   * `t.discriminatedUnion('kind', postBody, pageBody)` — the blessed spelling for a tagged shape.
+   * A failure reports the branch `kind` named, so the caller reads one field error instead of
+   * every branch's reasons concatenated.
+   */
+  discriminatedUnion<S extends readonly [AnySchema, ...AnySchema[]]>(
+    discriminant: string,
+    ...members: S
+  ): Schema<InferInput<S[number]>, InferOutput<S[number]>> {
+    return provider().discriminatedUnion(discriminant, ...members);
+  },
+  /**
+   * `t.refine(range, { name: 'end-after-start', message: 'endDate must be after startDate', … })`
+   * — a cross-field rule declared ON the schema, so OpenAPI, the MCP tool schema and the form
+   * binding all state it instead of it living in a handler where no projection can see it.
+   *
+   * Delegates to the method for the reason `t.nullable` does: `refine` composes an existing
+   * schema rather than building one, so a swapped provider's schemas keep their own behaviour.
+   */
+  refine<In, Out>(schema: Schema<In, Out>, refinement: Refinement<Out>): Schema<In, Out> {
+    return schema.refine(refinement);
+  },
   record<S extends AnySchema>(
     values: S,
   ): Schema<Readonly<Record<string, InferInput<S>>>, Record<string, InferOutput<S>>> {