@thi.ng/pointfree 3.1.69 → 3.1.71

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-02-25T14:07:53Z
+- **Last updated**: 2024-03-02T14:05:52Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.

package/README.md

@@ -1,16 +1,5 @@
 <!-- This file is generated - DO NOT EDIT! -->
 <!-- Please see: https://github.com/thi-ng/umbrella/blob/develop/CONTRIBUTING.md#changes-to-readme-files -->
-> [!IMPORTANT]
-> ‼️ Announcing the thi.ng user survey 2024 📋
->
-> [Please participate in the survey here!](https://forms.gle/XacbSDEmQMPZg8197)\
-> (open until end of February)
->
-> **To achieve a better sample size, I'd highly appreciate if you could
-> circulate the link to this survey in your own networks.**
->
-> [Discussion](https://github.com/thi-ng/umbrella/discussions/447)
-
 # ![@thi.ng/pointfree](https://media.thi.ng/umbrella/banners-20230807/thing-pointfree.svg?f42a1008)
 
 [![npm version](https://img.shields.io/npm/v/@thi.ng/pointfree.svg)](https://www.npmjs.com/package/@thi.ng/pointfree)
@@ -22,7 +11,7 @@
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
-> 🚀 Help me to work full-time on these projects by [sponsoring me on
+> 🚀 Please help me to work full-time on these projects by [sponsoring me on
 > GitHub](https://github.com/sponsors/postspectacular). Thank you! ❤️
 
 - [About](#about)
@@ -144,6 +133,8 @@ ported from [Factor](http://factorcode.org) and
 (details explained further below)
 
 ```ts
+import * as pf from "@thi.ng/pointfree";
+
 // define word to compute dot product of two vectors
 const dotp = pf.word([pf.vmul, [pf.add], 0, pf.foldl]);
 // another word to normalize a vector (uses `dotp`)
@@ -282,7 +273,9 @@ on the stack as is. Therefore, a stack program like: `[1, 2, pf.add]`
 compiles to:
 
 ```ts
-pf.add(pf.push(2)(pf.push(1)(<initial context>)))
+import * as pf from "@thi.ng/pointfree";
+
+pf.add(pf.push(2)(pf.push(1)(/* <initial context> */)))
 ```
 
 #### About stack effects
@@ -316,6 +309,8 @@ section of the result stack. This is merely syntax sugar and we use this
 for some of the examples below.
 
 ```ts
+import * as pf from "@thi.ng/pointfree";
+
 // calculate (1 + 2 + 3) * 10
 pf.run(
     // a pointfree stack program w/ stack effects
@@ -343,6 +338,8 @@ value(s) from result context.
 stack programs. Their use case is purely standalone application.
 
 ```ts
+import * as pf from "@thi.ng/pointfree";
+
 // define new word to compute multiply-add:
 // ( x y z -- x*y+z )
 const madd = pf.word([pf.invrot, pf.mul, pf.add]);
@@ -367,6 +364,8 @@ smaller re-usable units, words, quotations. These often extremely small
 words can be much easier tested and reused.
 
 ```ts
+import * as pf from "@thi.ng/pointfree";
+
 // compute square of x
 // ( x -- x*x )
 const pow2 = pf.word([pf.dup, pf.mul]);
@@ -402,6 +401,8 @@ execution. Quotations can be nested, composed and are executed via
 This example uses a quoted form of the above `pow2` word:
 
 ```ts
+import * as pf from "@thi.ng/pointfree";
+
 pf.runU(
     [
         // push quotation on stack
@@ -425,6 +426,8 @@ all other values in the quotation are passed as arguments. The result of
 the function call is placed back on the stack.
 
 ```ts
+import * as pf from "@thi.ng/pointfree";
+
 pf.runU(
     [
         [(a,b) => a + b, 1, 2],
@@ -441,6 +444,8 @@ functional composition of two quotations is the same as concatenating
 two arrays**:
 
 ```js
+import * as pf from "@thi.ng/pointfree";
+
 const add10 = [10, pf.add];
 const mul10 = [10, pf.mul];
 
@@ -458,6 +463,8 @@ Also see [the section about combinators](#dataflow-combinators) for more
 advanced options.
 
 ```ts
+import * as pf from "@thi.ng/pointfree";
+
 // build & execute curried quotation
 pf.run([10, [pf.add], pf.pushl, pf.exec], [[13]]);
 // 23
@@ -467,6 +474,8 @@ Furthermore, the ES6 spread operator can be used to dissolve a quotation
 in a larger word/program (i.e. as a form of inlining code).
 
 ```ts
+import * as pf from "@thi.ng/pointfree";
+
 // a quotation is just an array of values/words
 // this function is a quotation generator
 const tupleQ = (n) => [n, pf.collect];
@@ -509,6 +518,8 @@ restores them again after. Most other combinators are internally built
 on `dip` and/or `keep`.
 
 ```ts
+import * as pf from "@thi.ng/pointfree";
+
 // remove `20` before executing quot, then restores after
 // with the effect of apply qout to 2nd topmost value (here: 10)
 pf.run([10, 20, [pf.inc], pf.dip])[0]
@@ -527,6 +538,8 @@ Calls a quotation with a value on the d-stack, restoring the value after
 quotation finished.
 
 ```ts
+import * as pf from "@thi.ng/pointfree";
+
 // here `add` would normally consume two stack values
 // but `keep2` restores them again after the quot has run
 pf.run([1, 2, [pf.add], pf.keep2])[0]
@@ -542,6 +555,8 @@ pf.run([1, 2, [pf.add], pf.keep2])[0]
 value, then applies second quot to the same value.
 
 ```ts
+import * as pf from "@thi.ng/pointfree";
+
 pf.run([2, [10, pf.add], [10, pf.mul], pf.bi])[0]
 // [12, 20]
 
@@ -553,6 +568,8 @@ pf.run([2, 10, 100, [pf.add, pf.add], [pf.mul, pf.mul], pf.bi3])[0]
 `tri` takes 3 quotations, else same as `bi`:
 
 ```ts
+import * as pf from "@thi.ng/pointfree";
+
 pf.run([10, [pf.dec], [pf.dup, pf.mul], [pf.inc], pf.tri])[0]
 // [9, 100, 11]
 ```
@@ -567,6 +584,8 @@ pf.run([10, [pf.dec], [pf.dup, pf.mul], [pf.inc], pf.tri])[0]
 ( x y p q -- px qy )
 
 ```ts
+import * as pf from "@thi.ng/pointfree";
+
 pf.run([10, 20, [pf.inc], [pf.dec], pf.bis])[0]
 // [11, 19]
 
@@ -586,6 +605,8 @@ Applies the quotation `q` to `x`, then to `y`.
 ( x y q -- qx qy )
 
 ```ts
+import * as pf from "@thi.ng/pointfree";
+
 pf.run([10, 20, [pf.inc], pf.bia])[0]
 // [11, 21]
 
@@ -611,6 +632,8 @@ produce a result array (only flat results pushed on stack), whereas
 value on the stack and applies quotation for each.
 
 ```ts
+import * as pf from "@thi.ng/pointfree";
+
 // multiply each array item * 10
 pf.runU([[1, 2, 3, 4], [10, pf.mul], pf.mapll]);
 // [ 10, 20, 30, 40 ]
@@ -654,13 +677,17 @@ object back on stack at the end. Throws error if there're less remaining
 stack values than keys in given array.
 
 ```ts
-runU([1, 2, 3, ["a","b","c"], {}, bindkeys])
+import * as pf from "@thi.ng/pointfree";
+
+pf.runU([1, 2, 3, ["a","b","c"], {}, pf.bindkeys])
 // { c: 3, b: 2, a: 1 }
 ```
 
 #### Combine array transform op with deeper stack values
 
 ```ts
+import * as pf from "@thi.ng/pointfree";
+
 // helper word to extract a 8bit range from a 32bit int
 // `x` is the orig number, `s` bit shift amount
 // ( x s -- x byte )
@@ -688,6 +715,8 @@ splitBytes([[0xdecafbad]]);
 See `cond` documentation further below...
 
 ```ts
+import * as pf from "@thi.ng/pointfree";
+
 // negate TOS item ONLY if negative, else do nothing
 const abs = pf.wordU([pf.dup, pf.isneg, pf.cond(pf.neg)]);
 
@@ -701,6 +730,8 @@ abs([42])
 ```
 
 ```ts
+import * as pf from "@thi.ng/pointfree";
+
 // `cases()` is similar to JS `switch() { case ... }`
 const classify = (x) =>
     pf.unwrap(
@@ -731,6 +762,8 @@ as test produces a truthy result. There's also `loopq` which reads its
 arguments (same as `loop`) from the stack.
 
 ```ts
+import * as pf from "@thi.ng/pointfree";
+
 // print countdown from 3
 pf.run(
     [
@@ -754,6 +787,8 @@ counter based iterations. Like `loopq` it's not an higher-order word and
 works with a body quotation, which is executed `n` times.
 
 ```ts
+import * as pf from "@thi.ng/pointfree";
+
 pf.run([3, ["counter: ", pf.swap, pf.add, pf.print], pf.dotimes])
 // counter: 0
 // counter: 1
@@ -764,6 +799,8 @@ pf.run([3, ["counter: ", pf.swap, pf.add, pf.print], pf.dotimes])
 looping constructs:
 
 ```ts
+import * as pf from "@thi.ng/pointfree";
+
 // 2D range/grid loop
 //
 // (cols rows body -- ? )
@@ -818,6 +855,8 @@ several words available for moving data between main ("D-stack") and the
 r-stack and to manipulate the structure of the R-stack itself.
 
 ```ts
+import * as pf from "@thi.ng/pointfree";
+
 // this example partitions the main stack into triples
 
 // helper word to check if there're values on d-stack
@@ -1047,6 +1086,8 @@ body within an implicit `try .. catch` and if an error was thrown pushes
 it on stack and executes error quotation.
 
 ```ts
+import * as pf from "@thi.ng/pointfree";
+
 pf.runU([
     // body quotation
     [pf.div],

package/array.d.ts

@@ -11,7 +11,9 @@ import type { StackContext, StackFn } from "./api.js";
  *
  * Compare:
  *
- * ```
+ * ```js
+ * import * as pf from "@thi.ng/pointfree";
+ *
  * // using array literal within word definition
  * foo = pf.word([ [], 1, pf.pushl ])
  * pf.runU(foo)
@@ -108,7 +110,9 @@ export declare const catr: (ctx: StackContext) => StackContext;
  * any number of results and therefore also be used as filter, mapcat,
  * reduce...
  *
- * ```
+ * ```js
+ * import { mapl, mul, run } from "@thi.ng/pointfree";
+ *
  * // each item times 10
  * run([[1, 2, 3, 4], [10, mul], mapl])
  * // [ [ 10, 20, 30, 40 ], [], {} ]
@@ -116,7 +120,9 @@ export declare const catr: (ctx: StackContext) => StackContext;
  *
  * Use for filtering:
  *
- * ```
+ * ```js
+ * import { cond, drop, dup, even, mapl, run } from "@thi.ng/pointfree";
+ *
  * // drop even numbers, duplicate odd ones
  * run([[1, 2, 3, 4], [dup, even, cond(drop, dup)], mapl])
  * // [ [ 1, 1, 3, 3 ], [], {} ]
@@ -124,7 +130,9 @@ export declare const catr: (ctx: StackContext) => StackContext;
  *
  * Reduction:
  *
- * ```
+ * ```js
+ * import { add, mapl, runU } from "@thi.ng/pointfree";
+ *
  * // the `0` is the initial reduction result
  * runU([0, [1, 2, 3, 4], [add], mapl])
  * // 10
@@ -136,7 +144,7 @@ export declare const catr: (ctx: StackContext) => StackContext;
  * Use {@link mapll} to transform:
  *
  * @example
- * ```ts
+ * ```js
  * import { runU, mapll, mul } from "@thi.ng/pointfree";
  *
  * runU([[1, 2, 3, 4], [10, mul], mapll])
@@ -148,7 +156,7 @@ export declare const catr: (ctx: StackContext) => StackContext;
  * interim value into the result:
  *
  * @example
- * ```ts
+ * ```js
  * import { list, mapl, mul, pushr, runU } from "@thi.ng/pointfree";
  *
  * runU([list, [1, 2, 3, 4], [10, mul, pushr], mapl])
@@ -158,7 +166,7 @@ export declare const catr: (ctx: StackContext) => StackContext;
  * If the array size is known & not changed by transformation:
  *
  * @example
- * ```ts
+ * ```js
  * import { collect, mapl, mul, runU } from "@thi.ng/pointfree";
  *
  * runU([[1, 2, 3, 4], [10, mul], mapl, 4, collect])
@@ -174,7 +182,7 @@ export declare const mapl: (ctx: StackContext) => StackContext;
  * ( arr q -- arr )
  *
  * @example
- * ```ts
+ * ```js
  * import { mapll, mul, runU } from "@thi.ng/pointfree";
  *
  * runU([[1, 2, 3, 4], [10, mul], mapll])
@@ -183,7 +191,9 @@ export declare const mapl: (ctx: StackContext) => StackContext;
  *
  * Filter / mapcat:
  *
- * ```
+ * ```js
+ * import { cond, drop, dup, even, mapll, run } from "@thi.ng/pointfree";
+ *
  * // drop even numbers, duplicate odd ones
  * run([[1, 2, 3, 4], [dup, even, cond(drop, dup)], mapll])
  * // [ [ [ 1, 1, 3, 3 ] ], [], {} ]
@@ -267,7 +277,7 @@ export declare const setat: (ctx: StackContext) => StackContext;
  * keys in given array.
  *
  * @example
- * ```ts
+ * ```js
  * import { bindkeys, runU } from "@thi.ng/pointfree";
  *
  * runU([1,2,3, ["a","b","c"], {}, bindkeys])

package/loop.d.ts

@@ -6,8 +6,8 @@ import type { StackContext, StackProc } from "./api.js";
  * ( -- ? )
  *
  * @example
- * ```ts
- * import { dec, dup, ispos, print, runU } from "@thi.ng/pointfree";
+ * ```js
+ * import { dec, dup, ispos, print, run } from "@thi.ng/pointfree";
  *
  * run([loop([dup, ispos], [dup, print, dec])], [[3]])
  * // 3
@@ -15,6 +15,7 @@ import type { StackContext, StackProc } from "./api.js";
  * // 1
  * // [ true, [ 0 ], undefined ]
  * ```
+ *
  * @param test -
  * @param body -
  */
@@ -33,7 +34,7 @@ export declare const loopq: (ctx: StackContext) => StackContext;
  * pushes current counter on d-stack prior to executing body.
  *
  * @example
- * ```ts
+ * ```js
  * import { add, print, swap, runU } from "@thi.ng/pointfree";
  *
  * run([3, ["i=", swap, add, print], dotimes])
@@ -44,8 +45,8 @@ export declare const loopq: (ctx: StackContext) => StackContext;
  *
  * With empty body acts as finite range generator 0 .. n:
  *
- * ```ts
- * import { collect, cpdr, dotimes, movrd, runU } from "@thi.ng/pointfree";
+ * ```js
+ * import { collect, cpdr, dotimes, movrd, run, runU } from "@thi.ng/pointfree";
  *
  * // range gen
  * run([3, [], dotimes])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/pointfree",
-  "version": "3.1.69",
+  "version": "3.1.71",
   "description": "Pointfree functional composition / Forth style stack execution engine",
   "type": "module",
   "module": "./index.js",
@@ -35,11 +35,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.9.26",
-    "@thi.ng/checks": "^3.5.0",
-    "@thi.ng/compose": "^2.1.65",
-    "@thi.ng/equiv": "^2.1.49",
-    "@thi.ng/errors": "^2.4.18"
+    "@thi.ng/api": "^8.9.27",
+    "@thi.ng/checks": "^3.5.1",
+    "@thi.ng/compose": "^2.1.66",
+    "@thi.ng/equiv": "^2.1.50",
+    "@thi.ng/errors": "^2.4.19"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.40.1",
@@ -132,5 +132,5 @@
   "thi.ng": {
     "year": 2015
   },
-  "gitHead": "6e20f80dd9df1c8055ffa3c1e4d6f7598add0c0b\n"
+  "gitHead": "df9e312af741d87e6b450afcfea6a6e381662b1e\n"
 }