@scalar/validation 0.2.0 → 0.3.1

package/src/coerce.ts

@@ -1,224 +0,0 @@
-import { isObject } from './helpers/is-object'
-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.
- *
- * Higher score means a closer match. Literals and matching object shapes
- * are weighted more heavily. Objects are scored by shape/literals;
- * arrays/records by structural type; primitives by validation; unions try all branches.
- */
-const scoreUnion = (schema: Schema, value: unknown): number => {
-  if (schema.type === 'object') {
-    if (!isObject(value)) {
-      return 0
-    }
-
-    // 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) => {
-      if (!(key in value)) {
-        return acc
-      }
-      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') {
-    // Score 1 if value is an array, otherwise 0
-    return Array.isArray(value) ? 1 : 0
-  }
-  if (schema.type === 'record') {
-    // 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
-    return scoreUnion(schema.schema(), value)
-  }
-
-  if (schema.type === 'evaluate') {
-    // For an evaluate schema, evaluate the expression and recurse
-    return scoreUnion(schema.schema, schema.expression(value))
-  }
-
-  // For primitives and any other type, return 1 if valid, otherwise 0
-  return validate(schema, value) ? 1 : 0
-}
-
-/**
- * Coerces an unknown value toward the static type implied by `schema`. Values that
- * pass {@link validate} for that branch are kept; otherwise primitives default to
- * `0`, `''`, or `false`, and arrays, records, and objects are built recursively.
- * Unions pick the best-matching branch; `evaluate` runs `expression` before the inner schema.
- *
- * @example
- * ```ts
- * import { coerce, number, object, string } from '@scalar/validation'
- *
- * coerce(number(), 42) // 42
- * coerce(number(), 'nope') // 0 — invalid number uses default
- * coerce(object({ id: number(), name: string() }), { id: '1', name: 'Ada' }) // { id: 0, name: 'Ada' }
- * ```
- *
- * The optional `cache` argument tracks visited object–schema pairs to stop infinite recursion
- * on cyclic graphs; callers normally omit it.
- */
-export const coerce = <S extends Schema>(
-  schema: S,
-  value: unknown,
-  cache: WeakMap<object, Set<Schema>> = new WeakMap(),
-): Static<S> => {
-  // Prevent infinite recursion
-  if (isObject(value) && cache.get(value)?.has(schema)) {
-    return value as Static<S>
-  }
-  // Track visited schemas to prevent infinite recursion
-  if (isObject(value)) {
-    const schemas = cache.get(value) || new Set<Schema>()
-    schemas.add(schema)
-    cache.set(value, schemas)
-  }
-
-  // If no schema is provided, return the value as is
-  if (!schema) {
-    return value as Static<S>
-  }
-
-  if (schema.type === 'any') {
-    return value as unknown as Static<S>
-  }
-  if (schema.type === 'number') {
-    if (validate(schema, value)) {
-      return value as Static<S>
-    }
-    return 0 as Static<S>
-  }
-  if (schema.type === 'string') {
-    if (validate(schema, value)) {
-      return value as unknown as Static<S>
-    }
-    return '' as unknown as Static<S>
-  }
-  if (schema.type === 'boolean') {
-    if (validate(schema, value)) {
-      return value as unknown as Static<S>
-    }
-    return false as unknown as Static<S>
-  }
-  if (schema.type === 'nullable') {
-    return null as unknown as Static<S>
-  }
-  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>
-    }
-    return value.map((item) => coerce(schema.items, item, cache)) as unknown as Static<S>
-  }
-  if (schema.type === 'record') {
-    if (!isObject(value)) {
-      return {} as unknown as Static<S>
-    }
-    return Object.fromEntries(
-      Object.entries(value).map(([key, value]) => [key, coerce(schema.value, value, cache)]),
-    ) as unknown as Static<S>
-  }
-  if (schema.type === 'object') {
-    const keys = Object.keys(schema.properties)
-    const target = isObject(value) ? value : null
-    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(
-      (acc, schema) => {
-        const score = scoreUnion(schema, value)
-        return score > acc.score ? { schema, score } : acc
-      },
-      { schema: schema.schemas[0], score: 0 },
-    )
-    // 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
-  }
-  if (schema.type === 'lazy') {
-    return coerce(schema.schema(), value, cache)
-  }
-  if (schema.type === 'evaluate') {
-    return coerce(schema.schema, schema.expression(value), cache)
-  }
-
-  // We need to assert here that schema has the type never so we know we handle all cases
-  const _exhaustive: never = schema
-  console.warn('Unknown schema type:', _exhaustive)
-  return value as unknown as Static<S>
-}

package/src/helpers/is-object.test.ts

