@anabranch/queue 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Frodi Karlsson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# @anabranch/queue
+
+Queue primitives with Task/Stream semantics for error-tolerant message
+processing.
+
+## Description
+
+A queue abstraction that integrates with anabranch's Task and Stream types for
+composable error handling, concurrent processing, and automatic resource
+management.
+
+## Features
+
+- **Task/Stream Integration**: Leverage Task's retry/timeout and Stream's error
+  collection
+- **Multiple Adapters**: In-memory implementation included, Redis/RabbitMQ/SQS
+  coming soon
+- **Delayed Messages**: Support for scheduled/delayed message delivery
+- **Dead Letter Queues**: Automatic routing of failed messages after max
+  attempts
+- **Batch Operations**: Send multiple messages, acknowledge multiple at once
+
+## Installation
+
+```bash
+# JSR
+jsr add @anabranch/queue
+
+# Deno
+deno add @anabranch/queue
+```
+
+## Quick Start
+
+```ts
+import { createInMemory, Queue } from "@anabranch/queue";
+
+const connector = createInMemory();
+
+// Send a message
+const id = await Queue.withConnection(
+  connector,
+  (queue) => queue.send("notifications", { type: "welcome", userId: 123 }),
+).run();
+
+// Process messages with error collection
+const { successes, errors } = await Queue.withConnection(
+  connector,
+  (queue) =>
+    Task.of(() =>
+      queue.stream("notifications", { concurrency: 5 })
+        .map(async (msg) => await sendNotification(msg.data))
+        .tapErr((err) => logError(err))
+    ),
+).partition();
+```
+
+## API
+
+### Queue.send
+
+Send a message to a queue with optional delay:
+
+```ts
+await Queue.withConnection(
+  connector,
+  (queue) => queue.send("my-queue", { key: "value" }, { delayMs: 30_000 }),
+).run();
+```
+
+### Queue.stream
+
+Stream messages with concurrent processing:
+
+```ts
+const { successes, errors } = await Queue.withConnection(
+  connector,
+  (queue) =>
+    Task.of(() =>
+      queue.stream("orders", { count: 10, concurrency: 10 })
+        .map(async (msg) => await processOrder(msg.data))
+    ),
+).partition();
+```
+
+### Queue.ack / Queue.nack
+
+Acknowledge successful processing or negative acknowledge with requeue:
+
+```ts
+await Queue.withConnection(
+  connector,
+  (queue) => queue.nack("orders", msg.id, { requeue: true, delay: 5_000 }),
+).run();
+
+// Or route to dead letter queue
+await Queue.withConnection(
+  connector,
+  (queue) => queue.nack("orders", msg.id, { deadLetter: true }),
+).run();
+```
+
+### Queue.sendBatch
+
+Send multiple messages efficiently:
+
+```ts
+const ids = await Queue.withConnection(
+  connector,
+  (queue) =>
+    queue.sendBatch("notifications", [
+      { to: "user1@example.com" },
+      { to: "user2@example.com" },
+    ]),
+).run();
+```
+
+## Configuration
+
+### In-Memory Queue Options
+
+```ts
+const connector = createInMemory({
+  maxBufferSize: 1000,
+  queues: {
+    orders: {
+      maxAttempts: 3,
+      deadLetterQueue: "orders-failed",
+    },
+  },
+});
+```
+
+## Error Handling
+
+All errors are typed for catchable handling:
+
+- `QueueConnectionFailed` - Connection establishment failed
+- `QueueSendFailed` - Send operation failed
+- `QueueReceiveFailed` - Receive operation failed
+- `QueueAckFailed` - Acknowledgment failed
+
+```ts
+try {
+  await Queue.withConnection(connector, (queue) => queue.send("my-queue", data))
+    .run();
+} catch (error) {
+  if (error instanceof QueueSendFailed) {
+    console.error("Failed to send:", error.message);
+  }
+}
+```
+
+## Related
+
+- [@anabranch/anabranch](https://jsr.io/@anabranch/anabranch) - Core Task/Stream
+  primitives
+- [@anabranch/db](https://jsr.io/@anabranch/db) - Database adapter pattern
+  (inspiration for this package)

package/esm/anabranch/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Anabranch is a TypeScript library for error-tolerant async streams.
+ *
+ * Instead of throwing on the first error, it collects errors alongside
+ * successful values so you can process a stream to completion and deal with
+ * failures at the end — or not at all.
+ *
+ * The entry point is {@link Source}. Once you have a stream, chain operations
+ * like {@link Stream.map map}, {@link Stream.filter filter},
+ * {@link Stream.flatMap flatMap}, and {@link Stream.fold fold} to transform it,
+ * then consume it with {@link Stream.collect collect} or
+ * {@link Stream.partition partition}.
+ *
+ * @example Fetch a list of URLs concurrently, collect results and failures separately
+ * ```ts
+ * import { Source } from "anabranch";
+ *
+ * const { successes, errors } = await Source.from<string, Error>(
+ *   async function* () {
+ *     yield "https://example.com/1";
+ *     yield "https://example.com/2";
+ *     yield "https://example.com/3";
+ *   },
+ * )
+ *   .withConcurrency(3)
+ *   .map(async (url) => {
+ *     const res = await fetch(url);
+ *     if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
+ *     return res.json();
+ *   })
+ *   .partition();
+ *
+ * console.log(`${successes.length} succeeded, ${errors.length} failed`);
+ * ```
+ *
+ * @module
+ */
+export { Source } from "./streams/source.js";
+export { Task } from "./streams/task.js";
+export { Channel } from "./streams/channel.js";
+export type { Stream } from "./streams/stream.js";
+export { AggregateError } from "./streams/util.js";
+export type { ErrorResult, Promisable, Result, SuccessResult, } from "./streams/util.js";
+//# sourceMappingURL=index.d.ts.map

package/esm/anabranch/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/anabranch/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,YAAY,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EACV,WAAW,EACX,UAAU,EACV,MAAM,EACN,aAAa,GACd,MAAM,mBAAmB,CAAC"}

package/esm/anabranch/index.js

@@ -0,0 +1,41 @@
+/**
+ * Anabranch is a TypeScript library for error-tolerant async streams.
+ *
+ * Instead of throwing on the first error, it collects errors alongside
+ * successful values so you can process a stream to completion and deal with
+ * failures at the end — or not at all.
+ *
+ * The entry point is {@link Source}. Once you have a stream, chain operations
+ * like {@link Stream.map map}, {@link Stream.filter filter},
+ * {@link Stream.flatMap flatMap}, and {@link Stream.fold fold} to transform it,
+ * then consume it with {@link Stream.collect collect} or
+ * {@link Stream.partition partition}.
+ *
+ * @example Fetch a list of URLs concurrently, collect results and failures separately
+ * ```ts
+ * import { Source } from "anabranch";
+ *
+ * const { successes, errors } = await Source.from<string, Error>(
+ *   async function* () {
+ *     yield "https://example.com/1";
+ *     yield "https://example.com/2";
+ *     yield "https://example.com/3";
+ *   },
+ * )
+ *   .withConcurrency(3)
+ *   .map(async (url) => {
+ *     const res = await fetch(url);
+ *     if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
+ *     return res.json();
+ *   })
+ *   .partition();
+ *
+ * console.log(`${successes.length} succeeded, ${errors.length} failed`);
+ * ```
+ *
+ * @module
+ */
+export { Source } from "./streams/source.js";
+export { Task } from "./streams/task.js";
+export { Channel } from "./streams/channel.js";
+export { AggregateError } from "./streams/util.js";

package/esm/anabranch/streams/channel.d.ts

@@ -0,0 +1,15 @@
+import { _StreamImpl } from "./stream.js";
+interface ChannelOptions<T> {
+    bufferSize?: number;
+    onDrop?: (value: T) => void;
+    onClose?: () => void;
+}
+export declare class Channel<T, E = never> extends _StreamImpl<T, E> {
+    private sourceImpl;
+    constructor(options?: ChannelOptions<T>);
+    send(value: T): void;
+    fail(error: E): void;
+    close(): void;
+}
+export {};
+//# sourceMappingURL=channel.d.ts.map

package/esm/anabranch/streams/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../../src/anabranch/streams/channel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG1C,UAAU,cAAc,CAAC,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB;AAgFD,qBAAa,OAAO,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,CAAE,SAAQ,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC;IAC1D,OAAO,CAAC,UAAU,CAAsB;gBAE5B,OAAO,GAAE,cAAc,CAAC,CAAC,CAAM;IAM3C,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAIpB,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAIpB,KAAK,IAAI,IAAI;CAGd"}

package/esm/anabranch/streams/channel.js

@@ -0,0 +1,122 @@
+import { _StreamImpl } from "./stream.js";
+class ChannelSource {
+    constructor(options = {}) {
+        Object.defineProperty(this, "queue", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "closed", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "consumers", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "bufferSize", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "onDrop", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "onClose", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.bufferSize = Number.isFinite(options.bufferSize)
+            ? Math.max(1, options.bufferSize)
+            : Infinity;
+        this.onDrop = options.onDrop;
+        this.onClose = options.onClose;
+    }
+    send(value) {
+        if (this.closed) {
+            return;
+        }
+        if (this.queue.length >= this.bufferSize && this.bufferSize !== Infinity) {
+            this.onDrop?.(value);
+            return;
+        }
+        this.queue.push({ type: "success", value });
+        this.wake();
+    }
+    fail(error) {
+        if (this.closed) {
+            return;
+        }
+        this.queue.push({ type: "error", error });
+        this.wake();
+    }
+    close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.wake();
+    }
+    wake() {
+        while (this.consumers.length > 0) {
+            const consumer = this.consumers.shift();
+            if (consumer)
+                consumer();
+        }
+    }
+    async *generator() {
+        try {
+            while (true) {
+                while (this.queue.length > 0) {
+                    yield this.queue.shift();
+                }
+                if (this.closed && this.queue.length === 0) {
+                    return;
+                }
+                if (this.queue.length === 0) {
+                    await new Promise((resolve) => {
+                        this.consumers.push(resolve);
+                    });
+                    if (this.queue.length > 0)
+                        continue;
+                }
+            }
+        }
+        finally {
+            this.onClose?.();
+        }
+    }
+}
+export class Channel extends _StreamImpl {
+    constructor(options = {}) {
+        const sourceImpl = new ChannelSource(options);
+        super(() => sourceImpl.generator(), Infinity, Infinity);
+        Object.defineProperty(this, "sourceImpl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.sourceImpl = sourceImpl;
+    }
+    send(value) {
+        this.sourceImpl.send(value);
+    }
+    fail(error) {
+        this.sourceImpl.fail(error);
+    }
+    close() {
+        this.sourceImpl.close();
+    }
+}

package/esm/anabranch/streams/source.d.ts

@@ -0,0 +1,75 @@
+import { _StreamImpl } from "./stream.js";
+import type { Result } from "./util.js";
+/**
+ * The entry point for creating a {@link Stream}. Wraps an async generator so
+ * that yielded values become success results and any thrown error becomes a
+ * single error result.
+ *
+ * Use {@link Source.from} to create a source from an existing `AsyncIterable`
+ * or generator function. Use {@link Source.withConcurrency} and
+ * {@link Source.withBufferSize} to configure parallel execution.
+ *
+ * @example
+ * ```ts
+ * import { Source } from "anabranch";
+ *
+ * const stream = Source.from<number, Error>(async function* () {
+ *   yield 1;
+ *   yield 2;
+ *   yield 3;
+ * });
+ *
+ * const results = await stream.collect();
+ * ```
+ */
+export declare class Source<T, E> extends _StreamImpl<T, E> {
+    private readonly resultSource;
+    /**
+     * @param source An async generator function. Each yielded value becomes a
+     * success result; any thrown error becomes an error result and terminates
+     * the source.
+     * @param concurrency Maximum number of concurrent operations. Defaults to `Infinity`.
+     * @param bufferSize Maximum number of buffered results before backpressure is applied. Defaults to `Infinity`.
+     */
+    private constructor();
+    /**
+     * Creates a {@link Source} from an existing `AsyncIterable` or async
+     * generator function. Each value emitted becomes a success result; any
+     * thrown error becomes an error result.
+     *
+     * @example
+     * ```ts
+     * import { Source } from "anabranch";
+     *
+     * // From a generator function
+     * const stream = Source.from<number, Error>(async function* () {
+     *   yield 1;
+     *   yield 2;
+     * });
+     *
+     * // From an AsyncIterable
+     * async function* generate() {
+     *   yield 1;
+     *   yield 2;
+     * }
+     * const stream2 = Source.from<number, Error>(generate());
+     * ```
+     */
+    static from<T, E>(source: AsyncIterable<T>): Source<T, E>;
+    static from<T, E>(fn: () => AsyncGenerator<T>): Source<T, E>;
+    /**
+     * Creates a {@link Source} from an async generator that yields {@link Result}
+     * values directly. This is useful when you want to yield both successes and
+     * errors from the source without terminating it on the first error.
+     */
+    static fromResults<T, E>(source: () => AsyncGenerator<Result<T, E>>): Source<T, E>;
+    /**
+     * Sets the maximum number of concurrent operations for the stream.
+     */
+    withConcurrency(n: number): Source<T, E>;
+    /**
+     * Sets the maximum number of buffered results before backpressure is applied to the stream. If the buffer is full, the stream will pause until there is space in the buffer for new results.
+     */
+    withBufferSize(n: number): Source<T, E>;
+}
+//# sourceMappingURL=source.d.ts.map

package/esm/anabranch/streams/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../../src/anabranch/streams/source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,MAAM,CAAC,CAAC,EAAE,CAAC,CAAE,SAAQ,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC;IAS/C,OAAO,CAAC,QAAQ,CAAC,YAAY;IAR/B;;;;;;OAMG;IACH,OAAO;IAQP;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC;IACzD,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,cAAc,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC;IAoB5D;;;;OAIG;IACH,MAAM,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,EACrB,MAAM,EAAE,MAAM,cAAc,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GACzC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC;IAIf;;OAEG;IACH,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC;IAIxC;;OAEG;IACH,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC;CAGxC"}

package/esm/anabranch/streams/source.js

@@ -0,0 +1,77 @@
+import { _StreamImpl } from "./stream.js";
+/**
+ * The entry point for creating a {@link Stream}. Wraps an async generator so
+ * that yielded values become success results and any thrown error becomes a
+ * single error result.
+ *
+ * Use {@link Source.from} to create a source from an existing `AsyncIterable`
+ * or generator function. Use {@link Source.withConcurrency} and
+ * {@link Source.withBufferSize} to configure parallel execution.
+ *
+ * @example
+ * ```ts
+ * import { Source } from "anabranch";
+ *
+ * const stream = Source.from<number, Error>(async function* () {
+ *   yield 1;
+ *   yield 2;
+ *   yield 3;
+ * });
+ *
+ * const results = await stream.collect();
+ * ```
+ */
+export class Source extends _StreamImpl {
+    /**
+     * @param source An async generator function. Each yielded value becomes a
+     * success result; any thrown error becomes an error result and terminates
+     * the source.
+     * @param concurrency Maximum number of concurrent operations. Defaults to `Infinity`.
+     * @param bufferSize Maximum number of buffered results before backpressure is applied. Defaults to `Infinity`.
+     */
+    constructor(resultSource, concurrency = Infinity, bufferSize = Infinity) {
+        super(resultSource, concurrency, bufferSize);
+        Object.defineProperty(this, "resultSource", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: resultSource
+        });
+    }
+    static from(source) {
+        const fn = typeof source === "function" ? source : async function* () {
+            yield* source;
+        };
+        const resultSource = async function* () {
+            try {
+                for await (const value of fn()) {
+                    yield { type: "success", value };
+                }
+            }
+            catch (error) {
+                yield { type: "error", error: error };
+            }
+        };
+        return new Source(resultSource);
+    }
+    /**
+     * Creates a {@link Source} from an async generator that yields {@link Result}
+     * values directly. This is useful when you want to yield both successes and
+     * errors from the source without terminating it on the first error.
+     */
+    static fromResults(source) {
+        return new Source(source);
+    }
+    /**
+     * Sets the maximum number of concurrent operations for the stream.
+     */
+    withConcurrency(n) {
+        return new Source(this.resultSource, n, this.bufferSize);
+    }
+    /**
+     * Sets the maximum number of buffered results before backpressure is applied to the stream. If the buffer is full, the stream will pause until there is space in the buffer for new results.
+     */
+    withBufferSize(n) {
+        return new Source(this.resultSource, this.concurrency, n);
+    }
+}