{"id":12121,"library":"tcomb-validation","title":"tcomb-validation","description":"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.","status":"active","version":"3.4.1","language":"javascript","source_language":"en","source_url":"https://github.com/gcanti/tcomb-validation","tags":["javascript","tcomb","validation","models","domain","typescript"],"install":[{"cmd":"npm install tcomb-validation","lang":"bash","label":"npm"},{"cmd":"yarn add tcomb-validation","lang":"bash","label":"yarn"},{"cmd":"pnpm add tcomb-validation","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for defining the types that tcomb-validation uses for validation. This is a core peer dependency for functionality.","package":"tcomb","optional":false}],"imports":[{"note":"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.","wrong":"const validate = require('tcomb-validation');","symbol":"validate","correct":"import { validate } from 'tcomb-validation';"},{"note":"The `ValidationResult` class (or type for TypeScript) is a named export, used for inspecting validation outcomes.","wrong":"import ValidationResult from 'tcomb-validation/ValidationResult';","symbol":"ValidationResult","correct":"import { ValidationResult } from 'tcomb-validation';"},{"note":"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`.","wrong":"const t = require('tcomb-validation');","symbol":"tcomb types","correct":"import * as t from 'tcomb';"}],"quickstart":{"code":"import * as t from 'tcomb';\nimport { validate } from 'tcomb-validation';\n\n// Define a type using tcomb\nconst UserName = t.refinement(t.String, (s) => s.length > 3 && s.length < 20, 'UserName');\n\n// Define a struct (object type)\nconst User = t.struct({\n  id: t.Number,\n  name: UserName,\n  email: t.maybe(t.String) // optional email\n}, 'User');\n\n// Validate a valid object\nconst validUser = { id: 1, name: 'JohnDoe', email: 'john.doe@example.com' };\nlet result = validate(validUser, User);\nconsole.log('Valid user result:', result.isValid()); // true\n\n// Validate an invalid object\nconst invalidUser = { id: 'a', name: 'Jo', age: 30 }; // id wrong type, name too short, extra prop\nresult = validate(invalidUser, User, { strict: true }); // strict mode to disallow extra props\nconsole.log('Invalid user result:', result.isValid()); // false\nconsole.log('First error:', result.firstError()?.message);\n\n// Inspect all errors\nresult.errors.forEach(error => {\n  console.log(`Path: ${error.path.join('.')}, Value: ${error.value}, Message: ${error.message}`);\n});\n/* Expected output for invalidUser (may vary slightly based on tcomb-validation version):\n   Path: id, Value: a, Message: Invalid value \"a\" supplied to Number\n   Path: name, Value: Jo, Message: Invalid value \"Jo\" supplied to UserName\n   Path: age, Value: 30, Message: Invalid key \"age\" supplied to User\n*/","lang":"typescript","description":"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."},"warnings":[{"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`.","message":"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`.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Refactor calls to `validate` to use the `options` object. Instead of `validate(value, type, ['field'])`, use `validate(value, type, { path: ['field'] })`.","message":"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.","severity":"breaking","affected_versions":">=2.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to `tcomb-validation@3.4.1` or newer to benefit from the TypeScript fix for recursive type definitions.","message":"Users of TypeScript with complex or recursive type definitions might encounter type definition errors with versions prior to v3.4.1.","severity":"gotcha","affected_versions":"<3.4.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `tcomb` is installed (`npm install tcomb`) and correctly imported, typically as `t`: `import * as t from 'tcomb';` or `const t = require('tcomb');`.","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`).","error":"TypeError: Cannot read properties of undefined (reading 'String')"},{"fix":"Use a named import for `validate`: `import { validate } from 'tcomb-validation';` or for CommonJS: `const { validate } = require('tcomb-validation');`.","cause":"The `validate` function was not imported correctly from `tcomb-validation`, or `tcomb-validation` itself wasn't properly installed.","error":"TypeError: validate is not a function"},{"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.","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.","error":"TS2345: Argument of type 'string' is not assignable to parameter of type 'Number'."}],"ecosystem":"npm"}