feat: comply to standard schema

Author: SacDeNoeuds

guides/coercing-a-bigint-from-json.md

@@ -45,11 +45,9 @@ const bigint = pipe(
     } catch (error) {
       return {
         success: false,
-        error: {
-          input: stringOrNumber,
-          schemaName: 'bigint',
-          issues: [],
-        },
+        input: stringOrNumber,
+        schemaName: 'bigint',
+        issues: [],
       }
     }
   }),

package-lock.json

@@ -63,6 +63,7 @@
     "@rollup/plugin-node-resolve": "^15.3.0",
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "^12.1.1",
+    "@standard-schema/spec": "^1.0.0",
     "@types/node": "^22.10.1",
     "@vitest/coverage-istanbul": "^2.1.8",
     "prettier": "^3.4.1",

package.json

@@ -16,14 +16,22 @@ describe('Map schema', () => {
     const result = schema.parse(input)
     expect(result).toEqual({
       success: false,
-      error: {
-        input,
-        schemaName: 'Map<number, number>',
-        issues: [
-          { schemaName: 'number', input: 'a', path: ['a'] },
-          { schemaName: 'number', input: 'b', path: ['b'] },
-        ],
-      },
+      input,
+      schemaName: 'Map<number, number>',
+      issues: [
+        {
+          schemaName: 'number',
+          input: 'a',
+          path: ['a'],
+          message: expect.any(String),
+        },
+        {
+          schemaName: 'number',
+          input: 'b',
+          path: ['b'],
+          message: expect.any(String),
+        },
+      ],
     })
   })
 
@@ -33,14 +41,22 @@ describe('Map schema', () => {
     const result = schema.parse(input)
     expect(result).toEqual({
       success: false,
-      error: {
-        input,
-        schemaName: 'Map<string, string>',
-        issues: [
-          { schemaName: 'string', input: 1, path: ['a'] },
-          { schemaName: 'string', input: 2, path: ['b'] },
-        ],
-      },
+      input,
+      schemaName: 'Map<string, string>',
+      issues: [
+        {
+          schemaName: 'string',
+          input: 1,
+          path: ['a'],
+          message: expect.any(String),
+        },
+        {
+          schemaName: 'string',
+          input: 2,
+          path: ['b'],
+          message: expect.any(String),
+        },
+      ],
     })
   })
 
@@ -50,11 +66,16 @@ describe('Map schema', () => {
     const result = schema.parse(input)
     expect(result).toEqual({
       success: false,
-      error: {
-        input,
-        schemaName: 'Map<string, string>',
-        issues: [{ schemaName: 'Map<string, string>', input, path: [] }],
-      },
+      input,
+      schemaName: 'Map<string, string>',
+      issues: [
+        {
+          schemaName: 'Map<string, string>',
+          input,
+          path: [],
+          message: expect.any(String),
+        },
+      ],
     })
   })
 })

src/Map.test.ts

@@ -1,6 +1,6 @@
 import { createParseContext, withPathSegment } from './ParseContext'
 import { failure, success } from './ParseResult'
-import type { Schema } from './Schema'
+import { standardize, type Schema } from './Schema'
 
 /**
  * @category Schema Definition
@@ -35,9 +35,9 @@ export { Map_ as Map }
 function Map_<T extends Map<PropertyKey, any>, Input = unknown>(
   key: Schema<MapKey<T>>,
   value: Schema<MapValue<T>>,
-): MapSchema<T, Input> {
+) {
   const name = `Map<${key.name}, ${value.name}>`
-  return {
+  return standardize<MapSchema<T, Input>>({
     name,
     key,
     value,
@@ -56,5 +56,5 @@ function Map_<T extends Map<PropertyKey, any>, Input = unknown>(
       })
       return success(context, acc)
     },
-  }
+  })
 }

src/Map.ts

@@ -1,7 +1,13 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type { ParseContext } from './ParseContext'
 
-export type Success<T> = { success: true; value: T }
-export type Failure = { success: false; error: ParseError }
+export type Success<T> = Extract<
+  { readonly success: true; readonly value: T },
+  StandardSchemaV1.SuccessResult<T>
+>
+export interface Failure extends ParseError {
+  readonly success: false
+}
 
 /**
  * @category Parsing
@@ -17,28 +23,44 @@ export type Failure = { success: false; error: ParseError }
  *  | { success: false, error: ParseError }
  * ```
  */
-export type ParseResult<T> = Success<T> | Failure
+export type ParseResult<T> = Extract<
+  Success<T> | Failure,
+  StandardSchemaV1.Result<T>
+>
 
 /**
  * @category Parsing
  * @see {@link ParseResult}
  * @see {@link ParseIssue}
  */
