@hoangvu12/yomi 0.1.0

package/README.md

@@ -0,0 +1,191 @@
+# Yomi (読み)
+
+**Yomi** (pronounced "yoh-mee", 読み) means "reading" or "interpretation" in Japanese. This library interprets messy LLM output and coerces it to match your Zod schemas.
+
+## The Problem
+
+LLMs don't return perfect JSON. They return:
+
+```json
+{name: "John", age: "25",}  // unquoted keys, trailing comma
+```
+
+```
+Here's the user data: {"name": "John", "age": 25}  // wrapped in text
+```
+
+```json
+{"name": "John", "age": "25", "active": "yes"}  // wrong types everywhere
+```
+
+`JSON.parse()` fails. Even if it succeeds, your types are wrong.
+
+## The Solution
+
+Yomi uses a two-phase approach inspired by [BAML](https://docs.boundaryml.com/)'s schema-aligned parsing:
+
+1. **Flexible JSON parsing** - Fix malformed JSON, extract from markdown/text
+2. **Schema-aligned coercion** - Walk your Zod schema and coerce values to match
+
+```ts
+import { z } from "zod";
+import { parse } from "@hoangvu12/yomi";
+
+const User = z.object({
+  name: z.string(),
+  age: z.number(),
+  active: z.boolean(),
+});
+
+const result = parse(User, `{name: "John", age: "25", active: "yes"}`);
+
+// result.success === true
+// result.data.value === { name: "John", age: 25, active: true }
+// result.data.flags === ["json_repaired", "string_to_number", "string_to_bool"]
+```
+
+## Installation
+
+```bash
+npm install @hoangvu12/yomi zod
+# or
+bun add @hoangvu12/yomi zod
+```
+
+## API
+
+### `parse(schema, input)`
+
+Parse and coerce input to match schema. Returns a result object.
+
+```ts
+const result = parse(UserSchema, rawInput);
+
+if (result.success) {
+  console.log(result.data.value); // typed as z.infer<typeof UserSchema>
+  console.log(result.data.flags); // what transformations happened
+} else {
+  console.log(result.error); // what went wrong
+}
+```
+
+### `parseOrThrow(schema, input)`
+
+Same as `parse`, but throws on failure. Returns the coerced value directly.
+
+```ts
+const user = parseOrThrow(UserSchema, rawInput);
+// user is typed as z.infer<typeof UserSchema>
+```
+
+### `coerce(schema, value)` / `coerceOrThrow(schema, value)`
+
+Skip JSON parsing, just do schema coercion on an already-parsed value.
+
+```ts
+const result = coerce(UserSchema, { name: "John", age: "25" });
+```
+
+## What It Fixes
+
+### JSON Parsing
+
+| Input | Fixed |
+|-------|-------|
+| `{name: "John"}` | Unquoted keys |
+| `{"name": "John",}` | Trailing commas |
+| `// comment` | Comments |
+| `'single quotes'` | Single quotes |
+| `` ```json {...}``` `` | Markdown code blocks |
+| `Here's the data: {...}` | Surrounding text |
+
+### Type Coercion
+
+| From | To | Example |
+|------|----|---------|
+| `"123"` | `number` | `"25"` → `25` |
+| `"12.5"` | `int` | `"12.5"` → `13` (rounded) |
+| `123` | `string` | `123` → `"123"` |
+| `"true"`, `"yes"`, `"1"` | `boolean` | → `true` |
+| `"false"`, `"no"`, `"0"` | `boolean` | → `false` |
+| `value` | `array` | `"x"` → `["x"]` |
+| `[value]` | `single` | `["x"]` → `"x"` |
+| `"PENDING"` | `enum` | Case-insensitive match |
+| `null` | `undefined` | For optional fields |
+| `{extra: ...}` | `object` | Extra keys ignored |
+
+## Flags
+
+Every transformation is tracked. Use flags to:
+- Log when coercion happens in production
+- Detect if defaults were used vs explicit values
+- Debug why parsing succeeded unexpectedly
+
+```ts
+const result = parse(Schema, input);
+if (result.success) {
+  for (const flag of result.data.flags) {
+    console.log(flag);
+    // { flag: "string_to_number" }
+    // { flag: "extra_keys_ignored", keys: ["confidence"] }
+    // { flag: "float_to_int", original: 12.5, rounded: 13 }
+  }
+}
+```
+
+### Available Flags
+
+| Flag | Meaning |
+|------|---------|
+| `json_repaired` | jsonrepair fixed the JSON |
+| `extracted_from_markdown` | Extracted from `` ```json ``` `` block |
+| `extracted_from_text` | Extracted JSON from surrounding text |
+| `string_to_number` | `"123"` → `123` |
+| `string_to_bool` | `"true"` → `true` |
+| `number_to_string` | `123` → `"123"` |
+| `bool_to_string` | `true` → `"true"` |
+| `float_to_int` | `12.5` → `13` |
+| `single_to_array` | `x` → `[x]` |
+| `array_to_single` | `[x]` → `x` |
+| `null_to_undefined` | `null` → `undefined` |
+| `extra_keys_ignored` | Object had extra properties |
+| `missing_optional_key` | Optional field was missing |
+| `default_used` | Used schema's default value |
+| `enum_case_insensitive` | `"PENDING"` matched `"pending"` |
+
+## Supported Zod Types
+
+- Primitives: `string`, `number`, `boolean`, `null`, `undefined`, `literal`
+- Objects: `object`, `record`
+- Arrays: `array`, `tuple`
+- Unions: `union`, `discriminatedUnion`, `optional`, `nullable`
+- Enums: `enum`, `nativeEnum`
+- Modifiers: `default`, `catch`
+- Passthrough: `any`, `unknown`
+
+## How It Works
+
+```
+LLM Output (string)
+       │
+       ▼
+┌─────────────────┐
+│  Flexible JSON  │  ← jsonrepair + markdown extraction
+│     Parser      │
+└────────┬────────┘
+         │ unknown
+         ▼
+┌─────────────────┐
+│  Schema-Aligned │  ← walks Zod schema tree
+│    Coercer      │
+└────────┬────────┘
+         │ { value: T, flags: Flag[] }
+         ▼
+     Result<T>
+```
+
+The coercer recursively walks your Zod schema using `schema._def`, dispatching to type-specific coercion functions. Each coercer tries to interpret the input value as the expected type, recording flags when transformations occur.
+
+## License
+
+MIT

package/dist/coerce.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+import { type CoerceContext, type CoerceResult } from "./types.js";
+/**
+ * Coerce a value to match a Zod schema.
+ * This is the main entry point for schema-aligned coercion.
+ */
+export declare function coerceToSchema<T extends z.ZodTypeAny>(schema: T, value: unknown, ctx?: CoerceContext): CoerceResult<z.infer<T>>;
+//# sourceMappingURL=coerce.d.ts.map

package/dist/coerce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coerce.d.ts","sourceRoot":"","sources":["../src/coerce.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,YAAY,EAIlB,MAAM,YAAY,CAAC;AAcpB;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EACnD,MAAM,EAAE,CAAC,EACT,KAAK,EAAE,OAAO,EACd,GAAG,CAAC,EAAE,aAAa,GAClB,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAG1B"}

package/dist/coerce.js

@@ -0,0 +1,207 @@
+import { z } from "zod";
+import { createContext, failure, describeType, } from "./types.js";
+import { coerceString, coerceNumber, coerceInt, coerceBoolean, coerceNull, coerceLiteral, } from "./coercers/primitive.js";
+import { coerceArray, coerceTuple } from "./coercers/array.js";
+import { coerceObject, coerceRecord } from "./coercers/object.js";
+import { coerceUnion, coerceOptional, coerceNullable, coerceDefault } from "./coercers/union.js";
+import { coerceEnum, coerceNativeEnum } from "./coercers/enum.js";
+/**
+ * Coerce a value to match a Zod schema.
+ * This is the main entry point for schema-aligned coercion.
+ */
+export function coerceToSchema(schema, value, ctx) {
+    const context = ctx ?? createContext();
+    return coerceZodType(schema, value, context);
+}
+/**
+ * Internal dispatcher for Zod types.
+ */
+function coerceZodType(schema, value, ctx) {
+    const def = schema._def;
+    const typeName = def.typeName;
+    switch (typeName) {
+        // Primitives
+        case z.ZodFirstPartyTypeKind.ZodString:
+            return coerceString(value, ctx);
+        case z.ZodFirstPartyTypeKind.ZodNumber:
+            return coerceNumber(value, ctx);
+        case z.ZodFirstPartyTypeKind.ZodBigInt:
+            return coerceInt(value, ctx); // Use int coercion for bigint
+        case z.ZodFirstPartyTypeKind.ZodBoolean:
+            return coerceBoolean(value, ctx);
+        case z.ZodFirstPartyTypeKind.ZodNull:
+            return coerceNull(value, ctx);
+        case z.ZodFirstPartyTypeKind.ZodUndefined:
+            if (value === undefined || value === null) {
+                return { success: true, value: undefined, flags: ctx.flags };
+            }
+            return failure("Expected undefined", ctx, "undefined", describeType(value));
+        case z.ZodFirstPartyTypeKind.ZodVoid:
+            return { success: true, value: undefined, flags: ctx.flags };
+        case z.ZodFirstPartyTypeKind.ZodAny:
+        case z.ZodFirstPartyTypeKind.ZodUnknown:
+            return { success: true, value, flags: ctx.flags };
+        case z.ZodFirstPartyTypeKind.ZodNever:
+            return failure("ZodNever cannot match any value", ctx, "never", describeType(value));
+        // Literals
+        case z.ZodFirstPartyTypeKind.ZodLiteral:
+            return coerceLiteral(value, def.value, ctx);
+        // Arrays
+        case z.ZodFirstPartyTypeKind.ZodArray:
+            return coerceArray(value, (v, c) => coerceZodType(def.type, v, c), ctx);
+        // Tuples
+        case z.ZodFirstPartyTypeKind.ZodTuple: {
+            const items = def.items;
+            const coercers = items.map((item) => (v, c) => coerceZodType(item, v, c));
+            return coerceTuple(value, coercers, ctx);
+        }
+        // Objects
+        case z.ZodFirstPartyTypeKind.ZodObject: {
+            const shape = def.shape();
+            const objectSchema = {};
+            for (const [key, propSchema] of Object.entries(shape)) {
+                const isOptional = propSchema.isOptional();
+                const hasDefault = propSchema._def.typeName === z.ZodFirstPartyTypeKind.ZodDefault;
+                objectSchema[key] = {
+                    coercer: (v, c) => coerceZodType(propSchema, v, c),
+                    optional: isOptional,
+                    ...(hasDefault ? { default: propSchema._def.defaultValue() } : {}),
+                };
+            }
+            return coerceObject(value, objectSchema, ctx);
+        }
+        // Records
+        case z.ZodFirstPartyTypeKind.ZodRecord:
+            return coerceRecord(value, (v, c) => coerceZodType(def.valueType, v, c), ctx);
+        // Maps
+        case z.ZodFirstPartyTypeKind.ZodMap:
+            // Treat as record for now
+            return coerceRecord(value, (v, c) => coerceZodType(def.valueType, v, c), ctx);
+        // Unions
+        case z.ZodFirstPartyTypeKind.ZodUnion: {
+            const options = def.options;
+            const coercers = options.map((opt) => (v, c) => coerceZodType(opt, v, c));
+            return coerceUnion(value, coercers, ctx);
+        }
+        case z.ZodFirstPartyTypeKind.ZodDiscriminatedUnion: {
+            const options = def.options;
+            const coercers = options.map((opt) => (v, c) => coerceZodType(opt, v, c));
+            return coerceUnion(value, coercers, ctx);
+        }
+        // Optionals and Nullables
+        case z.ZodFirstPartyTypeKind.ZodOptional:
+            return coerceOptional(value, (v, c) => coerceZodType(def.innerType, v, c), ctx);
+        case z.ZodFirstPartyTypeKind.ZodNullable:
+            return coerceNullable(value, (v, c) => coerceZodType(def.innerType, v, c), ctx);
+        // Defaults
+        case z.ZodFirstPartyTypeKind.ZodDefault:
+            return coerceDefault(value, (v, c) => coerceZodType(def.innerType, v, c), def.defaultValue(), ctx);
+        // Catch
+        case z.ZodFirstPartyTypeKind.ZodCatch: {
+            const result = coerceZodType(def.innerType, value, ctx);
+            if (result.success)
+                return result;
+            return { success: true, value: def.catchValue({ error: result.error, input: value }), flags: ctx.flags };
+        }
+        // Enums
+        case z.ZodFirstPartyTypeKind.ZodEnum:
+            return coerceEnum(value, def.values, ctx);
+        case z.ZodFirstPartyTypeKind.ZodNativeEnum:
+            return coerceNativeEnum(value, def.values, ctx);
+        // Effects/Transforms
+        case z.ZodFirstPartyTypeKind.ZodEffects: {
+            // First coerce the inner type
+            const innerResult = coerceZodType(def.schema, value, ctx);
+            if (!innerResult.success)
+                return innerResult;
+            // Then apply the effect
+            // Note: We only handle refinements here, not transforms
+            // Transforms would need async support
+            if (def.effect.type === "refinement") {
+                const refinement = def.effect.refinement;
+                try {
+                    const isValid = refinement(innerResult.value);
+                    if (!isValid) {
+                        return failure("Refinement failed", ctx, "refined value", describeType(innerResult.value));
+                    }
+                }
+                catch (e) {
+                    return failure(`Refinement error: ${e instanceof Error ? e.message : String(e)}`, ctx, "refined value", describeType(innerResult.value));
+                }
+            }
+            return innerResult;
+        }
+        // Lazy
+        case z.ZodFirstPartyTypeKind.ZodLazy:
+            return coerceZodType(def.getter(), value, ctx);
+        // Branded
+        case z.ZodFirstPartyTypeKind.ZodBranded:
+            return coerceZodType(def.type, value, ctx);
+        // Pipeline
+        case z.ZodFirstPartyTypeKind.ZodPipeline: {
+            const inResult = coerceZodType(def.in, value, ctx);
+            if (!inResult.success)
+                return inResult;
+            return coerceZodType(def.out, inResult.value, ctx);
+        }
+        // Readonly
+        case z.ZodFirstPartyTypeKind.ZodReadonly:
+            return coerceZodType(def.innerType, value, ctx);
+        // Date - special handling
+        case z.ZodFirstPartyTypeKind.ZodDate: {
+            if (value instanceof Date) {
+                if (isNaN(value.getTime())) {
+                    return failure("Invalid Date", ctx, "Date", "Invalid Date");
+                }
+                return { success: true, value, flags: ctx.flags };
+            }
+            if (typeof value === "string" || typeof value === "number") {
+                const date = new Date(value);
+                if (isNaN(date.getTime())) {
+                    return failure(`Cannot parse "${value}" as Date`, ctx, "Date", describeType(value));
+                }
+                return { success: true, value: date, flags: ctx.flags };
+            }
+            return failure("Expected Date", ctx, "Date", describeType(value));
+        }
+        // Intersection - coerce to both types
+        case z.ZodFirstPartyTypeKind.ZodIntersection: {
+            const leftResult = coerceZodType(def.left, value, ctx);
+            if (!leftResult.success)
+                return leftResult;
+            const rightResult = coerceZodType(def.right, leftResult.value, ctx);
+            if (!rightResult.success)
+                return rightResult;
+            // Merge results for objects
+            if (typeof leftResult.value === "object" && typeof rightResult.value === "object") {
+                return { success: true, value: { ...leftResult.value, ...rightResult.value }, flags: ctx.flags };
+            }
+            return rightResult;
+        }
+        // Set
+        case z.ZodFirstPartyTypeKind.ZodSet: {
+            const arrayResult = coerceArray(value, (v, c) => coerceZodType(def.valueType, v, c), ctx);
+            if (!arrayResult.success)
+                return arrayResult;
+            return { success: true, value: new Set(arrayResult.value), flags: ctx.flags };
+        }
+        // Promise - just pass through
+        case z.ZodFirstPartyTypeKind.ZodPromise:
+            return { success: true, value, flags: ctx.flags };
+        // Function - just pass through
+        case z.ZodFirstPartyTypeKind.ZodFunction:
+            if (typeof value === "function") {
+                return { success: true, value, flags: ctx.flags };
+            }
+            return failure("Expected function", ctx, "function", describeType(value));
+        // Symbol
+        case z.ZodFirstPartyTypeKind.ZodSymbol:
+            if (typeof value === "symbol") {
+                return { success: true, value, flags: ctx.flags };
+            }
+            return failure("Expected symbol", ctx, "symbol", describeType(value));
+        default:
+            return failure(`Unsupported Zod type: ${typeName}`, ctx, typeName, describeType(value));
+    }
+}
+//# sourceMappingURL=coerce.js.map

package/dist/coerce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coerce.js","sourceRoot":"","sources":["../src/coerce.ts"],"names":[],"mappings":"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"}

package/dist/coercers/array.d.ts

@@ -0,0 +1,20 @@
+import { type CoerceContext, type CoerceResult } from "../types.js";
+export type ElementCoercer<T> = (value: unknown, ctx: CoerceContext) => CoerceResult<T>;
+/**
+ * LLMs often return a single item when we expect an array (especially when
+ * there's only one result). Rather than failing, we wrap it in an array.
+ */
+export declare function coerceArray<T>(value: unknown, elementCoercer: ElementCoercer<T>, ctx: CoerceContext): CoerceResult<T[]>;
+/**
+ * The reverse case: schema expects single value but LLM returned [value].
+ * If the array has exactly one element, unwrap it.
+ */
+export declare function coerceArrayToSingle<T>(value: unknown, elementCoercer: ElementCoercer<T>, ctx: CoerceContext): CoerceResult<T>;
+/**
+ * Tuples are fixed-length arrays where each position has a specific type.
+ * We validate length matches and coerce each element to its expected type.
+ */
+export declare function coerceTuple<T extends unknown[]>(value: unknown, elementCoercers: {
+    [K in keyof T]: ElementCoercer<T[K]>;
+}, ctx: CoerceContext): CoerceResult<T>;
+//# sourceMappingURL=array.d.ts.map

package/dist/coercers/array.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"array.d.ts","sourceRoot":"","sources":["../../src/coercers/array.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,YAAY,EAKlB,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,KAAK,YAAY,CAAC,CAAC,CAAC,CAAC;AAExF;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,KAAK,EAAE,OAAO,EACd,cAAc,EAAE,cAAc,CAAC,CAAC,CAAC,EACjC,GAAG,EAAE,aAAa,GACjB,YAAY,CAAC,CAAC,EAAE,CAAC,CAiCnB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,KAAK,EAAE,OAAO,EACd,cAAc,EAAE,cAAc,CAAC,CAAC,CAAC,EACjC,GAAG,EAAE,aAAa,GACjB,YAAY,CAAC,CAAC,CAAC,CAqBjB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,OAAO,EAAE,EAC7C,KAAK,EAAE,OAAO,EACd,eAAe,EAAE;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,EACzD,GAAG,EAAE,aAAa,GACjB,YAAY,CAAC,CAAC,CAAC,CAgCjB"}

package/dist/coercers/array.js

@@ -0,0 +1,77 @@
+import { Flag } from "../flags.js";
+import { childContext, success, failure, describeType, } from "../types.js";
+/**
+ * LLMs often return a single item when we expect an array (especially when
+ * there's only one result). Rather than failing, we wrap it in an array.
+ */
+export function coerceArray(value, elementCoercer, ctx) {
+    if (value === null || value === undefined) {
+        return failure("Expected array, got null/undefined", ctx, "array", describeType(value));
+    }
+    if (Array.isArray(value)) {
+        const results = [];
+        for (let i = 0; i < value.length; i++) {
+            // Each element gets its own path context for error reporting
+            const elementCtx = childContext(ctx, i);
+            const result = elementCoercer(value[i], elementCtx);
+            if (!result.success) {
+                return result;
+            }
+            results.push(result.value);
+        }
+        return success(results, ctx);
+    }
+    // Single value → wrap in array (common LLM behavior)
+    ctx.flags.push({ flag: Flag.SingleToArray });
+    const elementCtx = childContext(ctx, 0);
+    const result = elementCoercer(value, elementCtx);
+    if (!result.success) {
+        return result;
+    }
+    return success([result.value], ctx);
+}
+/**
+ * The reverse case: schema expects single value but LLM returned [value].
+ * If the array has exactly one element, unwrap it.
+ */
+export function coerceArrayToSingle(value, elementCoercer, ctx) {
+    if (!Array.isArray(value)) {
+        return elementCoercer(value, ctx);
+    }
+    if (value.length === 0) {
+        return failure("Expected single value, got empty array", ctx, "single value", "empty array");
+    }
+    if (value.length > 1) {
+        return failure(`Expected single value, got array with ${value.length} elements`, ctx, "single value", `array[${value.length}]`);
+    }
+    ctx.flags.push({ flag: Flag.ArrayToSingle });
+    const elementCtx = childContext(ctx, 0);
+    return elementCoercer(value[0], elementCtx);
+}
+/**
+ * Tuples are fixed-length arrays where each position has a specific type.
+ * We validate length matches and coerce each element to its expected type.
+ */
+export function coerceTuple(value, elementCoercers, ctx) {
+    if (!Array.isArray(value)) {
+        return failure("Expected tuple (array), got " + describeType(value), ctx, "tuple", describeType(value));
+    }
+    if (value.length !== elementCoercers.length) {
+        return failure(`Expected tuple of length ${elementCoercers.length}, got length ${value.length}`, ctx, `tuple[${elementCoercers.length}]`, `array[${value.length}]`);
+    }
+    const results = [];
+    for (let i = 0; i < elementCoercers.length; i++) {
+        const elementCtx = childContext(ctx, i);
+        const coercer = elementCoercers[i];
+        if (!coercer) {
+            return failure(`Missing coercer for index ${i}`, ctx, "coercer", "undefined");
+        }
+        const result = coercer(value[i], elementCtx);
+        if (!result.success) {
+            return result;
+        }
+        results.push(result.value);
+    }
+    return success(results, ctx);
+}
+//# sourceMappingURL=array.js.map

package/dist/coercers/array.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"array.js","sourceRoot":"","sources":["../../src/coercers/array.ts"],"names":[],"mappings":"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"}

