@thi.ng/compose 2.1.40 → 2.1.41

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-08-27T11:20:59Z
+- **Last updated**: 2023-08-29T09:49:09Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.

package/README.md

@@ -14,6 +14,7 @@ This project is part of the
 - [Status](#status)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
+- [Usage examples](#usage-examples)
 - [API](#api)
 - [Authors](#authors)
 - [License](#license)
@@ -55,6 +56,18 @@ Package sizes (brotli'd, pre-treeshake): ESM: 751 bytes
 - [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
 - [@thi.ng/errors](https://github.com/thi-ng/umbrella/tree/develop/packages/errors)
 
+## Usage examples
+
+Several demos in this repo's
+[/examples](https://github.com/thi-ng/umbrella/tree/develop/examples)
+directory are using this package.
+
+A selection:
+
+| Screenshot                                                                                                                | Description                   | Live demo                                                | Source                                                                                |
+|:--------------------------------------------------------------------------------------------------------------------------|:------------------------------|:---------------------------------------------------------|:--------------------------------------------------------------------------------------|
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/rdom-canvas-basics.jpg" width="240"/> | Minimal rdom-canvas animation | [Demo](https://demo.thi.ng/umbrella/rdom-canvas-basics/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/rdom-canvas-basics) |
+
 ## API
 
 [Generated API docs](https://docs.thi.ng/umbrella/compose/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/compose",
-  "version": "2.1.40",
+  "version": "2.1.41",
   "description": "Optimized functional composition helpers",
   "type": "module",
   "module": "./index.js",
@@ -105,5 +105,5 @@
       "default": "./trampoline.js"
     }
   },
-  "gitHead": "5929dd20497668496af13415cdf784a4d6f69aa3\n"
+  "gitHead": "9dec130cc636c1da0bc4f2baa0d995579d3b7629\n"
 }

package/thread-first.d.ts

@@ -1,9 +1,15 @@
 import type { FnAny } from "@thi.ng/api";
 /**
- * Takes an `init` value and a number of functions and/or function
- * tuples, consisting of: `[fn, ...args]`. Executes each function
- * (or tuple) with the return value of the previous expression inserted
- * as first argument, using `init` for the first expression.
+ * Similar to {@link threadLast}. A dataflow operator to improve the legibility
+ * of long (or deeply nested) call expressions. Takes an `init` value and a
+ * number of functions and/or function tuples, consisting of: `[fn, ...args]`.
+ * Executes each function (or tuple) with the return value of the previous
+ * step/function inserted as **first** argument, using `init` as the first
+ * expression. Returns result of last function/step given.
+ *
+ * @remarks
+ * This operator allows the code to be read more easily in the order of
+ * execution (same as the `->` operator/macro in Clojure).
  *
  * @example
  * ```ts
@@ -11,18 +17,21 @@ import type { FnAny } from "@thi.ng/api";
  * const sub = (a, b) => a - b;
  * const div = (a, b) => a / b;
  *
+ * // without operator: (-5 - 10) / 20
+ * console.log(div(sub(neg(5), 10), 20));
+ * // -0.75
+ *
+ * // rewritten using operator:
  * threadFirst(
  *   5,
  *   neg,       // -5
- *   [sub, 20], // -5 - 20 = -25
- *   [div, 10]  // -25 / 10 = -2.5
+ *   [sub, 10], // (-5) - 10
+ *   [div, 20], // (-5 - 10) / 20
+ *   console.log
  * );
- *
- * // -2.5
+ * // -0.75
  * ```
  *
- * {@link threadLast}
- *
  * @param init - start value
  * @param fns - functions / S-expressions
  */

package/thread-first.js

@@ -1,8 +1,14 @@
 /**
- * Takes an `init` value and a number of functions and/or function
- * tuples, consisting of: `[fn, ...args]`. Executes each function
- * (or tuple) with the return value of the previous expression inserted
- * as first argument, using `init` for the first expression.
+ * Similar to {@link threadLast}. A dataflow operator to improve the legibility
+ * of long (or deeply nested) call expressions. Takes an `init` value and a
+ * number of functions and/or function tuples, consisting of: `[fn, ...args]`.
+ * Executes each function (or tuple) with the return value of the previous
+ * step/function inserted as **first** argument, using `init` as the first
+ * expression. Returns result of last function/step given.
+ *
+ * @remarks
+ * This operator allows the code to be read more easily in the order of
+ * execution (same as the `->` operator/macro in Clojure).
  *
  * @example
  * ```ts
@@ -10,18 +16,21 @@
  * const sub = (a, b) => a - b;
  * const div = (a, b) => a / b;
  *
+ * // without operator: (-5 - 10) / 20
+ * console.log(div(sub(neg(5), 10), 20));
+ * // -0.75
+ *
+ * // rewritten using operator:
  * threadFirst(
  *   5,
  *   neg,       // -5
- *   [sub, 20], // -5 - 20 = -25
- *   [div, 10]  // -25 / 10 = -2.5
+ *   [sub, 10], // (-5) - 10
+ *   [div, 20], // (-5 - 10) / 20
+ *   console.log
  * );
- *
- * // -2.5
+ * // -0.75
  * ```
  *
- * {@link threadLast}
- *
  * @param init - start value
  * @param fns - functions / S-expressions
  */

package/thread-last.d.ts

@@ -1,9 +1,15 @@
 import type { FnAny } from "@thi.ng/api";
 /**
- * Takes an `init` value and a number of functions and/or function
- * tuples, consisting of: `[fn, ...args]`. Executes each function
- * (or tuple) with the return value of the previous expression inserted
- * as last argument, using `init` for the first expression.
+ * Similar to {@link threadFirst}. A dataflow operator to improve the legibility
+ * of long (or deeply nested) call expressions. Takes an `init` value and a
+ * number of functions and/or function tuples, consisting of: `[fn, ...args]`.
+ * Executes each function (or tuple) with the return value of the previous
+ * step/function inserted as **last** argument, using `init` as the first
+ * expression. Returns result of last function/step given.
+ *
+ * @remarks
+ * This operator allows the code to be read more easily in the order of
+ * execution (same as the `->>` operator/macro in Clojure).
  *
  * @example
  * ```ts
@@ -11,18 +17,21 @@ import type { FnAny } from "@thi.ng/api";
  * const sub = (a, b) => a - b;
  * const div = (a, b) => a / b;
  *
+ * // without operator: 20 / (10 - (-5))
+ * console.log(div(20, sub(10, neg(5))));
+ * // 1.3333333333333333
+ *
+ * // rewritten using operator:
  * threadLast(
  *   5,
  *   neg,       // -5
- *   [sub, 10], // 20 - (-5) = 25
- *   [div, 10]  // 10 / 25 = 0.4
+ *   [sub, 10], // 10 - (-5)
+ *   [div, 20],  // 20 / (10 - (-5))
+ *   console.log
  * );
- *
- * // 0.4
+ * // 1.3333333333333333
  * ```
  *
- * {@link threadFirst}
- *
  * @param init - start value
  * @param fns - functions / S-expressions
  */

package/thread-last.js

@@ -1,8 +1,14 @@
 /**
- * Takes an `init` value and a number of functions and/or function
- * tuples, consisting of: `[fn, ...args]`. Executes each function
- * (or tuple) with the return value of the previous expression inserted
- * as last argument, using `init` for the first expression.
+ * Similar to {@link threadFirst}. A dataflow operator to improve the legibility
+ * of long (or deeply nested) call expressions. Takes an `init` value and a
+ * number of functions and/or function tuples, consisting of: `[fn, ...args]`.
+ * Executes each function (or tuple) with the return value of the previous
+ * step/function inserted as **last** argument, using `init` as the first
+ * expression. Returns result of last function/step given.
+ *
+ * @remarks
+ * This operator allows the code to be read more easily in the order of
+ * execution (same as the `->>` operator/macro in Clojure).
  *
  * @example
  * ```ts
@@ -10,18 +16,21 @@
  * const sub = (a, b) => a - b;
  * const div = (a, b) => a / b;
  *
+ * // without operator: 20 / (10 - (-5))
+ * console.log(div(20, sub(10, neg(5))));
+ * // 1.3333333333333333
+ *
+ * // rewritten using operator:
  * threadLast(
  *   5,
  *   neg,       // -5
- *   [sub, 10], // 20 - (-5) = 25
- *   [div, 10]  // 10 / 25 = 0.4
+ *   [sub, 10], // 10 - (-5)
+ *   [div, 20],  // 20 / (10 - (-5))
+ *   console.log
  * );
- *
- * // 0.4
+ * // 1.3333333333333333
  * ```
  *
- * {@link threadFirst}
- *
  * @param init - start value
  * @param fns - functions / S-expressions
  */