ts-prorm-orm 1.1.0

package/dist/nosql/kafka/index.js

@@ -0,0 +1,234 @@
+"use strict";
+/**
+ * Apache Kafka store implementation.
+ *
+ * Kafka is a distributed, partitioned, append-only commit log used as a
+ * message broker / event-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 Kafka's real
+ * operations - producing to topics, creating/listing topics via the admin
+ * client, and subscribing consumers to topics - instead of forcing
+ * everything into a `query(sql)` shape.
+ *
+ * Uses the `kafkajs` driver. `kafkajs` is loaded lazily inside `connect()`
+ * (or supplied pre-built via `options.client`) so importing this module does
+ * not require the driver to be installed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KafkaStore = void 0;
+const errors_1 = require("../../errors");
+function wrapConnectionError(err, brokers) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const message = /econnrefused/i.test(parent.message)
+        ? 'Connection refused'
+        : `Unable to connect to Kafka: ${parent.message}`;
+    return new errors_1.ConnectionError(message, {
+        parent,
+        database: 'kafka',
+        host: brokers?.join(','),
+    });
+}
+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 });
+}
+/**
+ * `KafkaStore` wraps a `kafkajs` client and exposes Kafka's core operations:
+ * producing messages, topic administration, and consumer subscriptions.
+ */
+class KafkaStore {
+    constructor(options = {}) {
+        this.name = 'kafka';
+        this.library = 'kafkajs';
+        this.client = null;
+        this.producer = null;
+        /** Consumers created via `subscribe()`, tracked so `disconnect()` can stop them all. */
+        this.consumers = [];
+        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
+                // `kafkajs` to be installed unless a real connection is made.
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const { Kafka } = require('kafkajs');
+                this.client = new Kafka({
+                    clientId: this.options.clientId,
+                    brokers: this.options.brokers ?? [],
+                    ssl: this.options.ssl,
+                    sasl: this.options.sasl,
+                });
+            }
+            this.producer = this.client.producer();
+            await this.producer.connect();
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.producer = null;
+            this.connected = false;
+            throw wrapConnectionError(err, this.options.brokers);
+        }
+    }
+    async disconnect() {
+        // Stop consumers first so they stop pulling before the producer/client go.
+        for (const consumer of this.consumers.splice(0)) {
+            try {
+                await consumer.disconnect();
+            }
+            catch {
+                // Best-effort teardown - keep disconnecting the rest.
+            }
+        }
+        if (this.producer) {
+            try {
+                await this.producer.disconnect();
+            }
+            catch {
+                // Best-effort teardown.
+            }
+            this.producer = null;
+        }
+        this.client = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `kafkajs` `Kafka` client for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new errors_1.ConnectionError('Not connected to Kafka', { database: 'kafka' });
+        }
+        return this.client;
+    }
+    requireProducer() {
+        if (!this.producer) {
+            throw new errors_1.ConnectionError('Not connected to Kafka', { database: 'kafka' });
+        }
+        return this.producer;
+    }
+    // ---------------------------------------------------------------------
+    // Producing
+    // ---------------------------------------------------------------------
+    /**
+     * Produce one or more messages to `topic`. Returns kafkajs's record
+     * metadata (per-partition base offsets).
+     */
+    async produce(topic, messages) {
+        const producer = this.requireProducer();
+        try {
+            return await producer.send({ topic, messages });
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `Kafka produce to "${topic}" failed`);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Topic administration
+    // ---------------------------------------------------------------------
+    /**
+     * Create `topic` via a short-lived admin connection. Returns kafkajs's
+     * boolean indicating whether the topic was newly created (`false` if it
+     * already existed).
+     */
+    async createTopic(topic, opts = {}) {
+        const client = this.requireClient();
+        const admin = client.admin();
+        try {
+            await admin.connect();
+            return await admin.createTopics({
+                topics: [
+                    {
+                        topic,
+                        numPartitions: opts.numPartitions,
+                        replicationFactor: opts.replicationFactor,
+                    },
+                ],
+            });
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `Kafka createTopic "${topic}" failed`);
+        }
+        finally {
+            try {
+                await admin.disconnect();
+            }
+            catch {
+                // Best-effort teardown of the admin connection.
+            }
+        }
+    }
+    /** List all topic names known to the cluster via a short-lived admin connection. */
+    async listTopics() {
+        const client = this.requireClient();
+        const admin = client.admin();
+        try {
+            await admin.connect();
+            return await admin.listTopics();
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'Kafka listTopics failed');
+        }
+        finally {
+            try {
+                await admin.disconnect();
+            }
+            catch {
+                // Best-effort teardown of the admin connection.
+            }
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Consuming
+    // ---------------------------------------------------------------------
+    /**
+     * Subscribe a new consumer to `topics` and invoke `handler` for each
+     * message (kafkajs's `eachMessage` payload: `{ topic, partition, message }`).
+     * The consumer joins the group `options.groupId` (a generated id is used if
+     * omitted) and is tracked so `disconnect()` stops it. Returns the created
+     * kafkajs consumer.
+     */
+    async subscribe(topics, handler, options = {}) {
+        const client = this.requireClient();
+        const topicList = Array.isArray(topics) ? topics : [topics];
+        const groupId = options.groupId ?? `${this.options.clientId ?? 'kafka'}-group-${Date.now()}`;
+        const consumer = client.consumer({ groupId });
+        try {
+            await consumer.connect();
+            await consumer.subscribe({
+                topics: topicList,
+                fromBeginning: options.fromBeginning ?? false,
+            });
+            await consumer.run({ eachMessage: handler });
+            this.consumers.push(consumer);
+            return consumer;
+        }
+        catch (err) {
+            try {
+                await consumer.disconnect();
+            }
+            catch {
+                // Don't leak the half-set-up consumer's connection.
+            }
+            throw wrapDatabaseError(err, `Kafka subscribe to "${topicList.join(',')}" failed`);
+        }
+    }
+}
+exports.KafkaStore = KafkaStore;
+exports.default = KafkaStore;

