mire

Table of contents

- Introduction
- Installation
- Reference
- Acknowledgments

Introduction

Mire is a JavaScript library for the creation of _generic functions_, that is, functions capable of handling different types of data. Mire functionalities are exposed via a Generic object, which mimics the look and feel of standard JavaScript global objects, such as Array. Once created, a generic function can be extended so as to handle arguments of disparate types.

``javascript
import Generic from 'mire';

const { isArray } = Array;

const sum = Generic.of(function sum(x, y) {
return x + y;
});

sum.when([isArray, isArray], function sumArrays(xs, ys) {
return xs.map((x, i) => x + ys[i]);
});

sum(5, 6); // => 11
sum([7, 2], [3, 4]); // => [10, 6]
`

Installation

Mire can be installed via npm with the following command:

`
npm install mire
`

Reference

#### Generic.create

Creates a generic function by specifying its name, length and fallback handler. All parameters are optional. In the absence of a specific indication, the new generic function defaults to a fallback handler that always throws a NoMatchingError.

`javascript
import Generic from 'mire';

// name: '', length: 0, default fallback
const sum = Generic.create();

// name: 'sum', length: 0, default fallback
const sum = Generic.create({name: 'sum'});

// name: 'sum', length: 2, default fallback
const sum = Generic.create({name: 'sum', length: 2});

// name: 'sum', length: 2, user-defined fallback
const sum = Generic.create({
name: 'sum',
length: 2,
fallback: (x, y) => x + y
});
`

#### Generic.of

Creates a generic function starting from a function. The new generic function has the same name and length as the input function. In other words, Generic.of promotes a function to a generic function in the same way that Array.of promotes a single value to an array.

`javascript
import Generic from 'mire';

// name: 'sum', length: 2, input function as the fallback
const sum = Generic.of(function sum(x, y) {
return x + y;
});
`

#### GenericFunction.when

A generic function can be extended at any time in order to handle a new combination of argument types. This is achieved by specifying a handler function, together with the related dispatching predicates. Note that an existing handler may get overwritten by new handlers with the same predicates.

`javascript
import Generic from 'mire';

const { isArray } = Array;

const sum = Generic.of(function sum(x, y) {
return x + y;
});

sum.when([isArray, isArray], function sumArrays(xs, ys) {
return xs.map((x, i) => x + ys[i]);
});
`

#### Generic.NoMatchingError

When no fallback handler is passed to Generic.create, Mire defaults to a fallback handler that always throws a NoMatchingError error. Errors of such a type expose a generic property that points to the generic function at hand, as well as an args property, containing the passed arguments.

`javascript
import Generic from 'mire';

const sum = Generic.create();
try {
sum(5, 6);
} catch (err) {
// err is an instance of Generic.NoMatchingError
// err.generic points to sum
// err.args is [5, 6]
}
``

Acknowledgments

The amazing Mire logo was created by @adrygariglio. Mire adapts to JavaScript the approach to generic functions presented in MIT 6.945.