-export type ParseError = {
-  schemaName: string
-  input: unknown
-  issues: ParseIssue[]
-}
+export type ParseError = Extract<
+  {
+    readonly schemaName: string
+    readonly input: unknown
+    readonly issues: ReadonlyArray<StandardSchemaV1.Issue>
+  },
+  StandardSchemaV1.FailureResult
+>
 
 /**
  * @category Parsing
  * @see {@link ParseError}
  */
-export type ParseIssue = {
-  schemaName: string
-  refinement?: string
-  input: unknown
-  path: PropertyKey[]
+export type ParseIssue = Extract<
+  {
+    readonly schemaName: string
+    readonly refinement?: string
+    readonly input: unknown
+    readonly message: string
+    readonly path: PropertyKey[]
+  },
+  StandardSchemaV1.Issue
+>
+
+function makeMessage(issue: Omit<ParseIssue, 'message'>): string {
+  const refinement = issue.refinement ? ` (${issue.refinement})` : ''
+  const path = issue.path.length ? `At ${issue.path.join('.')}: ` : ''
+  return `${path}not a ${issue.schemaName}${refinement}`
 }
 
 /**
@@ -64,14 +86,20 @@ export function failure(
   input: unknown,
   refinement?: string,
 ): Failure {
-  context.issues.push({ input, schemaName, path: context.path, refinement })
+  context.issues.push({
+    input,
+    schemaName,
+    path: context.path,
+    refinement,
+    get message() {
+      return makeMessage(this)
+    },
+  })
   return {
     success: false,
-    error: {
-      input: context.rootInput,
-      schemaName: context.rootSchemaName,
-      issues: context.issues,
-    },
+    input: context.rootInput,
+    schemaName: context.rootSchemaName,
+    issues: context.issues,
   }
 }
 
@@ -97,10 +125,8 @@ export function success<T>(context: ParseContext, value: T): ParseResult<T> {
     ? { success: true, value }
     : {
         success: false,
-        error: {
-          input: context.rootInput,
-          schemaName: context.rootSchemaName,
-          issues: context.issues,
-        },
+        input: context.rootInput,
+        schemaName: context.rootSchemaName,
+        issues: context.issues,
       }
 }

src/ParseResult.ts

@@ -23,23 +23,33 @@ describe('flatMap', () => {
       const result = numberFromString.parse('foo')
       expect(result).toEqual({
         success: false,
-        error: {
-          input: 'foo',
-          schemaName: 'numberFromString',
-          issues: [{ schemaName: 'number', input: NaN, path: [] }],
-        },
+        input: 'foo',
+        schemaName: 'numberFromString',
+        issues: [
+          {
+            schemaName: 'number',
+            input: NaN,
+            path: [],
+            message: expect.any(String),
+          },
+        ],
       })
     })
 
     it('fails parsing a non-string – even a number !', () => {
       const result = numberFromString.parse(42)
       expect(result).toEqual({
         success: false,
-        error: {
-          input: 42,
-          schemaName: 'numberFromString',
-          issues: [{ schemaName: 'string', input: 42, path: [] }],
-        },
+        input: 42,
+        schemaName: 'numberFromString',
+        issues: [
+          {
+            schemaName: 'string',
+            input: 42,
+            path: [],
+            message: expect.any(String),
+          },
+        ],
       })
     })
   })

src/Schema.test.ts

@@ -1,12 +1,28 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec'
 import { createParseContext, type ParseContext } from './ParseContext'
 import { type ParseResult } from './ParseResult'
 import type { Refinement } from './refine'
 
+const vendor = 'unhoax'
+const version = 1 as const
+
+export function standardize<S extends Schema<any, any>>(
+  config: Omit<S, keyof StandardSchemaV1>,
+): S {
+  return Object.assign(config as any, {
+    '~standard': {
+      vendor,
+      version,
+      validate: config.parse,
+    },
+  })
+}
+
 /**
  * @category Schema Definition
  * @see {@link TypeOf}
  */
-export interface Schema<T, Input = unknown> {
+export interface Schema<T, Input = unknown> extends StandardSchemaV1<Input, T> {
   readonly name: string
   readonly refinements?: Refinement[]
   /**
@@ -132,11 +148,11 @@ export function flatMap<Input, Output>(
     return {
       ...schema,
       name: schemaName,
-      parse: (input, context = createParseContext(schemaName, input)) => {
+      parse: (input: any, context = createParseContext(schemaName, input)) => {
         const result = schema.parse(input, context)
         return result.success ? mapper(result.value, context) : result
       },
-    }
+    } as any
   }
 }