@ultimat3/schema 1.0.0

package/src/coerce.ts

@@ -0,0 +1,125 @@
+// Single responsibility: HTTP-boundary coercion. Kept out of validation on purpose — only the
+// HTTP layer has strings that "mean" numbers. Actions, jobs and MCP calls receive real JSON and
+// must never get this leniency.
+
+import type { SchemaNode } from './node';
+import { tryIntrospect } from './provider';
+
+const TRUE_VALUES = new Set(['1', 'true', 'yes', 'on']);
+const FALSE_VALUES = new Set(['0', 'false', 'no', 'off', '']);
+
+export type QuerySource =
+  | URLSearchParams
+  | Readonly<Record<string, string | readonly string[] | undefined>>;
+
+/**
+ * Coerce one raw value toward `node`. Never throws and never invents data: anything it cannot
+ * confidently convert is returned untouched so validation produces the real error message.
+ */
+export function coerceNode(node: SchemaNode, raw: unknown): unknown {
+  if (raw === undefined || raw === null) return raw;
+
+  switch (node.kind) {
+    case 'number': {
+      if (typeof raw !== 'string') return raw;
+      const value = Number(raw);
+      return raw.trim() !== '' && Number.isFinite(value) ? value : raw;
+    }
+    case 'boolean': {
+      if (typeof raw !== 'string') return raw;
+      const lowered = raw.toLowerCase();
+      if (TRUE_VALUES.has(lowered)) return true;
+      if (FALSE_VALUES.has(lowered)) return false;
+      return raw;
+    }
+    case 'date': {
+      if (typeof raw !== 'string') return raw;
+      const parsed = new Date(raw);
+      return Number.isNaN(parsed.getTime()) ? raw : parsed;
+    }
+    case 'array': {
+      const items: unknown[] = Array.isArray(raw) ? raw : [raw];
+      const itemNode = node.items;
+      return itemNode === undefined ? items : items.map((item) => coerceNode(itemNode, item));
+    }
+    case 'record': {
+      if (typeof raw !== 'object' || node.valueNode === undefined) return raw;
+      const out: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+        out[key] = coerceNode(node.valueNode, value);
+      }
+      return out;
+    }
+    case 'object': {
+      if (typeof raw !== 'object' || node.properties === undefined) return raw;
+      const source = raw as Record<string, unknown>;
+      const out: Record<string, unknown> = { ...source };
+      for (const [key, child] of Object.entries(node.properties)) {
+        if (key in source) out[key] = coerceNode(child, source[key]);
+      }
+      return out;
+    }
+    case 'money': {
+      if (typeof raw !== 'object') return raw;
+      const source = raw as Record<string, unknown>;
+      const minor = typeof source['minor'] === 'string' ? Number(source['minor']) : source['minor'];
+      return Number.isFinite(minor) ? { ...source, minor } : raw;
+    }
+    case 'union': {
+      // Only unambiguous single-kind unions (e.g. `number | undefined`) are safe to coerce.
+      const kinds = new Set((node.anyOf ?? []).map((member) => member.kind));
+      if (kinds.size !== 1) return raw;
+      const [member] = node.anyOf ?? [];
+      return member === undefined ? raw : coerceNode(member, raw);
+    }
+    default:
+      return raw;
+  }
+}
+
+function toRecord(source: QuerySource): Record<string, string | readonly string[] | undefined> {
+  if (!(source instanceof URLSearchParams)) {
+    return { ...source };
+  }
+  const out: Record<string, string | readonly string[]> = {};
+  for (const key of new Set(source.keys())) {
+    const all = source.getAll(key);
+    out[key] = all.length > 1 ? all : (all[0] as string);
+  }
+  return out;
+}
+
+/**
+ * Coerce a query string / route params object against a schema, ready to `parse()`.
+ * Unknown keys are passed through — the schema decides what to keep.
+ */
+export function coerceQuery(schema: unknown, source: QuerySource): Record<string, unknown> {
+  const record = toRecord(source);
+  const node = tryIntrospect(schema);
+  if (node?.properties === undefined) return record;
+
+  const out: Record<string, unknown> = { ...record };
+  for (const [key, child] of Object.entries(node.properties)) {
+    if (!(key in record)) continue;
+    const raw = record[key];
+    out[key] = coerceNode(child, child.kind === 'array' ? (raw ?? []) : normaliseSingle(raw));
+  }
+  return out;
+}
+
+function normaliseSingle(raw: string | readonly string[] | undefined): unknown {
+  return Array.isArray(raw) ? raw[raw.length - 1] : raw;
+}
+
+/** Coerce an arbitrary record (route params, form data) against a schema. */
+export function coerceInput(
+  schema: unknown,
+  raw: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+  const node = tryIntrospect(schema);
+  if (node === undefined) return { ...raw };
+  const coerced = coerceNode(node, raw);
+  return typeof coerced === 'object' && coerced !== null
+    ? (coerced as Record<string, unknown>)
+    : { ...raw };
+}

