eslint-plugin-zod-utils 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# eslint-plugin-zod-utils
+
+ESLint utilities for safer Zod schema usage.
+
+## Installation
+
+```sh
+npm install --save-dev eslint-plugin-zod-utils
+```
+
+## Usage
+
+Flat config:
+
+```js
+import zodUtils from "eslint-plugin-zod-utils";
+
+export default [
+  zodUtils.configs.recommended,
+];
+```
+
+Or configure the rule directly:
+
+```js
+import zodUtils from "eslint-plugin-zod-utils";
+
+export default [
+  {
+    plugins: {
+      "zod-utils": zodUtils,
+    },
+    rules: {
+      "zod-utils/no-inline-zod-schema": "error",
+    },
+  },
+];
+```
+
+Legacy eslintrc:
+
+```json
+{
+  "extends": ["plugin:zod-utils/legacy-recommended"]
+}
+```
+
+## Rules
+
+### `zod-utils/no-inline-zod-schema`
+
+Requires Zod schemas to be created as module-level variable declarations. This avoids recreating schemas inside functions, callbacks, render paths, hooks, or argument lists.
+
+This rule was inspired by the motivation behind [`babel-plugin-zod-hoist`](https://github.com/gajus/babel-plugin-zod-hoist#motivation), which documents the cost of repeatedly initializing equivalent Zod schemas and the benefits of hoisting them.
+
+Invalid:
+
+```ts
+import { z } from "zod";
+
+function parseUser(input: unknown) {
+  const UserSchema = z.object({
+    id: z.string(),
+  });
+
+  return UserSchema.parse(input);
+}
+```
+
+```ts
+import { z } from "zod";
+
+const parser = createParser(z.object({
+  id: z.string(),
+}));
+```
+
+Valid:
+
+```ts
+import { z } from "zod";
+
+const UserSchema = z.object({
+  id: z.string(),
+});
+
+function parseUser(input: unknown) {
+  return UserSchema.parse(input);
+}
+```
+
+The rule understands `import { z } from "zod"`, `import * as zod from "zod"`, aliased `z` imports, and direct named schema factories such as `import { object, string } from "zod"`.
+
+## Development
+
+```sh
+npm test
+npm run typecheck
+npm run lint
+npm run build
+npm pack --dry-run
+```

package/dist/index.cjs

@@ -0,0 +1,255 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  configs: () => configs,
+  default: () => index_default,
+  rules: () => rules
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/rules/no-inline-zod-schema.ts
+var import_utils = require("@typescript-eslint/utils");
+var ZOD_FACTORY_IMPORTS = /* @__PURE__ */ new Set([
+  "any",
+  "array",
+  "base64",
+  "base64url",
+  "bigint",
+  "boolean",
+  "cidrv4",
+  "cidrv6",
+  "cuid",
+  "cuid2",
+  "custom",
+  "date",
+  "discriminatedUnion",
+  "e164",
+  "email",
+  "emoji",
+  "enum",
+  "file",
+  "function",
+  "instanceof",
+  "intersection",
+  "ipv4",
+  "ipv6",
+  "jwt",
+  "ksuid",
+  "lazy",
+  "literal",
+  "map",
+  "nan",
+  "nanoid",
+  "nativeEnum",
+  "never",
+  "null",
+  "nullable",
+  "number",
+  "object",
+  "optional",
+  "preprocess",
+  "promise",
+  "record",
+  "set",
+  "string",
+  "stringbool",
+  "symbol",
+  "templateLiteral",
+  "tuple",
+  "undefined",
+  "union",
+  "unknown",
+  "ulid",
+  "url",
+  "uuid",
+  "uuidv4",
+  "uuidv6",
+  "uuidv7",
+  "void",
+  "xid"
+]);
+var ZOD_NAMESPACE_IMPORTS = /* @__PURE__ */ new Set(["z", "coerce", "iso"]);
+function findVariable(scope, name) {
+  let currentScope = scope;
+  while (currentScope) {
+    const variable = currentScope.set?.get(name) ?? currentScope.variables?.find((candidate) => candidate.name === name);
+    if (variable) {
+      return variable;
+    }
+    currentScope = currentScope.upper ?? null;
+  }
+  return null;
+}
+function getRootIdentifier(node) {
+  if (!node) {
+    return null;
+  }
+  switch (node.type) {
+    case "Identifier":
+      return node;
+    case "MemberExpression":
+      return getRootIdentifier(node.object);
+    case "CallExpression":
+      return getRootIdentifier(node.callee);
+    case "ChainExpression":
+      return getRootIdentifier(node.expression);
+    case "TSAsExpression":
+    case "TSNonNullExpression":
+    case "TSSatisfiesExpression":
+    case "TSTypeAssertion":
+      return getRootIdentifier(node.expression);
+    default:
+      return null;
+  }
+}
+function isZodImportSpecifier(node) {
+  if (node.type !== "ImportNamespaceSpecifier" && node.type !== "ImportSpecifier") {
+    return false;
+  }
+  const declaration = node.parent;
+  if (declaration?.type !== "ImportDeclaration") {
+    return false;
+  }
+  if (declaration.source.value !== "zod") {
+    return false;
+  }
+  if (node.type === "ImportNamespaceSpecifier") {
+    return true;
+  }
+  if (node.importKind === "type" || declaration.importKind === "type") {
+    return false;
+  }
+  const importedName = node.imported.type === "Identifier" ? node.imported.name : node.imported.value;
+  return ZOD_NAMESPACE_IMPORTS.has(importedName) || ZOD_FACTORY_IMPORTS.has(importedName);
+}
+function unwrapExpression(node) {
+  let current = node;
+  while (current.parent?.type === "TSAsExpression" || current.parent?.type === "TSNonNullExpression" || current.parent?.type === "TSSatisfiesExpression" || current.parent?.type === "TSTypeAssertion") {
+    current = current.parent;
+  }
+  return current;
+}
+function isModuleLevelVariableInitializer(node) {
+  const expression = unwrapExpression(node);
+  if (expression.parent?.type !== "VariableDeclarator") {
+    return false;
+  }
+  if (expression.parent.init !== expression) {
+    return false;
+  }
+  const declaration = expression.parent.parent;
+  if (declaration.type !== "VariableDeclaration") {
+    return false;
+  }
+  const container = declaration.parent;
+  return container.type === "Program" || container.type === "ExportNamedDeclaration" && container.parent.type === "Program";
+}
+var noInlineZodSchema = import_utils.ESLintUtils.RuleCreator(
+  (ruleName2) => `https://www.npmjs.com/package/eslint-plugin-zod-utils#${ruleName2}`
+)({
+  name: "no-inline-zod-schema",
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow creating Zod schemas outside module scope."
+    },
+    messages: {
+      inlineSchema: "Create Zod schemas at module scope instead of inline inside functions, callbacks, classes, or arguments."
+    },
+    schema: []
+  },
+  defaultOptions: [],
+  create(context) {
+    const sourceCode = context.sourceCode;
+    function isZodSchemaCall(node) {
+      const root = getRootIdentifier(node.callee);
+      if (!root) {
+        return false;
+      }
+      const scope = sourceCode.getScope(root);
+      const variable = findVariable(scope, root.name);
+      return variable?.defs.some((definition) => isZodImportSpecifier(definition.node)) ?? false;
+    }
+    function hasZodCallAncestor(node) {
+      let current = node.parent;
+      while (current) {
+        if (current.type === "CallExpression" && isZodSchemaCall(current)) {
+          return true;
+        }
+        current = current.parent;
+      }
+      return false;
+    }
+    return {
+      CallExpression(node) {
+        if (!isZodSchemaCall(node)) {
+          return;
+        }
+        if (hasZodCallAncestor(node)) {
+          return;
+        }
+        if (isModuleLevelVariableInitializer(node)) {
+          return;
+        }
+        context.report({
+          node,
+          messageId: "inlineSchema"
+        });
+      }
+    };
+  }
+});
+
+// src/index.ts
+var ruleName = "zod-utils/no-inline-zod-schema";
+var rules = {
+  "no-inline-zod-schema": noInlineZodSchema
+};
+var plugin = {
+  meta: {
+    name: "eslint-plugin-zod-utils",
+    version: "0.1.0"
+  },
+  rules,
+  configs: {}
+};
+plugin.configs.recommended = {
+  plugins: {
+    "zod-utils": plugin
+  },
+  rules: {
+    [ruleName]: "error"
+  }
+};
+plugin.configs["legacy-recommended"] = {
+  plugins: ["zod-utils"],
+  rules: {
+    [ruleName]: "error"
+  }
+};
+var configs = plugin.configs;
+var index_default = plugin;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  configs,
+  rules
+});

