@hoangvu12/yomi 0.1.0

package/dist/coercers/object.js

@@ -0,0 +1,75 @@
+import { Flag } from "../flags.js";
+import { childContext, success, failure, describeType, } from "../types.js";
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * 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 function coerceObject(value, schema, ctx) {
+    if (!isPlainObject(value)) {
+        return failure(`Expected object, got ${describeType(value)}`, ctx, "object", describeType(value));
+    }
+    const result = {};
+    const inputKeys = new Set(Object.keys(value));
+    const schemaKeys = new Set(Object.keys(schema));
+    for (const key of schemaKeys) {
+        const propSchema = schema[key];
+        if (!propSchema)
+            continue;
+        const propCtx = childContext(ctx, key);
+        const inputValue = value[key];
+        if (!(key in value) || inputValue === undefined) {
+            if (propSchema.optional) {
+                if ("default" in propSchema) {
+                    ctx.flags.push({ flag: Flag.DefaultUsed });
+                    result[key] = propSchema.default;
+                }
+                else {
+                    ctx.flags.push({ flag: Flag.MissingOptionalKey });
+                    // Leave undefined - don't add to result
+                }
+                continue;
+            }
+            else {
+                return failure(`Missing required property "${key}"`, propCtx, "value", "undefined");
+            }
+        }
+        const propResult = propSchema.coercer(inputValue, propCtx);
+        if (!propResult.success) {
+            return propResult;
+        }
+        result[key] = propResult.value;
+        inputKeys.delete(key);
+    }
+    // Track extra keys so callers know the LLM added unrequested fields
+    if (inputKeys.size > 0) {
+        const extraKeys = Array.from(inputKeys);
+        ctx.flags.push({ flag: Flag.ExtraKeysIgnored, keys: extraKeys });
+    }
+    return success(result, ctx);
+}
+/**
+ * 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 function coerceRecord(value, valueCoercer, ctx) {
+    if (!isPlainObject(value)) {
+        return failure(`Expected object, got ${describeType(value)}`, ctx, "object", describeType(value));
+    }
+    const result = {};
+    for (const [key, val] of Object.entries(value)) {
+        const propCtx = childContext(ctx, key);
+        const propResult = valueCoercer(val, propCtx);
+        if (!propResult.success) {
+            return propResult;
+        }
+        result[key] = propResult.value;
+    }
+    return success(result, ctx);
+}
+//# sourceMappingURL=object.js.map

package/dist/coercers/object.js.map

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

package/dist/coercers/primitive.d.ts

@@ -0,0 +1,33 @@
+import { type CoerceContext, type CoerceResult } from "../types.js";
+/**
+ * String is the most permissive type - almost anything can become a string.
+ * This is intentional since LLMs generate text, so stringification is natural.
+ */
+export declare function coerceString(value: unknown, ctx: CoerceContext): CoerceResult<string>;
+/**
+ * LLMs often return numbers as strings because they're generating text.
+ * "25" is obviously meant to be 25, so we parse it.
+ */
+export declare function coerceNumber(value: unknown, ctx: CoerceContext): CoerceResult<number>;
+/**
+ * When the schema expects an integer but LLM returns a float,
+ * rounding is more useful than failing. We track the precision loss.
+ */
+export declare function coerceInt(value: unknown, ctx: CoerceContext): CoerceResult<number>;
+/**
+ * LLMs return booleans in many forms: "true", "yes", "1", etc.
+ * We accept common truthy/falsy representations humans use.
+ */
+export declare function coerceBoolean(value: unknown, ctx: CoerceContext): CoerceResult<boolean>;
+/**
+ * JSON has null but TypeScript often uses undefined.
+ * We treat them as interchangeable for flexibility.
+ */
+export declare function coerceNull(value: unknown, ctx: CoerceContext): CoerceResult<null>;
+export declare function coerceUndefined(value: unknown, ctx: CoerceContext): CoerceResult<undefined>;
+/**
+ * For z.literal(42), we first try exact match, then try coercing
+ * to the literal's type. So z.literal(42) accepts both 42 and "42".
+ */
+export declare function coerceLiteral<T extends string | number | boolean>(value: unknown, literal: T, ctx: CoerceContext): CoerceResult<T>;
+//# sourceMappingURL=primitive.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"primitive.d.ts","sourceRoot":"","sources":["../../src/coercers/primitive.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,YAAY,EAIlB,MAAM,aAAa,CAAC;AAErB;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,GAAG,YAAY,CAAC,MAAM,CAAC,CA2BrF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,GAAG,YAAY,CAAC,MAAM,CAAC,CA6BrF;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,GAAG,YAAY,CAAC,MAAM,CAAC,CAclF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,GAAG,YAAY,CAAC,OAAO,CAAC,CA6CvF;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,GAAG,YAAY,CAAC,IAAI,CAAC,CAgBjF;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,GAAG,YAAY,CAAC,SAAS,CAAC,CAgB3F;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,OAAO,EAC/D,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,CAAC,EACV,GAAG,EAAE,aAAa,GACjB,YAAY,CAAC,CAAC,CAAC,CA6BjB"}