package/dist/coercers/enum.d.ts

@@ -0,0 +1,12 @@
+import { type CoerceContext, type CoerceResult } from "../types.js";
+/**
+ * LLMs often return enum values with wrong casing - "PENDING" instead of "pending".
+ * Rather than failing, we do case-insensitive matching and track when it happens.
+ */
+export declare function coerceEnum<T extends string>(value: unknown, allowedValues: readonly T[], ctx: CoerceContext): CoerceResult<T>;
+/**
+ * TypeScript enums have reverse mappings for numeric values.
+ * We filter those out and match against both keys and values.
+ */
+export declare function coerceNativeEnum<T extends Record<string, string | number>>(value: unknown, enumObject: T, ctx: CoerceContext): CoerceResult<T[keyof T]>;
+//# sourceMappingURL=enum.d.ts.map

package/dist/coercers/enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enum.d.ts","sourceRoot":"","sources":["../../src/coercers/enum.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,YAAY,EAIlB,MAAM,aAAa,CAAC;AAErB;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACzC,KAAK,EAAE,OAAO,EACd,aAAa,EAAE,SAAS,CAAC,EAAE,EAC3B,GAAG,EAAE,aAAa,GACjB,YAAY,CAAC,CAAC,CAAC,CA8BjB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,EACxE,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,CAAC,EACb,GAAG,EAAE,aAAa,GACjB,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CA4C1B"}

