Aller au contenu principal

k

const k: object

Kanon namespace object providing a single entry point for all schemas.

Similar to Zod's z object.

Type Declaration​

string(): (message?) => StringConstraint​

Creates a string schema.

String schema with 0 overhead after tsup + Terser build.

Usage identical to before:

  • string()
  • string("Custom error")
  • string().minLength(5)
  • string().email()

message?: string — Custom error message (optional).
Returns: StringConstraint — StringConstraint with all constraints.

Since​

2.0.0

number(): (message?) => NumberConstraint​

Creates a number schema.

Number schema with 0 overhead after tsup + Terser build.

Usage identical to before:

  • number()
  • number("Custom error")
  • number().min(5)
  • number().positive()

message?: string — Custom error message (optional).
Returns: NumberConstraint — NumberConstraint with all constraints.

Since​

2.0.0

boolean(): (message?) => BooleanSchema​

Creates a boolean schema.

Boolean schema with 0 overhead after tsup + Terser build.

Usage identical to before:

  • boolean()
  • boolean("Custom error")

message?: string — Custom error message (optional).
Returns: BooleanSchema — BooleanSchema

Since​

2.0.0

date(): (message?) => DateConstraint​

Creates a Date schema.

Date schema with 0 overhead after tsup + Terser build.

Usage identical to before:

  • date()
  • date("Custom error")
  • date().min(new Date())
  • date().max(new Date())

message?: string — Custom error message (optional).
Returns: DateConstraint — DateConstraint with all constraints.

Since​

2.0.0

bigint(): (message?) => BigIntConstraint​

Creates a bigint schema.

BigInt schema with 0 overhead after tsup + Terser build.

Usage identical to before:

  • bigint()
  • bigint("Custom error")
  • bigint().min(5n)
  • bigint().positive()

message?: string — Custom error message (optional).
Returns: BigIntConstraint — BigIntSchema with all constraints.

Since​

2.0.0

symbol(): (message?) => SymbolSchema​

Creates a symbol schema.

Symbol schema - validates symbol values.

message?: string — Custom error message (optional).
Returns: SymbolSchema — SymbolSchema

Since​

2.0.0

int(): (message?) => IntSchema​

Creates an integer schema.

Integer schema - validates integer numbers.

message?: string — Custom error message (optional).
Returns: IntSchema — IntSchema

Since​

2.0.0

null(): (message?) => NullSchema​

Creates a null schema.

Null schema with 0 overhead after tsup + Terser build.

Usage identical to before:

  • null_()
  • null_("Custom error")

message?: string — Custom error message (optional).
Returns: NullSchema — NullSchema

Since​

2.0.0

undefined(): (message?) => UndefinedSchema​

Creates an undefined schema.

Undefined schema with 0 overhead after tsup + Terser build.

Usage identical to before:

  • undefined_()
  • undefined_("Custom error")

message?: string — Custom error message (optional).
Returns: UndefinedSchema — UndefinedSchema

Since​

2.0.0

void(): (message?) => VoidSchema​

Creates a void schema.

Void schema with 0 overhead after tsup + Terser build.

Usage identical to before:

  • void_()
  • void_("Custom error")

The void type accepts only undefined - used for functions with no return value.

message?: string — Custom error message (optional).
Returns: VoidSchema — VoidSchema

Since​

2.0.0

never(): (message?) => NeverSchema​

Creates a never schema.

Never schema - always rejects any value.

Useful for impossible branches or dead code.

message?: string — Custom error message.
Returns: NeverSchema — NeverSchema that rejects any value

Since​

2.0.0

any(): (message?) => AnySchema​

Creates a schema accepting any value.

Any schema - accepts any value.

The any type accepts any value without validation. A custom message can be provided for API consistency and introspection, but it will never be used by the validator since any always accepts all values.

message?: string — Custom message (stored for API consistency and introspection, but never used by the validator since any always accepts all values)
Returns: AnySchema — AnySchema that accepts any value

Since​

2.0.0

unknown(): (message?) => UnknownSchema​

Creates a schema accepting unknown values.

Unknown schema - accepts any value (type-safe variant of any).

The unknown type accepts any value without validation. A custom message can be provided for API consistency and introspection, but it will never be used by the validator since unknown always accepts all values.

