@pubber-subber/gcp-pubsub 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sami Mishal
+
+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,109 @@
+# @pubber-subber/gcp-pubsub
+
+[Google Cloud Pub/Sub](https://cloud.google.com/pubsub) adapter for [`@pubber-subber/core`](https://www.npmjs.com/package/@pubber-subber/core). Backed by the official [`@google-cloud/pubsub`](https://www.npmjs.com/package/@google-cloud/pubsub) Node SDK.
+
+## Install
+
+```sh
+pnpm add @pubber-subber/core @pubber-subber/gcp-pubsub @google-cloud/pubsub
+```
+
+`@google-cloud/pubsub` is a **peer dependency**. Auth follows GCP defaults — `GOOGLE_APPLICATION_CREDENTIALS`, Workload Identity, etc.
+
+## Quick start
+
+```ts
+import { PubSub } from '@pubber-subber/core';
+import { gcpPubSub } from '@pubber-subber/gcp-pubsub';
+
+const pubsub = new PubSub({
+  adapter: gcpPubSub({ projectId: 'my-project' }),
+});
+
+await pubsub.subscribe(
+  'users.created',
+  (msg) => console.log(msg.payload, msg.meta?.attributes),
+  {
+    subscriptionName: 'workers-users-created',
+    createIfMissing: true,
+  },
+);
+
+await pubsub.publish(
+  'users.created',
+  { id: 1 },
+  { attributes: { tenantId: 't1' }, orderingKey: 'user-1' },
+);
+```
+
+## Options
+
+```ts
+gcpPubSub({
+  projectId?: string;
+  client?: GooglePubSub;             // pre-built @google-cloud/pubsub client
+  options?: ClientConfig;
+  codec?: Codec;
+  subscriptionPrefix?: string;       // default: 'pubber'
+})
+```
+
+| Option | Notes |
+| --- | --- |
+| `projectId` | GCP project. Falls back to `options.projectId` / SDK auto-detection. |
+| `client` | Pre-constructed `PubSub` client from `@google-cloud/pubsub`. Useful when you want to share a client. |
+| `options` | Full `ClientConfig` from the SDK (transport, scopes, etc.). |
+| `codec` | Payload encoder/decoder. Default `jsonCodec()`. |
+| `subscriptionPrefix` | Prefix for auto-generated subscription names when `subscriptionName` isn't provided. |
+
+## Publish meta
+
+```ts
+await pubsub.publish('users.created', payload, {
+  attributes: { tenantId: 't1' },
+  orderingKey: 'user-1',
+});
+```
+
+| Field | Notes |
+| --- | --- |
+| `attributes` | `Record<string, string>`, forwarded to Pub/Sub message attributes. |
+| `orderingKey` | Forwarded as the ordering key. Requires the topic to have message ordering enabled. |
+
+## Subscribe meta
+
+```ts
+await pubsub.subscribe('users.created', handler, {
+  subscriptionName: 'workers-users-created',
+  createIfMissing: true,
+});
+```
+
+| Field | Notes |
+| --- | --- |
+| `subscriptionName` | Existing subscription. **Required for production** — every worker must share the same subscription name to load-balance message processing. If omitted, a unique per-process name is generated (suitable for dev / one-off scripts only). |
+| `createIfMissing` | Create the subscription on demand if it doesn't exist. Useful for ephemeral or dev subscriptions. |
+| `subscriptionOptions` | Forwarded to `topic.createSubscription()` (e.g. `ackDeadlineSeconds`, `messageRetentionDuration`). |
+| `ephemeral` | Delete the subscription on `unsubscribe`. Use in tests; **never** in production. |
+
+## Capabilities
+
+```ts
+{ publish: true, subscribe: true, patternSubscribe: false, ack: true }
+```
+
+## Ack semantics
+
+- Handler returns successfully → `message.ack()`.
+- Handler throws → `message.nack()`. The server redelivers per the subscription's retry policy.
+- For manual control, call `msg.ack()` or `msg.nack()` inside your handler. The adapter tracks whether either was called and skips the auto-resolve to avoid double-ack.
+
+## Notes
+
+- Topic names use Pub/Sub's standard format. The adapter passes them through as-is — you can use bare names like `users.created` (resolved against the configured project) or fully qualified `projects/my-project/topics/users.created`.
+- For local development, the [Pub/Sub emulator](https://cloud.google.com/pubsub/docs/emulator) works out of the box: set `PUBSUB_EMULATOR_HOST=localhost:8085` and the SDK routes to it automatically.
+- The adapter doesn't auto-create topics — only subscriptions (via `createIfMissing`). Topics should exist before you publish.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,135 @@
+'use strict';
+
+var pubsub = require('@google-cloud/pubsub');
+var core = require('@pubber-subber/core');
+
+// src/index.ts
+function gcpPubSub(opts = {}) {
+  const codec = opts.codec ?? core.jsonCodec();
+  let client = null;
+  let idCounter = 0;
+  const liveSubscriptions = /* @__PURE__ */ new Set();
+  const ensure = () => {
+    if (client) return client;
+    if (opts.client) {
+      client = opts.client;
+    } else {
+      client = new pubsub.PubSub({ projectId: opts.projectId, ...opts.options });
+    }
+    return client;
+  };
+  return {
+    name: "gcp-pubsub",
+    capabilities: { publish: true, subscribe: true, patternSubscribe: false, ack: true },
+    async connect() {
+      ensure();
+    },
+    async disconnect() {
+      for (const s of [...liveSubscriptions]) {
+        await s.close().catch(noop);
+      }
+      liveSubscriptions.clear();
+      if (client) {
+        await client.close().catch(noop);
+        client = null;
+      }
+    },
+    async publish(topic, payload, meta) {
+      const c = ensure();
+      const t = c.topic(topic);
+      const encoded = codec.encode(payload);
+      const data = typeof encoded === "string" ? Buffer.from(encoded, "utf8") : Buffer.from(encoded);
+      await t.publishMessage({
+        data,
+        attributes: meta?.attributes,
+        orderingKey: meta?.orderingKey
+      });
+    },
+    async subscribe(topic, handler, meta) {
+      const c = ensure();
+      const prefix = opts.subscriptionPrefix ?? "pubber";
+      const subName = meta?.subscriptionName ?? `${prefix}-${sanitize(topic)}-${process.pid}-${Date.now()}-${++idCounter}`;
+      let subscription = c.subscription(subName);
+      if (meta?.createIfMissing) {
+        const [exists] = await subscription.exists();
+        if (!exists) {
+          try {
+            await c.topic(topic).createSubscription(subName, meta.subscriptionOptions);
+          } catch (err) {
+            throw new core.SubscriptionError(
+              `Failed to create subscription "${subName}" on topic "${topic}"`,
+              { cause: err }
+            );
+          }
+          subscription = c.subscription(subName);
+        }
+      }
+      const onMessage = async (message) => {
+        let payload = message.data;
+        try {
+          payload = codec.decode(message.data);
+        } catch {
+        }
+        let resolved = false;
+        const adapterMsg = {
+          topic,
+          payload,
+          raw: message,
+          meta: {
+            attributes: message.attributes,
+            messageId: message.id,
+            publishTime: message.publishTime,
+            orderingKey: message.orderingKey
+          },
+          ack: async () => {
+            if (resolved) return;
+            resolved = true;
+            message.ack();
+          },
+          nack: async () => {
+            if (resolved) return;
+            resolved = true;
+            message.nack();
+          }
+        };
+        try {
+          await handler(adapterMsg);
+          if (!resolved) {
+            resolved = true;
+            message.ack();
+          }
+        } catch {
+          if (!resolved) {
+            resolved = true;
+            message.nack();
+          }
+        }
+      };
+      subscription.on("message", onMessage);
+      liveSubscriptions.add(subscription);
+      idCounter += 1;
+      const id = `gcp-${idCounter}`;
+      return {
+        id,
+        topic,
+        unsubscribe: async () => {
+          subscription.off("message", onMessage);
+          await subscription.close().catch(noop);
+          liveSubscriptions.delete(subscription);
+          if (meta?.ephemeral) {
+            await subscription.delete().catch(noop);
+          }
+        }
+      };
+    }
+  };
+}
+function sanitize(name) {
+  return name.replace(/[^a-zA-Z0-9_\-.~+%]/g, "-").slice(0, 80);
+}
+function noop() {
+}
+
+exports.gcpPubSub = gcpPubSub;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["jsonCodec","GooglePubSub","SubscriptionError"],"mappings":"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","file":"index.cjs","sourcesContent":["import {\n  type ClientConfig,\n  type CreateSubscriptionOptions,\n  PubSub as GooglePubSub,\n  type Message,\n  type Subscription,\n} from '@google-cloud/pubsub';\nimport {\n  type AdapterMessage,\n  type Codec,\n  type PubSubAdapter,\n  SubscriptionError,\n  jsonCodec,\n} from '@pubber-subber/core';\n\nexport interface GcpPubSubAdapterOptions {\n  projectId?: string;\n  /** Or pass a fully-constructed client. */\n  client?: GooglePubSub;\n  /** Or `ClientConfig` for the underlying SDK. */\n  options?: ClientConfig;\n  /** Payload codec. Default: JSON. */\n  codec?: Codec;\n  /** Prefix for auto-generated subscription names. Default: `pubber`. */\n  subscriptionPrefix?: string;\n}\n\nexport interface GcpPublishMeta {\n  attributes?: Record<string, string>;\n  orderingKey?: string;\n}\n\nexport interface GcpSubscribeMeta {\n  /** Existing subscription name. If omitted, a unique name is generated. */\n  subscriptionName?: string;\n  /** Create the subscription if it doesn't exist. */\n  createIfMissing?: boolean;\n  /** Subscription options used when `createIfMissing` is true. */\n  subscriptionOptions?: CreateSubscriptionOptions;\n  /** Delete the subscription when the handle is unsubscribed. Best for dev. */\n  ephemeral?: boolean;\n}\n\nexport function gcpPubSub(\n  opts: GcpPubSubAdapterOptions = {},\n): PubSubAdapter<GcpPublishMeta, GcpSubscribeMeta> {\n  const codec = opts.codec ?? jsonCodec();\n  let client: GooglePubSub | null = null;\n  let idCounter = 0;\n  const liveSubscriptions = new Set<Subscription>();\n\n  const ensure = (): GooglePubSub => {\n    if (client) return client;\n    if (opts.client) {\n      client = opts.client;\n    } else {\n      client = new GooglePubSub({ projectId: opts.projectId, ...opts.options });\n    }\n    return client;\n  };\n\n  return {\n    name: 'gcp-pubsub',\n    capabilities: { publish: true, subscribe: true, patternSubscribe: false, ack: true },\n\n    async connect() {\n      ensure();\n    },\n\n    async disconnect() {\n      for (const s of [...liveSubscriptions]) {\n        await s.close().catch(noop);\n      }\n      liveSubscriptions.clear();\n      if (client) {\n        await client.close().catch(noop);\n        client = null;\n      }\n    },\n\n    async publish(topic, payload, meta) {\n      const c = ensure();\n      const t = c.topic(topic);\n      const encoded = codec.encode(payload);\n      const data =\n        typeof encoded === 'string' ? Buffer.from(encoded, 'utf8') : Buffer.from(encoded);\n      await t.publishMessage({\n        data,\n        attributes: meta?.attributes,\n        orderingKey: meta?.orderingKey,\n      });\n    },\n\n    async subscribe(topic, handler, meta) {\n      const c = ensure();\n      const prefix = opts.subscriptionPrefix ?? 'pubber';\n      const subName =\n        meta?.subscriptionName ??\n        `${prefix}-${sanitize(topic)}-${process.pid}-${Date.now()}-${++idCounter}`;\n      let subscription = c.subscription(subName);\n\n      if (meta?.createIfMissing) {\n        const [exists] = await subscription.exists();\n        if (!exists) {\n          try {\n            await c.topic(topic).createSubscription(subName, meta.subscriptionOptions);\n          } catch (err) {\n            throw new SubscriptionError(\n              `Failed to create subscription \"${subName}\" on topic \"${topic}\"`,\n              { cause: err },\n            );\n          }\n          subscription = c.subscription(subName);\n        }\n      }\n\n      const onMessage = async (message: Message) => {\n        let payload: unknown = message.data;\n        try {\n          payload = codec.decode(message.data);\n        } catch {\n          // Leave as raw buffer.\n        }\n        let resolved = false;\n        const adapterMsg: AdapterMessage = {\n          topic,\n          payload,\n          raw: message,\n          meta: {\n            attributes: message.attributes,\n            messageId: message.id,\n            publishTime: message.publishTime,\n            orderingKey: message.orderingKey,\n          },\n          ack: async () => {\n            if (resolved) return;\n            resolved = true;\n            message.ack();\n          },\n          nack: async () => {\n            if (resolved) return;\n            resolved = true;\n            message.nack();\n          },\n        };\n        try {\n          await handler(adapterMsg);\n          if (!resolved) {\n            resolved = true;\n            message.ack();\n          }\n        } catch {\n          if (!resolved) {\n            resolved = true;\n            message.nack();\n          }\n        }\n      };\n\n      subscription.on('message', onMessage);\n      liveSubscriptions.add(subscription);\n\n      idCounter += 1;\n      const id = `gcp-${idCounter}`;\n      return {\n        id,\n        topic,\n        unsubscribe: async () => {\n          subscription.off('message', onMessage);\n          await subscription.close().catch(noop);\n          liveSubscriptions.delete(subscription);\n          if (meta?.ephemeral) {\n            await subscription.delete().catch(noop);\n          }\n        },\n      };\n    },\n  };\n}\n\nfunction sanitize(name: string): string {\n  // GCP subscription names must match [a-zA-Z][a-zA-Z0-9_\\-.~+%]{2,254}\n  return name.replace(/[^a-zA-Z0-9_\\-.~+%]/g, '-').slice(0, 80);\n}\n\nfunction noop(): void {\n  // intentional\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,31 @@
+import { PubSub, ClientConfig, CreateSubscriptionOptions } from '@google-cloud/pubsub';
+import { Codec, PubSubAdapter } from '@pubber-subber/core';
+
+interface GcpPubSubAdapterOptions {
+    projectId?: string;
+    /** Or pass a fully-constructed client. */
+    client?: PubSub;
+    /** Or `ClientConfig` for the underlying SDK. */
+    options?: ClientConfig;
+    /** Payload codec. Default: JSON. */
+    codec?: Codec;
+    /** Prefix for auto-generated subscription names. Default: `pubber`. */
+    subscriptionPrefix?: string;
+}
+interface GcpPublishMeta {
+    attributes?: Record<string, string>;
+    orderingKey?: string;
+}
+interface GcpSubscribeMeta {
+    /** Existing subscription name. If omitted, a unique name is generated. */
+    subscriptionName?: string;
+    /** Create the subscription if it doesn't exist. */
+    createIfMissing?: boolean;
+    /** Subscription options used when `createIfMissing` is true. */
+    subscriptionOptions?: CreateSubscriptionOptions;
+    /** Delete the subscription when the handle is unsubscribed. Best for dev. */
+    ephemeral?: boolean;
+}
+declare function gcpPubSub(opts?: GcpPubSubAdapterOptions): PubSubAdapter<GcpPublishMeta, GcpSubscribeMeta>;
+
+export { type GcpPubSubAdapterOptions, type GcpPublishMeta, type GcpSubscribeMeta, gcpPubSub };

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import { PubSub, ClientConfig, CreateSubscriptionOptions } from '@google-cloud/pubsub';
+import { Codec, PubSubAdapter } from '@pubber-subber/core';
+
+interface GcpPubSubAdapterOptions {
+    projectId?: string;
+    /** Or pass a fully-constructed client. */
+    client?: PubSub;
+    /** Or `ClientConfig` for the underlying SDK. */
+    options?: ClientConfig;
+    /** Payload codec. Default: JSON. */
+    codec?: Codec;
+    /** Prefix for auto-generated subscription names. Default: `pubber`. */
+    subscriptionPrefix?: string;
+}
+interface GcpPublishMeta {
+    attributes?: Record<string, string>;
+    orderingKey?: string;
+}
+interface GcpSubscribeMeta {
+    /** Existing subscription name. If omitted, a unique name is generated. */
+    subscriptionName?: string;
+    /** Create the subscription if it doesn't exist. */
+    createIfMissing?: boolean;
+    /** Subscription options used when `createIfMissing` is true. */
+    subscriptionOptions?: CreateSubscriptionOptions;
+    /** Delete the subscription when the handle is unsubscribed. Best for dev. */
+    ephemeral?: boolean;
+}
+declare function gcpPubSub(opts?: GcpPubSubAdapterOptions): PubSubAdapter<GcpPublishMeta, GcpSubscribeMeta>;
+
+export { type GcpPubSubAdapterOptions, type GcpPublishMeta, type GcpSubscribeMeta, gcpPubSub };

package/dist/index.js

@@ -0,0 +1,133 @@
+import { PubSub } from '@google-cloud/pubsub';
+import { jsonCodec, SubscriptionError } from '@pubber-subber/core';
+
+// src/index.ts
+function gcpPubSub(opts = {}) {
+  const codec = opts.codec ?? jsonCodec();
+  let client = null;
+  let idCounter = 0;
+  const liveSubscriptions = /* @__PURE__ */ new Set();
+  const ensure = () => {
+    if (client) return client;
+    if (opts.client) {
+      client = opts.client;
+    } else {
+      client = new PubSub({ projectId: opts.projectId, ...opts.options });
+    }
+    return client;
+  };
+  return {
+    name: "gcp-pubsub",
+    capabilities: { publish: true, subscribe: true, patternSubscribe: false, ack: true },
+    async connect() {
+      ensure();
+    },
+    async disconnect() {
+      for (const s of [...liveSubscriptions]) {
+        await s.close().catch(noop);
+      }
+      liveSubscriptions.clear();
+      if (client) {
+        await client.close().catch(noop);
+        client = null;
+      }
+    },
+    async publish(topic, payload, meta) {
+      const c = ensure();
+      const t = c.topic(topic);
+      const encoded = codec.encode(payload);
+      const data = typeof encoded === "string" ? Buffer.from(encoded, "utf8") : Buffer.from(encoded);
+      await t.publishMessage({
+        data,
+        attributes: meta?.attributes,
+        orderingKey: meta?.orderingKey
+      });
+    },
+    async subscribe(topic, handler, meta) {
+      const c = ensure();
+      const prefix = opts.subscriptionPrefix ?? "pubber";
+      const subName = meta?.subscriptionName ?? `${prefix}-${sanitize(topic)}-${process.pid}-${Date.now()}-${++idCounter}`;
+      let subscription = c.subscription(subName);
+      if (meta?.createIfMissing) {
+        const [exists] = await subscription.exists();
+        if (!exists) {
+          try {
+            await c.topic(topic).createSubscription(subName, meta.subscriptionOptions);
+          } catch (err) {
+            throw new SubscriptionError(
+              `Failed to create subscription "${subName}" on topic "${topic}"`,
+              { cause: err }
+            );
+          }
+          subscription = c.subscription(subName);
+        }
+      }
+      const onMessage = async (message) => {
+        let payload = message.data;
+        try {
+          payload = codec.decode(message.data);
+        } catch {
+        }
+        let resolved = false;
+        const adapterMsg = {
+          topic,
+          payload,
+          raw: message,
+          meta: {
+            attributes: message.attributes,
+            messageId: message.id,
+            publishTime: message.publishTime,
+            orderingKey: message.orderingKey
+          },
+          ack: async () => {
+            if (resolved) return;
+            resolved = true;
+            message.ack();
+          },
+          nack: async () => {
+            if (resolved) return;
+            resolved = true;
+            message.nack();
+          }
+        };
+        try {
+          await handler(adapterMsg);
+          if (!resolved) {
+            resolved = true;
+            message.ack();
+          }
+        } catch {
+          if (!resolved) {
+            resolved = true;
+            message.nack();
+          }
+        }
+      };
+      subscription.on("message", onMessage);
+      liveSubscriptions.add(subscription);
+      idCounter += 1;
+      const id = `gcp-${idCounter}`;
+      return {
+        id,
+        topic,
+        unsubscribe: async () => {
+          subscription.off("message", onMessage);
+          await subscription.close().catch(noop);
+          liveSubscriptions.delete(subscription);
+          if (meta?.ephemeral) {
+            await subscription.delete().catch(noop);
+          }
+        }
+      };
+    }
+  };
+}
+function sanitize(name) {
+  return name.replace(/[^a-zA-Z0-9_\-.~+%]/g, "-").slice(0, 80);
+}
+function noop() {
+}
+
+export { gcpPubSub };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["GooglePubSub"],"mappings":"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","file":"index.js","sourcesContent":["import {\n  type ClientConfig,\n  type CreateSubscriptionOptions,\n  PubSub as GooglePubSub,\n  type Message,\n  type Subscription,\n} from '@google-cloud/pubsub';\nimport {\n  type AdapterMessage,\n  type Codec,\n  type PubSubAdapter,\n  SubscriptionError,\n  jsonCodec,\n} from '@pubber-subber/core';\n\nexport interface GcpPubSubAdapterOptions {\n  projectId?: string;\n  /** Or pass a fully-constructed client. */\n  client?: GooglePubSub;\n  /** Or `ClientConfig` for the underlying SDK. */\n  options?: ClientConfig;\n  /** Payload codec. Default: JSON. */\n  codec?: Codec;\n  /** Prefix for auto-generated subscription names. Default: `pubber`. */\n  subscriptionPrefix?: string;\n}\n\nexport interface GcpPublishMeta {\n  attributes?: Record<string, string>;\n  orderingKey?: string;\n}\n\nexport interface GcpSubscribeMeta {\n  /** Existing subscription name. If omitted, a unique name is generated. */\n  subscriptionName?: string;\n  /** Create the subscription if it doesn't exist. */\n  createIfMissing?: boolean;\n  /** Subscription options used when `createIfMissing` is true. */\n  subscriptionOptions?: CreateSubscriptionOptions;\n  /** Delete the subscription when the handle is unsubscribed. Best for dev. */\n  ephemeral?: boolean;\n}\n\nexport function gcpPubSub(\n  opts: GcpPubSubAdapterOptions = {},\n): PubSubAdapter<GcpPublishMeta, GcpSubscribeMeta> {\n  const codec = opts.codec ?? jsonCodec();\n  let client: GooglePubSub | null = null;\n  let idCounter = 0;\n  const liveSubscriptions = new Set<Subscription>();\n\n  const ensure = (): GooglePubSub => {\n    if (client) return client;\n    if (opts.client) {\n      client = opts.client;\n    } else {\n      client = new GooglePubSub({ projectId: opts.projectId, ...opts.options });\n    }\n    return client;\n  };\n\n  return {\n    name: 'gcp-pubsub',\n    capabilities: { publish: true, subscribe: true, patternSubscribe: false, ack: true },\n\n    async connect() {\n      ensure();\n    },\n\n    async disconnect() {\n      for (const s of [...liveSubscriptions]) {\n        await s.close().catch(noop);\n      }\n      liveSubscriptions.clear();\n      if (client) {\n        await client.close().catch(noop);\n        client = null;\n      }\n    },\n\n    async publish(topic, payload, meta) {\n      const c = ensure();\n      const t = c.topic(topic);\n      const encoded = codec.encode(payload);\n      const data =\n        typeof encoded === 'string' ? Buffer.from(encoded, 'utf8') : Buffer.from(encoded);\n      await t.publishMessage({\n        data,\n        attributes: meta?.attributes,\n        orderingKey: meta?.orderingKey,\n      });\n    },\n\n    async subscribe(topic, handler, meta) {\n      const c = ensure();\n      const prefix = opts.subscriptionPrefix ?? 'pubber';\n      const subName =\n        meta?.subscriptionName ??\n        `${prefix}-${sanitize(topic)}-${process.pid}-${Date.now()}-${++idCounter}`;\n      let subscription = c.subscription(subName);\n\n      if (meta?.createIfMissing) {\n        const [exists] = await subscription.exists();\n        if (!exists) {\n          try {\n            await c.topic(topic).createSubscription(subName, meta.subscriptionOptions);\n          } catch (err) {\n            throw new SubscriptionError(\n              `Failed to create subscription \"${subName}\" on topic \"${topic}\"`,\n              { cause: err },\n            );\n          }\n          subscription = c.subscription(subName);\n        }\n      }\n\n      const onMessage = async (message: Message) => {\n        let payload: unknown = message.data;\n        try {\n          payload = codec.decode(message.data);\n        } catch {\n          // Leave as raw buffer.\n        }\n        let resolved = false;\n        const adapterMsg: AdapterMessage = {\n          topic,\n          payload,\n          raw: message,\n          meta: {\n            attributes: message.attributes,\n            messageId: message.id,\n            publishTime: message.publishTime,\n            orderingKey: message.orderingKey,\n          },\n          ack: async () => {\n            if (resolved) return;\n            resolved = true;\n            message.ack();\n          },\n          nack: async () => {\n            if (resolved) return;\n            resolved = true;\n            message.nack();\n          },\n        };\n        try {\n          await handler(adapterMsg);\n          if (!resolved) {\n            resolved = true;\n            message.ack();\n          }\n        } catch {\n          if (!resolved) {\n            resolved = true;\n            message.nack();\n          }\n        }\n      };\n\n      subscription.on('message', onMessage);\n      liveSubscriptions.add(subscription);\n\n      idCounter += 1;\n      const id = `gcp-${idCounter}`;\n      return {\n        id,\n        topic,\n        unsubscribe: async () => {\n          subscription.off('message', onMessage);\n          await subscription.close().catch(noop);\n          liveSubscriptions.delete(subscription);\n          if (meta?.ephemeral) {\n            await subscription.delete().catch(noop);\n          }\n        },\n      };\n    },\n  };\n}\n\nfunction sanitize(name: string): string {\n  // GCP subscription names must match [a-zA-Z][a-zA-Z0-9_\\-.~+%]{2,254}\n  return name.replace(/[^a-zA-Z0-9_\\-.~+%]/g, '-').slice(0, 80);\n}\n\nfunction noop(): void {\n  // intentional\n}\n"]}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@pubber-subber/gcp-pubsub",
+  "version": "0.0.1",
+  "description": "Google Cloud Pub/Sub adapter for @pubber-subber.",
+  "keywords": [
+    "pubsub",
+    "pub-sub",
+    "messaging",
+    "events",
+    "adapter",
+    "gcp",
+    "google-cloud",
+    "google-cloud-pubsub",
+    "typescript"
+  ],
+  "homepage": "https://github.com/samishal1998/pubber-subber/tree/main/packages/gcp-pubsub#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/samishal1998/pubber-subber.git",
+    "directory": "packages/gcp-pubsub"
+  },
+  "bugs": {
+    "url": "https://github.com/samishal1998/pubber-subber/issues"
+  },
+  "author": "Sami Mishal",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "src", "README.md", "LICENSE"],
+  "scripts": {
+    "prebuild": "node ../../scripts/swap-package-json.mjs build",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:integration": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "node ../../scripts/swap-package-json.mjs publish",
+    "postpublish": "node ../../scripts/swap-package-json.mjs build"
+  },
+  "peerDependencies": {
+    "@google-cloud/pubsub": "^4.0.0 || ^5.0.0",
+    "@pubber-subber/core": "^0.0.1"
+  },
+  "devDependencies": {
+    "@pubber-subber/core": "workspace:*",
+    "@google-cloud/pubsub": "^4.9.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,188 @@
+import {
+  type ClientConfig,
+  type CreateSubscriptionOptions,
+  PubSub as GooglePubSub,
+  type Message,
+  type Subscription,
+} from '@google-cloud/pubsub';
+import {
+  type AdapterMessage,
+  type Codec,
+  type PubSubAdapter,
+  SubscriptionError,
+  jsonCodec,
+} from '@pubber-subber/core';
+
+export interface GcpPubSubAdapterOptions {
+  projectId?: string;
+  /** Or pass a fully-constructed client. */
+  client?: GooglePubSub;
+  /** Or `ClientConfig` for the underlying SDK. */
+  options?: ClientConfig;
+  /** Payload codec. Default: JSON. */
+  codec?: Codec;
+  /** Prefix for auto-generated subscription names. Default: `pubber`. */
+  subscriptionPrefix?: string;
+}
+
+export interface GcpPublishMeta {
+  attributes?: Record<string, string>;
+  orderingKey?: string;
+}
+
+export interface GcpSubscribeMeta {
+  /** Existing subscription name. If omitted, a unique name is generated. */
+  subscriptionName?: string;
+  /** Create the subscription if it doesn't exist. */
+  createIfMissing?: boolean;
+  /** Subscription options used when `createIfMissing` is true. */
+  subscriptionOptions?: CreateSubscriptionOptions;
+  /** Delete the subscription when the handle is unsubscribed. Best for dev. */
+  ephemeral?: boolean;
+}
+
+export function gcpPubSub(
+  opts: GcpPubSubAdapterOptions = {},
+): PubSubAdapter<GcpPublishMeta, GcpSubscribeMeta> {
+  const codec = opts.codec ?? jsonCodec();
+  let client: GooglePubSub | null = null;
+  let idCounter = 0;
+  const liveSubscriptions = new Set<Subscription>();
+
+  const ensure = (): GooglePubSub => {
+    if (client) return client;
+    if (opts.client) {
+      client = opts.client;
+    } else {
+      client = new GooglePubSub({ projectId: opts.projectId, ...opts.options });
+    }
+    return client;
+  };
+
+  return {
+    name: 'gcp-pubsub',
+    capabilities: { publish: true, subscribe: true, patternSubscribe: false, ack: true },
+
+    async connect() {
+      ensure();
+    },
+
+    async disconnect() {
+      for (const s of [...liveSubscriptions]) {
+        await s.close().catch(noop);
+      }
+      liveSubscriptions.clear();
+      if (client) {
+        await client.close().catch(noop);
+        client = null;
+      }
+    },
+
+    async publish(topic, payload, meta) {
+      const c = ensure();
+      const t = c.topic(topic);
+      const encoded = codec.encode(payload);
+      const data =
+        typeof encoded === 'string' ? Buffer.from(encoded, 'utf8') : Buffer.from(encoded);
+      await t.publishMessage({
+        data,
+        attributes: meta?.attributes,
+        orderingKey: meta?.orderingKey,
+      });
+    },
+
+    async subscribe(topic, handler, meta) {
+      const c = ensure();
+      const prefix = opts.subscriptionPrefix ?? 'pubber';
+      const subName =
+        meta?.subscriptionName ??
+        `${prefix}-${sanitize(topic)}-${process.pid}-${Date.now()}-${++idCounter}`;
+      let subscription = c.subscription(subName);
+
+      if (meta?.createIfMissing) {
+        const [exists] = await subscription.exists();
+        if (!exists) {
+          try {
+            await c.topic(topic).createSubscription(subName, meta.subscriptionOptions);
+          } catch (err) {
+            throw new SubscriptionError(
+              `Failed to create subscription "${subName}" on topic "${topic}"`,
+              { cause: err },
+            );
+          }
+          subscription = c.subscription(subName);
+        }
+      }
+
+      const onMessage = async (message: Message) => {
+        let payload: unknown = message.data;
+        try {
+          payload = codec.decode(message.data);
+        } catch {
+          // Leave as raw buffer.
+        }
+        let resolved = false;
+        const adapterMsg: AdapterMessage = {
+          topic,
+          payload,
+          raw: message,
+          meta: {
+            attributes: message.attributes,
+            messageId: message.id,
+            publishTime: message.publishTime,
+            orderingKey: message.orderingKey,
+          },
+          ack: async () => {
+            if (resolved) return;
+            resolved = true;
+            message.ack();
+          },
+          nack: async () => {
+            if (resolved) return;
+            resolved = true;
+            message.nack();
+          },
+        };
+        try {
+          await handler(adapterMsg);
+          if (!resolved) {
+            resolved = true;
+            message.ack();
+          }
+        } catch {
+          if (!resolved) {
+            resolved = true;
+            message.nack();
+          }
+        }
+      };
+
+      subscription.on('message', onMessage);
+      liveSubscriptions.add(subscription);
+
+      idCounter += 1;
+      const id = `gcp-${idCounter}`;
+      return {
+        id,
+        topic,
+        unsubscribe: async () => {
+          subscription.off('message', onMessage);
+          await subscription.close().catch(noop);
+          liveSubscriptions.delete(subscription);
+          if (meta?.ephemeral) {
+            await subscription.delete().catch(noop);
+          }
+        },
+      };
+    },
+  };
+}
+
+function sanitize(name: string): string {
+  // GCP subscription names must match [a-zA-Z][a-zA-Z0-9_\-.~+%]{2,254}
+  return name.replace(/[^a-zA-Z0-9_\-.~+%]/g, '-').slice(0, 80);
+}
+
+function noop(): void {
+  // intentional
+}