@effectionx/stream-helpers 0.4.1 → 0.6.0

package/package.json

@@ -1,36 +1,42 @@
 {
   "name": "@effectionx/stream-helpers",
-  "version": "0.4.1",
+  "version": "0.6.0",
+  "type": "module",
+  "main": "./dist/mod.js",
+  "types": "./dist/mod.d.ts",
+  "exports": {
+    ".": {
+      "development": "./mod.ts",
+      "default": "./dist/mod.js"
+    },
+    "./test-helpers": {
+      "development": "./test-helpers.ts",
+      "default": "./dist/test-helpers.js"
+    }
+  },
+  "peerDependencies": {
+    "effection": "^3 || ^4"
+  },
+  "dependencies": {
+    "@effectionx/signals": "workspace:*",
+    "@effectionx/timebox": "workspace:*",
+    "immutable": "^5",
+    "remeda": "^2"
+  },
+  "license": "MIT",
   "author": "engineering@frontside.com",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/thefrontside/effectionx.git"
   },
-  "license": "MIT",
   "bugs": {
     "url": "https://github.com/thefrontside/effectionx/issues"
   },
-  "main": "./script/mod.js",
-  "module": "./esm/mod.js",
-  "exports": {
-    ".": {
-      "import": "./esm/mod.js",
-      "require": "./script/mod.js"
-    },
-    "./test-helpers": {
-      "import": "./esm/test-helpers.js",
-      "require": "./script/test-helpers.js"
-    }
-  },
-  "scripts": {},
   "engines": {
-    "node": ">= 16"
+    "node": ">= 22"
   },
   "sideEffects": false,
-  "dependencies": {
-    "@effectionx/signals": "^0.4.0",
-    "@effectionx/timebox": "^0.3.0",
-    "effection": "^3 || ^4.0.0-0"
-  },
-  "_generatedBy": "dnt@dev"
-}
+  "devDependencies": {
+    "@effectionx/bdd": "workspace:*"
+  }
+}

package/subject.test.ts

@@ -0,0 +1,93 @@
+import {
+  createChannel,
+  type Operation,
+  type Stream,
+  type Subscription,
+} from "effection";
+import { beforeEach, describe, it } from "@effectionx/bdd";
+import { expect } from "expect";
+
+import { createSubject } from "./subject.ts";
+
+function* next<T, TClose>(
+  subscription: Subscription<T, TClose>,
+): Operation<T | TClose> {
+  const item = yield* subscription.next();
+  if (item.done) {
+    return item.value;
+  }
+  return item.value;
+}
+
+describe("subject", () => {
+  let subject = createSubject<number>();
+  let upstream = createChannel<number, string>();
+  let downstream: Stream<number, string>;
+
+  beforeEach(function* () {
+    subject = createSubject();
+
+    upstream = createChannel();
+
+    downstream = subject(upstream);
+  });
+
+  it("allows multiple subscribers", function* () {
+    const subscriber1 = yield* downstream;
+    const subscriber2 = yield* downstream;
+
+    yield* upstream.send(1);
+    yield* upstream.send(2);
+
+    // 1 multicast to both
+    expect(yield* next(subscriber1)).toEqual(1);
+    expect(yield* next(subscriber2)).toEqual(1);
+
+    // 2 multicast to both
+    expect(yield* next(subscriber1)).toEqual(2);
+    expect(yield* next(subscriber2)).toEqual(2);
+  });
+
+  it("each later subscribers get latest value", function* () {
+    const subscriber1 = yield* downstream;
+    yield* upstream.send(1);
+    expect(yield* next(subscriber1)).toEqual(1);
+
+    yield* upstream.send(2);
+    expect(yield* next(subscriber1)).toEqual(2);
+
+    const subscriber2 = yield* downstream;
+    expect(yield* next(subscriber2)).toEqual(2);
+  });
+
+  it("sends closing value to all subscribers", function* () {
+    const subscriber1 = yield* downstream;
+    const subscriber2 = yield* downstream;
+
+    yield* upstream.send(1);
+    yield* upstream.close("bye");
+
+    // 1 multicast to both
+    expect(yield* next(subscriber1)).toEqual(1);
+    expect(yield* next(subscriber2)).toEqual(1);
+
+    // 2 multicast to both
+    expect(yield* next(subscriber1)).toEqual("bye");
+    expect(yield* next(subscriber2)).toEqual("bye");
+  });
+
+  it("subscriber after close receives last value and close value", function* () {
+    const subscriber1 = yield* downstream;
+
+    yield* upstream.send(1);
+    yield* upstream.close("bye");
+
+    // First subscriber gets value and close
+    expect(yield* next(subscriber1)).toEqual(1);
+    expect(yield* next(subscriber1)).toEqual("bye");
+
+    // Late subscriber after close should get last value and close value
+    const subscriber2 = yield* downstream;
+    expect(yield* next(subscriber2)).toEqual("bye");
+  });
+});

