array-of-arrays-into-ast

array-of-arrays-into-ast

turns an array of arrays of data into a nested tree of plain objects

Install

npm i array-of-arrays-into-ast

The default is exported, so instead of "generateAst" below, you can name the consumed function however you want.

Consume via a require():

const generateAst = require("array-of-arrays-into-ast");

or as an ES Module:

import generateAst from "array-of-arrays-into-ast";

or for web pages, as a production-ready minified script file (so-called "UMD build"), straight from CDN:

<script src="https://cdn.jsdelivr.net/npm/array-of-arrays-into-ast/dist/array-of-arrays-into-ast.umd.js"></script>

// in which case you get a global variable "arrayOfArraysIntoAst" which you consume like this:
const generateAst = arrayOfArraysIntoAst;

This package has three builds in dist/ folder:

Type	Key in package.json	Path	Size
Main export - CommonJS version, transpiled to ES5, contains require and module.exports	main	dist/array-of-arrays-into-ast.cjs.js	2 KB
ES module build that Webpack/Rollup understands. Untranspiled ES6 code with import/export.	module	dist/array-of-arrays-into-ast.esm.js	1 KB
UMD build for browsers, transpiled, minified, containing iife's and has all dependencies baked-in	browser	dist/array-of-arrays-into-ast.umd.js	41 KB

⬆ back to top

Table of Contents

• Install
• What it does
• API
• opts.dedupe
• Principles
• Compared vs. datastructures-js
• Contributing
• Licence

What it does

It consumes array of arrays and produces a trie-like AST from them:

Input:

[[1, 2, 3], [1, 2], [5]];

Output:

{
  1: [
    {
      2: [
        {
          3: [null]
        },
        null
      ]
    }
  ],
  5: [null]
}

This library is a piece of a breakthrough code generator I'm producing.

⬆ back to top

API

generateAst (input, [opts])

API - Input

Input argument	Type	Obligatory?	Description
input	Array of zero or more arrays	yes	Source of data to put into an AST
otps	Plain object	no	An Optional Options Object. See its API below.

⬆ back to top

An Optional Options Object

Type: object - an Optional Options Object.

options object's key	Type	Default	Description
{
dedupe	Boolean	true	Skip duplicates
}

Here are all defaults in one place for copying:

{
  dedupe: true,
}

When unused, Optional Options Object can also be passed as a null or undefined value.

⬆ back to top

API - Output

Type	Description
Plain object	AST of the input

opts.dedupe

If you generate the AST with default settings, dedupe setting will be active and duplicate paths won't be created:

import generateAst from "array-of-arrays-into-ast";
const res = generateAst([[1], [1], [1]]);
console.log(
  `${`\u001b[${33}m${`res`}\u001b[${39}m`} = ${JSON.stringify(res, null, 4)}`
);
// res = {
//   1: [null]
// }

Now, see what happens when you turn off opts.dedupe:

import generateAst from "array-of-arrays-into-ast";
const res = generateAst([[1], [1], [1]], { dedupe: false });
console.log(
  `${`\u001b[${33}m${`res`}\u001b[${39}m`} = ${JSON.stringify(res, null, 4)}`
);
// res = {
//   1: [null, null, null]
// }
}

Notice how entries for each branch were created.

Generally, I don't see the reason why you'd want duplicates, but the setting is there if you ever need it. 👍🏻

⬆ back to top

Principles

Every object's key will have a value of array.

• null inside that array means it's the tip of the branch.

• An object inside that array means the branch continues.

Simples.

Compared vs. datastructures-js

There are libraries that produce and manage trie data structures, for example, datastructures-js. In particular case, the problem is, the data structure is abstracted behind the let trie = ds.trie(); and you can't access it directly, traversing the nested tree of arrays and objects.

datastructures-js trie would limit to search(), traverse() and count() methods. However, we need to recursively traverse every node and look up and down, what's around it.

Here's where this library comes in. It doesn't abstract the data it's producing - you get a nested plain object which you can traverse and further process any way you like, using a vast ocean of object- processing libraries.

⬆ back to top

Contributing

• If you see an error, raise an issue.
• If you want a new feature but can't code it up yourself, also raise an issue. Let's discuss it.
• If you tried to use this package, but something didn't work out, also raise an issue. We'll try to help.
• If you want to contribute some code, fork the monorepo via GitLab, then write code, then file a pull request on GitLab. We'll merge it in and release.

In monorepo, npm libraries are located in packages/ folder. Inside, the source code is located either in src/ folder (normal npm library) or in the root, cli.js (if it's a command-line application).

The npm script "dev", the "dev": "rollup -c --dev --silent" builds the development version retaining all console.logs with row numbers. It's handy to have js-row-num-cli installed globally so you can automatically update the row numbers on all console.logs.

⬆ back to top

Licence

MIT License

Copyright (c) 2015-2019 Roy Revelt and other contributors