From 130f5e35f5dcebe39c0ed65c1da472580671c0d6 Mon Sep 17 00:00:00 2001 From: Luke Davies Date: Tue, 5 Mar 2019 19:53:33 +0000 Subject: [PATCH] Formatted README --- README.md | 40 +++++++++++++++++++++++++++++++--------- 1 file changed, 31 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index b6d1910..da204d2 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,9 @@ This module is meant to provide memory-efficient lazy-evaluation iteration for i - [Footnotes](#footnotes) ## Installation + ### Deno + Use the following import: ```ts @@ -31,6 +33,7 @@ import { Lazy } from 'https://deno.land/x/lazy@v1.3.0/mod.ts'; Make sure the `@v{version}` 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). ### Node + The packge can be found here: https://www.npmjs.com/package/@luvies/lazy. Install via @@ -58,6 +61,7 @@ const { Lazy } = require('@luvies/lazy'); ``` ## Overview + At a base level, this module provides the following exports: ```ts @@ -87,10 +91,13 @@ const iterable = from([1, 2, 3, 4, 5]); After you have done this, the full power of the module is available to play with. ## Examples + 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: ```ts -const evenSquares = Lazy.range(0, 1000).where(i => i % 2 === 0).select(i => i ** 2); +const evenSquares = Lazy.range(0, 1000) + .where(i => i % 2 === 0) + .select(i => i ** 2); ``` 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: @@ -116,7 +123,7 @@ console.log(selectedEvenNumbers.sum()); // -> 1140 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: ```ts -console.log(Lazy.range(0, 1000).any(i => i > 100)) // -> true +console.log(Lazy.range(0, 1000).any(i => i > 100)); // -> true ``` 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). @@ -127,16 +134,24 @@ A primary aim of this library is to allow complex transformations on large datas 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 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(); +const avg = Lazy.from(data) + .select(d => d.x) + .where(x => selectPoint(x)) + .select(x => adjustPoint(x)) + .average(); ``` 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. ## Interop with native + 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, `toArray` and `toMap`, 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 `Lazy.from(...)` call, and everything will be available. @@ -144,6 +159,7 @@ On top of this, the entire module is build upon the native JS iteration protocol The `Lazy` class is also JSON-serialisable (as a list), meaning that you can simply pass the result of a chain into `JSON.stringify` and it will stringify correctly. ## API + Visit https://luvies.github.io/lazy/ for the full documentation. For an overview of the reference I use for developing this module, visit the [.NET Linq docs](https://docs.microsoft.com/en-us/dotnet/api/system.linq.enumerable). @@ -151,6 +167,7 @@ For an overview of the reference I use for developing this module, visit the [.N As an aside, all of the functions exported from [aggregates.ts](lib/aggregates.ts) support taking in any object that implements the `Iterator` iterface, so you can use them without wrapping the iterable around `Lazy` first if you so wish (although I'd recommend using them through `Lazy`). ### Promises + This module fully supports promises, and things like for-await-of. As an example (taken from the tests): ```ts @@ -188,7 +205,9 @@ const list = [ Promise.resolve(5), ]; -for (const element of (await Lazy.from(list).resolveAll()).select(i => i ** 2)) { +for (const element of (await Lazy.from(list).resolveAll()).select( + i => i ** 2, +)) { console.log(element); } @@ -218,16 +237,16 @@ Lazy.from(list).resolveAll() // type -> Promise> ``` ### 'No additional unexpected iteration' + For any function on `Lazy` 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 `reverse` 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 `select` method will only iterate to the next element when you ask it to, thus it doesn't perform any additional unexpected iteration. ### Custom implementations + 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 `Lazy` 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: ```ts class LazyToString extends Lazy { - public constructor( - private readonly _iterable: Iterable, - ) { + public constructor(private readonly _iterable: Iterable) { super(); } @@ -250,6 +269,7 @@ const result = Lazy.from([1, 10, 100, 1000]) Obviously this is a contrived example, since the same could be done with a single `select`, 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. ## Setting up this project + 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 [deno](https://github.com/denoland/deno) globally. To make editing work in VSCode, make sure that you do the following: - Run `yarn` to install the dependencies that VSCode needs to edit properly @@ -258,10 +278,12 @@ This project is written primarily for deno, with node support being done via a 2 - Adjust the [`tsconfig.json`](tsconfig.json) so that the `paths` are pointing to the right directory - They should point to the `$HOME/.deno/deps/http` and `$HOME/.deno/deps/https` directories - The path has to be relative due to a TS server limitation - - *DO NOT COMMIT THIS CHANGE*, as it only applies to your setup and your setup only + - _DO NOT COMMIT THIS CHANGE_, as it only applies to your setup and your setup only ### Compatibility + 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). ## Footnotes + Massive thanks to the .NET Core team and their work on Linq, the source reference was invaluable when implementing some of the methods here.