package/dist/coercers/primitive.js

@@ -0,0 +1,160 @@
+import { Flag } from "../flags.js";
+import { success, failure, describeType, } from "../types.js";
+/**
+ * String is the most permissive type - almost anything can become a string.
+ * This is intentional since LLMs generate text, so stringification is natural.
+ */
+export function coerceString(value, ctx) {
+    if (typeof value === "string") {
+        return success(value, ctx);
+    }
+    // Numbers and booleans have obvious string representations
+    if (typeof value === "number") {
+        ctx.flags.push({ flag: Flag.NumberToString });
+        return success(String(value), ctx);
+    }
+    if (typeof value === "boolean") {
+        ctx.flags.push({ flag: Flag.BoolToString });
+        return success(String(value), ctx);
+    }
+    // null/undefined have no meaningful string form - fail rather than return "null"
+    if (value === null || value === undefined) {
+        return failure("Expected string, got null/undefined", ctx, "string", describeType(value));
+    }
+    return failure(`Cannot coerce ${describeType(value)} to string`, ctx, "string", describeType(value));
+}
+/**
+ * LLMs often return numbers as strings because they're generating text.
+ * "25" is obviously meant to be 25, so we parse it.
+ */
+export function coerceNumber(value, ctx) {
+    if (typeof value === "number") {
+        // NaN is technically a number but useless - treat as error
+        if (Number.isNaN(value)) {
+            return failure("Got NaN", ctx, "number", "NaN");
+        }
+        return success(value, ctx);
+    }
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        const parsed = parseFloat(trimmed);
+        if (!Number.isNaN(parsed)) {
+            ctx.flags.push({ flag: Flag.StringToNumber });
+            return success(parsed, ctx);
+        }
+        return failure(`Cannot parse "${trimmed}" as number`, ctx, "number", "string");
+    }
+    if (value === null || value === undefined) {
+        return failure("Expected number, got null/undefined", ctx, "number", describeType(value));
+    }
+    return failure(`Cannot coerce ${describeType(value)} to number`, ctx, "number", describeType(value));
+}
+/**
+ * When the schema expects an integer but LLM returns a float,
+ * rounding is more useful than failing. We track the precision loss.
+ */
+export function coerceInt(value, ctx) {
+    const numResult = coerceNumber(value, ctx);
+    if (!numResult.success) {
+        return numResult;
+    }
+    const num = numResult.value;
+    if (Number.isInteger(num)) {
+        return success(num, ctx);
+    }
+    const rounded = Math.round(num);
+    ctx.flags.push({ flag: Flag.FloatToInt, original: num, rounded });
+    return success(rounded, ctx);
+}
+/**
+ * LLMs return booleans in many forms: "true", "yes", "1", etc.
+ * We accept common truthy/falsy representations humans use.
+ */
+export function coerceBoolean(value, ctx) {
+    if (typeof value === "boolean") {
+        return success(value, ctx);
+    }
+    if (typeof value === "string") {
+        const lower = value.toLowerCase().trim();
+        // Common truthy strings across languages and conventions
+        if (lower === "true" || lower === "yes" || lower === "1" || lower === "on") {
+            ctx.flags.push({ flag: Flag.StringToBool });
+            return success(true, ctx);
+        }
+        if (lower === "false" || lower === "no" || lower === "0" || lower === "off") {
+            ctx.flags.push({ flag: Flag.StringToBool });
+            return success(false, ctx);
+        }
+        return failure(`Cannot parse "${value}" as boolean`, ctx, "boolean", "string");
+    }
+    // 1/0 are common boolean representations in APIs
+    if (typeof value === "number") {
+        if (value === 1) {
+            ctx.flags.push({ flag: Flag.StringToBool });
+            return success(true, ctx);
+        }
+        if (value === 0) {
+            ctx.flags.push({ flag: Flag.StringToBool });
+            return success(false, ctx);
+        }
+        return failure(`Cannot coerce number ${value} to boolean`, ctx, "boolean", "number");
+    }
+    if (value === null || value === undefined) {
+        return failure("Expected boolean, got null/undefined", ctx, "boolean", describeType(value));
+    }
+    return failure(`Cannot coerce ${describeType(value)} to boolean`, ctx, "boolean", describeType(value));
+}
+/**
+ * JSON has null but TypeScript often uses undefined.
+ * We treat them as interchangeable for flexibility.
+ */
+export function coerceNull(value, ctx) {
+    if (value === null) {
+        return success(null, ctx);
+    }
+    if (value === undefined) {
+        ctx.flags.push({ flag: Flag.NullToUndefined });
+        return success(null, ctx);
+    }
+    return failure(`Expected null, got ${describeType(value)}`, ctx, "null", describeType(value));
+}
+export function coerceUndefined(value, ctx) {
+    if (value === undefined) {
+        return success(undefined, ctx);
+    }
+    if (value === null) {
+        ctx.flags.push({ flag: Flag.NullToUndefined });
+        return success(undefined, ctx);
+    }
+    return failure(`Expected undefined, got ${describeType(value)}`, ctx, "undefined", describeType(value));
+}
+/**
+ * For z.literal(42), we first try exact match, then try coercing
+ * to the literal's type. So z.literal(42) accepts both 42 and "42".
+ */
+export function coerceLiteral(value, literal, ctx) {
+    if (value === literal) {
+        return success(literal, ctx);
+    }
+    // Try coercing to the literal's type, then check equality
+    if (typeof literal === "string") {
+        const result = coerceString(value, ctx);
+        if (result.success && result.value === literal) {
+            return success(literal, ctx);
+        }
+    }
+    else if (typeof literal === "number") {
+        const result = coerceNumber(value, ctx);
+        if (result.success && result.value === literal) {
+            return success(literal, ctx);
+        }
+    }
+    else if (typeof literal === "boolean") {
+        const result = coerceBoolean(value, ctx);
+        if (result.success && result.value === literal) {
+            return success(literal, ctx);
+        }
+    }
+    return failure(`Expected literal ${JSON.stringify(literal)}, got ${JSON.stringify(value)}`, ctx, JSON.stringify(literal), describeType(value));
+}
+//# sourceMappingURL=primitive.js.map

