@oh-my-pi/omptype 17.2.6

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+
+- Initial release: ArkType-compatible schema validation with a lazy JIT runtime. Schemas interpret their first two calls and compile a specialized validator via `new Function` on the third, making `type()` construction ~100x cheaper than arktype while beating its hot-path validation speed. Supports the string definition DSL (primitives, literals, unions, arrays, bounds, `number.integer`, `string.url`, inline defaults, value-suffix `?` optionals), object definitions (`"+": "reject"/"delete"`, `"[string]"` index signatures), `type.errors`/`OmpErrors` with per-entry `path`/`problem`, `type.enumerated`, `type.raw`, keyword statics, composition methods (`.or/.and/.array/.pipe/.narrow/.describe/.default/.allows/.assert`), static inference via `typeof schema.infer`, and draft-2020-12 `toJsonSchema()` emission.
+- TypeBox-style (`@oh-my-pi/omptype/typebox`) and Zod-style (`@oh-my-pi/omptype/zod`) authoring adapters producing native omptype schemas.

package/README.md

@@ -0,0 +1,60 @@
+# @oh-my-pi/omptype
+
+Fast, ArkType-compatible schema validation for Bun. Schemas start with a small
+interpreter and lazily compile after repeated use, keeping construction cheap
+without giving up hot-path validation speed.
+
+## Installation
+
+```sh
+bun add @oh-my-pi/omptype
+```
+
+Omptype requires Bun 1.3.14 or newer.
+
+## Usage
+
+```ts
+import { type } from "@oh-my-pi/omptype";
+
+const Config = type({
+	name: "string",
+	"retries?": "number.integer >= 0",
+	enabled: "boolean = true",
+});
+
+const config = Config.assert({ name: "worker" });
+// { name: "worker", enabled: true }
+
+const result = Config({ name: 42 });
+if (result instanceof type.errors) {
+	console.error(result.summary);
+}
+```
+
+Schemas are callable and expose `.assert()`, `.allows()`, `.toJsonSchema()`,
+`.or()`, `.and()`, `.array()`, `.pipe()`, `.narrow()`, `.describe()`, and
+`.default()`.
+
+## Compatibility adapters
+
+TypeBox-style and Zod-style builders produce native omptype schemas:
+
+```ts
+import { Type, type Static } from "@oh-my-pi/omptype/typebox";
+import { z } from "@oh-my-pi/omptype/zod";
+
+const TypeBoxUser = Type.Object({ name: Type.String() });
+type TypeBoxUser = Static<typeof TypeBoxUser>;
+
+const ZodUser = z.object({ name: z.string() });
+const user = ZodUser.parse({ name: "Ada" });
+```
+
+`@oh-my-pi/omptype/ark` provides the repository's ArkType compatibility facade.
+Its `scope()` export remains available as an alias-free no-op for existing
+callers; new code should import `type` directly from `@oh-my-pi/omptype`.
+
+## License
+
+MIT

package/dist/types/ark.d.ts

@@ -0,0 +1,26 @@
+/**
+ * ArkType compatibility facade — `@oh-my-pi/omptype/ark`.
+ *
+ * Lets code written against arktype keep its imports and names while running
+ * on the omptype lazy-JIT runtime: swap `from "arktype"` for
+ * `from "@oh-my-pi/omptype/ark"` and nothing else changes. New code should
+ * import `@oh-my-pi/omptype` directly.
+ *
+ * Compatibility affordances beyond the plain re-export:
+ * - `ArkError` / `ArkErrors` alias `OmpError` / `OmpErrors`.
+ * - `scope()` (alias-free form only) returns `{ type }`; the `jitless` flag is
+ *   obsolete — omptype always starts interpreted and JIT-compiles lazily.
+ */
+import { OmpError, OmpErrors } from "./errors.js";
+import { type } from "./type.js";
+export * from "./index.js";
+export declare const ArkError: typeof OmpError;
+export type ArkError = OmpError;
+export declare const ArkErrors: typeof OmpErrors;
+export type ArkErrors = OmpErrors;
+/** ArkType `scope()` shim: only the alias-free `scope({}, config?)` form is supported. */
+export declare function scope(aliases: Record<string, never>, _config?: {
+    jitless?: boolean;
+}): {
+    type: typeof type;
+};