message?: string — Custom message (stored for API consistency and introspection, but never used by the validator since unknown always accepts all values)
Returns: UnknownSchema — UnknownSchema that accepts any value

Since​

2.0.0

literal(): <T>(value, message?) => LiteralSchema<T>​

Creates a literal schema for a specific value.

Literal schema - accepts only a specific value.

remarque

This is equivalent to object(entries).strict(). Use strictObject() to create a strict object directly, or object().strict() for method chaining.

Type Parameters​

T: T extends string | number | boolean​

value: T — The literal value to validate against.
message?: string — Custom error message.
Returns: LiteralSchema<T> — Schema that validates only this specific value.

Since​

2.0.0

enum(): <T>(values, message?) => EnumSchema<T[number]>​

Creates a string enum schema.

Enum schema - accepts only string enumeration values

Type Parameters​

T: T extends readonly [string, string]​

values: T — Array of allowed string values
message?: string — Custom error message
Returns: EnumSchema<T[number]> — Schema that validates only the string enum values

Since​

2.0.0

numberEnum(): <T>(values, message?) => EnumSchema<T[number]>​

Creates a number enum schema.

Number enum schema - enumeration of numbers

Type Parameters​

T: T extends readonly [number, number]​

values: T — Array of allowed number values
message?: string — Custom error message
Returns: EnumSchema<T[number]> — Schema that validates only the number enum values

Since​

2.0.0

booleanEnum(): <T>(values, message?) => EnumSchema<T[number]>​

Creates a boolean enum schema.

Boolean enum schema - enumeration of booleans

Type Parameters​

T: T extends readonly [boolean, boolean]​

values: T — Array of allowed boolean values
message?: string — Custom error message
Returns: EnumSchema<T[number]> — Schema that validates only the boolean enum values

Since​

2.0.0

mixedEnum(): <T>(values, message?) => EnumSchema<T[number]>​

Creates a mixed enum schema.

Mixed enum schema - enumeration of mixed types

Type Parameters​

T: T extends readonly [EnumValue, EnumValue]​

values: T — Array of allowed mixed values (string | number | boolean)
message?: string — Custom error message
Returns: EnumSchema<T[number]> — Schema that validates only the mixed enum values

Since​

2.0.0

nativeEnum(): <T>(enumObj, message?) => NativeEnumSchema<T[keyof T], T>​

Creates a schema from a TypeScript native enum.

NativeEnum schema - validates native TypeScript enums.

Supports string, number and mixed enums: - enum StringEnum { A = "a", B = "b" } - enum NumericEnum { A = 0, B = 1 } - enum MixedEnum { A = 0, B = "b" }

Type Parameters​

T: T extends Record<string, string | number>​

enumObj: T — TypeScript enum object.
message?: string — Custom error message.
Returns: NativeEnumSchema<T[keyof T], T> — Schema that validates native enum values.

Since​

2.0.0

object(): <T>(entries, message?) => ObjectConstraint<T>​

Creates an object schema from a shape.

Object schema with composition and constraints.

Type Parameters​

T: T extends Record<string, AnySchema>​

entries: T — Object entries schema definition.
message?: string — Custom error message (optional).
Returns: ObjectConstraint<T> — ObjectConstraint with all constraints.

Since​

2.0.0

strictObject(): <T>(entries, message?) => ObjectConstraint<T>​

Creates a strict object schema that rejects unknown keys.

Strict object schema - strictly validates defined properties.

Type Parameters​

T: T extends Record<string, AnySchema>​

entries: T — Object entries schema definition.
message?: string — Custom error message (optional).
Returns: ObjectConstraint<T> — ObjectConstraint with all constraints.

Since​

2.0.0

looseObject(): <T>(entries, message?) => ObjectConstraint<T>​

Creates a loose object schema that allows unknown keys.

Object schema with composition and constraints.

Type Parameters​

T: T extends Record<string, AnySchema>​

entries: T — Object entries schema definition.
message?: string — Custom error message (optional).
Returns: ObjectConstraint<T> — ObjectConstraint with all constraints.

Since​

2.0.0

array(): <ItemSchema>(item, message?) => ArrayConstraint<ItemSchema>​

Creates an array schema.

Array schema with composition and constraints.

