ts-prorm-orm 1.1.0

package/dist/nosql/eventhubs/index.js

@@ -0,0 +1,213 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventHubsStore = void 0;
+/**
+ * Azure Event Hubs store.
+ *
+ * Event Hubs is a managed, partitioned event-ingestion / event-streaming
+ * service (Azure's Kafka-like offering). 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 Event Hubs's real
+ * operations: sending event batches to a hub (`publish`) and subscribing a
+ * consumer to receive events (`subscribe`).
+ *
+ * Built on `@azure/event-hubs`: an `EventHubProducerClient` sends events
+ * (`sendBatch`) and an `EventHubConsumerClient` receives them (`subscribe`).
+ * The driver is loaded lazily inside `connect()` via `require` so importing
+ * this module never hard-requires it, and tests inject a mock module through
+ * the `client` option (an object exposing `EventHubProducerClient` and
+ * `EventHubConsumerClient` constructors) so no real driver or network is used.
+ *
+ * Message encoding: `publish()` accepts a `string` or `Buffer` (used as the
+ * event `body` unchanged) or any other JSON-serializable value (`JSON.stringify`d
+ * to a string body). Event Hubs itself AMQP-encodes the body on the wire.
+ *
+ * Note: Event Hubs (namespaces / hubs) are provisioned via the Azure
+ * management plane (ARM / portal / CLI), not the data-plane SDK, so this store
+ * intentionally does not expose a `createTopic`.
+ */
+const errors_1 = require("../../errors");
+/** Encode a message into the `body` Event Hubs sends (string/Buffer as-is, else JSON string). */
+function toBody(message) {
+    if (Buffer.isBuffer(message))
+        return message;
+    if (typeof message === 'string')
+        return message;
+    return JSON.stringify(message);
+}
+/**
+ * `EventHubsStore` wraps `@azure/event-hubs` producer/consumer clients and
+ * exposes event publishing and consumer subscriptions.
+ */
+class EventHubsStore {
+    constructor(options = {}) {
+        this.name = 'eventhubs';
+        this.library = '@azure/event-hubs';
+        this.azure = null;
+        this.producer = null;
+        /** Producers cached by event hub name (the default hub plus any others used). */
+        this.producers = new Map();
+        /** Active consumer subscriptions, tracked so `disconnect()` can close them. */
+        this.consumers = new Set();
+        this.connected = false;
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.azure)
+            return;
+        try {
+            this.azure = this.options.client ?? require('@azure/event-hubs');
+            this.connected = true;
+            if (this.options.eventHubName) {
+                this.producer = this.producerFor(this.options.eventHubName);
+            }
+        }
+        catch (err) {
+            this.azure = null;
+            this.producer = null;
+            this.connected = false;
+            throw new errors_1.ConnectionError(`Failed to connect to Event Hubs: ${err instanceof Error ? err.message : String(err)}`, { parent: err instanceof Error ? err : undefined, database: 'eventhubs' });
+        }
+    }
+    async disconnect() {
+        for (const consumer of this.consumers) {
+            try {
+                await consumer.close();
+            }
+            catch {
+                // Best-effort teardown.
+            }
+        }
+        this.consumers.clear();
+        for (const producer of this.producers.values()) {
+            try {
+                await producer.close?.();
+            }
+            catch {
+                // Best-effort teardown.
+            }
+        }
+        this.producers.clear();
+        this.producer = null;
+        this.azure = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.azure !== null;
+    }
+    /** Returns the underlying default `EventHubProducerClient` for anything not wrapped here. */
+    getClient() {
+        if (!this.connected || !this.azure) {
+            throw new errors_1.ConnectionError('Event Hubs is not connected. Call connect() first.', {
+                database: 'eventhubs',
+            });
+        }
+        return this.producerFor(this.options.eventHubName);
+    }
+    requireModule() {
+        if (!this.connected || !this.azure) {
+            throw new errors_1.ConnectionError('Event Hubs is not connected. Call connect() first.', {
+                database: 'eventhubs',
+            });
+        }
+        return this.azure;
+    }
+    /** Resolve (and cache) a producer for a given event hub name. */
+    producerFor(eventHubName) {
+        const azure = this.requireModule();
+        const hub = eventHubName ?? this.options.eventHubName ?? '';
+        const cached = this.producers.get(hub);
+        if (cached)
+            return cached;
+        const producer = new azure.EventHubProducerClient(this.options.connectionString, hub || undefined);
+        this.producers.set(hub, producer);
+        return producer;
+    }
+    wrapError(action, err) {
+        const parent = err instanceof Error ? err : new Error(String(err));
+        return new errors_1.DatabaseError(`Event Hubs ${action} failed: ${parent.message}`, {
+            parent,
+            original: parent.message,
+        });
+    }
+    // ---------------------------------------------------------------------
+    // Producing
+    // ---------------------------------------------------------------------
+    /**
+     * Send one `message` to `eventHubName` (or the store's default hub) as a
+     * single-event batch via `EventHubProducerClient.sendBatch`. The message is
+     * encoded per the module's rules (string/Buffer as-is, else JSON string).
+     */
+    async publish(eventHubName, message) {
+        const producer = this.producerFor(eventHubName);
+        try {
+            await producer.sendBatch([{ body: toBody(message) }]);
+        }
+        catch (err) {
+            throw this.wrapError(`publish to '${eventHubName}'`, err);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Consuming
+    // ---------------------------------------------------------------------
+    /**
+     * Subscribe a new `EventHubConsumerClient` to `eventHubName`, invoking
+     * `handler` once per received event. Returns a subscription whose `stop()`
+     * closes both the underlying subscription and consumer client; the
+     * subscription is tracked so `disconnect()` closes it too.
+     */
+    async subscribe(eventHubName, handler, options = {}) {
+        const azure = this.requireModule();
+        const consumerGroup = options.consumerGroup ?? this.options.consumerGroup ?? '$Default';
+        let consumer;
+        try {
+            consumer = new azure.EventHubConsumerClient(consumerGroup, this.options.connectionString, eventHubName);
+        }
+        catch (err) {
+            throw this.wrapError(`subscribe to '${eventHubName}'`, err);
+        }
+        try {
+            const handle = consumer.subscribe({
+                processEvents: async (events) => {
+                    for (const event of events ?? []) {
+                        await handler(event);
+                    }
+                },
+                processError: async () => {
+                    /* swallow — surface via the raw client if needed */
+                },
+            });
+            const tracked = {
+                async close() {
+                    try {
+                        await handle.close();
+                    }
+                    finally {
+                        await consumer.close?.();
+                    }
+                },
+            };
+            this.consumers.add(tracked);
+            return {
+                stop: async () => {
+                    this.consumers.delete(tracked);
+                    await tracked.close();
+                },
+            };
+        }
+        catch (err) {
+            try {
+                await consumer.close?.();
+            }
+            catch {
+                // Don't leak the half-set-up consumer.
+            }
+            throw this.wrapError(`subscribe to '${eventHubName}'`, err);
+        }
+    }
+}
+exports.EventHubsStore = EventHubsStore;
+exports.default = EventHubsStore;

package/dist/nosql/eventstore/index.js

@@ -0,0 +1,254 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventStoreStore = void 0;
+/**
+ * EventStoreDB (Kurrent) store.
+ *
+ * EventStoreDB is a purpose-built database for event sourcing: an append-only
+ * log of immutable events organized into streams, with catch-up and persistent
+ * subscriptions for reading them back. It has no SQL-shaped access pattern, so
+ * this store implements the minimal `NoSqlStore` marker interface
+ * (`src/nosql/store.ts`) and exposes EventStoreDB's real operations: appending
+ * an event to a stream (`publish`), a catch-up subscription that delivers
+ * events to a handler (`subscribe`), and reading a stream back (`readStream`).
+ *
+ * Built on `@eventstore/db-client`: an `EventStoreDBClient` appends
+ * (`appendToStream`), subscribes (`subscribeToStream`), and reads
+ * (`readStream`); the module's `jsonEvent(...)` helper builds event payloads.
+ * The driver is loaded lazily inside `connect()` via `require` so importing
+ * this module never hard-requires it, and tests inject a mock client through
+ * the `client` option so no real driver or network is used.
+ *
+ * Streams are created implicitly by the first append, so `createStream()` is a
+ * documented no-op that resolves without contacting the server.
+ *
+ * Message encoding: `publish()` accepts a `string` or `Buffer` (parsed as JSON
+ * when possible, otherwise wrapped as `{ value }`) or any other value (used as
+ * the event `data` directly). Each event is written as a JSON event with a
+ * caller-supplied `type` (default `'message'`).
+ */
+const errors_1 = require("../../errors");
+/** Build the JSON-event payload for an append, using the driver's `jsonEvent` when available. */
+function buildEvent(esdb, message, options) {
+    const type = options.type ?? 'message';
+    let data;
+    if (typeof message === 'string' || Buffer.isBuffer(message)) {
+        const text = message.toString();
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            data = { value: text };
+        }
+    }
+    else {
+        data = message;
+    }
+    const spec = { type, data, metadata: options.metadata, id: options.id };
+    if (esdb && typeof esdb.jsonEvent === 'function') {
+        return esdb.jsonEvent(spec);
+    }
+    // Fallback when the real driver isn't loaded (e.g. tests inject a client but
+    // not the module): a plain JSON-event-shaped object.
+    return { ...spec, contentType: 'application/json' };
+}
+/**
+ * `EventStoreStore` wraps an `@eventstore/db-client` `EventStoreDBClient` and
+ * exposes appending events, catch-up subscriptions, and stream reads.
+ */
+class EventStoreStore {
+    constructor(options = {}) {
+        this.name = 'eventstore';
+        this.library = '@eventstore/db-client';
+        this.client = null;
+        this.esdb = null;
+        this.connected = false;
+        /** Active subscriptions, tracked so `disconnect()` can end them. */
+        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;
+                this.tryLoadSdk();
+            }
+            else {
+                const esdb = require('@eventstore/db-client');
+                this.esdb = esdb;
+                this.client = esdb.EventStoreDBClient.connectionString(this.options.connectionString ?? 'esdb://localhost:2113?tls=false');
+            }
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.esdb = null;
+            this.connected = false;
+            throw new errors_1.ConnectionError(`Failed to connect to EventStoreDB: ${err instanceof Error ? err.message : String(err)}`, { parent: err instanceof Error ? err : undefined, database: 'eventstore' });
+        }
+    }
+    tryLoadSdk() {
+        if (this.esdb)
+            return;
+        try {
+            this.esdb = require('@eventstore/db-client');
+        }
+        catch {
+            this.esdb = null;
+        }
+    }
+    async disconnect() {
+        for (const sub of this.subscriptions) {
+            try {
+                sub.stop();
+            }
+            catch {
+                // Best-effort teardown.
+            }
+        }
+        this.subscriptions.clear();
+        try {
+            await this.client?.dispose?.();
+        }
+        finally {
+            this.client = null;
+            this.esdb = null;
+            this.connected = false;
+        }
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `EventStoreDBClient` for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client || !this.connected) {
+            throw new errors_1.ConnectionError('EventStoreDB client is not connected. Call connect() first.', {
+                database: 'eventstore',
+            });
+        }
+        return this.client;
+    }
+    wrapError(action, err) {
+        const parent = err instanceof Error ? err : new Error(String(err));
+        return new errors_1.DatabaseError(`EventStoreDB ${action} failed: ${parent.message}`, {
+            parent,
+            original: parent.message,
+        });
+    }
+    // ---------------------------------------------------------------------
+    // Producing
+    // ---------------------------------------------------------------------
+    /**
+     * Append one event carrying `message` to `stream` via `appendToStream`. The
+     * message is turned into a JSON event (`jsonEvent`) with `options.type`
+     * (default 'message'). Returns the driver's append result (next expected
+     * revision, etc.).
+     */
+    async publish(stream, message, options = {}) {
+        const client = this.requireClient();
+        const event = buildEvent(this.esdb, message, options);
+        try {
+            return await client.appendToStream(stream, event, options.expectedRevision !== undefined
+                ? { expectedRevision: options.expectedRevision }
+                : undefined);
+        }
+        catch (err) {
+            throw this.wrapError(`append to stream '${stream}'`, err);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Stream administration
+    // ---------------------------------------------------------------------
+    /**
+     * Streams are created implicitly by the first append in EventStoreDB, so this
+     * is a documented no-op that resolves without contacting the server. Provided
+     * to satisfy the common store surface (alias `createTopic`).
+     */
+    async createStream(_name) {
+        this.requireClient();
+        // Intentional no-op: EventStoreDB has no explicit stream-creation API.
+    }
+    /** Alias for `createStream()`, matching the common store surface. */
+    createTopic(name) {
+        return this.createStream(name);
+    }
+    // ---------------------------------------------------------------------
+    // Reading
+    // ---------------------------------------------------------------------
+    /**
+     * Read events from `stream` into an array by draining the driver's async
+     * iterable. Options (`fromRevision`, `maxCount`, `direction`, ...) are passed
+     * straight through.
+     */
+    async readStream(stream, options) {
+        const client = this.requireClient();
+        try {
+            const events = [];
+            for await (const resolved of client.readStream(stream, options)) {
+                events.push(resolved);
+            }
+            return events;
+        }
+        catch (err) {
+            throw this.wrapError(`read stream '${stream}'`, err);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Consuming
+    // ---------------------------------------------------------------------
+    /**
+     * Subscribe to `stream` with a catch-up subscription (`subscribeToStream`),
+     * invoking `handler` once per resolved event. Returns a subscription whose
+     * `stop()` ends it; it is tracked so `disconnect()` ends it too. The
+     * consuming loop runs detached (not awaited); this method resolves once the
+     * subscription is opened.
+     */
+    async subscribe(stream, handler, options = {}) {
+        const client = this.requireClient();
+        let iterable;
+        try {
+            iterable = client.subscribeToStream(stream, {
+                fromRevision: options.fromRevision ?? 'end',
+                resolveLinkTos: options.resolveLinkTos,
+            });
+        }
+        catch (err) {
+            throw this.wrapError(`subscribe to stream '${stream}'`, err);
+        }
+        let stopped = false;
+        const subscription = {
+            stop: () => {
+                stopped = true;
+                this.subscriptions.delete(subscription);
+                try {
+                    iterable.unsubscribe?.();
+                }
+                catch {
+                    // Best-effort.
+                }
+            },
+        };
+        this.subscriptions.add(subscription);
+        const loop = async () => {
+            for await (const resolved of iterable) {
+                if (stopped)
+                    break;
+                await handler(resolved);
+            }
+        };
+        loop().catch(() => {
+            /* swallow — best-effort background consuming */
+        });
+        return subscription;
+    }
+}
+exports.EventStoreStore = EventStoreStore;
+exports.default = EventStoreStore;

package/dist/nosql/faunadb/index.js

@@ -0,0 +1,188 @@
+"use strict";
+/**
+ * FaunaDB store implementation for the Prorm NoSQL layer.
+ *
+ * Fauna is a multi-model, distributed database (document, relational, graph)
+ * driven by FQL - a functional query language expressed as composed function
+ * calls rather than SQL strings. It does not fit the SQL-shaped `Dialect`
+ * interface, so this class implements the minimal `NoSqlStore` marker
+ * interface for connection lifecycle and otherwise exposes Fauna's real
+ * document CRUD (built from FQL expressions) plus a raw FQL `query` escape
+ * hatch.
+ *
+ * Uses the official `faunadb` driver. That driver is an optional peer
+ * dependency and is loaded lazily inside `connect()` so importing this module
+ * never requires it to be installed. Tests inject a pre-built mock `client`
+ * (and FQL builder `q`) via options, which bypasses the lazy `require`
+ * entirely - no real driver and no network are needed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FaunaDbStore = void 0;
+const errors_1 = require("../../errors");
+class FaunaDbStore {
+    constructor(options = {}) {
+        this.name = 'faunadb';
+        this.library = 'faunadb';
+        this.client = null;
+        this.q = null;
+        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;
+                this.q = this.options.q ?? this.tryRequireQuery();
+            }
+            else {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const fauna = require('faunadb');
+                this.client = new fauna.Client({
+                    secret: this.options.secret,
+                    domain: this.options.domain,
+                });
+                this.q = this.options.q ?? fauna.query;
+            }
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.q = null;
+            this.connected = false;
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw new errors_1.ConnectionError(`Unable to connect to FaunaDB: ${parent.message}`, {
+                parent,
+                database: 'faunadb',
+            });
+        }
+    }
+    tryRequireQuery() {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            return require('faunadb').query;
+        }
+        catch {
+            return null;
+        }
+    }
+    async disconnect() {
+        if (this.client && typeof this.client.close === 'function') {
+            try {
+                this.client.close();
+            }
+            catch {
+                // ignore close errors; the reference is dropped below regardless.
+            }
+        }
+        this.client = null;
+        this.q = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client || !this.connected) {
+            throw new errors_1.ConnectionError('Not connected to FaunaDB. Call connect() first.', {
+                database: 'faunadb',
+            });
+        }
+        return this.client;
+    }
+    requireQuery() {
+        const q = this.q;
+        if (!q) {
+            throw new errors_1.ConnectionError('FaunaDB FQL builder unavailable. Call connect() first.', {
+                database: 'faunadb',
+            });
+        }
+        return q;
+    }
+    // ---------------------------------------------------------------------
+    // Document CRUD (FQL)
+    // ---------------------------------------------------------------------
+    /** Create a document in `collection`; returns the new document's id. */
+    async insert(collection, doc) {
+        const client = this.requireClient();
+        const q = this.requireQuery();
+        try {
+            const result = await client.query(q.Create(q.Collection(collection), { data: doc }));
+            return result?.ref?.id ?? result?.data?.id;
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'FaunaDB insert failed');
+        }
+    }
+    /** Fetch a document by id, returning its `data`. */
+    async get(collection, id) {
+        const client = this.requireClient();
+        const q = this.requireQuery();
+        try {
+            const result = await client.query(q.Get(q.Ref(q.Collection(collection), id)));
+            return result?.data;
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'FaunaDB get failed');
+        }
+    }
+    /** Merge `patch` into a document's `data`, returning the updated data. */
+    async update(collection, id, patch) {
+        const client = this.requireClient();
+        const q = this.requireQuery();
+        try {
+            const result = await client.query(q.Update(q.Ref(q.Collection(collection), id), { data: patch }));
+            return result?.data;
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'FaunaDB update failed');
+        }
+    }
+    /** Delete a document by id. */
+    async delete(collection, id) {
+        const client = this.requireClient();
+        const q = this.requireQuery();
+        try {
+            return await client.query(q.Delete(q.Ref(q.Collection(collection), id)));
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'FaunaDB delete failed');
+        }
+    }
+    /**
+     * Run an FQL query. When `expr` is provided it is executed directly;
+     * otherwise all documents in `collection` are paginated and dereferenced.
+     * Returns the query's `data` array.
+     */
+    async query(collection, expr) {
+        const client = this.requireClient();
+        const q = this.requireQuery();
+        try {
+            const query = expr !== undefined
+                ? expr
+                : q.Map(q.Paginate(q.Documents(q.Collection(collection))), q.Lambda('ref', q.Get(q.Var('ref'))));
+            const result = await client.query(query);
+            return result?.data ?? [];
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'FaunaDB query failed');
+        }
+    }
+}
+exports.FaunaDbStore = FaunaDbStore;
+function wrapDatabaseError(err, message) {
+    if (err instanceof errors_1.ConnectionError) {
+        return err;
+    }
+    const parent = err instanceof Error ? err : new Error(String(err));
+    return errors_1.DatabaseError.from(parent, { message: `${message}: ${parent.message}` });
+}
+exports.default = FaunaDbStore;