ts-prorm-orm 1.1.0

package/dist/nosql/rocksdb/index.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RocksDBStore = void 0;
+/**
+ * RocksDB store.
+ *
+ * RocksDB is an embedded, in-process LSM-tree key-value store (no server). A
+ * store is opened against a filesystem path and exposes ordered key-value
+ * primitives — `put`/`get`/`del`, atomic `batch` writes, and ordered
+ * iteration. It has no query language and no SQL-shaped surface (`query(sql)`,
+ * identifier escaping, DDL), 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 exposes RocksDB's
+ * real KV surface directly.
+ *
+ * Built on the `rocksdb` npm driver (an `abstract-level` store). 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 and never reach the `require`.
+ */
+const errors_1 = require("../../errors");
+/**
+ * `RocksDBStore` wraps a `rocksdb` client and exposes its embedded KV surface:
+ * `put`/`get`/`del` for single keys, `batch` for atomic multi-key writes,
+ * and `list` for ordered key iteration (optionally by prefix).
+ */
+class RocksDBStore {
+    constructor(options = {}) {
+        this.name = 'rocksdb';
+        this.library = 'rocksdb';
+        this.client = null;
+        this.connected = false;
+        this.options = options;
+        this.path = options.path ?? './data/rocksdb';
+    }
+    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 RocksDB = require('rocksdb');
+                this.client = RocksDB(this.path);
+            }
+            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 RocksDB: ${parent.message}`, {
+                parent,
+                database: 'rocksdb',
+            });
+        }
+    }
+    async disconnect() {
+        if (this.client) {
+            try {
+                await this.client.close();
+            }
+            catch {
+                // best-effort close
+            }
+            this.client = null;
+        }
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `rocksdb` client for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client || !this.connected) {
+            throw new errors_1.ConnectionError('RocksDB client is not connected. Call connect() first.', {
+                database: 'rocksdb',
+            });
+        }
+        return this.client;
+    }
+    wrapError(action, err) {
+        const parent = err instanceof Error ? err : new Error(String(err));
+        return errors_1.DatabaseError.from(parent, { message: `RocksDB ${action} failed: ${parent.message}` });
+    }
+    /** Writes (or overwrites) the value at `key`. */
+    async put(key, value) {
+        const client = this.requireClient();
+        try {
+            await client.put(key, value);
+        }
+        catch (err) {
+            throw this.wrapError('put', err);
+        }
+    }
+    /** Reads the value at `key`. */
+    async get(key) {
+        const client = this.requireClient();
+        try {
+            return await client.get(key);
+        }
+        catch (err) {
+            throw this.wrapError('get', err);
+        }
+    }
+    /** Deletes the value at `key`. */
+    async del(key) {
+        const client = this.requireClient();
+        try {
+            await client.del(key);
+        }
+        catch (err) {
+            throw this.wrapError('del', err);
+        }
+    }
+    /** Applies a list of `put`/`del` operations as a single atomic batch. */
+    async batch(ops) {
+        const client = this.requireClient();
+        try {
+            await client.batch(ops);
+        }
+        catch (err) {
+            throw this.wrapError('batch', err);
+        }
+    }
+    /**
+     * Lists keys in order. With `prefix`, restricts to keys `>= prefix` and
+     * `< prefix + '\xff'` (a standard prefix-scan range for byte-ordered keys).
+     */
+    async list(prefix) {
+        const client = this.requireClient();
+        try {
+            const range = prefix !== undefined ? { gte: prefix, lt: `${prefix}\xff` } : {};
+            const keys = [];
+            for await (const [key] of client.iterator(range)) {
+                keys.push(String(key));
+            }
+            return keys;
+        }
+        catch (err) {
+            throw this.wrapError('list', err);
+        }
+    }
+}
+exports.RocksDBStore = RocksDBStore;
+exports.default = RocksDBStore;

package/dist/nosql/rockset/index.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * Rockset store.
+ *
+ * Rockset is a real-time analytics database that indexes streaming and
+ * document data (a "converged index" over row, columnar, and inverted
+ * indexes) and serves low-latency SQL over it. It is a schemaless,
+ * document-oriented, HTTP/JSON service with an official client
+ * (`@rockset/client`); there is no relational connection, no server-side
+ * transactions, and ingestion is document-based (`addDocuments`), so it does
+ * not fit the SQL-shaped `Dialect` interface (`src/dialects/dialect.ts`).
+ * This class implements the minimal `NoSqlStore` marker interface
+ * (`src/nosql/store.ts`) and exposes Rockset's query + document API directly.
+ *
+ * ## Driver: `@rockset/client`
+ *
+ * The `@rockset/client` package is an optional peer dependency, lazily
+ * `require`d inside `connect()` so importing this module never forces it to be
+ * installed. Tests inject a pre-built mock client via `RocksetStoreOptions.client`,
+ * which skips the `require` entirely.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RocksetStore = void 0;
+const errors_1 = require("../../errors");
+/**
+ * `RocksetStore` wraps a `@rockset/client` instance and exposes SQL querying
+ * (`query`) plus document ingestion (`ingest`) into a `workspace.collection`.
+ */
+class RocksetStore {
+    constructor(options = {}) {
+        this.name = 'rockset';
+        this.library = '@rockset/client';
+        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) {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const mod = require('@rockset/client');
+                const factory = mod.default ?? mod;
+                client = factory(this.options.apiKey, this.options.host);
+            }
+            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 Rockset: ${parent.message}`, {
+                parent,
+                database: 'rockset',
+                host: this.options.host,
+            });
+        }
+    }
+    async disconnect() {
+        this.client = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `@rockset/client` instance for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client || !this.connected) {
+            throw new errors_1.ConnectionError('Rockset client is not connected. Call connect() first.', {
+                database: 'rockset',
+            });
+        }
+        return this.client;
+    }
+    // ---------------------------------------------------------------------
+    // Query + ingest
+    // ---------------------------------------------------------------------
+    /**
+     * Run a SQL query via `client.queries.query({ sql: { query, parameters } })`
+     * and return the `results` array from the response.
+     */
+    async query(sql, params) {
+        const client = this.requireClient();
+        try {
+            const request = {
+                sql: params && params.length > 0 ? { query: sql, parameters: params } : { query: sql },
+            };
+            const response = await client.queries.query(request);
+            return (response?.results ?? []);
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, { message: `Rockset query failed: ${parent.message}`, sql });
+        }
+    }
+    /**
+     * Ingest `docs` into `target` (a `workspace.collection` path, or just a
+     * collection name — defaulting the workspace to `commons`) via
+     * `client.documents.addDocuments(workspace, collection, { data })`.
+     */
+    async ingest(target, docs) {
+        const client = this.requireClient();
+        const [workspace, collection] = target.includes('.')
+            ? [target.slice(0, target.indexOf('.')), target.slice(target.indexOf('.') + 1)]
+            : ['commons', target];
+        try {
+            return await client.documents.addDocuments(workspace, collection, { data: docs });
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, { message: `Rockset ingest failed: ${parent.message}` });
+        }
+    }
+}
+exports.RocksetStore = RocksetStore;
+exports.default = RocksetStore;

