@geekmidas/events 10.0.0-alpha.9 → 10.0.0-alpha.91

package/dist/pgboss/index.cjs

@@ -1,41 +1,159 @@
-require('../types-Byv8N9ma.cjs');
-const require_PgBossConnection = require('../PgBossConnection-23soZ_aM.cjs');
-
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_rolldown_runtime = require("../rolldown-runtime-C0BPl7ul.cjs");
+const require_telemetry = require("../telemetry-DG3l807O.cjs");
+let pg_boss = require("pg-boss");
+//#region src/pgboss/PgBossConnection.ts
+var PgBossConnection_exports = /* @__PURE__ */ require_rolldown_runtime.__exportAll({ PgBossConnection: () => PgBossConnection });
+var PgBossConnection = class PgBossConnection {
+	config;
+	type = "pgboss";
+	boss;
+	connecting;
+	constructor(config) {
+		this.config = config;
+	}
+	/**
+	* Create a PgBossConnection from a connection string.
+	* Format: pgboss://user:pass@host:5432/database?schema=pgboss
+	*/
+	static async fromConnectionString(connectionString) {
+		const url = new URL(connectionString);
+		const params = url.searchParams;
+		const config = {
+			connectionString: `postgres://${url.username ? `${url.username}:${url.password}@` : ""}${url.host}${url.pathname}`,
+			schema: params.get("schema") || void 0
+		};
+		const connection = new PgBossConnection(config);
+		await connection.connect();
+		return connection;
+	}
+	async connect() {
+		if (this.boss) return;
+		if (this.connecting) {
+			await this.connecting;
+			return;
+		}
+		this.connecting = (async () => {
+			try {
+				const applicationName = this.config.applicationName ?? process.env.GKM_APP_NAME;
+				const boss = new pg_boss.PgBoss({
+					connectionString: this.config.connectionString,
+					...this.config.schema && { schema: this.config.schema },
+					...applicationName && { application_name: applicationName }
+				});
+				await boss.start();
+				this.boss = boss;
+			} catch (error) {
+				this.cleanup();
+				throw error;
+			}
+		})();
+		await this.connecting;
+		this.connecting = void 0;
+	}
+	async close() {
+		try {
+			await this.boss?.stop({ graceful: true });
+		} catch {} finally {
+			this.cleanup();
+		}
+	}
+	isConnected() {
+		return !!this.boss;
+	}
+	cleanup() {
+		this.boss = void 0;
+		this.connecting = void 0;
+	}
+	/**
+	* Get the underlying pg-boss instance for publishing/subscribing
+	*/
+	get instance() {
+		return this.boss;
+	}
+};
+//#endregion
+//#region src/pgboss/errors.ts
+/** pg-boss connected but its instance never started. */
+var PgBossNotStarted = class extends Error {
+	constructor() {
+		super("pg-boss did not start. Check the database in the connection string is reachable and the role may create the pg-boss schema.");
+		this.name = "PgBossNotStarted";
+	}
+};
+/** A topic subscription with no name to give the subscriber's own queue. */
+var PgBossSubscriptionNeedsName = class extends Error {
+	topic;
+	constructor(topic) {
+		super(`Subscribing to topic '${topic}' on pg-boss needs a subscription name: each subscriber drains a queue of its own, and that queue is named for it. Pass \`subscription\`.`);
+		this.topic = topic;
+		this.name = "PgBossSubscriptionNeedsName";
+	}
+};
+//#endregion
 //#region src/pgboss/PgBossPublisher.ts
