mastra-pg-pubsub 0.1.0

package/dist/sql.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Identifier-safety helpers. All values flow through parameterized queries;
+ * only identifiers (schema, channel) are interpolated, and only after they
+ * have been validated against a strict allowlist and double-quoted.
+ */
+/**
+ * Validate a PostgreSQL schema name against `^[a-z_][a-z0-9_]*$`.
+ *
+ * @param schema - Candidate schema name.
+ * @returns The same schema name when valid.
+ * @throws {Error} When the name does not match the allowlist pattern.
+ */
+export declare function assertValidSchema(schema: string): string;
+/**
+ * Quote a validated identifier for safe interpolation into SQL text.
+ *
+ * @param identifier - An identifier already proven safe by validation.
+ * @returns The double-quoted identifier.
+ */
+export declare function quoteIdentifier(identifier: string): string;
+/**
+ * Derive the deterministic `LISTEN/NOTIFY` channel name for a schema. The
+ * schema is pre-validated, so the result is always a legal identifier.
+ *
+ * @param schema - The validated schema name.
+ * @returns The notify channel name.
+ */
+export declare function notifyChannel(schema: string): string;
+/**
+ * A stable 64-bit advisory lock key derived from a string, used to serialize
+ * lazy migrations across instances. FNV-1a folded into the signed BIGINT range
+ * accepted by `pg_advisory_lock`.
+ *
+ * @param input - Seed string (the schema name).
+ * @returns A bigint in the signed 64-bit range.
+ */
+export declare function advisoryLockKey(input: string): bigint;
+//# sourceMappingURL=sql.d.ts.map

package/dist/sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql.d.ts","sourceRoot":"","sources":["../src/sql.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOxD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASrD"}

package/dist/sql.js

@@ -0,0 +1,57 @@
+/**
+ * Identifier-safety helpers. All values flow through parameterized queries;
+ * only identifiers (schema, channel) are interpolated, and only after they
+ * have been validated against a strict allowlist and double-quoted.
+ */
+const SCHEMA_PATTERN = /^[a-z_][a-z0-9_]*$/;
+/**
+ * Validate a PostgreSQL schema name against `^[a-z_][a-z0-9_]*$`.
+ *
+ * @param schema - Candidate schema name.
+ * @returns The same schema name when valid.
+ * @throws {Error} When the name does not match the allowlist pattern.
+ */
+export function assertValidSchema(schema) {
+    if (!SCHEMA_PATTERN.test(schema)) {
+        throw new Error(`Invalid schema name ${JSON.stringify(schema)}: must match ${SCHEMA_PATTERN.source}`);
+    }
+    return schema;
+}
+/**
+ * Quote a validated identifier for safe interpolation into SQL text.
+ *
+ * @param identifier - An identifier already proven safe by validation.
+ * @returns The double-quoted identifier.
+ */
+export function quoteIdentifier(identifier) {
+    return `"${identifier.replace(/"/g, '""')}"`;
+}
+/**
+ * Derive the deterministic `LISTEN/NOTIFY` channel name for a schema. The
+ * schema is pre-validated, so the result is always a legal identifier.
+ *
+ * @param schema - The validated schema name.
+ * @returns The notify channel name.
+ */
+export function notifyChannel(schema) {
+    return `${schema}_events`;
+}
+/**
+ * A stable 64-bit advisory lock key derived from a string, used to serialize
+ * lazy migrations across instances. FNV-1a folded into the signed BIGINT range
+ * accepted by `pg_advisory_lock`.
+ *
+ * @param input - Seed string (the schema name).
+ * @returns A bigint in the signed 64-bit range.
+ */
+export function advisoryLockKey(input) {
+    let hash = 1469598103934665603n;
+    const prime = 1099511628211n;
+    const mask = (1n << 64n) - 1n;
+    for (let i = 0; i < input.length; i++) {
+        hash ^= BigInt(input.charCodeAt(i));
+        hash = (hash * prime) & mask;
+    }
+    return hash >= 1n << 63n ? hash - (1n << 64n) : hash;
+}
+//# sourceMappingURL=sql.js.map

