@scalar/validation 0.1.0 → 0.2.0

package/src/typegen.test.ts

@@ -0,0 +1,214 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  any,
+  array,
+  boolean,
+  evaluate,
+  lazy,
+  intersection,
+  literal,
+  notDefined,
+  nullable,
+  number,
+  object,
+  optional,
+  record,
+  string,
+  union,
+} from '@/schema'
+import { generateTypes } from '@/typegen'
+
+const fixedGeneratedAt = '2000-01-01T00:00:00.000Z'
+
+const autogeneratedBanner = `/**\n * This file is autogenerated. Do not edit it.\n *\n * Generated at: ${fixedGeneratedAt}\n */\n\n`
+
+describe('typegen', () => {
+  it('emits primitives and special scalars', () => {
+    expect(generateTypes(number())).toBe('number')
+    expect(generateTypes(string())).toBe('string')
+    expect(generateTypes(boolean())).toBe('boolean')
+    expect(generateTypes(nullable())).toBe('null')
+    expect(generateTypes(notDefined())).toBe('undefined')
+    expect(generateTypes(any())).toBe('any')
+  })
+
+  it('emits arrays with parentheses when the item is a union or intersection', () => {
+    expect(generateTypes(array(number()))).toBe('number[]')
+    expect(generateTypes(array(union([number(), string()])))).toBe('(number | string)[]')
+    expect(generateTypes(array(intersection([object({ a: number() }), object({ b: string() })])))).toBe(
+      '({\n  a: number;\n} & {\n  b: string;\n})[]',
+    )
+  })
+
+  it('emits records and objects', () => {
+    expect(generateTypes(record(string(), number()))).toBe('Record<string, number>')
+    expect(
+      generateTypes(
+        object({
+          id: number(),
+          name: string(),
+        }),
+      ),
+    ).toBe('{\n  id: number;\n  name: string;\n}')
+    expect(generateTypes(object({}))).toBe('{}')
+  })
+
+  it('indents nested object properties', () => {
+    const car = object({
+      make: string(),
+      model: string(),
+      year: number(),
+      test: object({ test: string() }),
+    })
+    expect(generateTypes(car)).toBe(
+      '{\n  make: string;\n  model: string;\n  year: number;\n  test: {\n    test: string;\n  };\n}',
+    )
+  })
+
+  it('extracts typeName into a single export and references by name', () => {
+    const user = object(
+      {
+        id: number(),
+        name: string(),
+      },
+      { typeName: 'User' },
+    )
+    expect(generateTypes(user, { generatedAt: fixedGeneratedAt })).toBe(
+      `${autogeneratedBanner}export type User = {\n  id: number;\n  name: string;\n}`,
+    )
+  })
+
+  it('does not duplicate named types when the same name appears multiple times', () => {
+    const user = object({ id: number() }, { typeName: 'User' })
+    const doc = object(
+      {
+        author: user,
+        editor: user,
+      },
+      { typeName: 'Document' },
+    )
+    const out = generateTypes(doc, { generatedAt: fixedGeneratedAt })
+    expect(out.match(/export type User/g)?.length).toBe(1)
+    expect(out).toContain('author: User')
+    expect(out).toContain('editor: User')
+    expect(out).toContain('export type Document =')
+  })
+
+  it('includes typeComment as JSDoc on named exports', () => {
+    const t = object({}, { typeName: 'Empty', typeComment: 'No fields.' })
+    expect(generateTypes(t, { generatedAt: fixedGeneratedAt })).toBe(
+      `${autogeneratedBanner}/** No fields. */\nexport type Empty = {}`,
+    )
+  })
+
+  it('formats multi-line typeComment as a JSDoc block', () => {
+    const t = object({}, { typeName: 'T', typeComment: 'Line 1\nLine 2' })
+    expect(generateTypes(t, { generatedAt: fixedGeneratedAt })).toBe(
+      `${autogeneratedBanner}/** \n * Line 1\n * Line 2\n */\nexport type T = {}`,
+    )
+  })
+
+  it('prefixes file-style output with an autogenerated banner and timestamp', () => {
+    const t = object({ x: number() }, { typeName: 'T' })
+    const out = generateTypes(t, { generatedAt: fixedGeneratedAt })
+    expect(out.startsWith(autogeneratedBanner)).toBe(true)
+    expect(out).toContain('Generated at: 2000-01-01T00:00:00.000Z')
+  })
+
+  it('wraps named types in export namespace when namespace option is set', () => {
+    const user = object(
+      {
+        id: number(),
+        name: string(),
+      },
+      { typeName: 'User' },
+    )
+    expect(generateTypes(user, { generatedAt: fixedGeneratedAt, namespace: 'Models' })).toBe(
+      `${autogeneratedBanner}export namespace Models {\n  export type User = {\n    id: number;\n    name: string;\n  }\n}\n`,
+    )
+  })
+
+  it('keeps cross-references unqualified inside a namespace', () => {
+    const user = object({ id: number() }, { typeName: 'User' })
+    const doc = object({ author: user }, { typeName: 'Document' })
+    const out = generateTypes(doc, { generatedAt: fixedGeneratedAt, namespace: 'Api' })
+    expect(out).toContain('export namespace Api {')
+    expect(out).toContain('author: User')
+    expect(out.match(/export type User/g)?.length).toBe(1)
+  })
+
+  it('ignores namespace when it is not a valid TypeScript identifier', () => {
+    const t = object({ x: number() }, { typeName: 'T' })
+    const out = generateTypes(t, { generatedAt: fixedGeneratedAt, namespace: 'not-valid' })
+    expect(out).not.toContain('export namespace')
+    expect(out).toContain('export type T =')
+  })
+
+  it('includes typeComment as JSDoc on object properties', () => {
+    const t = object({
+      id: number({ typeComment: 'Unique id.' }),
+      name: string({ typeComment: 'Display name.' }),
+    })
+    expect(generateTypes(t)).toBe('{\n  /** Unique id. */\n  id: number;\n  /** Display name. */\n  name: string;\n}')
+  })
+
+  it('indents multi-line property typeComment in nested objects', () => {
+    const t = object({
+      outer: string({ typeComment: 'A\nB' }),
+      inner: object({
+        x: number({ typeComment: 'Nested.' }),
+      }),
+    })
+    expect(generateTypes(t)).toBe(
+      '{\n  /** \n   * A\n   * B\n   */\n  outer: string;\n  inner: {\n    /** Nested. */\n    x: number;\n  };\n}',
+    )
+  })
+
+  it('ignores invalid typeName and keeps inline shape', () => {
+    const bad = object({ x: number() }, { typeName: 'not-valid' })
+    expect(generateTypes(bad)).toBe('{\n  x: number;\n}')
+  })
+
+  it('quotes object keys that are not valid identifiers', () => {
+    expect(generateTypes(object({ 'foo-bar': string() }))).toBe('{\n  "foo-bar": string;\n}')
+  })
+
+  it('emits unions and optionals', () => {
+    expect(generateTypes(union([literal(1), literal(2)]))).toBe('1 | 2')
+    expect(generateTypes(optional(number()))).toBe('number | undefined')
+  })
+
+  it('emits never for an empty union and unknown for an empty intersection', () => {
+    expect(generateTypes(union([]))).toBe('never')
+    expect(generateTypes(intersection([]))).toBe('unknown')
+  })
+
+  it('emits optional object properties with ? instead of | undefined', () => {
+    expect(
+      generateTypes(
+        object({
+          id: number(),
+          name: optional(string()),
+        }),
+      ),
+    ).toBe('{\n  id: number;\n  name?: string;\n}')
+  })
+
+  it('emits literal bigint', () => {
+    expect(generateTypes(literal(10n))).toBe('10n')
+  })
+
+  it('unwraps evaluate to the inner schema type', () => {
+    expect(generateTypes(evaluate((v) => v, number()))).toBe('number')
+  })
+
+  it('resolves lazy schemas', () => {
+    const schema = lazy(() => object({ n: number() }))
+    expect(generateTypes(schema)).toBe('{\n  n: number;\n}')
+  })
+
+  it('returns any when max depth is exhausted', () => {
+    expect(generateTypes(number(), { maxDepth: 0 })).toBe('any')
+  })
+})

