freezelist

FREEZELIST

Proxy optimization of Array methods. For use with immutable methods. Contains memoized methods. Does not modify the input array.

DESCRIPTION

A lightweight Node.js package that memorizes past computations when providing the same functions as in previous calls. Or any javascript agent.

• memoized methods
• helpers
• static helpers
• benchmark

INSTALL

npm i freezelist

USE

import List from "freezelist";

const animals = List([new Dog, new Cat, new Duck]);
const animals.filter... 

FUTURE

• Creates immutable lists from existing arrays or other iterable objects.
• Supports common list manipulation methods such as concat, filter, find etc.
• All operations return new instances of the list, preserving immutability.
• Memorizes past computations when providing the same functions as in previous calls.
• Uses weak reference memoization.
• Employs B-tree-like optimization for memoization in cases of concat or slice operations on previous computations.
• Utilizes a proxy over Array, hence the behavior is similar to Array.

Example

const testArray = [1, 2, 3, 4, 5, 6, 7, 8, 9];
const testList = List(testArray);
const lt10 = (value) => value < 10;
const gt10 = (value) => value > 10;
testList.filter(lt10) === testList // true
testList.concat(testArray) === testList.concat(testArray) // true
testList.concat(testArray).slice(testArray.length) === testList // true

testList.filter(gt10) === List([]) // true

var ge5 = (value) => value >= 5;
testList.filter(ge5) === testList.filter((value) => value >= 5) // false
testList.filter(ge5) === testList.filter(ge5) // true
testList.toReversed().toReversed() === testList // true

testList.push // undefined
testList.shift // undefined
testList.pop // undefined
testList.unshift // undefined
testList.splice // undefined
testList.sort // undefined
testList.reverse // undefined

List([]) === List.empty // true

Warning:

• It is not recommended to use this package if function references constantly change. In such cases, caching does not work effectively. Therefore, weak reference memoization might not behave as expected.

• If function references are constantly changing, it is recommended to use the general method Object.freeze or create/apply another Proxy wrapper.

• All methods are implemented using Array prototypes. If any of the methods do not work, please pay attention to your ES version. Otherwise, install polyfills.

methods

this methods memoized

• findIndex
• findLastIndex
• find
• findLast
• filter
• map
• flatMap
• every
• some
• toReversed
• toSorted
• concat

static

• findIndex
• findLastIndex
• find
• findLast
• filter
• map
• flatMap
• every
• some
• toReversed
• toSorted
• concat
• slice

var isOdd = (value) => value % 2 === 1;
var filterOdd = List.filter(isOdd);
var stringAll = List.map(String);

var numbers  = [1, 2, 3, 4, 5, 6];
var odds     = filterOdd(numbers) // [1, 3, 5]
var strOdds  = stringAll(odds) // ["1", "3", "5"]
var strings  = stringAll(numbers) // ["1", "2", "3", "4", "5", "6"]

var is5Str = (value) => value === "5";
List.find(is5Str)(filterOdd(stringAll(numbers))) // "5"
List.some(is5Str)(filterOdd(stringAll(numbers))) // true

var isString = (value) => typeof value === "string";
var someString = List.some(isString);
someString(numbers) // false
someString(strings) // true

var concat123 = List.concat([1, 2, 3]);
var everyString = List.every(isString);
everyString(numbers) // false
everyString(strings) // true
var mix = concat123(strings); // [1, 2, 3, "1", "2", "3", "4", "5", "6"]
everyString(mix) // false

helpers

• The library contains several functions for memoization. You can apply them if necessary.

memoWeak

import memoWeak from "freezelist/memoWeak"

The memoWeak function is similar to memoizeWeak but additionally memoizes the input function itself. This means that if the same function is passed to memoWeak again, it will return the same memoized version of that function.

var find = (call) => (values) => values.find(call);
var findMemo = memoWeak(find);
var identity = value => value
findMemo(identity) === findMemo(identity); // true
memoWeak(find) === memoWeak(find); // true

memo

import memo from "freezelist/memo"

The memo function is similar to memoize but additionally memoizes the parameter of the function. This means that if the same parameter is passed to memo again, it will return the same memoized result for that parameter.

var add = (y) => (x) => x + y;
var addMemo = memo(add);
addMemo === memo(add) // true
addMemo(1)(2) // 3
addMemo(1) === addMemo(1) // true
addMemo(1) === addMemo(2) // false

memoizeWeak

import memoizeWeak from "freezelist/memoizeWeak";

The memoizeWeak function behaves similarly to memoize but utilizes weak references for caching, enabling efficient memory management.

var find = (call) => (values) => values.find(call);
var findMemo = memoizeWeak(find);
var identity = value => value
findMemo(identity) === findMemo(identity); // true
memoizeWeak(find) === memoizeWeak(find); // false

memoize