package/src/errors.d.ts

@@ -0,0 +1,62 @@
+/** Same well-known symbol `@ultimat3/core` brands with. Keep in sync, never rename. */
+export declare const ULTIMATE_ERROR_BRAND: unique symbol;
+export interface SchemaErrorCodeDeclaration {
+    readonly title: string;
+    readonly docs?: string | undefined;
+}
+/**
+ * Pass to `registerErrorCodes()` from a package that may import both tiers (the CLI does this
+ * at boot) so the terminal and the dev overlay render these codes identically.
+ */
+export declare const SCHEMA_ERROR_CODES: Readonly<Record<string, SchemaErrorCodeDeclaration>>;
+export interface SchemaErrorInit {
+    readonly code: string;
+    readonly cause: string;
+    readonly fix: string;
+    readonly docs?: string | undefined;
+    readonly meta?: Readonly<Record<string, unknown>> | undefined;
+}
+export interface SchemaErrorJSON {
+    readonly code: string;
+    readonly title: string;
+    readonly cause: string;
+    readonly fix: string;
+    readonly docs: string;
+    readonly meta?: Readonly<Record<string, unknown>> | undefined;
+}
+export declare class SchemaError extends Error {
+    readonly [ULTIMATE_ERROR_BRAND] = true;
+    readonly name: string;
+    readonly code: string;
+    readonly title: string;
+    readonly cause: string;
+    readonly fix: string;
+    readonly docs: string;
+    readonly meta: Readonly<Record<string, unknown>> | undefined;
+    constructor(init: SchemaErrorInit);
+    /** The same 3-line rendering as `UltimateError.format()`. */
+    format(): string;
+    toJSON(): SchemaErrorJSON;
+}
+export interface ValidationIssue {
+    /** Dotted path from the validated root, e.g. `input.items[0].price`. */
+    readonly path: string;
+    readonly expected: string;
+    readonly received: string;
+    readonly message: string;
+}
+export declare class ValidationFailedError extends SchemaError {
+    static readonly code = "X_VALIDATION_FAILED";
+    readonly name = "ValidationFailedError";
+    readonly issues: readonly ValidationIssue[];
+    constructor(issues: readonly ValidationIssue[], root?: string);
+    /** One line per issue — what the dev overlay and `x test --json` render. */
+    formatIssues(): string;
+}
+export declare class SchemaUnsupportedError extends SchemaError {
+    static readonly code = "X_SCHEMA_UNSUPPORTED";
+    readonly name = "SchemaUnsupportedError";
+    constructor(init: Omit<SchemaErrorInit, 'code'>);
+}
+export declare function isSchemaError(value: unknown): value is SchemaError;
+//# sourceMappingURL=errors.d.ts.map

