一覧へ戻る
infra-blocks/ts-zod-utils（新しいタブで開きます）
主要言語: TypeScript
Extensions of the zod package with various utilities.
- star 数
- 5
- watcher 数
- 0
- fork 数
- 0
- issue 数
- 0
- 最終更新
- 2026/10/02
gem-hunter主要言語: TypeScript
Extensions of the zod package with various utilities.
zod is an amazing parsing library. This package aims to extend it with various utilities that I've found useful through my own programming. Those include schemas I find myself writing often, codecs that are shown in Zod's documentation but not yet available, and type utilities.
Some schemas return branded types for extra type safety. When that is the case, the documentation will highlight that fact. Otherwise, assume classical structural Typescript as output types.
When branding is used, the brand is a string that's the same as the name of the type. For example, the AwsAccountId
is an alias for string & z.$brand<"AwsAccountId">.
One caveat of using branded types schema is that the default value must also be branded (as should be). So,
for example, where you would write z.int().default(5), you instead have to write zu.number.integer().default(zu.number.integer().parse(5)).
This example also highlights an inconsistency with Zod where you can have z.int().default(123.456), which both
compiles and runs successfully.
The zu.aws module contains utilities to validate various AWS elements. All schemas return branded types.
import { zu } from "@infra-blocks/zod-utils"; // Validates a 12 digit string, as describe here: https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-identifiers.html zu.aws.accountId().parse("123456789012"); // Validates an AWS ARN, as described here: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html zu.aws.arn().parse("arn:aws:iam:us-east-1:123456789012:user/joe-cunt"); // Validates an AWS partition, as describe here: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html zu.aws.partition().parse("aws"); // Validates an AWS region, as described here: https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions // "gov" and "cn" regions are included. zu.aws.region().parse("us-east-1");
The zu.codec module contains codecs.
The zu.codec.bytes(options) utility is a factory returning a codec where the schemas are
z.string() and z.number(). The transformations in both directions are handled by the
bytes package. When encoding, the codec passes the options
provided to bytes.format(number, options).
import { zu } from "@infra-blocks/zod-utils"; const item: number = zu.codec.bytes().parse("1tb"); // item is 1099511627776. zu.codec.bytes({ unit: "mb" }).encode(item); // result is "1048576mb".
The zu.codec.csv() utility is a codec transforming a string into an array of string using the string split method
to do so. It uses zu.codec.stringSplit(",") internally.
import { zu } from "@infra-blocks/zod-utils"; const items = zu.codec.csv().parse("one,two,three"); // items is ["one", "two", "three"]
The zu.codec.jsonParse(schema) utility is a factory returning a codec where the first schema is
zu.string.json() and the second one is the one provided as input. This is almost verbatim
what is describe in Zod's documentation.
The zu.codec.ms(options) utility is a factory returning a codec where the schemas are
z.string() and z.number(). The transformations in both directions are handled by the
ms package. When encoding, the codec passes the options
provided to ms(number, options).
import { zu } from "@infra-blocks/zod-utils"; const item: number = zu.codec.ms().parse("1d"); // item is 86400000. zu.codec.ms({ long: true }).encode(item); // result is "1 day".
The zu.codec.stringSplit(separator) utility is a factory returning a codec where the first schema is
z.string(), the second schema is z.array(z.string()), and the transformations back and forth
are accomplished using String.split and Array.join respectively, using the provided separator.
The zu.codec.stringToBuffer(encoding) utility is a factory returning a codec where the first
schema is z.string(), the secon schema is z.instanceof(Buffer), and the transformations
back and forth are accomplished using Buffer.from and buffer.toString with the provided
encoding.
import { zu } from "@infra-blocks/zod-utils"; // Defaults to utf-8, because Buffer functions default to utf-8. const utf8Codec = zu.codec.stringToBuffer(); // A specific encoding can be provided. const base64Codec = zu.codec.stringToBuffer("base64"); utf8Codec.parse("1234"); // Returns Buffer.from("1234"); base64codec.parse("1234"); // Returns Buffer.from("1234", "base64");
The zu.codec.stringToInteger() codec is taken almost verbatim
from Zod's own documentation. The
only difference is the final type is branded as it is using zu.integer() internally.
import { zu } from "@infra-blocks/zod-utils"; import { Integer } from "@infra-blocks/zod-utils"; const item: Integer = zu.codec.stringToInteger().parse("1234");
The zu.codec.stringToJson() codec transforms a string into JSON using JSON.parse.
It uses zu.codec.jsonParse(zu.json()) internally.
import { zu } from "@infra-blocks/zod-utils"; const item: zu.Json = zu.codec.stringToJson().parse('[1, "word", null]');
The zu.codec.stringToPositiveInteger() is the positiveInteger variant of zu.codec.stringToInteger.
The final type is zu.PositiveInteger.
import { zu } from "@infra-blocks/zod-utils"; import { PositiveInteger } from "@infra-blocks/zod-utils"; const item: PositiveInteger = zu.codec.stringToPositiveInteger().parse("1234");
The zu.codec.stringToUrl() codec is taken Zod's own documentation.
The result is a URL object. No branding here esé.
import { zu } from "@infra-blocks/zod-utils"; const item: URL = zu.codec.stringToUrl().parse("http://localhost:3000");
The geojson module contains utilities to validate GeoJSON objects.
import { zu } from "@infra-blocks/zod-utils"; // Supports all GeoJSON types. // All geometries are supported. zu.geojson().parse({ type: "Point", coordinates: [1, 2] }); // Features zu.geojson().parse({ type: "Feature", geometry: { type: "LineString", // Works with 3d coordinates too. coordinates: [[1, 2, 3], [4, 4, 6]] }, // Either null or a JSON object. properties: { name: "BigFeature" } }); // Feature collections zu.geojson().parse({ type: "FeatureCollection", features: [ { type: "Feature", geometry: { type: "Polygon", coordinates: [[[1, 2], [2, 2], [2, 1], [1, 1]]] }, properties: { name: "BroSquare" } } ] });
For convenience, the module also exports sub schemas and types. This way, a user can pick and choose which schemas they specifically need in their context, or which ones they'd like to extend and customize.
import {zu} from "@infra-blocks/zod-utils"; const boundingBoxSchema = zu.geojson.boundingBox(); const boundingBox: zu.GeoJsonBoundingBox = boundingBoxSchema.parse({...}); const featureSchema = zu.geojson.feature(); const feature: zu.GeoJsonFeature = featureSchema.parse({...}); const featureCollectionSchema = zu.geojson.featureCollection(); const featureCollection: zu.GeoJsonFeatureCollection = featureCollectionSchema.parse({...}); const geometryCollectionSchema = zu.geojson.geometryCollection(); const geometryCollection: zu.GeoJsonGeometryCollection = geometryCollectionSchema.parse({...}); const lineStringSchema = zu.geojson.lineString(); const lineString: zu.GeoJsonLineString = lineStringSchema.parse({...}); const multiLineStringSchema = zu.geojson.multiLineString(); const multiLineString: zu.GeoJsonMultiLineString = multiLineStringSchema.parse({...}); const multiPointSchema = zu.geojson.multiPoint(); const multiPoint: zu.GeoJsonMultiPoint = multiPointSchema.parse({...}); const multiPolygonSchema = zu.geojson.multiPolygon(); const multiPolygon: zu.GeoJsonMultiPolygon = multiPolygonSchema.parse({...}); const pointSchema = zu.geojson.point(); const point: zu.GeoJsonPoint = pointSchema.parse({...}); const polygonSchema = zu.geojson.polygon(); const polygon: zu.GeoJsonPolygon = polygonSchema.parse({...}); const coordinateSchema = zu.geojson.coordinate(); const coordinate: zu.GeoJsonCoordinate = coordinateSchema.parse([1, 2]);
The module follows the spec. Note that the spec states the following:
GeoJSON processors MAY interpret Geometry objects with empty "coordinates" arrays as null objects.
This module tolerates empty coordinates arrays where the spec doesn't explicitly state that it must not be empty. For example, the following won't throw:
zu.geojson().parse({ type: "MultiLineString", coordinates: [] });
However, the following will throw because the spec explicitly states the coordinates must contain at least two positions:
zu.geojson().parse({ type: "LineString", coordinates: [] });
This behaviour could become configurable in a future version with a stricter default approach.
GeoJSON features must have properties. Those properties are either null or a JSON object. This module uses
the json module to validate the properties. This means that the following will throw:
zu.geojson().parse({ type: "Feature", geometry: { type: "Point", coordinates: [1, 2] }, properties: { notJson: new Map() } });
The zu.inferBrand<T> type utility extracts the brand(s) from a given type. It resolves to never if the
type is not branded. It unionizes the brands if more than one exists.
import { z } from "zod"; import { zu } from "@infra-blocks/zod-utils"; type Never = zu.inferBrand<string>; // Resolves to never. type StringBrand = zu.inferBrand<number & z.$brand<"Toto">>; // Resolves to "Toto". type UnionBrands = zu.inferBrand<number & z.$brand<"Toto"> & z.$brand<5>>; // Resolves to "Toto" | 5.
The iso module is an extension of zod's own iso module. All schemas return branded types.
import { zu } from "@infra-blocks/zod-utils"; zu.iso.currencyCode().parse("USD"); zu.iso.currencyCode().parse("CAD"); zu.iso.countryCode.alpha3("USA"); // The greatest country on earth. zu.iso.countryCode.alpha3("CAN"); // Its communist little brother.
The json module contains utilities to validate JSON objects, arrays and primitives.
import { zu } from "@infra-blocks/zod-utils"; // Works with any scalar zu.json().parse(0); zu.json().parse("hello"); zu.json().parse(true); zu.json().parse(null); // With arrays and objects too. zu.json().parse([1, "bye", false, null, ["nested"]]); zu.json().parse({ number: 42, string: "hello again, I guess", boolean: true, null: null, array: [1, "bye", false, null], nested: { someField: "you get it" } }); // Throws for bullshit. zu.json().parse(undefined); // Boom. zu.json().parse(Symbol("nope")); // Boom. zu.json().parse(new Set()); // Boom. // etc...
import { zu } from "@infra-blocks/zod-utils"; // Want to parse a JSON primitive? const jsonPrimitive: zu.JsonPrimitive = zu.json.primitive().parse(5); // Will throw for anything that is not a JSON primitive. zu.json.primitive().parse([]); // Boom. zu.json.primitive().parse({}); // Boom. zu.json.primitive().parse(undefined); // Boom. // A JSON array maybe? const jsonArray: zu.JsonArray = zu.json.array().parse([1, 2, 3]); // Will throw for anything that is not a JSON array. zu.json.array().parse(5); // Boom. zu.json.array().parse({}); // Boom. // And finally, what about making sure you get a JSON object? const jsonObject: zu.JsonObject = zu.json.object().parse({ hello: "world" }); // You know it by now, but just to make sure. zu.json.object().parse(5); // Boom. zu.json.object().parse([]); // Boom.
The zu.number module exports utilities for parsing numbers. All schemas return branded types.
zu.number.integer() produces a branded type using z.int() internally.
import { zu } from "@infra-blocks/zod-utils"; function expectsInteger(x: zu.Integer) { // Do some bull here. } expectsInteger(zu.number.integer().parse(42));
zu.number.positiveInteger() produces a branded type. It using z.int().min(0) internally.
import { zu } from "@infra-blocks/zod-utils"; function doingBull(x: zu.PositiveInteger) { // Do some bull here. } doingBull(zu.number.positiveInteger().parse(42));
The zu.string module exposes schemas for manipulating strings. All schemas return branded types.
Which means, their result can be used as strings anywhere, but strings cannot be used in place of the corresonding
type.
import { zu } from "@infra-blocks/zod-utils"; import { expectTypeOf } from "expect-type"; const result = zu.string.base64url().parse("w6p0cmUgb3UgbmUgcGFzIMOqdHJlIGVzdGk_"); expectTypeOf(result).toEqualTypeOf<zu.IntegerString>(); expect(result).to.equal("w6p0cmUgb3UgbmUgcGFzIMOqdHJlIGVzdGk_");
import { zu } from "@infra-blocks/zod-utils"; import { expectTypeOf } from "expect-type"; // Uses z.string().regex(z.regexes.integer) internally. const result = zu.string.integer().parse("1234"); expectTypeOf(result).toEqualTypeOf<zu.IntegerString>(); expect(result).to.equal("1234");
import { zu } from "@infra-blocks/zod-utils"; import { expectTypeOf } from "expect-type"; const result = zu.string.json().parse('[1, "word", null]'); expectTypeOf(result).toEqualTypeOf<zu.UrlString>(); expect(result).to.equal('[1, "word", null]');
import { zu } from "@infra-blocks/zod-utils"; import { expectTypeOf } from "expect-type"; // Uses z.string().regex(z.regexes.number) internally. const result = zu.string.integer().parse("1234.5678"); expectTypeOf(result).toEqualTypeOf<zu.NumberString>(); expect(result).to.equal("1234.5678");
import { zu } from "@infra-blocks/zod-utils"; import { expectTypeOf } from "expect-type"; // Uses z.string().regex(/^\d+$/) internally. const result = zu.string.positiveInteger().parse("1234"); expectTypeOf(result).toEqualTypeOf<zu.PositiveIntegerString>(); expect(result).to.equal("1234");
The typeGuard utility allows to obtain a function that will act as a type guard for the type
that the wrapped schema outputs. It is most useful with branded types, where the information
about the rules of the type is contained within it. Example:
import { z } from "zod"; import { zu } from "@infra-blocks/zod-utils"; import { expectTypeOf } from "expect-type"; export type Min5String = z.infer<typeof schema>; const schema = z.string().min(5).brand("Min5String"); const isMin5String = zu.typeGuard(schema); const myString = "toto-stfu"; if (isMin5String(myString)) { // Here, the type of myString extends Min5String (it's actually `"toto-stfu" & z.$brand<"Min5String">` // instead of `string & z.$brand<"Min5String">`) expectTypeOf(myString).toExtend<Min5String>(); } else { expectTypeOf(myString).toEqual<"toto-stfu">(); }
The isValid API is very similar to the type guard one, except it doesn't bind
to a schema. The schema is passed as argument. Where you would write zu.typeGuard(schema)(value),
you instead write zu.isValid(schema, value). Both behave the same and narrow the result type.