ts-zod-utils

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.

Branded types

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.

API

• aws
• codec
• geojson
• inferBrand
• iso
• json
• number
• string
• typeGuard
• isValid

aws

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");

codec

The zu.codec module contains codecs.

bytes

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

csv

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"]

jsonParse

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.

ms

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

stringSplit

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.

stringToBuffer

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");

stringToInteger

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");

stringToJson

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]');

stringToPositiveInteger

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");

stringToUrl

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");

geojson

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"
      }
    }
  ]
});

Sub schemas & Types

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]);

Design considerations

Empty coordinates arrays

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.

Properties

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()
  }
});

inferBrand

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.

iso

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.

json

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

Sub schemas & Types

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.

number

The zu.number module exports utilities for parsing numbers. All schemas return branded types.

integer

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));

positiveInteger

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));

string

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.

base64url

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_");

integer

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");

json

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]');

number

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");

positiveInteger

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");

typeGuard

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">();
}

Is Valid

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.