Table of Contents

• Table of Contents
• Description
• Features
• Usage
  • Basic usage
  • Defining validations
    • Primitives
    • Literals
    • Strings
    • Numbers
    • BigInts
    • Booleans
    • Arrays
    • Tuples
    • Unions
    • Enums
    • Maps
    • Sets
    • Instances
    • Records
    • TypedArray
  • Defining schemas (objects)
    • Utility types for TypeScript
      • Extracting an interface from a schema
      • Defining the structure of a schema through an interface
    • .extend:
    • .pick / .omit:
    • .partial
    • .required
  • Handling unrecognized keys
    • .strict
    • .ignore
    • .passthrough
  • BaseValidator: methods and properties
    • .run(data: unknown): Result: given a validation, you can call this method to check whether or not the
    • .parse(data: unknown): T: given a validations, you can call this method to check whether or not the input is valid.
    • .transform((value: T) => R): NopValidator: adds a constraint that modifies the input:
    • .reshape((value: T) => Result | IConstraint): NopValidator: adds a constraint able to both validate
    • .default(value: T | (() => T)): transform undefined into the given value or the callback's returned value:
    • .optional: a convenience method that returns a union of the type with s.undefined().
    • .nullable: a convenience method that returns a union of the type with s.nullable().
    • .nullish: a convenience method that returns a union of the type with s.nullish().
    • .array: a convenience method that returns an ArrayValidator with the type.
    • .or: a convenience method that returns an UnionValidator with the type. This method is also overridden in
    • .when: Adjust the schema based on a sibling or sinbling children fields.
      • Available options for providing is
      • Resolving of the key (first) parameter
      • Examples
  • Enabling and disabling validation
• Buy us some doughnuts
• Contributors

Description

Back to top

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

Note: Shapeshift requires Node.js v14.0.0 or higher to work.

Features

Back to top

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

Usage

Back to top

For complete usages, please dive into our documentation

Basic usage

Back to top

Creating a simple string validation

1import { s } from '@sapphire/shapeshift';
2
3const myStringValidation = s.string();
4
5// Parse
6myStringValidation.parse('sapphire'); // => returns 'sapphire'
7myStringValidation.parse(12); // throws ValidationError

Creating an object schema

1import { s } from '@sapphire/shapeshift';
2
3const user = s.object({
4  username: s.string()
5});
6
7user.parse({ username: 'Sapphire' });

Defining validations

Back to top

Primitives

Back to top

1import { s } from '@sapphire/shapeshift';
2
3// Primitives
4s.string();
5s.number();
6s.bigint();
7s.boolean();
8s.date();
9
10// Empty Types
11s.undefined();
12s.null();
13s.nullish(); // Accepts undefined | null
14
15// Catch-all Types
16s.any();
17s.unknown();
18
19// Never Type
20s.never();

Literals

Back to top

1s.literal('sapphire');
2s.literal(12);
3s.literal(420n);
4s.literal(true);
5s.literal(new Date(1639278160000)); // s.date().equal(1639278160000);

Strings

Back to top

Shapeshift includes a handful of string-specific validations:

1s.string().lengthLessThan(5);
2s.string().lengthLessThanOrEqual(5);
3s.string().lengthGreaterThan(5);
4s.string().lengthGreaterThanOrEqual(5);
5s.string().lengthEqual(5);
6s.string().lengthNotEqual(5);
7s.string().email();
8s.string().url();
9s.string().uuid();
10s.string().regex(regex);
11s.string().ip();
12s.string().ipv4();
13s.string().ipv6();
14s.string().phone();

Numbers

Back to top

Shapeshift includes a handful of number-specific validations:

1s.number().greaterThan(5); // > 5
2s.number().greaterThanOrEqual(5); // >= 5
3s.number().lessThan(5); // < 5
4s.number().lessThanOrEqual(5); // <= 5
5s.number().equal(5); // === 5
6s.number().notEqual(5); // !== 5
7
8s.number().equal(NaN); // special case: Number.isNaN
9s.number().notEqual(NaN); // special case: !Number.isNaN
10
11s.number().int(); // value must be an integer
12s.number().safeInt(); // value must be a safe integer
13s.number().finite(); // value must be finite
14
15s.number().positive(); // .greaterThanOrEqual(0)
16s.number().negative(); // .lessThan(0)
17
18s.number().divisibleBy(5); // Divisible by 5

And transformations:

1s.number().abs(); // Transforms the number to an absolute number
2s.number().sign(); // Gets the number's sign
3
4s.number().trunc(); // Transforms the number to the result of `Math.trunc`
5s.number().floor(); // Transforms the number to the result of `Math.floor`
6s.number().fround(); // Transforms the number to the result of `Math.fround`
7s.number().round(); // Transforms the number to the result of `Math.round`
8s.number().ceil(); // Transforms the number to the result of `Math.ceil`

