mastra-pg-pubsub 0.1.0

package/dist/listener.js

@@ -0,0 +1,126 @@
+import { notifyChannel, quoteIdentifier } from "./sql.js";
+/**
+ * Owns a single dedicated `LISTEN` connection and dispatches `NOTIFY` payloads
+ * (topic names) to registered per-topic wakeup handlers. Reconnects on
+ * connection loss so wakeups survive transient database blips; polling remains
+ * the correctness backstop in the meantime.
+ */
+export class NotifyListener {
+    #pool;
+    #channel;
+    #logger;
+    #handlers = new Map();
+    #client;
+    #connecting;
+    #closed = false;
+    /**
+     * @param pool - Pool used to acquire the dedicated listen connection.
+     * @param schema - Validated schema name; determines the channel.
+     * @param logger - Logger for connection diagnostics.
+     */
+    constructor(pool, schema, logger) {
+        this.#pool = pool;
+        this.#channel = notifyChannel(schema);
+        this.#logger = logger;
+    }
+    /**
+     * Register a wakeup handler for a topic, ensuring the listen connection is
+     * established. Returns an unregister function.
+     *
+     * @param topic - The topic to wake on.
+     * @param handler - Invoked when a `NOTIFY` for the topic arrives.
+     * @returns A function that removes this handler.
+     */
+    async register(topic, handler) {
+        let set = this.#handlers.get(topic);
+        if (!set) {
+            set = new Set();
+            this.#handlers.set(topic, set);
+        }
+        set.add(handler);
+        await this.#ensureConnected();
+        return () => {
+            const current = this.#handlers.get(topic);
+            if (current) {
+                current.delete(handler);
+                if (current.size === 0) {
+                    this.#handlers.delete(topic);
+                }
+            }
+        };
+    }
+    async #ensureConnected() {
+        if (this.#closed || this.#client) {
+            return;
+        }
+        if (!this.#connecting) {
+            this.#connecting = this.#connect().finally(() => {
+                this.#connecting = undefined;
+            });
+        }
+        return this.#connecting;
+    }
+    async #connect() {
+        const client = await this.#pool.connect();
+        client.on('notification', (msg) => {
+            if (msg.payload === undefined) {
+                return;
+            }
+            const handlers = this.#handlers.get(msg.payload);
+            if (handlers) {
+                for (const handler of handlers) {
+                    handler();
+                }
+            }
+        });
+        client.on('error', (error) => {
+            this.#logger.debug?.('listen connection error', error);
+            this.#handleDisconnect(client);
+        });
+        await client.query(`LISTEN ${quoteIdentifier(this.#channel)}`);
+        if (this.#closed) {
+            client.removeAllListeners('notification');
+            client.release();
+            return;
+        }
+        this.#client = client;
+    }
+    #handleDisconnect(client) {
+        if (this.#client !== client) {
+            return;
+        }
+        this.#client = undefined;
+        client.removeAllListeners('notification');
+        client.release(true);
+        if (this.#closed || this.#handlers.size === 0) {
+            return;
+        }
+        this.#ensureConnected().catch((error) => {
+            this.#logger.warn?.('listen reconnect failed', error);
+        });
+    }
+    /**
+     * Release the listen connection and stop dispatching. Idempotent.
+     */
+    async close() {
+        this.#closed = true;
+        this.#handlers.clear();
+        if (this.#connecting) {
+            await this.#connecting.catch(() => undefined);
+        }
+        const client = this.#client;
+        this.#client = undefined;
+        if (client) {
+            client.removeAllListeners('notification');
+            client.removeAllListeners('error');
+            try {
+                await client.query(`UNLISTEN ${quoteIdentifier(this.#channel)}`);
+            }
+            catch {
+                // best effort; releasing the client drops the listen anyway
+            }
+            client.release();
+        }
+    }
+}
+//# sourceMappingURL=listener.js.map

