@haathie/pgmb 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 haathie
+
+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/lib/abortable-async-iterator.d.ts

@@ -0,0 +1,14 @@
+type AAResult<T> = IteratorResult<T>;
+export declare class AbortableAsyncIterator<T> implements AsyncIterableIterator<T> {
+    #private;
+    readonly signal: AbortSignal;
+    readonly onEnd: () => void;
+    ended: boolean;
+    constructor(signal: AbortSignal, onEnd?: () => void);
+    next(): Promise<AAResult<T>>;
+    enqueue(value: T): void;
+    throw(reason?: unknown): Promise<AAResult<T>>;
+    return(value?: any): Promise<AAResult<T>>;
+    [Symbol.asyncIterator](): this;
+}
+export {};

package/lib/abortable-async-iterator.js

@@ -0,0 +1,86 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbortableAsyncIterator = void 0;
+const assert_1 = __importDefault(require("assert"));
+class AbortableAsyncIterator {
+    signal;
+    onEnd;
+    ended = false;
+    #resolve;
+    #reject;
+    #queue = [];
+    #locked = false;
+    constructor(signal, onEnd = () => { }) {
+        this.signal = signal;
+        this.onEnd = onEnd;
+        signal.addEventListener('abort', this.#onAbort);
+    }
+    async next() {
+        (0, assert_1.default)(!this.ended, 'Iterator has already been completed');
+        (0, assert_1.default)(!this.#locked, 'Concurrent calls to next() are not allowed');
+        let nextItem = this.#queue.shift();
+        if (nextItem) {
+            return { value: nextItem, done: false };
+        }
+        this.#locked = true;
+        try {
+            await this.#setupNextPromise();
+        }
+        finally {
+            this.#locked = false;
+        }
+        nextItem = this.#queue.shift();
+        if (nextItem) {
+            return { value: nextItem, done: false };
+        }
+        return { value: undefined, done: true };
+    }
+    enqueue(value) {
+        (0, assert_1.default)(!this.ended, 'Iterator has already been completed');
+        this.#queue.push(value);
+        this.#resolve?.();
+    }
+    throw(reason) {
+        this.signal.throwIfAborted();
+        this.#reject?.(reason);
+        this.#end();
+        return Promise.resolve({ done: true, value: undefined });
+    }
+    return(value) {
+        this.#resolve?.();
+        this.#end();
+        return Promise.resolve({ done: true, value });
+    }
+    #setupNextPromise() {
+        return new Promise((resolve, reject) => {
+            this.#resolve = () => {
+                resolve();
+                this.#cleanupTask();
+            };
+            this.#reject = err => {
+                reject(err);
+                this.#cleanupTask();
+            };
+        });
+    }
+    #cleanupTask() {
+        this.#resolve = undefined;
+        this.#reject = undefined;
+    }
+    #onAbort = (reason) => {
+        this.#reject?.(reason);
+        this.#end();
+        this.ended = true;
+    };
+    #end() {
+        this.signal.removeEventListener('abort', this.#onAbort);
+        this.onEnd();
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+}
+exports.AbortableAsyncIterator = AbortableAsyncIterator;

package/lib/batcher.d.ts

@@ -0,0 +1,12 @@
+import type { IEventData, PGMBEventBatcherOpts } from './types.ts';
+export declare class PGMBEventBatcher<T extends IEventData> {
+    #private;
+    constructor({ shouldLog, publish, flushIntervalMs, maxBatchSize, logger }: PGMBEventBatcherOpts<T>);
+    end(): Promise<void>;
+    /**
+     * Enqueue a message to be published, will be flushed to the database
+     * when flush() is called (either manually or via interval)
+     */
+    enqueue(msg: T): void;
+    flush(): Promise<void>;
+}

