ts-prorm-orm 1.1.0

package/dist/nosql/arangodb/index.js

@@ -0,0 +1,364 @@
+"use strict";
+/**
+ * ArangoDB store implementation.
+ *
+ * ArangoDB is a multi-model database: it stores JSON documents (like a
+ * document store), lets those documents form named graphs (vertices/edges),
+ * and queries both shapes through a single query language, AQL. None of
+ * that fits the SQL-shaped `Dialect` interface (no `JOIN`, no relational
+ * schema, no `query(sql)` returning rows in the SQL sense), so this class
+ * implements the minimal `NoSqlStore` marker interface and exposes
+ * ArangoDB's real surface directly: collection management, document CRUD,
+ * parameterized AQL queries with cursor-based iteration, graph/edge
+ * operations (including AQL graph traversal), and index management.
+ *
+ * Uses the official `arangojs` driver (v10).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArangoStore = void 0;
+const arangojs_1 = require("arangojs");
+const errors_1 = require("../../errors");
+function wrapConnectionError(err, url) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const host = Array.isArray(url) ? url[0] : url;
+    const message = /econnrefused/i.test(parent.message)
+        ? 'Connection refused'
+        : `Unable to connect to ArangoDB: ${parent.message}`;
+    return new errors_1.ConnectionError(message, { parent, database: 'arangodb', host });
+}
+function wrapDatabaseError(err, message) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    // Keep the `action` context (e.g. "ArangoDB ensureIndex failed") but don't
+    // discard the real underlying error text (e.g. ArangoDB's own
+    // "unique constraint violated" message) - append it so callers inspecting
+    // `err.message` still see what actually went wrong.
+    const combined = message ? `${message}: ${parent.message}` : parent.message;
+    return errors_1.DatabaseError.from(parent, { message: combined });
+}
+/** Normalize `"hash"`/`"skiplist"` (legacy names) to `"persistent"`, the type ArangoDB 3.12+ actually stores them as. */
+function normalizeIndexType(type) {
+    return type === 'hash' || type === 'skiplist' ? 'persistent' : type;
+}
+/**
+ * Whether an `IndexSelector` needs to be resolved to an id-based handle
+ * before being handed to `arangojs`. `IndexSelector`'s TypeScript type
+ * (`ObjectWithIndexId | ObjectWithName | string`) advertises `{ name }` as
+ * a first-class way to identify an index, but `arangojs`'s actual runtime
+ * `_indexHandle()` helper (used by `Collection#index()`/`#dropIndex()`)
+ * only ever looks at `selector.id` - a plain `{ name }` object with no
+ * `id` throws `"Index handle must be a string or an object with an id
+ * attribute"` even when an index with that name exists. See
+ * `resolveIndexSelector()` below, which works around this by looking the
+ * index up by name via `listIndexes()` first.
+ */
+function isNameOnlySelector(selector) {
+    return typeof selector !== 'string' && !('id' in selector) && 'name' in selector && selector.name !== undefined;
+}
+/**
+ * `ArangoStore` wraps the official `arangojs` driver's `Database`/
+ * `Collection`/`Graph`/`Cursor` API in a typed, promise-based convenience
+ * layer covering document CRUD, AQL queries, graphs, and indexes.
+ */
+class ArangoStore {
+    constructor(options = {}) {
+        this.name = 'arangodb';
+        this.library = 'arangojs';
+        this.db = null;
+        this.connected = false;
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    /**
+     * `arangojs`'s `Database` is a thin HTTP client wrapper with no persistent
+     * socket to open, so "connecting" here means constructing it and making
+     * one real request (`version()`) to fail fast on a bad URL/host/auth
+     * instead of only discovering the problem on the first real operation.
+     */
+    async connect() {
+        if (this.connected && this.db) {
+            return;
+        }
+        try {
+            const db = new arangojs_1.Database(this.options);
+            await db.version();
+            this.db = db;
+            this.connected = true;
+        }
+        catch (err) {
+            this.db = null;
+            this.connected = false;
+            throw wrapConnectionError(err, this.options.url);
+        }
+    }
+    async disconnect() {
+        if (this.db) {
+            this.db.close();
+            this.db = null;
+        }
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.db !== null;
+    }
+    /** Returns the underlying `arangojs` `Database` instance for anything not wrapped here. */
+    getClient() {
+        return this.requireDb();
+    }
+    requireDb() {
+        if (!this.db) {
+            throw new errors_1.ConnectionError('Not connected to ArangoDB', { database: 'arangodb' });
+        }
+        return this.db;
+    }
+    async exec(fn, action) {
+        const db = this.requireDb();
+        try {
+            return await fn(db);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `ArangoDB ${action} failed`);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Collection management
+    // ---------------------------------------------------------------------
+    /** Create a document collection. */
+    async createCollection(collectionName, options) {
+        return this.exec(async (db) => {
+            const collection = await db.createCollection(collectionName, options);
+            const result = await collection.properties();
+            return result;
+        }, 'createCollection');
+    }
+    /** Create an edge collection (documents store `_from`/`_to` and can be traversed as graph edges). */
+    async createEdgeCollection(collectionName, options) {
+        return this.exec(async (db) => {
+            const collection = await db.createEdgeCollection(collectionName, options);
+            const result = await collection.properties();
+            return result;
+        }, 'createEdgeCollection');
+    }
+    /** Drop a collection (document or edge). */
+    async dropCollection(collectionName, options) {
+        return this.exec(async (db) => {
+            await db.collection(collectionName).drop(options);
+            return true;
+        }, 'dropCollection');
+    }
+    /** Whether a collection with this name exists. */
+    async collectionExists(collectionName) {
+        return this.exec((db) => db.collection(collectionName).exists(), 'collection.exists');
+    }
+    /** List collections in the database (excludes system collections like `_users` by default). */
+    async listCollections(excludeSystem = true) {
+        return this.exec((db) => db.listCollections(excludeSystem), 'listCollections');
+    }
+    /** Remove all documents from a collection without dropping the collection itself. */
+    async truncateCollection(collectionName) {
+        await this.exec(async (db) => {
+            await db.collection(collectionName).truncate();
+        }, 'truncateCollection');
+    }
+    /** Number of documents currently in a collection. */
+    async collectionCount(collectionName) {
+        return this.exec(async (db) => {
+            const result = await db.collection(collectionName).count();
+            return result.count;
+        }, 'collection.count');
+    }
+    // ---------------------------------------------------------------------
+    // Document CRUD
+    // ---------------------------------------------------------------------
+    /** Insert a single document. Pass `_key` in `data` to choose the key explicitly; otherwise ArangoDB generates one. */
+    async insert(collectionName, data, options) {
+        return this.exec((db) => db.collection(collectionName).save(data, options), 'save');
+    }
+    /** Insert multiple documents in one request. Per-document failures (e.g. duplicate `_key`) come back as entries with `error: true` rather than throwing. */
+    async insertMany(collectionName, data, options) {
+        return this.exec((db) => db.collection(collectionName).saveAll(data, options), 'saveAll');
+    }
+    /** Fetch a single document by key/id. Returns `null` if it does not exist (rather than throwing). */
+    async getDocument(collectionName, selector, options) {
+        return this.exec(async (db) => {
+            const doc = await db
+                .collection(collectionName)
+                .document(selector, { ...options, graceful: true });
+            return (doc ?? null);
+        }, 'document');
+    }
+    /** Fetch multiple documents by key/id. Entries for documents that don't exist come back as `null`. */
+    async getDocuments(collectionName, selectors) {
+        return this.exec(async (db) => {
+            const raw = await db.collection(collectionName).documents(selectors);
+            return raw.map((doc) => doc && doc.error ? null : doc);
+        }, 'documents');
+    }
+    /** Whether a document with this key/id exists in the collection. */
+    async documentExists(collectionName, selector) {
+        return this.exec((db) => db.collection(collectionName).documentExists(selector), 'documentExists');
+    }
+    /** Partially update a document (shallow/deep merge of `patch` into the existing document, per ArangoDB's `PATCH` semantics). */
+    async updateDocument(collectionName, selector, patch, options) {
+        return this.exec((db) => db.collection(collectionName).update(selector, patch, options), 'update');
+    }
+    /** Fully replace a document's content (unlike `updateDocument`, unspecified fields are dropped). */
+    async replaceDocument(collectionName, selector, data, options) {
+        return this.exec((db) => db.collection(collectionName).replace(selector, data, options), 'replace');
+    }
+    /** Delete a single document by key/id. */
+    async removeDocument(collectionName, selector, options) {
+        return this.exec((db) => db.collection(collectionName).remove(selector, options), 'remove');
+    }
+    /** Delete multiple documents by key/id in one request. */
+    async removeDocuments(collectionName, selectors) {
+        return this.exec((db) => db.collection(collectionName).removeAll(selectors), 'removeAll');
+    }
+    // ---------------------------------------------------------------------
+    // AQL queries
+    // ---------------------------------------------------------------------
+    /**
+     * Run a parameterized AQL query and return the (cursor-based) result
+     * set as a native `arangojs` `Cursor` - iterate it with `for await`,
+     * `cursor.next()`, or `cursor.all()` to page through large result sets
+     * without loading everything into memory at once. Use `@name` in `query`
+     * for bind parameters and supply their values via `bindVars` (never
+     * string-interpolate untrusted values into `query` itself).
+     */
+    async query(query, bindVars = {}, options) {
+        return this.exec((db) => db.query(query, bindVars, options), 'query');
+    }
+    /** Convenience wrapper around `query()` that depletes the cursor and returns all results as an array. */
+    async queryAll(query, bindVars = {}, options) {
+        const cursor = await this.query(query, bindVars, options);
+        return cursor.all();
+    }
+    // ---------------------------------------------------------------------
+    // Graphs
+    // ---------------------------------------------------------------------
+    /**
+     * Create a named graph over one or more edge definitions (each mapping
+     * an edge collection to the vertex collection(s) it connects `from` and
+     * `to`). Collections referenced by the edge definitions that don't exist
+     * yet are created automatically by ArangoDB.
+     */
+    async createGraph(graphName, edgeDefinitions, options) {
+        return this.exec((db) => db.graph(graphName).create(edgeDefinitions, options), 'createGraph');
+    }
+    /** Drop a graph. If `dropCollections` is `true`, also drops the graph's vertex/edge collections (as long as they aren't used by another graph). */
+    async dropGraph(graphName, dropCollections = false) {
+        return this.exec((db) => db.graph(graphName).drop(dropCollections), 'graph.drop');
+    }
+    /** Whether a graph with this name exists. */
+    async graphExists(graphName) {
+        return this.exec((db) => db.graph(graphName).exists(), 'graph.exists');
+    }
+    /** List all graphs in the database. */
+    async listGraphs() {
+        return this.exec((db) => db.listGraphs(), 'listGraphs');
+    }
+    /** Add an existing (or new) vertex collection to a graph as an orphan collection (not tied to a specific edge definition). */
+    async addVertexCollection(graphName, collectionName) {
+        return this.exec((db) => db.graph(graphName).addVertexCollection(collectionName), 'graph.addVertexCollection');
+    }
+    /** Add a new edge definition to an existing graph. */
+    async addEdgeDefinition(graphName, edgeDefinition) {
+        return this.exec((db) => db.graph(graphName).addEdgeDefinition(edgeDefinition), 'graph.addEdgeDefinition');
+    }
+    // ---------------------------------------------------------------------
+    // Edges
+    // ---------------------------------------------------------------------
+    /** Insert an edge document into an edge collection, connecting `from` and `to` (each a document `_id`, e.g. `'people/alice'`). */
+    async insertEdge(edgeCollectionName, from, to, data = {}, options) {
+        return this.insert(edgeCollectionName, { ...data, _from: from, _to: to }, options);
+    }
+    /**
+     * Traverse a named graph from a start vertex using AQL's
+     * `FOR v, e, p IN min..max DIRECTION start GRAPH graphName` syntax,
+     * returning each visited vertex (`v`), the edge that reached it (`e`,
+     * `null` at depth 0), and the full path (`p`) as vertex/edge arrays.
+     *
+     * @param startVertexId - Start vertex `_id`, e.g. `'people/alice'`.
+     * @param graphName - Name of a graph created with `createGraph()`.
+     */
+    async traverse(startVertexId, graphName, options = {}) {
+        const direction = options.direction ?? 'OUTBOUND';
+        const minDepth = options.minDepth ?? 1;
+        const maxDepth = options.maxDepth ?? 1;
+        let aqlQuery = `FOR v, e, p IN ${minDepth}..${maxDepth} ${direction} @start GRAPH @graphName`;
+        if (options.filter) {
+            aqlQuery += ` FILTER ${options.filter}`;
+        }
+        if (options.limit !== undefined) {
+            aqlQuery += ` LIMIT ${options.limit}`;
+        }
+        aqlQuery += ' RETURN { vertex: v, edge: e, path: p }';
+        const rows = await this.queryAll(aqlQuery, { start: startVertexId, graphName });
+        return rows;
+    }
+    // ---------------------------------------------------------------------
+    // Indexes
+    // ---------------------------------------------------------------------
+    /** Create an index on a collection. `type: 'hash'`/`'skiplist'` are normalized to `'persistent'` (see `ArangoIndexType`). */
+    async createIndex(collectionName, options) {
+        return this.exec(async (db) => {
+            const type = normalizeIndexType(options.type);
+            const payload = {
+                type,
+                fields: options.fields,
+                name: options.name,
+                unique: options.unique,
+                sparse: options.sparse,
+                geoJson: options.geoJson,
+                minLength: options.minLength,
+                expireAfter: options.expireAfter,
+                inBackground: options.inBackground,
+                // `ensureIndex`'s overloads are keyed on a `type` literal per index
+                // kind; we accept a broader, unified option shape above and pass
+                // only the fields relevant to `type` through, so a runtime cast is
+                // needed here rather than a narrower compile-time overload match.
+            };
+            const result = await db.collection(collectionName).ensureIndex(payload);
+            return result;
+        }, 'ensureIndex');
+    }
+    /** Drop an index by id or name. */
+    async dropIndex(collectionName, selector) {
+        return this.exec(async (db) => {
+            const resolved = await this.resolveIndexSelector(db, collectionName, selector);
+            await db.collection(collectionName).dropIndex(resolved);
+            return true;
+        }, 'dropIndex');
+    }
+    /** List all indexes on a collection (including the automatic primary/edge indexes). */
+    async listIndexes(collectionName) {
+        return this.exec((db) => db.collection(collectionName).indexes(), 'indexes');
+    }
+    /** Fetch a single index's description by id or name. */
+    async getIndex(collectionName, selector) {
+        return this.exec(async (db) => {
+            const resolved = await this.resolveIndexSelector(db, collectionName, selector);
+            return db.collection(collectionName).index(resolved);
+        }, 'index');
+    }
+    /**
+     * Resolve a `{ name }`-only `IndexSelector` to an `{ id }` one by looking
+     * it up via `listIndexes()` first. String selectors and selectors that
+     * already carry an `id` are passed through unchanged - see
+     * `isNameOnlySelector()` for why this is necessary.
+     */
+    async resolveIndexSelector(db, collectionName, selector) {
+        if (!isNameOnlySelector(selector)) {
+            return selector;
+        }
+        const indexes = await db.collection(collectionName).indexes();
+        const found = indexes.find((index) => index.name === selector.name);
+        if (!found) {
+            throw new Error(`Index not found: ${selector.name}`);
+        }
+        return { id: found.id };
+    }
+}
+exports.ArangoStore = ArangoStore;
+exports.default = ArangoStore;

package/dist/nosql/azure-blob/index.js

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AzureBlobStore = void 0;
+/**
+ * Azure Blob Storage store.
+ *
+ * Azure Blob Storage is an object store: opaque byte blobs addressed by a
+ * `container` + `blob name` pair, with no query language, no joins, and no
+ * ad hoc filtering. It 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 Azure
+ * Blob Storage's own object-level operations (upload/download/delete/exists/
+ * list/create-container) directly.
+ *
+ * Built on the official `@azure/storage-blob` SDK. That package is an
+ * optional peer dependency here: it is lazy-`require()`d inside `connect()`
+ * only when a client isn't injected, so importing this module never forces
+ * the SDK to be installed. Tests inject a pre-built `BlobServiceClient` mock
+ * via the `client` option and never touch the real SDK or the network.
+ */
+const errors_1 = require("../../errors");
+function toBuffer(data) {
+    if (Buffer.isBuffer(data))
+        return data;
+    if (typeof data === 'string')
+        return Buffer.from(data);
+    if (data instanceof ArrayBuffer)
+        return Buffer.from(new Uint8Array(data));
+    return Buffer.from(data);
+}
+/** Collect a Node.js readable stream into a single Buffer. */
+function streamToBuffer(stream) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        stream.on('data', (chunk) => chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk));
+        stream.on('end', () => resolve(Buffer.concat(chunks)));
+        stream.on('error', reject);
+    });
+}
+/**
+ * `AzureBlobStore` wraps a `@azure/storage-blob` `BlobServiceClient` and
+ * exposes Azure Blob Storage's object-level operations. It implements the
+ * minimal `NoSqlStore` marker interface — there is no `query(sql)` because
+ * Blob Storage has no query language; access is by container + blob name.
+ */
+class AzureBlobStore {
+    constructor(options = {}) {
+        this.name = 'azure-blob';
+        this.library = '@azure/storage-blob';
+        this.client = null;
+        this.connected = false;
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // NoSqlStore lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client) {
+            return;
+        }
+        try {
+            if (this.options.client) {
+                // An injected client is used as-is; the SDK is never require()d.
+                this.client = this.options.client;
+            }
+            else {
+                // Lazy-load the SDK only when we actually have to build a client, so
+                // this module can be imported without `@azure/storage-blob` installed.
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const az = require('@azure/storage-blob');
+                const connectionString = this.resolveConnectionString();
+                this.client = az.BlobServiceClient.fromConnectionString(connectionString);
+            }
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.connected = false;
+            throw new errors_1.ConnectionError(`Failed to connect to Azure Blob Storage: ${err instanceof Error ? err.message : String(err)}`, { parent: err instanceof Error ? err : undefined, database: 'azure-blob' });
+        }
+    }
+    resolveConnectionString() {
+        if (this.options.connectionString) {
+            return this.options.connectionString;
+        }
+        if (this.options.account && this.options.accountKey) {
+            const suffix = this.options.endpointSuffix ?? 'core.windows.net';
+            return (`DefaultEndpointsProtocol=https;AccountName=${this.options.account};` +
+                `AccountKey=${this.options.accountKey};EndpointSuffix=${suffix}`);
+        }
+        throw new Error('AzureBlobStore requires one of: `client`, `connectionString`, or `account` + `accountKey`.');
+    }
+    async disconnect() {
+        // The `BlobServiceClient` holds no persistent socket to close (each
+        // request is an independent HTTPS call), so there's nothing to tear down
+        // beyond dropping our reference and flipping the connected flag.
+        this.client = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `BlobServiceClient` for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client || !this.connected) {
+            throw new errors_1.ConnectionError('Not connected to Azure Blob Storage. Call connect() first.', {
+                database: 'azure-blob',
+            });
+        }
+        return this.client;
+    }
+    blockBlob(container, key) {
+        return this.requireClient().getContainerClient(container).getBlockBlobClient(key);
+    }
+    wrapError(action, err) {
+        const parent = err instanceof Error ? err : new Error(String(err));
+        return errors_1.DatabaseError.from(parent, { message: `Azure Blob ${action} failed: ${parent.message}` });
+    }
+    // ---------------------------------------------------------------------
+    // Blob operations
+    // ---------------------------------------------------------------------
+    /** Uploads `data` to `container`/`key`, creating or overwriting the block blob. */
+    async uploadBlob(container, key, data) {
+        const blockBlob = this.blockBlob(container, key);
+        const buffer = toBuffer(data);
+        try {
+            await blockBlob.upload(buffer, buffer.length);
+        }
+        catch (err) {
+            throw this.wrapError(`upload to '${container}/${key}'`, err);
+        }
+    }
+    /** Downloads `container`/`key` and returns its full contents as a Buffer. */
+    async downloadBlob(container, key) {
+        const blockBlob = this.blockBlob(container, key);
+        try {
+            const response = await blockBlob.download();
+            if (response.readableStreamBody) {
+                return await streamToBuffer(response.readableStreamBody);
+            }
+            // Browser build fallback: the body arrives as a Blob instead of a stream.
+            const blobBody = response.blobBody ?? response.contentAsBlob;
+            if (blobBody) {
+                const blob = await blobBody;
+                return Buffer.from(await blob.arrayBuffer());
+            }
+            return Buffer.alloc(0);
+        }
+        catch (err) {
+            throw this.wrapError(`download of '${container}/${key}'`, err);
+        }
+    }
+    /** Deletes `container`/`key`. */
+    async deleteBlob(container, key) {
+        const blockBlob = this.blockBlob(container, key);
+        try {
+            await blockBlob.delete();
+        }
+        catch (err) {
+            throw this.wrapError(`delete of '${container}/${key}'`, err);
+        }
+    }
+    /** Returns whether `container`/`key` exists. */
+    async blobExists(container, key) {
+        const blockBlob = this.blockBlob(container, key);
+        try {
+            return await blockBlob.exists();
+        }
+        catch (err) {
+            throw this.wrapError(`exists check of '${container}/${key}'`, err);
+        }
+    }
+    /**
+     * Lists the names of all blobs in `container`, optionally filtered to those
+     * whose name starts with `prefix`. Iterates the SDK's async paging iterator
+     * (`listBlobsFlat`) fully and returns a flat array of blob names.
+     */
+    async listBlobs(container, prefix) {
+        const containerClient = this.requireClient().getContainerClient(container);
+        const names = [];
+        try {
+            for await (const blob of containerClient.listBlobsFlat({ prefix })) {
+                names.push(blob.name);
+            }
+        }
+        catch (err) {
+            throw this.wrapError(`list of '${container}'`, err);
+        }
+        return names;
+    }
+    /** Creates `container`. */
+    async createContainer(container) {
+        const containerClient = this.requireClient().getContainerClient(container);
+        try {
+            await containerClient.create();
+        }
+        catch (err) {
+            throw this.wrapError(`create container '${container}'`, err);
+        }
+    }
+}
+exports.AzureBlobStore = AzureBlobStore;
+exports.default = AzureBlobStore;