tcomb-validation

3.4.1 · active · verified Sun Apr 19

tcomb-validation is a general-purpose JavaScript validation library built upon the tcomb type combinator library. It provides a concise yet expressive syntax for validating various data structures, including native types, refinements, objects, lists, tuples, enums, unions, dicts, and intersections, with arbitrary nesting levels. The library offers detailed information on failed validations, making it a lightweight alternative to JSON Schema for validating domain models. The current stable version is 3.4.1, with releases typically addressing bug fixes and minor features, often in conjunction with its `tcomb` dependency. A key differentiator is its direct reuse of `tcomb` type definitions for validation, streamlining development when `tcomb` is already used for runtime type checking or domain modeling. It ships with TypeScript definitions, ensuring good type safety for modern JavaScript and TypeScript projects.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'String')
```
cause The `tcomb` library, which defines types like `t.String`, was not imported or was imported incorrectly (e.g., trying to use `t` from `tcomb-validation`).

fix Ensure `tcomb` is installed (`npm install tcomb`) and correctly imported, typically as `t`: `import * as t from 'tcomb';` or `const t = require('tcomb');`.
```
TypeError: validate is not a function
```
cause The `validate` function was not imported correctly from `tcomb-validation`, or `tcomb-validation` itself wasn't properly installed.

fix Use a named import for `validate`: `import { validate } from 'tcomb-validation';` or for CommonJS: `const { validate } = require('tcomb-validation');`.
```
TS2345: Argument of type 'string' is not assignable to parameter of type 'Number'.
```
cause A value of an incorrect type was provided to `validate` against a `tcomb` type, and TypeScript's static analysis caught a potential runtime validation failure.

fix Adjust the data being validated to match the expected `tcomb` type, or refine the `tcomb` type definition to correctly represent the allowable data shapes.

Warnings

breaking The behavior of `maybe(MyType)(undefined)` changed in v3.0.0. Previously it returned `null`, but after the upgrade to `tcomb` v3.0.0, it no longer implicitly converts `undefined` to `null`.
Fix: If you relied on `undefined` being converted to `null` by `maybe`, explicitly convert `undefined` values to `null` before validation, or adapt your code to handle `undefined`.
breaking The `path` argument to the `validate` function was replaced by a more flexible `options` object in v2.2.0. Passing a plain array as the `path` is now deprecated.
Fix: Refactor calls to `validate` to use the `options` object. Instead of `validate(value, type, ['field'])`, use `validate(value, type, { path: ['field'] })`.
gotcha To define types for validation (e.g., `t.String`, `t.struct`, `t.refinement`), you *must* explicitly import and use the `tcomb` library alongside `tcomb-validation`. `tcomb-validation` does not re-export `tcomb`'s type combinators.
Fix: Ensure you have `tcomb` installed (`npm install tcomb`) and import it (e.g., `import * as t from 'tcomb';` or `const t = require('tcomb');`) to define your validation schemas.
gotcha Users of TypeScript with complex or recursive type definitions might encounter type definition errors with versions prior to v3.4.1.
Fix: Upgrade to `tcomb-validation@3.4.1` or newer to benefit from the TypeScript fix for recursive type definitions.

Install

npm install tcomb-validation npm
yarn add tcomb-validation yarn
pnpm add tcomb-validation pnpm

Imports

validate
wrong:
```
const validate = require('tcomb-validation');
```
correct:
```
import { validate } from 'tcomb-validation';
```
The `validate` function is a named export. Older CJS examples might show `const t = require('tcomb-validation'); const validate = t.validate;` but it's directly exported.
ValidationResult
wrong:
```
import ValidationResult from 'tcomb-validation/ValidationResult';
```
correct:
```
import { ValidationResult } from 'tcomb-validation';
```
The `ValidationResult` class (or type for TypeScript) is a named export, used for inspecting validation outcomes.
tcomb types
wrong:
```
const t = require('tcomb-validation');
```
correct:
```
import * as t from 'tcomb';
```
While `tcomb-validation` uses `tcomb` types, the `tcomb` library itself must be imported separately (typically as `t`) to define types like `t.String` or `t.refinement`.

Quickstart

This quickstart demonstrates how to define complex types using `tcomb`, then use `tcomb-validation`'s `validate` function to check both valid and invalid data, including strict validation and error introspection.

import * as t from 'tcomb';
import { validate } from 'tcomb-validation';

// Define a type using tcomb
const UserName = t.refinement(t.String, (s) => s.length > 3 && s.length < 20, 'UserName');

// Define a struct (object type)
const User = t.struct({
  id: t.Number,
  name: UserName,
  email: t.maybe(t.String) // optional email
}, 'User');

// Validate a valid object
const validUser = { id: 1, name: 'JohnDoe', email: 'john.doe@example.com' };
let result = validate(validUser, User);
console.log('Valid user result:', result.isValid()); // true

// Validate an invalid object
const invalidUser = { id: 'a', name: 'Jo', age: 30 }; // id wrong type, name too short, extra prop
result = validate(invalidUser, User, { strict: true }); // strict mode to disallow extra props
console.log('Invalid user result:', result.isValid()); // false
console.log('First error:', result.firstError()?.message);

// Inspect all errors
result.errors.forEach(error => {
  console.log(`Path: ${error.path.join('.')}, Value: ${error.value}, Message: ${error.message}`);
});
/* Expected output for invalidUser (may vary slightly based on tcomb-validation version):
   Path: id, Value: a, Message: Invalid value "a" supplied to Number
   Path: name, Value: Jo, Message: Invalid value "Jo" supplied to UserName
   Path: age, Value: 30, Message: Invalid key "age" supplied to User
*/

view raw JSON →