patch current release

.husky/pre-commit

@@ -1 +1 @@
-pnpm lint
+pnpm lint:MA

.xo-config.json

@@ -1,6 +1,7 @@
 {
     "env": ["jest", "node"],
     "rules": {
+        "no-await-in-loop": "off",
         "import/extensions": "off",
         "unicorn/prefer-module": "off",
         "unicorn/no-array-for-each": "off",

README.md

@@ -1,57 +1,60 @@
 # n-tuple-array
 
-Get a specified amount of items when iterating over a JavaScript array, instead of the 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.
 
 
 ## Motivation
 
-Imagine that you received a collection of coordinates (latitude and longitude), but they were sent 
-as a flat array of values to speed up the data transfers.
+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 (their logical representation), such that you'd go **from** 
+`n-tuple-array` can help you get out the coordinates in pairs (i.e their logical representation), such that you'd go
+
+**from** 
 ```json
-// flatCoords
+// flat coordinates
 ["5.7225", "-9.6273", "2.68452", "-30.9501", ...]
 ```
 
 **to**
 ```javascript
-// generate pairs by default
-const coordIterable = tuplesFromArray({ list: flatCoords });
+// the iterable will generate pairs by default
+const coordsIterable = tuplesFromArray({ list: flatCoords });
 
 // using for..of, get pairs as ["5.7225", "-9.6273"] ...
-for (const pair of coordIterable) {
+for (const pair of coordsIterable) {
     console.log(pair);
 }
 
-// OR manipulate pairs with regular array functions
-const coordPairs = Array.from(coordIterable);
-console.log(Array.isArray(coordPairs));   // true
-// prints ["5.7225", "-9.6273"] ...
-coordPairs
+// OR manipulate pairs with regular array 
+// functions like map, filter, forEach ...
+const coordsInPairs = Array.from(coordsIterable);
+console.log(Array.isArray(coordsInPairs));   // true
+coordsInPairs
     .map(pair => {
+        // pair is ["5.7225", "-9.6273"] ...
         return myTransform(pair);
     })
 	.forEach((pair) => {
+        // pair is ["5.7225", "-9.6273"] ...
         placeOnMap(pair);
     });
 ```
 
 ### Some Real World Examples
 
-#### Wole Joko
+#### 1. Wole Joko
 
-I first tried my hands on this concept when [building wole-joko](https://github.com/chalu/wole-joko/blob/dev/src/js/utils.js#L57-L92), 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. I later took some time to [give the project more life](https://wole-joko.netlify.app/)
+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/
 
-#### Execute max of X tasks in parallel
+#### 2. Execute max of `N` async tasks
 
-JS challenge by [@thdxr on X.com](https://twitter.com/thdxr) <br>
 ![](./assets/the-dax-js-challenge.png "JS challenge by @thdxr")
-<br> <br>
 
 > 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/demo/demo-classic.ts#L6-L40)  <br>
+`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>
 
@@ -92,5 +95,5 @@ for (const quintet of quintetIterator) {
 }
 ```
 
-See more examples in [src/demo](./src/demo/) 
+See more examples in [src/examples](./src/examples/) 
 

dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+    "type": "commonjs"
+}

dist/cjs/types/index.d.ts

@@ -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/esm/index.mjs

@@ -1,9 +1,9 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.tuplesFromArray = exports.InvalidInvocationParameterError = void 0;
-class InvalidInvocationParameterError extends Error {
+/**
+ * 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 class InvalidInvocationParameterError extends Error {
 }
-exports.InvalidInvocationParameterError = InvalidInvocationParameterError;
 const validateParametersOrThrow = (list, maxItems, match) => {
     if (!list || !Array.isArray(list)) {
         throw new InvalidInvocationParameterError('expected list to be an array');
@@ -18,7 +18,34 @@ const validateParametersOrThrow = (list, maxItems, match) => {
         throw new InvalidInvocationParameterError(message);
     }
 };
-const tuplesFromArray = (config) => {
+/**
+ * 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 const tuplesFromArray = (config) => {
     const { list, match, maxItems = 2 } = config;
     validateParametersOrThrow(list, maxItems, match);
     let cursor = 0;
@@ -50,13 +77,12 @@ const tuplesFromArray = (config) => {
         return { value: items, done: items.length === 0 };
     };
     const iterable = {
+        next: proceedNext,
         [Symbol.iterator]() {
-            return {
-                next: proceedNext,
-            };
+            return this;
         },
     };
     return iterable;
 };
-exports.tuplesFromArray = tuplesFromArray;
-exports.default = exports.tuplesFromArray;
+export default tuplesFromArray;
+//# sourceMappingURL=index.js.map

dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+    "type": "module"
+}

dist/esm/types/index.d.ts

@@ -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

fix-pkgs

@@ -0,0 +1,11 @@
+cat >dist/cjs/package.json <<!EOF
+{
+    "type": "commonjs"
+}
+!EOF
+
+cat >dist/esm/package.json <<!EOF
+{
+    "type": "module"
+}
+!EOF