feat(standard schema): support standard schema as patterns

Author: gvergnaud

package-lock.json

@@ -78,6 +78,7 @@
     "prettier": "^2.8.8",
     "rimraf": "^5.0.1",
     "ts-jest": "^29.4.1",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.2",
+    "zod": "^3.25.76"
   }
 }

package.json

@@ -7,6 +7,12 @@
 import * as symbols from './symbols';
 import { SelectionType } from '../types/FindSelected';
 import { Pattern, Matcher, MatcherType, AnyMatcher } from '../types/Pattern';
+import type { StandardSchemaV1 } from '../types/standard-schema/standard-schema-v1';
+
+const STANDARD_SCHEMA_KEY = '~standard';
+
+const isPromise = (value: unknown): value is Promise<unknown> =>
+  typeof (value as any)?.then === 'function';
 
 // @internal
 export const isObject = (value: unknown): value is Object =>
@@ -20,6 +26,22 @@ export const isMatcher = (
   return pattern && !!pattern[symbols.matcher];
 };
 
+const isStandardSchema = (
+  value: unknown
+): value is StandardSchemaV1<any, any> => {
+  if (!isObject(value)) return false;
+  const standard = (value as Record<string | symbol, unknown>)[
+    STANDARD_SCHEMA_KEY
+  ];
+  if (!isObject(standard)) return false;
+  const { version, vendor, validate } = standard as StandardSchemaV1.Props;
+  return (
+    version === 1 &&
+    typeof vendor === 'string' &&
+    typeof validate === 'function'
+  );
+};
+
 // @internal
 const isOptionalPattern = (
   x: unknown
@@ -43,6 +65,16 @@ export const matchPattern = (
     return matched;
   }
 
+  if (isStandardSchema(pattern)) {
+    const result = pattern[STANDARD_SCHEMA_KEY].validate(value);
+    if (isPromise(result)) {
+      throw new Error(
+        'Async Standard Schema validation is not supported by ts-pattern.'
+      );
+    }
+    return !Array.isArray(result.issues);
+  }
+
   if (isObject(pattern)) {
     if (!isObject(value)) return false;
 

src/internals/helpers.ts

@@ -25,6 +25,7 @@ import {
   RecordValue,
 } from './helpers';
 import type { Matcher, Pattern, Override, AnyMatcher } from './Pattern';
+import type { StandardSchemaV1 } from './standard-schema/standard-schema-v1';
 
 type OptionalKeys<p> = ValueOf<{
   [k in keyof p]: 0 extends 1 & p[k] // inlining IsAny for perf
@@ -145,6 +146,8 @@ type InvertPatternInternal<p, input> = 0 extends 1 & p
         narrowedOrFn extends Fn ? Call<narrowedOrFn, input> : narrowedOrFn
       >;
     }[matcherType]
+  : p extends StandardSchemaV1<any, any>
+  ? StandardSchemaV1.InferOutput<p>
   : p extends Primitives
   ? p
   : p extends readonly any[]
@@ -370,6 +373,8 @@ type InvertPatternForExcludeInternal<p, i, empty = never> =
           ? Call<narrowedOrFn, i>
           : excluded;
       }[matcherType]
+    : p extends StandardSchemaV1<any, any>
+    ? StandardSchemaV1.InferInput<p>
     : p extends readonly any[]
     ? Extract<i, readonly any[]> extends infer arrayInput
       ? InvertArrayPatternForExclude<

src/types/InvertPattern.ts

@@ -3,6 +3,7 @@ import { MergeUnion, Primitives, WithDefault } from './helpers';
 import { None, Some, SelectionType } from './FindSelected';
 import { matcher } from '../patterns';
 import { ExtractPreciseValue } from './ExtractPreciseValue';
+import type { StandardSchemaV1 } from './standard-schema/standard-schema-v1';
 
 export type MatcherType =
   | 'not'
@@ -80,6 +81,8 @@ export type AnyMatcher = Matcher<any, any, any, any, any>;
 
 type UnknownMatcher = PatternMatcher<unknown>;
 
+type StandardSchemaPattern = StandardSchemaV1;
+
 export type CustomP<input, pattern, narrowedOrFn> = Matcher<
   input,
   pattern,
@@ -141,7 +144,8 @@ export type UnknownValuePattern =
   | readonly [...unknown[], unknown]
   | UnknownProperties
   | Primitives
-  | UnknownMatcher;
+  | UnknownMatcher
+  | StandardSchemaPattern;
 
 /**
  * `Pattern<a>` is the generic type for patterns matching a value of type `a`. A pattern can be any (nested) javascript value.
@@ -168,6 +172,7 @@ type KnownPatternInternal<
 > =
   | primitives
   | PatternMatcher<a>
+  | StandardSchemaPattern
   | ([objs] extends [never] ? never : ObjectPattern<Readonly<MergeUnion<objs>>>)
   | ([arrays] extends [never] ? never : ArrayPattern<arrays>);
 

src/types/Pattern.ts

@@ -0,0 +1,73 @@
+/** The Standard Schema interface. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+
+export declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  export interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1;
+    /** The vendor name of the schema library. */
+    readonly vendor: string;
+    /** Validates unknown input values. */
+    readonly validate: (
+      value: unknown
+    ) => Result<Output> | Promise<Result<Output>>;
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+
+  /** The result interface of the validate function. */
+  export type Result<Output> = SuccessResult<Output> | FailureResult;
+
+  /** The result interface if validation succeeds. */
+  export interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output;
+    /** The non-existent issues. */
+    readonly issues?: undefined;
+  }
+
+  /** The result interface if validation fails. */
+  export interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: ReadonlyArray<Issue>;
+  }
+
+  /** The issue interface of the failure output. */
+  export interface Issue {
+    /** The error message of the issue. */
+    readonly message: string;
+    /** The path of the issue, if any. */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+
+  /** The path segment interface of the issue. */
+  export interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey;
+  }
+
+  /** The Standard Schema types interface. */
+  export interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input;
+    /** The output type of the schema. */
+    readonly output: Output;
+  }
+
+  /** Infers the input type of a Standard Schema. */
+  export type InferInput<Schema extends StandardSchemaV1> = NonNullable<
+    Schema['~standard']['types']
+  >['input'];
+
+  /** Infers the output type of a Standard Schema. */
+  export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<
+    Schema['~standard']['types']
+  >['output'];
+
+  // biome-ignore lint/complexity/noUselessEmptyExport: needed for granular visibility control of TS namespace
+  export {};
+}