@@ -1,168 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { isObject } from './is-object'
-
-describe('isObject', () => {
-  it('returns true for plain empty objects', () => {
-    expect(isObject({})).toBe(true)
-  })
-
-  it('returns true for objects with properties', () => {
-    expect(isObject({ a: 1 })).toBe(true)
-    expect(isObject({ a: 1, b: 2, c: 3 })).toBe(true)
-  })
-
-  it('returns true for objects with different value types', () => {
-    const obj = {
-      string: 'hello',
-      number: 42,
-      boolean: true,
-      null: null,
-      undefined: undefined,
-      array: [],
-      nested: { x: 1 },
-    }
-    expect(isObject(obj)).toBe(true)
-  })
-
-  it('returns true for objects created with Object.create(null)', () => {
-    const obj = Object.create(null)
-    expect(isObject(obj)).toBe(true)
-  })
-
-  it('returns false for Date objects', () => {
-    expect(isObject(new Date())).toBe(false)
-  })
-
-  it('returns false for RegExp objects', () => {
-    expect(isObject(/test/)).toBe(false)
-    expect(isObject(new RegExp('test'))).toBe(false)
-  })
-
-  it('returns false for Error objects', () => {
-    expect(isObject(new Error('test'))).toBe(false)
-  })
-
-  it('returns false for Map objects', () => {
-    expect(isObject(new Map())).toBe(false)
-  })
-
-  it('returns false for Set objects', () => {
-    expect(isObject(new Set())).toBe(false)
-  })
-
-  it('returns false for WeakMap objects', () => {
-    expect(isObject(new WeakMap())).toBe(false)
-  })
-
-  it('returns false for WeakSet objects', () => {
-    expect(isObject(new WeakSet())).toBe(false)
-  })
-
-  it('returns false for Promise objects', () => {
-    expect(isObject(Promise.resolve())).toBe(false)
-  })
-
-  it('returns false for arrays', () => {
-    expect(isObject([])).toBe(false)
-    expect(isObject([1, 2, 3])).toBe(false)
-    expect(isObject(new Array(10))).toBe(false)
-  })
-
-  it('returns false for null', () => {
-    expect(isObject(null)).toBe(false)
-  })
-
-  it('returns false for undefined', () => {
-    expect(isObject(undefined)).toBe(false)
-  })
-
-  it('returns false for numbers', () => {
-    expect(isObject(0)).toBe(false)
-    expect(isObject(123)).toBe(false)
-    expect(isObject(-456)).toBe(false)
-    expect(isObject(3.14)).toBe(false)
-    expect(isObject(Number.NaN)).toBe(false)
-    expect(isObject(Number.POSITIVE_INFINITY)).toBe(false)
-    expect(isObject(Number.NEGATIVE_INFINITY)).toBe(false)
-  })
-
-  it('returns false for strings', () => {
-    expect(isObject('')).toBe(false)
-    expect(isObject('string')).toBe(false)
-    expect(isObject('hello world')).toBe(false)
-  })
-
-  it('returns false for booleans', () => {
-    expect(isObject(true)).toBe(false)
-    expect(isObject(false)).toBe(false)
-  })
-
-  it('returns false for functions', () => {
-    expect(
-      isObject(() => {
-        return
-      }),
-    ).toBe(false)
-    expect(
-      isObject(() => {
-        return
-      }),
-    ).toBe(false)
-    expect(
-      isObject(async () => {
-        return await Promise.resolve()
-      }),
-    ).toBe(false)
-  })
-
-  it('returns false for symbols', () => {
-    expect(isObject(Symbol('test'))).toBe(false)
-    expect(isObject(Symbol.for('test'))).toBe(false)
-  })
-
-  it('returns false for BigInt values', () => {
-    expect(isObject(BigInt(123))).toBe(false)
-    expect(isObject(123n)).toBe(false)
-  })
-
-  it('works correctly as a type guard', () => {
-    const value: unknown = { a: 1, b: 2 }
-
-    if (isObject(value)) {
-      // TypeScript should narrow the type to Record<string, unknown>
-      const keys = Object.keys(value)
-      expect(keys).toEqual(['a', 'b'])
-      expect(value.a).toBe(1)
-    }
-  })
-
-  it('handles objects with nested structures', () => {
-    const obj = {
-      nested: {
-        deeper: {
-          value: 'test',
-        },
-      },
-    }
-    expect(isObject(obj)).toBe(true)
-  })
-
-  it('returns false for class instances', () => {
-    class CustomClass {
-      prop = 'value'
-    }
-    const instance = new CustomClass()
-    expect(isObject(instance)).toBe(false)
-  })
-
-  it('handles frozen objects', () => {
-    const obj = Object.freeze({ a: 1 })
-    expect(isObject(obj)).toBe(true)
-  })
-
-  it('handles sealed objects', () => {
-    const obj = Object.seal({ a: 1 })
-    expect(isObject(obj)).toBe(true)
-  })
-})