package/src/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["errors.ts"],"names":[],"mappings":"AAIA,uFAAuF;AACvF,eAAO,MAAM,oBAAoB,EAAE,OAAO,MAAqC,CAAC;AAEhF,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAIhF,CAAC;AAYL,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;CAC/D;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;CAC/D;AAED,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,CAAC,oBAAoB,CAAC,QAAQ;IACvC,SAAkB,IAAI,EAAE,MAAM,CAAiB;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,SAAiB,KAAK,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAE7D,YAAY,IAAI,EAAE,eAAe,EAQhC;IAED,6DAA6D;IAC7D,MAAM,IAAI,MAAM,CAIf;IAED,MAAM,IAAI,eAAe,CASxB;CACF;AAED,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,qBAAsB,SAAQ,WAAW;IACpD,MAAM,CAAC,QAAQ,CAAC,IAAI,yBAAyB;IAC7C,SAAkB,IAAI,2BAA2B;IACjD,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;IAE5C,YAAY,MAAM,EAAE,SAAS,eAAe,EAAE,EAAE,IAAI,SAAU,EAW7D;IAED,4EAA4E;IAC5E,YAAY,IAAI,MAAM,CAErB;CACF;AAED,qBAAa,sBAAuB,SAAQ,WAAW;IACrD,MAAM,CAAC,QAAQ,CAAC,IAAI,0BAA0B;IAC9C,SAAkB,IAAI,4BAA4B;IAClD,YAAY,IAAI,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,EAE9C;CACF;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE"}

package/src/errors.js

@@ -0,0 +1,85 @@
+// Single responsibility: this package's error codes. `@ultimat3/schema` is tier 0 and may not
+// import `@ultimat3/core`, so `SchemaError` reproduces the `UltimateError` shape structurally
+// and carries the same `Symbol.for('ultimate.error')` brand — `isUltimateError()` still matches.
+/** Same well-known symbol `@ultimat3/core` brands with. Keep in sync, never rename. */
+export const ULTIMATE_ERROR_BRAND = Symbol.for('ultimate.error');
+/**
+ * Pass to `registerErrorCodes()` from a package that may import both tiers (the CLI does this
+ * at boot) so the terminal and the dev overlay render these codes identically.
+ */
+export const SCHEMA_ERROR_CODES = Object.freeze({
+    X_VALIDATION_FAILED: { title: 'value did not match its schema' },
+    X_SCHEMA_UNSUPPORTED: { title: 'the active schema provider cannot do this' },
+});
+const TITLES = Object.freeze({
+    X_VALIDATION_FAILED: 'value did not match its schema',
+    X_SCHEMA_UNSUPPORTED: 'the active schema provider cannot do this',
+});
+/** `X_SCHEMA_UNSUPPORTED` -> `schema unsupported`, same fallback as the core registry. */
+function humanize(code) {
+    return code.replace(/^X_/, '').toLowerCase().replaceAll('_', ' ');
+}
+export class SchemaError extends Error {
+    [ULTIMATE_ERROR_BRAND] = true;
+    name = 'SchemaError';
+    code;
+    title;
+    fix;
+    docs;
+    meta;
+    constructor(init) {
+        const title = TITLES[init.code] ?? humanize(init.code);
+        super(`${init.code}: ${title}`, { cause: init.cause });
+        this.code = init.code;
+        this.title = title;
+        this.fix = init.fix;
+        this.docs = init.docs ?? `https://ultimate.dev/errors/${init.code}`;
+        this.meta = init.meta;
+    }
+    /** The same 3-line rendering as `UltimateError.format()`. */
+    format() {
+        return [`${this.code}: ${this.title}`, `  cause: ${this.cause}`, `  fix:   ${this.fix}`].join('\n');
+    }
+    toJSON() {
+        return {
+            code: this.code,
+            title: this.title,
+            cause: this.cause,
+            fix: this.fix,
+            docs: this.docs,
+            meta: this.meta,
+        };
+    }
+}
+export class ValidationFailedError extends SchemaError {
+    static code = 'X_VALIDATION_FAILED';
+    name = 'ValidationFailedError';
+    issues;
+    constructor(issues, root = 'value') {
+        const cause = issues
+            .map((issue) => `${issue.path === '' ? root : issue.path}: ${issue.message}`)
+            .join('; ');
+        super({
+            code: ValidationFailedError.code,
+            cause,
+            fix: `send ${root} with the field(s) named in cause corrected to the expected type`,
+            meta: { issues },
+        });
+        this.issues = issues;
+    }
+    /** One line per issue — what the dev overlay and `x test --json` render. */
+    formatIssues() {
+        return this.issues.map((issue) => `  ${issue.path}: ${issue.message}`).join('\n');
+    }
+}
+export class SchemaUnsupportedError extends SchemaError {
+    static code = 'X_SCHEMA_UNSUPPORTED';
+    name = 'SchemaUnsupportedError';
+    constructor(init) {
+        super({ ...init, code: SchemaUnsupportedError.code });
+    }
+}
+export function isSchemaError(value) {
+    return typeof value === 'object' && value !== null && ULTIMATE_ERROR_BRAND in value;
+}
+//# sourceMappingURL=errors.js.map

