ts-prorm-orm 1.1.0

package/dist/nosql/dax/index.js

@@ -0,0 +1,212 @@
+"use strict";
+/**
+ * DAX (Amazon DynamoDB Accelerator) store implementation.
+ *
+ * DAX is a fully managed, in-memory, write-through cache for Amazon
+ * DynamoDB. It is not a standalone database - it is a DynamoDB *cache* that
+ * speaks the DynamoDB wire API, so the `amazon-dax-client` driver is a
+ * drop-in replacement for the low-level `AWS.DynamoDB` client
+ * (`getItem`/`putItem`/`deleteItem`/`scan`, each returning a request with a
+ * `.promise()`).
+ *
+ * This class implements the minimal `NoSqlStore` marker interface and maps a
+ * simple edge-KV surface onto a single DynamoDB table used as a key-value
+ * bucket:
+ *
+ * - `get(key)`    -> `getItem`   (Key = { <keyAttr>: key })
+ * - `set(k,v)`    -> `putItem`   (Item = { <keyAttr>: key, <valueAttr>: value })
+ * - `del(key)`    -> `deleteItem`
+ * - `list(pref?)` -> `scan`      (returns the `<keyAttr>` of each item)
+ * - `incr(k,by?)` -> read-modify-write over `getItem`/`putItem`
+ *   (non-atomic; documented).
+ *
+ * ## Driver
+ *
+ * Uses `amazon-dax-client`. The driver is loaded lazily inside `connect()`
+ * (or supplied pre-built via the `client` option) so importing this module
+ * never requires `amazon-dax-client` to be installed unless a store is
+ * actually connected. Tests inject a mock `client`.
+ *
+ * ## Serialization
+ *
+ * Values are stored as DynamoDB string (`S`) attributes: strings verbatim,
+ * every other value `JSON.stringify`'d first.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DaxStore = void 0;
+const errors_1 = require("../../errors");
+function serialize(value) {
+    return typeof value === 'string' ? value : JSON.stringify(value);
+}
+/**
+ * `DaxStore` wraps an `amazon-dax-client` (DynamoDB-compatible) client behind
+ * the `NoSqlStore` lifecycle and an edge-KV `get`/`set`/`del`/`list`/`incr`
+ * surface over a single DynamoDB table.
+ */
+class DaxStore {
+    constructor(options = {}) {
+        this.name = 'dax';
+        this.library = 'amazon-dax-client';
+        this.client = null;
+        this.connected = false;
+        this.options = options;
+    }
+    get tableName() {
+        return this.options.tableName ?? '';
+    }
+    get keyAttr() {
+        return this.options.keyAttr ?? 'key';
+    }
+    get valueAttr() {
+        return this.options.valueAttr ?? 'value';
+    }
+    get ttlAttr() {
+        return this.options.ttlAttr ?? 'ttl';
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    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 mod = require('amazon-dax-client');
+                const AmazonDaxClient = mod.default ?? mod;
+                this.client = new AmazonDaxClient({
+                    endpoints: this.options.endpoints,
+                    region: this.options.region,
+                });
+            }
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.connected = false;
+            throw wrapConnectionError(err, this.options.endpoints?.[0]);
+        }
+    }
+    async disconnect() {
+        this.client = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying DAX (DynamoDB-compatible) client for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new errors_1.ConnectionError('Not connected to DAX', {
+                database: 'dax',
+                host: this.options.endpoints?.[0],
+            });
+        }
+        return this.client;
+    }
+    // ---------------------------------------------------------------------
+    // Key-value operations
+    // ---------------------------------------------------------------------
+    /** Read a key via `getItem`. Returns the stored string, or `null` if missing. */
+    async get(key) {
+        const client = this.requireClient();
+        try {
+            const res = await client
+                .getItem({ TableName: this.tableName, Key: { [this.keyAttr]: { S: key } } })
+                .promise();
+            const attr = res.Item?.[this.valueAttr];
+            return attr?.S ?? null;
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'GET');
+        }
+    }
+    /**
+     * Write `value` under `key` via `putItem`. Strings are stored verbatim;
+     * other values are JSON-serialized. `options.ttl`/`options.expiration`
+     * populate the table's TTL attribute (`ttlAttr`).
+     */
+    async set(key, value, options = {}) {
+        const client = this.requireClient();
+        const item = {
+            [this.keyAttr]: { S: key },
+            [this.valueAttr]: { S: serialize(value) },
+        };
+        if (options.expiration !== undefined) {
+            item[this.ttlAttr] = { N: String(options.expiration) };
+        }
+        else if (options.ttl !== undefined) {
+            item[this.ttlAttr] = { N: String(Math.floor(Date.now() / 1000) + options.ttl) };
+        }
+        try {
+            await client.putItem({ TableName: this.tableName, Item: item }).promise();
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'SET');
+        }
+    }
+    /** Delete a key via `deleteItem`. */
+    async del(key) {
+        const client = this.requireClient();
+        try {
+            await client
+                .deleteItem({ TableName: this.tableName, Key: { [this.keyAttr]: { S: key } } })
+                .promise();
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'DEL');
+        }
+    }
+    /** List key names via `scan`, optionally filtered to those beginning with `prefix`. */
+    async list(prefix) {
+        const client = this.requireClient();
+        const params = {
+            TableName: this.tableName,
+            ProjectionExpression: '#k',
+            ExpressionAttributeNames: { '#k': this.keyAttr },
+        };
+        if (prefix !== undefined) {
+            params.FilterExpression = 'begins_with(#k, :p)';
+            params.ExpressionAttributeValues = { ':p': { S: prefix } };
+        }
+        try {
+            const res = await client.scan(params).promise();
+            const items = res.Items ?? [];
+            return items.map((item) => item[this.keyAttr]?.S).filter((k) => k !== undefined);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'LIST');
+        }
+    }
+    /**
+     * Increment the numeric value at `key` by `by` (default `1`). Implemented
+     * as a non-atomic read-modify-write over `getItem`/`putItem`.
+     */
+    async incr(key, by = 1) {
+        const current = await this.get(key);
+        const next = (current === null ? 0 : Number(current)) + by;
+        await this.set(key, String(next));
+        return next;
+    }
+}
+exports.DaxStore = DaxStore;
+function wrapConnectionError(err, host) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    return new errors_1.ConnectionError(`Unable to connect to DAX: ${parent.message}`, {
+        parent,
+        database: 'dax',
+        host,
+    });
+}
+function wrapDatabaseError(err, action) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    return errors_1.DatabaseError.from(parent, { message: `DAX ${action} failed: ${parent.message}` });
+}
+exports.default = DaxStore;