+/** The pg-boss event a topic's message type is published as. */
+function topicEvent(topic, type) {
+	return `${topic}/${type}`;
+}
 var PgBossPublisher = class PgBossPublisher {
-	constructor(connection) {
+	connection;
+	options;
+	constructor(connection, options = {}) {
 		this.connection = connection;
+		this.options = options;
 	}
 	/**
 	* Create a PgBossPublisher from a connection string.
 	* Format: pgboss://user:pass@host:5432/database?schema=pgboss
 	*/
-	static async fromConnectionString(connectionString) {
-		const { PgBossConnection: PgBossConnection$1 } = await Promise.resolve().then(() => require("../PgBossConnection-CCXhoNzb.cjs"));
-		const connection = await PgBossConnection$1.fromConnectionString(connectionString);
-		return new PgBossPublisher(connection);
+	static async fromConnectionString(connectionString, options = {}) {
+		const { PgBossConnection } = await Promise.resolve().then(() => PgBossConnection_exports);
+		const connection = await PgBossConnection.fromConnectionString(connectionString);
+		return new PgBossPublisher(connection, options);
 	}
 	async publish(messages) {
 		if (!this.connection.isConnected()) await this.connection.connect();
 		const boss = this.connection.instance;
-		if (!boss) throw new Error("PgBoss instance not initialized");
-		const groups = /* @__PURE__ */ new Map();
-		for (const m of messages) {
-			const list = groups.get(m.type) ?? [];
-			list.push({ data: m.payload });
-			groups.set(m.type, list);
-		}
-		for (const [name, jobs] of groups) {
-			await boss.createQueue(name);
-			await boss.insert(name, jobs);
+		if (!boss) throw new PgBossNotStarted();
+		const { topic } = this.options;
+		if (topic) {
+			await require_telemetry.publishTraced(messages, (m) => ({
+				system: "pgboss",
+				destination: topic,
+				type: m.type
+			}), async (carriers) => {
+				for (const [i, m] of messages.entries()) await boss.publish(topicEvent(topic, m.type), require_telemetry.withTraceKey({
+					type: m.type,
+					payload: m.payload
+				}, carriers[i]));
+			});
+			return;
 		}
+		await require_telemetry.publishTraced(messages, (m) => ({
+			system: "pgboss",
+			destination: m.type,
+			type: m.type
+		}), async (carriers) => {
+			const groups = /* @__PURE__ */ new Map();
+			for (const [i, m] of messages.entries()) {
+				const list = groups.get(m.type) ?? [];
+				list.push({ data: require_telemetry.withTraceKey(m.payload, carriers[i]) });
+				groups.set(m.type, list);
+			}
+			for (const [name, jobs] of groups) {
+				await boss.createQueue(name);
+				await boss.insert(name, jobs);
+			}
+		});
 	}
 	async close() {}
 };
-
 //#endregion
 //#region src/pgboss/PgBossSubscriber.ts
 var PgBossSubscriber = class PgBossSubscriber {
+	connection;
+	options;
 	constructor(connection, options = {}) {
 		this.connection = connection;
 		this.options = options;
@@ -45,10 +163,9 @@ var PgBossSubscriber = class PgBossSubscriber {
 	* Format: pgboss://user:pass@host:5432/database?schema=pgboss&batchSize=5
 	*/
 	static async fromConnectionString(connectionString) {
-		const url = new URL(connectionString);
-		const params = url.searchParams;
-		const { PgBossConnection: PgBossConnection$1 } = await Promise.resolve().then(() => require("../PgBossConnection-CCXhoNzb.cjs"));
-		const connection = await PgBossConnection$1.fromConnectionString(connectionString);
+		const params = new URL(connectionString).searchParams;
+		const { PgBossConnection } = await Promise.resolve().then(() => PgBossConnection_exports);
+		const connection = await PgBossConnection.fromConnectionString(connectionString);
 		const options = {
 			batchSize: params.get("batchSize") ? Number.parseInt(params.get("batchSize"), 10) : void 0,
 			pollingIntervalSeconds: params.get("pollingIntervalSeconds") ? Number.parseInt(params.get("pollingIntervalSeconds"), 10) : void 0
@@ -58,27 +175,74 @@ var PgBossSubscriber = class PgBossSubscriber {
 	async subscribe(messages, listener) {
 		if (!this.connection.isConnected()) await this.connection.connect();
 		const boss = this.connection.instance;
-		if (!boss) throw new Error("PgBoss instance not initialized");
+		if (!boss) throw new PgBossNotStarted();
+		const work = {
+			...this.options.batchSize && { batchSize: this.options.batchSize },
+			...this.options.pollingIntervalSeconds && { pollingIntervalSeconds: this.options.pollingIntervalSeconds }
+		};
+		const { topic, subscription } = this.options;
+		if (topic) {
+			if (!subscription) throw new PgBossSubscriptionNeedsName(topic);
+			const queue = topicEvent(topic, subscription);
+			await boss.createQueue(queue);
+			for (const type of messages) await boss.subscribe(topicEvent(topic, type), queue);
+			await boss.work(queue, work, async (jobs) => {
+				for (const job of jobs) {
+					const { data, carrier } = require_telemetry.withoutTraceKey(job.data);
+					await require_telemetry.consumeTraced({
+						system: "pgboss",
+						destination: topic,
+						type: data.type,
+						messageId: job.id
+					}, carrier, () => listener({
+						type: data.type,
+						payload: data.payload
+					}));
+				}
+			});
+			return;
+		}
 		for (const messageType of messages) {
 			await boss.createQueue(messageType);
-			await boss.work(messageType, {
-				...this.options.batchSize && { batchSize: this.options.batchSize },
-				...this.options.pollingIntervalSeconds && { pollingIntervalSeconds: this.options.pollingIntervalSeconds }
-			}, async (jobs) => {
+			await boss.work(messageType, work, async (jobs) => {
 				for (const job of jobs) {
-					const fullMessage = {
+					const { data, carrier } = require_telemetry.withoutTraceKey(job.data);
+					await require_telemetry.consumeTraced({
+						system: "pgboss",
+						destination: messageType,
 						type: job.name,
-						payload: job.data
-					};
-					await listener(fullMessage);
+						messageId: job.id
+					}, carrier, () => listener({
+						type: job.name,
+						payload: data
+					}));
 				}
 			});
 		}
 	}
 };
-
 //#endregion
-exports.PgBossConnection = require_PgBossConnection.PgBossConnection;
+//#region src/pgboss/driver.ts
+/**
+* `pgboss://` — queues and topics in Postgres. Register it with
+* `registerEventsDriver(pgbossEventsDriver)`; this subpath is the only one
+* that imports `pg-boss`.
+*/
+const pgbossEventsDriver = {
+	scheme: "pgboss",
+	connect: (url) => PgBossConnection.fromConnectionString(url),
+	publisher: (url, options) => PgBossPublisher.fromConnectionString(url, options),
+	publisherFor: (connection, options) => new PgBossPublisher(connection, options),
+	subscriber: (url) => PgBossSubscriber.fromConnectionString(url),
+	subscriberFor: (connection, options) => new PgBossSubscriber(connection, options)
+};
+//#endregion
+exports.PgBossConnection = PgBossConnection;
+exports.PgBossNotStarted = PgBossNotStarted;
 exports.PgBossPublisher = PgBossPublisher;
 exports.PgBossSubscriber = PgBossSubscriber;
+exports.PgBossSubscriptionNeedsName = PgBossSubscriptionNeedsName;
+exports.pgbossEventsDriver = pgbossEventsDriver;
+exports.topicEvent = topicEvent;
+
 //# sourceMappingURL=index.cjs.map

package/dist/pgboss/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["connection: PgBossConnection","connectionString: string","messages: TMessage[]","connection: PgBossConnection","options: PgBossSubscriberOptions","connectionString: string","messages: TMessage['type'][]","listener: (payload: TMessage) => Promise<void>"],"sources":["../../src/pgboss/PgBossPublisher.ts","../../src/pgboss/PgBossSubscriber.ts"],"sourcesContent":["import type { EventPublisher, PublishableMessage } from '../types';\nimport type { PgBossConnection } from './PgBossConnection';\n\nexport class PgBossPublisher<TMessage extends PublishableMessage<string, any>>\n\timplements EventPublisher<TMessage>\n{\n\tconstructor(private connection: PgBossConnection) {}\n\n\t/**\n\t * Create a PgBossPublisher from a connection string.\n\t * Format: pgboss://user:pass@host:5432/database?schema=pgboss\n\t */\n\tstatic async fromConnectionString<\n\t\tTMessage extends PublishableMessage<string, any>,\n\t>(connectionString: string): Promise<PgBossPublisher<TMessage>> {\n\t\tconst { PgBossConnection } = await import('./PgBossConnection');\n\t\tconst connection =\n\t\t\tawait PgBossConnection.fromConnectionString(connectionString);\n\t\treturn new PgBossPublisher<TMessage>(connection);\n\t}\n\n\tasync publish(messages: TMessage[]): Promise<void> {\n\t\tif (!this.connection.isConnected()) {\n\t\t\tawait this.connection.connect();\n\t\t}\n\n\t\tconst boss = this.connection.instance;\n\t\tif (!boss) {\n\t\t\tthrow new Error('PgBoss instance not initialized');\n\t\t}\n\n\t\t// Group jobs by queue name (v11+ requires per-queue insert calls)\n\t\tconst groups = new Map<string, { data: TMessage['payload'] }[]>();\n\t\tfor (const m of messages) {\n\t\t\tconst list = groups.get(m.type) ?? [];\n\t\t\tlist.push({ data: m.payload });\n\t\t\tgroups.set(m.type, list);\n\t\t}\n\n\t\tfor (const [name, jobs] of groups) {\n\t\t\tawait boss.createQueue(name);\n\t\t\tawait boss.insert(name, jobs);\n\t\t}\n\t}\n\n\tasync close(): Promise<void> {\n\t\t// Publisher doesn't own the connection\n\t}\n}\n","import type { EventSubscriber, PublishableMessage } from '../types';\nimport type { PgBossConnection } from './PgBossConnection';\n\nexport interface PgBossSubscriberOptions {\n\tbatchSize?: number;\n\tpollingIntervalSeconds?: number;\n}\n\nexport class PgBossSubscriber<TMessage extends PublishableMessage<string, any>>\n\timplements EventSubscriber<TMessage>\n{\n\tconstructor(\n\t\tprivate connection: PgBossConnection,\n\t\tprivate options: PgBossSubscriberOptions = {},\n\t) {}\n\n\t/**\n\t * Create a PgBossSubscriber from a connection string.\n\t * Format: pgboss://user:pass@host:5432/database?schema=pgboss&batchSize=5\n\t */\n\tstatic async fromConnectionString<\n\t\tTMessage extends PublishableMessage<string, any>,\n\t>(connectionString: string): Promise<PgBossSubscriber<TMessage>> {\n\t\tconst url = new URL(connectionString);\n\t\tconst params = url.searchParams;\n\n\t\tconst { PgBossConnection } = await import('./PgBossConnection');\n\t\tconst connection =\n\t\t\tawait PgBossConnection.fromConnectionString(connectionString);\n\n\t\tconst options: PgBossSubscriberOptions = {\n\t\t\tbatchSize: params.get('batchSize')\n\t\t\t\t? Number.parseInt(params.get('batchSize')!, 10)\n\t\t\t\t: undefined,\n\t\t\tpollingIntervalSeconds: params.get('pollingIntervalSeconds')\n\t\t\t\t? Number.parseInt(params.get('pollingIntervalSeconds')!, 10)\n\t\t\t\t: undefined,\n\t\t};\n\n\t\treturn new PgBossSubscriber<TMessage>(connection, options);\n\t}\n\n\tasync subscribe(\n\t\tmessages: TMessage['type'][],\n\t\tlistener: (payload: TMessage) => Promise<void>,\n\t): Promise<void> {\n\t\tif (!this.connection.isConnected()) {\n\t\t\tawait this.connection.connect();\n\t\t}\n\n\t\tconst boss = this.connection.instance;\n\t\tif (!boss) {\n\t\t\tthrow new Error('PgBoss instance not initialized');\n\t\t}\n\n\t\tfor (const messageType of messages) {\n\t\t\tawait boss.createQueue(messageType);\n\t\t\tawait boss.work(\n\t\t\t\tmessageType,\n\t\t\t\t{\n\t\t\t\t\t...(this.options.batchSize && {\n\t\t\t\t\t\tbatchSize: this.options.batchSize,\n\t\t\t\t\t}),\n\t\t\t\t\t...(this.options.pollingIntervalSeconds && {\n\t\t\t\t\t\tpollingIntervalSeconds: this.options.pollingIntervalSeconds,\n\t\t\t\t\t}),\n\t\t\t\t},\n\t\t\t\tasync (jobs) => {\n\t\t\t\t\tfor (const job of jobs) {\n\t\t\t\t\t\tconst fullMessage = {\n\t\t\t\t\t\t\ttype: job.name,\n\t\t\t\t\t\t\tpayload: job.data,\n\t\t\t\t\t\t} as TMessage;\n\n\t\t\t\t\t\tawait listener(fullMessage);\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t);\n\t\t}\n\t}\n}\n"],"mappings":";;;;AAGA,IAAa,kBAAb,MAAa,gBAEb;CACC,YAAoBA,YAA8B;EAA9B;CAAgC;;;;;CAMpD,aAAa,qBAEXC,kBAA8D;EAC/D,MAAM,EAAE,sCAAkB,GAAG,2CAAM;EACnC,MAAM,aACL,MAAM,mBAAiB,qBAAqB,iBAAiB;AAC9D,SAAO,IAAI,gBAA0B;CACrC;CAED,MAAM,QAAQC,UAAqC;AAClD,OAAK,KAAK,WAAW,aAAa,CACjC,OAAM,KAAK,WAAW,SAAS;EAGhC,MAAM,OAAO,KAAK,WAAW;AAC7B,OAAK,KACJ,OAAM,IAAI,MAAM;EAIjB,MAAM,yBAAS,IAAI;AACnB,OAAK,MAAM,KAAK,UAAU;GACzB,MAAM,OAAO,OAAO,IAAI,EAAE,KAAK,IAAI,CAAE;AACrC,QAAK,KAAK,EAAE,MAAM,EAAE,QAAS,EAAC;AAC9B,UAAO,IAAI,EAAE,MAAM,KAAK;EACxB;AAED,OAAK,MAAM,CAAC,MAAM,KAAK,IAAI,QAAQ;AAClC,SAAM,KAAK,YAAY,KAAK;AAC5B,SAAM,KAAK,OAAO,MAAM,KAAK;EAC7B;CACD;CAED,MAAM,QAAuB,CAE5B;AACD;;;;ACxCD,IAAa,mBAAb,MAAa,iBAEb;CACC,YACSC,YACAC,UAAmC,CAAE,GAC5C;EAFO;EACA;CACL;;;;;CAMJ,aAAa,qBAEXC,kBAA+D;EAChE,MAAM,MAAM,IAAI,IAAI;EACpB,MAAM,SAAS,IAAI;EAEnB,MAAM,EAAE,sCAAkB,GAAG,2CAAM;EACnC,MAAM,aACL,MAAM,mBAAiB,qBAAqB,iBAAiB;EAE9D,MAAMD,UAAmC;GACxC,WAAW,OAAO,IAAI,YAAY,GAC/B,OAAO,SAAS,OAAO,IAAI,YAAY,EAAG,GAAG;GAEhD,wBAAwB,OAAO,IAAI,yBAAyB,GACzD,OAAO,SAAS,OAAO,IAAI,yBAAyB,EAAG,GAAG;EAE7D;AAED,SAAO,IAAI,iBAA2B,YAAY;CAClD;CAED,MAAM,UACLE,UACAC,UACgB;AAChB,OAAK,KAAK,WAAW,aAAa,CACjC,OAAM,KAAK,WAAW,SAAS;EAGhC,MAAM,OAAO,KAAK,WAAW;AAC7B,OAAK,KACJ,OAAM,IAAI,MAAM;AAGjB,OAAK,MAAM,eAAe,UAAU;AACnC,SAAM,KAAK,YAAY,YAAY;AACnC,SAAM,KAAK,KACV,aACA;IACC,GAAI,KAAK,QAAQ,aAAa,EAC7B,WAAW,KAAK,QAAQ,UACxB;IACD,GAAI,KAAK,QAAQ,0BAA0B,EAC1C,wBAAwB,KAAK,QAAQ,uBACrC;GACD,GACD,OAAO,SAAS;AACf,SAAK,MAAM,OAAO,MAAM;KACvB,MAAM,cAAc;MACnB,MAAM,IAAI;MACV,SAAS,IAAI;KACb;AAED,WAAM,SAAS,YAAY;IAC3B;GACD,EACD;EACD;CACD;AACD"}
+{"version":3,"file":"index.cjs","names":["PgBoss","publishTraced","withTraceKey","withoutTraceKey","consumeTraced"],"sources":["../../src/pgboss/PgBossConnection.ts","../../src/pgboss/errors.ts","../../src/pgboss/PgBossPublisher.ts","../../src/pgboss/PgBossSubscriber.ts","../../src/pgboss/driver.ts"],"sourcesContent":["import { PgBoss } from 'pg-boss';\nimport type { EventConnection } from '../types';\nimport { EventPublisherType } from '../types';\n\nexport interface PgBossConnectionConfig {\n\tconnectionString: string;\n\tschema?: string;\n\t/**\n\t * Who this connection is to Postgres. Defaults to `GKM_APP_NAME`, which a\n\t * generated entry sets to the construct it runs — so the broker's\n\t * connections are named for the process that holds them, as its database\n\t * pools are, rather than all being `pgboss`.\n\t */\n\tapplicationName?: string;\n}\n\nexport class PgBossConnection implements EventConnection {\n\treadonly type = EventPublisherType.PgBoss;\n\tprivate boss?: PgBoss;\n\tprivate connecting?: Promise<void>;\n\n\tconstructor(private config: PgBossConnectionConfig) {}\n\n\t/**\n\t * Create a PgBossConnection from a connection string.\n\t * Format: pgboss://user:pass@host:5432/database?schema=pgboss\n\t */\n\tstatic async fromConnectionString(\n\t\tconnectionString: string,\n\t): Promise<PgBossConnection> {\n\t\tconst url = new URL(connectionString);\n\t\tconst params = url.searchParams;\n\n\t\tconst postgresUrl = `postgres://${url.username ? `${url.username}:${url.password}@` : ''}${url.host}${url.pathname}`;\n\n\t\tconst config: PgBossConnectionConfig = {\n\t\t\tconnectionString: postgresUrl,\n\t\t\tschema: params.get('schema') || undefined,\n\t\t};\n\n\t\tconst connection = new PgBossConnection(config);\n\t\tawait connection.connect();\n\t\treturn connection;\n\t}\n\n\tasync connect(): Promise<void> {\n\t\tif (this.boss) return;\n\n\t\tif (this.connecting) {\n\t\t\tawait this.connecting;\n\t\t\treturn;\n\t\t}\n\n\t\tthis.connecting = (async () => {\n\t\t\ttry {\n\t\t\t\tconst applicationName =\n\t\t\t\t\tthis.config.applicationName ?? process.env.GKM_APP_NAME;\n\t\t\t\tconst boss = new PgBoss({\n\t\t\t\t\tconnectionString: this.config.connectionString,\n\t\t\t\t\t...(this.config.schema && { schema: this.config.schema }),\n\t\t\t\t\t...(applicationName && { application_name: applicationName }),\n\t\t\t\t});\n\n\t\t\t\tawait boss.start();\n\t\t\t\tthis.boss = boss;\n\t\t\t} catch (error) {\n\t\t\t\tthis.cleanup();\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t})();\n\n\t\tawait this.connecting;\n\t\tthis.connecting = undefined;\n\t}\n\n\tasync close(): Promise<void> {\n\t\ttry {\n\t\t\tawait this.boss?.stop({ graceful: true });\n\t\t} catch {\n\t\t\t// Ignore errors during close\n\t\t} finally {\n\t\t\tthis.cleanup();\n\t\t}\n\t}\n\n\tisConnected(): boolean {\n\t\treturn !!this.boss;\n\t}\n\n\tprivate cleanup(): void {\n\t\tthis.boss = undefined;\n\t\tthis.connecting = undefined;\n\t}\n\n\t/**\n\t * Get the underlying pg-boss instance for publishing/subscribing\n\t */\n\tget instance(): PgBoss | undefined {\n\t\treturn this.boss;\n\t}\n}\n","// Beside the adapter but apart from its connection module, which imports\n// the broker's client: the publisher and subscriber load that lazily, and\n// importing an error class from it would load it eagerly.\n\n/** pg-boss connected but its instance never started. */\nexport class PgBossNotStarted extends Error {\n\tconstructor() {\n\t\tsuper(\n\t\t\t'pg-boss did not start. Check the database in the connection string is reachable and the role may create the pg-boss schema.',\n\t\t);\n\t\tthis.name = 'PgBossNotStarted';\n\t}\n}\n\n/** A topic subscription with no name to give the subscriber's own queue. */\nexport class PgBossSubscriptionNeedsName extends Error {\n\tconstructor(readonly topic: string) {\n\t\tsuper(\n\t\t\t`Subscribing to topic '${topic}' on pg-boss needs a subscription name: ` +\n\t\t\t\t'each subscriber drains a queue of its own, and that queue is named ' +\n\t\t\t\t'for it. Pass `subscription`.',\n\t\t);\n\t\tthis.name = 'PgBossSubscriptionNeedsName';\n\t}\n}\n","import { publishTraced, withTraceKey } from '../telemetry';\nimport type { EventPublisher, PublishableMessage } from '../types';\nimport { PgBossNotStarted } from './errors';\nimport type { PgBossConnection } from './PgBossConnection';\n\nexport interface PgBossPublisherOptions {\n\t/**\n\t * Publishing to a topic: each message is fanned out to every subscriber's\n\t * own queue rather than inserted into one shared queue. Without it, a\n\t * message goes to the queue named by its type — a work queue, one consumer.\n\t */\n\ttopic?: string;\n}\n\n/** The pg-boss event a topic's message type is published as. */\nexport function topicEvent(topic: string, type: string): string {\n\treturn `${topic}/${type}`;\n}\n\nexport class PgBossPublisher<TMessage extends PublishableMessage<string, any>>\n\timplements EventPublisher<TMessage>\n{\n\tconstructor(\n\t\tprivate connection: PgBossConnection,\n\t\tprivate options: PgBossPublisherOptions = {},\n\t) {}\n\n\t/**\n\t * Create a PgBossPublisher from a connection string.\n\t * Format: pgboss://user:pass@host:5432/database?schema=pgboss\n\t */\n\tstatic async fromConnectionString<\n\t\tTMessage extends PublishableMessage<string, any>,\n\t>(\n\t\tconnectionString: string,\n\t\toptions: PgBossPublisherOptions = {},\n\t): Promise<PgBossPublisher<TMessage>> {\n\t\tconst { PgBossConnection } = await import('./PgBossConnection');\n\t\tconst connection =\n\t\t\tawait PgBossConnection.fromConnectionString(connectionString);\n\t\treturn new PgBossPublisher<TMessage>(connection, options);\n\t}\n\n\tasync publish(messages: TMessage[]): Promise<void> {\n\t\tif (!this.connection.isConnected()) {\n\t\t\tawait this.connection.connect();\n\t\t}\n\n\t\tconst boss = this.connection.instance;\n\t\tif (!boss) {\n\t\t\tthrow new PgBossNotStarted();\n\t\t}\n\n\t\t// A topic: pg-boss copies the job into every queue subscribed to the\n\t\t// event — one per subscriber — so each subscriber sees each message.\n\t\t// The type rides in the data, because the job is named for the queue.\n\t\t//\n\t\t// pg-boss has no header field, so the trace context rides in the data\n\t\t// too, under a reserved key the subscriber removes before the handler.\n\t\tconst { topic } = this.options;\n\t\tif (topic) {\n\t\t\tawait publishTraced(\n\t\t\t\tmessages,\n\t\t\t\t(m) => ({ system: 'pgboss', destination: topic, type: m.type }),\n\t\t\t\tasync (carriers) => {\n\t\t\t\t\tfor (const [i, m] of messages.entries()) {\n\t\t\t\t\t\tawait boss.publish(\n\t\t\t\t\t\t\ttopicEvent(topic, m.type),\n\t\t\t\t\t\t\twithTraceKey({ type: m.type, payload: m.payload }, carriers[i]),\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t);\n\t\t\treturn;\n\t\t}\n\n\t\tawait publishTraced(\n\t\t\tmessages,\n\t\t\t(m) => ({ system: 'pgboss', destination: m.type, type: m.type }),\n\t\t\tasync (carriers) => {\n\t\t\t\t// Group jobs by queue name (v11+ requires per-queue insert calls)\n\t\t\t\tconst groups = new Map<string, { data: TMessage['payload'] }[]>();\n\t\t\t\tfor (const [i, m] of messages.entries()) {\n\t\t\t\t\tconst list = groups.get(m.type) ?? [];\n\t\t\t\t\tlist.push({ data: withTraceKey(m.payload, carriers[i]) });\n\t\t\t\t\tgroups.set(m.type, list);\n\t\t\t\t}\n\n\t\t\t\tfor (const [name, jobs] of groups) {\n\t\t\t\t\tawait boss.createQueue(name);\n\t\t\t\t\tawait boss.insert(name, jobs);\n\t\t\t\t}\n\t\t\t},\n\t\t);\n\t}\n\n\tasync close(): Promise<void> {\n\t\t// Publisher doesn't own the connection\n\t}\n}\n","import { consumeTraced, withoutTraceKey } from '../telemetry';\nimport type { EventSubscriber, PublishableMessage } from '../types';\nimport { PgBossNotStarted, PgBossSubscriptionNeedsName } from './errors';\nimport type { PgBossConnection } from './PgBossConnection';\nimport { topicEvent } from './PgBossPublisher';\n\nexport interface PgBossSubscriberOptions {\n\tbatchSize?: number;\n\tpollingIntervalSeconds?: number;\n\t/**\n\t * Subscribing to a topic. Each subscriber then drains a queue of its own,\n\t * `<topic>/<subscription>`, bound to the events it names — so every\n\t * subscriber sees every message, and replicas of one subscriber share it.\n\t * Without it, messages are drained from the queue named by their type:\n\t * work shared among whoever drains it.\n\t */\n\ttopic?: string;\n\t/** The subscriber's own name on the topic. Required with `topic`. */\n\tsubscription?: string;\n}\n\nexport class PgBossSubscriber<TMessage extends PublishableMessage<string, any>>\n\timplements EventSubscriber<TMessage>\n{\n\tconstructor(\n\t\tprivate connection: PgBossConnection,\n\t\tprivate options: PgBossSubscriberOptions = {},\n\t) {}\n\n\t/**\n\t * Create a PgBossSubscriber from a connection string.\n\t * Format: pgboss://user:pass@host:5432/database?schema=pgboss&batchSize=5\n\t */\n\tstatic async fromConnectionString<\n\t\tTMessage extends PublishableMessage<string, any>,\n\t>(connectionString: string): Promise<PgBossSubscriber<TMessage>> {\n\t\tconst url = new URL(connectionString);\n\t\tconst params = url.searchParams;\n\n\t\tconst { PgBossConnection } = await import('./PgBossConnection');\n\t\tconst connection =\n\t\t\tawait PgBossConnection.fromConnectionString(connectionString);\n\n\t\tconst options: PgBossSubscriberOptions = {\n\t\t\tbatchSize: params.get('batchSize')\n\t\t\t\t? Number.parseInt(params.get('batchSize')!, 10)\n\t\t\t\t: undefined,\n\t\t\tpollingIntervalSeconds: params.get('pollingIntervalSeconds')\n\t\t\t\t? Number.parseInt(params.get('pollingIntervalSeconds')!, 10)\n\t\t\t\t: undefined,\n\t\t};\n\n\t\treturn new PgBossSubscriber<TMessage>(connection, options);\n\t}\n\n\tasync subscribe(\n\t\tmessages: TMessage['type'][],\n\t\tlistener: (payload: TMessage) => Promise<void>,\n\t): Promise<void> {\n\t\tif (!this.connection.isConnected()) {\n\t\t\tawait this.connection.connect();\n\t\t}\n\n\t\tconst boss = this.connection.instance;\n\t\tif (!boss) {\n\t\t\tthrow new PgBossNotStarted();\n\t\t}\n\n\t\tconst work = {\n\t\t\t...(this.options.batchSize && { batchSize: this.options.batchSize }),\n\t\t\t...(this.options.pollingIntervalSeconds && {\n\t\t\t\tpollingIntervalSeconds: this.options.pollingIntervalSeconds,\n\t\t\t}),\n\t\t};\n\n\t\tconst { topic, subscription } = this.options;\n\t\tif (topic) {\n\t\t\tif (!subscription) throw new PgBossSubscriptionNeedsName(topic);\n\n\t\t\tconst queue = topicEvent(topic, subscription);\n\t\t\tawait boss.createQueue(queue);\n\t\t\tfor (const type of messages) {\n\t\t\t\tawait boss.subscribe(topicEvent(topic, type), queue);\n\t\t\t}\n\t\t\tawait boss.work<{ type: string; payload: unknown }>(\n\t\t\t\tqueue,\n\t\t\t\twork,\n\t\t\t\tasync (jobs) => {\n\t\t\t\t\tfor (const job of jobs) {\n\t\t\t\t\t\tconst { data, carrier } = withoutTraceKey(job.data);\n\t\t\t\t\t\tawait consumeTraced(\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\tsystem: 'pgboss',\n\t\t\t\t\t\t\t\tdestination: topic,\n\t\t\t\t\t\t\t\ttype: data.type,\n\t\t\t\t\t\t\t\tmessageId: job.id,\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\tcarrier,\n\t\t\t\t\t\t\t() =>\n\t\t\t\t\t\t\t\tlistener({\n\t\t\t\t\t\t\t\t\ttype: data.type,\n\t\t\t\t\t\t\t\t\tpayload: data.payload,\n\t\t\t\t\t\t\t\t} as TMessage),\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t);\n\t\t\treturn;\n\t\t}\n\n\t\tfor (const messageType of messages) {\n\t\t\tawait boss.createQueue(messageType);\n\t\t\tawait boss.work(messageType, work, async (jobs) => {\n\t\t\t\tfor (const job of jobs) {\n\t\t\t\t\t// The trace context is taken out of the data here, so the\n\t\t\t\t\t// handler's payload is exactly what was published.\n\t\t\t\t\tconst { data, carrier } = withoutTraceKey(job.data);\n\t\t\t\t\tawait consumeTraced(\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tsystem: 'pgboss',\n\t\t\t\t\t\t\tdestination: messageType,\n\t\t\t\t\t\t\ttype: job.name,\n\t\t\t\t\t\t\tmessageId: job.id,\n\t\t\t\t\t\t},\n\t\t\t\t\t\tcarrier,\n\t\t\t\t\t\t() => listener({ type: job.name, payload: data } as TMessage),\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t});\n\t\t}\n\t}\n}\n","import type { EventsDriver } from '../registry';\nimport { EventPublisherType } from '../types';\nimport { PgBossConnection } from './PgBossConnection';\nimport { PgBossPublisher } from './PgBossPublisher';\nimport { PgBossSubscriber } from './PgBossSubscriber';\n\n/**\n * `pgboss://` — queues and topics in Postgres. Register it with\n * `registerEventsDriver(pgbossEventsDriver)`; this subpath is the only one\n * that imports `pg-boss`.\n */\nexport const pgbossEventsDriver: EventsDriver = {\n\tscheme: EventPublisherType.PgBoss,\n\tconnect: (url) => PgBossConnection.fromConnectionString(url),\n\tpublisher: (url, options) =>\n\t\tPgBossPublisher.fromConnectionString(url, options),\n\tpublisherFor: (connection, options) =>\n\t\tnew PgBossPublisher(connection as PgBossConnection, options),\n\tsubscriber: (url) => PgBossSubscriber.fromConnectionString(url),\n\tsubscriberFor: (connection, options) =>\n\t\tnew PgBossSubscriber(connection as PgBossConnection, options),\n};\n"],"mappings":"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"}

package/dist/pgboss/index.d.cts

@@ -1,12 +1,37 @@
-import { EventConnection, EventPublisher, EventPublisherType, EventSubscriber, PublishableMessage } from "../types-BmixGrOD.cjs";
+import { d as EventPublisher, f as EventPublisherType, g as PublishableMessage, p as EventSubscriber, t as EventsDriver, u as EventConnection } from "../registry-DIx25Q5s.cjs";
 import { PgBoss } from "pg-boss";
-
+//#region src/pgboss/driver.d.ts
+/**
+ * `pgboss://` — queues and topics in Postgres. Register it with
+ * `registerEventsDriver(pgbossEventsDriver)`; this subpath is the only one
+ * that imports `pg-boss`.
+ */
+export declare const pgbossEventsDriver: EventsDriver;
+//#endregion
+//#region src/pgboss/errors.d.ts
+/** pg-boss connected but its instance never started. */
+export declare class PgBossNotStarted extends Error {
+  constructor();
+}
+/** A topic subscription with no name to give the subscriber's own queue. */
+export declare class PgBossSubscriptionNeedsName extends Error {
+  readonly topic: string;
+  constructor(topic: string);
+}
+//#endregion
 //#region src/pgboss/PgBossConnection.d.ts
 interface PgBossConnectionConfig {
   connectionString: string;
   schema?: string;
+  /**
+   * Who this connection is to Postgres. Defaults to `GKM_APP_NAME`, which a
+   * generated entry sets to the construct it runs — so the broker's
+   * connections are named for the process that holds them, as its database
+   * pools are, rather than all being `pgboss`.
+   */
+  applicationName?: string;
 }
-declare class PgBossConnection implements EventConnection {
+export declare class PgBossConnection implements EventConnection {
   private config;
   readonly type = EventPublisherType.PgBoss;
   private boss?;
@@ -26,28 +51,47 @@ declare class PgBossConnection implements EventConnection {
    */
   get instance(): PgBoss | undefined;
 }
-//# sourceMappingURL=PgBossConnection.d.ts.map
 //#endregion
 //#region src/pgboss/PgBossPublisher.d.ts
-declare class PgBossPublisher<TMessage extends PublishableMessage<string, any>> implements EventPublisher<TMessage> {
+interface PgBossPublisherOptions {
+  /**
+   * Publishing to a topic: each message is fanned out to every subscriber's
+   * own queue rather than inserted into one shared queue. Without it, a
+   * message goes to the queue named by its type — a work queue, one consumer.
+   */
+  topic?: string;
+}
+/** The pg-boss event a topic's message type is published as. */
+export declare function topicEvent(topic: string, type: string): string;
+export declare class PgBossPublisher<TMessage extends PublishableMessage<string, any>> implements EventPublisher<TMessage> {
   private connection;
-  constructor(connection: PgBossConnection);
+  private options;
+  constructor(connection: PgBossConnection, options?: PgBossPublisherOptions);
   /**
    * Create a PgBossPublisher from a connection string.
    * Format: pgboss://user:pass@host:5432/database?schema=pgboss
    */
-  static fromConnectionString<TMessage extends PublishableMessage<string, any>>(connectionString: string): Promise<PgBossPublisher<TMessage>>;
+  static fromConnectionString<TMessage extends PublishableMessage<string, any>>(connectionString: string, options?: PgBossPublisherOptions): Promise<PgBossPublisher<TMessage>>;
   publish(messages: TMessage[]): Promise<void>;
   close(): Promise<void>;
 }
-//# sourceMappingURL=PgBossPublisher.d.ts.map
 //#endregion
 //#region src/pgboss/PgBossSubscriber.d.ts
 interface PgBossSubscriberOptions {
   batchSize?: number;
   pollingIntervalSeconds?: number;
+  /**
+   * Subscribing to a topic. Each subscriber then drains a queue of its own,
+   * `<topic>/<subscription>`, bound to the events it names — so every
+   * subscriber sees every message, and replicas of one subscriber share it.
+   * Without it, messages are drained from the queue named by their type:
+   * work shared among whoever drains it.
+   */
+  topic?: string;
+  /** The subscriber's own name on the topic. Required with `topic`. */
+  subscription?: string;
 }
-declare class PgBossSubscriber<TMessage extends PublishableMessage<string, any>> implements EventSubscriber<TMessage> {
+export declare class PgBossSubscriber<TMessage extends PublishableMessage<string, any>> implements EventSubscriber<TMessage> {
   private connection;
   private options;
   constructor(connection: PgBossConnection, options?: PgBossSubscriberOptions);
@@ -58,8 +102,6 @@ declare class PgBossSubscriber<TMessage extends PublishableMessage<string, any>>
   static fromConnectionString<TMessage extends PublishableMessage<string, any>>(connectionString: string): Promise<PgBossSubscriber<TMessage>>;
   subscribe(messages: TMessage['type'][], listener: (payload: TMessage) => Promise<void>): Promise<void>;
 }
-//# sourceMappingURL=PgBossSubscriber.d.ts.map
-
 //#endregion
-export { PgBossConnection, PgBossConnectionConfig, PgBossPublisher, PgBossSubscriber, PgBossSubscriberOptions };
+export type { PgBossConnectionConfig, PgBossPublisherOptions, PgBossSubscriberOptions };
 //# sourceMappingURL=index.d.cts.map

package/dist/pgboss/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/pgboss/PgBossConnection.ts","../../src/pgboss/PgBossPublisher.ts","../../src/pgboss/PgBossSubscriber.ts"],"sourcesContent":[],"mappings":";;;;UAIiB,sBAAA;EAAA,gBAAA,EAAA,MAAA;EAKJ,MAAA,CAAA,EAAA,MAAA;;AACC,cADD,gBAAA,YAA4B,eAC3B,CAAA;EAAA,QAIe,MAAA;EAAsB,SAQvC,IAAA,GAZE,kBAAA,CAAA,MAAA;EAYc,QAAxB,IAAA;EAAO,QAgBO,UAAA;EAAO,WA2BT,CAAA,MAAA,EAnDa,sBAmDb;EAAO;;AAxDiC;;yDAapD,QAAQ;aAgBM;ECnCL,KAAA,CAAA,CAAA,ED8DG,OC9DH,CAAA,IAAe,CAAA;EAAA,WAAA,CAAA,CAAA,EAAA,OAAA;EAAA,QAAkB,OAAA;EAAkB;;;EAU3B,IACiB,QAAA,CAAA,CAAA,EDyErC,MCzEqC,GAAA,SAAA;;;;;cAXzC,iCAAiC,4CAClC,eAAe;;EDAV,WAAA,CAAA,UAAA,ECEgB,gBDFM;EAK1B;;;;EAKsC,OAQvC,oBAAA,CAAA,iBCTO,kBDSP,CAAA,MAAA,EAAA,GAAA,CAAA,CAAA,CAAA,gBAAA,EAAA,MAAA,CAAA,ECRkB,ODQlB,CCR0B,eDQ1B,CCR0C,QDQ1C,CAAA,CAAA;EAAgB,OAAxB,CAAA,QAAA,ECDqB,QDCrB,EAAA,CAAA,ECDkC,ODClC,CAAA,IAAA,CAAA;EAAO,KAgBO,CAAA,CAAA,ECOF,ODPE,CAAA,IAAA,CAAA;;;;;UEnCD,uBAAA;;EFCA,sBAAA,CAAA,EAAsB,MAAA;AAKvC;AAA8B,cEDjB,gBFCiB,CAAA,iBEDiB,kBFCjB,CAAA,MAAA,EAAA,GAAA,CAAA,CAAA,YEAlB,eFAkB,CEAF,QFAE,CAAA,CAAA;EAAA,QAChB,UAAA;EAAA,QAIe,OAAA;EAAsB,WAQvC,CAAA,UAAA,EEVU,gBFUV,EAAA,OAAA,CAAA,EETO,uBFSP;EAAgB;;;;EAiEL,OA9EkB,oBAAA,CAAA,iBEYtB,kBFZsB,CAAA,MAAA,EAAA,GAAA,CAAA,CAAA,CAAA,gBAAA,EAAA,MAAA,CAAA,EEaX,OFbW,CEaH,gBFbG,CEac,QFbd,CAAA,CAAA;EAAe,SAAA,CAAA,QAAA,EEkC5C,QFlC4C,CAAA,MAAA,CAAA,EAAA,EAAA,QAAA,EAAA,CAAA,OAAA,EEmClC,QFnCkC,EAAA,GEmCrB,OFnCqB,CAAA,IAAA,CAAA,CAAA,EEoCpD,OFpCoD,CAAA,IAAA,CAAA"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/pgboss/driver.ts","../../src/pgboss/errors.ts","../../src/pgboss/PgBossConnection.ts","../../src/pgboss/PgBossPublisher.ts","../../src/pgboss/PgBossSubscriber.ts"],"mappings":";;;;;;;;qBAWa,oBAAoB;;;;qBCNpB,yBAAyB;EACrC;;;qBASY,oCAAoC;WAC3B;EAArB,YAAqB;;;;UCZL;EAChB;EACA;;;;;;;EAOA;;qBAGY,4BAA4B;UAKpB;WAJX,OAAI,mBAAA;UACL;UACA;EAER,YAAoB,QAAQ;;;;;SAMf,qBACZ,2BACE,QAAQ;EAgBL,WAAW;EA8BX,SAAS;EAUf;UAIQ;;;;MAQJ,YAAY;;;;UC5FA;;;;;;EAMhB;;;wBAIe,WAAW,eAAe;qBAI7B,gBAAgB,iBAAiB,4CAClC,eAAe;UAGjB;UACA;EAFT,YACS,YAAY,kBACZ,UAAS;;;;;SAOL,qBACZ,iBAAiB,iCAEjB,0BACA,UAAS,yBACP,QAAQ,gBAAgB;EAOrB,QAAQ,UAAU,aAAa;EAqD/B,SAAS;;;;UC1FC;EAChB;EACA;;;;;;;;EAQA;;EAEA;;qBAGY,iBAAiB,iBAAiB,4CACnC,gBAAgB;UAGlB;UACA;EAFT,YACS,YAAY,kBACZ,UAAS;;;;;SAOL,qBACZ,iBAAiB,iCAChB,2BAA2B,QAAQ,iBAAiB;EAoBhD,UACL,UAAU,oBACV,WAAW,SAAS,aAAa,gBAC/B"}

package/dist/pgboss/index.d.mts

@@ -1,12 +1,37 @@
-import { EventConnection, EventPublisher, EventPublisherType, EventSubscriber, PublishableMessage } from "../types-DycjsYms.mjs";
+import { d as EventPublisher, f as EventPublisherType, g as PublishableMessage, p as EventSubscriber, t as EventsDriver, u as EventConnection } from "../registry-DIx25Q5s.mjs";
 import { PgBoss } from "pg-boss";
-
+//#region src/pgboss/driver.d.ts
+/**
+ * `pgboss://` — queues and topics in Postgres. Register it with
+ * `registerEventsDriver(pgbossEventsDriver)`; this subpath is the only one
+ * that imports `pg-boss`.
+ */
+export declare const pgbossEventsDriver: EventsDriver;
+//#endregion
+//#region src/pgboss/errors.d.ts
+/** pg-boss connected but its instance never started. */
+export declare class PgBossNotStarted extends Error {
+  constructor();
+}
+/** A topic subscription with no name to give the subscriber's own queue. */
+export declare class PgBossSubscriptionNeedsName extends Error {
+  readonly topic: string;
+  constructor(topic: string);
+}
+//#endregion
 //#region src/pgboss/PgBossConnection.d.ts
 interface PgBossConnectionConfig {
   connectionString: string;
   schema?: string;
+  /**
+   * Who this connection is to Postgres. Defaults to `GKM_APP_NAME`, which a
+   * generated entry sets to the construct it runs — so the broker's
+   * connections are named for the process that holds them, as its database
+   * pools are, rather than all being `pgboss`.
+   */
+  applicationName?: string;
 }
-declare class PgBossConnection implements EventConnection {
+export declare class PgBossConnection implements EventConnection {
   private config;
   readonly type = EventPublisherType.PgBoss;
   private boss?;
@@ -26,28 +51,47 @@ declare class PgBossConnection implements EventConnection {
    */
   get instance(): PgBoss | undefined;
 }
-//# sourceMappingURL=PgBossConnection.d.ts.map
 //#endregion
 //#region src/pgboss/PgBossPublisher.d.ts
-declare class PgBossPublisher<TMessage extends PublishableMessage<string, any>> implements EventPublisher<TMessage> {
+interface PgBossPublisherOptions {
+  /**
+   * Publishing to a topic: each message is fanned out to every subscriber's
+   * own queue rather than inserted into one shared queue. Without it, a
+   * message goes to the queue named by its type — a work queue, one consumer.
+   */
+  topic?: string;
+}
+/** The pg-boss event a topic's message type is published as. */
+export declare function topicEvent(topic: string, type: string): string;
+export declare class PgBossPublisher<TMessage extends PublishableMessage<string, any>> implements EventPublisher<TMessage> {
   private connection;
-  constructor(connection: PgBossConnection);
+  private options;
+  constructor(connection: PgBossConnection, options?: PgBossPublisherOptions);
   /**
    * Create a PgBossPublisher from a connection string.
    * Format: pgboss://user:pass@host:5432/database?schema=pgboss
    */
-  static fromConnectionString<TMessage extends PublishableMessage<string, any>>(connectionString: string): Promise<PgBossPublisher<TMessage>>;
+  static fromConnectionString<TMessage extends PublishableMessage<string, any>>(connectionString: string, options?: PgBossPublisherOptions): Promise<PgBossPublisher<TMessage>>;
   publish(messages: TMessage[]): Promise<void>;
   close(): Promise<void>;
 }
-//# sourceMappingURL=PgBossPublisher.d.ts.map
 //#endregion
 //#region src/pgboss/PgBossSubscriber.d.ts
 interface PgBossSubscriberOptions {
   batchSize?: number;
   pollingIntervalSeconds?: number;
+  /**
+   * Subscribing to a topic. Each subscriber then drains a queue of its own,
+   * `<topic>/<subscription>`, bound to the events it names — so every
+   * subscriber sees every message, and replicas of one subscriber share it.
+   * Without it, messages are drained from the queue named by their type:
+   * work shared among whoever drains it.
+   */
+  topic?: string;
+  /** The subscriber's own name on the topic. Required with `topic`. */
+  subscription?: string;
 }
-declare class PgBossSubscriber<TMessage extends PublishableMessage<string, any>> implements EventSubscriber<TMessage> {
+export declare class PgBossSubscriber<TMessage extends PublishableMessage<string, any>> implements EventSubscriber<TMessage> {
   private connection;
   private options;
   constructor(connection: PgBossConnection, options?: PgBossSubscriberOptions);
@@ -58,8 +102,6 @@ declare class PgBossSubscriber<TMessage extends PublishableMessage<string, any>>
   static fromConnectionString<TMessage extends PublishableMessage<string, any>>(connectionString: string): Promise<PgBossSubscriber<TMessage>>;
   subscribe(messages: TMessage['type'][], listener: (payload: TMessage) => Promise<void>): Promise<void>;
 }
-//# sourceMappingURL=PgBossSubscriber.d.ts.map
-
 //#endregion
-export { PgBossConnection, PgBossConnectionConfig, PgBossPublisher, PgBossSubscriber, PgBossSubscriberOptions };
+export type { PgBossConnectionConfig, PgBossPublisherOptions, PgBossSubscriberOptions };
 //# sourceMappingURL=index.d.mts.map

package/dist/pgboss/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/pgboss/PgBossConnection.ts","../../src/pgboss/PgBossPublisher.ts","../../src/pgboss/PgBossSubscriber.ts"],"sourcesContent":[],"mappings":";;;;UAIiB,sBAAA;EAAA,gBAAA,EAAA,MAAA;EAKJ,MAAA,CAAA,EAAA,MAAA;;AACC,cADD,gBAAA,YAA4B,eAC3B,CAAA;EAAA,QAIe,MAAA;EAAsB,SAQvC,IAAA,GAZE,kBAAA,CAAA,MAAA;EAYc,QAAxB,IAAA;EAAO,QAgBO,UAAA;EAAO,WA2BT,CAAA,MAAA,EAnDa,sBAmDb;EAAO;;AAxDiC;;yDAapD,QAAQ;aAgBM;ECnCL,KAAA,CAAA,CAAA,ED8DG,OC9DH,CAAA,IAAe,CAAA;EAAA,WAAA,CAAA,CAAA,EAAA,OAAA;EAAA,QAAkB,OAAA;EAAkB;;;EAU3B,IACiB,QAAA,CAAA,CAAA,EDyErC,MCzEqC,GAAA,SAAA;;;;;cAXzC,iCAAiC,4CAClC,eAAe;;EDAV,WAAA,CAAA,UAAA,ECEgB,gBDFM;EAK1B;;;;EAKsC,OAQvC,oBAAA,CAAA,iBCTO,kBDSP,CAAA,MAAA,EAAA,GAAA,CAAA,CAAA,CAAA,gBAAA,EAAA,MAAA,CAAA,ECRkB,ODQlB,CCR0B,eDQ1B,CCR0C,QDQ1C,CAAA,CAAA;EAAgB,OAAxB,CAAA,QAAA,ECDqB,QDCrB,EAAA,CAAA,ECDkC,ODClC,CAAA,IAAA,CAAA;EAAO,KAgBO,CAAA,CAAA,ECOF,ODPE,CAAA,IAAA,CAAA;;;;;UEnCD,uBAAA;;EFCA,sBAAA,CAAA,EAAsB,MAAA;AAKvC;AAA8B,cEDjB,gBFCiB,CAAA,iBEDiB,kBFCjB,CAAA,MAAA,EAAA,GAAA,CAAA,CAAA,YEAlB,eFAkB,CEAF,QFAE,CAAA,CAAA;EAAA,QAChB,UAAA;EAAA,QAIe,OAAA;EAAsB,WAQvC,CAAA,UAAA,EEVU,gBFUV,EAAA,OAAA,CAAA,EETO,uBFSP;EAAgB;;;;EAiEL,OA9EkB,oBAAA,CAAA,iBEYtB,kBFZsB,CAAA,MAAA,EAAA,GAAA,CAAA,CAAA,CAAA,gBAAA,EAAA,MAAA,CAAA,EEaX,OFbW,CEaH,gBFbG,CEac,QFbd,CAAA,CAAA;EAAe,SAAA,CAAA,QAAA,EEkC5C,QFlC4C,CAAA,MAAA,CAAA,EAAA,EAAA,QAAA,EAAA,CAAA,OAAA,EEmClC,QFnCkC,EAAA,GEmCrB,OFnCqB,CAAA,IAAA,CAAA,CAAA,EEoCpD,OFpCoD,CAAA,IAAA,CAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/pgboss/driver.ts","../../src/pgboss/errors.ts","../../src/pgboss/PgBossConnection.ts","../../src/pgboss/PgBossPublisher.ts","../../src/pgboss/PgBossSubscriber.ts"],"mappings":";;;;;;;;qBAWa,oBAAoB;;;;qBCNpB,yBAAyB;EACrC;;;qBASY,oCAAoC;WAC3B;EAArB,YAAqB;;;;UCZL;EAChB;EACA;;;;;;;EAOA;;qBAGY,4BAA4B;UAKpB;WAJX,OAAI,mBAAA;UACL;UACA;EAER,YAAoB,QAAQ;;;;;SAMf,qBACZ,2BACE,QAAQ;EAgBL,WAAW;EA8BX,SAAS;EAUf;UAIQ;;;;MAQJ,YAAY;;;;UC5FA;;;;;;EAMhB;;;wBAIe,WAAW,eAAe;qBAI7B,gBAAgB,iBAAiB,4CAClC,eAAe;UAGjB;UACA;EAFT,YACS,YAAY,kBACZ,UAAS;;;;;SAOL,qBACZ,iBAAiB,iCAEjB,0BACA,UAAS,yBACP,QAAQ,gBAAgB;EAOrB,QAAQ,UAAU,aAAa;EAqD/B,SAAS;;;;UC1FC;EAChB;EACA;;;;;;;;EAQA;;EAEA;;qBAGY,iBAAiB,iBAAiB,4CACnC,gBAAgB;UAGlB;UACA;EAFT,YACS,YAAY,kBACZ,UAAS;;;;;SAOL,qBACZ,iBAAiB,iCAChB,2BAA2B,QAAQ,iBAAiB;EAoBhD,UACL,UAAU,oBACV,WAAW,SAAS,aAAa,gBAC/B"}