package/src/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["errors.ts"],"names":[],"mappings":"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"}

package/src/errors.ts

@@ -0,0 +1,140 @@
+// Single responsibility: this package's error codes. `@ultimat3/schema` is tier 0 and may not
+// import `@ultimat3/core`, so `SchemaError` reproduces the `UltimateError` shape structurally
+// and carries the same `Symbol.for('ultimate.error')` brand — `isUltimateError()` still matches.
+
+import { formatIssues } from './standard';
+
+/** Same well-known symbol `@ultimat3/core` brands with. Keep in sync, never rename. */
+export const ULTIMATE_ERROR_BRAND: unique symbol = Symbol.for('ultimate.error');
+
+export interface SchemaErrorCodeDeclaration {
+  readonly title: string;
+  readonly docs?: string | undefined;
+}
+
+/**
+ * Pass to `registerErrorCodes()` from a package that may import both tiers (the CLI does this
+ * at boot) so the terminal and the dev overlay render these codes identically.
+ */
+export const SCHEMA_ERROR_CODES: Readonly<Record<string, SchemaErrorCodeDeclaration>> =
+  Object.freeze({
+    X_VALIDATION_FAILED: { title: 'value did not match its schema' },
+    X_SCHEMA_UNSUPPORTED: { title: 'the active schema provider cannot do this' },
+  });
+
+/**
+ * Derived, never re-typed: the declarations above are the single source, so a title edited there
+ * cannot fall out of step with what `SchemaError` renders locally.
+ */
+const TITLES: Readonly<Record<string, string>> = Object.freeze(
+  Object.fromEntries(
+    Object.entries(SCHEMA_ERROR_CODES).map(([code, declaration]) => [code, declaration.title]),
+  ),
+);
+
+/** `X_SCHEMA_UNSUPPORTED` -> `schema unsupported`, same fallback as the core registry. */
+function humanize(code: string): string {
+  return code.replace(/^X_/, '').toLowerCase().replaceAll('_', ' ');
+}
+
+export interface SchemaErrorInit {
+  readonly code: string;
+  readonly cause: string;
+  readonly fix: string;
+  readonly docs?: string | undefined;
+  readonly meta?: Readonly<Record<string, unknown>> | undefined;
+}
+
+export interface SchemaErrorJSON {
+  readonly code: string;
+  readonly title: string;
+  readonly cause: string;
+  readonly fix: string;
+  readonly docs: string;
+  readonly meta?: Readonly<Record<string, unknown>> | undefined;
+}
+
+export class SchemaError extends Error {
+  readonly [ULTIMATE_ERROR_BRAND] = true;
+  override readonly name: string = 'SchemaError';
+  readonly code: string;
+  readonly title: string;
+  declare readonly cause: string;
+  readonly fix: string;
+  readonly docs: string;
+  readonly meta: Readonly<Record<string, unknown>> | undefined;
+
+  constructor(init: SchemaErrorInit) {
+    const title = TITLES[init.code] ?? humanize(init.code);
+    super(`${init.code}: ${title}`, { cause: init.cause });
+    this.code = init.code;
+    this.title = title;
+    this.fix = init.fix;
+    this.docs = init.docs ?? `https://ultimate.dev/errors/${init.code}`;
+    this.meta = init.meta;
+  }
+
+  /** The same 3-line rendering as `UltimateError.format()`. */
+  format(): string {
+    return [`${this.code}: ${this.title}`, `  cause: ${this.cause}`, `  fix:   ${this.fix}`].join(
+      '\n',
+    );
+  }
+
+  toJSON(): SchemaErrorJSON {
+    return {
+      code: this.code,
+      title: this.title,
+      cause: this.cause,
+      fix: this.fix,
+      docs: this.docs,
+      meta: this.meta,
+    };
+  }
+}
+
+export interface ValidationIssue {
+  /** Dotted path from the validated root, e.g. `input.items[0].price`. */
+  readonly path: string;
+  readonly expected: string;
+  readonly received: string;
+  readonly message: string;
+}
+
+export class ValidationFailedError extends SchemaError {
+  static readonly code = 'X_VALIDATION_FAILED';
+  override readonly name = 'ValidationFailedError';
+  readonly issues: readonly ValidationIssue[];
+
+  constructor(issues: readonly ValidationIssue[], root = 'value') {
+    const cause = issues
+      .map((issue) => `${issue.path === '' ? root : issue.path}: ${issue.message}`)
+      .join('; ');
+    super({
+      code: ValidationFailedError.code,
+      cause,
+      fix: `send ${root} with the field(s) named in cause corrected to the expected type`,
+      meta: { issues },
+    });
+    this.issues = issues;
+  }
+
+  /** One line per issue — what the dev overlay and `x test --json` render. */
+  formatIssues(): string {
+    return formatIssues(this.issues)
+      .map((line) => `  ${line}`)
+      .join('\n');
+  }
+}
+
+export class SchemaUnsupportedError extends SchemaError {
+  static readonly code = 'X_SCHEMA_UNSUPPORTED';
+  override readonly name = 'SchemaUnsupportedError';
+  constructor(init: Omit<SchemaErrorInit, 'code'>) {
+    super({ ...init, code: SchemaUnsupportedError.code });
+  }
+}
+
+export function isSchemaError(value: unknown): value is SchemaError {
+  return typeof value === 'object' && value !== null && ULTIMATE_ERROR_BRAND in value;
+}

