Newlyweds Proposing Marriage
    Wondering what’s next for npm?Check out our public roadmap! »

    make-matrix
    TypeScript icon, indicating that this package has built-in type declarations

    1.3.1 • Public • Published

    make-matrix

    build npm version bundle size

    A simple, type-safe way to create multi-dimensional arrays

    Features

    • 🛸 Easily create multi-dimensional arrays, with as many dimensions as needed
    • 🎛 Define exact dimensions to create an array of specified size
    • 🔢 Initialise every point in the array to a custom initial value
    • 📜 Comes with TypeScript definitions and type-safe returns
    • 🔬 Tiny size (~ 500 bytes gzipped), with no external dependencies

    Installation

    Install the package from NPM, and import it into your JavaScript or TypeScript file:

    npm install make-matrix
    import makeMatrix from "make-matrix";

    Usage

    Create a matrix

    To simply create an array of n dimensions, just pass n as the function's first parameter.

    // create a 2D array
    const twoDimensionalArray = makeMatrix(2);
    
    // create a 3D array
    const threeDimensionalArray = makeMatrix(3);
    
    // create a 4D array
    const fourDimensionalArray = makeMatrix(4);

    Create a matrix with specified dimensions

    To create an array with exact dimensions, pass in an array of numbers.

    // create an array of size 5x7
    const fiveBySevenArray = makeMatrix([5, 7]);
    
    // create an array of size 3x3x2
    const threeByThreeByTwoArray = makeMatrix([3, 3, 2]);
    
    // create an array of size 2x6x9x5x6
    const fiveDimensionalArray = makeMatrix([2, 6, 9, 5, 6]);

    Initialise the matrix with set values

    By default each point in the matrix will be initialised to null (so that if reading a point returns undefined, you know that it exists outside the current bounds of the matrix). To fill each point with a custom initial value, pass that value as the function's second parameter, initialValues:

    // create a 3x5 array, with each point equal to 0
    const twoDimensionalNumberArray = makeMatrix([3, 5], 0);
    
    // create a 2x6x5 array, with each point equal to "value"
    const threeDimensionalStringArray = makeMatrix([2, 6, 5], "value");

    Pass a callback for dynamic initial values

    The initialValues parameter can also be a callback, which you can use to dynamically create items for each position in the matrix. The callback can accept an argument which will resolve to the current vector co-ordinates at each point in the matrix. This can allow you to populate your matrix in a "self-aware" way.

    // create a 10x10x10 array, with each point a different random number between 0 and 9
    const twoDRandomNumberArray = makeMatrix([10, 10, 10], () => Math.floor(Math.random() * 10));
    
    // create a 5x5 array, with each point self described by a string
    const twoDVectorStringArray = makeMatrix([5, 5], (vector) => vector.join());
    
    // create a 7x3,8 array, with each point transformed into a vector object
    const twoDVectorObjectArray = makeMatrix([7, 3, 8], (vector) => {
        return {
            x: vector[0],
            y: vector[1],
            z: vector[2],
            otherData: OTHER_DATA,
        }
    });

    With TypeScript

    This package comes with type definitions to provide type-safety when working with the returned arrays.

    Returned Matrices will be given a specific type dictated by T and the number of dimensions, where T is the type of the value passed to the functions initialValues parameter (or unknown, if not set).

    For example, a three-dimensional array of numbers will be of type number[][][]. Points within the matrix can then only be reassigned to numbers. TypeScript's compiler will present errors when any reassignments are of the wrong type, including if they are at an incorrect depth in the array. This type-safety also occurs when callbacks are used to dynamically populate your matrix.

    const threeDNumberArray = makeMatrix([2, 6, 5], 0); // return type of number[][][]
    
    threeDNumberArray[2][1][2] = 10; // OK
    
    threeDNumberArray[2][1][2] = false; // error: Type 'false' is not assignable to type 'number'
    
    threeDNumberArray[2][1] = 10; // error: Type '"value"' is not assignable to type 'number[]'
    
    threeDNumberArray[2][1][2][0] = 10; // error: Property '0' does not exist on type 'Number'

    This type-safety will work for any number of dimensions, however large numbers may slow down your typescript server, due to the nature of the recursive types working under the hood.

    Example

    To easily create a 3D grid using p5.js, make-matrix can be used like below. The source code for the grid at the top of this readme can be seen here, and an interactive demo of it here.

    const res = 10; // 10px grid resolution
    const matrix = makeMatrix([5, 5, 5]); // A 5x5x5 cube grid
    
    for (let x = 0; x < matrix.length; x += res) {
        for (let y = 0; y < matrix[x].length; y += res) {
            for (let z = 0; z < matrix[x][y].length; z += res) {
                line(x, y, z, x + res, y, z);
                line(x, y, z, x, y + res, z);
                line(x, y, z, x, y, z + res);
            }
        }
    }

    API

    // Simple
    makeMatrix(dimensions, initialValues);
    
    // With types
    makeMatrix<D, T>(
        dimensions: number | number[],
        initialValues?: T | ((vector: VectorOfLength<D>) => T)
    ): Matrix<T>;

    Parameters

    • dimensions — The desired dimensions of the matrix. A number or array of numbers.
    • initialValues — The value that each point in the matrix will initialise to. Can take any value. If a callback is passed, it will be run for each point in the matrix, which will be initialised to the callbacks returned value. (Optional — defaults to null).

    Returns

    • Matrix — A multidimensional array of your desired dimensions, with each point initialised to equal the initialValues parameter (or its returned value).

    Contributing

    This project welcomes contributions. To get started, please open an issue to do discuss the change you'd like to make. Then fork the repo, open it in your editor, and run npm install in your terminal. This will get everything set up for you to start making changes.

    Testing, linting and commit style

    This project uses ESLint, Prettier, commitlint and Jest — in combination with lint-staged and Husky — to enforce code quality, consistency and changelog style. These tools will check changed files, and cancel a commit with logging if any of the following are true:

    1. Eslint has found non-fixable issues in the code
    2. The Jest testing suites haven't all passed
    3. The commit message doesn't meet the conventional commit format (run git cz in terminal for help formatting your commit message)

    Open your git logs to debug commit errors.

    License

    This package is MIT Licensed.

    Install

    npm i make-matrix

    DownloadsWeekly Downloads

    108

    Version

    1.3.1

    License

    ISC

    Unpacked Size

    17.8 kB

    Total Files

    7

    Last publish

    Collaborators

    • avatar