@scalar/validation 0.1.0 → 0.2.0

package/dist/types.d.ts

@@ -1,8 +1,24 @@
-import type { AnySchema, ArraySchema, BooleanSchema, EvaluateSchema, LazySchema, LiteralSchema, NotDefinedSchema, NullableSchema, NumberSchema, ObjectSchema, RecordSchema, StringSchema, UnionSchema } from './schema.js';
+import type { AnySchema, ArraySchema, BooleanSchema, EvaluateSchema, IntersectionSchema, LazySchema, LiteralSchema, NotDefinedSchema, NullableSchema, NumberSchema, ObjectSchema, OptionalSchema, RecordSchema, StringSchema, UnionSchema } from './schema.js';
 export type Static<T> = _Static<T, 10>;
-type _Static<T, Depth extends number = 10> = Depth extends 0 ? any : T extends LiteralSchema<infer Value> ? Value : T extends NumberSchema ? number : T extends StringSchema ? string : T extends BooleanSchema ? boolean : T extends NullableSchema ? null : T extends NotDefinedSchema ? undefined : T extends AnySchema ? any : T extends ArraySchema<infer Item> ? Array<_Static<Item, Prev<Depth>>> : T extends RecordSchema<infer Key, infer Value> ? Record<_Static<Key, Prev<Depth>> & PropertyKey, _Static<Value, Prev<Depth>>> : T extends ObjectSchema<infer Properties> ? {
+/** 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>>;
-} : 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;
+} : 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>>;
+};
+type _Static<T, Depth extends number = 10> = Depth extends 0 ? any : T extends LiteralSchema<infer Value> ? Value : T extends NumberSchema ? number : T extends StringSchema ? string : T extends BooleanSchema ? boolean : T extends NullableSchema ? null : T extends NotDefinedSchema ? undefined : T extends AnySchema ? any : T extends ArraySchema<infer Item> ? Array<_Static<Item, Prev<Depth>>> : T extends RecordSchema<infer Key, infer Value> ? Record<_Static<Key, Prev<Depth>> & PropertyKey, _Static<Value, Prev<Depth>>> : T extends ObjectSchema<infer Properties> ? 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;
 type Prev<T extends number> = T extends 10 ? 9 : T extends 9 ? 8 : T extends 8 ? 7 : T extends 7 ? 6 : T extends 6 ? 5 : T extends 5 ? 4 : T extends 4 ? 3 : T extends 3 ? 2 : T extends 2 ? 1 : T extends 1 ? 0 : 0;
 export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,WAAW,EACX,aAAa,EACb,cAAc,EACd,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACZ,MAAM,UAAU,CAAA;AAGjB,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;AAGtC,KAAK,OAAO,CAAC,CAAC,EAAE,KAAK,SAAS,MAAM,GAAG,EAAE,IAAI,KAAK,SAAS,CAAC,GACxD,GAAG,GACH,CAAC,SAAS,aAAa,CAAC,MAAM,KAAK,CAAC,GAClC,KAAK,GACL,CAAC,SAAS,YAAY,GACpB,MAAM,GACN,CAAC,SAAS,YAAY,GACpB,MAAM,GACN,CAAC,SAAS,aAAa,GACrB,OAAO,GACP,CAAC,SAAS,cAAc,GACtB,IAAI,GACJ,CAAC,SAAS,gBAAgB,GACxB,SAAS,GACT,CAAC,SAAS,SAAS,GACjB,GAAG,GACH,CAAC,SAAS,WAAW,CAAC,MAAM,IAAI,CAAC,GAC/B,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GACjC,CAAC,SAAS,YAAY,CAAC,MAAM,GAAG,EAAE,MAAM,KAAK,CAAC,GAC5C,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,WAAW,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAC5E,CAAC,SAAS,YAAY,CAAC,MAAM,UAAU,CAAC,GACtC;KAAG,CAAC,IAAI,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;CAAE,GAChE,CAAC,SAAS,WAAW,CAAC,MAAM,OAAO,CAAC,GAClC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,GACrC,CAAC,SAAS,cAAc,CAAC,MAAM,CAAC,CAAC,GAC/B,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,GACvB,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,CAAC,GAC3B,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,GACnC,KAAK,CAAA;AAGnC,KAAK,IAAI,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,EAAE,GACtC,CAAC,GACD,CAAC,SAAS,CAAC,GACT,CAAC,GACD,CAAC,SAAS,CAAC,GACT,CAAC,GACD,CAAC,SAAS,CAAC,GACT,CAAC,GACD,CAAC,SAAS,CAAC,GACT,CAAC,GACD,CAAC,SAAS,CAAC,GACT,CAAC,GACD,CAAC,SAAS,CAAC,GACT,CAAC,GACD,CAAC,SAAS,CAAC,GACT,CAAC,GACD,CAAC,SAAS,CAAC,GACT,CAAC,GACD,CAAC,SAAS,CAAC,GACT,CAAC,GACD,CAAC,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/validate.d.ts

@@ -12,10 +12,12 @@ import type { Schema } from './schema.js';
  * - '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

package/dist/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,QAAQ,GAAI,QAAQ,MAAM,GAAG,SAAS,EAAE,OAAO,OAAO,KAAG,OAwDrE,CAAA"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,QAAQ,GAAI,QAAQ,MAAM,GAAG,SAAS,EAAE,OAAO,OAAO,KAAG,OAqErE,CAAA"}

package/dist/validate.js

@@ -12,10 +12,12 @@ import { isObject } from './helpers/is-object.js';
  * - '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
@@ -69,9 +71,22 @@ export const validate = (schema, value) => {
         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;
     }

package/package.json

@@ -15,7 +15,7 @@
     "coerce",
     "scalar"
   ],
-  "version": "0.1.0",
+  "version": "0.2.0",
   "engines": {
     "node": ">=20"
   },

package/src/coerce.test.ts

@@ -6,6 +6,7 @@ import {
   array,
   boolean,
   evaluate,
+  intersection,
   lazy,
   literal,
   notDefined,
@@ -417,6 +418,15 @@ describe('object', () => {
       y: 2,
     })
   })
+  it('omits optional properties when the value is undefined', () => {
+    const T = object({
+      id: number(),
+      name: optional(string()),
+    })
+    expect(coerce(T, { id: 1 })).toEqual({ id: 1 })
+    expect(coerce(T, { id: 1, name: undefined })).toEqual({ id: 1 })
+    expect(coerce(T, { id: 1, name: 'x' })).toEqual({ id: 1, name: 'x' })
+  })
 })
 
 describe('record', () => {
@@ -918,6 +928,63 @@ describe('union', () => {
       $ref: 'https://example.com/schema',
     })
   })
+
+  it('picks the branch whose type discriminator matches a union of literals', () => {
+    const T = union([
+      object({
+        type: literal('a'),
+        a: string(),
+      }),
+      object({
+        type: union([literal('b'), literal('c')]),
+        b: string(),
+      }),
+    ])
+    expect(coerce(T, { type: 'a' })).toEqual({ type: 'a', a: '' })
+    expect(coerce(T, { type: 'b' })).toEqual({ type: 'b', b: '' })
+    expect(coerce(T, { type: 'c' })).toEqual({ type: 'c', b: '' })
+  })
+})
+
+describe('intersection', () => {
+  const T = intersection([
+    object({
+      a: number(),
+      b: number(),
+    }),
+    object({
+      c: string(),
+      d: string(),
+    }),
+  ])
+  it('merges coerced properties from each object schema', () => {
+    const result = coerce(T, { a: 1, b: 2, c: 'x', d: 'y' })
+    expect(result).toEqual({ a: 1, b: 2, c: 'x', d: 'y' })
+  })
+  it('fills missing keys per branch from the same input value', () => {
+    const result = coerce(T, { a: 'nope', c: 123 })
+    expect(result).toEqual({ a: 0, b: 0, c: '', d: '' })
+  })
+  it('later branch wins on overlapping keys', () => {
+    const overlap = intersection([object({ x: number() }), object({ x: string() })])
+    const result = coerce(overlap, { x: 1 })
+    expect(result).toEqual({ x: '' })
+  })
+  it('wins in a union when every member validates and summed score beats narrower members', () => {
+    const A = object({ type: literal('A'), onlyA: number() })
+    const B = object({ type: literal('B'), onlyB: string() })
+    const both = intersection([
+      object({ type: literal('A'), shared: number() }),
+      object({ shared: number(), extra: string() }),
+    ])
+    const T = union([A, B, both])
+    // Intersection merges only its declared keys; it outscores A here because both sub-objects validate.
+    expect(coerce(T, { type: 'A', onlyA: 1, shared: 2, extra: 'ok' })).toEqual({
+      type: 'A',
+      shared: 2,
+      extra: 'ok',
+    })
+  })
 })
 
 describe('notDefined', () => {

package/src/coerce.ts

@@ -3,6 +3,24 @@ import type { Schema } from './schema'
 import type { Static } from './types'
 import { validate } from './validate'
 
+/**
+ * True when this property schema is only used to discriminate union branches
+ * (single literal, or a union of literals). No presence bonus when the value
+ * does not match — avoids ties like `type: literal('a')` vs `type: union([lit('b'), lit('c')])`.
+ */
+const isDiscriminatorProperty = (schema: Schema): boolean => {
+  if (schema.type === 'optional') {
+    return isDiscriminatorProperty(schema.schema)
+  }
+  if (schema.type === 'literal') {
+    return true
+  }
+  if (schema.type === 'union') {
+    return schema.schemas.length > 0 && schema.schemas.every(isDiscriminatorProperty)
+  }
+  return false
+}
+
 /**
  * Computes a "score" indicating how well a value matches a schema,
  * used for picking the best branch in union coercion.
@@ -17,16 +35,23 @@ const scoreUnion = (schema: Schema, value: unknown): number => {
       return 0
     }
 
-    // For each key in the schema's properties:
-    // - +10 if the value matches an explicit literal for the key.
-    // - +1 if the property exists (not literal match).
+    // Missing keys contribute 0 (including optional keys — matches prior union heuristics).
+    // Discriminator properties (`literal` or `union` of literals): recurse with scoreUnion;
+    // matching values get a high weight (×10) so `type: literal('A')` beats unrelated fields
+    // on another branch; mismatches score 0 (no "key present" tie-break).
+    // Other properties: scoreUnion plus +1 when the value fails validation so `{ a: null }`
+    // can still prefer the branch that declares `a`.
     return Object.keys(schema.properties).reduce<number>((acc, key) => {
-      const exists = key in value
-      const isLiteralMatch = schema.properties[key].type === 'literal' && value[key] === schema.properties[key].value
-      if (isLiteralMatch) {
-        return acc + 10
+      if (!(key in value)) {
+        return acc
       }
-      return acc + (exists ? 1 : 0)
+      const propSchema = schema.properties[key]
+      const raw = value[key as keyof typeof value]
+      const base = scoreUnion(propSchema, raw)
+      if (isDiscriminatorProperty(propSchema)) {
+        return acc + (base > 0 ? base * 10 : 0)
+      }
+      return acc + (base > 0 ? base : 1)
     }, 0)
   }
   if (schema.type === 'array') {
@@ -37,10 +62,19 @@ const scoreUnion = (schema: Schema, value: unknown): number => {
     // TODO: implement smarter scoring for records (just a placeholder for now)
     return isObject(value) ? 1 : 0
   }
+  if (schema.type === 'optional') {
+    return value === undefined ? 1 : scoreUnion(schema.schema, value)
+  }
   if (schema.type === 'union') {
     // For a union, use the highest score among all sub-schemas
     return Math.max(...schema.schemas.map((schema) => scoreUnion(schema, value)))
   }
+  if (schema.type === 'intersection') {
+    if (schema.schemas.length === 0) {
+      return 1
+    }
+    return schema.schemas.reduce((acc, sub) => acc + scoreUnion(sub, value), 0)
+  }
 
   if (schema.type === 'lazy') {
     // For a lazy schema, evaluate the inner schema and recurse
@@ -122,6 +156,12 @@ export const coerce = <S extends Schema>(
   if (schema.type === 'notDefined') {
     return undefined as unknown as Static<S>
   }
+  if (schema.type === 'optional') {
+    if (value === undefined) {
+      return undefined as unknown as Static<S>
+    }
+    return coerce(schema.schema, value, cache)
+  }
   if (schema.type === 'array') {
     if (!Array.isArray(value)) {
       return [] as unknown as Static<S>
@@ -139,9 +179,16 @@ export const coerce = <S extends Schema>(
   if (schema.type === 'object') {
     const keys = Object.keys(schema.properties)
     const target = isObject(value) ? value : null
-    return Object.fromEntries(
-      keys.map((key) => [key, coerce(schema.properties[key], target?.[key], cache)]),
-    ) as unknown as Static<S>
+    const entries: [string, unknown][] = []
+    for (const key of keys) {
+      const propSchema = schema.properties[key]
+      const raw = target?.[key as keyof typeof target]
+      if (propSchema.type === 'optional' && raw === undefined) {
+        continue
+      }
+      entries.push([key, coerce(propSchema, raw, cache)])
+    }
+    return Object.fromEntries(entries) as unknown as Static<S>
   }
   if (schema.type === 'union') {
     const branch = schema.schemas.reduce(
@@ -154,6 +201,12 @@ export const coerce = <S extends Schema>(
     // We need some way to pick one of the union values
     return coerce(branch.schema, value, cache)
   }
+  if (schema.type === 'intersection') {
+    return schema.schemas.reduce<Record<string, unknown>>(
+      (acc, subSchema) => Object.assign(acc, coerce(subSchema, value, cache) as Record<string, unknown>),
+      {},
+    ) as unknown as Static<S>
+  }
   if (schema.type === 'literal') {
     return schema.value
   }

package/src/index.ts

@@ -1,10 +1,26 @@
 export { coerce } from './coerce'
 export {
+  type AnySchema,
+  type ArraySchema,
+  type BooleanSchema,
+  type EvaluateSchema,
+  type IntersectionSchema,
+  type LazySchema,
+  type LiteralSchema,
+  type NotDefinedSchema,
+  type NullableSchema,
+  type NumberSchema,
+  type ObjectSchema,
+  type OptionalSchema,
+  type RecordSchema,
   type Schema,
+  type StringSchema,
+  type UnionSchema,
   any,
   array,
   boolean,
   evaluate,
+  intersection,
   lazy,
   literal,
   notDefined,
@@ -16,5 +32,6 @@ export {
   string,
   union,
 } from './schema'
+export { type GenerateTypesOptions, generateTypes } from './typegen'
 export type { Static } from './types'
 export { validate } from './validate'

package/src/schema.ts

@@ -1,63 +1,89 @@
+/**
+ * Optional metadata for type generation and documentation.
+ * - typeName: Used as the exported TypeScript type name if valid.
+ * - typeComment: Adds a JSDoc comment to the generated type declaration.
+ */
+type Documentation = Partial<{
+  /** Adds a JSDoc comment to the generated type declaration. */
+  typeComment: string
+  /** Used as the exported TypeScript type name if valid. */
+  typeName: string
+}>
+
 /** Schema for finite numeric values. {@link Static} resolves to `number`. */
 export type NumberSchema = {
   type: 'number'
-}
+} & Documentation
 
 /** Schema for string values. {@link Static} resolves to `string`. */
 export type StringSchema = {
   type: 'string'
-}
+} & Documentation
 
 /** Schema for boolean values. {@link Static} resolves to `boolean`. */
 export type BooleanSchema = {
   type: 'boolean'
-}
+} & Documentation
 
 /** Schema for `null`. {@link Static} resolves to `null`. */
 export type NullableSchema = {
   type: 'nullable'
-}
+} & Documentation
 
 /** Schema for a missing or omitted value. {@link Static} resolves to `undefined`. */
 export type NotDefinedSchema = {
   type: 'notDefined'
-}
+} & Documentation
 
 /** Schema that accepts any value without narrowing. {@link Static} resolves to `any`. */
 export type AnySchema = {
   type: 'any'
-}
+} & Documentation
 
 /** Schema for homogeneous lists. {@link Static} resolves to an array of the item static type. */
 export type ArraySchema<Item extends Schema> = {
   type: 'array'
   items: Item
-}
+} & Documentation
 
 /** Schema for key-value maps with uniform value shape. Keys are constrained to string or number schemas. */
 export type RecordSchema<Key extends StringSchema | NumberSchema | AnySchema, Value extends Schema> = {
   type: 'record'
   key: Key
   value: Value
-}
+} & Documentation
 
 /** Schema for objects with a fixed set of named properties, each with its own schema. */
 export type ObjectSchema<Properties extends Record<string, Schema>> = {
   type: 'object'
   properties: Properties
-}
+} & Documentation
 
 /** Schema that matches if any member schema matches (discriminated union when literals or object tags differ). */
 export type UnionSchema<Schemas extends Schema[]> = {
   type: 'union'
   schemas: Schemas
-}
+} & Documentation
+
+/**
+ * Schema that accepts `undefined` or a value matching the inner schema.
+ * In {@link Static} and type generation, object properties use `key?:` instead of `T | undefined`.
+ */
+export type OptionalSchema<S extends Schema> = {
+  type: 'optional'
+  schema: S
+} & Documentation
+
+export type IntersectionSchema<Schemas extends readonly ObjectSchema<any>[]> = {
+  type: 'intersection'
+  schemas: Schemas
+} & Documentation
 
 /** Schema for a single exact constant (string, number, boolean, or bigint). {@link Static} is that literal type. */
 export type LiteralSchema<T extends string | number | boolean | bigint> = {
   type: 'literal'
   value: T
-}
+} & Documentation
 
 /**
  * Schema for self-referential or recursive types (such as trees or linked lists).
@@ -90,59 +116,100 @@ export type Schema =
   | RecordSchema<any, any>
   | ObjectSchema<Record<string, any>>
   | UnionSchema<any[]>
+  | OptionalSchema<any>
+  | IntersectionSchema<readonly ObjectSchema<any>[]>
   | LiteralSchema<any>
   | LazySchema<any>
   | EvaluateSchema<any>
 
-const number = (): NumberSchema => ({
+const number = (options?: Documentation): NumberSchema => ({
   type: 'number',
+  typeName: options?.typeName,
+  typeComment: options?.typeComment,
 })
 
-const string = (): StringSchema => ({
+const string = (options?: Documentation): StringSchema => ({
   type: 'string',
+  typeName: options?.typeName,
+  typeComment: options?.typeComment,
 })
 
-const boolean = (): BooleanSchema => ({
+const boolean = (options?: Documentation): BooleanSchema => ({
   type: 'boolean',
+  typeName: options?.typeName,
+  typeComment: options?.typeComment,
 })
 
-const nullable = (): NullableSchema => ({
+const nullable = (options?: Documentation): NullableSchema => ({
   type: 'nullable',
+  typeName: options?.typeName,
+  typeComment: options?.typeComment,
 })
 
-const notDefined = (): NotDefinedSchema => ({
+const notDefined = (options?: Documentation): NotDefinedSchema => ({
   type: 'notDefined',
+  typeName: options?.typeName,
+  typeComment: options?.typeComment,
 })
 
-const any = (): AnySchema => ({
+const any = (options?: Documentation): AnySchema => ({
   type: 'any',
+  typeName: options?.typeName,
+  typeComment: options?.typeComment,
 })
 
-const array = <Item extends Schema>(items: Item): ArraySchema<Item> => ({
+const array = <Item extends Schema>(items: Item, options?: Documentation): ArraySchema<Item> => ({
   type: 'array',
   items,
+  typeName: options?.typeName,
+  typeComment: options?.typeComment,
 })
 
 const record = <Key extends StringSchema | AnySchema, Value extends Schema>(
   key: Key,
   value: Value,
+  options?: Documentation,
 ): RecordSchema<Key, Value> => ({
   type: 'record',
   key,
   value,
+  typeName: options?.typeName,
+  typeComment: options?.typeComment,
 })
 
-const object = <Properties extends Record<string, Schema>>(properties: Properties): ObjectSchema<Properties> => ({
+const object = <Properties extends Record<string, Schema>>(
+  properties: Properties,
+  options?: Documentation,
+): ObjectSchema<Properties> => ({
   type: 'object',
   properties,
+  typeName: options?.typeName,
+  typeComment: options?.typeComment,
 })
 
-const union = <Schemas extends Schema[]>(schemas: Schemas): UnionSchema<Schemas> => ({
+const union = <Schemas extends Schema[]>(schemas: Schemas, options?: Documentation): UnionSchema<Schemas> => ({
   type: 'union',
   schemas,
+  typeName: options?.typeName,
+  typeComment: options?.typeComment,
+})
+
+const intersection = <Schemas extends readonly ObjectSchema<any>[]>(
+  schemas: Schemas,
+  options?: Documentation,
+): IntersectionSchema<Schemas> => ({
+  type: 'intersection',
+  schemas,
+  typeName: options?.typeName,
+  typeComment: options?.typeComment,
 })
 
-const optional = <S extends Schema>(schema: S) => union([schema, notDefined()])
+const optional = <S extends Schema>(schema: S, options?: Documentation): OptionalSchema<S> => ({
+  type: 'optional',
+  schema,
+  typeName: options?.typeName,
+  typeComment: options?.typeComment,
+})
 
 const literal = <Value extends string | number | boolean | bigint>(value: Value): LiteralSchema<Value> => ({
   type: 'literal',
@@ -171,6 +238,7 @@ export {
   record,
   object,
   union,
+  intersection,
   optional,
   literal,
   lazy,