Type Parameters​

ItemSchema: ItemSchema extends GenericSchema​

item: ItemSchema — Schema for array items.
message?: string — Custom error message (optional).
Returns: ArrayConstraint<ItemSchema> — ArrayConstraint with all constraints.

Since​

2.0.0

tuple(): <T>(schemas, message?) => TupleSchema<T>​

Creates a tuple schema from a list of schemas.

Tuple schema - validates an array with specific types at each position.

Type Parameters​

T: T extends readonly GenericSchema[]​

schemas: T — Array of schemas for each tuple position.
message?: string — Custom error message.
Returns: TupleSchema<T> — Schema that validates a tuple with the specified types.

Since​

2.0.0

tupleOf(): <S1, S2>(schema1, schema2, message?) => TupleSchema<readonly [S1, S2]>​

Creates a typed 2-element tuple.

Tuple schema with specific types for better ergonomics.

Type Parameters​

S1: S1 extends GenericSchema​
S2: S2 extends GenericSchema​

schema1: S1 — First schema.
schema2: S2 — Second schema.
message?: string — Custom error message (optional).
Returns: TupleSchema<readonly [S1, S2]> — TupleSchema with two elements.

Since​

2.0.0

tupleOf3(): <S1, S2, S3>(schema1, schema2, schema3, message?) => TupleSchema<readonly [S1, S2, S3]>​

Creates a typed 3-element tuple.

Tuple schema with three specific types.

Type Parameters​

S1: S1 extends GenericSchema​
S2: S2 extends GenericSchema​
S3: S3 extends GenericSchema​

schema1: S1 — First schema.
schema2: S2 — Second schema.
schema3: S3 — Third schema.
message?: string — Custom error message (optional).
Returns: TupleSchema<readonly [S1, S2, S3]> — TupleSchema with three elements.

Since​

2.0.0

tupleOf4(): <S1, S2, S3, S4>(schema1, schema2, schema3, schema4, message?) => TupleSchema<readonly [S1, S2, S3, S4]>​

Creates a typed 4-element tuple.

Tuple schema with four specific types.

Type Parameters​

S1: S1 extends GenericSchema​
S2: S2 extends GenericSchema​
S3: S3 extends GenericSchema​
S4: S4 extends GenericSchema​

schema1: S1 — First schema.
schema2: S2 — Second schema.
schema3: S3 — Third schema.
schema4: S4 — Fourth schema.
message?: string — Custom error message (optional).
Returns: TupleSchema<readonly [S1, S2, S3, S4]> — TupleSchema with four elements.

Since​

2.0.0

tupleWithRest(): <T, R>(schemas, restSchema, message?) => TupleWithRestSchema<T, R>​

Creates a tuple schema with a rest element.

Tuple schema with variable length (rest).

Type Parameters​

T: T extends readonly GenericSchema[]​
R: R extends GenericSchema​

schemas: T — Array of schemas for fixed tuple positions.
restSchema: R — Schema for rest elements.
message?: string — Custom error message (optional).
Returns: TupleWithRestSchema<T, R> — TupleWithRestSchema with variable length.

Since​

2.0.0

record(): <KeySchema, ValueSchema>(keySchema, valueSchema, message?) => RecordSchema<KeySchema, ValueSchema>​

Creates a record schema with key and value schemas.

Record schema - validates an object with typed keys and values.

Type Parameters​

KeySchema: KeySchema extends GenericSchema​
ValueSchema: ValueSchema extends GenericSchema​

keySchema: KeySchema — Schema to validate keys (must be Schema<string>).
valueSchema: ValueSchema — Schema to validate values.
message?: string — Custom error message.
Returns: RecordSchema<KeySchema, ValueSchema> — Schema that validates an object with typed keys/values.

Since​

2.0.0

map(): <KeySchema, ValueSchema>(keySchema, valueSchema, message?) => MapConstraint<KeySchema, ValueSchema>​

Creates a Map schema.

Map schema - validates a Map with typed keys and values.

Type Parameters​

KeySchema: KeySchema extends GenericSchema​
ValueSchema: ValueSchema extends GenericSchema​

keySchema: KeySchema — Schema to validate keys.
valueSchema: ValueSchema — Schema to validate values.
message?: string — Custom error message.
Returns: MapConstraint<KeySchema, ValueSchema> — Schema that validates a Map with typed keys/values and constraints.