package/dist/coercers/enum.js

@@ -0,0 +1,62 @@
+import { Flag } from "../flags.js";
+import { success, failure, describeType, } from "../types.js";
+/**
+ * LLMs often return enum values with wrong casing - "PENDING" instead of "pending".
+ * Rather than failing, we do case-insensitive matching and track when it happens.
+ */
+export function coerceEnum(value, allowedValues, ctx) {
+    if (typeof value !== "string") {
+        return failure(`Expected enum value, got ${describeType(value)}`, ctx, allowedValues.join(" | "), describeType(value));
+    }
+    // Fast path: exact match
+    if (allowedValues.includes(value)) {
+        return success(value, ctx);
+    }
+    // Fallback: case-insensitive match
+    const lowerValue = value.toLowerCase();
+    const match = allowedValues.find((v) => v.toLowerCase() === lowerValue);
+    if (match) {
+        ctx.flags.push({ flag: Flag.EnumCaseInsensitive, input: value, matched: match });
+        return success(match, ctx);
+    }
+    return failure(`Value "${value}" is not a valid enum value`, ctx, allowedValues.join(" | "), `"${value}"`);
+}
+/**
+ * TypeScript enums have reverse mappings for numeric values.
+ * We filter those out and match against both keys and values.
+ */
+export function coerceNativeEnum(value, enumObject, ctx) {
+    // Filter out numeric keys (reverse mappings from numeric enums)
+    const enumValues = Object.entries(enumObject)
+        .filter(([key]) => isNaN(Number(key)))
+        .map(([_, val]) => val);
+    if (enumValues.includes(value)) {
+        return success(value, ctx);
+    }
+    // Try matching by key or value name, case-insensitive
+    if (typeof value === "string") {
+        const lowerValue = value.toLowerCase();
+        for (const [key, enumValue] of Object.entries(enumObject)) {
+            if (isNaN(Number(key))) {
+                // Match against enum key name
+                if (key.toLowerCase() === lowerValue) {
+                    ctx.flags.push({ flag: Flag.EnumCaseInsensitive, input: value, matched: key });
+                    return success(enumValue, ctx);
+                }
+                // Match against string enum value
+                if (typeof enumValue === "string" && enumValue.toLowerCase() === lowerValue) {
+                    ctx.flags.push({ flag: Flag.EnumCaseInsensitive, input: value, matched: enumValue });
+                    return success(enumValue, ctx);
+                }
+            }
+        }
+    }
+    // For numeric enums, also accept the number directly
+    if (typeof value === "number") {
+        if (enumValues.includes(value)) {
+            return success(value, ctx);
+        }
+    }
+    return failure(`Value "${String(value)}" is not a valid enum value`, ctx, enumValues.map((v) => String(v)).join(" | "), describeType(value));
+}
+//# sourceMappingURL=enum.js.map