package/src/helpers/is-object.ts

@@ -1,31 +0,0 @@
-/**
- * Stolen from |@scalar/helpers/object/is-object.ts|
- * so we don't have to depend on it.
- */
-
-/**
- * Returns true if the provided value is a record object
- * (i.e. not null, not an array, and has an actual object as the prototype).
- *
- * Differs from the previous isObject in that it returns false for Date,
- * RegExp, Error, Map, Set, WeakMap, WeakSet, Promise, and other non-plain objects.
- *
- * Examples:
- *   isObject({})                  // true
- *   isObject({ a: 1 })            // true
- *   isObject([])                  // false (Array)
- *   isObject(null)                // false
- *   isObject(123)                 // false
- *   isObject('string')            // false
- *   isObject(new Error('test'))   // false
- *   isObject(new Date())          // false
- *   isObject(Object.create(null)) // true
- */
-export const isObject = (value: unknown): value is Record<string | number | symbol, unknown> => {
-  if (value === null || typeof value !== 'object') {
-    return false
-  }
-
-  const proto = Object.getPrototypeOf(value)
-  return proto === Object.prototype || proto === null
-}

package/src/index.ts

@@ -1,37 +0,0 @@
-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,
-  nullable,
-  number,
-  object,
-  optional,
-  record,
-  string,
-  union,
-} from './schema'
-export { type GenerateTypesOptions, generateTypes } from './typegen'
-export type { Static } from './types'
-export { validate } from './validate'

package/src/schema.ts

@@ -1,246 +0,0 @@
-/**
- * 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).
- * The `schema` property is a factory function returning a schema instance, allowing
- * references to itself without causing circular definition errors at type-level.
- */
-export type LazySchema<S extends () => Schema> = {
-  type: 'lazy'
-  schema: S
-}
-
-/**
- * Schema that runs a coercion or transform (`expression`) on the input, then validates with the inner schema.
- * Use when parsing needs a preprocessing step before the usual rules apply.
- */
-export type EvaluateSchema<S extends Schema> = {
-  type: 'evaluate'
-  expression: (value: unknown) => unknown
-  schema: S
-}
-
-export type Schema =
-  | NumberSchema
-  | StringSchema
-  | BooleanSchema
-  | NullableSchema
-  | NotDefinedSchema
-  | AnySchema
-  | ArraySchema<any>
-  | RecordSchema<any, any>
-  | ObjectSchema<Record<string, any>>
-  | UnionSchema<any[]>
-  | OptionalSchema<any>
-  | IntersectionSchema<readonly ObjectSchema<any>[]>
-  | LiteralSchema<any>
-  | LazySchema<any>
-  | EvaluateSchema<any>
-
-const number = (options?: Documentation): NumberSchema => ({
-  type: 'number',
-  typeName: options?.typeName,
-  typeComment: options?.typeComment,
-})
-
-const string = (options?: Documentation): StringSchema => ({
-  type: 'string',
-  typeName: options?.typeName,
-  typeComment: options?.typeComment,
-})
-
-const boolean = (options?: Documentation): BooleanSchema => ({
-  type: 'boolean',
-  typeName: options?.typeName,
-  typeComment: options?.typeComment,
-})
-
-const nullable = (options?: Documentation): NullableSchema => ({
-  type: 'nullable',
-  typeName: options?.typeName,
-  typeComment: options?.typeComment,
-})
-
-const notDefined = (options?: Documentation): NotDefinedSchema => ({
-  type: 'notDefined',
-  typeName: options?.typeName,
-  typeComment: options?.typeComment,
-})
-
-const any = (options?: Documentation): AnySchema => ({
-  type: 'any',
-  typeName: options?.typeName,
-  typeComment: options?.typeComment,
-})
-
-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,
-  options?: Documentation,
-): ObjectSchema<Properties> => ({
-  type: 'object',
-  properties,
-  typeName: options?.typeName,
-  typeComment: options?.typeComment,
-})
-
-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, 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',
-  value,
-})
-
-const lazy = <S extends () => Schema>(schema: S): LazySchema<S> => ({
-  type: 'lazy',
-  schema,
-})
-
-const evaluate = <S extends Schema>(expression: (value: unknown) => unknown, schema: S): EvaluateSchema<S> => ({
-  type: 'evaluate',
-  expression,
-  schema,
-})
-
-export {
-  number,
-  string,
-  boolean,
-  nullable,
-  notDefined,
-  any,
-  array,
-  record,
-  object,
-  union,
-  intersection,
-  optional,
-  literal,
-  lazy,
-  evaluate,
-}