@yukiakai/zod-extra

Extra schemas and parsing utilities for Zod.

Features

• Strict parsing utilities
• Trimmed and normalized schemas
• String → boolean parsing
• String → number parsing
• URL parsing with protocol validation
• Composable .pipe()-friendly architecture
• Full TypeScript support

Installation

npm install @yukiakai/zod-extra

pnpm add @yukiakai/zod-extra

yarn add @yukiakai/zod-extra

Why?

JavaScript built-ins are often surprisingly permissive:

Number('') // 0
Number(' ') // 0
Number(' 123 ') // 123

new URL(' https://example.com ')

@yukiakai/zod-extra provides strict and normalized schemas to make parsing behavior explicit and composable.

String Schemas

zTrimmedString

Trims leading and trailing whitespace.

import { zTrimmedString } from '@yukiakai/zod-extra';

zTrimmedString.parse('  hello  ');
// => 'hello'

zNonEmptyString

Trimmed string with .min(1) validation.

import { zNonEmptyString } from '@yukiakai/zod-extra';

zNonEmptyString.parse(' hello ');
// => 'hello'

zStrictNullableString

Converts empty string to null without trimming.

import { zStrictNullableString } from '@yukiakai/zod-extra';

zStrictNullableString.parse('');
// => null

zStrictNullableString.parse('   ');
// => '   '

zNullableString

Trimmed version of zStrictNullableString.

import { zNullableString } from '@yukiakai/zod-extra';

zNullableString.parse('   ');
// => null

zStrictUndefinedString

Converts empty string to undefined without trimming.

import { zStrictUndefinedString } from '@yukiakai/zod-extra';

zStrictUndefinedString.parse('');
// => undefined

zUndefinedString

Trimmed version of zStrictUndefinedString.

import { zUndefinedString } from '@yukiakai/zod-extra';

zUndefinedString.parse('   ');
// => undefined

Boolean Schemas

zStrictBooleanString

Strict boolean parser.

• Does not trim

• Does not lowercase

• Only accepts:

  • 'true'
  • 'false'

import { zStrictBooleanString } from '@yukiakai/zod-extra';

zStrictBooleanString.parse('true');
// => true

zBooleanString

Normalized boolean parser.

• Trims whitespace
• Lowercases input
• Parses boolean values

import { zBooleanString } from '@yukiakai/zod-extra';

zBooleanString.parse(' TRUE ');
// => true

Number Schemas

zStrictNumberString

Strict finite number parser.

• Rejects whitespace
• Rejects empty strings
• Rejects Infinity
• Rejects NaN

import { zStrictNumberString } from '@yukiakai/zod-extra';

zStrictNumberString.parse('123');
// => 123

Invalid examples:

zStrictNumberString.parse(' 123 ');
zStrictNumberString.parse('');
zStrictNumberString.parse('Infinity');

zNumberString

Normalized number parser.

• Trims whitespace before parsing

import { zNumberString } from '@yukiakai/zod-extra';

zNumberString.parse(' 123 ');
// => 123

URL Schemas

zStrictURLObject

Strict URL parser that returns a URL object.

• Rejects whitespace
• Returns URL

import { zStrictURLObject } from '@yukiakai/zod-extra';

const url = zStrictURLObject.parse(
  'https://example.com',
);

url.hostname;
// => 'example.com'

zURLObject

Trimmed version of zStrictURLObject.

import { zURLObject } from '@yukiakai/zod-extra';

zURLObject.parse(' https://example.com ');

zStrictURL

Strict URL validator that returns a string.

import { zStrictURL } from '@yukiakai/zod-extra';

zStrictURL.parse('https://example.com');
// => 'https://example.com/'

zURL

Trimmed URL validator that returns a string.

import { zURL } from '@yukiakai/zod-extra';

zURL.parse(' https://example.com ');

Protocol-Specific URL Schemas

HTTP

import {
  zHttpURL,
  zHttpURLObject,
} from '@yukiakai/zod-extra';

HTTPS

import {
  zHttpsURL,
  zHttpsURLObject,
} from '@yukiakai/zod-extra';

HTTP or HTTPS

import {
  zHttpOrHttpsURL,
  zHttpOrHttpsURLObject,
} from '@yukiakai/zod-extra';

License

MIT Yuki Akai