package/dist/coercers/primitive.js.map

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

package/dist/coercers/union.d.ts

@@ -0,0 +1,35 @@
+import { type CoerceContext, type CoerceResult } from "../types.js";
+export type Coercer<T> = (value: unknown, ctx: CoerceContext) => CoerceResult<T>;
+/**
+ * For z.union([A, B, C]), we try each type in order and return the first success.
+ *
+ * Order matters! If you have z.union([z.string(), z.number()]), a number will
+ * become a string because string coercion accepts numbers. Put more specific
+ * types first if you want them to take priority.
+ *
+ * We use a temporary context for each attempt so failed attempts don't
+ * pollute the flags of the successful one.
+ */
+export declare function coerceUnion<T>(value: unknown, coercers: Coercer<T>[], ctx: CoerceContext): CoerceResult<T>;
+/**
+ * For z.optional(T), both undefined and null become undefined.
+ * This bridges JSON's null with TypeScript's optional fields.
+ */
+export declare function coerceOptional<T>(value: unknown, innerCoercer: Coercer<T>, ctx: CoerceContext): CoerceResult<T | undefined>;
+/**
+ * For z.nullable(T), both null and undefined become null.
+ * The inverse of optional - useful when the schema explicitly expects null.
+ */
+export declare function coerceNullable<T>(value: unknown, innerCoercer: Coercer<T>, ctx: CoerceContext): CoerceResult<T | null>;
+/**
+ * For z.default(value), use the default when input is missing.
+ * Tracks when defaults are used so callers can distinguish explicit
+ * values from fallbacks.
+ */
+export declare function coerceDefault<T>(value: unknown, innerCoercer: Coercer<T>, defaultValue: T, ctx: CoerceContext): CoerceResult<T>;
+/**
+ * For z.catch(value), return the catch value if coercion fails.
+ * Unlike default (which handles missing values), catch handles invalid values.
+ */
+export declare function coerceCatch<T>(value: unknown, innerCoercer: Coercer<T>, catchValue: T, ctx: CoerceContext): CoerceResult<T>;
+//# sourceMappingURL=union.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"union.d.ts","sourceRoot":"","sources":["../../src/coercers/union.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,YAAY,EAMlB,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,KAAK,YAAY,CAAC,CAAC,CAAC,CAAC;AAEjF;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EACtB,GAAG,EAAE,aAAa,GACjB,YAAY,CAAC,CAAC,CAAC,CAyBjB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC,EACxB,GAAG,EAAE,aAAa,GACjB,YAAY,CAAC,CAAC,GAAG,SAAS,CAAC,CAY7B;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC,EACxB,GAAG,EAAE,aAAa,GACjB,YAAY,CAAC,CAAC,GAAG,IAAI,CAAC,CAWxB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC,EACxB,YAAY,EAAE,CAAC,EACf,GAAG,EAAE,aAAa,GACjB,YAAY,CAAC,CAAC,CAAC,CAOjB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC,EACxB,UAAU,EAAE,CAAC,EACb,GAAG,EAAE,aAAa,GACjB,YAAY,CAAC,CAAC,CAAC,CASjB"}

