@pithos/core 2.0.0

package/dist/kanon/jit/cache.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @module kanon/jit/compiler
+ *
+ * Validator Cache for JIT Compilation
+ *
+ * Caches compiled validators to avoid re-compilation of the same schema.
+ * Uses WeakMap to allow garbage collection of unused schemas.
+ *
+ * @since 2.0.0
+ * @experimental
+ */
+import type { Schema, ValidatorResult } from "../types/base";
+/**
+ * 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.
+ *
+ * @template T - The type being validated
+ * @since 2.0.0
+ */
+export type CompiledValidatorFn<T> = (value: unknown) => ValidatorResult<T>;
+/**
+ * Compiled validator with metadata.
+ *
+ * @template T - The type being validated
+ * @since 2.0.0
+ */
+export interface CompiledValidator<T> extends CompiledValidatorFn<T> {
+    /** Generated source code (only in debug mode) */
+    source?: string;
+    /** Whether this is a fallback to V3 non-compiled validator */
+    isFallback?: boolean;
+}
+/**
+ * Interface for the validator cache.
+ *
+ * The cache stores compiled validators keyed by their source schema.
+ * Using WeakMap ensures that schemas can be garbage collected when
+ * no longer referenced elsewhere.
+ *
+ * @since 2.0.0
+ */
+export interface ValidatorCache {
+    /**
+     * Retrieves a compiled validator from the cache.
+     *
+     * @param schema - The schema to look up
+     * @returns The cached validator, or undefined if not found
+     */
+    get<T>(schema: Schema<T>): CompiledValidator<T> | undefined;
+    /**
+     * Stores a compiled validator in the cache.
+     *
+     * @param schema - The schema to use as key
+     * @param validator - The compiled validator to cache
+     */
+    set<T>(schema: Schema<T>, validator: CompiledValidator<T>): void;
+    /**
+     * Checks if a schema has a cached validator.
+     *
+     * @param schema - The schema to check
+     * @returns true if the schema has a cached validator
+     */
+    has(schema: Schema<unknown>): boolean;
+    /**
+     * Clears all cached validators.
+     *
+     * Note: This creates a new WeakMap, allowing the old entries
+     * to be garbage collected.
+     */
+    clear(): void;
+}
+/**
+ * Creates a new validator cache instance.
+ *
+ * @returns A new ValidatorCache
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * const cache = createValidatorCache();
+ *
+ * const schema = string();
+ * const validator = compile(schema);
+ *
+ * cache.set(schema, validator);
+ *
+ * // Later...
+ * if (cache.has(schema)) {
+ *   const cached = cache.get(schema);
+ * }
+ * ```
+ */
+export declare function createValidatorCache(): ValidatorCache;
+/**
+ * Global validator cache instance.
+ *
+ * This is the default cache used by the JIT compiler.
+ * It can be cleared using `globalValidatorCache.clear()`.
+ *
+ * @since 2.0.0
+ */
+export declare const globalValidatorCache: ValidatorCache;
+//# sourceMappingURL=cache.d.ts.map

package/dist/kanon/jit/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/kanon/jit/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAE7D;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,eAAe,CAAC,CAAC,CAAC,CAAC;AAE5E;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,CAAE,SAAQ,mBAAmB,CAAC,CAAC,CAAC;IAClE,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAE5D;;;;;OAKG;IACH,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAEjE;;;;;OAKG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAEtC;;;;;OAKG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AA8BD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,IAAI,cAAc,CAErD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,EAAE,cAAuC,CAAC"}

package/dist/kanon/jit/cache.js