package/dist/coercers/enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enum.js","sourceRoot":"","sources":["../../src/coercers/enum.ts"],"names":[],"mappings":"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"}

package/dist/coercers/object.d.ts

@@ -0,0 +1,23 @@
+import { type CoerceContext, type CoerceResult } from "../types.js";
+export type PropertyCoercer<T> = (value: unknown, ctx: CoerceContext) => CoerceResult<T>;
+export interface ObjectSchema {
+    [key: string]: {
+        coercer: PropertyCoercer<unknown>;
+        optional: boolean;
+        default?: unknown;
+    };
+}
+/**
+ * LLMs often add extra fields we didn't ask for (explanations, confidence scores,
+ * reasoning). We ignore these rather than failing, but track them in flags.
+ *
+ * Missing optional fields are also tracked - callers can detect when defaults
+ * were used vs when the LLM explicitly provided values.
+ */
+export declare function coerceObject<T extends Record<string, unknown>>(value: unknown, schema: ObjectSchema, ctx: CoerceContext): CoerceResult<T>;
+/**
+ * For z.record() - a map with string keys and uniform value types.
+ * Unlike objects, we don't have a fixed schema - just coerce each value.
+ */
+export declare function coerceRecord<T>(value: unknown, valueCoercer: PropertyCoercer<T>, ctx: CoerceContext): CoerceResult<Record<string, T>>;
+//# sourceMappingURL=object.d.ts.map

package/dist/coercers/object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object.d.ts","sourceRoot":"","sources":["../../src/coercers/object.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,YAAY,EAKlB,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,KAAK,YAAY,CAAC,CAAC,CAAC,CAAC;AAEzF,MAAM,WAAW,YAAY;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG;QACb,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;QAClC,QAAQ,EAAE,OAAO,CAAC;QAClB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;CACH;AAMD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5D,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,YAAY,EACpB,GAAG,EAAE,aAAa,GACjB,YAAY,CAAC,CAAC,CAAC,CAoDjB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,eAAe,CAAC,CAAC,CAAC,EAChC,GAAG,EAAE,aAAa,GACjB,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAwBjC"}