package/dist/sql.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql.js","sourceRoot":"","sources":["../src/sql.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,cAAc,GAAG,oBAAoB,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,uBAAuB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,gBAAgB,cAAc,CAAC,MAAM,EAAE,CACrF,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,UAAkB;IAChD,OAAO,IAAI,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC;AAC/C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,OAAO,GAAG,MAAM,SAAS,CAAC;AAC5B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,IAAI,IAAI,GAAG,oBAAoB,CAAC;IAChC,MAAM,KAAK,GAAG,cAAc,CAAC;IAC7B,MAAM,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,GAAG,EAAE,CAAC;IAC9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QACpC,IAAI,GAAG,CAAC,IAAI,GAAG,KAAK,CAAC,GAAG,IAAI,CAAC;IAC/B,CAAC;IACD,OAAO,IAAI,IAAI,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACvD,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,119 @@
+import type { Pool } from 'pg';
+/**
+ * A minimal log function. Compatible with `console.log`-style signatures and
+ * with structured loggers that accept a message plus arbitrary context.
+ */
+export type LogFn = (message: string, ...context: unknown[]) => void;
+/**
+ * Optional logger injected into {@link PostgresPubSub}. Every method is
+ * optional; when the whole logger (or an individual method) is absent the
+ * adapter stays silent. Expected races (lost claims, redelivery) log at
+ * `debug`; recoverable problems at `warn`; unexpected failures at `error`.
+ */
+export interface PubSubLogger {
+    /** Verbose, expected-path diagnostics (claim races, wakeups, polls). */
+    debug?: LogFn;
+    /** Recoverable anomalies (dropped events, exhausted retries, stale prune). */
+    warn?: LogFn;
+    /** Unexpected failures inside background loops. */
+    error?: LogFn;
+}
+/**
+ * Configuration for {@link PostgresPubSub}.
+ *
+ * Provide exactly one of {@link PostgresPubSubConfig.connectionString} or
+ * {@link PostgresPubSubConfig.pool}. A pool supplied here is owned by the
+ * caller and is never ended by {@link PostgresPubSub.close}.
+ */
+export interface PostgresPubSubConfig {
+    /**
+     * PostgreSQL connection string. The adapter creates and owns the pool, and
+     * ends it on {@link PostgresPubSub.close}. Mutually exclusive with
+     * {@link PostgresPubSubConfig.pool}.
+     */
+    connectionString?: string;
+    /**
+     * Bring-your-own `pg.Pool`. The adapter never ends it on
+     * {@link PostgresPubSub.close}. Mutually exclusive with
+     * {@link PostgresPubSubConfig.connectionString}.
+     */
+    pool?: Pool;
+    /**
+     * PostgreSQL schema that holds every table. Must match
+     * `^[a-z_][a-z0-9_]*$`. Defaults to `mastra_pubsub`.
+     */
+    schema?: string;
+    /**
+     * Backstop polling interval in milliseconds for each consume loop. Also
+     * bounds how quickly visibility-timeout redeliveries are noticed.
+     * Defaults to `1000`.
+     */
+    pollIntervalMs?: number;
+    /**
+     * Visibility timeout in milliseconds. A claimed delivery becomes visible
+     * again this long after it was claimed unless acked or nacked, providing
+     * crash safety. Defaults to `30_000`.
+     */
+    ackDeadlineMs?: number;
+    /**
+     * Delay in milliseconds before a nacked delivery becomes visible again.
+     * Defaults to `0` (immediate redelivery).
+     */
+    nackDelayMs?: number;
+    /**
+     * Maximum delivery attempts before an event is dropped (and optionally
+     * dead-lettered). `Infinity` disables the cap. `0` is treated as `Infinity`
+     * with a one-time warning. Defaults to `5`.
+     */
+    maxDeliveryAttempts?: number;
+    /** Number of deliveries claimed per loop iteration. Defaults to `32`. */
+    batchSize?: number;
+    /**
+     * Retention cap per topic. Maintenance trims a topic's events down to this
+     * many, never deleting events that still have pending deliveries. `0` keeps
+     * everything. Defaults to `10_000`.
+     */
+    maxEventsPerTopic?: number;
+    /**
+     * Maintenance interval in milliseconds (retention trim + stale private
+     * subscription pruning). `0` disables maintenance. Defaults to `60_000`.
+     */
+    cleanupIntervalMs?: number;
+    /**
+     * Age in milliseconds after which a private subscription whose
+     * `last_seen_at` heartbeat has not advanced is pruned. Defaults to
+     * `300_000`.
+     */
+    staleSubscriptionMs?: number;
+    /**
+     * Enable `LISTEN/NOTIFY` wakeups for low latency. When `false`, the adapter
+     * relies purely on {@link PostgresPubSubConfig.pollIntervalMs} polling.
+     * Defaults to `true`.
+     */
+    listen?: boolean;
+    /**
+     * Copy events that exhaust their delivery attempts into a `dead_events`
+     * table instead of discarding them silently. Defaults to `false`.
+     */
+    deadLetter?: boolean;
+    /** Optional logger; silent when omitted. */
+    logger?: PubSubLogger;
+}
+/**
+ * Fully-resolved configuration with every default applied. Internal.
+ */
+export interface ResolvedConfig {
+    schema: string;
+    pollIntervalMs: number;
+    ackDeadlineMs: number;
+    nackDelayMs: number;
+    maxDeliveryAttempts: number;
+    batchSize: number;
+    maxEventsPerTopic: number;
+    cleanupIntervalMs: number;
+    staleSubscriptionMs: number;
+    listen: boolean;
+    deadLetter: boolean;
+    logger: PubSubLogger;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAE/B;;;GAGG;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;AAErE;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,8EAA8E;IAC9E,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,mDAAmD;IACnD,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,YAAY,CAAC;CACtB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "mastra-pg-pubsub",
+  "version": "0.1.0",
+  "description": "PostgreSQL-backed PubSub adapter for Mastra: at-least-once delivery, consumer groups, replay from offset, dead-lettering, and low-latency LISTEN/NOTIFY wakeups.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Alan Hoffmeister",
+  "homepage": "https://github.com/alanhoff/mastra-pg-pubsub#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alanhoff/mastra-pg-pubsub.git"
+  },
+  "bugs": {
+    "url": "https://github.com/alanhoff/mastra-pg-pubsub/issues"
+  },
+  "keywords": [
+    "mastra",
+    "pubsub",
+    "postgres",
+    "postgresql",
+    "pg",
+    "events",
+    "message-queue",
+    "listen-notify",
+    "consumer-groups",
+    "at-least-once"
+  ],
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "test": "node --test 'test/*.test.ts'",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-lines=95 --test-coverage-functions=95 --test-coverage-branches=90 'test/*.test.ts'",
+    "db:up": "docker compose up -d --wait",
+    "db:down": "docker compose down -v",
+    "test:e2e": "node --env-file-if-exists=.env --test 'test/e2e/*.test.ts'"
+  },
+  "dependencies": {
+    "pg": "^8.16.0",
+    "@types/pg": "^8.15.0"
+  },
+  "peerDependencies": {
+    "@mastra/core": ">=1.13.0-0 <2.0.0-0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.0.0",
+    "@mastra/core": "^1.42.0",
+    "@mastra/memory": "^1.20.3",
+    "@mastra/pg": "^1.13.0",
+    "@types/node": "^22.13.0",
+    "typescript": "^5.7.0",
+    "zod": "^4.4.3"
+  }
+}