Superstruct for TypeScript: Complete Guide with Examples

Introduction to Superstruct

\n\n

Superstruct is a lightweight yet powerful library for validating and parsing data structures in TypeScript and JavaScript. It allows you to describe the expected shape of data (objects, arrays, strings, numbers, etc.) using simple and expressive "schemas" (structs), and then check whether real data conforms to these schemas.

\n\n

Unlike other validation libraries such as Zod or Yup, Superstruct focuses on simplicity, performance, and minimalism. It does not automatically generate complex TypeScript types (although it works well with them), but instead offers a flexible and intuitive API for describing structures.

\n\n

Why do you need Superstruct?

\n

\n
• Validation of data from external sources: API responses, form data, configuration files, localStorage — anywhere data might arrive in an unexpected format.
\n
• Creating safe DTOs (Data Transfer Objects): Ensures that data passed between application layers matches the expected structure.
\n
• Parsing and transformation: Superstruct can not only validate but also transform data (e.g., convert strings to numbers).
\n
• Readable documentation: Superstruct schemas themselves serve as excellent documentation of what the data looks like.
\n

\n\n

Installation

\n\n

Superstruct is an npm package, so installation is done via the Node.js package manager:

\n\n

npm install superstruct

\n\n

Or, if you are using Yarn:

\n\n

yarn add superstruct

\n\n

After installation, you can import the library into your TypeScript file:

\n\n

import { struct, string, number, object, array, optional, union, literal, enums, size, refine, assert, is, validate } from 'superstruct';

\n\n

Quick Start

\n\n

Let's create a simple schema for a user and validate some data.

\n\n

import { object, string, number, assert } from 'superstruct';\n\n// 1. Define the schema (struct)\nconst User = object({\n    id: number(),\n    name: string(),\n    email: string(),\n});\n\n// 2. Data we want to validate\nconst userData = {\n    id: 1,\n    name: 'Alice',\n    email: 'alice@example.com',\n};\n\n// 3. Validation\ntry {\n    assert(userData, User);\n    console.log('Data is valid!');\n} catch (e) {\n    console.error('Validation error:', e.message);\n}\n\n// 4. If the data is invalid, assert throws an exception\nconst badData = { id: 'not a number', name: 'Bob' };\ntry {\n    assert(badData, User);\n} catch (e) {\n    console.error('Error:', e.message);\n    // Output: Expected a number for `id`, but received: "not a number"\n}

\n\n

Main Methods and Functions

\n\n

Superstruct provides a set of factories for creating schemas. Here are 10 main ones:

\n\n

1. string()

\n

Description: Creates a schema that checks if the value is a string.

\n

Parameters: None.

\n

import { string, assert } from 'superstruct';\n\nconst NameSchema = string();\nassert('Hello', NameSchema); // OK\n// assert(123, NameSchema); // Error: Expected a string, but received: 123

\n\n

2. number()

\n

Description: Checks if the value is a number (including NaN, unless otherwise specified).

\n

Parameters: None.

\n

import { number, assert } from 'superstruct';\n\nconst AgeSchema = number();\nassert(30, AgeSchema); // OK\n// assert('30', AgeSchema); // Error

\n\n

3. boolean()

\n

Description: Checks if the value is a boolean (true or false).

\n

Parameters: None.

\n

import { boolean, assert } from 'superstruct';\n\nconst IsActiveSch