JavaScript Array Matrix

A lightweight and performant data structure for storing JavaScript objects in an n-way or n-order array matrix.

Array Matrix Demo

Table of contents

• Getting Started
  • Making a Matrix
    • Configuration Properties
      • data Property
      • orders Property
    • Example Matrix
• Querying Data
  • getEntry
  • getDimension
• Additional Methods
  • getAxes
  • getAxisPoints
  • debug
• Demo and Performance
• Dev Workflow

Getting Started

First, add the module to your project:

npm i -S javascript-array-matrix

Import ArrayMatrix into your project:

import ArrayMatrix from 'javascript-array-matrix';

OR

const ArrayMatrix = require('javascript-array-matrix');

Making a Matrix

To create a new array matrix, you instantiate a new ArrayMatrix object with a configuration object:

const myMatrix = new ArrayMatrix(configs);

Configuration Properties

data Property

type: {Array}

Required

This is an array of objects that will be parsed and organized into the array matrix. The objects do not have to match exactly, but each object must have the properties corresponding to the orders passed in as arguments.

orders Property

type: {Array}

Required

Each string in they array must correspond to a key or property on the objects passed in the data argument Array.

The more properties that are provided, the higher the order or rank of the matrix, and more dimensions in the array. You should provide the minimum number of orders required to map each object to a cell in the array.

Example: if you are selling a T-shirt, you would want two orders: size and color. When you know the size and color of the T-shirt, you would use those values to access the product in the Array Matrix, allowing you to get the sku, price, availability, etc.

If there are multiple T-shirts on a single page, you may want to use three orders: size, color, and manufacturer. Or maybe size, color, and style number. The important take-away is that you have the minimum number of orders/properties necessary so that each maps to at most 1 object per cell.

There will be situations where you may have 0 objects per cell, and that is okay. The Array Matrix will return null for those cells. (ex.: Blue T-shirts in Small, but not Red T-shirts in Small).

Example Matrix

const matrixData = [
  { color: 'Blue', size: 'Small', sku: '123' },
  { color: 'Blue', size: 'Medium', sku: '124' },
  { color: 'Red', size: 'Medium', sku: '125' },
  { color: 'Blue', size: 'Large', sku: '126' },
  { color: 'Red', size: 'Large', sku: '127' },
  { color: 'Green', size: 'Large', sku: '128' }
];

const matrixOrders = ['color', 'size'];

const matrix = new ArrayMatrix({
  data: matrixData,
  orders: matrixOrders
});

Querying Data

getEntry

Gets a single entry from the matrix at the provided points.

Parameters

points {Object}: an object with keys corresponding to the orders or axes of the matrix, and the value corresponding to the label or name of the point in the matrix.

Using our Example Matrix:

const chosenTShirt = matrix.getEntry({ size: 'Medium', color: 'Red' });
// chosenTshirt points to { color: 'Red', size: 'Medium', sku: '125' }

NOTE: When querying for an entry, the number of keys in the points argument object needs to equal the number of orders present in the matrix.

getDimension

Gets multiple entries from a dimension in the matrix from the provided points. The missing axis/points is the dimension that is returned.

Parameters

points {Object}: an object with keys corresponding to the orders or axes of the matrix, and the value corresponding to the label or name of the point in the matrix.

Unlike getEntry, getDimension takes a points argument Object with the number of keys one less than the number of orders present in the matrix.

Using our Example Matrix:

const allBlueShirts = matrix.getDimension({ color: 'Blue' });
// allBlueShirts is [
//    { color: 'Blue', size: 'Small', sku: '123' },
//    { color: 'Blue', size: 'Medium', sku: '124' },
//    { color: 'Blue', size: 'Large', sku: '126' }
// ];

const allSmallShirts = matrix.getDimension({ size: 'Medium' });
// allSmallShirts is [
//    { color: 'Blue', size: 'Medium', sku: '124' },
//    { color: 'Red', size: 'Medium', sku: '125' },
// ];

NOTE: Currently ArrayMatrix only supports returning 1 dimension at a time. Adding functionality to return more than one dimension is being reviewed and undergoing performance tests.

For examples on how this can scale to use 3, 4, ... n level orders, see our Demo.

Additional Methods

getAxes

NOTE: axes is the plural of axis, and is not the the tool used by lumberjacks or weapon used by Medieval Vikings.

Gets the axes and named points along those axes.

Using our Example Matrix:

const matrixAxes = matrix.getAxes();
// matrixAxes is {
//    color: ['Blue', 'Red', 'Green'],
//    size: ['Small', 'Medium', 'Large']
// };

getAxisPoints

Gets the points along an axis and returns the named points.

Parameters

axis {String}: The name of the axis whose named points you want.

Using our Example Matrix:

const axisPoints = matrix.getAxisPoints('color');
// axisPoints is ['Blue', 'Red', 'Green'];

debug

Returns all the data stored in the array matrix - matrix, props, axes.

Demo and Performance

For more advanced demonstration of different 2, 3, and 4 order array matrices, the App has examples. Running the project locally starts the demo application, where you can play with queries and see performance results as well.

Here is the Demo.

Dev Workflow

• npm run dev starts a local development server, opens the dev page with your default browser, and watches for changes via livereload
  
  
• npm run build compiles commonjs and ES modules and places them in the dist directory
  
  
• npm test runs test using Jest + Enzyme.