package/dist/nosql/deno-kv/index.js

@@ -0,0 +1,206 @@
+"use strict";
+/**
+ * Deno KV store implementation.
+ *
+ * Deno KV is a globally-distributed, serverless key-value database. Outside
+ * a Deno runtime it is reached over the network with the KV Connect
+ * protocol, which is an HTTP/JSON transport. This class implements the
+ * minimal `NoSqlStore` marker interface and exposes an edge-KV
+ * `get`/`set`/`del`/`list`/`incr` surface.
+ *
+ * ## No canonical Node driver - HTTP over `fetch` (KV Connect assumption)
+ *
+ * There is no first-party Node client for Deno KV, so `library` is
+ * `'fetch'`. This store assumes a **KV Connect-style HTTP gateway** that
+ * exposes a small REST surface for the underlying database:
+ *
+ * - `get(key)`    -> `GET    /kv/values/<key>`  (404 => `null`)
+ * - `set(k,v)`    -> `PUT    /kv/values/<key>`  (body + optional `expireIn`)
+ * - `del(key)`    -> `DELETE /kv/values/<key>`
+ * - `list(pref?)` -> `GET    /kv/keys?prefix=`  (returns the key names)
+ * - `incr(k,by?)` -> read-modify-write over `get`/`set` (documented as
+ *   non-atomic; the native `atomic().sum()` op is not modeled here).
+ *
+ * Keys are treated as opaque strings (Deno KV's array key parts are joined
+ * by the caller). For tests (and callers with their own transport) an
+ * alternative HTTP client can be injected via `client`; when omitted a tiny
+ * internal `fetch`-based client is built at `connect()` time.
+ *
+ * ## Serialization
+ *
+ * String values are stored verbatim; every other value is `JSON.stringify`'d
+ * before being written.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DenoKvStore = void 0;
+exports.createFetchClient = createFetchClient;
+const errors_1 = require("../../errors");
+function serialize(value) {
+    return typeof value === 'string' ? value : JSON.stringify(value);
+}
+/** Build a `fetch`-backed HTTP client for the KV Connect gateway. */
+function createFetchClient(baseURL, accessToken) {
+    const root = baseURL.endsWith('/') ? baseURL.slice(0, -1) : baseURL;
+    return {
+        async request(method, path, init) {
+            const url = new URL(root + path);
+            for (const [key, value] of Object.entries(init?.query ?? {})) {
+                if (value !== undefined)
+                    url.searchParams.set(key, value);
+            }
+            const headers = {};
+            if (accessToken)
+                headers.Authorization = `Bearer ${accessToken}`;
+            if (init?.body !== undefined)
+                headers['Content-Type'] = 'application/json';
+            return fetch(url.toString(), { method, headers, body: init?.body });
+        },
+    };
+}
+/**
+ * `DenoKvStore` wraps a KV Connect HTTP gateway behind the `NoSqlStore`
+ * lifecycle and an edge-KV `get`/`set`/`del`/`list`/`incr` surface.
+ */
+class DenoKvStore {
+    constructor(options = {}) {
+        this.name = 'deno-kv';
+        this.library = 'fetch';
+        this.client = null;
+        this.connected = false;
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client) {
+            return;
+        }
+        try {
+            this.client =
+                this.options.client ?? createFetchClient(this.options.url ?? '', this.options.accessToken);
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.connected = false;
+            throw wrapConnectionError(err, this.options.url);
+        }
+    }
+    async disconnect() {
+        this.client = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying (internal or injected) HTTP client. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new errors_1.ConnectionError('Not connected to Deno KV', {
+                database: 'deno-kv',
+                host: this.options.url,
+            });
+        }
+        return this.client;
+    }
+    valuePath(key) {
+        return `/kv/values/${encodeURIComponent(key)}`;
+    }
+    // ---------------------------------------------------------------------
+    // Key-value operations
+    // ---------------------------------------------------------------------
+    /** Read a key. Returns `null` on a 404 (missing key). */
+    async get(key) {
+        const client = this.requireClient();
+        try {
+            const res = await client.request('GET', this.valuePath(key));
+            if (res.status === 404)
+                return null;
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            return await res.text();
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'GET');
+        }
+    }
+    /**
+     * Write `value` under `key`. Strings are stored verbatim; other values are
+     * JSON-serialized. `options.ttl` maps to `expireIn` (ms), `options.expiration`
+     * to `expireAt` (absolute Unix ms).
+     */
+    async set(key, value, options = {}) {
+        const client = this.requireClient();
+        const query = {};
+        if (options.ttl !== undefined)
+            query.expireIn = String(options.ttl);
+        if (options.expiration !== undefined)
+            query.expireAt = String(options.expiration);
+        try {
+            const res = await client.request('PUT', this.valuePath(key), {
+                body: serialize(value),
+                query,
+            });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'SET');
+        }
+    }
+    /** Delete a key. */
+    async del(key) {
+        const client = this.requireClient();
+        try {
+            const res = await client.request('DELETE', this.valuePath(key));
+            if (!res.ok && res.status !== 404)
+                throw new Error(`HTTP ${res.status}`);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'DEL');
+        }
+    }
+    /** List key names, optionally filtered by `prefix`. */
+    async list(prefix) {
+        const client = this.requireClient();
+        try {
+            const res = await client.request('GET', '/kv/keys', { query: { prefix } });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            const body = await res.json();
+            const keys = body?.keys ?? [];
+            return keys;
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'LIST');
+        }
+    }
+    /**
+     * Increment the numeric value at `key` by `by` (default `1`). Implemented
+     * as a non-atomic read-modify-write over `get`/`set`.
+     */
+    async incr(key, by = 1) {
+        const current = await this.get(key);
+        const next = (current === null ? 0 : Number(current)) + by;
+        await this.set(key, String(next));
+        return next;
+    }
+}
+exports.DenoKvStore = DenoKvStore;
+function wrapConnectionError(err, host) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    return new errors_1.ConnectionError(`Unable to connect to Deno KV: ${parent.message}`, {
+        parent,
+        database: 'deno-kv',
+        host,
+    });
+}
+function wrapDatabaseError(err, action) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    return errors_1.DatabaseError.from(parent, { message: `Deno KV ${action} failed: ${parent.message}` });
+}
+exports.default = DenoKvStore;