package/dist/coercers/union.js

@@ -0,0 +1,82 @@
+import { Flag } from "../flags.js";
+import { success, failure, createContext, describeType, } from "../types.js";
+/**
+ * For z.union([A, B, C]), we try each type in order and return the first success.
+ *
+ * Order matters! If you have z.union([z.string(), z.number()]), a number will
+ * become a string because string coercion accepts numbers. Put more specific
+ * types first if you want them to take priority.
+ *
+ * We use a temporary context for each attempt so failed attempts don't
+ * pollute the flags of the successful one.
+ */
+export function coerceUnion(value, coercers, ctx) {
+    const errors = [];
+    for (const coercer of coercers) {
+        const tempCtx = createContext();
+        tempCtx.path = ctx.path;
+        const result = coercer(value, tempCtx);
+        if (result.success) {
+            // Only merge flags from the successful path
+            ctx.flags.push(...tempCtx.flags);
+            return success(result.value, ctx);
+        }
+        errors.push(result);
+    }
+    const expectedTypes = errors.map((e) => e.error.expected).join(" | ");
+    return failure(`Value does not match any union type`, ctx, expectedTypes, describeType(value));
+}
+/**
+ * For z.optional(T), both undefined and null become undefined.
+ * This bridges JSON's null with TypeScript's optional fields.
+ */
+export function coerceOptional(value, innerCoercer, ctx) {
+    if (value === undefined) {
+        return success(undefined, ctx);
+    }
+    // JSON has null, TypeScript has undefined - treat them the same for optional
+    if (value === null) {
+        ctx.flags.push({ flag: Flag.NullToUndefined });
+        return success(undefined, ctx);
+    }
+    return innerCoercer(value, ctx);
+}
+/**
+ * For z.nullable(T), both null and undefined become null.
+ * The inverse of optional - useful when the schema explicitly expects null.
+ */
+export function coerceNullable(value, innerCoercer, ctx) {
+    if (value === null) {
+        return success(null, ctx);
+    }
+    if (value === undefined) {
+        ctx.flags.push({ flag: Flag.NullToUndefined });
+        return success(null, ctx);
+    }
+    return innerCoercer(value, ctx);
+}
+/**
+ * For z.default(value), use the default when input is missing.
+ * Tracks when defaults are used so callers can distinguish explicit
+ * values from fallbacks.
+ */
+export function coerceDefault(value, innerCoercer, defaultValue, ctx) {
+    if (value === undefined || value === null) {
+        ctx.flags.push({ flag: Flag.DefaultUsed });
+        return success(defaultValue, ctx);
+    }
+    return innerCoercer(value, ctx);
+}
+/**
+ * For z.catch(value), return the catch value if coercion fails.
+ * Unlike default (which handles missing values), catch handles invalid values.
+ */
+export function coerceCatch(value, innerCoercer, catchValue, ctx) {
+    const result = innerCoercer(value, ctx);
+    if (result.success) {
+        return result;
+    }
+    ctx.flags.push({ flag: Flag.DefaultUsed });
+    return success(catchValue, ctx);
+}
+//# sourceMappingURL=union.js.map

