compile()

compile<T>(schema, options?): CompiledValidator<T>

Experimental

Compiles a schema into an optimized validator function using JIT compilation.

The JIT compiler generates JavaScript code at runtime using new Function(), which is then executed by the V8 engine with full optimization. This results in validators that are significantly faster than the interpreted V3 validators.

Performance

Typical performance improvements over V3 non-compiled validators:

• Simple objects (3 props): ~1.4x faster
• Complex objects (nested): ~4x faster
• Large arrays (500+ items): ~4x faster
• Unions: ~1.3-2x faster

---

Caching

Compiled validators are cached using a WeakMap keyed by schema reference. This means calling compile(schema) multiple times with the same schema returns the same compiled validator without re-compilation.

---

CSP Limitations

The JIT compiler uses new Function() which is blocked in environments with strict Content Security Policy (missing 'unsafe-eval'). In such cases, the compiler automatically falls back to the original V3 validator. Check validator.isFallback to detect this scenario.

---

Refinements

Schemas with refinements (custom validation functions) are supported but cannot be fully inlined. Refinements are called as external functions, which introduces some overhead compared to pure type validation.

---

Type Parameters

T: T

The type that the schema validates

---

Parameters

schema: Schema<T>

The schema to compile

options?: CompileOptions

Compilation options

---

Returns: CompiledValidator<T>

A compiled validator function

---

Examples

import { object, string, number, compile } from "@kanon";

const userSchema = object({ name: string(), age: number() });
const validate = compile(userSchema);

validate({ name: "John", age: 30 }); // true
validate({ name: 123, age: 30 }); // "Property 'name': Expected string"

const validate = compile(schema, { debug: true });
console.log(validate.source);
// Output:
// if (typeof value !== "object" || value === null) {
//   return "Expected object";
// }
// var v_0 = value.name;
// if (typeof v_0 !== "string") {
//   return "Property 'name': Expected string";
// }
// ...

const validate = compile(schema);
if (validate.isFallback) {
  console.warn("JIT compilation not available, using V3 fallback");
}

const tagsSchema = array(string());
const validate = compile(tagsSchema);

validate(["a", "b", "c"]); // true
validate(["a", 123, "c"]); // "Index 1: Expected string"

const idSchema = unionOf(string(), number());
const validate = compile(idSchema);

validate("abc"); // true
validate(123); // true
validate(true); // "Expected string or number"

---

Since

2.0.0

CompileOptions

Interface

Experimental

Options for the compile function.

---

Example

// Default compilation (cached, no debug)
const validate = compile(schema);

// Debug mode - includes source code
const debugValidate = compile(schema, { debug: true });
console.log(debugValidate.source);

// Disable caching (useful for testing)
const uncachedValidate = compile(schema, { noCache: true });

// Force fallback (useful for testing CSP scenarios)
const fallbackValidate = compile(schema, { forceFallback: true });

---

Since

2.0.0

---

Properties

debug?: boolean

Experimental

Enable debug mode to include source code in the result. When true, the compiled validator will have a source property containing the generated JavaScript code.

noCache?: boolean

Experimental

Disable caching for this compilation. By default, compiled validators are cached using a WeakMap. Set to true to always generate a new validator.

Default

false

forceFallback?: boolean

Experimental

Force fallback to V3 validator (for testing). When true, the JIT compiler will skip compilation and return the original V3 validator with isFallback: true.

Default

false

CompiledValidator()<T>

Interface

Compiled validator with metadata.

---

Since

2.0.0

---

Extends

• CompiledValidatorFn<T>

---

Type Parameters

T: T

The type being validated

CompiledValidator(value): ValidatorResult<T>

Experimental

---

Parameters

value: unknown

---

Returns: ValidatorResult<T>

---

Properties

source?: string

Experimental

Generated source code (only in debug mode)

isFallback?: boolean

Experimental

Whether this is a fallback to V3 non-compiled validator

CompiledValidatorFn()<T>

Type

CompiledValidatorFn<T> = (value) => ValidatorResult<T>

Experimental

Compiled validator function type.

A compiled validator is a function that validates a value and returns either true for valid values, a string error message for invalid values, or a coerced result object.

---

Type Parameters

T: T

The type being validated

---

Parameters

value: unknown

---

Returns: ValidatorResult<T>

---

Since

2.0.0

isJITAvailable()

Function

isJITAvailable(): boolean

Experimental

Checks if JIT compilation is available in the current environment.

JIT compilation requires new Function() to be available, which may be blocked by Content Security Policy (CSP) in some environments.

Use this function to check availability before deciding whether to use JIT compilation or fall back to alternative strategies.

---

Returns: boolean

true if new Function() is supported, false otherwise

---

Example

import { isJITAvailable, compile } from "@kanon";

if (isJITAvailable()) {
  const validate = compile(schema);
  // Use JIT-compiled validator
} else {
  // Use V3 non-compiled validator
  const validate = schema.validator;
}

---

Since

2.0.0

clearCache()

Function

clearCache(): void

Experimental

Clears the global validator cache.

The JIT compiler caches compiled validators using a WeakMap keyed by schema reference. This function clears all cached validators, forcing re-compilation on the next compile() call.

Useful for:

• Testing scenarios where you need fresh compilations
• Memory management in long-running applications
• Debugging compilation issues

---

Returns: void

---

Example

import { compile, clearCache } from "@kanon";

const validate1 = compile(schema);
const validate2 = compile(schema);
console.log(validate1 === validate2); // true (cached)

clearCache();

const validate3 = compile(schema);
console.log(validate1 === validate3); // false (re-compiled)

---

Since

2.0.0