tcomb: Runtime Type Checking & DDD

Common errors

• [tcomb] Invalid value "s" supplied to Number

  cause Attempting to pass a value of an incorrect type (e.g., a string) to a tcomb type checker that expects a different type (e.g., Number).
  fix Ensure the value passed to the tcomb type check (e.g., `t.Number(value)`) matches the expected type. In TypeScript, this might indicate a mismatch between static and runtime types.

• [tcomb] Invalid value undefined supplied to Person/name: String

  cause A required field in a tcomb struct was omitted or explicitly supplied with `undefined` when a non-optional type (e.g., `t.String` instead of `t.maybe(t.String)`) was expected.
  fix Provide a valid value for all required fields in the struct's constructor. For fields that can be `null` or `undefined`, define them using `t.maybe(Type)`.

Warnings

• breaking tcomb is explicitly designed to be disabled in production environments. All type checks and `Object.freeze` calls are stripped out when `process.env.NODE_ENV` is set to `'production'`, rendering it ineffective for production validation and potentially leading to unexpected behavior if relied upon.
  Fix: For production-grade runtime type validation, consider using alternative libraries from the same author, such as `io-ts` or `tcomb-validation`. Do not deploy tcomb-dependent code to production expecting runtime checks to be active.
• gotcha While tcomb ships with TypeScript definitions, its runtime checks are distinct from compile-time TypeScript checks. Using `babel-plugin-tcomb` allows for a more integrated experience with type annotations, but without it, runtime checks must be explicitly called (e.g., `t.Number(a)`).
  Fix: Ensure you understand the distinction between compile-time TypeScript validation and tcomb's runtime validation. For automatic runtime checks based on type annotations, consider integrating `babel-plugin-tcomb` into your build process.
• gotcha Instances created with tcomb structs are immutable by default via `Object.freeze` in development. Direct modification attempts on these objects will fail silently in non-strict mode or throw errors in strict mode.
  Fix: Use the `t.update(instance, spec)` utility with immutability helpers (`$set`, `$merge`, `$push`, etc.) to create new instances with desired modifications, rather than attempting to mutate the original instance.

Install

• npm install tcomb npm
• yarn add tcomb yarn
• pnpm add tcomb pnpm

Imports

• t (default export)
  wrong:

  const t = require('tcomb');

  correct:

  import t from 'tcomb';

  The default export `t` is the primary entry point, providing access to all type combinators (e.g., `t.Number`, `t.struct`) and utilities like `t.update`. The CommonJS `require` syntax is typically considered outdated in modern JavaScript projects unless explicitly targeting older Node.js environments.
• Type definitions (TypeScript)

  import t from 'tcomb';
  // Or for type inference:
  type MyStructType = t.TypeOf<typeof MyStructDefinition>;

  While tcomb ships with TypeScript definitions, its types are typically accessed via the `t` object itself (e.g., `t.String`, `t.struct`). For defining types, you'd usually import `t` and use its properties or leverage `t.TypeOf<typeof ...>` for inference.
• Specific combinator (e.g., struct)
  wrong:

  import { struct } from 'tcomb';

  correct:

  import t from 'tcomb';
  const MyType = t.struct({ /* ... */ });

  Individual type combinators and utilities like `struct`, `list`, `maybe`, `update` are properties of the `t` object, not direct named exports. Attempting to destructure them directly will result in an `undefined` value or a runtime error.

Quickstart

This quickstart demonstrates how to define type-checked functions, create custom refined types, build structured objects (structs) with runtime validation, and perform immutable updates on instances using tcomb's utilities.

import t from 'tcomb';

// A type-checked function demonstrating basic validation
function sum(a, b) {
  t.Number(a); // Runtime check: 'a' must be a Number
  t.Number(b); // Runtime check: 'b' must be a Number
  return a + b;
}

try {
  sum(1, 's'); // This will throw an error
} catch (e) {
  console.error(`Caught error for sum(1, 's'): ${e.message}`);
}

// Define a custom refined type (Integer)
const Integer = t.refinement(t.Number, (n) => n % 1 === 0, 'Integer');

// Define a structured object (a 'struct') for a Person
const Person = t.struct({
  name: t.String,              // required string
  surname: t.maybe(t.String),  // optional string (can be null or undefined)
  age: Integer,                // required integer (using our custom Integer type)
  tags: t.list(t.String)       // a list of strings
}, 'Person');

// Add a method to the struct's prototype (as you would with a class)
Person.prototype.getFullName = function () {
  return `${this.name} ${this.surname ?? ''}`.trim();
};

let personInstance;
try {
  personInstance = Person({
    name: 'Guido',
    age: 42,
    tags: ['developer', 'js']
  });
  console.log(`Created person: ${personInstance.getFullName()}`);
} catch (e) {
  console.error(`Caught error creating person: ${e.message}`);
}

// Attempt to create a person with missing required fields
try {
  Person({
    surname: 'Canti'
  }); // This will throw an error for missing 'name' and 'age'
} catch (e) {
  console.error(`Caught error for invalid person creation: ${e.message}`);
}

// Update an immutable instance using t.update
const updatedPerson = Person.update(personInstance, {
  name: { $set: 'Giuliano' }, // Change name
  age: { $set: 43 },          // Change age
  tags: { $push: ['opensource'] } // Add a tag
});
console.log(`Updated person: ${updatedPerson.getFullName()}, Age: ${updatedPerson.age}, Tags: ${updatedPerson.tags.join(', ')}`);