package/src/typegen.ts

@@ -0,0 +1,268 @@
+import type { Schema } from './schema'
+
+const DEFAULT_MAX_DEPTH = 10
+
+export type GenerateTypesOptions = {
+  maxDepth?: number
+  /**
+   * ISO 8601 timestamp printed in the autogenerated file banner.
+   * Defaults to the time of the `generateTypes` call when the banner is emitted.
+   */
+  generatedAt?: string
+  /**
+   * When set to a valid TypeScript identifier, wraps all emitted `export type` declarations (and any
+   * trailing root type) in `export namespace Name { ... }` so consumers reference `Name.SomeType`.
+   */
+  namespace?: string
+}
+
+type NamedDeclaration = {
+  name: string
+  body: string
+  comment?: string
+}
+
+type TypeGenContext = {
+  definitions: Map<string, string>
+  declarations: NamedDeclaration[]
+  inProgress: Set<string>
+}
+
+/**
+ * Returns TypeScript for the schema: named `typeName` nodes become `export type` aliases (once each),
+ * referenced by name elsewhere. With no named nodes, returns a single inline type expression (same as before).
+ *
+ * When at least one named type is emitted, the result is prefixed with a banner stating the output is
+ * autogenerated and must not be edited manually, plus a generation timestamp.
+ *
+ * Pass `namespace` to wrap declarations in `export namespace … { … }`.
+ */
+export const generateTypes = (schema: Schema, options?: GenerateTypesOptions): string => {
+  const maxDepth = options?.maxDepth ?? DEFAULT_MAX_DEPTH
+  const ctx: TypeGenContext = {
+    definitions: new Map(),
+    declarations: [],
+    inProgress: new Set(),
+  }
+  const root = emitSchema(schema, maxDepth, ctx, '')
+
+  if (ctx.declarations.length === 0) {
+    return root
+  }
+
+  const declStrings = ctx.declarations.map(formatNamedDeclaration)
+  const body = declStrings.join('\n\n')
+  const lastDeclared = ctx.declarations.at(-1)?.name
+  let content = lastDeclared === root ? body : `${body}\n\n${root}`
+  const ns = options?.namespace
+  if (ns && isValidTypeScriptIdentifier(ns)) {
+    content = wrapDeclarationsInNamespace(ns, content)
+  }
+  const generatedAt = options?.generatedAt ?? new Date().toISOString()
+  return `${formatAutogeneratedFileBanner(generatedAt)}${content}`
+}
+
+const formatAutogeneratedFileBanner = (generatedAt: string): string =>
+  `/**\n * This file is autogenerated. Do not edit it.\n *\n * Generated at: ${generatedAt}\n */\n\n`
+
+const wrapDeclarationsInNamespace = (namespace: string, content: string): string => {
+  const body = content
+    .split('\n')
+    .map((line) => (line === '' ? '' : `  ${line}`))
+    .join('\n')
+  return `export namespace ${namespace} {\n${body}\n}\n`
+}
+
+const formatNamedDeclaration = (d: NamedDeclaration): string => {
+  const commentBlock = d.comment ? formatTypeCommentAsJsDoc(d.comment) : ''
+  const comment = commentBlock ? `${commentBlock}\n` : ''
+  return `${comment}export type ${d.name} = ${d.body}`
+}
+
+/** Inline JSDoc for one line; multi-line comments use a newline after the opening delimiter and ` * ` on each line. */
+const formatTypeCommentAsJsDoc = (comment: string): string => {
+  const lines = comment.split(/\r?\n/)
+  const trimmed = lines.map((line) => line.trim())
+  while (trimmed.length > 0 && trimmed[0] === '') {
+    trimmed.shift()
+  }
+  while (trimmed.length > 0 && trimmed.at(-1) === '') {
+    trimmed.pop()
+  }
+  if (trimmed.length === 0) {
+    return ''
+  }
+  if (trimmed.length === 1) {
+    return `/** ${trimmed[0]} */`
+  }
+  const body = trimmed.map((line) => ` * ${line}`).join('\n')
+  return `/** \n${body}\n */`
+}
+
+/** Prefixes each line of a JSDoc block with `indent` for object property comments. */
+const formatTypeCommentAsIndentedJsDoc = (indent: string, comment: string): string => {
+  const doc = formatTypeCommentAsJsDoc(comment)
+  if (!doc) {
+    return ''
+  }
+  return doc
+    .split('\n')
+    .map((line) => `${indent}${line}`)
+    .join('\n')
+}
+
+const getTypeName = (schema: Schema): string | undefined => {
+  if (schema.type === 'lazy' || schema.type === 'evaluate') {
+    return undefined
+  }
+  const name = schema.typeName
+  if (!name || !isValidTypeScriptIdentifier(name)) {
+    return undefined
+  }
+  return name
+}
+
+const getTypeComment = (schema: Schema): string | undefined => {
+  if (schema.type === 'lazy' || schema.type === 'evaluate') {
+    return undefined
+  }
+  if (schema.type === 'optional') {
+    return schema.typeComment ?? getTypeComment(schema.schema)
+  }
+  return schema.typeComment
+}
+
+const isValidTypeScriptIdentifier = (name: string): boolean => /^[$_A-Za-z][$_\w]*$/.test(name)
+
+const emitSchema = (schema: Schema, depth: number, ctx: TypeGenContext, braceIndent: string): string => {
+  const name = getTypeName(schema)
+  if (name) {
+    if (ctx.definitions.has(name)) {
+      return name
+    }
+    if (ctx.inProgress.has(name)) {
+      return name
+    }
+    ctx.inProgress.add(name)
+    const body = structuralEmit(schema, depth, ctx, '')
+    ctx.inProgress.delete(name)
+    if (!ctx.definitions.has(name)) {
+      ctx.definitions.set(name, body)
+      ctx.declarations.push({
+        name,
+        body,
+        comment: getTypeComment(schema),
+      })
+    }
+    return name
+  }
+  return structuralEmit(schema, depth, ctx, braceIndent)
+}
+
+const structuralEmit = (schema: Schema, depth: number, ctx: TypeGenContext, braceIndent: string): string => {
+  if (depth <= 0) {
+    return 'any'
+  }
+  const next = depth - 1
+
+  switch (schema.type) {
+    case 'number':
+      return 'number'
+    case 'string':
+      return 'string'
+    case 'boolean':
+      return 'boolean'
+    case 'nullable':
+      return 'null'
+    case 'notDefined':
+      return 'undefined'
+    case 'any':
+      return 'any'
+    case 'array': {
+      const item = emitSchema(schema.items, next, ctx, braceIndent)
+      return needsArrayItemParen(item) ? `(${item})[]` : `${item}[]`
+    }
+    case 'record': {
+      const key = emitSchema(schema.key, next, ctx, braceIndent)
+      const value = emitSchema(schema.value, next, ctx, braceIndent)
+      return `Record<${key}, ${value}>`
+    }
+    case 'object': {
+      const entries = Object.entries(schema.properties)
+      if (entries.length === 0) {
+        return '{}'
+      }
+      const keyIndent = `${braceIndent}  `
+      const props = entries.map(([key, child]) => {
+        const tsKey = /^[$_a-zA-Z][$_\w]*$/.test(key) ? key : JSON.stringify(key)
+        const optionalProp = child.type === 'optional'
+        const valueSchema = optionalProp ? child.schema : child
+        const value = emitSchema(valueSchema, next, ctx, keyIndent)
+        const propComment = getTypeComment(child)
+        const docBlock = propComment ? formatTypeCommentAsIndentedJsDoc(keyIndent, propComment) : ''
+        const propLine = optionalProp ? `${keyIndent}${tsKey}?: ${value};` : `${keyIndent}${tsKey}: ${value};`
+        return docBlock ? `${docBlock}\n${propLine}` : propLine
+      })
+      return `{\n${props.join('\n')}\n${braceIndent}}`
+    }
+    case 'optional': {
+      const inner = emitSchema(schema.schema, next, ctx, braceIndent)
+      return `${wrapUnionMember(inner)} | undefined`
+    }
+    case 'union':
+      if (schema.schemas.length === 0) {
+        return 'never'
+      }
+      return schema.schemas.map((s) => wrapUnionMember(emitSchema(s, next, ctx, braceIndent))).join(' | ')
+    case 'intersection':
+      if (schema.schemas.length === 0) {
+        return 'unknown'
+      }
+      return schema.schemas.map((s) => wrapIntersectionMember(emitSchema(s, next, ctx, braceIndent))).join(' & ')
+    case 'literal':
+      return literalToTs(schema.value)
+    case 'lazy':
+      return emitSchema(schema.schema(), next, ctx, braceIndent)
+    case 'evaluate':
+      return emitSchema(schema.schema, next, ctx, braceIndent)
+    default: {
+      const _exhaustive: never = schema
+      return _exhaustive
+    }
+  }
+}
+
+const literalToTs = (value: string | number | boolean | bigint): string => {
+  if (typeof value === 'bigint') {
+    return `${value}n`
+  }
+  return JSON.stringify(value)
+}
+
+const needsArrayItemParen = (t: string): boolean => {
+  if (t === 'number' || t === 'string' || t === 'boolean' || t === 'null' || t === 'undefined' || t === 'any') {
+    return false
+  }
+  // Union: `A | B[]` is `A | (B[])`; intersection: `A & B[]` is `A & (B[])`. Wrap the whole item type.
+  return t.includes(' | ') || t.includes(' & ')
+}
+
+const wrapUnionMember = (t: string): string => {
+  if (t === 'number' || t === 'string' || t === 'boolean' || t === 'null' || t === 'undefined' || t === 'any') {
+    return t
+  }
+  if (/^(?:-?(?:\d+(?:\.\d+)?|\.\d+)(?:[eE][+-]?\d+)?|-?\d+n|"(?:[^"\\]|\\.)*"|true|false)$/.test(t)) {
+    return t
+  }
+  if (/^[$_A-Za-z][$_\w]*$/.test(t)) {
+    return t
+  }
+  return `(${t})`
+}
+
+const wrapIntersectionMember = (t: string): string => {
+  if (t.includes(' | ') || t.includes(' & ')) {
+    return `(${t})`
+  }
+  return t
+}

