@thi.ng/transducers-async 0.2.22 → 0.3.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-10-05T12:12:32Z
+- **Last updated**: 2024-10-14T19:58:28Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,14 @@ 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.
 
+## [0.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/transducers-async@0.3.0) (2024-10-14)
+
+#### 🚀 Features
+
+- add intercept() transducer ([8d87215](https://github.com/thi-ng/umbrella/commit/8d87215))
+  - add tests & docs
+  - update pkg exports
+
 ### [0.2.6](https://github.com/thi-ng/umbrella/tree/@thi.ng/transducers-async@0.2.6) (2024-06-21)
 
 #### ♻️ Refactoring

package/README.md

@@ -116,7 +116,7 @@ For Node.js REPL:
 const txa = await import("@thi.ng/transducers-async");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 3.11 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 3.20 KB
 
 ## Dependencies
 

package/index.d.ts

@@ -8,6 +8,7 @@ export * from "./delayed.js";
 export * from "./ensure.js";
 export * from "./events.js";
 export * from "./filter.js";
+export * from "./intercept.js";
 export * from "./iterator.js";
 export * from "./map.js";
 export * from "./mapcat.js";

package/index.js

@@ -8,6 +8,7 @@ export * from "./delayed.js";
 export * from "./ensure.js";
 export * from "./events.js";
 export * from "./filter.js";
+export * from "./intercept.js";
 export * from "./iterator.js";
 export * from "./map.js";
 export * from "./mapcat.js";

package/intercept.d.ts

@@ -0,0 +1,68 @@
+import type { Fn, MaybeAsyncIterable, MaybePromise, Nullable } from "@thi.ng/api";
+import type { AsyncTransducer } from "./api.js";
+export type Interceptor<T> = Fn<T, MaybePromise<Nullable<T>>>;
+export interface AsyncInterceptor<T> extends AsyncTransducer<T, T> {
+    /**
+     * Adds given interceptor function to the beginning of the list of interceptors.
+     *
+     * @param pred
+     */
+    prepend(pred: Interceptor<T>): void;
+    /**
+     * Adds given interceptor function to the end of the list of interceptors.
+     *
+     * @param pred
+     */
+    append(pred: Interceptor<T>): void;
+    /**
+     * Removes interceptor from list of interceptors and returns true if
+     * successful.
+     *
+     * @param pred
+     */
+    remove(pred: Interceptor<T>): boolean;
+}
+/**
+ * Async transducer. Applies a (dynamically changeable) list of interceptor
+ * functions to augment/transform incoming values, or drop them entirely.
+ *
+ * @remarks
+ * Interceptor functions are always applied in series to each received value.
+ * Each interceptor can stop processing of a value by returning `null` or
+ * `undefined`, otherwise the function is free to augment/transform the value
+ * (but keeping its type) and the result is used as input for the next
+ * interceptor, and eventually as result of the entire transducer function.
+ *
+ * If `intercept()` is called without source iterable and returns an transducer,
+ * interceptor functions can be dynamically added or removed via the exposed
+ * functions in {@link AsyncInterceptor}.
+ *
+ * @example
+ * ```ts tangle:../export/intercept.ts
+ * import { intercept, iterator } from "@thi.ng/transducers-async";
+ *
+ * // tag-based inference
+ * const xform = intercept<string[]>([
+ *   // add an "untitled" tag, if needed
+ *   (tags) => !tags.find(x => /^title:/.test(x)) ? [...tags, "untitled"] : tags,
+ * ]);
+ *
+ * // dynamically add a second interceptor to skip items if they're tagged with "temp"
+ * // using .prepend() here to avoid extraneous processing
+ * xform.prepend((tags) => tags.includes("temp") ? null : tags);
+ *
+ * const items = [
+ *   ["photo1", "title:test"],
+ *   ["photo2"],
+ *   ["photo3", "temp"],
+ * ];
+ *
+ * // process inputs and display results
+ * for await(let tags of iterator(xform, items)) console.log(tags);
+ * ```
+ *
+ * @param interceptors
+ */
+export declare function intercept<T>(interceptors?: Interceptor<T>[]): AsyncInterceptor<T>;
+export declare function intercept<T>(interceptors: Interceptor<T>[], src: MaybeAsyncIterable<T>): AsyncIterableIterator<T>;
+//# sourceMappingURL=intercept.d.ts.map

package/intercept.js

@@ -0,0 +1,31 @@
+import { compR } from "./compr.js";
+import { iterator1 } from "./iterator.js";
+function intercept(interceptors = [], src) {
+  if (src) return iterator1(intercept(interceptors), src);
+  const xform = (rfn) => compR(rfn, async (acc, x) => {
+    for (let fn of interceptors) {
+      const res = await fn(x);
+      if (res == null) return acc;
+      x = res;
+    }
+    return rfn[2](acc, x);
+  });
+  xform.prepend = (fn) => {
+    interceptors.unshift(fn);
+  };
+  xform.append = (fn) => {
+    interceptors.push(fn);
+  };
+  xform.remove = (fn) => {
+    const idx = interceptors.indexOf(fn);
+    if (idx >= 0) {
+      interceptors.splice(idx, 1);
+      return true;
+    }
+    return false;
+  };
+  return xform;
+}
+export {
+  intercept
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/transducers-async",
-  "version": "0.2.22",
+  "version": "0.3.1",
   "description": "Async versions of various highly composable transducers, reducers and iterators",
   "type": "module",
   "module": "./index.js",
@@ -41,7 +41,7 @@
     "@thi.ng/checks": "^3.6.13",
     "@thi.ng/compose": "^3.0.14",
     "@thi.ng/errors": "^2.5.17",
-    "@thi.ng/transducers": "^9.2.6"
+    "@thi.ng/transducers": "^9.2.7"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.47.9",
@@ -118,6 +118,9 @@
     "./filter": {
       "default": "./filter.js"
     },
+    "./intercept": {
+      "default": "./intercept.js"
+    },
     "./iterator": {
       "default": "./iterator.js"
     },
@@ -205,5 +208,5 @@
     "status": "alpha",
     "year": 2018
   },
-  "gitHead": "241df2019d93359c34da1a11a94e416b6ea73f32\n"
+  "gitHead": "8301254c4436505a1fb0e3cc28eca3adb920c3e0\n"
 }