Never Pummel Muskoxen

    @sapphire/shapeshift
    TypeScript icon, indicating that this package has built-in type declarations

    3.4.0 • Public • Published

    Sapphire Logo

    @sapphire/shapeshift

    ShapeShift

    Blazing fast input validation and transformation

    GitHub codecov npm

    Table of Contents

    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
    • Faster than

    Usage

    Back to top

    For complete usages, please dive into our documentation

    Basic usage

    Back to top

    Creating a simple string validation

    import { s } from '@sapphire/shapeshift';
    
    const myStringValidation = s.string;
    
    // Parse
    myStringValidation.parse('sapphire'); // => returns 'sapphire'
    myStringValidation.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 validations

    Back to top

    Primitives

    Back to top

    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

    Back to top

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

    Strings

    Back to top

    ShapeShift includes a handful of string-specific validations:

    s.string.lengthLessThan(5);
    s.string.lengthLessThanOrEqual(5);
    s.string.lengthGreaterThan(5);
    s.string.lengthGreaterThanOrEqual(5);
    s.string.lengthEqual(5);
    s.string.lengthNotEqual(5);
    s.string.email;
    s.string.url();
    s.string.uuid();
    s.string.regex(regex);
    s.string.ip();
    s.string.ipv4;
    s.string.ipv6;

    Numbers

    Back to top

    ShapeShift includes a handful of number-specific validations:

    s.number.greaterThan(5); // > 5
    s.number.greaterThanOrEqual(5); // >= 5
    s.number.lessThan(5); // < 5
    s.number.lessThanOrEqual(5); // <= 5
    s.number.equal(5); // === 5
    s.number.notEqual(5); // !== 5
    
    s.number.equal(NaN); // special case: Number.isNaN
    s.number.notEqual(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; // .greaterThanOrEqual(0)
    s.number.negative; // .lessThan(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

    Back to top

    ShapeShift includes a handful of number-specific validations:

    s.bigint.greaterThan(5n); // > 5n
    s.bigint.greaterThanOrEqual(5n); // >= 5n
    s.bigint.lessThan(5n); // < 5n
    s.bigint.lessThanOrEqual(5n); // <= 5n
    s.bigint.equal(5n); // === 5n
    s.bigint.notEqual(5n); // !== 5n
    
    s.bigint.positive; // .greaterThanOrEqual(0n)
    s.bigint.negative; // .lessThan(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

    Back to top

    ShapeShift includes a few boolean-specific validations:

    s.boolean.true; // value must be true
    s.boolean.false; // value must be false
    
    s.boolean.equal(true); // s.boolean.true
    s.boolean.equal(false); // s.boolean.false
    
    s.boolean.notEqual(true); // s.boolean.false
    s.boolean.notEqual(false); // s.boolean.true

    Arrays

    Back to top

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

    ShapeShift includes a handful of array-specific validations:

    s.string.array.lengthLessThan(5); // Must have less than 5 elements
    s.string.array.lengthLessThanOrEqual(5); // Must have 5 or less elements
    s.string.array.lengthGreaterThan(5); // Must have more than 5 elements
    s.string.array.lengthGreaterThanOrEqual(5); // Must have 5 or more elements
    s.string.array.lengthEqual(5); // Must have exactly 5 elements
    s.string.array.lengthNotEqual(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.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:

    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()]);

    Unions

    Back to top

    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

    Back to top

    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

    Back to top

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

    Sets

    Back to top

    const set = s.set(s.number);
    // 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:

    class User {
    	public constructor(public name: string) {}
    }
    
    const userInstanceValidation = s.instance(User);
    userInstanceValidation.parse(new User('Sapphire')); // => User { name: 'Sapphire' }
    userInstanceValidation.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:

    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

    Function validation is not yet implemented and will be made available starting v2.1.0

    Functions // TODO

    Back to top

    You can define function validations. 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.


    TypedArray

    Back to top

    const typedArray = s.typedArray();
    const int16Array = s.int16Array;
    const uint16Array = s.uint16Array;
    const uint8ClampedArray = s.uint8ClampedArray;
    const int16Array = s.int16Array;
    const uint16Array = s.uint16Array;
    const int32Array = s.int32Array;
    const uint32Array = s.uint32Array;
    const float32Array = s.float32Array;
    const float64Array = s.float64Array;
    const bigInt64Array = s.bigInt64Array;
    const bigUint64Array = s.bigUint64Array;

    ShapeShift includes a handful of validations specific to typed arrays.

    s.typedArray().lengthLessThan(5); // Length must be less than 5
    s.typedArray().lengthLessThanOrEqual(5); // Length must be 5 or less
    s.typedArray().lengthGreaterThan(5); // Length must be more than 5
    s.typedArray().lengthGreaterThanOrEqual(5); // Length must be 5 or more
    s.typedArray().lengthEqual(5); // Length must be exactly 5
    s.typedArray().lengthNotEqual(5); // Length must not be 5
    s.typedArray().lengthRange(0, 4); // Length L must satisfy 0 <= L < 4
    s.typedArray().lengthRangeInclusive(0, 4); // Length L must satisfy 0 <= L <= 4
    s.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

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

    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:

    import { InferType, s } from '@sapphire/shapeshift';
    
    const schema = s.object({
    	foo: s.string,
    	bar: s.number,
    	baz: s.boolean,
    	qux: s.bigint,
    	quux: s.date
    });
    
    type Inferredtype = InferType<typeof schema>;
    
    // Expected type:
    type Inferredtype = {
    	foo: string;
    	bar: number;
    	baz: boolean;
    	qux: bigint;
    	quux: Date;
    };
    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:

    import { s, SchemaOf } from '@sapphire/shapeshift';
    
    interface IIngredient {
    	ingredientId: string | undefined;
    	name: string | undefined;
    }
    
    interface IInstruction {
    	instructionId: string | undefined;
    	message: string | undefined;
    }
    
    interface IRecipe {
    	recipeId: string | undefined;
    	title: string;
    	description: string;
    	instructions: IInstruction[];
    	ingredients: IIngredient[];
    }
    
    type InstructionSchemaType = SchemaOf<IInstruction>;
    // Expected Type: ObjectValidator<IInstruction>
    
    type IngredientSchemaType = SchemaOf<IIngredient>;
    // Expected Type: ObjectValidator<IIngredient>
    
    type RecipeSchemaType = SchemaOf<IRecipe>;
    // Expected Type: ObjectValidator<IRecipe>
    
    const instructionSchema: InstructionSchemaType = s.object({
    	instructionId: s.string.optional,
    	message: s.string
    });
    
    const ingredientSchema: IngredientSchemaType = s.object({
    	ingredientId: s.string.optional,
    	name: s.string
    });
    
    const recipeSchema: RecipeSchemaType = s.object({
    	recipeId: s.string.optional,
    	title: s.string,
    	description: s.string,
    	instructions: s.array(instructionSchema),
    	ingredients: s.array(ingredientSchema)
    });

    .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:

    const animal = s.object({
    	name: s.string.optional,
    	age: s.number
    });
    
    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:

    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:

    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

    Back to top

    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
    });

    .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:

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

    Which is the same as doing:

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

    Handling unrecognized keys

    Back to top

    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

    Back to top

    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

    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:

    import { s } from '@sapphire/shapeshift';
    
    const getLength = s.string.transform((value) => value.length);
    getLength.parse('Hello There'); // => 11

    Reshape is not yet implemented and will be made available starting v2.1.0

    ⚠️ .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

    ⚠️ .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

    ⚠️ 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)

    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.

    import { setGlobalValidationEnabled } from '@sapphire/shapeshift';
    
    setGlobalValidationEnabled(false);
    import { s } from '@sapphire/shapeshift';
    
    const 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

    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!

    Install

    npm i @sapphire/shapeshift

    DownloadsWeekly Downloads

    124,099

    Version

    3.4.0

    License

    MIT

    Unpacked Size

    800 kB

    Total Files

    11

    Last publish

    Collaborators

    • favna
    • kyranet
    • vladfrangu