package/src/types.ts

@@ -3,12 +3,14 @@ import type {
   ArraySchema,
   BooleanSchema,
   EvaluateSchema,
+  IntersectionSchema,
   LazySchema,
   LiteralSchema,
   NotDefinedSchema,
   NullableSchema,
   NumberSchema,
   ObjectSchema,
+  OptionalSchema,
   RecordSchema,
   StringSchema,
   UnionSchema,
@@ -17,6 +19,34 @@ import type {
 // Export Static type with depth limit to prevent infinite recursion
 export type Static<T> = _Static<T, 10>
 
+/** Folds a tuple of object schemas into an intersection of their static object types. */
+type IntersectObjectStatics<
+  Schemas extends readonly ObjectSchema<any>[],
+  Depth extends number,
+> = Schemas extends readonly [infer First extends ObjectSchema<any>, ...infer Rest extends readonly ObjectSchema<any>[]]
+  ? _Static<First, Depth> & IntersectObjectStatics<Rest, Depth>
+  : {}
+
+type OptionalPropertyKeys<P> = {
+  [K in keyof P]: P[K] extends OptionalSchema<any> ? K : never
+}[keyof P]
+
+type RequiredPropertyKeys<P> = {
+  [K in keyof P]: P[K] extends OptionalSchema<any> ? never : K
+}[keyof P]
+
+type OptionalSchemaInner<S> = S extends OptionalSchema<infer Inner> ? Inner : never
+
+type ObjectStatics<Properties, Depth extends number> = [keyof Properties] extends [never]
+  ? {}
+  : OptionalPropertyKeys<Properties> extends never
+    ? { [K in keyof Properties]: _Static<Properties[K], Prev<Depth>> }
+    : RequiredPropertyKeys<Properties> extends never
+      ? { [K in OptionalPropertyKeys<Properties>]?: _Static<OptionalSchemaInner<Properties[K]>, Prev<Depth>> }
+      : { [K in RequiredPropertyKeys<Properties>]: _Static<Properties[K], Prev<Depth>> } & {
+          [K in OptionalPropertyKeys<Properties>]?: _Static<OptionalSchemaInner<Properties[K]>, Prev<Depth>>
+        }
+
 // Internal type with depth counter
 type _Static<T, Depth extends number = 10> = Depth extends 0
   ? any
@@ -39,14 +69,18 @@ type _Static<T, Depth extends number = 10> = Depth extends 0
                   : T extends RecordSchema<infer Key, infer Value>
                     ? Record<_Static<Key, Prev<Depth>> & PropertyKey, _Static<Value, Prev<Depth>>>
                     : T extends ObjectSchema<infer Properties>
-                      ? { [K in keyof Properties]: _Static<Properties[K], Prev<Depth>> }
-                      : T extends UnionSchema<infer Schemas>
-                        ? _Static<Schemas[number], Prev<Depth>>
-                        : T extends EvaluateSchema<infer S>
-                          ? _Static<S, Prev<Depth>>
-                          : T extends LazySchema<infer S>
-                            ? _Static<ReturnType<S>, Prev<Depth>>
-                            : never
+                      ? ObjectStatics<Properties, Depth>
+                      : T extends OptionalSchema<infer S>
+                        ? _Static<S, Prev<Depth>> | undefined
+                        : T extends IntersectionSchema<infer Schemas extends readonly ObjectSchema<any>[]>
+                          ? IntersectObjectStatics<Schemas, Prev<Depth>>
+                          : T extends UnionSchema<infer Schemas>
+                            ? _Static<Schemas[number], Prev<Depth>>
+                            : T extends EvaluateSchema<infer S>
+                              ? _Static<S, Prev<Depth>>
+                              : T extends LazySchema<infer S>
+                                ? _Static<ReturnType<S>, Prev<Depth>>
+                                : never
 
 // Helper type to decrement depth counter
 type Prev<T extends number> = T extends 10

package/src/validate.test.ts

@@ -5,6 +5,7 @@ import {
   array,
   boolean,
   evaluate,
+  intersection,
   lazy,
   literal,
   notDefined,
@@ -652,6 +653,58 @@ describe('union', () => {
   })
 })
 
+describe('intersection', () => {
+  it('passes when the value satisfies every member object schema', () => {
+    const T = intersection([object({ a: number(), b: number() }), object({ c: string(), d: string() })])
+    expect(validate(T, { a: 1, b: 2, c: 'x', d: 'y' })).toBe(true)
+  })
+
+  it('fails when one member object schema fails', () => {
+    const T = intersection([object({ a: number(), b: number() }), object({ c: string(), d: string() })])
+    expect(validate(T, { a: 1, b: 2, c: 'x', d: 3 })).toBe(false)
+  })
+
+  it('fails when the first member fails even if later members would pass', () => {
+    const T = intersection([object({ x: literal(1) }), object({ y: string() })])
+    expect(validate(T, { x: 2, y: 'ok' })).toBe(false)
+  })
+
+  it('requires overlapping keys to satisfy every arm that declares them', () => {
+    const T = intersection([object({ id: number() }), object({ id: string() })])
+    expect(validate(T, { id: 1 })).toBe(false)
+    expect(validate(T, { id: '1' })).toBe(false)
+  })
+
+  it('rejects non-plain objects before member checks', () => {
+    const T = intersection([object({ x: number() }), object({ y: number() })])
+    expect(validate(T, null)).toBe(false)
+    expect(validate(T, undefined)).toBe(false)
+    expect(validate(T, 0)).toBe(false)
+    expect(validate(T, [])).toBe(false)
+    expect(validate(T, new Date())).toBe(false)
+  })
+
+  it('treats an empty intersection as vacuously valid', () => {
+    const T = intersection([])
+    expect(validate(T, null)).toBe(true)
+    expect(validate(T, { a: 1 })).toBe(true)
+  })
+
+  it('matches a single member the same as that object schema alone', () => {
+    const O = object({ x: number() })
+    const T = intersection([O])
+    expect(validate(T, { x: 1 })).toBe(true)
+    expect(validate(T, {})).toBe(false)
+    expect(validate(O, { x: 1 })).toBe(validate(T, { x: 1 }))
+  })
+
+  it('validates members that use lazy schemas', () => {
+    const T = intersection([object({ a: number() }), object({ nested: lazy(() => object({ z: string() })) })])
+    expect(validate(T, { a: 1, nested: { z: 'ok' } })).toBe(true)
+    expect(validate(T, { a: 1, nested: { z: 1 } })).toBe(false)
+  })
+})
+
 describe('notDefined', () => {
   const T = notDefined()
   it('Should fail string', () => {

package/src/validate.ts

@@ -14,10 +14,12 @@ import type { Schema } from './schema'
  * - 'notDefined':  Only `undefined` is valid.
  * - 'array':       Array with all items validated recursively.
  * - 'record':      Object with string/number keys and values, checked recursively.
- * - 'object':      Object with fixed property keys, each validated recursively.
+ * - 'object':      Plain object with fixed property keys, each validated recursively.
  * - 'union':       Accepts if value matches any of the listed schemas.
+ * - 'optional':    Accepts `undefined` or a value matching the inner schema.
+ * - 'intersection': Accepts if value matches every member schema (members are object schemas; value must be a plain object).
  * - 'literal':     Exact match with a literal value.
- * - 'recursive':   Schema referring to itself for nested validation (e.g. trees).
+ * - 'lazy':        Delegates to the schema returned by the factory.
  * - 'evaluate':    Transforms value then validates against an inner schema.
  *
  * @example
@@ -72,9 +74,22 @@ export const validate = (schema: Schema | undefined, value: unknown): boolean =>
     const schemaKeys = Object.keys(schema.properties)
     return schemaKeys.every((key) => validate(schema.properties[key], value[key]))
   }
+  if (schema.type === 'optional') {
+    return value === undefined || validate(schema.schema, value)
+  }
   if (schema.type === 'union') {
     return schema.schemas.some((schema) => validate(schema, value))
   }
+  if (schema.type === 'intersection') {
+    if (schema.schemas.length === 0) {
+      // Vacuous: no constraints (matches `Array.prototype.every` on an empty list).
+      return true
+    }
+    if (!isObject(value)) {
+      return false
+    }
+    return schema.schemas.every((subSchema) => validate(subSchema, value))
+  }
   if (schema.type === 'literal') {
     return value === schema.value
   }