import memoize from "freezelist/memoize";

This function is a higher-order function that performs memoization, a technique used to cache the results of expensive function calls.

var inc = (next) => console.log("incrementing") || next++;
var memoInc = memoize(inc);
memoInc(2); // 3 | console -> incrementing
memoInc(2); // 3
memoInc(2); // 3
memoInc(3); // 4 | console -> incrementing
memoInc(3); // 4
memoInc(2); // 3
memoInc(1); // 2 | console -> incrementing

var add = (next) => (value) => next + value;
var addMemo = memoize((value) => add(value));
addMemo(1) === addMemo(1); // true

import once from "freezelist/once"

The once function memoizes the computation once and consistently returns the same computed value thereafter.

var add = (y) => (x) => x + y;
var addOnce = once(add);
addOnce(1)(2) // 3
addOnce(2)(2) // 3
addOnce(3)(2) // 3
addOnce(2)(3) // 4
addOnce(3)(3) // 4
addOnce(4)(4) // 5

import pure from "freezelist/pure"

The pure function utilizes the body of the function as a key. If the function has already been created, it returns the same function. Caution: Do not use with side effects.

pure((value) => value + 1) === pure((value) => value + 1) // true
pure((x) => x + 1) === pure((y) => y + 1) // false

import always from "freezelist/always"

always: Exports functions that always return a specified value, regardless of the input argument.

var T = always(true);

T() // true
T(false) // true
T(true) // true

var F = always(false);

F() // false
F(false) // false
F(true) // false

import T from "freezelist/T"

T: Exports a function that always returns true.

T() // true
T(false) // true
T(true) // true

import F from "freezelist/F"

F: Exports a function that always returns false.

F() // false
F(false) // false
F(true) // false

benchmark

Benefits of Usage Illustrated with an Example.

Array benchmark (small is better)

method	slow	avg	best	total
(is:0) find	0.013146013021469116	0.00012582829977599442	0.00011199712753295898	0.22619247436523438
(is:0) findLast	0.24636802077293396	0.08995326521293436	0.08812400698661804	95.64512541890144
(is:0) findIndex	0.021925002336502075	0.00013207708415106492	0.00012299418449401855	0.25381630659103394
(is:0) findLastIndex	0.5638859868049622	0.0867885997980331	0.08553600311279297	92.93515482544899
(is:0) filter	0.26325398683547974	0.09665332985718686	0.09577301144599915	101.15064090490341
(is:0) some	0.0032570064067840576	0.00013028696075732926	0.00011998414993286133	0.23662486672401428
(is:0) every	0.007956981658935547	0.0001333375170341599	0.00012299418449401855	0.2323017120361328
(is:4999) find	0.11581200361251831	0.05337818045839135	0.04415199160575867	46.895296186208725
(is:4999) findLast	0.1359269917011261	0.0513399853387715	0.04415100812911987	45.01649284362793
(is:4999) findIndex	0.08764299750328064	0.0432878256681294	0.04287302494049072	44.467748790979385
(is:4999) findLastIndex	0.110850989818573	0.04340059599683292	0.04287999868392944	44.57445400953293
(is:4999) filter	0.19745299220085144	0.09615995021133064	0.09583300352096558	97.42268002033234
(is:4999) some	0.1129859983921051	0.04787135333289496	0.044150978326797485	44.75313124060631
(is:4999) every	0.0016939938068389893	0.00020958214181857044	0.00011998414993286133	0.14904281497001648
(is:9999) find	0.23492899537086487	0.09241079233624763	0.08808398246765137	94.7162943482399
(is:9999) findLast	0.0028229951858520508	0.00018165541505818159	0.0001310110092163086	0.17870557308197021
(is:9999) findIndex	0.30890199542045593	0.08620258700498284	0.08553999662399292	89.49158081412315
(is:9999) findLastIndex	0.0031360089778900146	0.00020201551575513242	0.0001240074634552002	0.1701372265815735
(is:9999) filter	0.28716301918029785	0.11365661623394648	0.09580400586128235	98.28035670518875
(is:9999) some	0.22939500212669373	0.10155332909779496	0.088142991065979	90.43184334039688
(is:9999) every	0.016414999961853027	0.00019541470700641732	0.00011998414993286133	0.1861596703529358

List benchmark (small is better)

