@ultimat3/schema 31.6.0 → 31.7.0

package/CLAUDE.md

@@ -23,6 +23,11 @@ loop: **a loop that collects issues asks `stopCollecting(count, hasMore)` after
 union that discards member issues restores `issuesStopped()`. `standard.large.test.ts` pins 10k bad
 items → 100 issues, `issuesTruncated`, ≤ 100 item checks (a work count, never wall time). The cap is ambient module state because builtin
 validation is synchronous; `withIssueCap` is re-entrant and only the outermost run reports.
+**A composite reads a builtin member's `Check` directly** (`checkOf` answers it from a `WeakMap`
+keyed by the member's `'~standard'` object, filled in `makeSchema`; only a foreign Standard Schema
+member goes through `validate`), and calls it through `checkAt(check, value, path, key)`: the
+member runs at a shared empty path and its issues are re-rooted only on failure.
+`standard.perf.test.ts` pins both as work counts (0 public validates, 1 path for 10k valid rows).
 `schema-rules.ts` is a leaf (`SCHEMA_RULES`, `issueRuleFacts`), imported by `standard.ts`,
 `errors.ts` (type only) and `builder.ts`. `sensitive.ts` reads `provider.ts` and is not in `t`'s graph.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/schema",
-  "version": "31.6.0",
+  "version": "31.7.0",
   "description": "Ultimate's validation seam: Standard Schema interface, the t namespace, JSON Schema output",
   "keywords": [
     "ultimate",

package/src/array-schema.ts

@@ -4,6 +4,7 @@
 
 import {
   type AnySchema,
+  checkAt,
   checkOf,
   failWith,
   makeSchema,
@@ -83,7 +84,7 @@ export function arraySchema<S extends AnySchema>(
     const issues: StandardIssue[] = [];
     const out: unknown[] = [];
     for (const [index, member] of value.entries()) {
-      const result = itemCheck(member, [...path, index]);
+      const result = checkAt(itemCheck, member, path, index);
       if (result.ok) out.push(result.value);
       else {
         issues.push(...result.issues);

package/src/builder.ts

@@ -253,13 +253,23 @@ function capped<Out>(check: Check<Out>, value: unknown): StandardResult<Out> {
     : cappedFailure(run.value.issues, run.cap, run.stopped);
 }
 
+/**
+ * A builtin schema's check, keyed by its `'~standard'` object — the one part every spread
+ * (`{ ...base, min }`) keeps by reference. A composite reads a builtin member through this, never
+ * through the public `validate`: that door costs a cap closure, a run record, a result and a
+ * re-wrap per member even when the member passes (`standard.perf.test.ts`).
+ */
+const BUILTIN_CHECKS = new WeakMap<object, Check<unknown>>();
+
 export function makeSchema<In, Out>(node: SchemaNode, check: Check<Out>): Schema<In, Out> {
+  const props: Schema<In, Out>['~standard'] = {
+    version: 1,
+    vendor: VENDOR,
+    validate: (value: unknown): StandardResult<Out> => capped(check, value),
+  };
+  BUILTIN_CHECKS.set(props, check as Check<unknown>);
   const schema: Schema<In, Out> = {
-    '~standard': {
-      version: 1,
-      vendor: VENDOR,
-      validate: (value: unknown): StandardResult<Out> => capped(check, value),
-    },
+    '~standard': props,
     node,
     parse(value: unknown, root = 'value'): Out {
       const result = capped(check, value);
@@ -329,8 +339,14 @@ export function makeSchema<In, Out>(node: SchemaNode, check: Check<Out>): Schema
   return schema;
 }
 
-/** Read the check back off a builtin schema so composites can reuse it. */
+/**
+ * Read the check back off a schema so composites can reuse it. A builtin schema answers its own
+ * check, joining the caller's issue cap directly; a foreign Standard Schema member keeps the
+ * public route, its issues re-rooted under the caller's path.
+ */
 export function checkOf<In, Out>(schema: Schema<In, Out>): Check<Out> {
+  const builtin = BUILTIN_CHECKS.get(schema['~standard']);
+  if (builtin !== undefined) return builtin as Check<Out>;
   return (value, path) => {
     const result = schema['~standard'].validate(value);
     if (isThenable(result)) {
@@ -348,3 +364,24 @@ export function checkOf<In, Out>(schema: Schema<In, Out>): Check<Out> {
     );
   };
 }
+
+/** The path a composite hands a member: shared, never written to, so a pass allocates none. */
+const MEMBER_ROOT: Path = Object.freeze([]);
+
+/**
+ * A composite's member at `key` under `path`. The member runs at a shared empty path and its
+ * issues are re-rooted only when it fails, so a passing member costs no path array; order and
+ * count are the member's own, so the issue cap and issue order are untouched.
+ */
+export function checkAt<Out>(
+  check: Check<Out>,
+  value: unknown,
+  path: Path,
+  key: PropertyKey,
+): CheckResult<Out> {
+  const result = check(value, MEMBER_ROOT);
+  if (result.ok) return result;
+  return failWith(
+    result.issues.map((issue) => ({ ...issue, path: [...path, key, ...(issue.path ?? [])] })),
+  );
+}

package/src/record-schema.ts

@@ -4,6 +4,7 @@
 
 import {
   type AnySchema,
+  checkAt,
   checkOf,
   failWith,
   isPlainObject,
@@ -49,14 +50,13 @@ export function recordSchema<S extends AnySchema>(
         // the same segment `arraySchema` already uses, so `formatPath` renders `meta[3]` with no
         // new spelling to learn. It is `Object.entries` order — integer-like keys sort ahead of
         // string ones — so it names an entry that exists rather than a byte offset in the body.
-        const at = [...path, index];
         // A record is stored as `jsonb` far more often than not, and jsonb refuses an unstorable
         // KEY exactly as it does a value — so the key is refused here, by position, not quoted.
         const unfitKey = unstorable(key);
         if (unfitKey !== undefined) {
           issues.push({
             message: `expected a record key, received one ${unfitKey}`,
-            path: at,
+            path: [...path, index],
             rule: 'record.key',
           });
           continue;
@@ -66,12 +66,12 @@ export function recordSchema<S extends AnySchema>(
             // The refused NAMES are a closed set declared right here, so the message may state
             // them: that is the one part of this line the caller did not choose.
             message: expected(`a record key that is not ${PROTOTYPE_KEYS.join(' | ')}`, key),
-            path: at,
+            path: [...path, index],
             rule: 'record.key',
           });
           continue;
         }
-        const result = valueCheck(entry, at);
+        const result = checkAt(valueCheck, entry, path, index);
         if (result.ok) out[key] = result.value;
         else issues.push(...result.issues);
       }

package/src/validators.ts

@@ -7,6 +7,7 @@ import { type ArrayBounds, arraySchema } from './array-schema';
 import {
   type AnySchema,
   type Check,
+  checkAt,
   checkOf,
   failWith,
   isPlainObject,
@@ -224,7 +225,7 @@ export function objectSchema<S extends Shape>(shape: S): ObjectSchema<S> {
       // its `.default()` could never fire, and the HTTP path and this one disagreed about what
       // the caller sent.
       const raw = Object.hasOwn(value, key) ? value[key] : undefined;
-      const result = memberCheck(raw, [...path, key]);
+      const result = checkAt(memberCheck, raw, path, key);
       if (result.ok) {
         // Unknown keys are dropped, never forwarded — no mass assignment through an action.
         if (result.value !== undefined) out[key] = result.value;