BigInts

Back to top

Shapeshift includes a handful of number-specific validations:

1s.bigint().greaterThan(5n); // > 5n
2s.bigint().greaterThanOrEqual(5n); // >= 5n
3s.bigint().lessThan(5n); // < 5n
4s.bigint().lessThanOrEqual(5n); // <= 5n
5s.bigint().equal(5n); // === 5n
6s.bigint().notEqual(5n); // !== 5n
7
8s.bigint().positive(); // .greaterThanOrEqual(0n)
9s.bigint().negative(); // .lessThan(0n)
10
11s.bigint().divisibleBy(5n); // Divisible by 5n

And transformations:

1s.bigint().abs(); // Transforms the bigint to an absolute bigint
2
3s.bigint().intN(5); // Clamps to a bigint to a signed bigint with 5 digits, see BigInt.asIntN
4s.bigint().uintN(5); // Clamps to a bigint to an unsigned bigint with 5 digits, see BigInt.asUintN

Booleans

Back to top

Shapeshift includes a few boolean-specific validations:

1s.boolean().true(); // value must be true
2s.boolean().false(); // value must be false
3
4s.boolean().equal(true); // s.boolean().true()
5s.boolean().equal(false); // s.boolean().false()
6
7s.boolean().notEqual(true); // s.boolean().false()
8s.boolean().notEqual(false); // s.boolean().true()

Arrays

Back to top

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

Shapeshift includes a handful of array-specific validations:

1s.string().array().lengthLessThan(5); // Must have less than 5 elements
2s.string().array().lengthLessThanOrEqual(5); // Must have 5 or less elements
3s.string().array().lengthGreaterThan(5); // Must have more than 5 elements
4s.string().array().lengthGreaterThanOrEqual(5); // Must have 5 or more elements
5s.string().array().lengthEqual(5); // Must have exactly 5 elements
6s.string().array().lengthNotEqual(5); // Must not have exactly 5 elements
7s.string().array().lengthRange(0, 4); // Must have at least 0 elements and less than 4 elements (in math, that is [0, 4))
8s.string().array().lengthRangeInclusive(0, 4); // Must have at least 0 elements and at most 4 elements (in math, that is [0, 4])
9s.string().array().lengthRangeExclusive(0, 4); // Must have more than 0 element and less than 4 elements (in math, that is (0, 4))
10s.string().array().unique(); // All elements must be unique. Deep equality is used to check for uniqueness.

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

Tuples

Back to top

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

1const dish = s.tuple([
2  s.string(), // Dish's name
3  s.number().int(), // Table's number
4  s.date() // Date the dish was ready for delivery
5]);
6
7dish.parse(['Iberian ham', 10, new Date()]);

Unions

Back to top

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

1const stringOrNumber = s.union([s.string(), s.number()]);
2
3stringOrNumber.parse('Sapphire'); // => 'Sapphire'
4stringOrNumber.parse(42); // => 42
5stringOrNumber.parse({}); // => throws CombinedError

Enums

Back to top

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

1s.enum(['Red', 'Green', 'Blue']);
2// s.union([s.literal('Red'), s.literal('Green'), s.literal('Blue')]);

Maps

Back to top

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

Sets

Back to top

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

Instances

Back to top

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:

1class User {
2  public constructor(public name: string) {}
3}
4
5const userInstanceValidation = s.instance(User);
6userInstanceValidation.parse(new User('Sapphire')); // => User { name: 'Sapphire' }
7userInstanceValidation.parse('oops'); // => throws ValidatorError

Records

Back to top

Record validations 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:

1const tags = s.record(s.string());
2
3tags.parse({ foo: 'bar', hello: 'world' }); // => { foo: 'bar', hello: 'world' }
4tags.parse({ foo: 42 }); // => throws CombinedError
5tags.parse('Hello'); // => throws ValidateError

---

TypedArray

Back to top

1const typedArray = s.typedArray();
2const int16Array = s.int16Array();
3const uint16Array = s.uint16Array();
4const uint8ClampedArray = s.uint8ClampedArray();
5const int16Array = s.int16Array();
6const uint16Array = s.uint16Array();
7const int32Array = s.int32Array();
8const uint32Array = s.uint32Array();
9const float32Array = s.float32Array();
10const float64Array = s.float64Array();
11const bigInt64Array = s.bigInt64Array();
12const bigUint64Array = s.bigUint64Array();

Shapeshift includes a handful of validations specific to typed arrays.