package/dist/index.d.cts

@@ -0,0 +1,42 @@
+import * as _typescript_eslint_utils_ts_eslint from '@typescript-eslint/utils/ts-eslint';
+
+declare const ruleName = "zod-utils/no-inline-zod-schema";
+declare const rules: {
+    "no-inline-zod-schema": _typescript_eslint_utils_ts_eslint.RuleModule<"inlineSchema", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
+};
+type Plugin = {
+    meta: {
+        name: string;
+        version: string;
+    };
+    rules: typeof rules;
+    configs: {
+        recommended?: {
+            plugins: {
+                "zod-utils": Plugin;
+            };
+            rules: Record<typeof ruleName, "error">;
+        };
+        "legacy-recommended"?: {
+            plugins: ["zod-utils"];
+            rules: Record<typeof ruleName, "error">;
+        };
+    };
+};
+declare const plugin: Plugin;
+declare const configs: {
+    recommended?: {
+        plugins: {
+            "zod-utils": Plugin;
+        };
+        rules: Record<typeof ruleName, "error">;
+    };
+    "legacy-recommended"?: {
+        plugins: ["zod-utils"];
+        rules: Record<typeof ruleName, "error">;
+    };
+};
+
+export { configs, plugin as default, rules };

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+import * as _typescript_eslint_utils_ts_eslint from '@typescript-eslint/utils/ts-eslint';
+
+declare const ruleName = "zod-utils/no-inline-zod-schema";
+declare const rules: {
+    "no-inline-zod-schema": _typescript_eslint_utils_ts_eslint.RuleModule<"inlineSchema", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
+};
+type Plugin = {
+    meta: {
+        name: string;
+        version: string;
+    };
+    rules: typeof rules;
+    configs: {
+        recommended?: {
+            plugins: {
+                "zod-utils": Plugin;
+            };
+            rules: Record<typeof ruleName, "error">;
+        };
+        "legacy-recommended"?: {
+            plugins: ["zod-utils"];
+            rules: Record<typeof ruleName, "error">;
+        };
+    };
+};
+declare const plugin: Plugin;
+declare const configs: {
+    recommended?: {
+        plugins: {
+            "zod-utils": Plugin;
+        };
+        rules: Record<typeof ruleName, "error">;
+    };
+    "legacy-recommended"?: {
+        plugins: ["zod-utils"];
+        rules: Record<typeof ruleName, "error">;
+    };
+};
+
+export { configs, plugin as default, rules };

