Registry / serialization / tcomb-validation

tcomb-validation

library3.4.1jsnpmunverified

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.

serialization

npm install tcomb-validation

github ↗package ↗

INSTALL

IMPORT

SIG · TCOMB-VALIDATION

tcomb-validation

serializationjavascriptv3.4.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

validate

✓ import { validate } from 'tcomb-validation';

✗ const validate = require('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

✓ import { ValidationResult } from 'tcomb-validation';

✗ import ValidationResult from 'tcomb-validation/ValidationResult';

The `ValidationResult` class (or type for TypeScript) is a named export, used for inspecting validation outcomes.

tcomb types

✓ import * as t from 'tcomb';

✗ const t = require('tcomb-validation');

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

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 */

Debug

Known issues

breakingThe 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`.

affects: >=3.0.0

breakingThe `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'] })`.

affects: >=2.2.0

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

affects: >=1.0.0

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

affects: <3.4.1

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'String')

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

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

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.

Upgrade

Version history

3.4.1latest on npm

Audit

Dependencies

tcombrequiredRequired for defining the types that tcomb-validation uses for validation. This is a core peer dependency for functionality.

Agent activity

6 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/gcanti/tcomb-validation ↗

packagehttps://www.npmjs.com/package/tcomb-validation ↗