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

• 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

• 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

• 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 |