package/subject.ts

@@ -0,0 +1,67 @@
+import type { Stream, Subscription } from "effection";
+
+/**
+ * Converts any stream into a multicast stream that produces latest value
+ * to new subscribers. It's designed to be analagous in function to [RxJS
+ * BehaviorSubject](https://www.learnrxjs.io/learn-rxjs/subjects/behaviorsubject).
+ *
+ * @returns A function that takes a stream and returns a multicast stream
+ *
+ * @example
+ * ```ts
+ * const subject = createSubject<number>();
+ * const downstream = subject(upstream);
+ *
+ * const sub1 = yield* downstream; // subscribes to upstream
+ * yield* upstream.send(1);
+ * yield* sub1.next(); // { done: false, value: 1 }
+ *
+ * const sub2 = yield* downstream; // late subscriber
+ * yield* sub2.next(); // { done: false, value: 1 } - gets latest value
+ * ```
+ *
+ * Use it with a pipe operator to convert any stream into a behavior subject.
+ *
+ * @example
+ * ```
+ * let source = createChannel<string, void>();
+ * let subject = createSubject<string>();
+ *
+ * let pipeline = pipe([
+ *  top,
+ *  transform1,
+ *  transform2,
+ *  subject,
+ * ]);
+ * ```
+ */
+export function createSubject<T>(): <TClose>(
+  stream: Stream<T, TClose>,
+) => Stream<T, TClose> {
+  let current: IteratorResult<T> | undefined = undefined;
+
+  return <TClose>(stream: Stream<T, TClose>) => ({
+    *[Symbol.iterator]() {
+      let upstream = yield* stream;
+
+      let iterator: Subscription<T, TClose> = current
+        ? {
+            *next() {
+              iterator = upstream;
+              // biome-ignore lint/style/noNonNullAssertion: current checked in ternary condition
+              return current!;
+            },
+          }
+        : {
+            *next() {
+              current = yield* upstream.next();
+              return current;
+            },
+          };
+
+      return {
+        next: () => iterator.next(),
+      };
+    },
+  });
+}

package/test-helpers/faucet.test.ts

