RTTC: Runtime Type-Checking for JavaScript

Common errors

• Error: Invalid value provided: Expecting a 'number' but got a 'string' (e.g. "999").

  cause `rttc.validateStrict()` was used with a value that is semantically a number but not strictly of the 'number' JavaScript type (e.g., a string like "999").
  fix If strict type matching is desired, ensure the input is exactly the expected type. If lenient coercion is acceptable, use `rttc.validate()` or `rttc.coerce()` instead, which can handle type conversion for such cases.

• Error: Invalid value provided: Expecting a 'number' but got an 'object' (e.g. { x: 32, y: 79 }).

  cause `rttc.validate()` was used with a value that is fundamentally incompatible with the expected type (e.g., an object when a number is expected).
  fix Ensure that the input data structure broadly matches the expected type schema. For cases where incompatible types might occur, consider preprocessing the data or using `rttc.coerce()` if a fallback to a base value is acceptable, as `coerce()` never throws.

• TypeError: Cannot read properties of undefined (reading 'someProperty')

  cause `rttc.coerce()` returned a base value (e.g., `0`, `''`, `[]`, `{}`) for a complex type due to a major type mismatch, and subsequent code attempted to access properties on this base value, possibly an empty object or array, leading to unexpected `undefined`.
  fix After calling `rttc.coerce()`, always check the structure and content of the returned value if there's a possibility of major type mismatches in the input. Implement defensive coding (e.g., optional chaining `?.`, nullish coalescing `??`) or use `rttc.validate()`/`rttc.validateStrict()` if explicit errors are preferred over implicit base value fallbacks.

• Error: Failed to parse and coerce human value to primitive type: Invalid format.

  cause In `rttc@10.0.0` or later, `rttc.parseHuman()` was called with a string that could not be coerced to the specified primitive type (e.g., 'not-a-number' for a 'number' schema).
  fix Handle the potential validation error from `rttc.parseHuman()` using a `try...catch` block. Validate the input string before passing it, or adjust the schema if more flexible parsing is required. Consider custom parsing logic if `rttc.parseHuman()`'s strictness is not suitable for your use case.

Warnings

• breaking In v10.0.0, `rttc.parseHuman()` now throws a validation error if coercion of a human-entered string to a primitive type schema fails. Previously, it would silently fall back to the base value for the type.
  Fix: Review calls to `rttc.parseHuman()` with primitive type schemas. Implement `try...catch` blocks or use `rttc.coerce()` directly if you prefer non-throwing behavior that returns base values on failure.
• gotcha `rttc.validateStrict()`, `rttc.validate()`, and `rttc.coerce()` have distinct behaviors regarding error handling and coercion. `validateStrict` throws on *any* type mismatch, `validate` throws on *major* mismatches but coerces minor ones, and `coerce` *never* throws, instead returning base values for major mismatches.
  Fix: Carefully choose the appropriate method based on desired strictness. Use `validateStrict()` for exact type adherence, `validate()` for lenient validation with minor coercion, and `coerce()` when guaranteed non-throwing behavior and fallback to base values are preferred.
• gotcha Older versions of RTTC (prior to v9.3.4) could exhibit edge cases or false positives with `rttc.isEqual()` or other functions when object key names contained `.` (dots). This was addressed in v9.3.4.
  Fix: Upgrade to `rttc@9.3.4` or newer to ensure correct behavior when working with object keys that include periods. If upgrading is not possible, avoid using dots in key names where RTTC functions are applied.

Install

• npm install rttc npm
• yarn add rttc yarn
• pnpm add rttc pnpm

Imports

• rttc
  wrong:

  import rttc from 'rttc';
  // OR
  import { rttc } from 'rttc';

  correct:

  const rttc = require('rttc');

  RTTC primarily uses CommonJS module exports. Direct ESM `import` statements may not work as expected without specific Node.js configuration (like `"type": "module"` in package.json or transpilation) or the use of an `esm` loader, as the package does not explicitly define `exports` for ESM.
• validateStrict
  wrong:

  import { validateStrict } from 'rttc';

  correct:

  const rttc = require('rttc');
  rttc.validateStrict('number', 999);

  Methods like `validateStrict` are properties of the main `rttc` module object, not named exports. Access them via the imported `rttc` object.
• coerce
  wrong:

  import { coerce } from 'rttc';

  correct:

  const rttc = require('rttc');
  rttc.coerce('number', '999');

  Similar to `validateStrict`, `coerce` is a method on the `rttc` object. The library exports a single module object containing all its utilities.

Quickstart

Demonstrates `rttc.coerce` applying a complex recursive schema to an array of objects, coercing values to their base types when possible and filling in missing required fields with base values, never throwing errors.

const rttc = require('rttc');

const schema = [
  { name: 'string', age: 'number', friends: ['string'] }
];

const data = [
  { name: 'Karl', age: 258 },
  { name: 'Samantha', age: '937' },
  { name: 'Lupé', age: 82, friends: ['Henry', 'Mario', undefined] },
  { name: 'Andres', age: '22' },
  { age: ['nonsense!'] }
];

const coercedData = rttc.coerce(schema, data);

console.log(coercedData);
/*
Output:
[
  { name: 'Karl', age: 258, friends: [] },
  { name: 'Samantha', age: 937, friends: [] },
  { name: 'Lupé', age: 82, friends: ['Henry', 'Mario'] },
  { name: 'Andres', age: 22, friends: [] },
  { name: '', age: 0, friends: [] }
]
*/