package/dist/types/compile.d.ts

@@ -0,0 +1,5 @@
+import { type IR } from "./ir.js";
+/** Compile `ir` into a specialized validator. */
+export declare function compile(ir: IR): (value: unknown) => unknown;
+/** Generated source for inspection/debugging. */
+export declare function compileToSource(ir: IR): string;

package/dist/types/errors.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Validation error containers mirroring ArkType's observable error surface:
+ * `result instanceof type.errors` / `instanceof OmpErrors`, lazy `.summary`,
+ * array iteration, and per-entry `.path` / `.problem` / `.message`.
+ *
+ * Failure-path cost matters: schemas reject untrusted input constantly, so
+ * construction stores only the path, the expectation, and the offending value.
+ * All human-readable strings are built lazily on property access.
+ */
+/** A single validation failure at one path. */
+export declare class OmpError {
+    /** Property path from the root to the failing value (empty at root). */
+    readonly path: PropertyKey[];
+    /** Human-readable expectation, e.g. `"a string"` or `"at most 3600"`. */
+    readonly expected: string;
+    /** The value that failed validation. */
+    readonly data: unknown;
+    constructor(
+    /** Property path from the root to the failing value (empty at root). */
+    path: PropertyKey[], 
+    /** Human-readable expectation, e.g. `"a string"` or `"at most 3600"`. */
+    expected: string, 
+    /** The value that failed validation. */
+    data: unknown);
+    /** Short description of the received value, e.g. `"a number"` or `"missing"`. */
+    get actual(): string;
+    /** Path-less problem statement: `must be <expected> (was <actual>)`. */
+    get problem(): string;
+    /** Full message including the path prefix. */
+    get message(): string;
+    toString(): string;
+}
+/** Sentinel for a required key that was absent (distinguishes from `undefined`). */
+export declare const MISSING: unique symbol;
+/**
+ * Aggregate of validation failures; the value returned by a schema call on
+ * invalid input. Array-like so callers can `.map()` over entries.
+ */
+export declare class OmpErrors extends Array<OmpError> {
+    static get [Symbol.species](): typeof Array;
+    /** Single-failure constructor used by generated validators. */
+    static single(path: PropertyKey[], expected: string, data: unknown): OmpErrors;
+    /** Prefix every entry's path with `key` (used when nesting sub-schemas). */
+    prefix(key: PropertyKey): this;
+    /** Human-readable digest of every failure, one per line. Built lazily. */
+    get summary(): string;
+    toString(): string;
+    /** Throw a `TraversalError` carrying the summary. */
+    throw(): never;
+}
+/** Error thrown by `Type.assert` on invalid input. */
+export declare class TraversalError extends Error {
+    readonly errors: OmpErrors;
+    constructor(errors: OmpErrors);
+}
+/**
+ * Definition/usage error thrown while building a schema — malformed string
+ * DSL, unsupported composition, or an illegal builder call. Distinct from
+ * validation failures, which are returned as {@link OmpErrors}.
+ */
+export declare class OmpTypeError extends Error {
+    constructor(message: string);
+}

package/dist/types/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * omptype — ArkType-compatible schema validation with a lazy JIT runtime.
+ *
+ * Drop-in for the arktype surface this repo uses:
+ * `type()`, `Type`, `type.errors` / `OmpErrors`, `type.enumerated()`,
+ * `.or/.and/.array/.pipe/.narrow/.describe/.default/.allows/.assert/.toJsonSchema`,
+ * plus `typeof schema.infer` static inference.
+ */
+export * from "./errors.js";
+export * from "./infer.js";
+export * from "./ir.js";
+export * from "./json-schema.js";
+export * from "./type.js";

package/dist/types/infer.d.ts

