@ptolemy2002/zod-utils 1.3.0 → 1.5.0

package/README.md

@@ -7,6 +7,7 @@ Various utilities for working with Zod schemas.
   - [clone](docs/util/clone.md) - Utility for cloning Zod schemas without affecting the original
   - [function](docs/util/function.md) - Schema factory for validating callable functions with input/output schemas
   - [interpret](docs/util/interpret.md) - Utilities for formatting Zod errors as strings
+  - [issuePathStartsWith](docs/util/issuePathStartsWith.md) - Utility for checking whether a Zod issue path starts with a given prefix
   - [prefixIssuePath](docs/util/prefixIssuePath.md) - Utility for prepending a path prefix to a Zod issue
   - [typeGuards](docs/util/typeGuards.md) - Type guards for Zod-related values
   - [validate](docs/util/validate.md) - Schema-wrapping factories for creating validators

package/dist/function.d.ts

@@ -1,9 +1,23 @@
-import z, { ZodArray, ZodUnknown } from "zod";
+import z, { ZodArray, ZodType, ZodUnknown } from "zod";
 import { $ZodFunctionArgs, $ZodFunctionOut } from "zod/v4/core";
+export type TrialErrorMode = "allow" | "forbid" | "require" | ((e: unknown) => boolean) | {
+    require: (e: unknown) => boolean;
+};
+export type FunctionTrial<Input extends unknown[]> = {
+    id?: string;
+    input: Input;
+    outputSchema?: ZodType;
+    error?: TrialErrorMode;
+    errorStringify?: (e: unknown) => string;
+};
 export type ZodFunctionParseOptions<In extends $ZodFunctionArgs, Out extends $ZodFunctionOut> = {
     input?: In;
     output?: Out;
     inputPath?: PropertyKey | PropertyKey[];
     outputPath?: PropertyKey | PropertyKey[];
 };
-export declare function zodFunctionSchema<In extends $ZodFunctionArgs = ZodArray<ZodUnknown>, Out extends $ZodFunctionOut = ZodUnknown>(options?: ZodFunctionParseOptions<In, Out>): z.ZodPipe<z.ZodAny, z.ZodTransform<(...args: z.core.output<In>) => z.core.output<Out>, any>>;
+export type ZodFunctionSchemaOptions<In extends $ZodFunctionArgs, Out extends $ZodFunctionOut> = {
+    trials?: FunctionTrial<z.infer<In>>[];
+} & ZodFunctionParseOptions<In, Out>;
+export declare function zodValidatedFunction<In extends $ZodFunctionArgs = ZodArray<ZodUnknown>, Out extends $ZodFunctionOut = ZodUnknown>(func: unknown, { inputPath, outputPath, input, output }?: ZodFunctionParseOptions<In, Out>): (...args: z.infer<In>) => z.core.output<Out>;
+export declare function zodFunctionSchema<In extends $ZodFunctionArgs = ZodArray<ZodUnknown>, Out extends $ZodFunctionOut = ZodUnknown>({ trials, inputPath, outputPath, ...options }?: ZodFunctionSchemaOptions<In, Out>): z.ZodPipe<z.ZodAny, z.ZodTransform<(...args: z.core.output<In>) => z.core.output<Out>, any>>;

package/dist/function.js

@@ -36,12 +36,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.zodValidatedFunction = zodValidatedFunction;
 exports.zodFunctionSchema = zodFunctionSchema;
 const zod_1 = __importStar(require("zod"));
 const typeGuards_1 = require("./typeGuards");
 const prefixIssuePath_1 = require("./prefixIssuePath");
+const issuePathStartsWith_1 = require("./issuePathStartsWith");
 const is_callable_1 = __importDefault(require("is-callable"));
