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.