@@ -0,0 +1,49 @@
+/** Type-level output inference for the definition forms accepted by omptype. */
+type Whitespace = " " | "\n" | "\r" | "\t";
+type TrimLeft<s extends string> = s extends `${Whitespace}${infer rest}` ? TrimLeft<rest> : s;
+type TrimRight<s extends string> = s extends `${infer rest}${Whitespace}` ? TrimRight<rest> : s;
+type Trim<s extends string> = TrimLeft<TrimRight<s>>;
+type InferPrimitive<s extends string> = s extends "string" | "string.url" ? string : s extends "number" | "number.integer" ? number : s extends "boolean" ? boolean : s extends "null" ? null : s extends "undefined" ? undefined : s extends "unknown" ? unknown : s extends "object" ? object : s extends "bigint" ? bigint : s extends "true" ? true : s extends "false" ? false : never;
+type InferMember<member extends string> = Trim<member> extends infer s extends string ? s extends `${infer element}[]` ? InferMember<element>[] : s extends `'${infer literal}'` | `"${infer literal}"` ? literal : s extends `${infer literal extends number}` ? literal : InferPrimitive<s> extends infer primitive ? [primitive] extends [never] ? s extends `${string}string${string}` ? string : s extends `${string}number${string}` ? number : unknown : primitive : unknown : unknown;
+/** Split top-level unions without distributing over the accumulated members. */
+type InferUnion<s extends string, result = never> = s extends `${infer head}|${infer tail}` ? InferUnion<tail, result | InferMember<head>> : result | InferMember<s>;
+type HasInlineDefault<s extends string> = s extends `${string}=${string}` ? s extends `${string}<${string}` | `${string}>${string}` ? false : true : false;
+type WithoutInlineDefault<s extends string> = HasInlineDefault<s> extends true ? (s extends `${infer base}=${string}` ? Trim<base> : s) : s;
+/** String-DSL-only inference; safe inside recursive interfaces (never probes `Type`). */
+export type InferString<s extends string> = WithoutInlineDefault<Trim<s>> extends infer trimmed extends string ? trimmed extends `${infer base}?` ? InferString<base> : trimmed extends `(${infer inner})[]` ? InferUnion<inner>[] : InferUnion<trimmed> : unknown;
+type HasDefault<def> = def extends string ? HasInlineDefault<def> : def extends {
+    readonly hasDefault: true;
+} ? true : false;
+type DefinitionKeys<def extends object> = Exclude<keyof def, "+" | "[string]">;
+/** Optional when the key carries a `?` suffix or the string value does (`limit: "number?"`). */
+type IsOptionalProp<key, def> = key extends `${string}?` ? true : def extends string ? Trim<def> extends `${string}?` ? true : false : false;
+type PropName<key extends PropertyKey> = key extends `${infer name}?` ? name : key;
+type RequiredProperties<def extends object> = {
+    -readonly [key in DefinitionKeys<def> as IsOptionalProp<key, def[key]> extends true ? HasDefault<def[key]> extends true ? PropName<key> : never : PropName<key>]-?: InferDef<def[key]>;
+};
+type OptionalProperties<def extends object> = {
+    -readonly [key in DefinitionKeys<def> as IsOptionalProp<key, def[key]> extends true ? HasDefault<def[key]> extends true ? never : PropName<key> : never]?: InferDef<def[key]>;
+};
+type Simplify<t> = {
+    [key in keyof t]: t[key];
+};
+type PropertiesOf<def extends object> = Simplify<RequiredProperties<def> & OptionalProperties<def>>;
+type InferObject<def extends object> = "[string]" extends keyof def ? [DefinitionKeys<def>] extends [never] ? Record<string, InferDef<def["[string]"]>> : PropertiesOf<def> & Record<string, InferDef<def["[string]"]>> : PropertiesOf<def>;
+/** Object-literal inference for fluent composition without re-inspecting the containing `Type`. */
+export type InferObjectDef<def extends object> = InferObject<def>;
+type InferLiteralDef<def> = def extends string ? InferString<def> : def extends object ? InferObjectLiteral<def> : unknown;
+type LiteralRequiredProperties<def extends object> = {
+    -readonly [key in DefinitionKeys<def> as IsOptionalProp<key, def[key]> extends true ? HasDefault<def[key]> extends true ? PropName<key> : never : PropName<key>]-?: InferLiteralDef<def[key]>;
+};
+type LiteralOptionalProperties<def extends object> = {
+    -readonly [key in DefinitionKeys<def> as IsOptionalProp<key, def[key]> extends true ? HasDefault<def[key]> extends true ? never : PropName<key> : never]?: InferLiteralDef<def[key]>;
+};
+/** Object-literal-only inference for fluent branches; never inspects embedded schema types. */
+export type InferObjectLiteral<def extends object> = Simplify<LiteralRequiredProperties<def> & LiteralOptionalProperties<def>>;
+/** Infer the validated output type produced by a definition. */
+export type InferDef<def = unknown> = def extends {
+    infer: infer output;
+} ? output : def extends string ? InferString<def> : def extends readonly [infer element, "[]"] ? InferDef<element>[] : def extends object ? InferObject<def> : unknown;
+/** Input-side defaults and morphs are not distinguished yet. */
+export type InferDefIn<def = unknown> = InferDef<def>;
+export {};