package/dist/listener.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listener.js","sourceRoot":"","sources":["../src/listener.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAG1D;;;;;GAKG;AACH,MAAM,OAAO,cAAc;IAChB,KAAK,CAAO;IACZ,QAAQ,CAAS;IACjB,OAAO,CAAe;IACtB,SAAS,GAAG,IAAI,GAAG,EAA2B,CAAC;IACxD,OAAO,CAAyB;IAChC,WAAW,CAA4B;IACvC,OAAO,GAAG,KAAK,CAAC;IAEhB;;;;OAIG;IACH,YAAY,IAAU,EAAE,MAAc,EAAE,MAAoB;QAC1D,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QACtC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,CAAC,KAAa,EAAE,OAAmB;QAC/C,IAAI,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACpC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACjC,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACjB,MAAM,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC9B,OAAO,GAAG,EAAE;YACV,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAC1C,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBACxB,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;oBACvB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBAC/B,CAAC;YACH,CAAC;QACH,CAAC,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,gBAAgB;QACpB,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjC,OAAO;QACT,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;gBAC9C,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;YAC/B,CAAC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,QAAQ;QACZ,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QAC1C,MAAM,CAAC,EAAE,CAAC,cAAc,EAAE,CAAC,GAAG,EAAE,EAAE;YAChC,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC9B,OAAO;YACT,CAAC;YACD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACjD,IAAI,QAAQ,EAAE,CAAC;gBACb,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;oBAC/B,OAAO,EAAE,CAAC;gBACZ,CAAC;YACH,CAAC;QACH,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAC3B,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;YACvD,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC,CAAC,CAAC;QACH,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAC/D,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAC;YAC1C,MAAM,CAAC,OAAO,EAAE,CAAC;YACjB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED,iBAAiB,CAAC,MAAkB;QAClC,IAAI,IAAI,CAAC,OAAO,KAAK,MAAM,EAAE,CAAC;YAC5B,OAAO;QACT,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;QACzB,MAAM,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAC;QAC1C,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACrB,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YAC9C,OAAO;QACT,CAAC;QACD,IAAI,CAAC,gBAAgB,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YACtC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;QACxD,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACvB,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAChD,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;QACzB,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAC;YAC1C,MAAM,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;YACnC,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,KAAK,CAAC,YAAY,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;YACnE,CAAC;YAAC,MAAM,CAAC;gBACP,4DAA4D;YAC9D,CAAC;YACD,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,CAAC;IACH,CAAC;CACF"}

package/dist/postgres-pubsub.d.ts