1s.typedArray().lengthLessThan(5); // Length must be less than 5
2s.typedArray().lengthLessThanOrEqual(5); // Length must be 5 or less
3s.typedArray().lengthGreaterThan(5); // Length must be more than 5
4s.typedArray().lengthGreaterThanOrEqual(5); // Length must be 5 or more
5s.typedArray().lengthEqual(5); // Length must be exactly 5
6s.typedArray().lengthNotEqual(5); // Length must not be 5
7s.typedArray().lengthRange(0, 4); // Length L must satisfy 0 <= L < 4
8s.typedArray().lengthRangeInclusive(0, 4); // Length L must satisfy 0 <= L <= 4
9s.typedArray().lengthRangeExclusive(0, 4); // Length L must satisfy 0 < L < 4

Note that all of these methods have analogous methods for working with the typed array's byte length, s.typedArray().byteLengthX() - for instance, s.typedArray().byteLengthLessThan(5) is the same as s.typedArray().lengthLessThan(5) but for the array's byte length.

---

Defining schemas (objects)

Back to top

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

Utility types for TypeScript

Back to top

For object validation Shapeshift exports 2 utility types that can be used to extract interfaces from schemas and define the structure of a schema as an interface beforehand respectively.

Extracting an interface from a schema

Back to top

You can use the InferType type to extract the interface from a schema, for example:

1import { InferType, s } from '@sapphire/shapeshift';
2
3const schema = s.object({
4  foo: s.string(),
5  bar: s.number(),
6  baz: s.boolean(),
7  qux: s.bigint(),
8  quux: s.date()
9});
10
11type Inferredtype = InferType<typeof schema>;
12
13// Expected type:
14type Inferredtype = {
15  foo: string;
16  bar: number;
17  baz: boolean;
18  qux: bigint;
19  quux: Date;
20};

Defining the structure of a schema through an interface

Back to top

You can use the SchemaOf type to define the structure of a schema before defining the actual schema, for example:

1import { s, SchemaOf } from '@sapphire/shapeshift';
2
3interface IIngredient {
4  ingredientId: string | undefined;
5  name: string | undefined;
6}
7
8interface IInstruction {
9  instructionId: string | undefined;
10  message: string | undefined;
11}
12
13interface IRecipe {
14  recipeId: string | undefined;
15  title: string;
16  description: string;
17  instructions: IInstruction[];
18  ingredients: IIngredient[];
19}
20
21type InstructionSchemaType = SchemaOf<IInstruction>;
22// Expected Type: ObjectValidator<IInstruction>
23
24type IngredientSchemaType = SchemaOf<IIngredient>;
25// Expected Type: ObjectValidator<IIngredient>
26
27type RecipeSchemaType = SchemaOf<IRecipe>;
28// Expected Type: ObjectValidator<IRecipe>
29
30const instructionSchema: InstructionSchemaType = s.object({
31  instructionId: s.string().optional(),
32  message: s.string()
33});
34
35const ingredientSchema: IngredientSchemaType = s.object({
36  ingredientId: s.string().optional(),
37  name: s.string()
38});
39
40const recipeSchema: RecipeSchemaType = s.object({
41  recipeId: s.string().optional(),
42  title: s.string(),
43  description: s.string(),
44  instructions: s.array(instructionSchema),
45  ingredients: s.array(ingredientSchema)
46});

.extend:

Back to top

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:

1const animal = s.object({
2  name: s.string().optional(),
3  age: s.number()
4});
5
6const pet = animal.extend({
7  owner: s.string().nullish()
8});
9
10const pet = animal.extend(
11  s.object({
12    owner: s.string().nullish()
13  })
14);

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

.pick / .omit:

Back to top

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

1const pkg = s.object({
2  name: s.string(),
3  description: s.string(),
4  dependencies: s.string().array()
5});
6
7const justTheName = pkg.pick(['name']);
8// s.object({ name: s.string() });
9
10const noDependencies = pkg.omit(['dependencies']);
11// s.object({ name: s.string(), description: s.string() });

.partial

Back to top

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

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

Which is the same as doing:

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

---

.required

Back to top

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

1const user = s.object({
2  username: s.string().optional(),
3  password: s.string().optional()
4}).required;

Which is the same as doing:

1const user = s.object({
2  username: s.string(),
3  password: s.string()
4});

---

Handling unrecognized keys

Back to top

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

1const person = s.object({
2  framework: s.string()
3});
4
5person.parse({
6  framework: 'Sapphire',
7  awesome: true
8});
9// => { name: 'Sapphire' }

.strict

Back to top

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

1const person = s.object({
2  framework: s.string()
3}).strict;
4
5person.parse({
6  framework: 'Sapphire',
7  awesome: true
8});
9// => throws ValidationError

.ignore

Back to top

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

.passthrough

Back to top

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

---

BaseValidator: methods and properties

Back to top

All validations in Shapeshift contain certain methods.

• .run(data: unknown): Result<T, Error>: given a validation, 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 validations, 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:

