@effectionx/task-buffer 1.0.2

package/README.md

@@ -0,0 +1,33 @@
+# Task Buffer
+
+Manages concurrent task execution by enforcing a maximum limit on simultaneously
+active operations.
+
+---
+
+When this limit is reached, the `TaskBuffer` automatically queues additional
+spawn requests and processes them in order as capacity becomes available. This
+prevents resource overload while ensuring all tasks are eventually executed.
+
+```ts
+import { run, sleep } from "effection";
+import { useTaskBuffer } from "@effectionx/task-buffer";
+
+await run(function* () {
+  // Create a task buffer with a maximum of 2 concurrent tasks
+  const buffer = yield* useTaskBuffer(2);
+
+  // These tasks will execute immediately since they're within the limit
+  yield* buffer.spawn(() => sleep(10));
+  yield* buffer.spawn(() => sleep(10));
+
+  // This task will be queued until one of the running tasks completes
+  yield* buffer.spawn(() => sleep(10));
+
+  // Wait for this specific task to complete
+  yield* yield* buffer.spawn(() => sleep(10));
+
+  // Wait for all spawned tasks to complete
+  yield* buffer;
+});
+```

package/esm/mod.d.ts

@@ -0,0 +1,2 @@
+export { useTaskBuffer } from "./task-buffer.js";
+//# sourceMappingURL=mod.d.ts.map

package/esm/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC"}

package/esm/mod.js

@@ -0,0 +1 @@
+export { useTaskBuffer } from "./task-buffer.js";

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/task-buffer.d.ts

@@ -0,0 +1,46 @@
+import { type Operation, type Task } from "effection";
+/**
+ * Spawn operations, but only allow a certain number to be active at a
+ * given time. Once the `TaskBuffer` becomes full, it will queue up spawn
+ * operations until room becomes available
+ */
+export interface TaskBuffer extends Operation<void> {
+    /**
+     * Spawn `op` in the task buffer when there is room available. If
+     *  there is room, then this operation will complete immediately.
+     * Otherwise, it will return once there is room in the buffer and
+     * the task is successfully spawned.
+     * `spawn()` operation will not return until the task has actually
+     * been spawned.
+     *
+     * @param op - the operation to spawn in the buffer.
+     * @returns the spawned task.
+     */
+    spawn<T>(op: () => Operation<T>): Operation<Operation<Task<T>>>;
+}
+/**
+ * Create a new `TaskBuffer` attached to the current scope. It will
+ * not allow its number of active tasks to exceed `max`.
+ *
+ * ```ts
+ * import { run, sleep } from "effection";
+ * import { useTaskBuffer } from "@effectionx/task-buffer";
+ *
+ * await run(function*() {
+ *  const buffer = yield* useTaskBuffer(2);
+ *
+ *  yield* buffer.spawn(() => sleep(10));
+ *  yield* buffer.spawn(() => sleep(10));
+ *  // the next task won't execute until the above two tasks are completed
+ *  yield* buffer.spawn(() => sleep(10));
+ *
+ *  // will wait for all tasks to be complete
+ *  yield* buffer;
+ * });
+ * ```
+ *
+ * @param max - the maximum number of concurrent tasks.
+ * @returns the new task buffer.
+ */
+export declare function useTaskBuffer(max: number): Operation<TaskBuffer>;
+//# sourceMappingURL=task-buffer.d.ts.map

package/esm/task-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-buffer.d.ts","sourceRoot":"","sources":["../src/task-buffer.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,SAAS,EAMd,KAAK,IAAI,EAGV,MAAM,WAAW,CAAC;AAEnB;;;;GAIG;AACH,MAAM,WAAW,UAAW,SAAQ,SAAS,CAAC,IAAI,CAAC;IACjD;;;;;;;;;;OAUG;IACH,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACjE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,UAAU,CAAC,CAuDhE"}

package/esm/task-buffer.js