@@ -0,0 +1,65 @@
+/**
+ * @module kanon/jit/compiler
+ *
+ * Validator Cache for JIT Compilation
+ *
+ * Caches compiled validators to avoid re-compilation of the same schema.
+ * Uses WeakMap to allow garbage collection of unused schemas.
+ *
+ * @since 2.0.0
+ * @experimental
+ */
+/**
+ * Internal implementation of the validator cache.
+ */
+class ValidatorCacheImpl {
+    constructor() {
+        this.cache = new WeakMap();
+    }
+    get(schema) {
+        return this.cache.get(schema);
+    }
+    set(schema, validator) {
+        this.cache.set(schema, validator);
+    }
+    has(schema) {
+        return this.cache.has(schema);
+    }
+    clear() {
+        this.cache = new WeakMap();
+    }
+}
+/**
+ * Creates a new validator cache instance.
+ *
+ * @returns A new ValidatorCache
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * const cache = createValidatorCache();
+ *
+ * const schema = string();
+ * const validator = compile(schema);
+ *
+ * cache.set(schema, validator);
+ *
+ * // Later...
+ * if (cache.has(schema)) {
+ *   const cached = cache.get(schema);
+ * }
+ * ```
+ */
+export function createValidatorCache() {
+    return new ValidatorCacheImpl();
+}
+/**
+ * Global validator cache instance.
+ *
+ * This is the default cache used by the JIT compiler.
+ * It can be cleared using `globalValidatorCache.clear()`.
+ *
+ * @since 2.0.0
+ */
+export const globalValidatorCache = createValidatorCache();
+//# sourceMappingURL=cache.js.map

package/dist/kanon/jit/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../src/kanon/jit/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAwEH;;GAEG;AACH,MAAM,kBAAkB;IAItB;QACE,IAAI,CAAC,KAAK,GAAG,IAAI,OAAO,EAAE,CAAC;IAC7B,CAAC;IAED,GAAG,CAAI,MAAiB;QACtB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAqC,CAAC;IACpE,CAAC;IAED,GAAG,CAAI,MAAiB,EAAE,SAA+B;QACvD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,SAAuC,CAAC,CAAC;IAClE,CAAC;IAED,GAAG,CAAC,MAAuB;QACzB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,GAAG,IAAI,OAAO,EAAE,CAAC;IAC7B,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,IAAI,kBAAkB,EAAE,CAAC;AAClC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAmB,oBAAoB,EAAE,CAAC"}

package/dist/kanon/jit/compiler.d.ts