package/src/index.d.ts

@@ -0,0 +1,19 @@
+export type { AnySchema, Check, CheckErr, CheckOk, CheckResult, Path, Schema, Shape, ShapeInput, ShapeOutput, Simplify, } from './builder';
+export { checkOf, describeValue, expected, fail, failWith, makeSchema, pass, VENDOR, } from './builder';
+export type { QuerySource } from './coerce';
+export { coerceInput, coerceNode, coerceQuery } from './coerce';
+export type { SchemaErrorCodeDeclaration, SchemaErrorInit, SchemaErrorJSON, ValidationIssue, } from './errors';
+export { isSchemaError, SCHEMA_ERROR_CODES, SchemaError, SchemaUnsupportedError, ULTIMATE_ERROR_BRAND, ValidationFailedError, } from './errors';
+export type { JsonSchema, JsonSchemaDialect, JsonSchemaType, ToJsonSchemaOptions, } from './json-schema';
+export { nodeToJsonSchema, toJsonSchema, toMcpInputSchema } from './json-schema';
+export type { SchemaFormat, SchemaKind, SchemaNode } from './node';
+export { isSchemaNode, nodeOf, requiredKeys } from './node';
+export type { SchemaProvider } from './provider';
+export { builtinProvider, configureSchemaProvider, introspect, resetSchemaProvider, schemaProvider, tryIntrospect, } from './provider';
+export type { InferInput, InferOutput, StandardFailureResult, StandardIssue, StandardPathSegment, StandardResult, StandardSchemaProps, StandardSchemaV1, StandardSuccessResult, StandardTypes, } from './standard';
+export { formatPath, isStandardSchema, parse, parseAsync, toValidationIssues, validate, validateAsync, } from './standard';
+export type { Infer } from './t';
+export { t } from './t';
+export type { MoneyValue, NumberSchema, ObjectSchema, StringSchema, TNamespace, } from './validators';
+export { arraySchema, builtinT, enumSchema, literalSchema, objectSchema, optionalSchema, recordSchema, unionSchema, } from './validators';
+//# sourceMappingURL=index.d.ts.map