package/dist/coercers/union.js.map

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

package/dist/flags.d.ts

@@ -0,0 +1,44 @@
+/**
+ * LLMs often return data that doesn't exactly match the expected schema.
+ * Rather than failing, we coerce values to fit - but we track every
+ * transformation so callers can audit what changed and detect potential issues.
+ */
+export declare enum Flag {
+    StringToNumber = "string_to_number",
+    StringToBool = "string_to_bool",
+    NumberToString = "number_to_string",
+    BoolToString = "bool_to_string",
+    FloatToInt = "float_to_int",
+    IntToFloat = "int_to_float",
+    NullToUndefined = "null_to_undefined",
+    SingleToArray = "single_to_array",
+    ArrayToSingle = "array_to_single",
+    JsonRepaired = "json_repaired",
+    ExtractedFromMarkdown = "extracted_from_markdown",
+    ExtractedFromText = "extracted_from_text",
+    ExtraKeysIgnored = "extra_keys_ignored",
+    MissingOptionalKey = "missing_optional_key",
+    DefaultUsed = "default_used",
+    EnumCaseInsensitive = "enum_case_insensitive"
+}
+/**
+ * Some flags benefit from additional context for debugging.
+ * ExtraKeysIgnored tells you which keys, FloatToInt shows the precision lost.
+ */
+export type FlagWithContext = {
+    flag: Flag.ExtraKeysIgnored;
+    keys: string[];
+} | {
+    flag: Flag.FloatToInt;
+    original: number;
+    rounded: number;
+} | {
+    flag: Flag.EnumCaseInsensitive;
+    input: string;
+    matched: string;
+} | {
+    flag: Exclude<Flag, Flag.ExtraKeysIgnored | Flag.FloatToInt | Flag.EnumCaseInsensitive>;
+};
+export declare function flag(f: Flag): FlagWithContext;
+export declare function flagValues(flags: FlagWithContext[]): Flag[];
+//# sourceMappingURL=flags.d.ts.map

