DotObjectArray, a.k.a. DOA a.k.a. ObjectArray

Why DOA ?

For three reasons :

• No support for associative arrays in vanilla JS
• Creating deep levels keys in a vanilla JS Object can programmatically be a pain if none of parent keys exists
• Bored of always using the same snippets everywhere and wants to have a less then 10KB NPM dependency ready to import

Features

DOA is an object with a set of methods to :

• Check, push, get and store data with ease regardless of its level
• Brings some array-like behaviours for convenience (you know forEach, eh ?)
• Easy to use data serializers and parsers
• Work as well on a whole dataset or a key-based sub-selection of the dataset

Installation

Module

The ObjectArray class is provided as a UMD module.

npm install dot-object-array

or

yarn add dot-object-array

Then simply require/import it :

import ObjectArray from 'dot-object-array';
const ObjectArray = require('dot-object-array').default;
// or
const ObjectArray = require('dot-object-array').ObjectArray;

ObjectArray have been built on a ECMA6 class with webpack a named default export.

Browser

DOA is available as CDN external link or can easily be installed locally.

Bundle

<script type="text/javascript" src="https://bundle.run/dot-object-array@latest"></script>

JsDelivr

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/dot-object-array@latest"></script>

Unpkg

<script type="text/javascript" src="https://unpkg.com/dot-object-array@latest"></script>

Local install

For browser install, you can simply fetch file dist/objectarray.min.js in this repo or clone it and load it :

<script type="text/javascript" src="myJsFolder/objectarray.min.js"></script>

An ObjectArray constructor will be added to global (window) scope.

Quick examples

// Import data at creation
var doa = new ObjectArray({
    item1: 3,
 item2: 12,
 item3: 5
});

//Add data
doa.push('item4', 4); // Single item or dataset
doa.import({
  item5: 5,
  item6: 6
});

//Add data with dotted notations
doa.push('dat.long.darn.key','isntIt?'); // Will automatically create each keys

//Iterate on keys at root level or in sub dataset
doa.forEach(function(value, key, index) {
 [...]
});
doa.forEach(function(value, key, index) {
 [...]
}, 'dat.path.to.data');

// Sub dataset import
doa.import({
 subitem1: 1,
 subitem2: 'astring',
 subitem3: {obj: really}
}, 'dat.long.and.far.away.key');

//sub dataset access
doa.dataset('dat.long.and.far.away.key');
// or
doa.pull('dat.long.and.far.away.key');

// And many more !

Playground

If you want to go further and try a bit, you can go to the playground.

Documentation

A full documentation (manual and API reference) set is available : https://liqueurdetoile.github.io/DotObjectArray

JSON support

You can easily use ObjectArrays to manipulate JSON data. Just rely on JSON native object to import your JSON structure, manipulate it with ObjectArray ease and get it back at the end 😉

var jstring = '{"dat": {"long": {"path": "foo", "dream": "baz"}}}';
var doa = new ObjectArray(JSON.parse(jstring));

// Let's say we want to move all dat.long stuff to a short thing
doa.push('short', doa.dataset('dat.long')).remove('dat');
      
console.log(JSON.stringify(doa.data)); // outputs {"short":{"path":"foo","dream":"baz"}}

Bugs and features requests

ObjectArray is test-driven though it did not prevent all issues. Please report here any trouble or features request.

Want to help ?

There is many more to do to implements othe features. Don't mind fork DOA, tweak it and submit a pull request 😉