hybrid-array

An Array with Object benefits : enjoy data[id] as much as data[index] & data.find(item).

Getting started

Installation

From browser

<script type="module">
    import {
        createImmutableHybridArray,
        createLiteHybridArray,
        createHybridArray
    } from 'https://cdn.jsdelivr.net/npm/hybrid-array/mod.js';
</script>

From Deno

import {
    createImmutableHybridArray,
    createLiteHybridArray,
    createHybridArray
} from 'https://git.kaki87.net/KaKi87/hybrid-array/raw/branch/master/mod.js';

From Node

import {
    createImmutableHybridArray,
    createLiteHybridArray,
    createHybridArray
} from 'hybrid-array';

Usage

For static data

Create an "immutable" hybrid array :

const hybridArray = createImmutableHybridArray(
    data, // required array of objects containing the primary key
    primaryKey // 'id' by default
);

Access items :

console.log(hybridArray[index]);
console.log(hybridArray[id]); // statically pointing to the object containing the same ID

Safety (TL;DR : duplicate IDs, ID edits and items adding/removal should be avoided)

• When an ID is duplicated, all instances of it are accessible by index, and only the last one is accessible by ID ;
• When an ID is edited, the old ID will still point to the current item and the new ID will still point to nothing (or to its current item if it's a duplicate) ;
• When an item is replaced by index, its current ID pointer will still point to it even if the new ID is different ;
• When an item is replaced by ID, its current index pointer will still point to its current item.
• When an item is added by index, it will have no ID pointer ;
• When an item is added by ID, it will have no index pointer ;
• When an item is deleted by index, its ID reference will still exist ;
• When an item is deleted by ID, its index reference will still exist.

For dynamic but trusted and small data

Create a "lite" hybrid array :

const hybridArray = createLiteHybridArray(
    data, // optional array of objects containing the primary key
    primaryKey // 'id' by default
);

Add (more) items :

hybridArray.push(item);
hybridArray[index] = item;

Access items :

console.log(hybridArray[index]);
console.log(hybridArray[id]); // runs `hybridArray.find(item => item.id === id)` under the hood

Safety (TL;DR : duplicate IDs & ID edits should be avoided)

• When an ID is duplicated, either initially or by edit, all instances of it are accessible by index, and only the lowest-index one is accessible by ID ;
• When an item is added by ID, it will have no index pointer ;
• When an item is deleted by ID, its index pointer will remain.

For dynamic and untrusted or bug data

Create a "fully-featured" hybrid array :

const hybridArray = createHybridArray(
    data, // optional array of objects containing the primary key
    primaryKey // 'id' by default
);

Add (more) items :

hybridArray.push(item);
hybridArray[index] = item;
hybridArray[id] = item;

Access items :

console.log(hybridArray[index]);
console.log(hybridArray[id]); // uses a Map between ID & index under the hood

Delete items :

delete hybridArray[index]; // also removes the ID reference
delete hybridArray[id]; // also removes the index reference

Safety

• When an ID is duplicated, either initially or by edit, only the last instance of it is accessible by index or ID, the previous ones are overwritten.

Related projects

• junosuarez/indexed-array
• zeke/keyed-array

Detailed feature comparison

• index & id are existing ones
• nIndex & nId are new ones
• eIndex & eId are existing ones but different from index & id
• neIndex & neId are new or existing ones (but different from index & id)
• { id } can contain any additional key/value pairs
• {} contains any key/value pairs except id

	Object	Array	createImmutableHybridArray	createLiteHybridArray	createHybridArray	junosuarez/indexed-array	zeke/keyed-array
▼ Read operations
data[index]	No	Yes	Yes	Yes	Yes	Yes	Yes
data[id]	Yes	No	Yes	Yes	Yes	Yes	Yes
data.length	No	Yes	Yes	Yes	Yes	Yes	Yes
JSON.stringify(data)	Yes	Yes	Yes	Yes	Yes	Yes	Yes
data[index].id = nId	No	Yes	No	Yes	Yes	No	No
▼ Write operations
data[index].id = eId	No	No	No	No	Yes	No	No
data[id].id = nId	No	No	No	Yes	Yes	No	No
data[id].id = eId	No	No	No	No	Yes	No	No
data[neIndex] = { id: nId }	No	Yes	No	Yes	Yes	No	No
data[index] = { id }	No	No	No	No	Yes	No	No
data[neId] = {}	Yes	No	No	No	Yes	No	No
data.push({ id: nId })	No	Yes	No	Yes	Yes	No	No
data.push({ id })	No	No	No	No	Yes	No	No
delete data[index]	No	Yes	No	Yes	Yes	No	No
delete data[id]	Yes	No	No	No	Yes	No	No
▼ Transforming write ops.
data.splice()	No	Yes	No	Yes	Yes	No	No
data.sort()	No	Yes	Yes	Yes	Yes	Yes	Yes
▼ Misc
Input control	No	No	N/A	No	Yes	No	No
Unique primary key constraint	Yes	No	Yes	No	Yes	No	No
Custom primary key	N/A	N/A	Yes	Yes	Yes	Yes	No