package/lib/batcher.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PGMBEventBatcher = void 0;
+class PGMBEventBatcher {
+    #publish;
+    #flushIntervalMs;
+    #maxBatchSize;
+    #currentBatch = { messages: [] };
+    #flushTimeout;
+    #flushTask;
+    #logger;
+    #shouldLog;
+    #batch = 0;
+    constructor({ shouldLog, publish, flushIntervalMs, maxBatchSize = 2500, logger }) {
+        this.#publish = publish;
+        this.#flushIntervalMs = flushIntervalMs;
+        this.#maxBatchSize = maxBatchSize;
+        this.#logger = logger;
+        this.#shouldLog = shouldLog;
+    }
+    async end() {
+        clearTimeout(this.#flushTimeout);
+        await this.#flushTask;
+        await this.flush();
+    }
+    /**
+     * Enqueue a message to be published, will be flushed to the database
+     * when flush() is called (either manually or via interval)
+     */
+    enqueue(msg) {
+        this.#currentBatch.messages.push(msg);
+        if (this.#currentBatch.messages.length >= this.#maxBatchSize) {
+            this.flush();
+            return;
+        }
+        if (this.#flushTimeout || !this.#flushIntervalMs) {
+            return;
+        }
+        this.#flushTimeout = setTimeout(() => this.flush(), this.#flushIntervalMs);
+    }
+    async flush() {
+        if (!this.#currentBatch.messages.length) {
+            return;
+        }
+        const batch = this.#currentBatch;
+        this.#currentBatch = { messages: [] };
+        clearTimeout(this.#flushTimeout);
+        this.#flushTimeout = undefined;
+        await this.#flushTask;
+        this.#flushTask = this.#publishBatch(batch);
+        return this.#flushTask;
+    }
+    async #publishBatch({ messages }) {
+        const batch = ++this.#batch;
+        try {
+            const ids = await this.#publish(...messages);
+            for (const [i, { id }] of ids.entries()) {
+                if (this.#shouldLog && !this.#shouldLog(messages[i])) {
+                    continue;
+                }
+                this.#logger
+                    ?.info({ batch, id, message: messages[i] }, 'published message');
+            }
+        }
+        catch (err) {
+            this.#logger
+                ?.error({ batch, err, msgs: messages }, 'failed to publish messages');
+        }
+    }
+}
+exports.PGMBEventBatcher = PGMBEventBatcher;

package/lib/client.d.ts

@@ -0,0 +1,73 @@
+import { type Logger } from 'pino';
+import { PGMBEventBatcher } from './batcher.ts';
+import type { PgClientLike } from './query-types.ts';
+import type { GetWebhookInfoFn, IEphemeralListener, IEventData, IEventHandler, IReadEvent, Pgmb2ClientOpts, registerReliableHandlerParams, RegisterSubscriptionParams } from './types.ts';
+type IReliableListener<T extends IEventData> = {
+    type: 'reliable';
+    handler: IEventHandler<T>;
+    removeOnEmpty?: boolean;
+    extra?: unknown;
+    queue: {
+        item: IReadEvent<T>;
+        checkpoint: Checkpoint;
+    }[];
+};
+type IFireAndForgetListener<T extends IEventData> = {
+    type: 'fire-and-forget';
+    stream: IEphemeralListener<T>;
+};
+type IListener<T extends IEventData> = IFireAndForgetListener<T> | IReliableListener<T>;
+type Checkpoint = {
+    activeTasks: number;
+    nextCursor: string;
+    cancelled?: boolean;
+};
+export type IListenerStore<T extends IEventData> = {
+    values: {
+        [id: string]: IListener<T>;
+    };
+};
+export declare class PgmbClient<T extends IEventData = IEventData> extends PGMBEventBatcher<T> {
+    #private;
+    readonly client: PgClientLike;
+    readonly logger: Logger;
+    readonly groupId: string;
+    readonly sleepDurationMs: number;
+    readonly readChunkSize: number;
+    readonly subscriptionMaintenanceMs: number;
+    readonly tableMaintenanceMs: number;
+    readonly maxActiveCheckpoints: number;
+    readonly getWebhookInfo: GetWebhookInfoFn;
+    readonly webhookHandler: IEventHandler;
+    readonly listeners: {
+        [subId: string]: IListenerStore<T>;
+    };
+    constructor({ client, groupId, logger, sleepDurationMs, readChunkSize, maxActiveCheckpoints, poll, subscriptionMaintenanceMs, webhookHandlerOpts, getWebhookInfo, tableMaintainanceMs, ...batcherOpts }: Pgmb2ClientOpts);
+    init(): Promise<void>;
+    end(): Promise<void>;
+    publish(events: T[], client?: PgClientLike): Promise<import("./queries.ts").IWriteEventsResult[]>;
+    assertSubscription(opts: RegisterSubscriptionParams, client?: PgClientLike): Promise<import("./queries.ts").IAssertSubscriptionResult>;
+    /**
+     * Registers a fire-and-forget handler, returning an async iterator
+     * that yields events as they arrive. The client does not wait for event
+     * processing acknowledgements. Useful for cases where data is eventually
+     * consistent, or when event delivery isn't critical
+     * (eg. http SSE, websockets).
+     */
+    registerFireAndForgetHandler(opts: RegisterSubscriptionParams): Promise<IEphemeralListener<T>>;
+    /**
+     * Registers a reliable handler for the given subscription params.
+     * If the handler throws an error, client will rollback to the last known
+     * good cursor, and re-deliver events.
+     * To avoid a full redelivery of a batch, a retry strategy can be provided
+     * to retry failed events by the handler itself, allowing for delayed retries
+     * with backoff, and without disrupting the overall event flow.
+     */
+    registerReliableHandler({ retryOpts, name, ...opts }: registerReliableHandlerParams, handler: IEventHandler<T>): Promise<{
+        subscriptionId: string;
+        cancel: () => void;
+    }>;
+    removeSubscription(subId: string): Promise<void>;
+    readChanges(): Promise<number>;
+}
+export {};