ts-prorm-orm 1.1.0

package/dist/nosql/scylladb/index.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScyllaStore = void 0;
+/**
+ * ScyllaDB (CQL) store.
+ *
+ * ScyllaDB is a wide-column, partition-key-based distributed store that is
+ * wire- and query-compatible with Apache Cassandra: it speaks the same CQL
+ * (Cassandra Query Language) and native protocol, so the same `cassandra-driver`
+ * (DataStax Node.js driver) connects to it unchanged. Its distinguishing trait
+ * is a C++, shard-per-core (seastar) architecture aimed at much higher
+ * throughput and lower, more predictable latency than the JVM-based Cassandra.
+ *
+ * Like Cassandra, ScyllaDB deliberately omits joins, arbitrary WHERE-clause
+ * filtering, and subqueries: every query must be answerable from a single
+ * partition (or an explicitly designed secondary index / materialized view),
+ * 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.
+ *
+ * Built on the `cassandra-driver`. The driver is an optional peer dependency
+ * and is 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");
+/**
+ * `ScyllaStore` wraps a `cassandra-driver` `Client` 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`) so the driver can cache
+ * query metadata, infer parameter types, and route requests to the shard/replica
+ * that owns the partition — the recommended default for anything run more than
+ * once, and especially valuable on ScyllaDB's shard-aware driver path.
+ */
+class ScyllaStore {
+    constructor(options = {}) {
+        this.name = 'scylladb';
+        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 ScyllaDB: ${parent.message}`, {
+                parent,
+                database: 'scylladb',
+                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('ScyllaDB client is not connected. Call connect() first.', {
+                database: 'scylladb',
+            });
+        }
+        return this.client;
+    }
+    wrapError(action, err) {
+        const parent = err instanceof Error ? err : new Error(String(err));
+        return errors_1.DatabaseError.from(parent, { message: `ScyllaDB ${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 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 (atomic across the
+     * statements, though not isolated — CQL batches are not SQL transactions).
+     * 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.ScyllaStore = ScyllaStore;
+exports.default = ScyllaStore;

package/dist/nosql/signoz/index.js

@@ -0,0 +1,227 @@
+"use strict";
+/**
+ * SigNoz store implementation.
+ *
+ * SigNoz is an open-source, ClickHouse-backed observability platform for
+ * logs, traces, and metrics. Logs are ingested over OTLP/HTTP (the
+ * OpenTelemetry logs protocol) and queried through SigNoz's query-range API
+ * (a builder-style JSON body over its ClickHouse store). There is no
+ * SQL-shaped query surface exposed to clients, no row-level UPDATE/DELETE,
+ * and no identifier escaping, so SigNoz does not fit the SQL `Dialect`
+ * interface (`src/dialects/dialect.ts`). This class implements the minimal
+ * `NoSqlStore` marker interface (`src/nosql/store.ts`) and exposes SigNoz's
+ * OTLP ingest + query API.
+ *
+ * ## No canonical driver - HTTP over `fetch`
+ *
+ * SigNoz has no single canonical npm client; ingest is OTLP/HTTP JSON and
+ * query is a REST/JSON API. This store talks to both with the global `fetch`
+ * (so `library` is `'fetch'`). For tests (and custom transports) an
+ * alternative HTTP client can be injected via `SigNozStoreOptions.client`.
+ *
+ * ## Endpoints wrapped
+ *
+ * - `push(resource, entries)` -> `POST /v1/logs`          (OTLP/HTTP ingest)
+ * - `query(builder, opts?)`   -> `POST /api/v4/query_range` (query-range)
+ * - `labels()`                -> `GET  /api/v1/logs/fields`  (log field keys)
+ * - `streams()`               -> `GET  /api/v1/services`     (services)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SigNozStore = exports.DEFAULT_SIGNOZ_BASE_URL = void 0;
+exports.createFetchClient = createFetchClient;
+const errors_1 = require("../../errors");
+/** Default SigNoz base URL (query service). */
+exports.DEFAULT_SIGNOZ_BASE_URL = 'http://localhost:8080';
+/** Build a `fetch`-backed client for the given base URL. */
+function createFetchClient(baseURL, headers) {
+    const buildUrl = (path, params) => {
+        const url = new URL(path, baseURL.endsWith('/') ? baseURL : `${baseURL}/`);
+        for (const [key, value] of Object.entries(params ?? {})) {
+            if (value === undefined)
+                continue;
+            if (Array.isArray(value)) {
+                for (const item of value)
+                    url.searchParams.append(key, item);
+            }
+            else {
+                url.searchParams.set(key, value);
+            }
+        }
+        return url.toString();
+    };
+    return {
+        async get(path, params) {
+            const res = await fetch(buildUrl(path, params), {
+                method: 'GET',
+                headers: { Accept: 'application/json', ...(headers ?? {}) },
+            });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status} ${res.statusText}`);
+            return res.json();
+        },
+        async post(path, body, contentType) {
+            const res = await fetch(buildUrl(path), {
+                method: 'POST',
+                body,
+                headers: { ...(headers ?? {}), ...(contentType ? { 'Content-Type': contentType } : {}) },
+            });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status} ${res.statusText}`);
+            const text = await res.text();
+            if (!text)
+                return undefined;
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                return text;
+            }
+        },
+    };
+}
+/** Map a simplified attribute value into an OTLP AnyValue. */
+function toAnyValue(value) {
+    if (typeof value === 'number') {
+        return Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value };
+    }
+    if (typeof value === 'boolean')
+        return { boolValue: value };
+    return { stringValue: value };
+}
+/**
+ * `SigNozStore` wraps SigNoz's OTLP/HTTP log ingest and its query-range API
+ * (plus log-field and service metadata) behind the `NoSqlStore` lifecycle.
+ */
+class SigNozStore {
+    constructor(options = {}) {
+        this.name = 'signoz';
+        this.library = 'fetch';
+        this.client = null;
+        this.connected = false;
+        this.baseURL = options.baseURL ?? exports.DEFAULT_SIGNOZ_BASE_URL;
+        this.injectedClient = options.client;
+        this.headers = options.headers;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client)
+            return;
+        this.client = this.injectedClient ?? createFetchClient(this.baseURL, this.headers);
+        this.connected = true;
+    }
+    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 SigNoz', {
+                database: 'signoz',
+                host: this.baseURL,
+            });
+        }
+        return this.client;
+    }
+    async doGet(path, params, action) {
+        const client = this.requireClient();
+        try {
+            return await client.get(path, params);
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, {
+                message: `SigNoz ${action ?? 'request'} failed: ${parent.message}`,
+            });
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Ingest (OTLP/HTTP)
+    // ---------------------------------------------------------------------
+    /**
+     * Ingests log records over OTLP/HTTP via `POST /v1/logs`. The simplified
+     * `entries` are assembled into the OTLP `resourceLogs -> scopeLogs ->
+     * logRecords` envelope, tagged with the shared `resource` attributes.
+     */
+    async push(resource, entries) {
+        const client = this.requireClient();
+        const payload = {
+            resourceLogs: [
+                {
+                    resource: {
+                        attributes: Object.entries(resource).map(([key, value]) => ({
+                            key,
+                            value: toAnyValue(value),
+                        })),
+                    },
+                    scopeLogs: [
+                        {
+                            logRecords: entries.map((e) => ({
+                                timeUnixNano: e.timeUnixNano === undefined ? undefined : String(e.timeUnixNano),
+                                severityText: e.severity,
+                                body: { stringValue: e.body },
+                                attributes: Object.entries(e.attributes ?? {}).map(([key, value]) => ({
+                                    key,
+                                    value: toAnyValue(value),
+                                })),
+                            })),
+                        },
+                    ],
+                },
+            ],
+        };
+        try {
+            return await client.post('/v1/logs', JSON.stringify(payload), 'application/json');
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, { message: `SigNoz push failed: ${parent.message}` });
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Query
+    // ---------------------------------------------------------------------
+    /**
+     * Runs a query-range request via `POST /api/v4/query_range`. The
+     * `builder` is SigNoz's composite query payload (`compositeQuery` /
+     * builder queries); `start`/`end`/`step` fill the time window. Returns the
+     * parsed response.
+     */
+    async query(builder, options = {}) {
+        const client = this.requireClient();
+        const payload = {
+            start: options.start,
+            end: options.end,
+            step: options.step,
+            ...builder,
+        };
+        try {
+            return await client.post('/api/v4/query_range', JSON.stringify(payload), 'application/json');
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, { message: `SigNoz query failed: ${parent.message}` });
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Metadata
+    // ---------------------------------------------------------------------
+    /** Lists the known log field/attribute keys via `GET /api/v1/logs/fields`. */
+    async labels() {
+        return this.doGet('/api/v1/logs/fields', undefined, 'labels');
+    }
+    /** Lists the observed services via `GET /api/v1/services`. */
+    async streams() {
+        return this.doGet('/api/v1/services', undefined, 'streams');
+    }
+}
+exports.SigNozStore = SigNozStore;
+exports.default = SigNozStore;

package/dist/nosql/sns/index.js

@@ -0,0 +1,201 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SnsStore = void 0;
+/**
+ * Amazon SNS (Simple Notification Service) store.
+ *
+ * SNS is a managed, push-based publish/subscribe fan-out service: publishers
+ * send to a topic and SNS pushes to every subscribed endpoint (SQS queue,
+ * Lambda, HTTP(S), email, SMS, ...). 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 SNS's real operations:
+ * publishing to a topic (`publish`), registering a subscription endpoint
+ * (`subscribe`), and topic administration (`createTopic`).
+ *
+ * Built on AWS SDK v3 (`@aws-sdk/client-sns`): an `SNSClient` speaks the wire
+ * protocol via the command pattern — you build a command object
+ * (`new PublishCommand(input)`) and hand it to `client.send(command)`. The SDK
+ * is loaded lazily inside `connect()` (via `require`) so importing this module
+ * never hard-requires the driver, and tests inject a mock `client` (with a
+ * `send(command)` method) so no real SDK or network is used.
+ *
+ * IMPORTANT: SNS delivery is *push*-based — there is no client-side receive
+ * loop. `subscribe()` therefore does NOT take a message handler; it registers
+ * an endpoint (an SQS queue ARN, Lambda ARN, HTTPS URL, email address, ...)
+ * that SNS will push messages to. Consuming those messages happens at that
+ * endpoint (e.g. via `SqsStore.subscribe` on a subscribed queue).
+ *
+ * Message encoding: `publish()` accepts a `string` (sent as-is), a `Buffer`
+ * (decoded to UTF-8), or any other JSON-serializable value (`JSON.stringify`d).
+ * The result becomes the notification `Message`.
+ */
+const errors_1 = require("../../errors");
+/** Encode a message into the string SNS carries as the notification `Message`. */
+function toMessage(message) {
+    if (typeof message === 'string')
+        return message;
+    if (Buffer.isBuffer(message))
+        return message.toString('utf8');
+    return JSON.stringify(message);
+}
+/**
+ * `SnsStore` wraps an AWS v3 `SNSClient` and exposes topic publishing,
+ * endpoint subscription registration, and topic administration.
+ */
+class SnsStore {
+    constructor(options = {}) {
+        this.name = 'sns';
+        this.library = '@aws-sdk/client-sns';
+        this.client = null;
+        this.aws = null;
+        this.connected = false;
+        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-sns');
+                this.aws = aws;
+                this.client = new aws.SNSClient({
+                    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 SNS: ${err instanceof Error ? err.message : String(err)}`, { parent: err instanceof Error ? err : undefined, database: 'sns' });
+        }
+    }
+    tryLoadSdk() {
+        if (this.aws)
+            return;
+        try {
+            this.aws = require('@aws-sdk/client-sns');
+        }
+        catch {
+            this.aws = null;
+        }
+    }
+    async disconnect() {
+        try {
+            this.client?.destroy?.();
+        }
+        finally {
+            this.client = null;
+            this.aws = null;
+            this.connected = false;
+        }
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `SNSClient` (loosely typed) for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client || !this.connected) {
+            throw new errors_1.ConnectionError('SNS client is not connected. Call connect() first.', {
+                database: 'sns',
+            });
+        }
+        return this.client;
+    }
+    command(name, input) {
+        if (!this.aws)
+            this.tryLoadSdk();
+        const Ctor = this.aws?.[name];
+        if (typeof Ctor !== 'function') {
+            throw new errors_1.ConnectionError(`SNS command '${name}' is unavailable: '@aws-sdk/client-sns' could not be loaded.`, { database: 'sns' });
+        }
+        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(`SNS ${action} failed${name}: ${parent.message}`, {
+            parent,
+            original: parent.message,
+        });
+    }
+    // ---------------------------------------------------------------------
+    // Producing
+    // ---------------------------------------------------------------------
+    /**
+     * `Publish` — publish one `message` to the topic at `topicArn`. The message
+     * is encoded to a string (string as-is, Buffer → UTF-8, else JSON). Returns
+     * the message id (and FIFO sequence number, if any).
+     */
+    async publish(topicArn, message, options = {}) {
+        const client = this.requireClient();
+        try {
+            const result = await client.send(this.command('PublishCommand', {
+                TopicArn: topicArn,
+                Message: toMessage(message),
+                Subject: options.subject,
+                MessageGroupId: options.messageGroupId,
+                MessageDeduplicationId: options.messageDeduplicationId,
+                MessageAttributes: options.messageAttributes,
+                MessageStructure: options.messageStructureJson ? 'json' : undefined,
+            }));
+            return { messageId: result?.MessageId, sequenceNumber: result?.SequenceNumber };
+        }
+        catch (err) {
+            throw this.wrapError(`Publish to '${topicArn}'`, err);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Topic administration
+    // ---------------------------------------------------------------------
+    /** `CreateTopic` — create a topic by name. Returns its ARN. */
+    async createTopic(name, attributes) {
+        const client = this.requireClient();
+        try {
+            const result = await client.send(this.command('CreateTopicCommand', { Name: name, Attributes: attributes }));
+            return result?.TopicArn;
+        }
+        catch (err) {
+            throw this.wrapError(`CreateTopic '${name}'`, err);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Subscribing (push-based)
+    // ---------------------------------------------------------------------
+    /**
+     * `Subscribe` — register a push `endpoint` on the topic at `topicArn`. Unlike
+     * poll-based engines, SNS pushes notifications to the endpoint, so this takes
+     * an endpoint (SQS/Lambda ARN, HTTPS URL, email, ...) and a protocol rather
+     * than a message handler. Returns the subscription ARN (or 'pending
+     * confirmation' for endpoints that require confirmation).
+     */
+    async subscribe(topicArn, endpoint, options = {}) {
+        const client = this.requireClient();
+        try {
+            const result = await client.send(this.command('SubscribeCommand', {
+                TopicArn: topicArn,
+                Protocol: options.protocol ?? 'https',
+                Endpoint: endpoint,
+                ReturnSubscriptionArn: options.returnSubscriptionArn,
+                Attributes: options.attributes,
+            }));
+            return result?.SubscriptionArn;
+        }
+        catch (err) {
+            throw this.wrapError(`Subscribe to '${topicArn}'`, err);
+        }
+    }
+}
+exports.SnsStore = SnsStore;
+exports.default = SnsStore;