package/dist/nosql/dgraph/index.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DgraphStore = void 0;
+/**
+ * Dgraph store.
+ *
+ * Dgraph is a distributed, native graph database queried with DQL (its
+ * GraphQL-derived query language) rather than SQL. Data is modeled as nodes
+ * (identified by UIDs) and typed predicates/edges between them, with an
+ * optional schema defined via `alter`. It has no `Dialect`-shaped
+ * `query(sql)`/identifier-escaping surface, so this class implements the
+ * minimal `NoSqlStore` marker interface (`src/nosql/store.ts`) and exposes
+ * Dgraph's real primitives — parameterized DQL queries, JSON mutations, and
+ * schema `alter`/`dropAll` operations — directly.
+ *
+ * Built on the official `dgraph-js` gRPC driver. That driver is an optional
+ * peer dependency 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");
+/**
+ * `DgraphStore` wraps a `dgraph-js` `DgraphClient` and exposes Dgraph's real
+ * surface: `query()` for parameterized DQL reads, `mutate()` for JSON
+ * mutations (auto-committed), and `alter()`/`dropAll()` for schema/data
+ * management.
+ */
+class DgraphStore {
+    constructor(options = {}) {
+        this.name = 'dgraph';
+        this.library = 'dgraph-js';
+        this.client = null;
+        /** The client stub, kept so `disconnect()` can close its gRPC channel. Null when a client is injected. */
+        this.stub = null;
+        this.connected = false;
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // NoSqlStore lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client) {
+            return;
+        }
+        try {
+            if (this.options.client) {
+                // Injected mock: use it directly and never touch the real driver.
+                this.client = this.options.client;
+            }
+            else {
+                // Lazy-load the optional driver so importing this module never
+                // requires `dgraph-js` to be installed.
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const dgraph = require('dgraph-js');
+                const stub = new dgraph.DgraphClientStub(this.options.address);
+                this.stub = stub;
+                this.client = new dgraph.DgraphClient(stub);
+            }
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.stub = null;
+            this.connected = false;
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw new errors_1.ConnectionError(`Unable to connect to Dgraph: ${parent.message}`, {
+                parent,
+                database: 'dgraph',
+                host: this.options.address,
+            });
+        }
+    }
+    async disconnect() {
+        if (this.stub) {
+            this.stub.close();
+            this.stub = null;
+        }
+        this.client = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `dgraph-js` `DgraphClient` for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client || !this.connected) {
+            throw new errors_1.ConnectionError('Dgraph client is not connected. Call connect() first.', {
+                database: 'dgraph',
+            });
+        }
+        return this.client;
+    }
+    wrapError(action, err) {
+        const parent = err instanceof Error ? err : new Error(String(err));
+        return errors_1.DatabaseError.from(parent, { message: `Dgraph ${action} failed: ${parent.message}` });
+    }
+    // ---------------------------------------------------------------------
+    // Query / mutate
+    // ---------------------------------------------------------------------
+    /**
+     * Runs a parameterized DQL query in a fresh transaction and returns the
+     * parsed JSON result. `vars` binds DQL query variables (e.g.
+     * `{ $name: 'alice' }`) sent separately from the query text. The
+     * transaction is always discarded in a `finally` — a read-only query never
+     * needs committing, and discarding releases its server-side resources.
+     */
+    async query(dql, vars = {}) {
+        const client = this.requireClient();
+        const txn = client.newTxn();
+        try {
+            const res = await txn.queryWithVars(dql, vars);
+            return JSON.parse(res.getJson());
+        }
+        catch (err) {
+            throw this.wrapError('query', err);
+        }
+        finally {
+            await txn.discard();
+        }
+    }
+    /**
+     * Applies a JSON mutation (`setJson`) and commits it immediately
+     * (`commitNow: true`), so no separate commit round trip is needed. The
+     * transaction is discarded in a `finally` as a safety net (committed
+     * transactions treat discard as a no-op).
+     */
+    async mutate(setJson) {
+        const client = this.requireClient();
+        const txn = client.newTxn();
+        try {
+            return await txn.mutate({ setJson, commitNow: true });
+        }
+        catch (err) {
+            throw this.wrapError('mutate', err);
+        }
+        finally {
+            await txn.discard();
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Schema / data management
+    // ---------------------------------------------------------------------
+    /**
+     * Alters the schema by forwarding a DQL schema definition (DDL) to
+     * `client.alter({ schema })`, e.g. `'name: string @index(exact) .'`.
+     */
+    async alter(schema) {
+        const client = this.requireClient();
+        try {
+            return await client.alter({ schema });
+        }
+        catch (err) {
+            throw this.wrapError('alter', err);
+        }
+    }
+    /** Drops all data and schema in the cluster via `client.alter({ dropAll: true })`. */
+    async dropAll() {
+        const client = this.requireClient();
+        try {
+            return await client.alter({ dropAll: true });
+        }
+        catch (err) {
+            throw this.wrapError('dropAll', err);
+        }
+    }
+}
+exports.DgraphStore = DgraphStore;
+exports.default = DgraphStore;