@@ -0,0 +1,275 @@
+/**
+ * @module kanon/jit/compiler
+ *
+ * Kanon V3 JIT Compiler
+ *
+ * Generates optimized JavaScript validators at runtime using `new Function()`.
+ * Supports all schema types: primitives, composites, unions, and coercion.
+ *
+ * @since 2.0.0
+ * @experimental
+ *
+ * ## Performance Results (January 2026)
+ *
+ * Test schema: Object with 5 properties (string, number, boolean, string, number)
+ *
+ * | Scenario        | V3 Non-Compiled | JIT Compiled | Fastest-Validator | JIT vs V3 |
+ * |-----------------|-----------------|--------------|-------------------|-----------|
+ * | Valid Objects   | 12.6M ops/s     | 23.6M ops/s  | 19.3M ops/s       | 1.88x     |
+ * | Invalid Objects | 13.1M ops/s     | 23.5M ops/s  | 3.1M ops/s        | 1.80x     |
+ *
+ * ## CSP (Content Security Policy) Limitations
+ *
+ * The JIT compiler uses `new Function()` which is blocked in environments with
+ * strict Content Security Policy (missing `'unsafe-eval'`).
+ *
+ * When JIT compilation fails, the system automatically falls back to the original
+ * V3 non-compiled validator with `isFallback: true`.
+ *
+ * ## Refinements Support
+ *
+ * Refinements are user-defined validation functions that cannot be inlined.
+ * They are stored as external functions and called via the externals map.
+ * This introduces function call overhead but preserves correctness.
+ */
+import type { Schema, ValidatorResult } from "../types/base";
+/**
+ * Compiled validator function with metadata.
+ *
+ * A compiled validator is a function that validates values against a schema.
+ * It returns `true` for valid values, an error message string for invalid values,
+ * or `{ coerced: T }` for coercion schemas.
+ *
+ * @typeParam T - The type that the validator validates
+ *
+ * @example
+ * ```typescript
+ * const validate: CompiledValidator<{ name: string }> = compile(schema);
+ *
+ * // Valid value
+ * validate({ name: "John" }); // true
+ *
+ * // Invalid value
+ * validate({ name: 123 }); // "Property 'name': Expected string"
+ *
+ * // Check if using fallback
+ * if (validate.isFallback) {
+ *   console.log("JIT not available, using V3 validator");
+ * }
+ *
+ * // Debug mode - inspect generated code
+ * const debugValidate = compile(schema, { debug: true });
+ * console.log(debugValidate.source);
+ * ```
+ *
+ * @since 2.0.0
+ */
+export type CompiledValidator<T> = ((value: unknown) => ValidatorResult<T>) & {
+    /**
+     * Generated source code (only available when compiled with `{ debug: true }`).
+     * Useful for debugging and understanding the generated validation logic.
+     */
+    source?: string;
+    /**
+     * True if using V3 fallback due to CSP or other restrictions.
+     * When true, the validator is the original V3 non-compiled validator.
+     */
+    isFallback?: boolean;
+};
+/**
+ * Options for the compile function.
+ *
+ * @example
+ * ```typescript
+ * // 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
+ */
+export interface CompileOptions {
+    /**
+     * 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.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * 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
+     */
+    noCache?: boolean;
+    /**
+     * 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
+     */
+    forceFallback?: boolean;
+}
+/**
+ * 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.
+ *
+ * @typeParam T - The type that the schema validates
+ * @param schema - The schema to compile
+ * @param options - Compilation options
+ * @returns A compiled validator function
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { object, string, number, compile } from "../index";
+ *
+ * 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"
+ * ```
+ *
+ * @example Debug mode - inspect generated code
+ * ```typescript
+ * 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";
+ * // }
+ * // ...
+ * ```
+ *
+ * @example Checking for CSP fallback
+ * ```typescript
+ * const validate = compile(schema);
+ * if (validate.isFallback) {
+ *   console.warn("JIT compilation not available, using V3 fallback");
+ * }
+ * ```
+ *
+ * @example With arrays
+ * ```typescript
+ * const tagsSchema = array(string());
+ * const validate = compile(tagsSchema);
+ *
+ * validate(["a", "b", "c"]); // true
+ * validate(["a", 123, "c"]); // "Index 1: Expected string"
+ * ```
+ *
+ * @example With unions
+ * ```typescript
+ * 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
+ * @experimental
+ */
+export declare function compile<T>(schema: Schema<T>, options?: CompileOptions): CompiledValidator<T>;
+/**
+ * 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 `true` if `new Function()` is supported, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { isJITAvailable, compile } from "../index";
+ *
+ * if (isJITAvailable()) {
+ *   const validate = compile(schema);
+ *   // Use JIT-compiled validator
+ * } else {
+ *   // Use V3 non-compiled validator
+ *   const validate = schema.validator;
+ * }
+ * ```
+ *
+ * @since 2.0.0
+ */
+export declare function isJITAvailable(): boolean;
+/**
+ * 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
+ *
+ * @example
+ * ```typescript
+ * import { compile, clearCache } from "../index";
+ *
+ * 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
+ */
+export declare function clearCache(): void;
+//# sourceMappingURL=compiler.d.ts.map

package/dist/kanon/jit/compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../../../src/kanon/jit/compiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAiB,MAAM,eAAe,CAAC;AAuC5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,eAAe,CAAC,CAAC,CAAC,CAAC,GAAG;IAC5E;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAqYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACvB,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,OAAO,CAAC,EAAE,cAAc,GACvB,iBAAiB,CAAC,CAAC,CAAC,CA+DtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAUxC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAEjC"}