@thi.ng/transducers 8.7.2 → 8.8.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-09-19T10:42:50Z
+- **Last updated**: 2023-10-11T10:05:08Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,13 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [8.8.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/transducers@8.8.0) (2023-10-11)
+
+#### 🚀 Features
+
+- add repeatedly2d/3d() iterators ([5057939](https://github.com/thi-ng/umbrella/commit/5057939))
+- add consume() helper fn ([e612846](https://github.com/thi-ng/umbrella/commit/e612846))
+
 ## [8.7.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/transducers@8.7.0) (2023-09-15)
 
 #### 🚀 Features

package/README.md

@@ -52,6 +52,7 @@ This project is part of the
     - [transduce](#transduce)
     - [transduceRight](#transduceright)
     - [run](#run)
+    - [consume](#consume)
   - [Transducers](#transducers)
   - [Generators / Iterators](#generators--iterators)
   - [Reducers](#reducers)
@@ -174,7 +175,7 @@ For Node.js REPL:
 const transducers = await import("@thi.ng/transducers");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 8.71 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 8.78 KB
 
 ## Dependencies
 
@@ -201,6 +202,7 @@ A selection:
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/ascii-raymarch.jpg" width="240"/>                | ASCII art raymarching with thi.ng/shader-ast & thi.ng/text-canvas                                       | [Demo](https://demo.thi.ng/umbrella/ascii-raymarch/)       | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/ascii-raymarch)      |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/big-font.png" width="240"/>                      | Large ASCII font text generator using @thi.ng/rdom                                                      | [Demo](https://demo.thi.ng/umbrella/big-font/)             | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/big-font)            |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/bitmap-font.gif" width="240"/>                   | Figlet-style bitmap font creation with transducers                                                      | [Demo](https://demo.thi.ng/umbrella/bitmap-font/)          | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/bitmap-font)         |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/canvas-recorder.png" width="240"/>               | Self-modifying, animated typographic grid with emergent complex patterns                                | [Demo](https://demo.thi.ng/umbrella/canvas-recorder/)      | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/canvas-recorder)     |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/cellular-automata.png" width="240"/>             | 2D transducer based cellular automata                                                                   | [Demo](https://demo.thi.ng/umbrella/cellular-automata/)    | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/cellular-automata)   |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/commit-heatmap.png" width="240"/>                | Heatmap visualization of this mono-repo's commits                                                       |                                                            | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/commit-heatmap)      |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/commit-table-ssr.png" width="240"/>              | Filterable commit log UI w/ minimal server to provide commit history                                    | [Demo](https://demo.thi.ng/umbrella/commit-table-ssr/)     | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/commit-table-ssr)    |
@@ -851,6 +853,26 @@ every value produced by the transducer. If `fx` is _not_ given, the
 transducer is assumed to include at least one `sideEffect()` step
 itself. Returns nothing.
 
+#### consume
+
+`consume(src: Iterable<any>): void`
+
+Similar to `run()`, consumes given iterable, presumably for any implicit
+side-effects. Iterable MUST be finite!
+
+```ts
+// here the function given to repeatedly2d() has only a side-effect, however
+// repeatedly2d() itself is lazy. Using consume() then forces this lazy iterator/generator
+// to be realized and so also the side-effects to be executed
+consume(repeatedly2d((x, y) => console.log("output:", [x, y]), 2, 3));
+// output: [ 0, 0 ]
+// output: [ 1, 0 ]
+// output: [ 0, 1 ]
+// output: [ 1, 1 ]
+// output: [ 0, 2 ]
+// output: [ 1, 2 ]
+```
+
 ### Transducers
 
 All of the following functions can be used and composed as transducers.
@@ -964,6 +986,8 @@ transduce(map((x) => x*10), push(), range(4))
 - [rangeNd](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers/src/range-nd.ts)
 - [repeat](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers/src/repeat.ts)
 - [repeatedly](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers/src/repeatedly.ts)
+- [repeatedly2d](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers/src/repeatedly2d.ts)
+- [repeatedly3d](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers/src/repeatedly3d.ts)
 - [reverse](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers/src/reverse.ts)
 - [sortedKeys](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers/src/sorted-keys.ts)
 - [symmetric](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers/src/symmetric.ts)

package/consume.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Consumes given iterable, presumably for any implicit side-effects. Iterable
+ * MUST be finite!
+ *
+ * @remarks
+ * See {@link run} for a similar approach when also side-effecting transducers
+ * should be applied.
+ *
+ * @example
+ * ```ts
+ * consume(repeatedly2d((x, y) => console.log("output:", [x, y]), 2, 3));
+ * // output: [ 0, 0 ]
+ * // output: [ 1, 0 ]
+ * // output: [ 0, 1 ]
+ * // output: [ 1, 1 ]
+ * // output: [ 0, 2 ]
+ * // output: [ 1, 2 ]
+ * ```
+ *
+ * @param src
+ */
+export declare const consume: (src: Iterable<any>) => void;
+//# sourceMappingURL=consume.d.ts.map

package/consume.js

@@ -0,0 +1,25 @@
+/**
+ * Consumes given iterable, presumably for any implicit side-effects. Iterable
+ * MUST be finite!
+ *
+ * @remarks
+ * See {@link run} for a similar approach when also side-effecting transducers
+ * should be applied.
+ *
+ * @example
+ * ```ts
+ * consume(repeatedly2d((x, y) => console.log("output:", [x, y]), 2, 3));
+ * // output: [ 0, 0 ]
+ * // output: [ 1, 0 ]
+ * // output: [ 0, 1 ]
+ * // output: [ 1, 1 ]
+ * // output: [ 0, 2 ]
+ * // output: [ 1, 2 ]
+ * ```
+ *
+ * @param src
+ */
+export const consume = (src) => {
+    for (let _ of src)
+        ;
+};

package/index.d.ts

@@ -8,6 +8,7 @@ export * from "./step.js";
 export * from "./transduce.js";
 export * from "./comp.js";
 export * from "./compr.js";
+export * from "./consume.js";
 export * from "./deep-transform.js";
 export * from "./juxtr.js";
 export * from "./lookup.js";
@@ -139,6 +140,8 @@ export * from "./range3d.js";
 export * from "./range-nd.js";
 export * from "./repeat.js";
 export * from "./repeatedly.js";
+export * from "./repeatedly2d.js";
+export * from "./repeatedly3d.js";
 export * from "./reverse.js";
 export * from "./sorted-keys.js";
 export * from "./symmetric.js";

package/index.js

@@ -9,6 +9,7 @@ export * from "./transduce.js";
 // helpers
 export * from "./comp.js";
 export * from "./compr.js";
+export * from "./consume.js";
 export * from "./deep-transform.js";
 export * from "./juxtr.js";
 export * from "./lookup.js";
@@ -143,6 +144,8 @@ export * from "./range3d.js";
 export * from "./range-nd.js";
 export * from "./repeat.js";
 export * from "./repeatedly.js";
+export * from "./repeatedly2d.js";
+export * from "./repeatedly3d.js";
 export * from "./reverse.js";
 export * from "./sorted-keys.js";
 export * from "./symmetric.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/transducers",
-  "version": "8.7.2",
+  "version": "8.8.0",
   "description": "Lightweight transducer implementations for ES6 / TypeScript",
   "type": "module",
   "module": "./index.js",
@@ -39,13 +39,13 @@
   },
   "dependencies": {
     "@thi.ng/api": "^8.9.5",
-    "@thi.ng/arrays": "^2.6.0",
+    "@thi.ng/arrays": "^2.6.1",
     "@thi.ng/checks": "^3.4.5",
     "@thi.ng/compare": "^2.2.0",
     "@thi.ng/compose": "^2.1.41",
     "@thi.ng/errors": "^2.3.5",
     "@thi.ng/math": "^5.6.1",
-    "@thi.ng/random": "^3.6.6"
+    "@thi.ng/random": "^3.6.7"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.36.4",
@@ -147,6 +147,9 @@
     "./conj": {
       "default": "./conj.js"
     },
+    "./consume": {
+      "default": "./consume.js"
+    },
     "./converge": {
       "default": "./converge.js"
     },
@@ -459,6 +462,12 @@
     "./repeatedly": {
       "default": "./repeatedly.js"
     },
+    "./repeatedly2d": {
+      "default": "./repeatedly2d.js"
+    },
+    "./repeatedly3d": {
+      "default": "./repeatedly3d.js"
+    },
     "./reverse": {
       "default": "./reverse.js"
     },
@@ -579,5 +588,5 @@
     ],
     "year": 2016
   },
-  "gitHead": "10d8b3725e96c5d704c759489a89f132892b181e\n"
+  "gitHead": "e9f04908dc37ae9e29320f098d195f9f8445a1ad\n"
 }

package/repeatedly2d.d.ts

@@ -0,0 +1,22 @@
+import type { FnU2 } from "@thi.ng/api";
+/**
+ * Syntax sugar for `map(fn, range2d(cols, rows))`. Returns iterator yielding
+ * values of given 2-arg function `fn` which is called repeatedly with `x` and
+ * `y` grid coordinates. The iteration order is always row-major.
+ *
+ * @example
+ * ```ts
+ * [...repeatedly2d((x, y) => [(x + 1) * 10, (y + 1) * 100], 2, 3)]
+ * // [
+ * //   [ 10, 100 ], [ 20, 100 ],
+ * //   [ 10, 200 ], [ 20, 200 ],
+ * //   [ 10, 300 ], [ 20, 300 ]
+ * // ]
+ * ```
+ *
+ * @param fn - value producer
+ * @param cols - number of columns
+ * @param rows - number of rows
+ */
+export declare function repeatedly2d<T>(fn: FnU2<number, T>, cols: number, rows: number): Generator<T, void, unknown>;
+//# sourceMappingURL=repeatedly2d.d.ts.map

package/repeatedly2d.js

@@ -0,0 +1,26 @@
+/**
+ * Syntax sugar for `map(fn, range2d(cols, rows))`. Returns iterator yielding
+ * values of given 2-arg function `fn` which is called repeatedly with `x` and
+ * `y` grid coordinates. The iteration order is always row-major.
+ *
+ * @example
+ * ```ts
+ * [...repeatedly2d((x, y) => [(x + 1) * 10, (y + 1) * 100], 2, 3)]
+ * // [
+ * //   [ 10, 100 ], [ 20, 100 ],
+ * //   [ 10, 200 ], [ 20, 200 ],
+ * //   [ 10, 300 ], [ 20, 300 ]
+ * // ]
+ * ```
+ *
+ * @param fn - value producer
+ * @param cols - number of columns
+ * @param rows - number of rows
+ */
+export function* repeatedly2d(fn, cols, rows) {
+    for (let y = 0; y < rows; y++) {
+        for (let x = 0; x < cols; x++) {
+            yield fn(x, y);
+        }
+    }
+}

package/repeatedly3d.d.ts

@@ -0,0 +1,22 @@
+import type { FnU3 } from "@thi.ng/api";
+/**
+ * Syntax sugar for `map(fn, range3d(cols, rows, slices))`. Returns iterator yielding
+ * values of given 3-arg function `fn` which is called repeatedly with `x`, `y` and
+ * `z` grid coordinates. The iteration order is always slice major, then row-major.
+ *
+ * @example
+ * ```ts
+ * [...repeatedly3d((x, y, z) => [(x+1)*10, (y+1)*100, (z+1)*1000], 2, 2, 2)]
+ * // [
+ * //   [ 10, 100, 1000 ], [ 20, 100, 1000 ], [ 10, 200, 1000 ], [ 20, 200, 1000 ],
+ * //   [ 10, 100, 2000 ], [ 20, 100, 2000 ], [ 10, 200, 2000 ], [ 20, 200, 2000 ]
+ * // ]
+ * ```
+ *
+ * @param fn - value producer
+ * @param cols - number of columns
+ * @param rows - number of rows
+ * @param slices - number of slices
+ */
+export declare function repeatedly3d<T>(fn: FnU3<number, T>, cols: number, rows: number, slices: number): Generator<T, void, unknown>;
+//# sourceMappingURL=repeatedly3d.d.ts.map

package/repeatedly3d.js

@@ -0,0 +1,28 @@
+/**
+ * Syntax sugar for `map(fn, range3d(cols, rows, slices))`. Returns iterator yielding
+ * values of given 3-arg function `fn` which is called repeatedly with `x`, `y` and
+ * `z` grid coordinates. The iteration order is always slice major, then row-major.
+ *
+ * @example
+ * ```ts
+ * [...repeatedly3d((x, y, z) => [(x+1)*10, (y+1)*100, (z+1)*1000], 2, 2, 2)]
+ * // [
+ * //   [ 10, 100, 1000 ], [ 20, 100, 1000 ], [ 10, 200, 1000 ], [ 20, 200, 1000 ],
+ * //   [ 10, 100, 2000 ], [ 20, 100, 2000 ], [ 10, 200, 2000 ], [ 20, 200, 2000 ]
+ * // ]
+ * ```
+ *
+ * @param fn - value producer
+ * @param cols - number of columns
+ * @param rows - number of rows
+ * @param slices - number of slices
+ */
+export function* repeatedly3d(fn, cols, rows, slices) {
+    for (let z = 0; z < slices; z++) {
+        for (let y = 0; y < rows; y++) {
+            for (let x = 0; x < cols; x++) {
+                yield fn(x, y, z);
+            }
+        }
+    }
+}