Patch v0.1.6 (#24)

Patch v0.1.6 with cleaner JS examples and README updates

Author: chalu

README.md

@@ -1,32 +1,41 @@
 # n-tuple-array
 
-Get a **`configurable`** amount of items when iterating over a JavaScript array, instead of a single item that arrays provide per iteration, by default.
+Get a **`configurable`** amount of items when iterating over a JavaScript array, instead of a single item that arrays provide per iteration, by default. 
+
+Put differently, easily and safely retrieve a configurable number of items from an array, without having to manipulate array bounds or indices.
 
 
 ## Motivation
 
 Imagine that you received a large collection of coordinates (latitude and longitude), but they were sent 
 as a flat array of values to speed up the data transfer.
 
-`n-tuple-array` can help you get out the coordinates in pairs (i.e their logical representation), such that you'd go
+`n-tuple-array` can help you get out the coordinates in pairs (i.e their logical representation), such that you'd __easily__ go
 
 **from** 
 ```json
 // flat coordinates
 ["5.7225", "-9.6273", "2.68452", "-30.9501", ...]
 ```
 
-**to**
+**to** 
+```json
+// coordinates in pairs
+[["5.7225", "-9.6273"], ["2.68452", "-30.9501"], ...]
+```
+
+**using**
 ```javascript
 // the iterable will generate pairs by default
 const coordsIterable = tuplesFromArray({ list: flatCoords });
 
-// using for..of, get pairs as ["5.7225", "-9.6273"] ...
+// with for..of, get pairs as ["5.7225", "-9.6273"] ...
 for (const pair of coordsIterable) {
     console.log(pair);
 }
 
-// OR manipulate pairs with regular array 
+// OR 
+// manipulate pairs with regular array 
 // functions like map, filter, forEach ...
 const coordsInPairs = Array.from(coordsIterable);
 console.log(Array.isArray(coordsInPairs));   // true
@@ -41,29 +50,6 @@ coordsInPairs
     });
 ```
 
-### Some Real World Examples
-
-#### 1. Wole Joko
-
-I first tried my hands on this concept when [fleshing out wole-joko](https://github.com/chalu/wole-joko/blob/dev/src/js/utils.js#L57-L92), which strated as a _live coding task_ I was asked to do in an engineering manager interview :man_shrugging 
-It was a simulation of people entering an event hall to get seated, but **only two** could get in at a time - https://wole-joko.netlify.app/
-
-#### 2. Execute max of `N` async tasks
-
-![](./assets/the-dax-js-challenge.png "JS challenge by @thdxr")
-
-> The below was adapted for more concise terminal output
-
-`n-tuple-array` solution. View [code here](https://github.com/chalu/n-tuple-array/blob/main/src/examples/classic.ts#L6-L40)  <br>
-![](./assets/demo-classic.png "n-tuple-array solution")
-<br> <br>
-
-`n-tuple-array` solution demo <br>
-`n-tuple-array` solution demo <br>
-![](./assets/ntuple-array-demo-optimized.gif "n-tuple-array solution demo")
-
- 
-
 ## Setup & Usage
 
 ```bash
@@ -72,7 +58,6 @@ npm install @chalu/n-tuple-array
 
 ```javascript
 const { tuplesFromArray } = require('@chalu/n-tuple-array');
-const { tuplesFromArray } = require('@chalu/n-tuple-array');
 
 // some setup
 const numbers = Array.from({length: 100}, (_, i) => i + 1);
@@ -86,16 +71,39 @@ const isEven = (item) => {
     return true;
 };
 
-// use the lib
+// use the lib, get batches of <= 5 nums
+// from the collection in numbers above
 const quintetIterator = tuplesFromArray({
     list: numbers, maxItems: 5, match: isEven
 });
 
+// since quintetIterator uses the isEven match
+// function, give us only even numbers in fives
 for (const quintet of quintetIterator) {
     // prints [ 2, 4, 6, 8, 10 ] ... [ 92, 94, 96, 98, 100 ]
 	console.log(quintet);
 }
 ```
 
+### Some Real World Examples
+
+#### 1. Wole Joko
+
+I first tried my hands on this concept when [fleshing out wole-joko](https://github.com/chalu/wole-joko/blob/dev/src/js/utils.js#L57-L92), which strated as a _live coding task_ I was asked to do in an engineering manager interview :man_shrugging 
+It was a simulation of people entering an event hall to get seated, but **only two** could get in at a time - https://wole-joko.netlify.app/
+
+#### 2. Execute max of `N` async tasks at the same time
+
+![](./assets/the-dax-js-challenge.png "JS challenge by @thdxr")
+
+> The below was adapted for more concise terminal output
+
+`n-tuple-array` solution. View [code here](https://github.com/chalu/n-tuple-array/blob/main/src/examples/classic.ts#L6-L40)  <br>
+![](./assets/demo-classic.png "n-tuple-array solution")
+<br> <br>
+
+`n-tuple-array` solution demo <br>
+![](./assets/ntuple-array-demo-optimized.gif)
+
 See more examples in [src/examples](./src/examples/) 
 

assets/the-dax-js-challenge.png

@@ -1,13 +1,53 @@
-type Item<T> = T | undefined;
-type Value<T> = Array<Item<T>>;
 export type Matcher<T> = (item: T | unknown) => boolean;
 export type TupleConfig<T> = {
+    /**
+     * The input array to use
+     */
     list: T[];
+    /**
+     * The max number of items to return from the input array, per iteration
+     * @defaultValue 2
+     */
     maxItems?: number;
+    /**
+     * When provided, a function used to determine which items in the input array
+     * are eligible to be included, per iteration
+     */
     match?: Matcher<T>;
 };
+/**
+ * An exception than can be thrown if there is no input array, `maxItems` is <= 0 or is not
+ * a number, or `match` is not a function
+ */
 export declare class InvalidInvocationParameterError extends Error {
 }
-export declare const tuplesFromArray: <T>(config: TupleConfig<T>) => Iterable<Value<T>>;
+/**
+ * Returns an iterable iterator that ouputs a configured
+ * list of items when iterating over a given array
+ *
+ * @typeParam T - Type of items the input list contains
+ *
+ * @param config - An object to indicate the input array `config.list`, and set the
+ * max size of items per interation `config.maxItems`. You can also optionally specify `config.match`
+ * as a function that should return true to filter in items from the input array
+ * (or false to filter them out) when deciding what items is to be included per iteration
+ *
+ * @function
+ * @throws InvalidInvocationParameterError
+ * This exception is thrown if there is no input array, `maxItems` is <= 0 or is not
+ * a number, or `match` is not a function
+ *
+ * @returns an IterableIterator
+ *
+ * @example
+ * Here is an example that will get max of 3 items from
+ * each iteration on the returned iterable
+ * ```javascript
+ * 	const iterable = tuplesFromArray({
+ * 	  list:[], maxSize: 3, match: (itm) => !!itm
+ * 	});
+ * ```
+ */
+export declare const tuplesFromArray: <T>(config: TupleConfig<T>) => IterableIterator<(T | undefined)[]>;
 export default tuplesFromArray;
 //# sourceMappingURL=index.d.ts.map

dist/cjs/types/index.d.ts

@@ -1,7 +1,7 @@
 {
   "name": "@chalu/n-tuple-array",
-  "version": "0.1.6",
-  "description": "Get a specified amount of items when iterating over a JavaScript array, instead of just a single item that arrays provide!",
+  "version": "0.1.7",
+  "description": "Configure and get a specified amount of items when iterating over a JavaScript array.",
   "main": "./dist/cjs/index.js",
   "module": "dist/esm/index.mjs",
   "types": "./dist/cjs/types/index.d.ts",

package.json

@@ -14,6 +14,7 @@ const processTask = async (todo, batchId) => {
 };
 
 const executeConcurrent = async (todos, maxBatchSize) => {
+	console.log(`\ndo <= ${maxBatchSize} of ${todos.length} tasks (concurrently), at any given time\n`);
 	const done = [];
 	const todosCopy = todos.slice();
 	const worker = async (_, batchIndex) => {
@@ -35,5 +36,5 @@ const executeConcurrent = async (todos, maxBatchSize) => {
 	const maxTasksPerTime = 2;
 
 	const allDone = await executeConcurrent(tasks, maxTasksPerTime);
-	console.log(allDone);
+	console.log('\n', allDone);
 })();

src/examples/js/concurrent.js

@@ -16,13 +16,13 @@ const processTask = async (todo, batchId) => {
 };
 
 const executeWitLibrary = async (todos, maxBatchSize) => {
-	console.log(`do <= ${maxBatchSize} of ${todos.length} tasks, at any given time`);
+	console.log(`\ndo <= ${maxBatchSize} of ${todos.length} tasks, at any given time (with library)`);
 	const done = [];
 
 	let batchIndex = 1;
 	const todosBatchIterable = tuplesFromArray({list: todos, maxItems: maxBatchSize});
 	for (const batch of todosBatchIterable) {
-		console.log(`----- starting batch [${batchIndex}], ${batch.length} todos`);
+		console.log(`\n----- starting batch [${batchIndex}], ${batch.length} todos`);
 		const results = await Promise.allSettled(
 			batch.map(todo => processTask(todo, batchIndex)),
 		);
@@ -39,5 +39,5 @@ const executeWitLibrary = async (todos, maxBatchSize) => {
 	const maxTasksPerTime = 2;
 
 	const allDone = await executeWitLibrary(tasks, maxTasksPerTime);
-	console.log(allDone);
+	console.log('\n', allDone);
 })();

src/examples/js/with-lib.mjs

@@ -15,15 +15,15 @@ const processTask = async (todo, batchId) => {
 
 // Everywhere start/end is used is repititive and error prone
 const executeWithoutLibrary = async (todos, maxBatchSize) => {
-	console.log(`do <= ${maxBatchSize} of ${todos.length} tasks, at any given time`);
+	console.log(`\ndo <= ${maxBatchSize} of ${todos.length} tasks, at any given time (no library)`);
 	const done = [];
 
 	let start = 0;
 	let end = start + maxBatchSize;
 	let batchIndex = 1;
 	let batch = todos.slice(start, end);
 	while (batch.length > 0) {
-		console.log(`----- starting batch [${batchIndex}], ${batch.length} todos`);
+		console.log(`\n----- starting batch [${batchIndex}], ${batch.length} todos`);
 		const results = await Promise.allSettled(
 			batch.map(todo => processTask(todo, batchIndex)),
 		);
@@ -48,5 +48,5 @@ const executeWithoutLibrary = async (todos, maxBatchSize) => {
 	const maxTasksPerTime = 2;
 
 	const allDone = await executeWithoutLibrary(tasks, maxTasksPerTime);
-	console.log(allDone);
+	console.log('\n', allDone);
 })();