@@ -0,0 +1,82 @@
+import { createChannel, Err, Ok, resource, spawn, useScope, withResolvers, } from "effection";
+/**
+ * Create a new `TaskBuffer` attached to the current scope. It will
+ * not allow its number of active tasks to exceed `max`.
+ *
+ * ```ts
+ * import { run, sleep } from "effection";
+ * import { useTaskBuffer } from "@effectionx/task-buffer";
+ *
+ * await run(function*() {
+ *  const buffer = yield* useTaskBuffer(2);
+ *
+ *  yield* buffer.spawn(() => sleep(10));
+ *  yield* buffer.spawn(() => sleep(10));
+ *  // the next task won't execute until the above two tasks are completed
+ *  yield* buffer.spawn(() => sleep(10));
+ *
+ *  // will wait for all tasks to be complete
+ *  yield* buffer;
+ * });
+ * ```
+ *
+ * @param max - the maximum number of concurrent tasks.
+ * @returns the new task buffer.
+ */
+export function useTaskBuffer(max) {
+    return resource(function* (provide) {
+        let input = createChannel();
+        let output = createChannel();
+        let buffer = new Set();
+        let scope = yield* useScope();
+        let requests = [];
+        yield* spawn(function* () {
+            while (true) {
+                if (requests.length === 0) {
+                    yield* next(input);
+                }
+                else if (buffer.size < max) {
+                    let request = requests.pop();
+                    let task = yield* scope.spawn(request.operation);
+                    buffer.add(task);
+                    yield* spawn(function* () {
+                        try {
+                            let result = Ok(yield* task);
+                            buffer.delete(task);
+                            yield* output.send(result);
+                        }
+                        catch (error) {
+                            buffer.delete(task);
+                            yield* output.send(Err(error));
+                        }
+                    });
+                    request.resolve(task);
+                }
+                else {
+                    yield* next(output);
+                }
+            }
+        });
+        yield* provide({
+            *[Symbol.iterator]() {
+                let outputs = yield* output;
+                while (buffer.size > 0 || requests.length > 0) {
+                    yield* outputs.next();
+                }
+            },
+            *spawn(fn) {
+                let { operation, resolve } = withResolvers();
+                requests.unshift({
+                    operation: fn,
+                    resolve: resolve,
+                });
+                yield* input.send();
+                return operation;
+            },
+        });
+    });
+}
+function* next(stream) {
+    let subscription = yield* stream;
+    return yield* subscription.next();
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@effectionx/task-buffer",
+  "version": "1.0.2",
+  "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"
+    }
+  },
+  "engines": {
+    "node": ">= 16"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "effection": "4.0.0-alpha.4"
+  },
+  "_generatedBy": "dnt@dev"
+}

package/script/mod.d.ts

@@ -0,0 +1,2 @@
+export { useTaskBuffer } from "./task-buffer.js";
+//# sourceMappingURL=mod.d.ts.map

package/script/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC"}

package/script/mod.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useTaskBuffer = void 0;
+var task_buffer_js_1 = require("./task-buffer.js");
+Object.defineProperty(exports, "useTaskBuffer", { enumerable: true, get: function () { return task_buffer_js_1.useTaskBuffer; } });

package/script/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/script/task-buffer.d.ts

@@ -0,0 +1,46 @@
+import { type Operation, type Task } from "effection";
+/**
+ * Spawn operations, but only allow a certain number to be active at a
+ * given time. Once the `TaskBuffer` becomes full, it will queue up spawn
+ * operations until room becomes available
+ */
+export interface TaskBuffer extends Operation<void> {
+    /**
+     * Spawn `op` in the task buffer when there is room available. If
+     *  there is room, then this operation will complete immediately.
+     * Otherwise, it will return once there is room in the buffer and
+     * the task is successfully spawned.
+     * `spawn()` operation will not return until the task has actually
+     * been spawned.
+     *
+     * @param op - the operation to spawn in the buffer.
+     * @returns the spawned task.
+     */
+    spawn<T>(op: () => Operation<T>): Operation<Operation<Task<T>>>;
+}
+/**
+ * Create a new `TaskBuffer` attached to the current scope. It will
+ * not allow its number of active tasks to exceed `max`.
+ *
+ * ```ts
+ * import { run, sleep } from "effection";
+ * import { useTaskBuffer } from "@effectionx/task-buffer";
+ *
+ * await run(function*() {
+ *  const buffer = yield* useTaskBuffer(2);
+ *
+ *  yield* buffer.spawn(() => sleep(10));
+ *  yield* buffer.spawn(() => sleep(10));
+ *  // the next task won't execute until the above two tasks are completed
+ *  yield* buffer.spawn(() => sleep(10));
+ *
+ *  // will wait for all tasks to be complete
+ *  yield* buffer;
+ * });
+ * ```
+ *
+ * @param max - the maximum number of concurrent tasks.
+ * @returns the new task buffer.
+ */
+export declare function useTaskBuffer(max: number): Operation<TaskBuffer>;
+//# sourceMappingURL=task-buffer.d.ts.map

