Superstruct
GitHubDocs
  • Introduction
  • Guides
    • Getting Started
    • Validating Data
    • Coercing Data
    • Refining Validation
    • Handling Errors
    • Using TypeScript
  • API Reference
    • Core
    • Types
    • Refinements
    • Coercions
    • Utilities
    • Errors
    • TypeScript
  • Resources
    • FAQ
    • Links
Powered by GitBook
On this page
  • assert
  • create
  • is
  • mask
  • validate
  1. API Reference

Core

PreviousUsing TypeScriptNextTypes

Last updated 2 years ago

assert

assert<T>(value: unknown, struct: Struct<T>, message?: string) => asserts value is T

assert(value, User, 'The user is invalid!')

Assert that value is valid according to a struct. If the value is invalid a will be thrown (the optional message parameter allows you to override error's message).

🤖 When using TypeScript assert acts as an , so you can ensure that after calling it the type of the value matches the shape of the struct.

create

create<T>(value: unknown, struct: Struct<T>, message?: string) => T

const user = create(value, User, 'Unable to create a user!')

Create a value using the coercion logic that is built-in to the struct, returning the newly coerced value. If the value is invalid a will be thrown (the optional message parameter allows you to override error's message).

🤖 If you want coercion logic like defaulted values, you must call this helper before running validation.

is

is<T>(value: unknown, struct: Struct<T>) => value is T

if (is(value, User)) {
  // ...
}

Test that value is valid, returning a boolean representing whether it is valid or not.

🤖 When using TypeScript is acts as a type guard, so you can use it in an if statement to ensure that inside the statement the value matches the shape of the struct.

mask

mask<T>(value: unknown, struct: Struct<T>, message?: string) => T

const user = mask(value, User, 'The value is incompatible with type User!')

Note that when mask is used with type — given that type signals to the core that an object might have arbitrary additional properties — unknown properties will be retained in the returned value.

🤖 Just like create, mask includes coercion logic and works recursively.

validate

validate<T>(value: unknown, struct: Struct<T>, options: Object) => [StructError, T]

const [err, user] = validate(value, User)

Mask a value, returning a new value containing only properties defined by a struct. Conceptually this is similar to create, except that extra properties are omitted from the newly created value instead of throwing a . If an error is thrown anyway, the optional message parameter allows you to override its message.

Validate value, returning a result tuple. If the value is invalid the first element will be a . Otherwise, the first element will be undefined and the second element will be a value that is guaranteed to match the struct.

You can pass { coerce: true } as the third argument to enable coercion of the input value. As well as pass { message: 'Your custom error message' } to override the message of the .

assertion function
StructError
StructError
StructError
StructError
StructError