Table of contents

• Installation
• Basic usage
• Booleans
• Numbers
• Strings
• Errors

Installation

Requirements

Roud inherits requirements from Zod itself:

• Typescript 4.1+

• Strict mode activated

  // tsconfig.json
  {
  	// ...
  	"compilerOptions": {
  		// ...
  		"strict": true
  	}
  }

Node

Zod is a peer dependency and must be installed alongside Roud.

npm install roud zod

Basic usage

Roud fully extends Zod and for the most parts can be used outside of Remix. For simplicity reasons the following example will show how it should be used within Remix action.

import { ActionArgs } from "@remix-run/server-runtime";
import { r } from "roud";

const action = async ({ request }: ActionArgs) => {
	const Schema = r.schema({
		title: r.string(),
		quantity: r.number().min(0).max(10),
		termsOfService: r.boolean().accepted(),
	});

	const formData = await Schema.parseRequestFormData(request);
	// Type ^
	// {
	//     title: string;
	//     quantity: number;
	//     termsOfService: boolean;
	// }
};

If you used Zod before, parseRequestFormData() acts the same as parse() and throws RoudError if validation fails. You can also use safeParseRequestFormData which instead of throwing will return either the data or RoudError.

Booleans

Accepts true, "yes", "on", "true" "1", 1, false, "no", "off", "false" "0", 0 and normalizes the value to either true or false.

Available validators

| Validator | Description | | ------------------------------------- | ----------------------------------------------------------- | | accepted() | Boolean must be true | | acceptedIf(callback: () => boolean) | Boolean must be true when callback evaluates to true | | declined() | Boolean must be false | | declinedIf(callback: () => boolean) | Boolean must be false when callback evaluates to true |

Example

const Schema = r.schema({
	termsOfService: r.boolean().accepted(),
});

Numbers

Accepts any value parsable by Javascript's Number() constructor and normalizes it to real number.

Available validators

| Validator | Description | | ----------------------------------------- | ------------------------------------------------------------------------- | | between(min: number, max: number) | Number must have a size between the given minimum and maximum (inclusive) | | digits(digits: number) | Number must have an exact length of value | | digitsBetween(min: number, max: number) | Number must have a length between the given mininum and maximum | | integer() | Number must be an integer | | max(number: number) | Number must be less than or equal to a maximum value | | maxDigits(digits: number) | Number must have a maximum length of value | | min(number: number) | Number must have a minimum value | | minDigits(digits: number) | Number must have a minimum length of value | | multipleOf(number: number) | Number must must be a multiple of value |

Example

const Schema = r.schema({
	quantity: r.number().integer().between(0, 10),
	price: r.number().min(0),
});

Strings

Accepts any string value.

Available validators

| Validator | Description | | ------------------------------------------ | ----------------------------------------------------------------- | | doesNotEndWith(string: string) | String must not end with a provided value | | doesNotStartWith(string: string) | String must not start with a provided value | | email() | String must be a valid email address | | endsWith(string: string) | String must end with a provided value | | ipAddress() | String must be a valid IPv4 address | | json() | String must be a valid JSON | | macAddress() | String must be a valid MAC address | | notRegex(regExp: RegExp) | String must not match the given regular expression | | onlyLetters() | String must only contain letters | | onlyLettersAndNumbers() | String must only contain letters and numbers | | onlyLettersNumbersAndDashes() | String must only contain letters, numbers and dashes | | onlyLettersNumbersDashesAndUnderscores() | String must only contain letters, numbers, dashes and underscores | | regex(regExp: RegExp) | String must match the given regular expression | | startsWith(string: string) | String must start with a provided value | | timeZone() | String must be a valid time zone | | url() | String must be a valid URL | | uuid() | String must be a valid UUID |

Example

const Schema = r.schema({
	title: r.string().onlyLetters(),
	username: r.string().onlyLettersNumbersDashesAndUnderscores(),
});

Errors

Roud extends the default ZodError which simplifies passing errors back to the form. Here is an basic example:

import { ActionArgs } from "@remix-run/server-runtime";
import { r } from "roud";

const action = async ({ request }: ActionArgs) => {
	const Schema = r.schema({
		title: r.string(),
		quantity: r.number().min(0).max(10),
		termsOfService: r.boolean().accepted(),
	});

	const formDataResult = await Schema.safeParseRequestFormData(request);

	if (formDataResult.success) {
		return json({ formData: formDataResult.data });
	}

	return json({ formDataErrors: formDataResult.error.getValidationErrors() });
	// Type ^
	// {
	//     title: ["The title must be a string."],
	//     quantity: [
	//         "The title must be a number.",
	//         "The quantity must be at least 0.",
	//         "The quantity must not be greater than 10.",
	//     ],
	//     termsOfService: [
	//         "The termsOfService must be a boolean.",
	//         "The termsOfService must be accepted.",
	//     ],
	// }
};