package/dist/types/interp.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Tree-walking validator used for a schema's first few calls (before the JIT
+ * compiler kicks in) and as the fallback for IR shapes the compiler declines.
+ *
+ * Semantics must stay in lockstep with `compile.ts`:
+ * - success returns the output value; the input is returned as-is unless the
+ *   schema morphs (defaults, `"+": "delete"`, embedded stepped schemas), in
+ *   which case a fresh object/array is produced and the input is untouched
+ * - failure returns an `OmpErrors` with a single fast-fail entry
+ */
+import { OmpErrors } from "./errors.js";
+import { type IR } from "./ir.js";
+/** Validate `value` against `ir`; returns output value or `OmpErrors`. */
+export declare function walk(ir: IR, value: unknown): unknown;
+/**
+ * Detailed failure for a union: descend into the member the value was clearly
+ * aimed at — unique runtime-kind match, else an object member whose literal
+ * discriminant property (e.g. `type: "'computer_call'"`) equals the value's —
+ * for a precise nested error (paths, narrow messages) instead of the coarse
+ * "A or B" expectation.
+ */
+export declare function unionFail(ir: IR & {
+    k: "union";
+}, v: unknown, path: PropertyKey[]): OmpErrors;

package/dist/types/ir.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Schema IR and the ArkType-compatible definition parser.
+ *
+ * `parseDef` turns the definition subset this repo uses — string DSL
+ * (primitives, literals, unions, arrays, bounds, `number.integer`,
+ * `string.url`, inline `= literal` defaults), object literals (optional `?`
+ * keys, `"+"` undeclared-key policy, `"[string]"` index signatures), tuple
+ * `[def, "[]"]` arrays, and embedded `Type` instances — into a small IR tree
+ * consumed by the interpreter (`interp.ts`), the JIT compiler (`compile.ts`),
+ * and the JSON Schema emitter (`json-schema.ts`).
+ */
+/** Brand carried by `Type` instances so the parser can embed them in defs. */
+export declare const IR_BRAND: unique symbol;
+/**
+ * The parser-facing surface of an embedded `Type` instance.
+ * `type.ts` implements this on every schema it creates.
+ */
+export interface EmbeddableSchema {
+    [IR_BRAND]: true;
+    /** Structural IR of the schema (base type when runtime steps exist). */
+    ir: IR;
+    /** True when the schema carries `.pipe()`/`.narrow()` steps. */
+    hasSteps: boolean;
+    /** `.default()` payload; a function is a factory invoked per fill. */
+    defaultValue?: unknown;
+    hasDefault: boolean;
+    /** `.describe()` annotation, emitted into JSON Schema. */
+    description?: string;
+    /** Full validate+morph pipeline (identical to calling the schema). */
+    run(value: unknown): unknown;
+}
+/** Policy for undeclared object keys. */
+export type Extras = "keep" | "reject" | "delete";
+export type IR = {
+    k: "unknown";
+    desc?: string;
+} | {
+    k: "null";
+    desc?: string;
+} | {
+    k: "undefined";
+    desc?: string;
+} | {
+    k: "boolean";
+    desc?: string;
+} | {
+    k: "bigint";
+    desc?: string;
+}
+/** Any non-null object (the bare `object` keyword). */
+ | {
+    k: "anyobject";
+    desc?: string;
+} | {
+    k: "string";
+    min?: number;
+    max?: number;
+    url?: boolean;
+    desc?: string;
+} | {
+    k: "number";
+    min?: number;
+    max?: number;
+    xmin?: boolean;
+    xmax?: boolean;
+    int?: boolean;
+    desc?: string;
+} | {
+    k: "lit";
+    v: unknown;
+    desc?: string;
+} | {
+    k: "union";
+    members: IR[];
+    desc?: string;
+} | {
+    k: "array";
+    el: IR;
+    min?: number;
+    max?: number;
+    desc?: string;
+} | {
+    k: "object";
+    props: PropIR[];
+    index?: IR;
+    extras: Extras;
+    desc?: string;
+}
+/** Embedded schema with runtime steps; validated by calling `run`. */
+ | {
+    k: "sub";
+    schema: EmbeddableSchema;
+    desc?: string;
+};
+export interface PropIR {
+    key: string;
+    opt: boolean;
+    val: IR;
+    /** Default payload (value, or factory when `defFactory`); missing key is filled. */
+    def?: unknown;
+    defFactory?: boolean;
+    hasDefault?: boolean;
+}
+/** Definition input accepted by `type()` and object property values. */
+export type Def = string | EmbeddableSchema | readonly Def[] | {
+    readonly [k: string]: Def;
+};
+/** Embed a schema value: inline pure structure, keep `sub` nodes for stepped schemas. */
+export declare function embed(schema: EmbeddableSchema): IR;
+/** Parse a definition (string DSL, object literal, tuple, or embedded schema) into IR. */
+export declare function parseDef(def: Def): IR;
+/** True when validating `ir` can produce an output different from its input. */
+export declare function hasMorph(ir: IR): boolean;
+/** Human-readable expectation for error messages, e.g. `"a string"`. */
+export declare function expectedOf(ir: IR): string;