package/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAEA,YAAY,EACV,SAAS,EACT,KAAK,EACL,QAAQ,EACR,OAAO,EACP,WAAW,EACX,IAAI,EACJ,MAAM,EACN,KAAK,EACL,UAAU,EACV,WAAW,EACX,QAAQ,GACT,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,OAAO,EACP,aAAa,EACb,QAAQ,EACR,IAAI,EACJ,QAAQ,EACR,UAAU,EACV,IAAI,EACJ,MAAM,GACP,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAChE,YAAY,EACV,0BAA0B,EAC1B,eAAe,EACf,eAAe,EACf,eAAe,GAChB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,WAAW,EACX,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,mBAAmB,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjF,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAC5D,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,UAAU,EACV,mBAAmB,EACnB,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,UAAU,EACV,WAAW,EACX,qBAAqB,EACrB,aAAa,EACb,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,EACrB,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,KAAK,EACL,UAAU,EACV,kBAAkB,EAClB,QAAQ,EACR,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,KAAK,EAAE,MAAM,KAAK,CAAC;AACjC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,YAAY,EACV,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,WAAW,EACX,QAAQ,EACR,UAAU,EACV,aAAa,EACb,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,WAAW,GACZ,MAAM,cAAc,CAAC"}

package/src/index.js

@@ -0,0 +1,11 @@
+// Single responsibility: the public API of @ultimat3/schema. Explicit named exports only.
+export { checkOf, describeValue, expected, fail, failWith, makeSchema, pass, VENDOR, } from './builder';
+export { coerceInput, coerceNode, coerceQuery } from './coerce';
+export { isSchemaError, SCHEMA_ERROR_CODES, SchemaError, SchemaUnsupportedError, ULTIMATE_ERROR_BRAND, ValidationFailedError, } from './errors';
+export { nodeToJsonSchema, toJsonSchema, toMcpInputSchema } from './json-schema';
+export { isSchemaNode, nodeOf, requiredKeys } from './node';
+export { builtinProvider, configureSchemaProvider, introspect, resetSchemaProvider, schemaProvider, tryIntrospect, } from './provider';
+export { formatPath, isStandardSchema, parse, parseAsync, toValidationIssues, validate, validateAsync, } from './standard';
+export { t } from './t';
+export { arraySchema, builtinT, enumSchema, literalSchema, objectSchema, optionalSchema, recordSchema, unionSchema, } from './validators';
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAe1F,OAAO,EACL,OAAO,EACP,aAAa,EACb,QAAQ,EACR,IAAI,EACJ,QAAQ,EACR,UAAU,EACV,IAAI,EACJ,MAAM,GACP,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAOhE,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,WAAW,EACX,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,UAAU,CAAC;AAOlB,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjF,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAE5D,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,UAAU,EACV,mBAAmB,EACnB,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC;AAapB,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,KAAK,EACL,UAAU,EACV,kBAAkB,EAClB,QAAQ,EACR,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB,OAAO,EACL,WAAW,EACX,QAAQ,EACR,UAAU,EACV,aAAa,EACb,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,WAAW,GACZ,MAAM,cAAc,CAAC"}

package/src/index.ts