@@ -0,0 +1,120 @@
+import { describe, it } from "@effectionx/bdd";
+import { createArraySignal, is } from "@effectionx/signals";
+import { expect } from "expect";
+import { each, race, sleep, spawn } from "effection";
+
+import { useFaucet } from "./faucet.ts";
+
+describe("useFaucet", () => {
+  it("creates a faucet that can pour items", function* () {
+    const faucet = yield* useFaucet<number>({ open: true });
+    const results = yield* createArraySignal<number>([]);
+
+    // Spawn a subscription to the faucet
+    yield* spawn(function* () {
+      for (const item of yield* each(faucet)) {
+        results.push(item);
+        yield* each.next();
+      }
+    });
+
+    yield* spawn(function* () {
+      yield* sleep(1);
+      // Pour an array of items
+      yield* faucet.pour([1, 2, 3]);
+    });
+
+    // Wait for processing
+    yield* is(results, (results) => results.length === 3);
+
+    expect(results.valueOf()).toEqual([1, 2, 3]);
+  });
+
+  it("respects the open state", function* () {
+    expect.assertions(2);
+    const faucet = yield* useFaucet<number>({ open: false });
+    const results = yield* createArraySignal<number>([]);
+
+    // Spawn a subscription to the faucet
+    yield* spawn(function* () {
+      for (const item of yield* each(faucet)) {
+        results.push(item);
+        yield* each.next();
+      }
+    });
+
+    // Try to pour while closed, give it a timeout to avoid it getting stuck
+    yield* race([faucet.pour([1, 2, 3]), sleep(1)]);
+
+    expect(results.valueOf()).toEqual([]);
+
+    faucet.open();
+
+    yield* faucet.pour([4, 5, 6]);
+
+    yield* is(results, (results) => results.length === 3);
+
+    expect(results.valueOf()).toEqual([4, 5, 6]);
+  });
+
+  it("supports pouring with an operation", function* () {
+    const faucet = yield* useFaucet<number>({ open: true });
+    const results = yield* createArraySignal<number>([]);
+
+    // Spawn a subscription to the faucet
+    yield* spawn(function* () {
+      for (const item of yield* each(faucet)) {
+        results.push(item);
+        yield* each.next();
+      }
+    });
+
+    // Pour using a generator function
+    yield* spawn(function* () {
+      yield* sleep(1);
+      yield* faucet.pour(function* (send) {
+        yield* send(1);
+        yield* sleep(10);
+        yield* send(2);
+        yield* sleep(10);
+        yield* send(3);
+      });
+    });
+
+    yield* is(results, (results) => results.length === 3);
+
+    expect(results.valueOf()).toEqual([1, 2, 3]);
+  });
+
+  it("stops pouring when closed", function* () {
+    const faucet = yield* useFaucet<number>({ open: true });
+    const results = yield* createArraySignal<number>([]);
+
+    // Spawn a subscription to the faucet
+    yield* spawn(function* () {
+      for (const item of yield* each(faucet)) {
+        results.push(item);
+        yield* each.next();
+      }
+    });
+
+    // Start pouring with a generator
+    yield* spawn(function* () {
+      yield* sleep(1);
+      yield* faucet.pour(function* (send) {
+        yield* send(1);
+        yield* sleep(10);
+        yield* send(2);
+        yield* sleep(10);
+        // Close the faucet
+        faucet.close();
+        // This should not be sent because we'll close the faucet
+        yield* send(3);
+      });
+    });
+
+    yield* is(results, (results) => results.length === 2);
+
+    expect(results.valueOf()).toEqual([1, 2]);
+  });
+});

package/{script/test-helpers/faucet.d.ts → test-helpers/faucet.ts}

@@ -1,36 +1,42 @@
-import { type Operation, type Stream } from "effection";
+import { createChannel, type Operation, type Stream } from "effection";
+import { createBooleanSignal, is } from "@effectionx/signals";
+
 /**
  * Interface of the stream returned by `useFaucet`.
  */
 export interface Faucet<T> extends Stream<T, never> {
-    /**
-     * Pour items to the stream synchronously.
-     * @param items - The items to pour to the stream.
-     */
-    pour(items: T[]): Operation<void>;
-    /**
-     * Pour items to the stream using an operation that can be asynchronous.
-     * @param op - The generator function to pour items to the stream.
-     */
-    pour(op: (send: (item: T) => Operation<void>) => Operation<void>): Operation<void>;
-    /**
-     * Open the stream to allow items to be sent to the stream.
-     */
-    open(): void;
-    /**
-     * Close the stream to prevent items from being sent to the stream.
-     */
-    close(): void;
+  /**
+   * Pour items to the stream synchronously.
+   * @param items - The items to pour to the stream.
+   */
+  pour(items: T[]): Operation<void>;
+  /**
+   * Pour items to the stream using an operation that can be asynchronous.
+   * @param op - The generator function to pour items to the stream.
+   */
+  pour(
+    op: (send: (item: T) => Operation<void>) => Operation<void>,
+  ): Operation<void>;
+  /**
+   * Open the stream to allow items to be sent to the stream.
+   */
+  open(): void;
+  /**
+   * Close the stream to prevent items from being sent to the stream.
+   */
+  close(): void;
 }
