@scalar/validation 0.1.0

package/src/coerce.ts

@@ -0,0 +1,171 @@
+import { isObject } from './helpers/is-object'
+import type { Schema } from './schema'
+import type { Static } from './types'
+import { validate } from './validate'
+
+/**
+ * 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
+    }
+
+    // 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).
+    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
+      }
+      return acc + (exists ? 1 : 0)
+    }, 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 === '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 === '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 === '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
+    return Object.fromEntries(
+      keys.map((key) => [key, coerce(schema.properties[key], target?.[key], cache)]),
+    ) 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 === '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

@@ -0,0 +1,168 @@
+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

@@ -0,0 +1,31 @@
+/**
+ * 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

@@ -0,0 +1,20 @@
+export { coerce } from './coerce'
+export {
+  type Schema,
+  any,
+  array,
+  boolean,
+  evaluate,
+  lazy,
+  literal,
+  notDefined,
+  nullable,
+  number,
+  object,
+  optional,
+  record,
+  string,
+  union,
+} from './schema'
+export type { Static } from './types'
+export { validate } from './validate'

package/src/schema.ts

@@ -0,0 +1,178 @@
+/** Schema for finite numeric values. {@link Static} resolves to `number`. */
+export type NumberSchema = {
+  type: 'number'
+}
+
+/** Schema for string values. {@link Static} resolves to `string`. */
+export type StringSchema = {
+  type: 'string'
+}
+
+/** Schema for boolean values. {@link Static} resolves to `boolean`. */
+export type BooleanSchema = {
+  type: 'boolean'
+}
+
+/** Schema for `null`. {@link Static} resolves to `null`. */
+export type NullableSchema = {
+  type: 'nullable'
+}
+
+/** Schema for a missing or omitted value. {@link Static} resolves to `undefined`. */
+export type NotDefinedSchema = {
+  type: 'notDefined'
+}
+
+/** Schema that accepts any value without narrowing. {@link Static} resolves to `any`. */
+export type AnySchema = {
+  type: 'any'
+}
+
+/** 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
+}
+
+/** 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
+}
+
+/** 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
+}
+
+/** 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
+}
+
+/** 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
+}
+
+/**
+ * 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[]>
+  | LiteralSchema<any>
+  | LazySchema<any>
+  | EvaluateSchema<any>
+
+const number = (): NumberSchema => ({
+  type: 'number',
+})
+
+const string = (): StringSchema => ({
+  type: 'string',
+})
+
+const boolean = (): BooleanSchema => ({
+  type: 'boolean',
+})
+
+const nullable = (): NullableSchema => ({
+  type: 'nullable',
+})
+
+const notDefined = (): NotDefinedSchema => ({
+  type: 'notDefined',
+})
+
+const any = (): AnySchema => ({
+  type: 'any',
+})
+
+const array = <Item extends Schema>(items: Item): ArraySchema<Item> => ({
+  type: 'array',
+  items,
+})
+
+const record = <Key extends StringSchema | AnySchema, Value extends Schema>(
+  key: Key,
+  value: Value,
+): RecordSchema<Key, Value> => ({
+  type: 'record',
+  key,
+  value,
+})
+
+const object = <Properties extends Record<string, Schema>>(properties: Properties): ObjectSchema<Properties> => ({
+  type: 'object',
+  properties,
+})
+
+const union = <Schemas extends Schema[]>(schemas: Schemas): UnionSchema<Schemas> => ({
+  type: 'union',
+  schemas,
+})
+
+const optional = <S extends Schema>(schema: S) => union([schema, notDefined()])
+
+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,
+  optional,
+  literal,
+  lazy,
+  evaluate,
+}

package/src/types.ts

@@ -0,0 +1,72 @@
+import type {
+  AnySchema,
+  ArraySchema,
+  BooleanSchema,
+  EvaluateSchema,
+  LazySchema,
+  LiteralSchema,
+  NotDefinedSchema,
+  NullableSchema,
+  NumberSchema,
+  ObjectSchema,
+  RecordSchema,
+  StringSchema,
+  UnionSchema,
+} from './schema'
+
+// Export Static type with depth limit to prevent infinite recursion
+export type Static<T> = _Static<T, 10>
+
+// Internal type with depth counter
+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>
+                      ? { [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
+
+// Helper type to decrement depth counter
+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