JavaScript Type Validation and Coercion

Common errors

• TypeError: Invalid [type] provided for [name] ([value])

  cause An input value failed validation when passed to an `*/ensure` utility without `isOptional` or `default` options.
  fix Provide a value that satisfies the type constraints of the `*/ensure` utility, or configure the `isOptional: true` option to allow `null`/`undefined`, or set a `default` value.

• ReferenceError: require is not defined

  cause Attempting to use `require()` statements (CommonJS) in an environment or file configured for ECMAScript Modules (ESM) without proper interoperability setup.
  fix Ensure your project is configured for CommonJS (e.g., by omitting `"type": "module"` in `package.json` or by using `.cjs` file extensions for CommonJS files), or use a build tool like Webpack or Rollup to bundle CommonJS modules for an ESM target.

Warnings

• gotcha The `type` package is designed for validating and coercing primitive or simple JavaScript types. For complex, deeply nested object structures or schema-based validation, it's explicitly recommended to use more powerful dedicated schema utilities like AJV or Hapi/Joi, as `type` does not offer this functionality.
  Fix: For complex object validation, integrate a schema validation library like AJV or Hapi/Joi instead of trying to compose complex validations with `type` utilities.
• gotcha The library explicitly states 'No transpilation implied', meaning users should not expect it to polyfill modern JavaScript features. It's written to work in ECMAScript 3+ engines, focusing purely on type validation.
  Fix: Ensure your target environment natively supports the JavaScript features you are using, or implement your own transpilation/polyfill solution if needed. Do not rely on this library for environment compatibility.
• gotcha By default, `*/ensure` utilities throw a `TypeError` if the input value does not meet the specified constraints. This requires explicit error handling (e.g., `try...catch`) or the use of `isOptional` and `default` options to prevent exceptions.
  Fix: Wrap calls to `*/ensure` in `try...catch` blocks to gracefully handle validation failures, or configure the `isOptional: true` option to accept `null`/`undefined` and `default` option to provide a fallback value.
• gotcha The `*/coerce` utilities offer 'restricted coercion' and return `null` if a value is not coercible according to their rules, rather than throwing an error. This differs from the error-throwing behavior of `*/ensure`.
  Fix: When using `*/coerce`, always check for `null` in the returned value to determine if coercion was successful. Do not assume a non-null return value without checking.

Install

• npm install type npm
• yarn add type yarn
• pnpm add type pnpm

Imports

• ensureString
  wrong:

  import { ensureString } from 'type/string/ensure';

  correct:

  const ensureString = require('type/string/ensure');

  This package primarily utilizes CommonJS `require()` for accessing its modular sub-path utilities, as demonstrated in its examples.
• isObject
  wrong:

  import { isObject } from 'type/object/is';

  correct:

  const isObject = require('type/object/is');

  CommonJS `require()` is the intended method for importing specific type checking utilities.
• ensureNaturalNumber
  wrong:

  import { ensureNaturalNumber } from 'type/natural-number/ensure';

  correct:

  const ensureNaturalNumber = require('type/natural-number/ensure');

  Each type utility is exposed via a dedicated CommonJS sub-path.

Quickstart

This example demonstrates how to normalize and validate function arguments using various `type` utilities, including string, date, natural number, and object checks, applying options like error messages, optionality, and default values for robust input handling.

const ensureString        = require('type/string/ensure');
const ensureDate          = require('type/date/ensure');
const ensureNaturalNumber = require('type/natural-number/ensure');
const isObject            = require('type/object/is');

function processData(path, options = { min: 0 }) {
  path = ensureString(path, { errorMessage: "%v is not a valid path string" });
  if (!isObject(options)) {
    console.warn("Options provided were not an object, defaulting to empty.");
    options = {};
  }
  const min = ensureNaturalNumber(options.min, { default: 0 });
  const max = ensureNaturalNumber(options.max, { isOptional: true, errorMessage: "Max value '%v' is not a natural number" });
  const startTime = ensureDate(options.startTime, { isOptional: true });

  console.log(`Processing path: ${path}`);
  console.log(`Min: ${min}, Max: ${max === null ? 'N/A' : max}`);
  console.log(`Start Time: ${startTime === null ? 'N/A' : startTime.toISOString()}`);
  // ...further logic based on validated inputs
}

// Example usage:
processData('/api/resource', { min: 5, max: 10, startTime: new Date() });
processData('/another/path', { min: 'abc' }); // Will throw TypeError for min
processData('/default/options');