@@ -0,0 +1,99 @@
+import type { Event, EventCallback, SubscribeOptions } from '@mastra/core/events';
+import { PubSub } from '@mastra/core/events';
+import type { PostgresPubSubConfig } from './types.ts';
+/**
+ * A PostgreSQL-backed {@link PubSub} implementation for Mastra.
+ *
+ * Provides at-least-once delivery with ack/nack and visibility timeouts,
+ * competing-consumer groups and groupless fan-out, replay addressed by
+ * per-topic `index`, optional dead-lettering, and low-latency `LISTEN/NOTIFY`
+ * wakeups with polling as the correctness backstop. The only runtime
+ * dependency is `pg`; `@mastra/core` is a peer dependency.
+ */
+export declare class PostgresPubSub extends PubSub {
+    #private;
+    /**
+     * @param config - Adapter configuration. Provide exactly one of
+     *   `connectionString` or `pool`.
+     */
+    constructor(config: PostgresPubSubConfig);
+    /**
+     * Create the schema and tables explicitly. Idempotent and safe to call
+     * concurrently across instances (serialized by an advisory lock). When not
+     * called, migration happens lazily on first use.
+     */
+    migrate(): Promise<void>;
+    /**
+     * Publish an event to a topic. Assigns `id`, `createdAt`, and a per-topic
+     * `index` inside a single transaction, fans out one delivery row per active
+     * subscription, and emits a `NOTIFY` wakeup.
+     *
+     * @param topic - The topic to publish to.
+     * @param event - Event without `id`/`createdAt` (assigned here).
+     * @param _options - Accepted for interface compatibility; `localOnly` is
+     *   ignored because delivery is always database-mediated.
+     */
+    publish(topic: string, event: Omit<Event, 'id' | 'createdAt'>, _options?: {
+        localOnly?: boolean;
+    }): Promise<void>;
+    /**
+     * Subscribe to a topic. With `options.group`, members compete and each event
+     * reaches exactly one member (round-robin across local callbacks). Without a
+     * group, the subscription is private to this instance and receives every
+     * event (fan-out).
+     *
+     * @param topic - The topic to subscribe to.
+     * @param cb - Callback invoked per delivered event.
+     * @param options - Subscribe options; `group` selects competing-consumer
+     *   semantics. `batch` is ignored (no native batching).
+     */
+    subscribe(topic: string, cb: EventCallback, options?: SubscribeOptions): Promise<void>;
+    /**
+     * Remove a callback from a topic. Tears down the underlying subscription
+     * (and, for private subscriptions, deletes its database rows) once no local
+     * callbacks remain.
+     *
+     * @param topic - The topic the callback was subscribed to.
+     * @param cb - The callback to remove.
+     */
+    unsubscribe(topic: string, cb: EventCallback): Promise<void>;
+    /**
+     * Resolve once all in-flight publishes and local deliveries have settled.
+     * Per-event callback errors are logged, never thrown. If locally-owned
+     * deliveries remain unsettled after the bounded drain window, reject so
+     * shutdown callers do not mistake a stuck subscriber for a clean drain.
+     */
+    flush(): Promise<void>;
+    /**
+     * Fetch historical events for a topic with `index >= offset`, ordered by
+     * `index`.
+     *
+     * @param topic - The topic to read history for.
+     * @param offset - Inclusive starting `index`. Defaults to `0`.
+     * @returns Events in ascending `index` order.
+     */
+    getHistory(topic: string, offset?: number): Promise<Event[]>;
+    /**
+     * Subscribe and replay all history first, then continue live, deduping the
+     * boundary by event `index` so no event is delivered twice.
+     *
+     * @param topic - The topic to subscribe to.
+     * @param cb - Callback for replayed and live events.
+     */
+    subscribeWithReplay(topic: string, cb: EventCallback): Promise<void>;
+    /**
+     * Subscribe and replay history starting at `offset`, then continue live,
+     * deduping the boundary by event `index`.
+     *
+     * @param topic - The topic to subscribe to.
+     * @param offset - Inclusive starting `index` for replay.
+     * @param cb - Callback for replayed and live events.
+     */
+    subscribeFromOffset(topic: string, offset: number, cb: EventCallback): Promise<void>;
+    /**
+     * Stop all loops, release the listener, delete this instance's private
+     * subscriptions, and end the pool when the adapter created it. Idempotent.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=postgres-pubsub.d.ts.map

package/dist/postgres-pubsub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-pubsub.d.ts","sourceRoot":"","sources":["../src/postgres-pubsub.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAClF,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAM7C,OAAO,KAAK,EAAE,oBAAoB,EAAgC,MAAM,YAAY,CAAC;AAqErF;;;;;;;;GAQG;AACH,qBAAa,cAAe,SAAQ,MAAM;;IAiBxC;;;OAGG;gBACS,MAAM,EAAE,oBAAoB;IA0BxC;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAe9B;;;;;;;;;OASG;IACY,OAAO,CACpB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,GAAG,WAAW,CAAC,EACtC,QAAQ,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GACjC,OAAO,CAAC,IAAI,CAAC;IAkEhB;;;;;;;;;;OAUG;IACY,SAAS,CACtB,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,aAAa,EACjB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC;IAyFhB;;;;;;;OAOG;IACY,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAsC3E;;;;;OAKG;IACY,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA2BrC;;;;;;;OAOG;IACY,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,SAAI,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAYtE;;;;;;OAMG;IACY,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAInF;;;;;;;OAOG;IACY,mBAAmB,CAChC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,aAAa,GAChB,OAAO,CAAC,IAAI,CAAC;IA+HhB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAmC7B"}