Since​

2.0.0

set(): <ItemSchema>(itemSchema, message?) => SetConstraint<ItemSchema>​

Creates a Set schema.

Set schema - validates a Set with typed elements.

Type Parameters​

ItemSchema: ItemSchema extends GenericSchema​

itemSchema: ItemSchema — Schema to validate each item.
message?: string — Custom error message.
Returns: SetConstraint<ItemSchema> — Schema that validates a Set with typed items and constraints.

Since​

2.0.0

union(): <S1, S2>(schema1, schema2, message?) => UnionSchema<readonly [S1, S2]>​

Creates a union schema. Alias for unionOf.

Union schema with specific types for better ergonomics.

Type Parameters​

S1: S1 extends GenericSchema​
S2: S2 extends GenericSchema​

schema1: S1 — First schema.
schema2: S2 — Second schema.
message?: string — Custom error message (optional).
Returns: UnionSchema<readonly [S1, S2]> — UnionSchema with two schemas.

Since​

2.0.0

unionOf(): <S1, S2>(schema1, schema2, message?) => UnionSchema<readonly [S1, S2]>​

Creates a union of 2 schemas.

Union schema with specific types for better ergonomics.

Type Parameters​

S1: S1 extends GenericSchema​
S2: S2 extends GenericSchema​

schema1: S1 — First schema.
schema2: S2 — Second schema.
message?: string — Custom error message (optional).
Returns: UnionSchema<readonly [S1, S2]> — UnionSchema with two schemas.

Since​

2.0.0

unionOf3(): <S1, S2, S3>(schema1, schema2, schema3, message?) => UnionSchema<readonly [S1, S2, S3]>​

Creates a union of 3 schemas.

Union schema with three specific types.

Type Parameters​

S1: S1 extends GenericSchema​
S2: S2 extends GenericSchema​
S3: S3 extends GenericSchema​

schema1: S1 — First schema.
schema2: S2 — Second schema.
schema3: S3 — Third schema.
message?: string — Custom error message (optional).
Returns: UnionSchema<readonly [S1, S2, S3]> — UnionSchema with three schemas.

Since​

2.0.0

unionOf4(): <S1, S2, S3, S4>(schema1, schema2, schema3, schema4, message?) => UnionSchema<readonly [S1, S2, S3, S4]>​

Creates a union of 4 schemas.

Union schema with four specific types.

Type Parameters​

S1: S1 extends GenericSchema​
S2: S2 extends GenericSchema​
S3: S3 extends GenericSchema​
S4: S4 extends GenericSchema​

schema1: S1 — First schema.
schema2: S2 — Second schema.
schema3: S3 — Third schema.
schema4: S4 — Fourth schema.
message?: string — Custom error message (optional).
Returns: UnionSchema<readonly [S1, S2, S3, S4]> — UnionSchema with four schemas.

Since​

2.0.0

intersection(): <S1, S2>(schema1, schema2, message?) => IntersectionSchema<readonly [S1, S2]>​

Creates an intersection of 2 schemas.

Intersection schema - validates that the value satisfies multiple schemas.

Type Parameters​

S1: S1 extends GenericSchema​
S2: S2 extends GenericSchema​

schema1: S1 — First schema.
schema2: S2 — Second schema.
message?: string — Custom error message.
Returns: IntersectionSchema<readonly [S1, S2]> — Schema that validates the intersection of both schemas.

Since​

2.0.0

intersection3(): <S1, S2, S3>(schema1, schema2, schema3, message?) => IntersectionSchema<readonly [S1, S2, S3]>​

Creates an intersection of 3 schemas.

Intersection schema with 3 schemas.

Type Parameters​

S1: S1 extends GenericSchema​
S2: S2 extends GenericSchema​
S3: S3 extends GenericSchema​

schema1: S1 — First schema.
schema2: S2 — Second schema.
schema3: S3 — Third schema.
message?: string — Custom error message (optional).
Returns: IntersectionSchema<readonly [S1, S2, S3]> — IntersectionSchema with three schemas.

Since​

2.0.0

partial(): <T>(schema, message?) => PartialSchema<ObjectSchema<T>>​