1import { s } from '@sapphire/shapeshift';
2
3const getLength = s.string().transform((value) => value.length);
4getLength.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:

1import { s, Result } from '@sapphire/shapeshift';
2
3const getLength = s.string().reshape((value) => Result.ok(value.length));
4getLength.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:

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

1const number = s.number().default(Math.random);
2number.parse(12); // => 12
3number.parse(undefined); // => 0.989911985608602
4number.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().

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

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

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

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

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

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

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

1s.string().or(s.number());
2// => s.union(s.string(), s.number())
3
4s.object({ name: s.string() }).or(s.string(), s.number());
5// => s.union(s.object({ name: s.string() }), s.string(), s.number())

• .when: Adjust the schema based on a sibling or sinbling children fields.

For using when you provide an object literal where the key is is undefined, a value, or a matcher function; then provides the schema when is resolves truthy, and otherwise provides the schema when is resolves falsey.

Available options for providing is

When is is not provided (=== undefined) it is strictly resolved as Boolean(value) wherein value is the current value of the referenced sibling. Note that if multiple siblings are referenced then all the values of the array need to resolve truthy for the is to resolve truthy.

When is is a primitive literal it is strictly compared (===) to the current value.

If you want to use a different form of equality you can provide a function like: is: (value) => value === true.

Resolving of the key (first) parameter

For resolving the key parameter to its respective value we use lodash/get. This means that every way that Lodash supports resolving a key to its respective value is also supported by Shapeshift. This includes:

• Simply providing a string or number like 'name' or 1.
• Providing a string or number with a dot notation like 'name.first' (representative of a nested object structure of { 'name': { 'first': 'Sapphire' } } => resolves to Sapphire).
• Providing a string or number with a bracket notation like 'name[0]' (representative of an array structure of { 'name': ['Sapphire', 'Framework'] } => resolves to Sapphire).
• Providing a string or number with a dot and bracket notation like 'name[1].first' (representative of a nested object structure of { 'name': [{ 'first': 'Sapphire' }, { 'first': 'Framework' }] } => resolves to Framework).

Examples

Let's start with a basic example:

1const whenPredicate = s.object({
2  booleanLike: s.boolean(),
3  numberLike: s.number().when('booleanLike', {
4    then: (schema) => schema.greaterThanOrEqual(5),
5    otherwise: (schema) => schema.lessThanOrEqual(5)
6  })
7});
8
9whenPredicate.parse({ booleanLike: true, numberLike: 6 });
10// => { booleanLike: true, numberLike: 6 }
11
12whenPredicate.parse({ booleanLike: true, numberLike: 4 });
13// => ExpectedConstraintError('s.number().greaterThanOrEqual', 'Invalid number value', 4, 'expected >= 5')
14
15whenPredicate.parse({ booleanLike: false, numberLike: 4 });
16// => { booleanLike: false, numberLike: 4 }

The provided key can also be an array of sibling children:

1const whenPredicate = s.object({
2  booleanLike: s.boolean(),
3  stringLike: s.string(),
4  numberLike: s.number().when(['booleanLike', 'stringLike'], {
5	is: ([booleanLikeValue, stringLikeValue]) => booleanLikeValue === true && stringLikeValue === 'foobar',
6    then: (schema) => schema.greaterThanOrEqual(5),
7    otherwise: (schema) => schema.lessThanOrEqual(5)
8  })
9});
10
11whenPredicate.parse({ booleanLike: true, stringLike: 'foobar', numberLike: 6 });
12// => { booleanLike: true, numberLike: 6 }
13
14whenPredicate.parse({ booleanLike: true, stringLike: 'barfoo', numberLike: 4 });
15// => ExpectedConstraintError('s.number().greaterThanOrEqual', 'Invalid number value', 4, 'expected >= 5')
16
17whenPredicate.parse({ booleanLike: false, stringLike: 'foobar' numberLike: 4 });
18// => ExpectedConstraintError('s.number().greaterThanOrEqual', 'Invalid number value', 4, 'expected >= 5')

Enabling and disabling validation

Back to top

At times, you might want to have a consistent code base with validation, but would like to keep validation to the strict necessities instead of the in-depth constraints available in shapeshift. By calling setGlobalValidationEnabled you can disable validation at a global level, and by calling setValidationEnabled you can disable validation on a per-validator level.

When setting the validation enabled status per-validator, you can also set it to null to use the global setting.

1import { setGlobalValidationEnabled } from '@sapphire/shapeshift';
2
3setGlobalValidationEnabled(false);

1import { s } from '@sapphire/shapeshift';
2
3const predicate = s.string().lengthGreaterThan(5).setValidationEnabled(false);

Buy us some doughnuts

Back to top

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

Back to top

Please make sure to read the Contributing Guide before making a pull request.

Thank you to all the people who already contributed to Sapphire!