ts-prorm-orm 1.1.0

package/dist/nosql/pubsub/index.js

@@ -0,0 +1,187 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PubSubStore = void 0;
+/**
+ * Google Cloud Pub/Sub store.
+ *
+ * Pub/Sub is a managed, topic-and-subscription messaging service. It has no
+ * query language and no SQL-shaped access pattern, so this store implements the
+ * minimal `NoSqlStore` marker interface (`src/nosql/store.ts`) and exposes
+ * Pub/Sub's real operations: publishing messages to a topic (`publish`),
+ * receiving messages on a subscription via an event listener (`subscribe`), and
+ * topic/subscription administration (`createTopic`, `createSubscription`).
+ *
+ * Built on `@google-cloud/pubsub`: `new PubSub()` yields a client whose
+ * `topic(name).publishMessage(...)` publishes and whose
+ * `subscription(name).on('message', ...)` streams messages. The driver is
+ * loaded lazily inside `connect()` via `require`, and tests inject a mock
+ * client through the `client` option so no real driver or network is used.
+ *
+ * Message encoding: `publish()` accepts a `string` (UTF-8 encoded), a `Buffer`
+ * (sent as-is), or any other JSON-serializable value (`JSON.stringify`d then
+ * UTF-8 encoded). The bytes become the message `data`.
+ */
+const errors_1 = require("../../errors");
+/** Encode a message into the `Buffer` Pub/Sub carries as message `data`. */
+function toData(message) {
+    if (Buffer.isBuffer(message))
+        return message;
+    if (typeof message === 'string')
+        return Buffer.from(message, 'utf8');
+    return Buffer.from(JSON.stringify(message), 'utf8');
+}
+/**
+ * `PubSubStore` wraps a `@google-cloud/pubsub` client and exposes topic
+ * publishing, subscription listening, and topic/subscription administration.
+ */
+class PubSubStore {
+    constructor(options = {}) {
+        this.name = 'pubsub';
+        this.library = '@google-cloud/pubsub';
+        this.client = null;
+        this.connected = false;
+        /** Subscription objects that have live listeners, tracked for `disconnect()`. */
+        this.subscriptions = new Set();
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client)
+            return;
+        try {
+            if (this.options.client) {
+                this.client = this.options.client;
+            }
+            else {
+                const { PubSub } = require('@google-cloud/pubsub');
+                this.client = new PubSub({
+                    projectId: this.options.projectId,
+                    keyFilename: this.options.keyFilename,
+                    apiEndpoint: this.options.apiEndpoint,
+                });
+            }
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.connected = false;
+            throw new errors_1.ConnectionError(`Failed to connect to Pub/Sub: ${err instanceof Error ? err.message : String(err)}`, { parent: err instanceof Error ? err : undefined, database: 'pubsub' });
+        }
+    }
+    async disconnect() {
+        for (const subscription of this.subscriptions) {
+            try {
+                subscription.removeAllListeners?.();
+                await subscription.close?.();
+            }
+            catch {
+                // Best-effort teardown.
+            }
+        }
+        this.subscriptions.clear();
+        try {
+            await this.client?.close?.();
+        }
+        finally {
+            this.client = null;
+            this.connected = false;
+        }
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `PubSub` client for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client || !this.connected) {
+            throw new errors_1.ConnectionError('Pub/Sub client is not connected. Call connect() first.', {
+                database: 'pubsub',
+            });
+        }
+        return this.client;
+    }
+    wrapError(action, err) {
+        const parent = err instanceof Error ? err : new Error(String(err));
+        return new errors_1.DatabaseError(`Pub/Sub ${action} failed: ${parent.message}`, {
+            parent,
+            original: parent.message,
+        });
+    }
+    // ---------------------------------------------------------------------
+    // Producing
+    // ---------------------------------------------------------------------
+    /**
+     * Publish one `message` to `topic` via `topic(name).publishMessage`. The
+     * message is encoded per the module's rules (string → UTF-8, Buffer → as-is,
+     * else JSON). Returns the server-assigned message id.
+     */
+    async publish(topic, message, attributes) {
+        const client = this.requireClient();
+        try {
+            return await client.topic(topic).publishMessage({ data: toData(message), attributes });
+        }
+        catch (err) {
+            throw this.wrapError(`publish to topic '${topic}'`, err);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Administration
+    // ---------------------------------------------------------------------
+    /** `createTopic` — create a new topic. */
+    async createTopic(name) {
+        const client = this.requireClient();
+        try {
+            await client.createTopic(name);
+        }
+        catch (err) {
+            throw this.wrapError(`createTopic '${name}'`, err);
+        }
+    }
+    /** `createSubscription` — attach a new subscription `name` to `topic`. */
+    async createSubscription(topic, name, options) {
+        const client = this.requireClient();
+        try {
+            await client.createSubscription(topic, name, options);
+        }
+        catch (err) {
+            throw this.wrapError(`createSubscription '${name}' on topic '${topic}'`, err);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Consuming
+    // ---------------------------------------------------------------------
+    /**
+     * Subscribe to `subscription`, invoking `handler` for each streamed message
+     * (the driver's `Message` object; call `.ack()` / `.nack()` on it). Attaches
+     * a `'message'` listener via `subscription(name).on('message', ...)` and
+     * returns a subscription handle whose `stop()` detaches the listener; it is
+     * also tracked so `disconnect()` detaches it.
+     */
+    async subscribe(subscription, handler) {
+        const client = this.requireClient();
+        let sub;
+        try {
+            sub = client.subscription(subscription);
+            sub.on('message', (message) => {
+                void handler(message);
+            });
+        }
+        catch (err) {
+            throw this.wrapError(`subscribe to '${subscription}'`, err);
+        }
+        this.subscriptions.add(sub);
+        return {
+            stop: async () => {
+                this.subscriptions.delete(sub);
+                sub.removeAllListeners?.();
+                await sub.close?.();
+            },
+        };
+    }
+}
+exports.PubSubStore = PubSubStore;
+exports.default = PubSubStore;

package/dist/nosql/pulsar/index.js

@@ -0,0 +1,232 @@
+"use strict";
+/**
+ * Apache Pulsar store implementation.
+ *
+ * Pulsar is a distributed pub/sub messaging and streaming platform. It has no
+ * query language and does not fit the SQL-shaped `Dialect` interface, so this
+ * class implements the minimal `NoSqlStore` marker interface and exposes
+ * Pulsar's real operations - producing to topics, subscribing consumers, and
+ * creating readers - instead of forcing everything into a `query(sql)` shape.
+ *
+ * Uses the `pulsar-client` driver. `pulsar-client` is loaded lazily inside
+ * `connect()` (or supplied pre-built via `options.client`) so importing this
+ * module does not require the driver to be installed.
+ *
+ * ## Message serialization
+ *
+ * Pulsar sends and receives raw bytes. `produce()` accepts a `string` or a
+ * `Buffer`: strings are UTF-8 encoded to a `Buffer` and Buffers are passed
+ * through untouched, then handed to the producer as `{ data: Buffer }`.
+ * Consumers receive Pulsar `Message` objects; use `msg.getData()` to read the
+ * raw bytes back.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PulsarStore = void 0;
+const errors_1 = require("../../errors");
+function wrapConnectionError(err, serviceUrl) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const message = /econnrefused/i.test(parent.message)
+        ? 'Connection refused'
+        : `Unable to connect to Pulsar: ${parent.message}`;
+    return new errors_1.ConnectionError(message, {
+        parent,
+        database: 'pulsar',
+        host: serviceUrl,
+    });
+}
+function wrapDatabaseError(err, message) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const combined = message ? `${message}: ${parent.message}` : parent.message;
+    return errors_1.DatabaseError.from(parent, { message: combined });
+}
+/** Serialize a `string`/`Buffer` message into the raw bytes Pulsar expects. */
+function toBuffer(message) {
+    return Buffer.isBuffer(message) ? message : Buffer.from(message, 'utf8');
+}
+/**
+ * `PulsarStore` wraps a `pulsar-client` `Client` and exposes Pulsar's core
+ * operations: producing messages, consumer subscriptions, and readers.
+ */
+class PulsarStore {
+    constructor(options = {}) {
+        this.name = 'pulsar';
+        this.library = 'pulsar-client';
+        this.client = null;
+        /** One cached producer per topic, so repeated `produce()` calls reuse it. */
+        this.producers = new Map();
+        /** Consumers created via `subscribe()`, tracked so `disconnect()` can close them. */
+        this.consumers = [];
+        /** Readers created via `createReader()`, tracked so `disconnect()` can close them. */
+        this.readers = [];
+        /** Set false on `disconnect()` to stop live `subscribe()` receive loops. */
+        this.receiving = false;
+        this.connected = false;
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client) {
+            return;
+        }
+        try {
+            if (this.options.client) {
+                this.client = this.options.client;
+            }
+            else {
+                // Lazy-load the driver so importing this module doesn't require
+                // `pulsar-client` to be installed unless a real connection is made.
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const Pulsar = require('pulsar-client');
+                this.client = new Pulsar.Client({
+                    serviceUrl: this.options.serviceUrl,
+                });
+            }
+            this.receiving = true;
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.connected = false;
+            throw wrapConnectionError(err, this.options.serviceUrl);
+        }
+    }
+    async disconnect() {
+        // Stop receive loops before closing anything.
+        this.receiving = false;
+        for (const consumer of this.consumers.splice(0)) {
+            try {
+                await consumer.close();
+            }
+            catch {
+                // Best-effort teardown - keep closing the rest.
+            }
+        }
+        for (const reader of this.readers.splice(0)) {
+            try {
+                await reader.close();
+            }
+            catch {
+                // Best-effort teardown.
+            }
+        }
+        for (const producer of this.producers.values()) {
+            try {
+                await producer.close();
+            }
+            catch {
+                // Best-effort teardown.
+            }
+        }
+        this.producers.clear();
+        if (this.client) {
+            try {
+                await this.client.close();
+            }
+            catch {
+                // Best-effort teardown.
+            }
+            this.client = null;
+        }
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `pulsar-client` `Client` for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new errors_1.ConnectionError('Not connected to Pulsar', { database: 'pulsar' });
+        }
+        return this.client;
+    }
+    // ---------------------------------------------------------------------
+    // Producing
+    // ---------------------------------------------------------------------
+    /**
+     * Produce `message` to `topic`. The producer for a topic is created on first
+     * use and cached, so repeated `produce()` calls to the same topic reuse it.
+     * `message` may be a UTF-8 `string` or a `Buffer`; it is serialized to raw
+     * bytes and sent as `{ data: Buffer }`. Returns the producer's send result.
+     */
+    async produce(topic, message) {
+        const client = this.requireClient();
+        try {
+            let producer = this.producers.get(topic);
+            if (!producer) {
+                producer = await client.createProducer({ topic });
+                this.producers.set(topic, producer);
+            }
+            return await producer.send({ data: toBuffer(message) });
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `Pulsar produce to "${topic}" failed`);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Consuming
+    // ---------------------------------------------------------------------
+    /**
+     * Subscribe a consumer to `topic` under `subscription` and invoke `handler`
+     * for every received message. Runs a background receive loop that calls
+     * `consumer.receive()`, passes each message to `handler`, then
+     * acknowledges it with `consumer.acknowledge(msg)`. The loop stops on
+     * `disconnect()`. The consumer is tracked so `disconnect()` closes it.
+     * Returns the created consumer.
+     */
+    async subscribe(topic, subscription, handler, options = {}) {
+        const client = this.requireClient();
+        let consumer;
+        try {
+            consumer = await client.subscribe({ topic, subscription, ...options });
+            this.consumers.push(consumer);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `Pulsar subscribe to "${topic}" failed`);
+        }
+        // Background receive loop: pull, dispatch to handler, acknowledge. Stops
+        // when `disconnect()` flips `this.receiving` to false.
+        void (async () => {
+            while (this.receiving) {
+                let msg;
+                try {
+                    msg = await consumer.receive();
+                }
+                catch {
+                    // Consumer closed (typically during disconnect) - end the loop.
+                    break;
+                }
+                try {
+                    await handler(msg);
+                    await consumer.acknowledge(msg);
+                }
+                catch {
+                    // Handler/ack failure: don't kill the loop, move to the next message.
+                }
+            }
+        })();
+        return consumer;
+    }
+    /**
+     * Create a Pulsar reader over `topic`. Readers give non-destructive,
+     * position-controlled reads (no subscription/acks). The reader is tracked so
+     * `disconnect()` closes it. Returns the created reader.
+     */
+    async createReader(topic, options = {}) {
+        const client = this.requireClient();
+        try {
+            const reader = await client.createReader({ topic, ...options });
+            this.readers.push(reader);
+            return reader;
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `Pulsar createReader for "${topic}" failed`);
+        }
+    }
+}
+exports.PulsarStore = PulsarStore;
+exports.default = PulsarStore;