Zod Schemas for apps on ICP

A collection of reusable Zod schemas and validators for common data patterns in Internet Computer applications.

Table of contents

• Installation
• Features

Installation

You can use the library by installing it in your project.

npm i @dfinity/zod-schemas

The bundle needs peer dependencies, be sure that following resources are available in your project as well.

npm i @icp-sdk/core

Features

The library implements following features:

:toolbox: Functions

• inferOptionSchema
• inferNullishSchema
• inferNullableSchema
• inferResultSchema
• createUrlSchema

:gear: inferOptionSchema

| Function | Type | | ------------------- | ---------------------------------------------------- | | inferOptionSchema | <T extends z.ZodType>(schema: T) => ZodOptional<T> |

References:

• Option

:link: Source

:gear: inferNullishSchema

| Function | Type | | -------------------- | ----------------------------------------------------------------- | | inferNullishSchema | <T extends z.ZodType>(schema: T) => ZodOptional<ZodNullable<T>> |

References:

• Nullable

:link: Source

:gear: inferNullableSchema

| Function | Type | | --------------------- | ---------------------------------------------------- | | inferNullableSchema | <T extends z.ZodType>(schema: T) => ZodNullable<T> |

References:

• Nullish

:link: Source

:gear: inferResultSchema

| Function | Type | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | inferResultSchema | <T extends z.ZodType>(schema: T) => ZodDiscriminatedUnion<[ZodObject<{ status: ZodLiteral<"success">; result: T; }, $strict>, ZodObject<{ status: ZodLiteral<"error">; err: ZodOptional<...>; }, $strict>]> |

References:

• Result

:link: Source

:gear: createUrlSchema

Creates a Zod schema for validating URLs. By default, it validates that the URL protocol is HTTPS and allow usage of HTTP only locally.

| Function | Type | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | createUrlSchema | ({ additionalProtocols, allowHttpLocally, }: { additionalProtocols?: ${string}:[] or undefined; allowHttpLocally?: boolean or undefined; }) => ZodURL |

Parameters:

• options: - Configuration options for the schema.
• options.additionalProtocols: - Additional protocols to allow (e.g., "wss:" or "ftp:"). ⚠️ Usage of insecure protocols is discouraged.
• options.allowHttpLocally: - Whether to allow HTTP for localhost and 127.0.0.1. Default: true.

Returns:

• The Zod schema with URL validation.

Examples:

const schema = createUrlSchema({ additionalProtocols: ["wss:"], allowHttpLocally: false });

schema.parse("https://example.com"); // Valid schema.parse("wss://example.com"); // Valid schema.parse("http://localhost"); // Invalid if allowHttpLocally is false

:link: Source

:wrench: Constants

• Uint8ArraySchema
• PrincipalTextSchema
• PrincipalSchema
• UrlSchema

:gear: Uint8ArraySchema

Zod schema to validate a value is a Uint8Array instance.

| Constant | Type | | ------------------ | ------------------------------------------------------------- | | Uint8ArraySchema | ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>> |

Examples:

const result = Uint8ArraySchema.safeParse(new Uint8Array([1, 2, 3]));
console.log(result.success); // true or false

:link: Source

:gear: PrincipalTextSchema

Zod schema to validate a string as a valid textual representation of a Principal.

This schema checks if the provided string can be converted into a Principal instance. If the conversion fails, validation will return an error message.

| Constant | Type | | --------------------- | ----------- | | PrincipalTextSchema | ZodString |

Examples:

const result = PrincipalTextSchema.safeParse("aaaaa-aa");
console.log(result.success); // true or false

:link: Source

:gear: PrincipalSchema

Zod schema to validate and transform a value into a Principal instance.

This schema checks if the provided value is an instance or an object representing a Principal and transforms it into a valid Principal instance.

| Constant | Type | | ----------------- | ------------------------------------------------------------------------ | | PrincipalSchema | ZodPipe<ZodCustom<Principal, Principal>, ZodTransform<any, Principal>> |

Examples:

const result = PrincipalSchema.safeParse(Principal.fromText("aaaaa-aa"));
console.log(result.success); // true or false

:link: Source

:gear: UrlSchema

Default URL schema that enforces HTTPS and allows HTTP locally.

| Constant | Type | | ----------- | -------- | | UrlSchema | ZodURL |

Examples:

UrlSchema.parse("https://example.com"); // Valid UrlSchema.parse("http://127.0.0.1"); // Valid (localhost exception)

:link: Source

:nut_and_bolt: Enum

• ZodSchemaId

:gear: ZodSchemaId

Enum of metadata id values assigned to Zod schemas in this library.

| Property | Type | Description | | --------------- | ----------------- | --------------------------------------------- | | PrincipalText | "PrincipalText" | Metadata id for {@link PrincipalTextSchema }. | | Principal | "Principal" | Metadata id for {@link PrincipalSchema }. | | Uint8Array | "Uint8Array" | Metadata id for {@link Uint8ArraySchema }. | | Url | "Url" | Metadata id for {@link UrlSchema }. |

:link: Source