Lazy list transformation.
A live array behaves similarly to a normal array, exposing a length
property, number-indexed values and various methods such as map
, includes
and reduce
. The difference is that those indexed values are opaquely virtualised through user-provided get
, set
and getLength
functions.
This is useful, for example, when an array-like interface is needed but the potential size of calculated values makes it unfeasible to store them all in a standard mapped array, or if the mapping process is wastefully expensive while only some elements will ever be accessed.
$ npm i @xtia/live-array
import { liveArray } from "@xtia/live-array";
const ids = ["main", "my-form", "my-submit-button"];
const elements = liveArray(ids, id => document.getElementById(id));
// or
const elements2 = liveArray({
getLength: () => ids.length,
get: idx => document.getElementById(ids[idx]),
});
console.log(elements[1]); // <form ...>
// changes to the source will be reflected in the live array:
ids[1] = "my-cancel-button";
console.log(elements[1]); // <button ...>
The following methods mimic those of a normal array:
map
forEach
filter
at
find
findIndex
some
every
join
reduce
includes
indexOf
lastIndexOf
slice
The following methods are unique to a LiveArray:
Creates a new LiveArray that performs further transformation on read and write.
If set
is provided, changes carry both ways:
const base = [2, 3, 4];
const doubles = liveArray(base).mapLive(n => n * 2, n => n / 2);
// ^ get ^ set
console.log(doubles[0]); // 4
doubles[0] = 100;
console.log(base[0]); // 50
Creates a new LiveArray from a range within the parent
const base = [1, 2, 3, 4, 5, 6];
const doubles = liveArray(base, n => n * 2);
const slice = base.sliceLive(2, 4);
console.log(slice.length); // 2
base[2] = 100;
console.log(slice[0]); // 200
Creates a new LiveArray that reads the parent in reverse order.
const words = ["world"];
const live = liveArray(words);
const backwards = live.reverseLive();
words.push("hello");
console.log(backwards.join(" ")); // "hello world"
Creates a new LiveArray that reads the parent with automatic value caching.
If invalidator
is provided, it will be called for every value read where the value is already cached, and passed an object of
{
ageMs: number; // ms since the value was cached
value: T; // the cached value
index: number;
cacheCount: number; // the number of items currently cached
}
If invalidator
returns true
, the cache entry is considered invalid. The value will then be recalculated, as normal, by the parent's provided get
.
function expensiveHash(s: string) {
for (let i = 0; i < 100000000; i++) s = getHash(s);
return s;
}
const keys = ["banana", "sausage", "lemon", "treacle", "shoes", "elephant"];
const hashes = liveArray(keys, expensiveHash).withCache();
Advanced example with smart invalidation:
const hashes = liveArray({
getLength: () => keys.length,
get: idx => ({
key: keys[idx],
hash: expensiveHash(keys[idx]),
}),
})
// invalidate cache entries where the key has changed
.withCache(entry => entry.value.key !== keys[entry.index])
// but return only the hash
.mapLive(v => v.hash);