package/dist/types/json-schema.d.ts

@@ -0,0 +1,8 @@
+import type { IR } from "./ir.js";
+export interface JsonSchemaOptions {
+    description?: string;
+}
+type JsonSchema = Record<string, unknown>;
+/** Emit the draft-2020-12 JSON Schema represented by an IR tree. */
+export declare function irToJsonSchema(ir: IR, options?: JsonSchemaOptions): JsonSchema;
+export {};

package/dist/types/type.d.ts

@@ -0,0 +1,100 @@
+import { OmpErrors } from "./errors.js";
+import type { InferDef, InferObjectLiteral, InferString } from "./infer.js";
+import { type Def, hasMorph, type IR, IR_BRAND } from "./ir.js";
+/** Context passed to `.narrow()` / `.pipe()` callbacks. */
+export interface NarrowContext {
+    /** Record `must be <expectation>` and signal failure. */
+    mustBe(expectation: string): false;
+    /** Record a custom problem and signal failure. */
+    reject(problem: string): false;
+}
+/** Options accepted by `Type.toJsonSchema` (ArkType-compatible; emission is always draft 2020-12). */
+export interface ToJsonSchemaOptions {
+    target?: string;
+    dialect?: string;
+    fallback?: (ctx: {
+        base: Record<string, unknown>;
+    }) => unknown;
+}
+interface SchemaInference<out t> {
+    readonly [IR_BRAND]: true;
+    readonly infer: t;
+}
+/** A compiled schema: callable validator plus composition methods. */
+export interface Type<out t = unknown> {
+    (data: unknown): t | OmpErrors;
+    readonly [IR_BRAND]: true;
+    /** Structural IR (base type; runtime steps live in `steps`). */
+    readonly ir: IR;
+    /** `.pipe()` / `.narrow()` steps applied after structural validation. */
+    readonly hasSteps: boolean;
+    readonly hasDefault: boolean;
+    readonly defaultValue?: unknown;
+    readonly description?: string;
+    /** Full validate+morph pipeline; identical to calling the schema. */
+    readonly run: (data: unknown) => unknown;
+    /** Inference-only output type (no runtime value). */
+    readonly infer: t;
+    /** Inference-only input type (no runtime value). */
+    readonly inferIn: t;
+    /** Structural + narrow check without running pipes. */
+    allows(data: unknown): data is t;
+    /** Validate and return output, throwing `TraversalError` on failure. */
+    assert(data: unknown): t;
+    /** JSON Schema (draft 2020-12) for this schema's structural base. */
+    toJsonSchema(options?: ToJsonSchemaOptions): Record<string, unknown>;
+}
+/** Schema returned by omptype builders, with precise object-literal composition inference. */
+export interface FluentType<t = unknown> extends Type<t> {
+    describe(description: string): FluentType<t>;
+    default(value: t | (() => t)): FluentType<t>;
+    or<r>(def: SchemaInference<r>): FluentType<t | r>;
+    or<const def extends string>(def: def): FluentType<t | InferString<def>>;
+    or<const def extends Record<string, unknown>>(def: def): FluentType<t | InferObjectLiteral<def>>;
+    or(def: Def): FluentType<unknown>;
+    and<r>(def: SchemaInference<r>): FluentType<t & r>;
+    and<const def extends Record<string, unknown>>(def: def): FluentType<t & InferObjectLiteral<def>>;
+    and(def: Def): FluentType<unknown>;
+    array(): FluentType<t[]>;
+    atLeastLength(bound: number): FluentType<t>;
+    atMostLength(bound: number): FluentType<t>;
+    atLeast(bound: number): FluentType<t>;
+    atMost(bound: number): FluentType<t>;
+    pipe<r>(fn: (data: t, ctx: NarrowContext) => r): FluentType<Exclude<r, OmpErrors>>;
+    narrow<narrowed extends t>(fn: (data: t, ctx: NarrowContext) => data is narrowed): FluentType<narrowed>;
+    narrow(fn: (data: t, ctx: NarrowContext) => boolean): FluentType<t>;
+}
+/** Runtime constructor-like value used by ArkType-compatible `instanceof Type` checks. */
+export declare const Type: () => void;
+/**
+ * The `type()` builder: parses a definition into a callable schema.
+ *
+ * The `const def` generic drives static inference (`typeof schema.infer`);
+ * the runtime is definition-shape-agnostic, hence the cast.
+ */
+export declare function type<const def>(def: def): FluentType<InferDef<def>>;
+export declare namespace type {
+    /** Error aggregate returned by failed validations (`result instanceof type.errors`). */
+    const errors: typeof OmpErrors;
+    type errors = OmpErrors;
+    /** Keyword statics for fluent building, e.g. `type.number.atLeast(5)`. */
+    const string: FluentType<string>;
+    const number: FluentType<number>;
+    const boolean: FluentType<boolean>;
+    const unknown: FluentType<unknown>;
+    /** Union of literal values from a runtime array (`type.enumerated(...list)`). */
+    function enumerated<const values extends readonly unknown[]>(...values: values): FluentType<values[number]>;
+    /** Untyped builder for runtime-assembled definitions (`type.raw({...})`). */
+    function raw(def: unknown): BaseType;
+}
+export interface ScopeOptions {
+    jitless?: boolean;
+}
+/** ArkType-compatible scope wrapper; omptype's global builder is already lazy. */
+export declare function scope(_aliases: Record<string, unknown>, _options?: ScopeOptions): {
+    type: typeof type;
+};
+/** A schema whose output type is not statically known (`type.raw` results). */
+export type BaseType = FluentType<unknown>;
+/** `hasMorph` re-export for diagnostics/tooling. */
+export { hasMorph };