ts-zod-utils

This package exposes various utilities extending the zod package.

API

• aws
• geojson
• json
• csv
• typeGuard
• validate

AWS

The aws module contains utilities to validate various AWS elements.

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

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";
import {
  GeoJson,
  GeoJsonBoundingBox,
  GeoJsonFeature,
  GeoJsonFeatureCollection,
  GeoJsonGeometryCollection,
  GeoJsonLineString,
  GeoJsonMultiLineString,
  GeoJsonMultiPoint,
  GeoJsonMultiPolygon,
  GeoJsonPoint,
  GeoJsonPolygon,
  GeoJsonCoordinate
} from "@infra-blocks/zod-utils/geojson";

const boundingBoxSchema = zu.geojson.boundingBox();
const boundingBox: GeoJsonBoundingBox = boundingBoxSchema.parse({...});

const featureSchema = zu.geojson.feature();
const feature: GeoJsonFeature = featureSchema.parse({...});

const featureCollectionSchema = zu.geojson.featureCollection();
const featureCollection: GeoJsonFeatureCollection = featureCollectionSchema.parse({...});

const geometryCollectionSchema = zu.geojson.geometryCollection();
const geometryCollection: GeoJsonGeometryCollection = geometryCollectionSchema.parse({...});

const lineStringSchema = zu.geojson.lineString();
const lineString: GeoJsonLineString = lineStringSchema.parse({...});

const multiLineStringSchema = zu.geojson.multiLineString();
const multiLineString: GeoJsonMultiLineString = multiLineStringSchema.parse({...});

const multiPointSchema = zu.geojson.multiPoint();
const multiPoint: GeoJsonMultiPoint = multiPointSchema.parse({...});

const multiPolygonSchema = zu.geojson.multiPolygon();
const multiPolygon: GeoJsonMultiPolygon = multiPolygonSchema.parse({...});

const pointSchema = zu.geojson.point();
const point: GeoJsonPoint = pointSchema.parse({...});

const polygonSchema = zu.geojson.polygon();
const polygon: GeoJsonPolygon = polygonSchema.parse({...});

const coordinateSchema = zu.geojson.coordinate();
const coordinate: 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()
  }
});

JSON

The json module contains utilities to validate JSON objects and stringified JSON objects.

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

// You can also parse stringified JSON!
zu.json.stringified().parse("5"); // Returns the number 5.
zu.json.stringified().parse('"JSON string"'); // Returns "JSON string". Note the quotes were removed.
zu.json.stringified().parse(JSON.strinfify({ field: "value" })); // Returns {field: "value"}.

Sub schemas & Types

import { zu } from "@infra-blocks/zod-utils";
import { Json, JsonArray, JsonObject, JsonPrimitive } from "@infra-blocks/zod-utils/json";

// The type hints are used just to showcase their usage. They aren't necessary when parsing.
// Want to parse a JSON primitive?
const jsonPrimitive: 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: 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: 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.

CSV

The csv utility is nothing but a shorthand for z.string().transform(s => s.split(",")), which is commonly written, in my experience. One can stop retyping all those letters and replace them with a simple zu.csv() call.

import { zu } from "@infra-blocks/zod-utils";

const items = zu.csv().parse("one,two,three"); // items is ["one", "two", "three"]

Type Guard

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

It can still be used with vanilla types, but then the guarantees returned by a type guard are not as strong. In our specific case, the type guard would assert that myString is a string, despite the fact that it also checked that its length has to be greater than 5. That information has been lost.

Validate

The validate 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.validate(schema, value). Both behave the same.