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.

const Generic = require('mire'),
      isArray = Array.isArray;

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.

const Generic = require('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.

const Generic = require('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.

const Generic = require('mire'),
      isArray = Array.isArray;

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.

const Generic = require('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.