ts-prorm-orm 1.1.0

package/dist/nosql/nats/index.js

@@ -0,0 +1,247 @@
+"use strict";
+/**
+ * NATS store implementation.
+ *
+ * NATS is a lightweight publish/subscribe and request/reply messaging system.
+ * Its JetStream layer adds persistence, including a key/value (KV) store built
+ * on top of streams. NATS has no query language and does not fit the
+ * SQL-shaped `Dialect` interface, so this class implements the minimal
+ * `NoSqlStore` marker interface and exposes NATS's real operations
+ * (core pub/sub, request/reply, and JetStream KV) instead of forcing
+ * everything into a `query(sql)` shape.
+ *
+ * Uses the `nats` driver (`nats.js`). The driver is lazy-loaded inside
+ * `connect()` via `require('nats')` so that importing this module never
+ * pulls in the driver unless a connection is actually opened; tests inject a
+ * pre-built connection through the `client` option and never touch the real
+ * driver or the network.
+ *
+ * Encoding: NATS messages are byte payloads (`Uint8Array`). `publish()` and
+ * `request()` accept either a `string` (UTF-8 encoded via `TextEncoder`) or a
+ * `Uint8Array` (passed through unchanged). `subscribe()` handlers and
+ * `request()` replies deliver the raw `Uint8Array` payload; decode with
+ * `TextDecoder` (or the message's own `.string()`/`.json()` helpers when using
+ * the real driver) as needed. JetStream KV values are encoded the same way on
+ * write, and `kvGet()` returns the entry's raw `Uint8Array` value (or `null`
+ * when the key is absent).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NatsStore = void 0;
+const errors_1 = require("../../errors");
+const textEncoder = new TextEncoder();
+/** Encode a string/`Uint8Array` payload into the `Uint8Array` the driver expects. */
+function encode(data) {
+    return typeof data === 'string' ? textEncoder.encode(data) : data;
+}
+function wrapConnectionError(err, servers) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const host = Array.isArray(servers) ? servers.join(',') : servers;
+    return new errors_1.ConnectionError(`Unable to connect to NATS: ${parent.message}`, {
+        parent,
+        database: 'nats',
+        host,
+    });
+}
+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 });
+}
+/**
+ * `NatsStore` wraps a `nats` `NatsConnection` and exposes NATS's core
+ * publish/subscribe and request/reply operations plus JetStream KV
+ * (`kvPut`/`kvGet`/`kvDelete`) as a typed, promise-based API.
+ */
+class NatsStore {
+    constructor(options = {}) {
+        this.name = 'nats';
+        this.library = 'nats';
+        this.connection = null;
+        this.connected = false;
+        /** Cached JetStream KV bucket views, keyed by bucket name. */
+        this.kvCache = new Map();
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.connection) {
+            return;
+        }
+        try {
+            if (this.options.client) {
+                // A pre-built connection was injected (used by tests and by callers
+                // that manage the connection themselves); adopt it and skip the
+                // driver require entirely.
+                this.connection = this.options.client;
+            }
+            else {
+                // Lazy-load the optional `nats` driver only when actually opening a
+                // real connection, so importing this module never requires it.
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const nats = require('nats');
+                this.connection = (await nats.connect({
+                    servers: this.options.servers,
+                    token: this.options.token,
+                    user: this.options.user,
+                    pass: this.options.pass,
+                }));
+            }
+            this.connected = true;
+        }
+        catch (err) {
+            this.connection = null;
+            this.connected = false;
+            throw wrapConnectionError(err, this.options.servers);
+        }
+    }
+    async disconnect() {
+        if (this.connection) {
+            try {
+                // Prefer a graceful drain (flushes pending messages and unsubscribes)
+                // and fall back to a hard close if the connection doesn't support it.
+                if (typeof this.connection.drain === 'function') {
+                    await this.connection.drain();
+                }
+                else if (typeof this.connection.close === 'function') {
+                    await this.connection.close();
+                }
+            }
+            catch {
+                try {
+                    await this.connection.close?.();
+                }
+                catch {
+                    // Ignore secondary teardown failures - we're discarding the
+                    // connection regardless.
+                }
+            }
+            this.connection = null;
+        }
+        this.kvCache.clear();
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.connection !== null;
+    }
+    /** Returns the underlying `nats` connection for anything not wrapped here. */
+    getClient() {
+        return this.requireConnection();
+    }
+    requireConnection() {
+        if (!this.connection) {
+            throw new errors_1.ConnectionError('Not connected to NATS', { database: 'nats' });
+        }
+        return this.connection;
+    }
+    // ---------------------------------------------------------------------
+    // Core pub/sub + request/reply
+    // ---------------------------------------------------------------------
+    /**
+     * Publish `data` to `subject`. The payload is encoded per the module's
+     * encoding rules (string → UTF-8, `Uint8Array` → as-is).
+     */
+    publish(subject, data) {
+        const connection = this.requireConnection();
+        try {
+            connection.publish(subject, encode(data));
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `NATS publish to "${subject}" failed`);
+        }
+    }
+    /**
+     * Subscribe to `subject`, invoking `handler` for each message via the
+     * driver's callback option (`subscribe(subject, { callback })`). Returns the
+     * driver's `Subscription` (call `.unsubscribe()` / `.drain()` on it to stop).
+     * The callback style is chosen over the async-iterator style so a handler
+     * can be registered without spawning a consuming loop.
+     */
+    subscribe(subject, handler) {
+        const connection = this.requireConnection();
+        try {
+            return connection.subscribe(subject, { callback: handler });
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `NATS subscribe to "${subject}" failed`);
+        }
+    }
+    /**
+     * Send a request to `subject` and await a single reply. `opts` is passed
+     * straight through to the driver (e.g. `{ timeout }`). Resolves with the
+     * driver's reply `Msg`; read `.data` / `.string()` / `.json()` off it.
+     */
+    async request(subject, data, opts) {
+        const connection = this.requireConnection();
+        try {
+            return await connection.request(subject, encode(data), opts);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `NATS request to "${subject}" failed`);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // JetStream KV
+    // ---------------------------------------------------------------------
+    /**
+     * Lazily resolve (and cache) the JetStream KV bucket view for `bucket` via
+     * `connection.jetstream().views.kv(bucket)`. Subsequent calls for the same
+     * bucket return the cached view.
+     */
+    async kv(bucket) {
+        const cached = this.kvCache.get(bucket);
+        if (cached) {
+            return cached;
+        }
+        const connection = this.requireConnection();
+        try {
+            const view = await connection.jetstream().views.kv(bucket);
+            this.kvCache.set(bucket, view);
+            return view;
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `NATS KV open bucket "${bucket}" failed`);
+        }
+    }
+    /**
+     * Put `value` at `key` in `bucket`'s KV store (encoded per the module's
+     * encoding rules). Returns the revision number assigned by JetStream.
+     */
+    async kvPut(bucket, key, value) {
+        const view = await this.kv(bucket);
+        try {
+            return await view.put(key, encode(value));
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `NATS KV put "${key}" in bucket "${bucket}" failed`);
+        }
+    }
+    /**
+     * Get the raw value stored at `key` in `bucket`, or `null` if the key is
+     * absent (or holds a deleted/purged entry). Returns the entry's
+     * `Uint8Array` value; decode with `TextDecoder` as needed.
+     */
+    async kvGet(bucket, key) {
+        const view = await this.kv(bucket);
+        try {
+            const entry = await view.get(key);
+            return entry ? entry.value : null;
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `NATS KV get "${key}" from bucket "${bucket}" failed`);
+        }
+    }
+    /** Delete `key` from `bucket`'s KV store. */
+    async kvDelete(bucket, key) {
+        const view = await this.kv(bucket);
+        try {
+            await view.delete(key);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `NATS KV delete "${key}" from bucket "${bucket}" failed`);
+        }
+    }
+}
+exports.NatsStore = NatsStore;
+exports.default = NatsStore;

