@sapphire/shapeshift v3.9.7
@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.url; // TODO
s.string.uuid; // TODO
s.string.regex(regex); // TODO
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); // TODO | Divisible by 5
And transformations:
s.number.abs; // TODO | Transforms the number to an absolute number
s.number.sign; // TODO | Gets the number's sign
s.number.trunc; // TODO | Transforms the number to the result of Math.trunc`
s.number.floor; // TODO | Transforms the number to the result of Math.floor`
s.number.fround; // TODO | Transforms the number to the result of Math.fround`
s.number.round; // TODO | Transforms the number to the result of Math.round`
s.number.ceil; // TODO | 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); // TODO | Divisible by 5n
And transformations:
s.bigint.abs; // TODO | Transforms the bigint to an absolute bigint
s.bigint.intN(5); // TODO | Clamps to a bigint to a signed bigint with 5 digits, see BigInt.asIntN
s.bigint.uintN(5); // TODO | 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 string-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
Note:
.lengthGt
and.lengthGe
are overloaded and change the inferred type from 1 to 10. For example,s.string.array.lengthGe(2)
's inferred type is[string, string, ...string[]]
// TODO
Tuples // TODO
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).
Records // TODO
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 AggregateError
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 AggregateError
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 // TODO
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); // TODO
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, useResult.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'); // TODO
name.parse('Hello'); // => 'Hello'
name.parse(undefined); // => 'Sapphire'
const number = s.number.default(Math.random); // TODO
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):
This project follows the all-contributors specification. Contributions of any kind welcome!
3 days ago
10 days ago
10 days ago
17 days ago
24 days ago
24 days ago
1 month ago
1 month ago
1 month ago
1 month ago
1 month ago
1 month ago
1 month ago
1 month ago
1 month ago
1 month ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
8 months ago
7 months ago
6 months ago
8 months ago
9 months ago
6 months ago
9 months ago
7 months ago
10 months ago
5 months ago
6 months ago
7 months ago
7 months ago
6 months ago
5 months ago
6 months ago
7 months ago
5 months ago
7 months ago
7 months ago
7 months ago
10 months ago
5 months ago
10 months ago
7 months ago
10 months ago
9 months ago
6 months ago
6 months ago
9 months ago
9 months ago
7 months ago
5 months ago
6 months ago
7 months ago
7 months ago
8 months ago
7 months ago
8 months ago
6 months ago
6 months ago
10 months ago
8 months ago
5 months ago
8 months ago
10 months ago
8 months ago
6 months ago
5 months ago
11 months ago
11 months ago
1 year ago
11 months ago
1 year ago
12 months ago
11 months ago
11 months ago
11 months ago
11 months ago
12 months ago
11 months ago
12 months ago
11 months ago
11 months ago
12 months ago
12 months ago
11 months ago
11 months ago
11 months ago
12 months ago
11 months ago
1 year ago
12 months ago
11 months ago
11 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
1 year ago
2 years ago
2 years ago
1 year ago
2 years ago
2 years ago
2 years ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
1 year ago
1 year ago
2 years ago
1 year ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago