@sapphire/shapeshift

What is @sapphire/shapeshift?

@sapphire/shapeshift is a powerful validation library for JavaScript and TypeScript. It allows developers to define schemas for their data and validate it against these schemas. The library is designed to be highly flexible and easy to use, making it suitable for a wide range of applications.

What are @sapphire/shapeshift's main functionalities?

Basic Validation

This feature allows you to define a schema and validate an object against it. In this example, the schema expects an object with a 'name' string and an 'age' number.

const { s } = require('@sapphire/shapeshift');

const schema = s.object({
  name: s.string,
  age: s.number
});

const data = { name: 'John', age: 30 };
const result = schema.parse(data);
console.log(result); // { name: 'John', age: 30 }

Optional Fields

This feature allows you to define optional fields in your schema. In this example, the 'age' field is optional.

const { s } = require('@sapphire/shapeshift');

const schema = s.object({
  name: s.string,
  age: s.number.optional
});

const data = { name: 'John' };
const result = schema.parse(data);
console.log(result); // { name: 'John' }

Array Validation

This feature allows you to validate arrays. In this example, the schema expects an array of strings.

const { s } = require('@sapphire/shapeshift');

const schema = s.array(s.string);

const data = ['apple', 'banana', 'cherry'];
const result = schema.parse(data);
console.log(result); // ['apple', 'banana', 'cherry']

Nested Objects

This feature allows you to validate nested objects. In this example, the schema expects an object with a 'user' object that contains 'name' and 'age' fields.

const { s } = require('@sapphire/shapeshift');

const schema = s.object({
  user: s.object({
    name: s.string,
    age: s.number
  })
});

const data = { user: { name: 'John', age: 30 } };
const result = schema.parse(data);
console.log(result); // { user: { name: 'John', age: 30 } }

Other packages similar to @sapphire/shapeshift

joi

Joi is a powerful schema description language and data validator for JavaScript. It allows you to create blueprints or schemas for JavaScript objects to ensure validation of key information. Compared to @sapphire/shapeshift, Joi is more established and widely used in the industry, offering a rich set of features and integrations.

yup

Yup is a JavaScript schema builder for value parsing and validation. It is heavily inspired by Joi but is designed to work with modern JavaScript and TypeScript. Yup is known for its simplicity and ease of use, making it a popular choice for form validation in React applications. Compared to @sapphire/shapeshift, Yup offers a more modern API and better TypeScript support.

zod

Zod is a TypeScript-first schema declaration and validation library. It aims to provide a simple and expressive way to define schemas and validate data. Zod is particularly well-suited for TypeScript projects, offering excellent type inference and integration. Compared to @sapphire/shapeshift, Zod provides a more TypeScript-centric approach and better type safety.

README

@sapphire/shapeshift

ShapeShift

Blazing fast input validation and transformation ⚡

Description

A very fast and lightweight input validation and transformation library for JavaScript.

Note: ShapeShift requires Node.js v15.0.0 or higher to work.

Features

• TypeScript friendly
• Offers CJS, ESM and UMD builds
• API similar to zod
• Faster than ⚡

Usage

For complete usages, please dive into our documentation

Basic usage

Creating a simple string schema

import { s } from '@sapphire/shapeshift';

const mySchema = s.string;

// Parse
mySchema.parse('sapphire'); // => returns 'sapphire'
mySchema.parse(12); // throws ValidationError

Creating an object schema

import { s } from '@sapphire/shapeshift';

const user = s.object({
	username: s.string
});

user.parse({ username: 'Sapphire' });

Defining schemas

Primitives

import { s } from '@sapphire/shapeshift';

// Primitives
s.string;
s.number;
s.bigint;
s.boolean;
s.date;

// Empty Types
s.undefined;
s.null;
s.nullish; // Accepts undefined | null

// Catch-all Types
s.any;
s.unknown;

// Never Type
s.never;

Literals

s.literal('sapphire');
s.literal(12);
s.literal(420n);
s.literal(true);
s.literal(new Date(1639278160000)); // s.date.eq(1639278160000);

Strings

ShapeShift includes a handful of string-specific validations:

s.string.lengthLt(5);
s.string.lengthLe(5);
s.string.lengthGt(5);
s.string.lengthGe(5);
s.string.lengthEq(5);
s.string.lengthNe(5);
s.string.email;
s.string.url();
s.string.uuid();
s.string.regex(regex);
s.string.ip();
s.string.ipv4;
s.string.ipv6;

Numbers

ShapeShift includes a handful of number-specific validations:

s.number.gt(5); // > 5
s.number.ge(5); // >= 5
s.number.lt(5); // < 5
s.number.le(5); // <= 5
s.number.eq(5); // === 5
s.number.ne(5); // !== 5

s.number.eq(NaN); // special case: Number.isNaN
s.number.ne(NaN); // special case: !Number.isNaN

s.number.int; // value must be an integer
s.number.safeInt; // value must be a safe integer
s.number.finite; // value must be finite

s.number.positive; // .ge(0)
s.number.negative; // .lt(0)