package/dist/nosql/nedb/index.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NedbStore = void 0;
+/**
+ * NeDB store.
+ *
+ * NeDB is an embedded, in-process document database with a MongoDB-like API,
+ * backed by an append-only file (or purely in-memory). It stores documents
+ * addressed by an `_id` field and exposes `insert`/`findOne`/`find`/`remove`.
+ * It has no SQL-shaped surface, so it does not fit the `Dialect` interface
+ * used by the SQL dialects in this repo. Instead it implements the minimal
+ * `NoSqlStore` marker interface (`src/nosql/store.ts`) and maps a common
+ * key-value surface (`put`/`get`/`del` on `_id`) onto NeDB's document API,
+ * alongside the native `insert`/`find`.
+ *
+ * Built on the `nedb` npm driver (callback-based), loaded lazily inside
+ * `connect()` (via `require`) so importing this module never forces the driver
+ * to be installed; tests inject a pre-built mock `client` instead and never
+ * reach the `require`.
+ */
+const errors_1 = require("../../errors");
+/**
+ * `NedbStore` wraps a `nedb` `Datastore` and exposes both a common KV surface
+ * — `put`/`get`/`del` keyed on `_id`, `batch`, `list` — and NeDB's native
+ * document operations `insert`/`find`.
+ */
+class NedbStore {
+    constructor(options = {}) {
+        this.name = 'nedb';
+        this.library = 'nedb';
+        this.client = null;
+        this.connected = false;
+        this.options = options;
+    }
+    async connect() {
+        if (this.connected && this.client) {
+            return;
+        }
+        try {
+            if (this.options.client) {
+                this.client = this.options.client;
+            }
+            else {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const Datastore = require('nedb');
+                this.client = new Datastore(this.options.filename
+                    ? { filename: this.options.filename, autoload: true }
+                    : {});
+            }
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.connected = false;
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw new errors_1.ConnectionError(`Unable to open NeDB: ${parent.message}`, {
+                parent,
+                database: 'nedb',
+            });
+        }
+    }
+    async disconnect() {
+        // NeDB has no explicit close; drop the reference so the store reports
+        // disconnected and callers can't keep using it.
+        this.client = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `nedb` `Datastore` for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client || !this.connected) {
+            throw new errors_1.ConnectionError('NeDB datastore is not connected. Call connect() first.', {
+                database: 'nedb',
+            });
+        }
+        return this.client;
+    }
+    wrapError(action, err) {
+        const parent = err instanceof Error ? err : new Error(String(err));
+        return errors_1.DatabaseError.from(parent, { message: `NeDB ${action} failed: ${parent.message}` });
+    }
+    /** Wrap a callback-style NeDB call into a Promise. */
+    promisify(fn) {
+        return new Promise((resolve, reject) => {
+            fn((err, result) => (err ? reject(err) : resolve(result)));
+        });
+    }
+    /**
+     * Writes a document keyed by `_id = key`. Maps onto NeDB's `insert`, merging
+     * `key` into the document as its `_id`.
+     */
+    async put(key, value) {
+        const client = this.requireClient();
+        try {
+            return await this.promisify((cb) => client.insert({ _id: key, ...value }, cb));
+        }
+        catch (err) {
+            throw this.wrapError('put', err);
+        }
+    }
+    /** Reads a document by `_id` (NeDB `findOne({ _id })`). Returns `null` if absent. */
+    async get(key) {
+        const client = this.requireClient();
+        try {
+            return await this.promisify((cb) => client.findOne({ _id: key }, cb));
+        }
+        catch (err) {
+            throw this.wrapError('get', err);
+        }
+    }
+    /** Deletes a document by `_id` (NeDB `remove({ _id })`). Returns the number removed. */
+    async del(key) {
+        const client = this.requireClient();
+        try {
+            return await this.promisify((cb) => client.remove({ _id: key }, {}, cb));
+        }
+        catch (err) {
+            throw this.wrapError('del', err);
+        }
+    }
+    /** Native `insert`: adds a document (NeDB assigns an `_id` if omitted). */
+    async insert(doc) {
+        const client = this.requireClient();
+        try {
+            return await this.promisify((cb) => client.insert(doc, cb));
+        }
+        catch (err) {
+            throw this.wrapError('insert', err);
+        }
+    }
+    /** Native `find`: returns every document matching the Mongo-style `query`. */
+    async find(query = {}) {
+        const client = this.requireClient();
+        try {
+            return await this.promisify((cb) => client.find(query, cb));
+        }
+        catch (err) {
+            throw this.wrapError('find', err);
+        }
+    }
+    /** Applies a list of `put`/`del` operations sequentially. */
+    async batch(ops) {
+        for (const op of ops) {
+            if (op.type === 'put') {
+                await this.put(op.key, op.value);
+            }
+            else {
+                await this.del(op.key);
+            }
+        }
+    }
+    /** Lists all document `_id`s (via `find({})`). */
+    async list() {
+        const docs = await this.find({});
+        return docs.map((doc) => String(doc._id));
+    }
+}
+exports.NedbStore = NedbStore;
+exports.default = NedbStore;