-function zodFunctionParse(func, { inputPath = "args", outputPath = "return", input = zod_1.default.array(zod_1.default.unknown()), output = zod_1.default.unknown() }) {
+const interpret_1 = require("./interpret");
+function zodValidatedFunction(func, { inputPath = "args", outputPath = "return", input = zod_1.default.array(zod_1.default.unknown()), output = zod_1.default.unknown() } = {}) {
     if (!(0, is_callable_1.default)(func)) {
         throw new zod_1.ZodError([{
                 message: `Expected a callable function, but received ${typeof func}`,
@@ -51,32 +54,114 @@ function zodFunctionParse(func, { inputPath = "args", outputPath = "return", inp
             }]);
     }
     const functionFactory = zod_1.default.function({ input, output });
-    const wrappedFunction = (setReachedCaller, ...args) => {
+    const wrappedFunction = (setReachedCaller, setFinishedCall, ...args) => {
         setReachedCaller(true);
-        return func(...args);
+        const result = func(...args);
+        setFinishedCall(true);
+        return result;
     };
     return (...args) => {
         // This is how we will differentiate between argument and
         // parameter validation errors
         let reachedCaller = false;
+        let finishedCall = false;
         try {
-            const implementedFunction = functionFactory.implement(((...args) => wrappedFunction((v) => (reachedCaller = v), ...args)));
+            const implementedFunction = functionFactory.implement(((...args) => wrappedFunction((v) => (reachedCaller = v), (v) => (finishedCall = v), ...args)));
             return implementedFunction(...args);
         }
         catch (e) {
             if ((0, typeGuards_1.isZodError)(e)) {
-                e = new zod_1.ZodError(e.issues.map(i => (0, prefixIssuePath_1.prefixZodIssuePath)(i, reachedCaller ? outputPath : inputPath)));
+                if (!reachedCaller || finishedCall)
+                    e = new zod_1.ZodError(e.issues.map(i => (0, prefixIssuePath_1.prefixZodIssuePath)(i, reachedCaller ? outputPath : inputPath)));
             }
             throw e;
         }
+        finally {
+            // Reset reachedCaller and finishedCall for the next call
+            reachedCaller = false;
+            finishedCall = false;
+        }
     };
 }
-function zodFunctionSchema(options = {}) {
+function zodFunctionSchema({ trials = [], inputPath = "args", outputPath = "return", ...options } = {}) {
     // Transform the input value using zodFunctionParse
     // so that this schema can be used to validate functions
     return zod_1.default.any().transform((v, ctx) => {
         try {
-            return zodFunctionParse(v, options);
+            const result = zodValidatedFunction(v, {
+                inputPath, outputPath,
+                ...options
+            });
+            // That zodValidatedFunction call guarantees that this is a function.
+            // We will not call it if there are no trials,
+            // as functions with side effects would be problematic to test.
+            if (trials.length > 0) {
+                trials.forEach((trial, i) => {
+                    var _a;
+                    const id = (_a = trial.id) !== null && _a !== void 0 ? _a : `trial_${i}`;
+                    const { outputSchema = zod_1.default.unknown(), error, errorStringify = (e) => {
+                        if ((0, typeGuards_1.isZodError)(e))
+                            return (0, interpret_1.interpretZodError)(e, { multiline: false });
+                        if (e instanceof Error)
+                            return e.message;
+                        return String(e);
+                    } } = trial;
+                    const requiresError = error === "require" || (typeof error === "object" && error !== null);
+                    const isExpectedError = (err) => {
+                        if (error === "allow" || error === "require")
+                            return true;
+                        if (error === undefined || error === "forbid")
+                            return false;
+                        if (typeof error === "function")
+                            return error(err);
+                        return error.require(err);
+                    };
+                    try {
+                        const output = result(...trial.input);
+                        if (requiresError) {
+                            ctx.addIssue({
+                                code: "custom",
+                                message: "Unexpected Success",
+                                path: [id],
+                            });
+                            return;
+                        }
+                        const { success: outputSuccess, error: outputError } = outputSchema.safeParse(output);
+                        if (!outputSuccess) {
+                            // Indicate the trial where the error occurred to each issue.
+                            // The fact that the error is in the output is already indicated,
+                            // courtesy of the wrapper zodValidatedFunction provides.
+                            outputError.issues.forEach(issue => ctx.addIssue({
+                                ...issue,
+                                path: [id, ...issue.path]
+                            }));
+                        }
+                    }
+                    catch (err) {
+                        if ((0, typeGuards_1.isZodError)(err)) {
+                            if (err.issues.every(issue => (0, issuePathStartsWith_1.issuePathStartsWith)(issue.path, inputPath) ||
+                                (0, issuePathStartsWith_1.issuePathStartsWith)(issue.path, outputPath))) {
+                                // Indicate the trial where the error occurred to each issue.
+                                // The fact that the error is in either the input or output is
+                                // already indicated, courtesy of the wrapper zodValidatedFunction provides.
+                                err.issues.forEach(issue => ctx.addIssue({
+                                    ...issue,
+                                    path: [id, ...issue.path]
+                                }));
+                                return;
+                            }
+                        }
+                        if (!isExpectedError(err)) {
+                            ctx.addIssue({
+                                code: "custom",
+                                message: `Unexpected Error: ${errorStringify(err)}`,
+                                path: [id],
+                            });
+                        }
+                    }
+                });
+            }
+            return result;
         }
         catch (e) {
             if ((0, typeGuards_1.isZodError)(e)) {

package/dist/index.d.ts

@@ -5,3 +5,4 @@ export * from './interpret';
 export * from './validate';
 export * from './clone';
 export * from './prefixIssuePath';
+export * from './issuePathStartsWith';

package/dist/index.js

@@ -21,3 +21,4 @@ __exportStar(require("./interpret"), exports);
 __exportStar(require("./validate"), exports);
 __exportStar(require("./clone"), exports);
 __exportStar(require("./prefixIssuePath"), exports);
+__exportStar(require("./issuePathStartsWith"), exports);

package/dist/interpret.d.ts

@@ -1,3 +1,7 @@
-import { ZodError } from 'zod';
-import { $ZodError } from 'zod/v4/core';
-export declare function interpretZodError(err: ZodError | $ZodError, prefix?: PropertyKey | PropertyKey[]): string;
+import { InterpretableZodError, InterpretableZodIssue } from './types';
+export type InterpretZodErrorOptions = {
+    prefix?: PropertyKey | PropertyKey[];
+    multiline?: boolean;
+};
+export declare function interpretZodError(err: InterpretableZodError, options?: PropertyKey | PropertyKey[] | InterpretZodErrorOptions): string;
+export declare function interpretZodIssue(issue: InterpretableZodIssue, options?: PropertyKey | PropertyKey[] | InterpretZodErrorOptions): string;

package/dist/interpret.js

@@ -1,42 +1,25 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.interpretZodError = interpretZodError;
-const zod_1 = __importStar(require("zod"));
+exports.interpretZodIssue = interpretZodIssue;
+const zod_1 = __importDefault(require("zod"));
 const prefixIssuePath_1 = require("./prefixIssuePath");
-function interpretZodError(err, prefix = "") {
-    const modifiedErr = new zod_1.ZodError(err.issues.map(issue => (0, prefixIssuePath_1.prefixZodIssuePath)(issue, prefix)));
-    return zod_1.default.prettifyError(modifiedErr);
+function interpretZodError(err, options = "") {
+    if (typeof options !== "object" || Array.isArray(options))
+        options = { prefix: options };
+    const { multiline = true, prefix = "" } = options;
+    const modifiedErr = {
+        issues: err.issues.map(issue => (0, prefixIssuePath_1.prefixZodIssuePath)(issue, prefix))
+    };
+    let result = zod_1.default.prettifyError(modifiedErr);
+    if (!multiline) {
+        result = result.replace(/\n\s*→/g, " →");
+    }
+    return result;
+}
+function interpretZodIssue(issue, options = "") {
+    return interpretZodError({ issues: [issue] }, options);
 }

package/dist/issuePathStartsWith.d.ts

@@ -0,0 +1 @@
+export declare function issuePathStartsWith(issuePath: PropertyKey[], prefix: PropertyKey | PropertyKey[]): boolean;

package/dist/issuePathStartsWith.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.issuePathStartsWith = issuePathStartsWith;
+function issuePathStartsWith(issuePath, prefix) {
+    if (!Array.isArray(prefix))
+        prefix = [prefix];
+    if (issuePath.length < prefix.length)
+        return false;
+    return prefix.every((segment, i) => issuePath[i] === segment);
+}

package/dist/prefixIssuePath.d.ts

@@ -1,2 +1,2 @@
-import z from "zod";
-export declare function prefixZodIssuePath(issue: z.core.$ZodIssue, prefix: PropertyKey | PropertyKey[]): z.core.$ZodIssue;
+import { InterpretableZodIssue } from "./types";
+export declare function prefixZodIssuePath<I extends InterpretableZodIssue>(issue: I, prefix: PropertyKey | PropertyKey[]): I;

package/dist/prefixIssuePath.js

@@ -2,9 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.prefixZodIssuePath = prefixZodIssuePath;
 function prefixZodIssuePath(issue, prefix) {
+    var _a;
     if (!Array.isArray(prefix))
         prefix = [prefix];
-    const newPath = [...prefix, ...issue.path]
+    const newPath = [...prefix, ...((_a = issue.path) !== null && _a !== void 0 ? _a : [])]
         .filter(p => typeof p !== "string" || p.length > 0);
     if (newPath.length === 0)
         newPath.push("(root)");

package/dist/types.d.ts

@@ -18,3 +18,10 @@ export type ZodValidateWithErrorsOptions = {
     prefix?: string | string[];
 };
 export type MaybeZodOptional<ZT extends ZodType> = ZT | ZodOptional<ZT>;
+export type InterpretableZodIssue = Readonly<{
+    message: string;
+    path?: PropertyKey[];
+}>;
+export type InterpretableZodError = Readonly<{
+    issues: InterpretableZodIssue[];
+}>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ptolemy2002/zod-utils",
-    "version": "1.3.0",
+    "version": "1.5.0",
     "private": false,
     "main": "dist/index.js",
     "types": "dist/index.d.ts",