package/script/task-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-buffer.d.ts","sourceRoot":"","sources":["../src/task-buffer.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,SAAS,EAMd,KAAK,IAAI,EAGV,MAAM,WAAW,CAAC;AAEnB;;;;GAIG;AACH,MAAM,WAAW,UAAW,SAAQ,SAAS,CAAC,IAAI,CAAC;IACjD;;;;;;;;;;OAUG;IACH,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACjE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,UAAU,CAAC,CAuDhE"}

package/script/task-buffer.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useTaskBuffer = useTaskBuffer;
+const effection_1 = require("effection");
+/**
+ * Create a new `TaskBuffer` attached to the current scope. It will
+ * not allow its number of active tasks to exceed `max`.
+ *
+ * ```ts
+ * import { run, sleep } from "effection";
+ * import { useTaskBuffer } from "@effectionx/task-buffer";
+ *
+ * await run(function*() {
+ *  const buffer = yield* useTaskBuffer(2);
+ *
+ *  yield* buffer.spawn(() => sleep(10));
+ *  yield* buffer.spawn(() => sleep(10));
+ *  // the next task won't execute until the above two tasks are completed
+ *  yield* buffer.spawn(() => sleep(10));
+ *
+ *  // will wait for all tasks to be complete
+ *  yield* buffer;
+ * });
+ * ```
+ *
+ * @param max - the maximum number of concurrent tasks.
+ * @returns the new task buffer.
+ */
+function useTaskBuffer(max) {
+    return (0, effection_1.resource)(function* (provide) {
+        let input = (0, effection_1.createChannel)();
+        let output = (0, effection_1.createChannel)();
+        let buffer = new Set();
+        let scope = yield* (0, effection_1.useScope)();
+        let requests = [];
+        yield* (0, effection_1.spawn)(function* () {
+            while (true) {
+                if (requests.length === 0) {
+                    yield* next(input);
+                }
+                else if (buffer.size < max) {
+                    let request = requests.pop();
+                    let task = yield* scope.spawn(request.operation);
+                    buffer.add(task);
+                    yield* (0, effection_1.spawn)(function* () {
+                        try {
+                            let result = (0, effection_1.Ok)(yield* task);
+                            buffer.delete(task);
+                            yield* output.send(result);
+                        }
+                        catch (error) {
+                            buffer.delete(task);
+                            yield* output.send((0, effection_1.Err)(error));
+                        }
+                    });
+                    request.resolve(task);
+                }
+                else {
+                    yield* next(output);
+                }
+            }
+        });
+        yield* provide({
+            *[Symbol.iterator]() {
+                let outputs = yield* output;
+                while (buffer.size > 0 || requests.length > 0) {
+                    yield* outputs.next();
+                }
+            },
+            *spawn(fn) {
+                let { operation, resolve } = (0, effection_1.withResolvers)();
+                requests.unshift({
+                    operation: fn,
+                    resolve: resolve,
+                });
+                yield* input.send();
+                return operation;
+            },
+        });
+    });
+}
+function* next(stream) {
+    let subscription = yield* stream;
+    return yield* subscription.next();
+}