Makes all properties of an object schema optional.

Partial transform - makes all properties optional.

Type Parameters​

T: T extends Record<string, GenericSchema>​

schema: Object schema to make partial. — ObjectSchema<T> | ObjectConstraint<T> | { entries: T; }
message?: string — Custom error message.
Returns: PartialSchema<ObjectSchema<T>> — Schema with all properties optional.

Since​

2.0.0

required(): <T>(schema, message?) => RequiredSchema<ObjectSchema<T>>​

Makes all properties of an object schema required.

Required transform - makes all properties required.

Type Parameters​

T: T extends Record<string, GenericSchema>​

schema: Object schema to make required. — ObjectSchema<T> | ObjectConstraint<T> | { entries: T; }
message?: string — Custom error message.
Returns: RequiredSchema<ObjectSchema<T>> — Schema with all properties required.

Since​

2.0.0

pick(): <T, K>(schema, keys, message?) => PickSchema<ObjectSchema<T>, K>​

Picks a subset of properties from an object schema.

Pick transform - selects specific properties.

Type Parameters​

T: T extends Record<string, GenericSchema>​
K: K extends string | number | symbol​

schema: Source object schema. — ObjectSchema<T> | ObjectConstraint<T> | { entries: T; }
keys: readonly K[] — Keys to select.
message?: string — Custom error message.
Returns: PickSchema<ObjectSchema<T>, K> — Schema with only selected properties.

Since​

2.0.0

omit(): <T, K>(schema, keys, message?) => OmitSchema<ObjectSchema<T>, K>​

Omits a subset of properties from an object schema.

Omit transform - excludes specific properties.

Type Parameters​

T: T extends Record<string, GenericSchema>​
K: K extends string | number | symbol​

schema: Source object schema. — ObjectSchema<T> | ObjectConstraint<T> | { entries: T; }
keys: readonly K[] — Keys to exclude.
message?: string — Custom error message.
Returns: OmitSchema<ObjectSchema<T>, K> — Schema without excluded properties.

Since​

2.0.0

keyof(): <T>(objectSchema, message?) => KeyofSchema<ObjectSchema<T>>​

Extracts the string keys of an object schema.

Keyof schema - validates that the value is a key of an object.

Type Parameters​

T: T extends Record<string, GenericSchema>​

objectSchema: Object schema whose keys to validate. — ObjectSchema<T> | ObjectConstraint<T> | { entries: T; }
message?: string — Custom error message.
Returns: KeyofSchema<ObjectSchema<T>> — Schema that validates the object keys.

Since​

2.0.0

optional(): <T>(schema) => OptionalSchema<Schema<T>>​

Wraps a schema to also accept undefined.

Makes a schema optional (accepts undefined).

Type Parameters​

T: T​

schema: Schema<T> — The schema to make optional
Returns: OptionalSchema<Schema<T>> — Schema that accepts the original type or undefined

Since​

2.0.0

nullable(): <T>(schema, message?) => NullableSchema<Schema<T>>​

Wraps a schema to also accept null.

Makes a schema nullable (accepts null).

Type Parameters​

T: T​

schema: Schema<T> — The schema to make nullable
message?: string — Custom error message
Returns: NullableSchema<Schema<T>> — Schema that accepts the original type or null

Since​

2.0.0

default(): <Inner>(schema, defaultValue, message?) => DefaultSchema<Inner>​

Provides a default value when validation fails.

Default schema - provides a default value if undefined.

Type Parameters​

Inner: Inner extends GenericSchema​

schema: Inner — Base schema.
defaultValue: Default value or function that returns the default value. — Infer<Inner> | () => Infer<Inner>
message?: string — Custom error message.
Returns: DefaultSchema<Inner> — Schema that uses the default value if undefined.

Since​

2.0.0

readonly(): <Inner>(schema, message?) => ReadonlySchema<Inner>​

Marks a schema output as readonly.

Readonly schema - makes properties read-only (TypeScript semantics).

Type Parameters​

Inner: Inner extends GenericSchema​

schema: Inner — Base schema.
message?: string — Custom error message.
Returns: ReadonlySchema<Inner> — Schema that marks properties as readonly.

Since​

2.0.0

lazy(): <T>(getter, message?) => LazySchema<T>​

