mire

    3.0.1 • Public • Published

    Table of contents

    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.

    Install

    npm i mire

    DownloadsWeekly Downloads

    25

    Version

    3.0.1

    License

    MIT

    Unpacked Size

    16.1 kB

    Total Files

    7

    Last publish

    Collaborators

    • iliocatallo