Typed Function

4.2.2 · active · verified Sun Apr 19

typed-function (current stable version 4.2.2) is a JavaScript utility library designed to centralize and manage runtime type checking and automatic type conversion for function arguments. It allows developers to define multiple signatures for a single function, supporting union types, the `any` type, and variable arguments. This approach helps in separating type validation logic from core business logic, leading to cleaner code and more informative error messages when functions are called with incorrect input. The library aims to improve robustness and debuggability in JavaScript applications by providing consistent and helpful error messages, preventing silent failures due to invalid inputs. It is actively maintained and supports various environments, including Node.js (>=18) and modern browsers. Its key differentiators include flexible signature definition, detailed error reporting, and optional type conversion.

Common errors

```
TypeError: Unexpected type of argument X (expected Y, got Z) in function functionName
```
cause A function was called with an argument whose type does not match any of the defined signatures for that argument, and no automatic conversion was possible.

fix Ensure the arguments provided to the typed function strictly match one of its defined signatures. If type conversion is desired, ensure the necessary types and conversion rules are registered via `typed.addType`.
```
TypeError: No matching signature found for function functionName with arguments (type1, type2, ..., typeN)
```
cause The arguments provided to the typed function do not match the number or types of any of the defined function signatures.

fix Review the function's defined signatures and adjust the call to match an existing signature. Alternatively, add a new signature to the typed function that accommodates the intended argument types and count.

Warnings

gotcha Runtime type checking inherently adds a performance overhead. While `typed-function` is optimized, applying it to every function call, especially in hot code paths, can impact performance.
Fix: Apply `typed-function` selectively to public API functions or where robust input validation is critical, avoiding overuse in performance-sensitive internal logic. Profile your application to identify bottlenecks.
gotcha `typed-function` enforces strict input types, but over-applying this strictness can inadvertently reduce a function's flexibility, potentially violating Postel's law ('be liberal in what you accept and conservative in what you send').
Fix: Balance strict type checking with the robustness principle. Only apply stringent type validation where necessary for correctness, API stability, or preventing specific classes of bugs, allowing more flexibility in internal utility functions.
breaking Major version updates (e.g., v3 to v4) can introduce breaking changes to the type signature syntax, `addType` API, or default type conversion behaviors.
Fix: Always consult the official release notes and migration guides when upgrading to a new major version to understand specific breaking changes and necessary code adjustments. Test thoroughly after upgrading.

Install

npm install typed-function npm
yarn add typed-function yarn
pnpm add typed-function pnpm

Imports

typed
wrong:
```
import { typed } from 'typed-function'
```
correct:
```
import typed from 'typed-function'
```
The 'typed-function' library exports its main factory function as a default export.
typed
```
const typed = require('typed-function')
```
CommonJS import for Node.js environments. The 'typed' function is the default export.
addType
```
typed.addType({ name: 'MyType', test: (x) => x instanceof MyClass })
```
The 'addType' method is available on the imported 'typed' function itself, not as a separate named export, for extending the type system.

Quickstart

Demonstrates creating basic typed functions with single and multiple signatures, including union types, and handling type mismatch errors.

import typed from 'typed-function';

// Create a typed function with a single signature
const greet = typed({
  'string, string': function (firstName, lastName) {
    return `Hello, ${firstName} ${lastName}!`;
  }
});

console.log(greet('John', 'Doe'));
// Expected output: "Hello, John Doe!"

// Create a typed function with multiple signatures (overloading)
// and a union type for one argument
const calculate = typed({
  'number, number': function (a, b) {
    return a + b;
  },
  'string, string': function (a, b) {
    return a + b; // string concatenation
  },
  'number, number | string': function (a, b) {
    // This signature allows a number and a number or string for the second argument.
    // 'typed-function' will attempt type conversion if possible based on registered types.
    return `Result: ${a + b}`;
  }
});

console.log(calculate(5, 3));
// Expected output: 8
console.log(calculate('Hello', ' World'));
// Expected output: "Hello World"

try {
  console.log(calculate(10, '20')); // Matches 'number, number | string'
} catch (e) {
  console.error("Error calling calculate with number and string:", e.message);
}

// Example of a function designed to throw an error for unsupported types
const processDate = typed({
    'Date': function(date) {
        return `It's a date: ${date.toDateString()}`;
    }
});

try {
    console.log(processDate('not a date'));
} catch (e) {
    console.error("Error calling processDate:", e.message);
}
// Expected: Error calling processDate: TypeError: Unexpected type of argument 1 (expected Date, got string) in function processDate

view raw JSON →