@@ -0,0 +1,102 @@
+// Single responsibility: the public API of @ultimat3/schema. Explicit named exports only.
+
+export type {
+  AnySchema,
+  Check,
+  CheckErr,
+  CheckOk,
+  CheckResult,
+  Path,
+  Schema,
+  Shape,
+  ShapeInput,
+  ShapeOutput,
+  Simplify,
+} from './builder';
+export {
+  checkOf,
+  describeValue,
+  expected,
+  fail,
+  failWith,
+  makeSchema,
+  pass,
+  VENDOR,
+} from './builder';
+export type { QuerySource } from './coerce';
+export { coerceInput, coerceNode, coerceQuery } from './coerce';
+export type {
+  SchemaErrorCodeDeclaration,
+  SchemaErrorInit,
+  SchemaErrorJSON,
+  ValidationIssue,
+} from './errors';
+export {
+  isSchemaError,
+  SCHEMA_ERROR_CODES,
+  SchemaError,
+  SchemaUnsupportedError,
+  ULTIMATE_ERROR_BRAND,
+  ValidationFailedError,
+} from './errors';
+export type {
+  JsonSchema,
+  JsonSchemaDialect,
+  JsonSchemaType,
+  ToJsonSchemaOptions,
+} from './json-schema';
+export { nodeToJsonSchema, toJsonSchema, toMcpInputSchema } from './json-schema';
+export type { SchemaFormat, SchemaKind, SchemaNode } from './node';
+export { isSchemaNode, nodeOf, requiredKeys } from './node';
+export type { SchemaProvider } from './provider';
+export {
+  builtinProvider,
+  configureSchemaProvider,
+  introspect,
+  resetSchemaProvider,
+  schemaProvider,
+  tryIntrospect,
+} from './provider';
+export type {
+  FormattableIssue,
+  InferInput,
+  InferOutput,
+  StandardFailureResult,
+  StandardIssue,
+  StandardPathSegment,
+  StandardResult,
+  StandardSchemaProps,
+  StandardSchemaV1,
+  StandardSuccessResult,
+  StandardTypes,
+} from './standard';
+export {
+  formatIssues,
+  formatPath,
+  isStandardSchema,
+  parse,
+  parseAsync,
+  toValidationIssues,
+  validate,
+  validateAsync,
+} from './standard';
+export type { Infer } from './t';
+export { t } from './t';
+export type {
+  MoneyValue,
+  NumberSchema,
+  ObjectSchema,
+  StringSchema,
+  TNamespace,
+} from './validators';
+export {
+  arraySchema,
+  builtinT,
+  enumSchema,
+  literalSchema,
+  nullableSchema,
+  objectSchema,
+  optionalSchema,
+  recordSchema,
+  unionSchema,
+} from './validators';

package/src/json-schema.d.ts

@@ -0,0 +1,37 @@
+import { type SchemaNode } from './node';
+export type JsonSchemaType = 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array';
+export interface JsonSchema {
+    readonly $schema?: string;
+    readonly type?: JsonSchemaType;
+    readonly format?: string;
+    readonly description?: string;
+    readonly default?: unknown;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly pattern?: string;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly enum?: readonly (string | number)[];
+    readonly const?: string | number | boolean | null;
+    readonly properties?: Readonly<Record<string, JsonSchema>>;
+    readonly required?: readonly string[];
+    readonly additionalProperties?: boolean | JsonSchema;
+    readonly items?: JsonSchema;
+    readonly anyOf?: readonly JsonSchema[];
+    readonly title?: string;
+}
+export type JsonSchemaDialect = '2020-12' | 'draft-07';
+export interface ToJsonSchemaOptions {
+    /** MCP clients are happiest with `draft-07`; OpenAPI 3.1 wants `2020-12` (the default). */
+    readonly dialect?: JsonSchemaDialect | undefined;
+    /** Emit `$schema` at the root. Off for OpenAPI component schemas. */
+    readonly includeDialect?: boolean | undefined;
+    readonly title?: string | undefined;
+}
+/** Convert any schema the active provider can introspect. */
+export declare function toJsonSchema(schema: unknown, options?: ToJsonSchemaOptions): JsonSchema;
+/** The exact shape an MCP `tools/list` entry needs: draft-07, no `$schema`. */
+export declare function toMcpInputSchema(schema: unknown): JsonSchema;
+/** Convert an already-introspected node — used by generators that walk the IR themselves. */
+export declare function nodeToJsonSchema(node: SchemaNode): JsonSchema;
+//# sourceMappingURL=json-schema.d.ts.map

package/src/json-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.d.ts","sourceRoot":"","sources":["json-schema.ts"],"names":[],"mappings":"AAIA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAC;AAGvD,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE9F,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAC7C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IAClD,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IAC3D,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IACrD,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,UAAU,CAAC;AAOvD,MAAM,WAAW,mBAAmB;IAClC,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACjD,qEAAqE;IACrE,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC;AAsFD,6DAA6D;AAC7D,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,UAAU,CAQvF;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,GAAG,UAAU,CAE5D;AAED,6FAA6F;AAC7F,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAE7D"}