@ultimat3/schema 1.2.0 → 2.0.0

package/src/validators.ts

@@ -6,30 +6,27 @@ import {
   type AnySchema,
   type Check,
   checkOf,
-  expected,
   fail,
   failWith,
+  isPlainObject,
   makeSchema,
   pass,
+  type Refinement,
   type Schema,
   type Shape,
   type ShapeInput,
   type ShapeOutput,
 } from './builder';
+import { expected } from './describe-value';
+import { discriminatedUnionSchema } from './discriminated-union';
+import { type MoneyValue, moneySchema } from './money-value';
 import type { SchemaNode } from './node';
 import type { InferInput, InferOutput, StandardIssue } from './standard';
 
-/** Structurally identical to `Money` in `@ultimat3/money`. Never a float. */
-export interface MoneyValue {
-  readonly minor: number;
-  readonly currency: string;
-}
-
 const EMAIL_RE = /^[^\s@]+@[^\s@.]+(\.[^\s@.]+)+$/;
 const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const CURSOR_RE = /^[A-Za-z0-9_-]+$/;
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-const CURRENCY_RE = /^[A-Z]{3}$/;
 
 export interface StringSchema extends Schema<string, string> {
   min(length: number): StringSchema;
@@ -52,17 +49,60 @@ export interface ObjectSchema<S extends Shape> extends Schema<ShapeInput<S>, Sha
 
 type Simplified<S> = { [K in keyof S]: S[K] } & {};
 
+/**
+ * The literal the caller wrote, flags included. An error quoting `/^[a-z]+$/` for a pattern
+ * carrying `i` names something that would have matched the value it just refused.
+ */
+function describePattern(node: SchemaNode): string {
+  return node.patternFlags === undefined || node.patternFlags === ''
+    ? String(node.pattern)
+    : `/${node.pattern}/${node.patternFlags}`;
+}
+
+/**
+ * Characters, not UTF-16 code units — the unit `json-schema.ts` already promises, since JSON
+ * Schema defines `minLength`/`maxLength` over code points and the message here has always said
+ * "chars". `'👍'.length` is 2, so `t.string.max(1)` refused a value the published schema, a human
+ * and Postgres' `char_length` all count as one.
+ *
+ * Only a surrogate makes the two counts differ, so the string is walked only when one is present
+ * — every ASCII value keeps the O(1) read this replaced.
+ */
+const HAS_SURROGATE = /[\uD800-\uDBFF]/;
+
+function charCount(value: string): number {
+  return HAS_SURROGATE.test(value) ? [...value].length : value.length;
+}
+
+/**
+ * Compiled once per schema, not once per validation. `lastIndex` is reset because a `g` or `y`
+ * pattern carries it between calls — a cached global RegExp answers `false` for the second
+ * `.test()` of the very value it just accepted, which the per-call construction hid.
+ */
+function patternTester(node: SchemaNode): ((value: string) => boolean) | undefined {
+  if (node.pattern === undefined) return undefined;
+  const source = node.pattern;
+  const flags = node.patternFlags;
+  let compiled: RegExp | undefined;
+  return (value) => {
+    compiled ??= new RegExp(source, flags);
+    compiled.lastIndex = 0;
+    return compiled.test(value);
+  };
+}
+
 function stringLike(node: SchemaNode, what: string, test?: (value: string) => boolean) {
+  const matchesPattern = patternTester(node);
   const check: Check<string> = (value, path) => {
     if (typeof value !== 'string') return fail(path, expected(what, value));
-    if (node.minLength !== undefined && value.length < node.minLength) {
+    if (node.minLength !== undefined && charCount(value) < node.minLength) {
       return fail(path, expected(`${what} of at least ${node.minLength} chars`, value));
     }
-    if (node.maxLength !== undefined && value.length > node.maxLength) {
+    if (node.maxLength !== undefined && charCount(value) > node.maxLength) {
       return fail(path, expected(`${what} of at most ${node.maxLength} chars`, value));
     }
-    if (node.pattern !== undefined && !new RegExp(node.pattern).test(value)) {
-      return fail(path, expected(`${what} matching ${node.pattern}`, value));
+    if (matchesPattern !== undefined && !matchesPattern(value)) {
+      return fail(path, expected(`${what} matching ${describePattern(node)}`, value));
     }
     if (test !== undefined && !test(value)) return fail(path, expected(what, value));
     return pass(value);
@@ -80,7 +120,18 @@ function makeStringSchema(
     ...base,
     min: (length) => makeStringSchema({ ...node, minLength: length }, what, test),
     max: (length) => makeStringSchema({ ...node, maxLength: length }, what, test),
-    pattern: (regex) => makeStringSchema({ ...node, pattern: regex.source }, what, test),
+    pattern: (regex) =>
+      makeStringSchema(
+        // Flags travel with the source: a node holding only `source` rebuilt a *different*
+        // RegExp, so `/^[a-z]+$/i` refused `ABC` and quoted the pattern that matches it.
+        {
+          ...node,
+          pattern: regex.source,
+          ...(regex.flags === '' ? {} : { patternFlags: regex.flags }),
+        },
+        what,
+        test,
+      ),
   };
 }
 
@@ -109,10 +160,6 @@ function makeNumberSchema(node: SchemaNode): NumberSchema {
   };
 }
 
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 export function objectSchema<S extends Shape>(shape: S): ObjectSchema<S> {
   const properties: Record<string, SchemaNode> = {};
   const checks: [string, Check<unknown>][] = [];
@@ -214,6 +261,15 @@ export function unionSchema<S extends readonly [AnySchema, ...AnySchema[]]>(
   });
 }
 
+/**
+ * Keys that reach an object's prototype rather than its own properties. A record's keys are the
+ * caller's, so `{"__proto__":{…}}` on a `{}` literal set the OUTPUT's prototype: `Object.keys`
+ * answered `[]` while `settings[k] ?? fallback` handed a handler the attacker's value for a key
+ * that was never sent. Refused by name AND built on a null prototype — the null prototype alone
+ * would keep `__proto__` as a silent own key nobody declared.
+ */
+const PROTOTYPE_KEYS: ReadonlySet<string> = new Set(['__proto__', 'constructor', 'prototype']);
+
 export function recordSchema<S extends AnySchema>(
   values: S,
 ): Schema<Readonly<Record<string, InferInput<S>>>, Record<string, InferOutput<S>>> {
@@ -224,8 +280,15 @@ export function recordSchema<S extends AnySchema>(
     (value, path) => {
       if (!isPlainObject(value)) return fail(path, expected('an object', value));
       const issues: StandardIssue[] = [];
-      const out: Record<string, unknown> = {};
+      const out: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
       for (const [key, entry] of Object.entries(value)) {
+        if (PROTOTYPE_KEYS.has(key)) {
+          issues.push({
+            message: expected(`a record key that is not ${[...PROTOTYPE_KEYS].join(' | ')}`, key),
+            path: [...path, key],
+          });
+          continue;
+        }
         const result = valueCheck(entry, [...path, key]);
         if (result.ok) out[key] = result.value;
         else issues.push(...result.issues);
@@ -248,6 +311,18 @@ export function optionalSchema<S extends AnySchema>(
   return schema.optional() as Schema<InferInput<S> | undefined, InferOutput<S> | undefined>;
 }
 
+/**
+ * The free-function spelling of `schema.refine(...)`, shipped beside `t.refine` for the same
+ * reason `nullableSchema` ships beside `t.nullable`: a call site that already holds a schema
+ * should not have to reach for the namespace.
+ */
+export function refineSchema<In, Out>(
+  schema: Schema<In, Out>,
+  refinement: Refinement<Out>,
+): Schema<In, Out> {
+  return schema.refine(refinement);
+}
+
 function isTimeZone(value: string): boolean {
   try {
     new Intl.DateTimeFormat('en', { timeZone: value });
@@ -283,37 +358,6 @@ const dateSchema: Schema<Date | string | number, Date> = makeSchema<Date | strin
   },
 );
 
-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 },
-      currency: { kind: 'string', pattern: CURRENCY_RE.source },
-    },
-  },
-  (value, path) => {
-    if (!isPlainObject(value)) return fail(path, expected('a Money object', value));
-    const minor = value['minor'];
-    const currency = value['currency'];
-    const issues: StandardIssue[] = [];
-    if (typeof minor !== 'number' || !Number.isInteger(minor)) {
-      issues.push({
-        message: expected('an integer number of minor units', minor),
-        path: [...path, 'minor'],
-      });
-    }
-    if (typeof currency !== 'string' || !CURRENCY_RE.test(currency)) {
-      issues.push({
-        message: expected('a 3-letter ISO 4217 code', currency),
-        path: [...path, 'currency'],
-      });
-    }
-    if (issues.length > 0) return failWith(issues);
-    return pass({ minor: minor as number, currency: currency as string });
-  },
-);
-
 /** The shape a schema provider must implement to back `t`. */
 export interface TNamespace {
   readonly string: StringSchema;
@@ -339,6 +383,13 @@ export interface TNamespace {
   union<S extends readonly [AnySchema, ...AnySchema[]]>(
     ...members: S
   ): Schema<InferInput<S[number]>, InferOutput<S[number]>>;
+  /** A union routed by one literal key: one branch's issues on failure, not every branch's. */
+  discriminatedUnion<S extends readonly [AnySchema, ...AnySchema[]]>(
+    discriminant: string,
+    ...members: S
+  ): Schema<InferInput<S[number]>, InferOutput<S[number]>>;
+  /** A rule the IR cannot state structurally — cross-field, cross-row, or arithmetic. */
+  refine<In, Out>(schema: Schema<In, Out>, refinement: Refinement<Out>): Schema<In, Out>;
   record<S extends AnySchema>(
     values: S,
   ): Schema<Readonly<Record<string, InferInput<S>>>, Record<string, InferOutput<S>>>;
@@ -383,6 +434,8 @@ export const builtinT: TNamespace = Object.freeze({
   enumerated: <const V extends readonly [string, ...string[]]>(...values: V) => enumSchema(values),
   literal: literalSchema,
   union: unionSchema,
+  discriminatedUnion: discriminatedUnionSchema,
+  refine: refineSchema,
   record: recordSchema,
   nullable: nullableSchema,
   optional: optionalSchema,