zod_utilz

library0.8.4jsnpmunverified

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.

serialization

npm install zod_utilz

github ↗package ↗

INSTALL

IMPORT

SIG · ZOD_UTILZ

zod_utilz

serializationjavascriptv0.8.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ import { zu } from 'zod_utilz';

✗ import zu from 'zod_utilz'; // OR const zu = require('zod_utilz');

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.

json

✓ import { zu } from 'zod_utilz'; const jsonSchema = zu.json();

✗ import { json } from 'zod_utilz';

`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.

SPR

✓ import { zu } from 'zod_utilz'; const result = zu.SPR(schema.safeParse(data));

✗ import { SPR } from 'zod_utilz';

`SPR` is a method on the `zu` object, designed to enhance `ZodSafeParseReturn` for easier optional chaining. It's not a top-level named export.

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.

import { z } from 'zod'; import { zu } from 'zod_utilz'; // Define a Zod schema for a JSON object const mySchema = zu.json(z.object({ name: z.string().min(1, 'Name is required'), age: z.number().int().positive('Age must be a positive integer'), email: z.string().email('Invalid email format').optional(), })); // Example usage with valid JSON string const jsonStringValid = '{"name": "Alice", "age": 30, "email": "alice@example.com"}'; const parsedValid = mySchema.safeParse(jsonStringValid); if (parsedValid.success) { console.log('Successfully parsed valid data:', parsedValid.data); } else { console.error('Validation failed for valid data:', parsedValid.error.flatten()); } // Example usage with invalid JSON string (missing name, invalid age type) const jsonStringInvalid = '{"age": "twenty", "email": "bob@example.com"}'; const parsedInvalid = mySchema.safeParse(jsonStringInvalid); if (parsedInvalid.success) { console.log('Successfully parsed invalid data (should fail):', parsedInvalid.data); } else { console.error('Validation failed for invalid data:', parsedInvalid.error.flatten()); } // Using zu.stringToJSON for direct string parsing const stringToJSONSchema = zu.stringToJSON(z.object({ message: z.string(), })); const directParsed = stringToJSONSchema.safeParse('{"message": "Hello from string!"}'); if (directParsed.success) { console.log('stringToJSON parsed:', directParsed.data); }

Debug

Known issues

breakingBetween 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.

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.

affects: >=0.8.0 <0.8.3

gotchaThe 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.

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()`.

affects: >=0.6.0

gotchaThis 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.

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`).

affects: >=0.6.0

gotchaThe 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.

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.

affects: >=0.6.0

Errors

Common errors & fixes

TypeError: Cannot destructure property 'zu' of 'undefined' as it is undefined.

Attempting to `require()` an ES Module-first package or incorrect module resolution in a mixed CJS/ESM environment.

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.

TS2307: Cannot find module 'zod_utilz' or its corresponding type declarations.

The package is not installed, the import path is incorrect, or TypeScript's `moduleResolution` setting is not compatible with how `zod_utilz` is published.

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`.

TS2345: Argument of type '...' is not assignable to parameter of type 'ZodType<any, ZodTypeDef, any>'.

A mismatch between the `zod` or `typescript` versions installed in your project and the peer dependencies expected by `zod_utilz`.

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.

Upgrade

Version history

0.8.4latest on npm

Audit

Dependencies

typescriptrequiredPeer dependency required for type-checking and modern TypeScript features.

zodrequiredCore peer dependency as it provides utilities for Zod schemas.

Agent activity

29 hits · last 30 days

node

Resources

githubhttps://github.com/JacobWeisenburger/zod_utilz ↗

packagehttps://www.npmjs.com/package/zod_utilz ↗