s.number.divisibleBy(5); // Divisible by 5

And transformations:

s.number.abs; // Transforms the number to an absolute number
s.number.sign; // Gets the number's sign

s.number.trunc; // Transforms the number to the result of `Math.trunc`
s.number.floor; // Transforms the number to the result of `Math.floor`
s.number.fround; // Transforms the number to the result of `Math.fround`
s.number.round; // Transforms the number to the result of `Math.round`
s.number.ceil; // Transforms the number to the result of `Math.ceil`

BigInts

ShapeShift includes a handful of number-specific validations:

s.bigint.gt(5n); // > 5n
s.bigint.ge(5n); // >= 5n
s.bigint.lt(5n); // < 5n
s.bigint.le(5n); // <= 5n
s.bigint.eq(5n); // === 5n
s.bigint.ne(5n); // !== 5n

s.bigint.positive; // .ge(0n)
s.bigint.negative; // .lt(0n)

s.bigint.divisibleBy(5n); // Divisible by 5n

And transformations:

s.bigint.abs; // Transforms the bigint to an absolute bigint

s.bigint.intN(5); // Clamps to a bigint to a signed bigint with 5 digits, see BigInt.asIntN
s.bigint.uintN(5); // Clamps to a bigint to an unsigned bigint with 5 digits, see BigInt.asUintN

Booleans

ShapeShift includes a few boolean-specific validations:

s.boolean.true; // value must be true
s.boolean.false; // value must be false

s.boolean.eq(true); // s.boolean.true
s.boolean.eq(false); // s.boolean.false

s.boolean.ne(true); // s.boolean.false
s.boolean.ne(false); // s.boolean.true

Arrays

const stringArray = s.array(s.string);
const stringArray = s.string.array;

ShapeShift includes a handful of array-specific validations:

s.string.array.lengthLt(5); // Must have less than 5 elements
s.string.array.lengthLe(5); // Must have 5 or less elements
s.string.array.lengthGt(5); // Must have more than 5 elements
s.string.array.lengthGe(5); // Must have 5 or more elements
s.string.array.lengthEq(5); // Must have exactly 5 elements
s.string.array.lengthNe(5); // Must not have exactly 5 elements
s.string.array.lengthRange(0, 4); // Must have at least 0 elements and less than 4 elements (in math, that is [0, 4))
s.string.array.lengthRangeInclusive(0, 4); // Must have at least 0 elements and at most 4 elements (in math, that is [0, 4])
s.string.array.lengthRangeExclusive(0, 4); // Must have more than 0 element and less than 4 elements (in math, that is (0, 4))

Note: All .length methods define tuple types with the given amount of elements. For example, s.string.array.lengthGe(2)'s inferred type is [string, string, ...string[]]

Tuples

Unlike arrays, tuples have a fixed number of elements and each element can have a different type:

const dish = s.tuple([
	s.string, // Dish's name
	s.number.int, // Table's number
	s.date // Date the dish was ready for delivery
]);

dish.parse(['Iberian ham', 10, new Date()]);

Objects

// Properties are required by default:
const animal = s.object({
	name: s.string,
	age: s.number
});

.extend:

You can add additional fields using either an object or an ObjectValidator, in this case, you will get a new object validator with the merged properties:

const pet = animal.extend({
	owner: s.string.nullish
});

const pet = animal.extend(
	s.object({
		owner: s.string.nullish
	})
);

If both schemas share keys, an error will be thrown. Please use .omit on the first object if you desire this behaviour.

.pick / .omit:

Inspired by TypeScript's built-in Pick and Omit utility types, all object schemas have the aforementioned methods that return a modifier version:

const pkg = s.object({
	name: s.string,
	description: s.string,
	dependencies: s.string.array
});

const justTheName = pkg.pick(['name']);
// s.object({ name: s.string });

const noDependencies = pkg.omit(['dependencies']);
// s.object({ name: s.string, description: s.string });

.partial

Inspired by TypeScript's built-in Partial utility type, all object schemas have the aforementioned method that makes all properties optional:

const user = s
	.object({
		username: s.string,
		password: s.string
	})
	.partial();

Which is the same as doing:

const user = s.object({
	username: s.string.optional,
	password: s.string.optional
});

Unrecognized keys

By default, ShapeShift will not include keys that are not defined by the schema during parsing:

const person = s.object({
	framework: s.string
});

person.parse({
	framework: 'Sapphire',
	awesome: true
});
// => { name: 'Sapphire' }

.strict

You can disallow unknown keys with .strict. If the input includes any unknown keys, an error will be thrown.

const person = s.object({
	framework: s.string
}).strict;

person.parse({
	framework: 'Sapphire',
	awesome: true
});
// => throws ValidationError

.ignore

You can use the .ignore getter to reset an object schema to the default behaviour (ignoring unrecognized keys).

.passthrough

You can use the .passthrough getter to make the validator add the unrecognized properties the shape does not have, from the input.

Records