package/dist/nosql/keyspaces/index.js

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyspacesStore = void 0;
+/**
+ * Amazon Keyspaces (for Apache Cassandra) store.
+ *
+ * Amazon Keyspaces is AWS's serverless, fully managed wide-column store that is
+ * compatible with Apache Cassandra: it speaks CQL (Cassandra Query Language)
+ * over the same native protocol, so the standard `cassandra-driver` (DataStax
+ * Node.js driver) connects to it unchanged.
+ *
+ * DEPLOYMENT REQUIREMENTS (real clusters — not exercised by the mock tests):
+ *   - TLS is mandatory. Keyspaces only accepts encrypted connections, so a real
+ *     deployment must pass SSL options (e.g. `sslOptions` with the Starfield /
+ *     Amazon root CA) through `clientOptions`.
+ *   - Authentication is either service-specific credentials (username/password
+ *     via `credentials`) or, preferably, SigV4 request signing using AWS IAM
+ *     credentials via the `aws-sigv4-auth-cassandra-plugin` `AuthProvider`
+ *     (also passed through `clientOptions`).
+ *   - Keyspaces default read/write consistency is `LOCAL_QUORUM`; set it via
+ *     query options / driver profiles as your workload requires.
+ * All of these are plain `cassandra-driver` `Client` options, so they flow
+ * through this store unchanged via `clientOptions` (or a pre-built `client`).
+ *
+ * Like Cassandra, Keyspaces omits joins, arbitrary WHERE-clause filtering, and
+ * subqueries: queries are partition-scoped and data is modelled query-first
+ * around partition and clustering keys. That model does not fit the SQL-shaped
+ * `Dialect` interface (`src/dialects/dialect.ts`), so this store implements the
+ * minimal `NoSqlStore` marker interface (`src/nosql/store.ts`) and exposes CQL
+ * execution directly rather than pretending to be a relational dialect.
+ *
+ * The 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.
+ */
+const errors_1 = require("../../errors");
+/**
+ * `KeyspacesStore` wraps a `cassandra-driver` `Client` pointed at an Amazon
+ * Keyspaces endpoint and exposes CQL execution (`execute`), atomic
+ * multi-statement batches (`batch`), and a few parameterized convenience
+ * helpers (`insert`, `selectAll`).
+ *
+ * Statements are prepared by default (`prepare: true`). All Keyspaces-specific
+ * connection concerns (TLS, SigV4/credentials, LOCAL_QUORUM consistency) are
+ * plain driver options and pass through via `clientOptions` or a pre-built
+ * `client`.
+ */
+class KeyspacesStore {
+    constructor(options = {}) {
+        this.name = 'keyspaces';
+        this.library = 'cassandra-driver';
+        this.client = null;
+        this.connected = false;
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // NoSqlStore lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client) {
+            return;
+        }
+        try {
+            let client = this.options.client;
+            if (!client) {
+                // Lazy-load the optional driver so importing this module never
+                // requires `cassandra-driver` to be installed. Tests inject a mock
+                // `client` above and never reach this branch.
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const cql = require('cassandra-driver');
+                client = new cql.Client({
+                    contactPoints: this.options.contactPoints,
+                    localDataCenter: this.options.localDataCenter,
+                    keyspace: this.options.keyspace,
+                    credentials: this.options.credentials,
+                    ...this.options.clientOptions,
+                });
+            }
+            await client.connect();
+            this.client = client;
+            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 connect to Amazon Keyspaces: ${parent.message}`, {
+                parent,
+                database: 'keyspaces',
+                host: this.options.contactPoints?.[0],
+            });
+        }
+    }
+    async disconnect() {
+        if (this.client) {
+            try {
+                await this.client.shutdown();
+            }
+            finally {
+                this.client = null;
+                this.connected = false;
+            }
+        }
+        else {
+            this.connected = false;
+        }
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `cassandra-driver` `Client` for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client || !this.connected) {
+            throw new errors_1.ConnectionError('Amazon Keyspaces client is not connected. Call connect() first.', {
+                database: 'keyspaces',
+            });
+        }
+        return this.client;
+    }
+    wrapError(action, err) {
+        const parent = err instanceof Error ? err : new Error(String(err));
+        return errors_1.DatabaseError.from(parent, {
+            message: `Amazon Keyspaces ${action} failed: ${parent.message}`,
+        });
+    }
+    // ---------------------------------------------------------------------
+    // CQL execution
+    // ---------------------------------------------------------------------
+    /**
+     * Execute a single CQL statement with optional bound `params`. Statements
+     * are prepared by default (`prepare: true`); pass `opts.prepare = false` to
+     * run a one-off unprepared. Any other driver query options (including
+     * `consistency`, which defaults to `LOCAL_QUORUM` on Keyspaces) are forwarded
+     * via `opts`. Returns the full driver result (with `.rows`).
+     */
+    async execute(query, params = [], opts = {}) {
+        const client = this.requireClient();
+        try {
+            return (await client.execute(query, params, { prepare: true, ...opts }));
+        }
+        catch (err) {
+            throw this.wrapError(`execute (${query})`, err);
+        }
+    }
+    /**
+     * Execute multiple statements as a single logged batch. Each entry is a
+     * `{ query, params }` pair. Prepared by default; forward other driver batch
+     * options via `opts`.
+     */
+    async batch(queries, opts = {}) {
+        const client = this.requireClient();
+        try {
+            return await client.batch(queries, { prepare: true, ...opts });
+        }
+        catch (err) {
+            throw this.wrapError('batch', err);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Convenience helpers
+    // ---------------------------------------------------------------------
+    /**
+     * Convenience `INSERT`: builds a parameterized
+     * `INSERT INTO table (cols...) VALUES (?, ?, ...)` from `obj`'s keys and
+     * executes it (prepared). For upserts with TTL, IF NOT EXISTS, or other
+     * clauses, write the CQL yourself and call `execute()`.
+     */
+    async insert(table, obj, opts = {}) {
+        const columns = Object.keys(obj);
+        if (columns.length === 0) {
+            throw new errors_1.DatabaseError('insert() requires at least one column', {
+                original: 'empty insert object',
+            });
+        }
+        const placeholders = columns.map(() => '?').join(', ');
+        const query = `INSERT INTO ${table} (${columns.join(', ')}) VALUES (${placeholders})`;
+        const params = columns.map((c) => obj[c]);
+        return this.execute(query, params, opts);
+    }
+    /** Convenience `SELECT * FROM table`. Returns the full driver result (with `.rows`). */
+    async selectAll(table, opts = {}) {
+        return this.execute(`SELECT * FROM ${table}`, [], opts);
+    }
+}
+exports.KeyspacesStore = KeyspacesStore;
+exports.default = KeyspacesStore;

package/dist/nosql/kinesis/index.js

@@ -0,0 +1,253 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KinesisStore = void 0;
+/**
+ * Amazon Kinesis Data Streams store.
+ *
+ * Kinesis is a managed, sharded, append-only record-streaming service — a
+ * cloud sibling of Kafka. There is no query language and no SQL-shaped access
+ * pattern, so this store implements the minimal `NoSqlStore` marker interface
+ * (`src/nosql/store.ts`) and exposes Kinesis's real streaming operations:
+ * putting records to a stream (`publish`), a shard-iterator poll loop that
+ * delivers records to a handler (`subscribe`), and stream administration
+ * (`createStream`).
+ *
+ * Built on AWS SDK v3 (`@aws-sdk/client-kinesis`): a `KinesisClient` speaks the
+ * wire protocol via the command pattern — you build a command object
+ * (`new PutRecordCommand(input)`) and hand it to `client.send(command)`. The
+ * SDK is loaded lazily inside `connect()` (via `require`) rather than a
+ * top-level import so importing this module never hard-requires the driver,
+ * and so tests can inject a pre-built mock `client` (with a `send(command)`
+ * method) and never load the SDK or touch the network.
+ *
+ * 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 record's `Data`.
+ */
+const errors_1 = require("../../errors");
+/** Encode a message into the `Uint8Array` Kinesis stores as a record `Data`. */
+function toBytes(message) {
+    if (Buffer.isBuffer(message))
+        return message;
+    if (message instanceof Uint8Array)
+        return message;
+    if (typeof message === 'string')
+        return Buffer.from(message, 'utf8');
+    return Buffer.from(JSON.stringify(message), 'utf8');
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        // Don't let a pending poll-interval timer keep the process alive.
+        timer.unref?.();
+    });
+}
+/**
+ * `KinesisStore` wraps an AWS v3 `KinesisClient` and exposes stream producing,
+ * a shard-iterator consumer loop, and stream administration.
+ */
+class KinesisStore {
+    constructor(options = {}) {
+        this.name = 'kinesis';
+        this.library = '@aws-sdk/client-kinesis';
+        this.client = null;
+        this.aws = null;
+        this.connected = false;
+        /** Active subscriptions, tracked so `disconnect()` can stop their poll loops. */
+        this.subscriptions = new Set();
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        try {
+            if (this.options.client) {
+                this.client = this.options.client;
+                this.tryLoadSdk();
+            }
+            else {
+                const aws = require('@aws-sdk/client-kinesis');
+                this.aws = aws;
+                this.client = new aws.KinesisClient({
+                    region: this.options.region,
+                    credentials: this.options.credentials,
+                    endpoint: this.options.endpoint,
+                });
+            }
+            this.connected = true;
+        }
+        catch (err) {
+            this.connected = false;
+            this.client = null;
+            this.aws = null;
+            throw new errors_1.ConnectionError(`Failed to connect to Kinesis: ${err instanceof Error ? err.message : String(err)}`, { parent: err instanceof Error ? err : undefined, database: 'kinesis' });
+        }
+    }
+    /** Best-effort lazy-load of the SDK for its command constructors (see `command()`). */
+    tryLoadSdk() {
+        if (this.aws)
+            return;
+        try {
+            this.aws = require('@aws-sdk/client-kinesis');
+        }
+        catch {
+            this.aws = null;
+        }
+    }
+    async disconnect() {
+        for (const sub of this.subscriptions) {
+            try {
+                sub.stop();
+            }
+            catch {
+                // Best-effort teardown.
+            }
+        }
+        this.subscriptions.clear();
+        try {
+            this.client?.destroy?.();
+        }
+        finally {
+            this.client = null;
+            this.aws = null;
+            this.connected = false;
+        }
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `KinesisClient` (loosely typed) for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client || !this.connected) {
+            throw new errors_1.ConnectionError('Kinesis client is not connected. Call connect() first.', {
+                database: 'kinesis',
+            });
+        }
+        return this.client;
+    }
+    /** Resolve a command constructor by name from the (lazily loaded) SDK. */
+    command(name, input) {
+        if (!this.aws)
+            this.tryLoadSdk();
+        const Ctor = this.aws?.[name];
+        if (typeof Ctor !== 'function') {
+            throw new errors_1.ConnectionError(`Kinesis command '${name}' is unavailable: '@aws-sdk/client-kinesis' could not be loaded.`, { database: 'kinesis' });
+        }
+        return new Ctor(input);
+    }
+    wrapError(action, err) {
+        const parent = err instanceof Error ? err : new Error(String(err));
+        const name = parent.name ? ` (${parent.name})` : '';
+        return new errors_1.DatabaseError(`Kinesis ${action} failed${name}: ${parent.message}`, {
+            parent,
+            original: parent.message,
+        });
+    }
+    // ---------------------------------------------------------------------
+    // Producing
+    // ---------------------------------------------------------------------
+    /**
+     * `PutRecord` — publish one `message` to `stream`. The message is encoded to
+     * bytes (string → UTF-8, Buffer → as-is, else JSON). Returns the shard id and
+     * sequence number assigned by Kinesis.
+     */
+    async publish(stream, message, options = {}) {
+        const client = this.requireClient();
+        try {
+            const result = await client.send(this.command('PutRecordCommand', {
+                StreamName: stream,
+                Data: toBytes(message),
+                PartitionKey: options.partitionKey ?? `pk-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+                ExplicitHashKey: options.explicitHashKey,
+                SequenceNumberForOrdering: options.sequenceNumberForOrdering,
+            }));
+            return { shardId: result?.ShardId, sequenceNumber: result?.SequenceNumber };
+        }
+        catch (err) {
+            throw this.wrapError(`PutRecord on '${stream}'`, err);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Stream administration
+    // ---------------------------------------------------------------------
+    /** `CreateStream` — provision a new stream. */
+    async createStream(name, options = {}) {
+        const client = this.requireClient();
+        try {
+            await client.send(this.command('CreateStreamCommand', {
+                StreamName: name,
+                ShardCount: options.shardCount ?? 1,
+                StreamModeDetails: options.streamMode ? { StreamMode: options.streamMode } : undefined,
+            }));
+        }
+        catch (err) {
+            throw this.wrapError(`CreateStream '${name}'`, err);
+        }
+    }
+    /** Alias for `createStream()`, matching the common store surface. */
+    createTopic(name, options = {}) {
+        return this.createStream(name, options);
+    }
+    // ---------------------------------------------------------------------
+    // Consuming
+    // ---------------------------------------------------------------------
+    /**
+     * Subscribe to `stream`: acquire a shard iterator (`GetShardIterator`) and
+     * poll `GetRecords` in a loop, invoking `handler` once per record. Returns a
+     * subscription whose `stop()` ends the loop; the subscription is also tracked
+     * so `disconnect()` stops it. The poll loop runs detached (not awaited); this
+     * method resolves once the initial iterator is acquired.
+     */
+    async subscribe(stream, handler, options = {}) {
+        const client = this.requireClient();
+        const shardId = options.shardId ?? 'shardId-000000000000';
+        const pollIntervalMs = options.pollIntervalMs ?? 1000;
+        let iterator;
+        try {
+            const iterResult = await client.send(this.command('GetShardIteratorCommand', {
+                StreamName: stream,
+                ShardId: shardId,
+                ShardIteratorType: options.shardIteratorType ?? 'LATEST',
+                StartingSequenceNumber: options.startingSequenceNumber,
+            }));
+            iterator = iterResult?.ShardIterator;
+        }
+        catch (err) {
+            throw this.wrapError(`GetShardIterator on '${stream}'`, err);
+        }
+        let stopped = false;
+        const subscription = {
+            stop: () => {
+                stopped = true;
+                this.subscriptions.delete(subscription);
+            },
+        };
+        this.subscriptions.add(subscription);
+        const loop = async () => {
+            while (!stopped && iterator) {
+                const result = await client.send(this.command('GetRecordsCommand', { ShardIterator: iterator, Limit: options.limit }));
+                const records = result?.Records ?? [];
+                for (const record of records) {
+                    if (stopped)
+                        break;
+                    await handler(record);
+                }
+                iterator = result?.NextShardIterator;
+                if (stopped || !iterator)
+                    break;
+                await sleep(pollIntervalMs);
+            }
+        };
+        // Detached: consuming is a long-lived loop, not part of subscribe()'s resolution.
+        loop().catch(() => {
+            /* swallow — the loop is best-effort background polling */
+        });
+        return subscription;
+    }
+}
+exports.KinesisStore = KinesisStore;
+exports.default = KinesisStore;