package/dist/flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,oBAAY,IAAI;IAGd,cAAc,qBAAqB;IACnC,YAAY,mBAAmB;IAC/B,cAAc,qBAAqB;IACnC,YAAY,mBAAmB;IAG/B,UAAU,iBAAiB;IAC3B,UAAU,iBAAiB;IAG3B,eAAe,sBAAsB;IAIrC,aAAa,oBAAoB;IACjC,aAAa,oBAAoB;IAGjC,YAAY,kBAAkB;IAG9B,qBAAqB,4BAA4B;IACjD,iBAAiB,wBAAwB;IAGzC,gBAAgB,uBAAuB;IACvC,kBAAkB,yBAAyB;IAG3C,WAAW,iBAAiB;IAG5B,mBAAmB,0BAA0B;CAC9C;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,IAAI,CAAC,gBAAgB,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,IAAI,CAAC,mBAAmB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAClE;IAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,mBAAmB,CAAC,CAAA;CAAE,CAAC;AAEhG,wBAAgB,IAAI,CAAC,CAAC,EAAE,IAAI,GAAG,eAAe,CAE7C;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,IAAI,EAAE,CAE3D"}

package/dist/flags.js

@@ -0,0 +1,42 @@
+/**
+ * LLMs often return data that doesn't exactly match the expected schema.
+ * Rather than failing, we coerce values to fit - but we track every
+ * transformation so callers can audit what changed and detect potential issues.
+ */
+export var Flag;
+(function (Flag) {
+    // LLMs frequently return numbers as strings ("25" instead of 25)
+    // because they're generating text, not typed data
+    Flag["StringToNumber"] = "string_to_number";
+    Flag["StringToBool"] = "string_to_bool";
+    Flag["NumberToString"] = "number_to_string";
+    Flag["BoolToString"] = "bool_to_string";
+    // When schema expects int but LLM returns 3.7, we round rather than fail
+    Flag["FloatToInt"] = "float_to_int";
+    Flag["IntToFloat"] = "int_to_float";
+    // JSON has null, TypeScript has undefined - we bridge the gap
+    Flag["NullToUndefined"] = "null_to_undefined";
+    // LLMs sometimes return a single item when an array is expected,
+    // or vice versa - common when there's only one result
+    Flag["SingleToArray"] = "single_to_array";
+    Flag["ArrayToSingle"] = "array_to_single";
+    // The JSON parser had to fix syntax issues (trailing commas, unquoted keys, etc.)
+    Flag["JsonRepaired"] = "json_repaired";
+    // JSON was wrapped in markdown code blocks or surrounded by explanation text
+    Flag["ExtractedFromMarkdown"] = "extracted_from_markdown";
+    Flag["ExtractedFromText"] = "extracted_from_text";
+    // LLMs often add extra fields we didn't ask for (explanations, metadata)
+    Flag["ExtraKeysIgnored"] = "extra_keys_ignored";
+    Flag["MissingOptionalKey"] = "missing_optional_key";
+    // Value was missing/null so we used the schema's default
+    Flag["DefaultUsed"] = "default_used";
+    // LLM returned "RED" but schema expects "red" - close enough
+    Flag["EnumCaseInsensitive"] = "enum_case_insensitive";
+})(Flag || (Flag = {}));
+export function flag(f) {
+    return { flag: f };
+}
+export function flagValues(flags) {
+    return flags.map((f) => f.flag);
+}
+//# sourceMappingURL=flags.js.map