Record schemas are similar to objects, but validate Record<string, T> types, keep in mind this does not check for the keys, and cannot support validation for specific ones:

const tags = s.record(s.string);

tags.parse({ foo: 'bar', hello: 'world' }); // => { foo: 'bar', hello: 'world' }
tags.parse({ foo: 42 }); // => throws CombinedError
tags.parse('Hello'); // => throws ValidateError

Unions

ShapeShift includes a built-in method for composing OR types:

const stringOrNumber = s.union(s.string, s.number);

stringOrNumber.parse('Sapphire'); // => 'Sapphire'
stringOrNumber.parse(42); // => 42
stringOrNumber.parse({}); // => throws CombinedError

Enums

Enums are a convenience method that aliases s.union(s.literal(a), s.literal(b), ...):

s.enum('Red', 'Green', 'Blue');
// s.union(s.literal('Red'), s.literal('Green'), s.literal('Blue'));

Maps

const map = s.map(s.string, s.number);
// Map<string, number>

Sets

const set = s.set(s.number);
// Set<number>

Instances

You can use s.instance(Class) to check that the input is an instance of a class. This is useful to validate inputs against classes:

class User {
	public constructor(public name: string) {}
}

const schema = s.instance(User);
schema.parse(new User('Sapphire')); // => User { name: 'Sapphire' }
schema.parse('oops' as any); // => throws ValidatorError

Functions // TODO

You can define function schemas. This checks for whether or not an input is a function:

s.function; // () => unknown

You can define arguments by passing an array as the first argument, as well as the return type as the second:

s.function([s.string]); // (arg0: string) => unknown
s.function([s.string, s.number], s.string); // (arg0: string, arg1: number) => string

Note: ShapeShift will transform the given function into one with validation on arguments and output. You can access the .raw property of the function to get the unchecked function.

BaseValidator: methods and properties

All schemas in ShapeShift contain certain methods.

.run(data: unknown): Result<T, Error>: given a schema, you can call this method to check whether or not the input is valid. If it is, a Result with success: true and a deep-cloned value will be returned with the given constraints and transformations. Otherwise, a Result with success: false and an error is returned.

.parse(data: unknown): T: given a schema, you can call this method to check whether or not the input is valid. If it is, a deep-cloned value will be returned with the given constraints and transformations. Otherwise, an error is thrown.

.transform<R>((value: T) => R): NopValidator<R>: adds a constraint that modifies the input:

import { s } from '@sapphire/shapeshift';

const getLength = s.string.transform((value) => value.length);
getLength.parse('Hello There'); // => 11

:warning: .transform's functions must not throw. If a validation error is desired to be thrown, .reshape instead.

.reshape<R>((value: T) => Result<R, Error> | IConstraint): NopValidator<R>: adds a constraint able to both validate and modify the input:

import { s, Result } from '@sapphire/shapeshift';

const getLength = s.string.reshape((value) => Result.ok(value.length)); // TODO
getLength.parse('Hello There'); // => 11

:warning: .reshape's functions must not throw. If a validation error is desired to be thrown, use Result.err(error) instead.

.default(value: T | (() => T)): transform undefined into the given value or the callback's returned value:

const name = s.string.default('Sapphire');
name.parse('Hello'); // => 'Hello'
name.parse(undefined); // => 'Sapphire'

const number = s.number.default(Math.random);
number.parse(12); // => 12
number.parse(undefined); // => 0.989911985608602
number.parse(undefined); // => 0.3224350185068794

:warning: The default values are not validated.

.optional: a convenience method that returns a union of the type with s.undefined.

s.string.optional; // s.union(s.string, s.undefined)

.nullable: a convenience method that returns a union of the type with s.nullable.

s.string.nullable; // s.union(s.string, s.nullable)

.nullish: a convenience method that returns a union of the type with s.nullish.

s.string.nullish; // s.union(s.string, s.nullish)

.array: a convenience method that returns an ArrayValidator with the type.

s.string.array; // s.array(s.string)

.or: a convenience method that returns an UnionValidator with the type. This method is also overridden in UnionValidator to just append one more entry.

s.string.or(s.number);
// => s.union(s.string, s.number)

s.object({ name: s.string }).or(s.string, s.number);
// => s.union(s.object({ name: s.string }), s.string, s.number)

Buy us some doughnuts

Sapphire Community is and always will be open source, even if we don't get donations. That being said, we know there are amazing people who may still want to donate just to show their appreciation. Thank you very much in advance!

We accept donations through Open Collective, Ko-fi, Paypal, Patreon and GitHub Sponsorships. You can use the buttons below to donate through your method of choice.

Donate With	Address
Open Collective	Click Here
Ko-fi	Click Here
Patreon	Click Here
PayPal	Click Here

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Antonio Román 💻 📖 🤔

Vlad Frangu 💻 📖 🤔

Jeroen Claassens 📖 🚧 🚇

renovate[bot] 🚧

WhiteSource Renovate 🚧

John 💻

Parbez 💻 ⚠️ 🐛 📖

This project follows the all-contributors specification. Contributions of any kind welcome!