@ptolemy2002/zod-utils 1.3.0 → 1.4.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);
+                        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/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/package.json

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