package/dist/nosql/s3/index.js

@@ -0,0 +1,298 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.S3Store = void 0;
+/**
+ * Amazon S3 object-storage store.
+ *
+ * S3 is an object store, not a database — there is no query language, no
+ * rows, and no SQL-shaped access pattern. Data is organized as opaque
+ * objects (arbitrary byte bodies plus metadata) addressed by a `(bucket,
+ * key)` pair, where the "key" is a flat string that only *looks* like a
+ * path (`foo/bar/baz.json`) — S3 has no real directories, just an optional
+ * key `prefix` you can filter listings by. None of that fits the SQL-shaped
+ * `Dialect` interface (`src/dialects/dialect.ts`), so this store implements
+ * the minimal `NoSqlStore` marker interface (`src/nosql/store.ts`) and
+ * exposes S3's own object-level operations directly.
+ *
+ * Built on AWS SDK v3 (`@aws-sdk/client-s3`): an `S3Client` speaks the S3
+ * wire protocol via the command pattern — you construct a command object
+ * (`new PutObjectCommand(input)`) and hand it to `client.send(command)`.
+ * The SDK is loaded lazily inside `connect()` (via `require`) rather than a
+ * top-level import so that importing this module doesn't hard-require the
+ * `@aws-sdk/client-s3` package unless an S3 store is actually connected —
+ * and so tests can inject a pre-built mock `client` and never load the SDK
+ * at all.
+ */
+const errors_1 = require("../../errors");
+/**
+ * Amazon S3 store, implementing the minimal `NoSqlStore` marker interface.
+ * Unlike the SQL dialects, there is no `query(sql)` — S3's operations are
+ * object-shaped (Put/Get/Delete/List/Head/Copy) and that shape is preserved
+ * here rather than forced into a SQL string.
+ */
+class S3Store {
+    constructor(options = {}) {
+        this.name = 's3';
+        this.library = '@aws-sdk/client-s3';
+        this.client = null;
+        this.aws = null;
+        this.connected = false;
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // NoSqlStore lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        try {
+            if (this.options.client) {
+                // A pre-built client was injected (mock or custom). Use it directly
+                // and don't require the SDK at all — the command constructors are
+                // only needed when we build them ourselves below, but with an
+                // injected client the caller/test provides commands' behavior via
+                // the mock's `send`. We still lazy-load the SDK for the command
+                // classes if it happens to be available; if not, callers using an
+                // injected client typically only exercise `send`, and the command
+                // classes are loaded on demand in each method.
+                this.client = this.options.client;
+                this.tryLoadSdk();
+            }
+            else {
+                const aws = require('@aws-sdk/client-s3');
+                this.aws = aws;
+                this.client = new aws.S3Client({
+                    region: this.options.region,
+                    credentials: this.options.credentials,
+                    endpoint: this.options.endpoint,
+                    forcePathStyle: this.options.forcePathStyle,
+                });
+            }
+            this.connected = true;
+        }
+        catch (err) {
+            this.connected = false;
+            this.client = null;
+            this.aws = null;
+            throw new errors_1.ConnectionError(`Failed to connect to S3: ${err instanceof Error ? err.message : String(err)}`, { parent: err instanceof Error ? err : undefined });
+        }
+    }
+    /**
+     * Attempt to lazy-load `@aws-sdk/client-s3` for its command constructors.
+     * Best-effort: when a client was injected (e.g. a test mock) the SDK may
+     * not be installed, so a failure here is swallowed and the command classes
+     * are loaded on demand instead (see `command()`).
+     */
+    tryLoadSdk() {
+        if (this.aws)
+            return;
+        try {
+            this.aws = require('@aws-sdk/client-s3');
+        }
+        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 `S3Client` (loosely typed) for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client || !this.connected) {
+            throw new errors_1.ConnectionError('S3 client is not connected. Call connect() first.');
+        }
+        return this.client;
+    }
+    /**
+     * Resolve an S3 command constructor by name from the (lazily loaded) SDK,
+     * so that with an injected mock client we only load `@aws-sdk/client-s3`
+     * the first time a command is actually built. Throws a `ConnectionError`
+     * if the SDK genuinely can't be resolved.
+     */
+    command(name, input) {
+        if (!this.aws) {
+            this.tryLoadSdk();
+        }
+        const Ctor = this.aws?.[name];
+        if (typeof Ctor !== 'function') {
+            throw new errors_1.ConnectionError(`S3 command '${name}' is unavailable: '@aws-sdk/client-s3' could not be loaded.`);
+        }
+        return new Ctor(input);
+    }
+    /** Wraps an AWS SDK failure in a `DatabaseError`, preserving the original error. */
+    wrapError(action, err) {
+        const parent = err instanceof Error ? err : new Error(String(err));
+        const name = parent.name ? ` (${parent.name})` : '';
+        return new errors_1.DatabaseError(`S3 ${action} failed${name}: ${parent.message}`, {
+            parent,
+            original: parent.message,
+        });
+    }
+    // ---------------------------------------------------------------------
+    // Object operations
+    // ---------------------------------------------------------------------
+    /** `PutObject` — store an object's body (and optional metadata) under `bucket`/`key`. */
+    async putObject(bucket, key, body, options = {}) {
+        const client = this.requireClient();
+        try {
+            const result = await client.send(this.command('PutObjectCommand', {
+                Bucket: bucket,
+                Key: key,
+                Body: body,
+                ContentType: options.contentType,
+                Metadata: options.metadata,
+                CacheControl: options.cacheControl,
+                ContentEncoding: options.contentEncoding,
+                ACL: options.acl,
+                ServerSideEncryption: options.serverSideEncryption,
+            }));
+            return { etag: result?.ETag, versionId: result?.VersionId };
+        }
+        catch (err) {
+            throw this.wrapError(`PutObject on '${bucket}/${key}'`, err);
+        }
+    }
+    /** `GetObject` — fetch an object's body and metadata. */
+    async getObject(bucket, key) {
+        const client = this.requireClient();
+        try {
+            const result = await client.send(this.command('GetObjectCommand', { Bucket: bucket, Key: key }));
+            return {
+                body: result?.Body,
+                contentType: result?.ContentType,
+                contentLength: result?.ContentLength,
+                etag: result?.ETag,
+                lastModified: result?.LastModified,
+                metadata: result?.Metadata,
+            };
+        }
+        catch (err) {
+            throw this.wrapError(`GetObject on '${bucket}/${key}'`, err);
+        }
+    }
+    /** `DeleteObject` — remove an object. Succeeds even if the key doesn't exist. */
+    async deleteObject(bucket, key) {
+        const client = this.requireClient();
+        try {
+            await client.send(this.command('DeleteObjectCommand', { Bucket: bucket, Key: key }));
+        }
+        catch (err) {
+            throw this.wrapError(`DeleteObject on '${bucket}/${key}'`, err);
+        }
+    }
+    /**
+     * `ListObjectsV2` — list objects in `bucket`, optionally restricted to
+     * those whose key starts with `prefix`. A single call returns at most
+     * 1000 objects; use `result.nextContinuationToken` (via the raw client)
+     * to page beyond that.
+     */
+    async listObjects(bucket, prefix) {
+        const client = this.requireClient();
+        try {
+            const result = await client.send(this.command('ListObjectsV2Command', { Bucket: bucket, Prefix: prefix }));
+            const contents = result?.Contents ?? [];
+            return {
+                objects: contents.map((o) => ({
+                    key: o?.Key,
+                    size: o?.Size,
+                    etag: o?.ETag,
+                    lastModified: o?.LastModified,
+                })),
+                isTruncated: Boolean(result?.IsTruncated),
+                nextContinuationToken: result?.NextContinuationToken,
+            };
+        }
+        catch (err) {
+            throw this.wrapError(`ListObjects on '${bucket}'`, err);
+        }
+    }
+    /** `HeadObject` — fetch an object's metadata without its body. Throws (NotFound) if the object doesn't exist. */
+    async headObject(bucket, key) {
+        const client = this.requireClient();
+        try {
+            const result = await client.send(this.command('HeadObjectCommand', { Bucket: bucket, Key: key }));
+            return {
+                contentType: result?.ContentType,
+                contentLength: result?.ContentLength,
+                etag: result?.ETag,
+                lastModified: result?.LastModified,
+                metadata: result?.Metadata,
+            };
+        }
+        catch (err) {
+            throw this.wrapError(`HeadObject on '${bucket}/${key}'`, err);
+        }
+    }
+    /**
+     * Whether an object exists, implemented via `HeadObject`. Returns `false`
+     * when S3 reports the object is missing (a `NotFound` / 404 error) rather
+     * than throwing; any other error (e.g. access denied) is re-thrown.
+     */
+    async objectExists(bucket, key) {
+        try {
+            await this.headObject(bucket, key);
+            return true;
+        }
+        catch (err) {
+            if (this.isNotFound(err)) {
+                return false;
+            }
+            throw err;
+        }
+    }
+    /** `CopyObject` — server-side copy from `srcBucket`/`srcKey` to `destBucket`/`destKey`. */
+    async copyObject(srcBucket, srcKey, destBucket, destKey) {
+        const client = this.requireClient();
+        // CopySource is a URL-encoded `bucket/key` reference to the source object.
+        const copySource = `${srcBucket}/${srcKey}`;
+        try {
+            const result = await client.send(this.command('CopyObjectCommand', {
+                Bucket: destBucket,
+                Key: destKey,
+                CopySource: copySource,
+            }));
+            return {
+                etag: result?.CopyObjectResult?.ETag,
+                lastModified: result?.CopyObjectResult?.LastModified,
+            };
+        }
+        catch (err) {
+            throw this.wrapError(`CopyObject from '${srcBucket}/${srcKey}' to '${destBucket}/${destKey}'`, err);
+        }
+    }
+    /**
+     * Recognize S3's "object does not exist" errors across the shapes the SDK
+     * (and its wrapped form here) can surface them: the raw error's `.name`
+     * (`NotFound`, `NoSuchKey`), its HTTP status (404), or the wrapped
+     * `DatabaseError`'s `.parent`.
+     */
+    isNotFound(err) {
+        const candidates = [err];
+        const parent = err?.parent;
+        if (parent)
+            candidates.push(parent);
+        for (const c of candidates) {
+            const name = c?.name;
+            if (name === 'NotFound' || name === 'NoSuchKey')
+                return true;
+            const status = c?.$metadata?.httpStatusCode ??
+                c?.statusCode;
+            if (status === 404)
+                return true;
+        }
+        return false;
+    }
+}
+exports.S3Store = S3Store;
+exports.default = S3Store;