method	slow	avg	best	total
(is:0) find	0.04578500986099243	0.00019926726200930744	0.00018298625946044922	0.3711164891719818
(is:0) findLast	0.43387100100517273	0.00021054504097242627	0.00019299983978271484	0.7773020267486572
(is:0) findIndex	0.018757998943328857	0.00017074912567650066	0.00016698241233825684	0.2268763780593872
(is:0) findLastIndex	0.0026049911975860596	0.00017361497197792452	0.00016200542449951172	0.24420121312141418
(is:0) filter	0.060264021158218384	0.00017865018608556046	0.00016000866889953613	0.3104492723941803
(is:0) some	0.012078016996383667	0.0002047760573348015	0.0001850128173828125	0.2800108790397644
(is:0) every	0.010136991739273071	0.00022196482849220475	0.0002110004425048828	0.3413539528846741
(is:4999) find	0.05303400754928589	0.00017745729679980918	0.00016799569129943848	0.3179231286048889
(is:4999) findLast	0.1433829963207245	0.00018209477287165784	0.0001710057258605957	0.43011197447776794
(is:4999) findIndex	0.013437986373901367	0.00015700827902576054	0.00015100836753845215	0.23018282651901245
(is:4999) findLastIndex	0.000514984130859375	0.00015939170131266822	0.00014898180961608887	0.21402081847190857
(is:4999) filter	0.024091005325317383	0.0001544858368499715	0.00014200806617736816	0.2368161976337433
(is:4999) some	0.0008890032768249512	0.00017338552538655473	0.00016000866889953613	0.23946571350097656
(is:4999) every	0.0010719895362854004	0.00020495555107628114	0.00014698505401611328	0.27923691272735596
(is:9999) find	0.08872401714324951	0.07360692378056707	0.07318398356437683	76.7261433005333
(is:9999) findLast	0.1714160144329071	0.000550392242496034	0.00016999244689941406	0.5755237936973572
(is:9999) findIndex	0.000496983528137207	0.07593817097672888	0.07504600286483765	78.89414730668068
(is:9999) findLastIndex	0.07692000269889832	0.0005592977923345066	0.00032898783683776855	0.6342817842960358
(is:9999) filter	0.34512999653816223	0.07723275818212744	0.07616299390792847	80.88212183117867
(is:9999) some	0.2513199746608734	0.0727806533745375	0.07082900404930115	75.91782841086388
(is:9999) every	0.7847490012645721	0.0004673107686380167	0.0742499828338623	81.65851283073425

name	time ms (array time - list time)
average diff	0.04288869194819794
total diff	980.8674493432045
slow diff	0.0011970102787017822
best diff	0.0956220030784607

However, there is also a downside to using different references. List benchmark (small is better)

method	slow	avg	best	total
(is:0) find	0.017932981252670288	0.0008189397542704353	0.00018700957298278809	0.4456775486469269
(is:0) findLast	0.47867098450660706	0.11180581547549087	0.0858440101146698	95.03021365404129
(is:0) findIndex	0.29715999960899353	0.0011408011963341203	0.00018399953842163086	0.7334803640842438
(is:0) findLastIndex	0.7401839792728424	0.11328831263801993	0.08577001094818115	95.64228889346123
(is:0) filter	1.9352980256080627	0.13475315152105077	0.10406500101089478	116.73099943995476
(is:0) some	0.04808899760246277	0.000967048437389102	0.00020700693130493164	0.5676142573356628
(is:0) every	1.0563759803771973	0.13623522024433876	0.10397198796272278	116.48176655173302
(is:4999) find	0.10088899731636047	0.03734477910933264	0.0368179976940155	37.91008344292641
(is:4999) findLast	0.15418300032615662	0.04472632322244856	0.04322999715805054	44.903518319129944
(is:4999) findIndex	0.08876699209213257	0.040836217241857264	0.0377810001373291	38.929931938648224
(is:4999) findLastIndex	0.0985029935836792	0.044396556927625105	0.043252021074295044	44.22883030772209
(is:4999) filter	0.7337439954280853	0.09294671959135986	0.09008598327636719	93.83211103081703
(is:4999) some	0.0854330062866211	0.03649339660024642	0.03571498394012451	38.39343759417534
(is:4999) every	1.7619860172271729	0.09362696891645275	0.0897970199584961	94.82973054051399
(is:9999) find	0.2361150085926056	0.07360692378056707	0.07318398356437683	76.7261433005333
(is:9999) findLast	0.02373400330543518	0.000550392242496034	0.000299990177154541	0.5755237936973572
(is:9999) findIndex	0.23989200592041016	0.07593817097672888	0.07504600286483765	78.89414730668068
(is:9999) findLastIndex	0.07692000269889832	0.0005592977923345066	0.00032898783683776855	0.6342817842960358
(is:9999) filter	0.34512999653816223	0.07723275818212744	0.07616299390792847	80.88212183117867
(is:9999) some	0.2513199746608734	0.0727806533745375	0.07082900404930115	75.91782841086388
(is:9999) every	0.7847490012645721	0.09259174982566319	0.0742499828338623	81.65851283073425

name	time ms (array time - list time)
average diff	-0.034354674276938134
total diff	-226.53446304798126
slow diff	-0.0162389874458313
best diff	-0.0082319974899292

For your own testing, you can review the benchmark.js file located in the library folder.