package/dist/index.js

@@ -0,0 +1,227 @@
+// src/rules/no-inline-zod-schema.ts
+import { ESLintUtils } from "@typescript-eslint/utils";
+var ZOD_FACTORY_IMPORTS = /* @__PURE__ */ new Set([
+  "any",
+  "array",
+  "base64",
+  "base64url",
+  "bigint",
+  "boolean",
+  "cidrv4",
+  "cidrv6",
+  "cuid",
+  "cuid2",
+  "custom",
+  "date",
+  "discriminatedUnion",
+  "e164",
+  "email",
+  "emoji",
+  "enum",
+  "file",
+  "function",
+  "instanceof",
+  "intersection",
+  "ipv4",
+  "ipv6",
+  "jwt",
+  "ksuid",
+  "lazy",
+  "literal",
+  "map",
+  "nan",
+  "nanoid",
+  "nativeEnum",
+  "never",
+  "null",
+  "nullable",
+  "number",
+  "object",
+  "optional",
+  "preprocess",
+  "promise",
+  "record",
+  "set",
+  "string",
+  "stringbool",
+  "symbol",
+  "templateLiteral",
+  "tuple",
+  "undefined",
+  "union",
+  "unknown",
+  "ulid",
+  "url",
+  "uuid",
+  "uuidv4",
+  "uuidv6",
+  "uuidv7",
+  "void",
+  "xid"
+]);
+var ZOD_NAMESPACE_IMPORTS = /* @__PURE__ */ new Set(["z", "coerce", "iso"]);
+function findVariable(scope, name) {
+  let currentScope = scope;
+  while (currentScope) {
+    const variable = currentScope.set?.get(name) ?? currentScope.variables?.find((candidate) => candidate.name === name);
+    if (variable) {
+      return variable;
+    }
+    currentScope = currentScope.upper ?? null;
+  }
+  return null;
+}
+function getRootIdentifier(node) {
+  if (!node) {
+    return null;
+  }
+  switch (node.type) {
+    case "Identifier":
+      return node;
+    case "MemberExpression":
+      return getRootIdentifier(node.object);
+    case "CallExpression":
+      return getRootIdentifier(node.callee);
+    case "ChainExpression":
+      return getRootIdentifier(node.expression);
+    case "TSAsExpression":
+    case "TSNonNullExpression":
+    case "TSSatisfiesExpression":
+    case "TSTypeAssertion":
+      return getRootIdentifier(node.expression);
+    default:
+      return null;
+  }
+}
+function isZodImportSpecifier(node) {
+  if (node.type !== "ImportNamespaceSpecifier" && node.type !== "ImportSpecifier") {
+    return false;
+  }
+  const declaration = node.parent;
+  if (declaration?.type !== "ImportDeclaration") {
+    return false;
+  }
+  if (declaration.source.value !== "zod") {
+    return false;
+  }
+  if (node.type === "ImportNamespaceSpecifier") {
+    return true;
+  }
+  if (node.importKind === "type" || declaration.importKind === "type") {
+    return false;
+  }
+  const importedName = node.imported.type === "Identifier" ? node.imported.name : node.imported.value;
+  return ZOD_NAMESPACE_IMPORTS.has(importedName) || ZOD_FACTORY_IMPORTS.has(importedName);
+}
+function unwrapExpression(node) {
+  let current = node;
+  while (current.parent?.type === "TSAsExpression" || current.parent?.type === "TSNonNullExpression" || current.parent?.type === "TSSatisfiesExpression" || current.parent?.type === "TSTypeAssertion") {
+    current = current.parent;
+  }
+  return current;
+}
+function isModuleLevelVariableInitializer(node) {
+  const expression = unwrapExpression(node);
+  if (expression.parent?.type !== "VariableDeclarator") {
+    return false;
+  }
+  if (expression.parent.init !== expression) {
+    return false;
+  }
+  const declaration = expression.parent.parent;
+  if (declaration.type !== "VariableDeclaration") {
+    return false;
+  }
+  const container = declaration.parent;
+  return container.type === "Program" || container.type === "ExportNamedDeclaration" && container.parent.type === "Program";
+}
+var noInlineZodSchema = ESLintUtils.RuleCreator(
+  (ruleName2) => `https://www.npmjs.com/package/eslint-plugin-zod-utils#${ruleName2}`
+)({
+  name: "no-inline-zod-schema",
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow creating Zod schemas outside module scope."
+    },
+    messages: {
+      inlineSchema: "Create Zod schemas at module scope instead of inline inside functions, callbacks, classes, or arguments."
+    },
+    schema: []
+  },
+  defaultOptions: [],
+  create(context) {
+    const sourceCode = context.sourceCode;
+    function isZodSchemaCall(node) {
+      const root = getRootIdentifier(node.callee);
+      if (!root) {
+        return false;
+      }
+      const scope = sourceCode.getScope(root);
+      const variable = findVariable(scope, root.name);
+      return variable?.defs.some((definition) => isZodImportSpecifier(definition.node)) ?? false;
+    }
+    function hasZodCallAncestor(node) {
+      let current = node.parent;
+      while (current) {
+        if (current.type === "CallExpression" && isZodSchemaCall(current)) {
+          return true;
+        }
+        current = current.parent;
+      }
+      return false;
+    }
+    return {
+      CallExpression(node) {
+        if (!isZodSchemaCall(node)) {
+          return;
+        }
+        if (hasZodCallAncestor(node)) {
+          return;
+        }
+        if (isModuleLevelVariableInitializer(node)) {
+          return;
+        }
+        context.report({
+          node,
+          messageId: "inlineSchema"
+        });
+      }
+    };
+  }
+});
+
+// src/index.ts
+var ruleName = "zod-utils/no-inline-zod-schema";
+var rules = {
+  "no-inline-zod-schema": noInlineZodSchema
+};
+var plugin = {
+  meta: {
+    name: "eslint-plugin-zod-utils",
+    version: "0.1.0"
+  },
+  rules,
+  configs: {}
+};
+plugin.configs.recommended = {
+  plugins: {
+    "zod-utils": plugin
+  },
+  rules: {
+    [ruleName]: "error"
+  }
+};
+plugin.configs["legacy-recommended"] = {
+  plugins: ["zod-utils"],
+  rules: {
+    [ruleName]: "error"
+  }
+};
+var configs = plugin.configs;
+var index_default = plugin;
+export {
+  configs,
+  index_default as default,
+  rules
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "eslint-plugin-zod-utils",
+  "version": "1.0.0",
+  "description": "ESLint utilities for safer Zod schema usage.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean --external @typescript-eslint/utils",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepack": "npm run lint && npm run typecheck && npm test && npm run build"
+  },
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "zod",
+    "typescript"
+  ],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "eslint": ">=8.57.0 || >=9.0.0 || >=10.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.9.1",
+    "@typescript-eslint/parser": "^8.60.1",
+    "@typescript-eslint/rule-tester": "^8.60.1",
+    "eslint": "^10.4.1",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.60.1",
+    "vitest": "^4.1.8"
+  },
+  "dependencies": {
+    "@typescript-eslint/utils": "^8.60.1"
+  }
+}