@ptolemy2002/zod-utils 1.2.0 → 1.4.0

package/README.md

@@ -5,7 +5,9 @@ Various utilities for working with Zod schemas.
 - [Type Reference](docs/type-reference.md) - Complete type definitions for all exported types
 - `util` - Utilities for working with Zod schemas and errors
   - [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

@@ -0,0 +1,23 @@
+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 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

@@ -0,0 +1,173 @@
+"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.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"));
+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}`,
+                path: [],
+                code: "invalid_type",
+                expected: "function"
+            }]);
+    }
+    const functionFactory = zod_1.default.function({ input, output });
+    const wrappedFunction = (setReachedCaller, setFinishedCall, ...args) => {
+        setReachedCaller(true);
+        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), (v) => (finishedCall = v), ...args)));
+            return implementedFunction(...args);
+        }
+        catch (e) {
+            if ((0, typeGuards_1.isZodError)(e)) {
+                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({ 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 {
+            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)) {
+                e.issues.forEach(issue => ctx.addIssue(issue));
+            }
+            return zod_1.default.NEVER;
+        }
+    });
+}

package/dist/index.d.ts

@@ -1,6 +1,8 @@
+export * from './function';
 export * from './types';
 export * from './typeGuards';
 export * from './interpret';
 export * from './validate';
 export * from './clone';
 export * from './prefixIssuePath';
+export * from './issuePathStartsWith';

package/dist/index.js

@@ -14,9 +14,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./function"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./typeGuards"), exports);
 __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,2 +1,3 @@
 import { ZodError } from 'zod';
-export declare function interpretZodError(err: ZodError, prefix?: PropertyKey | PropertyKey[]): string;
+import { $ZodError } from 'zod/v4/core';
+export declare function interpretZodError(err: ZodError | $ZodError, prefix?: PropertyKey | PropertyKey[]): string;

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/typeGuards.d.ts

@@ -1,2 +1,3 @@
 import { ZodError } from 'zod';
-export declare function isZodError(err: unknown): err is ZodError;
+import { $ZodError } from 'zod/v4/core';
+export declare function isZodError(err: unknown): err is ZodError | $ZodError;

package/dist/typeGuards.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isZodError = isZodError;
 const zod_1 = require("zod");
+const core_1 = require("zod/v4/core");
 function isZodError(err) {
-    return !!err && (err instanceof zod_1.ZodError || (err instanceof Error && err.name === 'ZodError'));
+    return !!err && (err instanceof zod_1.ZodError || err instanceof core_1.$ZodError || (err instanceof Error && (err.name === 'ZodError' || err.name === '$ZodError')));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ptolemy2002/zod-utils",
-    "version": "1.2.0",
+    "version": "1.4.0",
     "private": false,
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -32,6 +32,7 @@
         "zod": "^4.3.6"
     },
     "devDependencies": {
+        "@types/is-callable": "^1.1.2",
         "@types/jest": "^29.5.0",
         "@types/node": "^25.3.5",
         "jest": "^29.5.0",
@@ -40,5 +41,8 @@
         "tsconfig-paths": "^4.2.0",
         "typescript-transform-paths": "^3.5.3",
         "zod": "^4.3.6"
+    },
+    "dependencies": {
+        "is-callable": "^1.2.7"
     }
 }