@luvies/lazy

<!doctype html> <html class="default no-js"> <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <title>@luvies/lazy</title> <meta name="description" content="Documentation for @luvies/lazy"> <meta name="viewport" content="width=device-width, initial-scale=1"> <link rel="stylesheet" href="assets/css/main.css"> <script async src="assets/js/search.js" id="search-script"></script> </head> <body> <header> <div class="tsd-page-toolbar"> <div class="container"> <div class="table-wrap"> <div class="table-cell" id="tsd-search" data-index="assets/js/search.json" data-base="."> <div class="field"> <label for="tsd-search-field" class="tsd-widget search no-caption">Search</label> <input id="tsd-search-field" type="text" /> </div> <ul class="results"> <li class="state loading">Preparing search index...</li> <li class="state failure">The search index is not available</li> </ul> <a href="index.html" class="title">@luvies/lazy</a> </div> <div class="table-cell" id="tsd-widgets"> <div id="tsd-filter"> <a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a> <div class="tsd-filter-group"> <div class="tsd-select" id="tsd-filter-visibility"> All <ul class="tsd-select-list"> <li data-value="public">Public</li> <li data-value="protected">Public/Protected</li> <li data-value="private" class="selected">All</li> </ul> </div> <input type="checkbox" id="tsd-filter-inherited" checked /> <label class="tsd-widget" for="tsd-filter-inherited">Inherited</label> <input type="checkbox" id="tsd-filter-externals" checked /> <label class="tsd-widget" for="tsd-filter-externals">Externals</label> </div> </div> <a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a> </div> </div> </div> </div> <div class="tsd-page-title"> <div class="container"> <h1>Project @luvies/lazy</h1> </div> </div> </header> <div class="container container-main"> <div class="row"> <div class="col-8 col-content"> <div class="tsd-panel tsd-typography"> <a href="#lazy-iteration" id="lazy-iteration" style="color: inherit; text-decoration: none;"> <h1>Lazy Iteration</h1> </a> <a href="https://travis-ci.com/luvies/lazy"><img src="https://travis-ci.com/luvies/lazy.svg?branch=master" alt="Build Status"></a> <img src="https://github.com/luvies/lazy/workflows/Node%2FDeno%20CI/badge.svg" alt="Github Build Status"> <a href="https://badge.fury.io/js/%40luvies%2Flazy"><img src="https://badge.fury.io/js/%40luvies%2Flazy.svg" alt="npm version"></a> This module is meant to provide memory-efficient lazy-evaluation iteration for iterable objects. The aim of this project is to support deno, node and browser, and support all native JavaScript systems for iteration (for-of, for-await-of, etc). <a href="#contents" id="contents" style="color: inherit; text-decoration: none;"> <h2>Contents</h2> </a> <ul> <li><a href="#installation">Installation</a><ul> <li><a href="#deno">Deno</a></li> <li><a href="#node">Node</a></li> </ul> </li> <li><a href="#overview">Overview</a></li> <li><a href="#examples">Examples</a></li> <li><a href="#interop-with-native">Introp with native</a></li> <li><a href="#api">API</a><ul> <li><a href="#promises">Promises</a></li> <li><a href="#no-additional-unexpected-iteration">No additional unexpected iteration</a></li> <li><a href="#custom-implementations">Custom implementations</a></li> <li><a href="#compatibility">Compatibility</a></li> <li><a href="#shorthand-usage">Shorthand usage</a></li> </ul> </li> <li><a href="#setting-up-this-project">Setting up this project</a></li> <li><a href="#footnotes">Footnotes</a></li> </ul> <a href="#installation" id="installation" style="color: inherit; text-decoration: none;"> <h2>Installation</h2> </a> <a href="#deno" id="deno" style="color: inherit; text-decoration: none;"> <h3>Deno</h3> </a> Use the following import: <pre><code class="language-ts">import { Lazy } from 'https://deno.land/x/lazy@v{version}/mod.ts'; </code></pre> Make sure the <code>@v{version}</code> tag is the correct one you want. I'd recommend against master, as it could change without notice & might be broken (although I will try not to break it). <a href="#node" id="node" style="color: inherit; text-decoration: none;"> <h3>Node</h3> </a> The packge can be found here: <a href="https://www.npmjs.com/package/@luvies/lazy">https://www.npmjs.com/package/@luvies/lazy</a>. Install via <pre><code>yarn add @luvies/lazy </code></pre> or <pre><code>npm install @luvies/lazy </code></pre> Import using <pre><code class="language-ts">import { Lazy } from '@luvies/lazy'; </code></pre> or <pre><code class="language-js">const { Lazy } = require('@luvies/lazy'); </code></pre> <a href="#overview" id="overview" style="color: inherit; text-decoration: none;"> <h2>Overview</h2> </a> At a base level, this module provides the following exports: <pre><code class="language-ts">abstract class Lazy<TElement> {...} // These are provided to allow direct imports, but are just aliases over the static class methods. function from<TElement>(iterable: Iterable<TElement>): Lazy<TElement>; function empty<TElement>(): Lazy<TElement>; function range(start: number, end?: number): Lazy<number>; function repeat<TElement>(element: TElement, count?: number): Lazy<TElement>; </code></pre> The <code>Lazy</code> class is the root of the module, all things come from it and are derived off it. To start using it, do something like the following: <pre><code class="language-ts">// Static method import. import { Lazy } from 'https://deno.land/x/lazy@v{version}/mod.ts'; const iterable = Lazy.from([1, 2, 3, 4, 5]); // Direct function import. import { from } from 'https://deno.land/x/lazy@v{version}/mod.ts'; const iterable = from([1, 2, 3, 4, 5]); </code></pre> After you have done this, the full power of the module is available to play with. <a href="#examples" id="examples" style="color: inherit; text-decoration: none;"> <h2>Examples</h2> </a> The aim of the module is to support the full suite of Linq methods the C# provides, as it covers a large surface area with the possible use-cases. Not only does it aim to provide them, it aims to act like them. Nothing is is executed until you call the iterator and start walking through the elements of the list. Here's a small example: <pre><code class="language-ts">const evenSquares = Lazy.range(0, 1000) .where(i => i % 2 === 0) .select(i => i ** 2); </code></pre> The result of this chain is an iterator object, however nothing has actually happened yet. As with linq, things only happen exactly when you ask for it: <pre><code class="language-ts">for (const num of evenSquares) { console.log(num); // 0, 4, 16, 36, 64, 100, 144... } </code></pre> A huge part of what makes linq so powerful is its composability, which this module provides at a base level: <pre><code class="language-ts">const selectedEvenNumbers = evenNumbers.take(10); </code></pre> As with C# Linq, this statement will create a new iteratable object that only returns the first 10 elements of the original iterable object. And the order of composability is not limited, every single method that returns an iterator supports chaining with every other method. On top of this, this module supports the same linq aggregation functions that linq does, for example: <pre><code class="language-ts">console.log(selectedEvenNumbers.sum()); // -> 1140 </code></pre> These functions allow you to deal with iterable objects at a high-level, hiding the fact that not all of the values might be available until the iteration is actually done. They also handle things like short-cuts, for example: <pre><code class="language-ts">console.log(Lazy.range(0, 1000).any(i => i > 100)); // -> true </code></pre> This function knows that as soon as the condition is fulfilled, it can stop iterating and hand back the result, saving time with iterating the entire list (which would be easy to forget otherwise). A primary aim of this library is to allow complex transformations on large datasets without having to deal with the copying that JavaScript normally does, for example: <pre><code class="language-ts">const data = getData(); // Could be a large list of datapoints. // Native JS const points = data .map(d => d.x) .filter(x => selectPoint(x)) .map(x => adjustPoint(x)); const avg = points.reduce((prev, curr) => prev + curr) / points.length; // Lazy iterators const avg = Lazy.from(data) .select(d => d.x) .where(x => selectPoint(x)) .select(x => adjustPoint(x)) .average(); </code></pre> The native version will create 3 copies of the array, non of which are used beyond the last to calculate the final average, after which point it is also usless. In contrast, the lazy iterator will only apply the transformations/filters at the exact point they are needed, so no copies are done, and the built-in aggregation function allow for a nicer final calculation. <a href="#interop-with-native" id="interop-with-native" style="color: inherit; text-decoration: none;"> <h2>Interop with native</h2> </a> While all of these functions are good, it would be difficult to integrate them without being about to easily convert back to native JS objects. Fortunately, this module provides just that. Currently there are 2 functions, <code>toArray</code> and <code>toMap</code>, which do pretty much exactly as they seem. You can end a lazy chain with one of these to make it resolve all of the iterators and output a native JS object, which can be then used in consuming code. On top of this, the entire module is build upon the native JS iteration protocol, meaning that any object that implements that can be used with it with no other changes. Just drop the object into a <code>Lazy.from(...)</code> call, and everything will be available. The <code>Lazy</code> class is also JSON-serialisable (as a list), meaning that you can simply pass the result of a chain into <code>JSON.stringify</code> and it will stringify correctly. <a href="#api" id="api" style="color: inherit; text-decoration: none;"> <h2>API</h2> </a> Visit <a href="https://luvies.github.io/lazy/">https://luvies.github.io/lazy/</a> for the full documentation. For an overview of the reference I use for developing this module, visit the <a href="https://docs.microsoft.com/en-us/dotnet/api/system.linq.enumerable">.NET Linq docs</a>. As an aside, all of the functions exported from <a href="lib/aggregates.ts">aggregates.ts</a> support taking in any object that implements the <code>Iterator<T></code> iterface, so you can use them without wrapping the iterable around <code>Lazy</code> first if you so wish (although I'd recommend using them through <code>Lazy</code>). <a href="#promises" id="promises" style="color: inherit; text-decoration: none;"> <h3>Promises</h3> </a> This module fully supports promises, and things like for-await-of. As an example (taken from the tests): <pre><code class="language-ts">const list = [ Promise.resolve(1), Promise.resolve(2), Promise.resolve(3), Promise.resolve(4), Promise.resolve(5), ]; for await (const element of Lazy.from(list)) { console.log(element); } /* Output: -> 1 -> 2 -> 3 -> 4 -> 5 */ </code></pre> However, it also supports resolving all promises in the iterable to their values all at once, using the help of <code>Promise.all</code>: <pre><code class="language-ts">const list = [ Promise.resolve(1), Promise.resolve(2), Promise.resolve(3), Promise.resolve(4), Promise.resolve(5), ]; for (const element of (await Lazy.from(list).resolveAll()).select( i => i ** 2, )) { console.log(element); } /* Output: -> 1 -> 4 -> 9 -> 16 -> 25 */ </code></pre> For TypeScript users, the <code>resolveAll</code> function all also correctly determines the resulting object type, even if there is a mix of promises and non promises: <pre><code class="language-ts">const list = [ Promise.resolve(1), 2 Promise.resolve(3), 4 Promise.resolve(5), ]; // type -> Array<number | Promise<number>> Lazy.from(list).resolveAll() // type -> Promise<Lazy<number>> </code></pre> <a href="#39no-additional-unexpected-iteration39" id="39no-additional-unexpected-iteration39" style="color: inherit; text-decoration: none;"> <h3>'No additional unexpected iteration'</h3> </a> For any function on <code>Lazy</code> that uses this term, it simply means 'if you start iteration on the resulting object, it will not perform any iteration you did not ask for'. To put it another way, when you call the iterator function, nothing will happen until you explicitly ask for the next element. This term is used since, for some functions, additional iteration is needed in order to perform the action required. An example of this would be the <code>reverse</code> method; you cannot iterate the first element of the result until you know what the last element of the underlying iterable is, so it has to iterate it completely first before returning the first element. In contrast, the <code>select</code> method will only iterate to the next element when you ask it to, thus it doesn't perform any additional unexpected iteration. <a href="#custom-implementations" id="custom-implementations" style="color: inherit; text-decoration: none;"> <h3>Custom implementations</h3> </a> This module supports using your own lazy iterable implementations in the chain. This is because of the way all of the functions are implemented, which is that they return a new object that extends the <code>Lazy</code> class and only contains the exact properties needed to perform the iteration. This allows you to write a custom implementation that does something unique to the problem you need to solve, and then integrate it into the normal chain. Here is an example implementation: <pre><code class="language-ts">class LazyToString<TSource> extends Lazy<string> { public constructor(private readonly _iterable: Iterable<TSource>) { super(); } public *[Symbol.iterator](): Iterator<string> { for (const element of this._iterable) { yield `${element}`; } } } const iterableToString = <TSource>(t: Iterable<TSource>) => new LazyToString(t); const result = Lazy.from([1, 10, 100, 1000]) .apply<LazyToString<number>, string>(iterableToString) .select(s => s.length) .toArray(); // result -> [1, 2, 3, 4] </code></pre> Obviously this is a contrived example, since the same could be done with a single <code>select</code>, but you see the power that is available. You can make any custom implementation at all, and it will chain as if it was part of the API itself. <a href="#shorthand-usage" id="shorthand-usage" style="color: inherit; text-decoration: none;"> <h3>Shorthand usage</h3> </a> If you are using <code>Lazy.from</code> a lot in your code, you can use the following snippet to make usage much more ergonomic: <pre><code class="language-ts">declare global { interface Array<T> { /** * Returns the lazy iterator of the current array. */ lazy: Lazy<T>; } } Object.defineProperty(Array.prototype, 'lazy', { get() { return Lazy.from(this); }, }); </code></pre> <a href="#setting-up-this-project" id="setting-up-this-project" style="color: inherit; text-decoration: none;"> <h2>Setting up this project</h2> </a> This project is written primarily for deno, with node support being done via a 2-step compilation process. In order to set up the project, you need to install <a href="https://github.com/denoland/deno">deno</a> globally. To make editing work in VSCode, make sure that you do the following: <ul> <li>Run <code>yarn</code> to install the dependencies that VSCode needs to edit properly</li> <li>Run <code>yarn init-types</code> to grab the types for the testing module</li> <li>Make sure that VSCode is using the local TypeScript version (bottom right of the editor while opening a <code>.ts</code> file)</li> <li>Adjust the <a href="tsconfig.json"><code>tsconfig.json</code></a> so that the <code>paths</code> are pointing to the right directory<ul> <li>They should point to the <code>$HOME/.deno/deps/http</code> and <code>$HOME/.deno/deps/https</code> directories</li> <li>The path has to be relative due to a TS server limitation</li> <li>DO NOT COMMIT THIS CHANGE, as it only applies to your setup and your setup only</li> </ul> </li> </ul> <a href="#compatibility" id="compatibility" style="color: inherit; text-decoration: none;"> <h3>Compatibility</h3> </a> As mentioned before, this module is fully compatible with normal ES2015 iterators and native arrays/maps. It targets ES2015, meaning that if you need to support ES5 & earlier, you will need to use a transpiler like babel. For Node.js, it requires about v6 or higher (not properly tested on this version though). <a href="#footnotes" id="footnotes" style="color: inherit; text-decoration: none;"> <h2>Footnotes</h2> </a> Massive thanks to the .NET Core team and their work on Linq, the source reference was invaluable when implementing some of the methods here. </div> </div> <div class="col-4 col-menu menu-sticky-wrap menu-highlight"> <nav class="tsd-navigation primary"> <ul> <li class=" "> <a href="modules.html">Exports</a> </li> </ul> </nav> <nav class="tsd-navigation secondary menu-sticky"> <ul class="before-current"> <li class=" tsd-kind-class tsd-has-type-parameter"> <a href="classes/lazy.html" class="tsd-kind-icon">Lazy</a> </li> <li class=" tsd-kind-function tsd-has-type-parameter"> <a href="modules.html#empty" class="tsd-kind-icon">empty</a> </li> <li class=" tsd-kind-function tsd-has-type-parameter"> <a href="modules.html#from" class="tsd-kind-icon">from</a> </li> <li class=" tsd-kind-function"> <a href="modules.html#range" class="tsd-kind-icon">range</a> </li> <li class=" tsd-kind-function tsd-has-type-parameter"> <a href="modules.html#repeat" class="tsd-kind-icon">repeat</a> </li> </ul> </nav> </div> </div> </div> <footer class="with-border-bottom"> <div class="container"> <h2>Legend</h2> <div class="tsd-legend-group"> <ul class="tsd-legend"> <li class="tsd-kind-method tsd-parent-kind-class">Method</li> </ul> <ul class="tsd-legend"> <li class="tsd-kind-method tsd-parent-kind-class tsd-is-static">Static method</li> </ul> </div> </div> </footer> <div class="container tsd-generator"> Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a> </div> <div class="overlay"></div> <script src="assets/js/main.js"></script> </body> </html>