Creates a lazy schema for recursive types.

Lazy schema - allows creating recursive types by deferring evaluation.

Type Parameters​

T: T​

getter: () => Schema<T> — Function that returns the schema to evaluate.
message?: string — Custom error message.
Returns: LazySchema<T> — Lazy schema that evaluates the schema on demand.

Since​

2.0.0

coerce: object​

Namespace for coercion schemas.

coerce.string(): > readonly string: (message?) => StringConstraint = coerceString​

Coerces input to string before validating.

Coerce String schema - converts anything to string with constraints.

message?: string — Custom error message.
Returns: StringConstraint — Schema that coerces to string with chainable constraints.

Since​

2.0.0

Example​
// Basic coercion
coerceString()

// With constraints
coerceString().minLength(2).maxLength(100)
coerceString().email()

coerce.number(): > readonly number: (message?) => NumberConstraint = coerceNumber​

Coerces input to number before validating.

Coerce Number schema - converts to number with constraints.

message?: string — Custom error message.
Returns: NumberConstraint — Schema that coerces to number with chainable constraints.

Since​

2.0.0

Example​
// Basic coercion
coerceNumber()

// With constraints
coerceNumber().min(0).max(100)
coerceNumber().int().positive()

coerce.boolean(): > readonly boolean: (message?) => BooleanSchema = coerceBoolean​

Coerces input to boolean before validating.

Coerce Boolean schema - converts to boolean.

message?: string — Custom error message (optional).
Returns: BooleanSchema — Schema that coerces to boolean.

Since​

2.0.0

coerce.date(): > readonly date: (message?) => DateConstraint = coerceDate​

Coerces input to Date before validating.

Coerce Date schema - converts to Date with constraints.

message?: string — Custom error message.
Returns: DateConstraint — Schema that coerces to Date with chainable constraints.

Since​

2.0.0

Example​
// Basic coercion
coerceDate()

// With constraints
coerceDate().min(new Date("2020-01-01"))
coerceDate().max(new Date()).before(new Date("2030-01-01"))

coerce.bigint(): > readonly bigint: (message?) => BigIntConstraint = coerceBigInt​

Coerces input to bigint before validating.

Coerce BigInt schema - converts values to bigint with constraints.

Handles conversion from number, string, boolean, and other types to BigInt. Returns the coerced value directly for optimal performance.

message?: string — Custom error message
Returns: BigIntConstraint — Schema that converts to bigint with chainable constraints.

Since​

2.0.0

Example​
// Basic coercion
coerceBigInt()

// With constraints
coerceBigInt().min(0n).max(100n)
coerceBigInt().positive()

parse(): <T>(schema, input) => { success: true; data: T; } | { success: false; error: string; }​

Validates a value against a schema.

Core parsing logic for Kanon V3 validation system.

Type Parameters​

T: T​

The expected output type of the schema.

schema: Schema<T> — Schema to validate against.
input: unknown — Value to validate.
Returns: { success: true; data: T; } | { success: false; error: string; } — Result object with success flag and data or error.

Since​

2.0.0

Performance: <a id="parseBulk"></a>​

Optimization: Fast paths for success/error cases.

parseBulk(): <T>(schema, values, options?) => { success: true; data: T[]; } | { success: false; errors: string[]; }​

Validates an array of values against a schema.

Bulk validation with two modes:

  • Early abort: stops at first validation failure (fastest).
  • Complete: collects all errors (comprehensive).

Type Parameters​

T: T​

The expected output type of the schema.

schema: Schema<T> — Schema to validate against.
values: unknown[] — Array of values to validate.
options?: ParseBulkOptions — Bulk validation options.
Returns: { success: true; data: T[]; } | { success: false; errors: string[]; } — Result object with success flag and data array or errors array.

Since​

2.0.0

Performance​

Optimization: Pre-allocation and early abort mode.

Since​

2.0.0

Note​

Tree-shaking warning: Importing k includes ALL Kanon schemas in your bundle, even if you only use a subset. For optimal bundle size, prefer direct imports.

Example​

import { k } from '@kanon/helpers/k';

const userSchema = k.object({
  name: k.string().minLength(1),
  age: k.number().min(0),
  email: k.string().email(),
});

const result = k.parse(userSchema, input);