package/dist/flags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags.js","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAN,IAAY,IAoCX;AApCD,WAAY,IAAI;IACd,iEAAiE;IACjE,kDAAkD;IAClD,2CAAmC,CAAA;IACnC,uCAA+B,CAAA;IAC/B,2CAAmC,CAAA;IACnC,uCAA+B,CAAA;IAE/B,yEAAyE;IACzE,mCAA2B,CAAA;IAC3B,mCAA2B,CAAA;IAE3B,8DAA8D;IAC9D,6CAAqC,CAAA;IAErC,iEAAiE;IACjE,sDAAsD;IACtD,yCAAiC,CAAA;IACjC,yCAAiC,CAAA;IAEjC,kFAAkF;IAClF,sCAA8B,CAAA;IAE9B,6EAA6E;IAC7E,yDAAiD,CAAA;IACjD,iDAAyC,CAAA;IAEzC,yEAAyE;IACzE,+CAAuC,CAAA;IACvC,mDAA2C,CAAA;IAE3C,yDAAyD;IACzD,oCAA4B,CAAA;IAE5B,6DAA6D;IAC7D,qDAA6C,CAAA;AAC/C,CAAC,EApCW,IAAI,KAAJ,IAAI,QAoCf;AAYD,MAAM,UAAU,IAAI,CAAC,CAAO;IAC1B,OAAO,EAAE,IAAI,EAAE,CAAC,EAAqB,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAwB;IACjD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { type CoerceResult } from "./types.js";
+import { Flag, type FlagWithContext } from "./flags.js";
+export { Flag, type FlagWithContext } from "./flags.js";
+export { type CoerceResult, type CoerceSuccess, type CoerceFailure, type CoerceError } from "./types.js";
+export { JsonParseError } from "./parse.js";
+/**
+ * Parse result from the main parse function.
+ */
+export type ParseResult<T> = {
+    success: true;
+    data: T;
+    flags: FlagWithContext[];
+} | {
+    success: false;
+    error: ParseError;
+};
+/**
+ * Error from parsing.
+ */
+export interface ParseError {
+    type: "json_parse_error" | "coercion_error";
+    message: string;
+    path?: (string | number)[];
+    expected?: string;
+    received?: string;
+}
+/**
+ * Parse a string into a typed value using a Zod schema.
+ *
+ * This is the main entry point for the Schema-Aligned Parser.
+ * It combines flexible JSON parsing with schema-aligned coercion.
+ *
+ * @example
+ * ```ts
+ * const UserSchema = z.object({
+ *   name: z.string(),
+ *   age: z.number(),
+ * });
+ *
+ * // Handles malformed JSON
+ * const result = parse(UserSchema, `{name: 'John', age: "25",}`);
+ * // → { success: true, data: { name: "John", age: 25 }, flags: [...] }
+ * ```
+ */
+export declare function parse<T extends z.ZodTypeAny>(schema: T, input: string): ParseResult<z.infer<T>>;
+/**
+ * Parse a string into a typed value, throwing on error.
+ *
+ * @throws {Error} If parsing or coercion fails
+ */
+export declare function parseOrThrow<T extends z.ZodTypeAny>(schema: T, input: string): z.infer<T>;
+/**
+ * Coerce an already-parsed value to match a schema.
+ *
+ * Use this when you already have a parsed JavaScript value
+ * and just need schema-aligned coercion.
+ *
+ * @example
+ * ```ts
+ * const data = JSON.parse(rawJson);
+ * const result = coerce(UserSchema, data);
+ * ```
+ */
+export declare function coerce<T extends z.ZodTypeAny>(schema: T, value: unknown): CoerceResult<z.infer<T>>;
+/**
+ * Coerce a value to match a schema, throwing on error.
+ *
+ * @throws {Error} If coercion fails
+ */
+export declare function coerceOrThrow<T extends z.ZodTypeAny>(schema: T, value: unknown): z.infer<T>;
+/**
+ * Check if a parse result has any coercion flags.
+ * Useful for detecting when values were transformed.
+ */
+export declare function hasFlags(result: ParseResult<unknown>): boolean;
+/**
+ * Get the flag types from a parse result.
+ */
+export declare function getFlags(result: ParseResult<unknown>): Flag[];
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,KAAK,YAAY,EAAiB,MAAM,YAAY,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAGxD,OAAO,EAAE,IAAI,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACzG,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IACrB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAC;IAAC,KAAK,EAAE,eAAe,EAAE,CAAA;CAAE,GACpD;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAAC;AAE1C;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,kBAAkB,GAAG,gBAAgB,CAAC;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAC1C,MAAM,EAAE,CAAC,EACT,KAAK,EAAE,MAAM,GACZ,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CA8CzB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EACjD,MAAM,EAAE,CAAC,EACT,KAAK,EAAE,MAAM,GACZ,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAYZ;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAC3C,MAAM,EAAE,CAAC,EACT,KAAK,EAAE,OAAO,GACb,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAE1B;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAClD,MAAM,EAAE,CAAC,EACT,KAAK,EAAE,OAAO,GACb,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CASZ;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,OAAO,CAE9D;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI,EAAE,CAG7D"}