+
 /**
  * Options for the faucet.
  */
 export interface FaucetOptions {
-    /**
-     * Whether the faucet is open when created.
-     */
-    open?: boolean;
+  /**
+   * Whether the faucet is open when created.
+   */
+  open?: boolean;
 }
+
 /**
  * Creates a stream that can be used to test the behavior of streams that use backpressure.
  * It's useful in tests where it can be used as a source stream. This function is used to create
@@ -74,5 +80,30 @@ export interface FaucetOptions {
  * @param options.open - Whether the faucet is open.
  * @returns stream of items coming from the faucet
  */
-export declare function useFaucet<T>(options: FaucetOptions): Operation<Faucet<T>>;
-//# sourceMappingURL=faucet.d.ts.map
+export function* useFaucet<T>(options: FaucetOptions): Operation<Faucet<T>> {
+  let signal = createChannel<T, never>();
+  let open = yield* createBooleanSignal(options.open);
+
+  return {
+    [Symbol.iterator]: signal[Symbol.iterator],
+    *pour(items) {
+      if (Array.isArray(items)) {
+        for (let i of items) {
+          yield* is(open, (open) => open);
+          yield* signal.send(i);
+        }
+      } else {
+        yield* items(function* (item) {
+          yield* is(open, (open) => open);
+          yield* signal.send(item);
+        });
+      }
+    },
+    close() {
+      open.set(false);
+    },
+    open() {
+      open.set(true);
+    },
+  };
+}

package/test-helpers.ts

@@ -0,0 +1 @@
+export * from "./test-helpers/faucet.ts";

package/tracker.test.ts

@@ -0,0 +1,109 @@
+import { describe, it } from "@effectionx/bdd";
+import { expect } from "expect";
+import { each, sleep, spawn } from "effection";
+import { pipe } from "remeda";
+
+import { batch } from "./batch.ts";
+import { map } from "./map.ts";
+import { useFaucet } from "./test-helpers/faucet.ts";
+import { createTracker } from "./tracker.ts";
+import { createArraySignal, is } from "@effectionx/signals";
+
+describe("tracker", () => {
+  it("waits for all items to be processed", function* () {
+    const tracker = yield* createTracker();
+    const faucet = yield* useFaucet<number>({ open: true });
+    const received = yield* createArraySignal<number>([]);
+
+    const stream = pipe(
+      faucet,
+      tracker.passthrough(),
+      map(function* (x: number) {
+        yield* sleep(10);
+        return x;
+      }),
+    );
+
+    yield* spawn(function* () {
+      for (const item of yield* each(stream)) {
+        yield* sleep(10);
+        received.push(item);
+        tracker.markOne(item);
+        yield* each.next();
+      }
+    });
+
+    yield* sleep(1);
+
+    yield* faucet.pour(function* (send) {
+      yield* send(1);
+      yield* sleep(1);
+      yield* send(2);
+      yield* sleep(1);
+      yield* send(3);
+    });
+
+    yield* tracker;
+
+    yield* is(received, (received) => received.length === 3);
+
+    expect(received.valueOf()).toEqual([1, 2, 3]);
+  });
+
+  it("tracks batched items", function* () {
+    const tracker = yield* createTracker();
+    const faucet = yield* useFaucet<number>({ open: true });
+    const received = yield* createArraySignal<readonly number[]>([]);
+
+    const stream = pipe(
+      faucet,
+      tracker.passthrough(),
+      batch({
+        maxSize: 3,
+      }),
+      map(function* (items) {
+        yield* sleep(10);
+        return items;
+      }),
+    );
+
+    yield* spawn(function* () {
+      for (const items of yield* each(stream)) {
+        received.push(items);
+        tracker.markMany(items);
+        yield* each.next();
+      }
+    });
+
+    yield* sleep(1);
+
+    yield* faucet.pour(function* (send) {
+      yield* send(1);
+      yield* sleep(10);
+      yield* send(2);
+      yield* sleep(10);
+      yield* send(3);
+      yield* sleep(10);
+      yield* send(4);
+      yield* sleep(10);
+      yield* send(5);
+      yield* sleep(10);
+      yield* send(6);
+      yield* sleep(10);
+      yield* send(7);
+      yield* sleep(10);
+      yield* send(8);
+      yield* sleep(10);
+      yield* send(9);
+    });
+
+    yield* is(received, (received) => received.flat().length >= 9);
+    yield* tracker;
+
+    expect(received.valueOf()).toEqual([
+      [1, 2, 3],
+      [4, 5, 6],
+      [7, 8, 9],
+    ]);
+  });
+});

