{"id":14397,"library":"zod_utilz","title":"Zod Utilz","description":"Zod Utilz (zod_utilz) is a TypeScript library providing framework-agnostic utilities that extend the functionality of Zod. Currently at version 0.8.4, it aims to simplify common Zod tasks, fill feature gaps, and offer implementations for potential new Zod features. Key utilities include `SPR` for enhanced `SafeParseResult` handling, `makeErrorMap` for custom error maps, `coerce` for type coercion, and dedicated schemas like `json()` and `stringToJSON()` for JSON validation. The library maintains a steady release cadence, typically with minor versions introducing new utilities. It differentiates itself by focusing on practical, often-requested Zod extensions, while also striving for reduced bundle size by replacing internal dependencies like Lodash. It requires `zod` (`^3.22.4`) and `typescript` (`^5.0.0`) as peer dependencies.","status":"active","version":"0.8.4","language":"javascript","source_language":"en","source_url":"https://github.com/JacobWeisenburger/zod_utilz","tags":["javascript","typescript"],"install":[{"cmd":"npm install zod_utilz","lang":"bash","label":"npm"},{"cmd":"yarn add zod_utilz","lang":"bash","label":"yarn"},{"cmd":"pnpm add zod_utilz","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for type-checking and modern TypeScript features.","package":"typescript","optional":false},{"reason":"Core peer dependency as it provides utilities for Zod schemas.","package":"zod","optional":false}],"imports":[{"note":"The library exports a named object `zu` containing all utilities. Attempting a default import (`import zu from ...`) or CommonJS require (`const zu = require(...)`) will typically result in errors in modern ESM environments.","wrong":"import zu from 'zod_utilz';\n// OR\nconst zu = require('zod_utilz');","symbol":"zu","correct":"import { zu } from 'zod_utilz';"},{"note":"`json()` is a method on the `zu` object, not a direct named export from the `zod_utilz` package. All utilities are accessed via the `zu` object.","wrong":"import { json } from 'zod_utilz';","symbol":"json","correct":"import { zu } from 'zod_utilz';\nconst jsonSchema = zu.json();"},{"note":"`SPR` is a method on the `zu` object, designed to enhance `ZodSafeParseReturn` for easier optional chaining. It's not a top-level named export.","wrong":"import { SPR } from 'zod_utilz';","symbol":"SPR","correct":"import { zu } from 'zod_utilz';\nconst result = zu.SPR(schema.safeParse(data));"}],"quickstart":{"code":"import { z } from 'zod';\nimport { zu } from 'zod_utilz';\n\n// Define a Zod schema for a JSON object\nconst mySchema = zu.json(z.object({\n  name: z.string().min(1, 'Name is required'),\n  age: z.number().int().positive('Age must be a positive integer'),\n  email: z.string().email('Invalid email format').optional(),\n}));\n\n// Example usage with valid JSON string\nconst jsonStringValid = '{\"name\": \"Alice\", \"age\": 30, \"email\": \"alice@example.com\"}';\nconst parsedValid = mySchema.safeParse(jsonStringValid);\n\nif (parsedValid.success) {\n  console.log('Successfully parsed valid data:', parsedValid.data);\n} else {\n  console.error('Validation failed for valid data:', parsedValid.error.flatten());\n}\n\n// Example usage with invalid JSON string (missing name, invalid age type)\nconst jsonStringInvalid = '{\"age\": \"twenty\", \"email\": \"bob@example.com\"}';\nconst parsedInvalid = mySchema.safeParse(jsonStringInvalid);\n\nif (parsedInvalid.success) {\n  console.log('Successfully parsed invalid data (should fail):', parsedInvalid.data);\n} else {\n  console.error('Validation failed for invalid data:', parsedInvalid.error.flatten());\n}\n\n// Using zu.stringToJSON for direct string parsing\nconst stringToJSONSchema = zu.stringToJSON(z.object({\n  message: z.string(),\n}));\n\nconst directParsed = stringToJSONSchema.safeParse('{\"message\": \"Hello from string!\"}');\nif (directParsed.success) {\n  console.log('stringToJSON parsed:', directParsed.data);\n}","lang":"typescript","description":"Demonstrates importing `zu` and using `zu.json()` and `zu.stringToJSON()` to validate JSON data from strings against a Zod schema, including success and error handling."},"warnings":[{"fix":"Ensure your project's `tsconfig.json` (if applicable) and bundler configuration (`moduleResolution`, `target`, `module`) are set for modern ES Modules (e.g., `\"module\": \"nodenext\"` or `\"es2020\"`). You may need to update your bundler or Node.js version.","message":"Between versions 0.8.0 and 0.8.2, the package's build process switched from Deno to Bun, and changes were made to the `main` and `module` fields in `package.json`. These changes can cause module resolution issues, particularly in environments mixing CommonJS and ES Modules, or with older bundlers. Projects might experience 'Cannot find module' errors or incorrect module loading.","severity":"breaking","affected_versions":">=0.8.0 <0.8.3"},{"fix":"Always import the `zu` object as a named export: `import { zu } from 'zod_utilz';`. Then access utilities as properties of `zu`, e.g., `zu.json()`, `zu.SPR()`, `zu.makeErrorMap()`.","message":"The library exports a single named object `zu` that contains all utilities. Attempting to directly import individual utilities as named exports (e.g., `import { json } from 'zod_utilz'`) will fail, as `json` is a method of the `zu` object (`zu.json()`), not a top-level export.","severity":"gotcha","affected_versions":">=0.6.0"},{"fix":"Ensure that `zod` and `typescript` are installed in your project at versions compatible with the specified peer dependency ranges. Update your `package.json` to reflect the required versions and reinstall dependencies (`npm install` or `yarn install`).","message":"This library has peer dependencies on `zod` (`^3.22.4`) and `typescript` (`^5.0.0`). Incompatible versions of these peer dependencies can lead to TypeScript compilation errors, runtime validation issues, or unexpected behavior due to API changes in Zod or TypeScript.","severity":"gotcha","affected_versions":">=0.6.0"},{"fix":"For most projects, importing `zu` and letting bundlers handle tree-shaking is sufficient. If extreme bundle size optimization for specific utilities is critical, evaluate your bundler's tree-shaking effectiveness, or consider the project's suggestion of direct code inclusion for the absolute minimum footprint.","message":"The project's README suggests that for highly optimized bundle sizes when only a few utilities are needed, users might consider copying the source code of specific utilities directly into their projects. This implies that relying on bundler tree-shaking for `zod_utilz` may not always be perfectly efficient for all build configurations.","severity":"gotcha","affected_versions":">=0.6.0"}],"env_vars":null,"search_vec":"'0.8.4':25 '3.22.4':113 '5.0.0':116 'agnost':14 'aim':27 'also':98 'bundl':102 'cadenc':77 'coerc':57 'coercion':60 'common':30 'current':22 'custom':54 'dedic':62 'depend':107,119 'differenti':86 'enhanc':49 'error':55 'extend':17 'extens':96 'featur':34,43 'fill':33 'focus':89 'framework':13 'framework-agnost':12 'function':19 'gap':35 'handl':51 'implement':38 'includ':46 'intern':106 'introduc':82 'javascript':120 'json':65,69 'key':44 'librari':10,72 'like':64,108 'lodash':109 'maintain':73 'makeerrormap':52 'map':56 'minor':80 'new':41,83 'offer':37 'often':93 'often-request':92 'peer':118 'potenti':40 'practic':91 'provid':11 'reduc':101 'releas':76 'replac':105 'request':94 'requir':111 'safeparseresult':50 'schema':63 'simplifi':29 'size':103 'spr':47 'steadi':75 'stringtojson':67 'strive':99 'task':32 'type':59 'typescript':9,115,121 'typic':78 'util':15,45,84 'utilz':2,4,6 'valid':70 'version':24,81 'zod':1,3,5,21,31,42,95,112","created_at":"2026-04-20T01:59:30.211688+00:00","updated_at":"2026-04-20T01:59:30.211688+00:00","problems":[{"fix":"Ensure you are using ES Module import syntax: `import { zu } from 'zod_utilz';`. If your project is CommonJS-only, you may need to configure your bundler (e.g., Webpack, Rollup) or Node.js environment to correctly resolve and transpile ESM imports.","cause":"Attempting to `require()` an ES Module-first package or incorrect module resolution in a mixed CJS/ESM environment.","error":"TypeError: Cannot destructure property 'zu' of 'undefined' as it is undefined."},{"fix":"Verify `zod_utilz` is installed (`npm install zod_utilz`). Check the import path. For TypeScript, ensure `tsconfig.json` has `\"moduleResolution\": \"Bundler\"` or `\"NodeNext\"` to correctly resolve module types, especially if `zod_utilz` uses modern `exports` maps in its `package.json`.","cause":"The package is not installed, the import path is incorrect, or TypeScript's `moduleResolution` setting is not compatible with how `zod_utilz` is published.","error":"TS2307: Cannot find module 'zod_utilz' or its corresponding type declarations."},{"fix":"Update `zod` to `^3.22.4` and `typescript` to `^5.0.0` or newer compatible versions in your `package.json`. Run `npm install` or `yarn install` to ensure the correct versions are used.","cause":"A mismatch between the `zod` or `typescript` versions installed in your project and the peer dependencies expected by `zod_utilz`.","error":"TS2345: Argument of type '...' is not assignable to parameter of type 'ZodType<any, ZodTypeDef, any>'."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/JacobWeisenburger/zod_utilz","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/zod_utilz","openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}