Superstruct Data Validation

Common errors

• TypeError: require is not a function

  cause Attempting to use CommonJS `require()` syntax in an ESM module context, or when the `superstruct` package is treated as an ESM module.
  fix Migrate your import statements to ES Modules syntax: `import { object } from 'superstruct'`. If you are in a Node.js CJS module, you may need to ensure your `package.json` specifies `"type": "commonjs"` and potentially configure your build system for interop.

• TS2307: Cannot find module 'superstruct' or its corresponding type declarations.

  cause TypeScript compiler cannot locate the package or its types, often due to incorrect module resolution settings, or an outdated TypeScript version that doesn't fully support NodeNext module features.
  fix Verify `superstruct` is installed. Check your `tsconfig.json` for `moduleResolution` (e.g., `"node16"` or `"bundler"`) and `module` (e.g., `"esnext"` or `"nodenext"`). Ensure your TypeScript version is up-to-date (>=4.7 for NodeNext features).

• StructError: At path "age" expected a number but received "twenty-five"

  cause A runtime validation error indicating that a value for a specific path in the data does not match the expected type defined in the Superstruct schema.
  fix Inspect the `error.path` and `error.value` properties of the `StructError` to identify the problematic data point. Adjust the input data to conform to the schema's type expectations, or modify the schema if the data structure has genuinely changed.

Warnings

• breaking Superstruct v2.0.0 introduced a fix for incorrectly passing validation for arrays within `object()`, `type()`, and `record()` structs. If you were relying on the previous, incorrect behavior where invalid arrays might have been accepted, your validation logic will now correctly flag these as errors.
  Fix: Review any schemas using `object()`, `type()`, or `record()` that validate properties expecting arrays. Ensure your input data strictly adheres to the defined array types, as previously invalid arrays will now correctly cause validation failures.
• gotcha Superstruct has progressively moved towards stricter module resolution, especially with 'NodeNext' compatibility. Version 1.0.5-0 (pre-v2) explicitly added file extensions to imports/exports, indicating a shift towards explicit ESM module graphs. This can lead to issues with CommonJS setups or misconfigured TypeScript projects.
  Fix: For Node.js projects, ensure your `tsconfig.json` correctly configures `moduleResolution` (e.g., `bundler` or `node16`) and `module` (e.g., `esnext`, `nodenext`). If using CommonJS, be mindful of `require()` calls and potential interop issues, favoring ESM imports where possible.
• gotcha With NodeNext type resolution, users migrating or using Superstruct in CommonJS environments might encounter TypeScript errors related to type declaration files (`d.cts`). Versions 2.0.3-0 and 2.0.3-1 specifically address fixes for these scenarios.
  Fix: If experiencing type resolution issues in a CommonJS project with NodeNext, ensure you are on Superstruct `v2.0.3` or newer. You may also need to adjust your `tsconfig.json` to explicitly handle `d.cts` files or ensure your build setup correctly processes CJS type definitions.

Install

• npm install superstruct npm
• yarn add superstruct yarn
• pnpm add superstruct pnpm

Imports

• object
  wrong:

  const { object, string, number } = require('superstruct')

  correct:

  import { object, string, number } from 'superstruct'

  Superstruct v2 is primarily designed for ESM. While CJS usage is possible, explicit type declarations for CommonJS may require specific NodeNext configurations, or lead to module resolution issues.
• assert
  wrong:

  import assert from 'superstruct/assert'

  correct:

  import { assert, StructError } from 'superstruct'

  Most utilities like `assert` and `validate` are named exports from the main package. `StructError` is also a named export for error handling.
• Struct
  wrong:

  import { Struct } from 'superstruct'

  correct:

  import type { Struct } from 'superstruct'

  The `Struct` type is used for TypeScript type annotations and should be imported as a type, not a value. Other specific types like `Infer` are also named type imports.

Quickstart

This quickstart demonstrates defining a data schema for a `User` using `object`, `string`, `number`, and `array` structs, then uses `assert` to validate both valid and invalid data against the schema, catching and logging `StructError` for failures.

import { object, string, number, array, assert, StructError } from 'superstruct';

// Define a struct for a User
const User = object({
  id: string(),
  name: string(),
  email: string(),
  age: number(),
  roles: array(string()),
});

// Example valid data
const validUser = {
  id: 'user-123',
  name: 'John Doe',
  email: 'john.doe@example.com',
  age: 30,
  roles: ['admin', 'editor'],
};

// Example invalid data
const invalidUser = {
  id: 'user-456',
  name: 'Jane Smith',
  email: 'jane.smith@example.com',
  age: 'twenty-five', // Age should be a number
  roles: ['viewer', 123] // Roles should be array of strings
};

console.log('Validating validUser...');
try {
  assert(validUser, User);
  console.log('validUser is valid!');
} catch (error) {
  if (error instanceof StructError) {
    console.error('Validation failed for validUser:', error.message);
  } else {
    throw error;
  }
}

console.log('\nValidating invalidUser...');
try {
  assert(invalidUser, User);
  console.log('invalidUser is valid (this should not happen)!');
} catch (error) {
  if (error instanceof StructError) {
    console.error('Validation failed for invalidUser:', error.message);
    console.error('Failure path:', error.path);
  } else {
    throw error;
  }
}