package/tracker.ts

@@ -0,0 +1,57 @@
+import { type Operation, resource, type Stream } from "effection";
+import { createSetSignal, is } from "@effectionx/signals";
+
+export interface Tracker extends Operation<void> {
+  /**
+   * Returns a stream helper that doesn't modify the items passing through the stream,
+   * but will capture a reference to the item. Call the `markOne` or `markMany` methods
+   * with the item to indicate that it has exited the stream.
+   */
+  passthrough(): <T>(stream: Stream<T, never>) => Stream<T, never>;
+  /**
+   * Call this method with an item that has passed through the stream to indicate that it has exited the stream.
+   */
+  markOne(item: unknown): void;
+  /**
+   * Call this method with an iterable of items that have passed through the stream to indicate that they have exited the stream.
+   */
+  markMany(items: Iterable<unknown>): void;
+}
+
+/**
+ * Creates a tracker that can be used to verify that all items that entered the stream
+ * eventually exit the stream. This is helpful when you want to ensure that all items
+ * were processed before terminating the operation that created the stream.
+ */
+export function createTracker(): Operation<Tracker> {
+  return resource(function* (provide) {
+    const tracked = yield* createSetSignal();
+
+    yield* provide({
+      *[Symbol.iterator]() {
+        yield* is(tracked, (set) => set.size === 0);
+      },
+      passthrough() {
+        return <T, TDone>(stream: Stream<T, TDone>): Stream<T, TDone> => ({
+          *[Symbol.iterator]() {
+            const subscription = yield* stream;
+
+            return {
+              *next() {
+                const next = yield* subscription.next();
+                tracked.add(next.value);
+                return next;
+              },
+            };
+          },
+        });
+      },
+      markOne(item) {
+        tracked.delete(item);
+      },
+      markMany(items) {
+        tracked.difference(items);
+      },
+    });
+  });
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "."
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["**/*.test.ts", "dist"],
+  "references": [
+    {
+      "path": "../bdd"
+    },
+    {
+      "path": "../signals"
+    },
+    {
+      "path": "../timebox"
+    }
+  ]
+}

package/valve.test.ts

@@ -0,0 +1,52 @@
+import { describe, it } from "@effectionx/bdd";
+import { createArraySignal, is } from "@effectionx/signals";
+import { expect } from "expect";
+import { mock } from "node:test";
+import { each, sleep, spawn } from "effection";
+
+import { valve } from "./valve.ts";
+import { useFaucet } from "./test-helpers/faucet.ts";
+
+describe("valve", () => {
+  it("closes and opens the valve", function* () {
+    const faucet = yield* useFaucet<number>({ open: true });
+
+    const closeFn = function* () {
+      faucet.close();
+    };
+    const close = mock.fn(closeFn);
+
+    const openFn = function* () {
+      faucet.open();
+    };
+    const open = mock.fn(openFn);
+
+    const stream = valve({
+      closeAt: 5,
+      close,
+      open,
+      openAt: 2,
+    });
+
+    const values = yield* createArraySignal<number>([]);
+
+    yield* spawn(function* () {
+      for (const value of yield* each(stream(faucet))) {
+        values.push(value);
+        yield* sleep(1);
+        yield* each.next();
+      }
+    });
+
+    yield* sleep(1);
+
+    yield* faucet.pour([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+
+    yield* is(values, (values) => values.length === 10);
+
+    expect(values.valueOf()).toEqual([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+
+    expect(close.mock.callCount()).toBe(1);
+    expect(open.mock.callCount()).toBe(1);
+  });
+});