@frogfish/k2db 1.0.5 → 1.0.7

package/data.d.ts

@@ -1,8 +1,8 @@
-import { DB, BaseDocument } from "./db";
-export declare class Data {
+import { K2DB, BaseDocument } from "./db";
+export declare class K2Data {
     private db;
     private owner;
-    constructor(db: DB, owner: string);
+    constructor(db: K2DB, owner: string);
     /**
      * Retrieves a single document by UUID.
      * @param collectionName - Name of the collection.

package/data.js

@@ -1,8 +1,8 @@
 "use strict";
 // src/Data.ts
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Data = void 0;
-class Data {
+exports.K2Data = void 0;
+class K2Data {
     constructor(db, owner) {
         this.db = db;
         this.owner = owner;
@@ -115,4 +115,4 @@ class Data {
         return this.db.isHealthy();
     }
 }
-exports.Data = Data;
+exports.K2Data = K2Data;

package/db.d.ts

@@ -19,7 +19,7 @@ export interface BaseDocument {
     _deleted?: boolean;
     [key: string]: any;
 }
-export declare class DB {
+export declare class K2DB {
     private conf;
     private db;
     private connection;

package/db.js

@@ -0,0 +1,566 @@
+"use strict";
+// src/db.ts
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.K2DB = void 0;
+const k2error_1 = require("@frogfish/k2error"); // Keep the existing error structure
+const mongodb_1 = require("mongodb");
+const uuid_1 = require("uuid");
+const debug_1 = __importDefault(require("debug"));
+const debug = (0, debug_1.default)("k2:db");
+class K2DB {
+    constructor(conf) {
+        this.conf = conf;
+    }
+    /**
+     * Initializes the MongoDB connection.
+     */
+    async init() {
+        const dbName = this.conf.name;
+        let connectUrl = "mongodb://";
+        // Add user and password if available
+        if (this.conf.user && this.conf.password) {
+            connectUrl += `${encodeURIComponent(this.conf.user)}:${encodeURIComponent(this.conf.password)}@`;
+        }
+        // Handle single host (non-replicaset) or multiple hosts (replicaset)
+        if (!this.conf.hosts || this.conf.hosts.length === 0) {
+            throw new k2error_1.K2Error(k2error_1.ServiceError.CONFIGURATION_ERROR, "No valid hosts provided in configuration", "sys_mdb_no_hosts");
+        }
+        connectUrl += this.conf.hosts
+            .map((host) => `${host.host}:${host.port || 27017}`)
+            .join(",");
+        // Append database name
+        connectUrl += `/${dbName}`;
+        // Append replicaset and options if it's a replicaset
+        if (this.conf.hosts.length > 1 && this.conf.replicaset) {
+            connectUrl += `?replicaSet=${this.conf.replicaset}&keepAlive=true&autoReconnect=true&socketTimeoutMS=0`;
+        }
+        // Mask sensitive information in logs
+        const safeConnectUrl = connectUrl.replace(/\/\/.*?:.*?@/, "//*****:*****@");
+        debug(`Connecting to MongoDB: ${safeConnectUrl}`);
+        // Define connection options with timeouts
+        const options = {
+            connectTimeoutMS: 2000, // 2 seconds
+            serverSelectionTimeoutMS: 2000, // 2 seconds
+            // Additional options can be added here
+        };
+        try {
+            // Establish MongoDB connection
+            this.connection = await mongodb_1.MongoClient.connect(connectUrl, options);
+            this.db = this.connection.db(dbName);
+            debug("Successfully connected to MongoDB");
+        }
+        catch (err) {
+            // Handle connection error
+            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, "Failed to connect to MongoDB", "sys_mdb_init", this.normalizeError(err));
+        }
+    }
+    /**
+     * Retrieves a collection from the database.
+     * @param collectionName - Name of the collection.
+     */
+    async getCollection(collectionName) {
+        try {
+            this.validateCollectionName(collectionName); // Validate the collection name
+            const collection = this.db.collection(collectionName);
+            return collection;
+        }
+        catch (err) {
+            // If the error is already an K2Error, rethrow it
+            if (err instanceof k2error_1.K2Error) {
+                throw err;
+            }
+            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, `Error getting collection: ${collectionName}`, "sys_mdb_gc", this.normalizeError(err));
+        }
+    }
+    async get(collectionName, uuid) {
+        const res = await this.findOne(collectionName, { _uuid: uuid });
+        if (!res) {
+            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, "Error getting the document with provided identity", "sys_mdb_get");
+        }
+        return res;
+    }
+    /**
+     * Retrieves a single document by UUID.
+     * @param collectionName - Name of the collection.
+     * @param uuid - UUID of the document.
+     * @param objectTypeName - Optional object type name.
+     * @param fields - Optional array of fields to include.
+     */
+    async findOne(collectionName, criteria, fields) {
+        const collection = await this.getCollection(collectionName);
+        const projection = {};
+        if (fields && fields.length > 0) {
+            fields.forEach((field) => {
+                projection[field] = 1;
+            });
+        }
+        try {
+            const item = await collection.findOne(criteria, { projection });
+            if (item) {
+                const { _id, ...rest } = item;
+                return rest;
+            }
+            return null;
+        }
+        catch (err) {
+            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, "Error finding document", "sys_mdb_fo", this.normalizeError(err));
+        }
+    }
+    /**
+     * Finds documents based on parameters with pagination support.
+     * @param collectionName - Name of the collection.
+     * @param filter - Criteria to filter the documents.
+     * @param params - Optional search parameters (for sorting, including/excluding fields).
+     * @param skip - Number of documents to skip (for pagination).
+     * @param limit - Maximum number of documents to return.
+     */
+    async find(collectionName, filter, params = {}, skip = 0, limit = 100) {
+        const collection = await this.getCollection(collectionName);
+        // Ensure filter is valid, defaulting to an empty object
+        const criteria = filter || {};
+        // Handle the _deleted field if params specify not to include deleted documents
+        if (params.includeDeleted) {
+            // No _deleted filter, include all documents
+        }
+        else if (params.deleted === true) {
+            criteria._deleted = true; // Explicitly search for deleted documents
+        }
+        else {
+            criteria._deleted = { $ne: true }; // Exclude deleted by default
+        }
+        // Build projection (fields to include or exclude)
+        let projection = { _id: 0 }; // Exclude _id by default
+        if (typeof params.filter === "string" && params.filter === "all") {
+            projection = {}; // Include all fields
+        }
+        else if (Array.isArray(params.filter)) {
+            params.filter.forEach((field) => {
+                projection[field] = 1; // Only include the specified fields
+            });
+        }
+        if (Array.isArray(params.exclude)) {
+            params.exclude.forEach((field) => {
+                projection[field] = 0; // Exclude the specified fields
+            });
+        }
+        // Build sorting options
+        let sort = undefined;
+        if (params.order) {
+            sort = {};
+            for (const [key, value] of Object.entries(params.order)) {
+                sort[key] = value === "asc" ? 1 : -1;
+            }
+        }
+        try {
+            let cursor = collection.find(criteria, { projection });
+            // Apply pagination
+            cursor = cursor.skip(skip).limit(limit);
+            if (sort) {
+                cursor = cursor.sort(sort);
+            }
+            const data = await cursor.toArray();
+            // Remove _id safely from each document
+            const result = data.map((doc) => {
+                const { _id, ...rest } = doc;
+                return rest;
+            });
+            return result;
+        }
+        catch (err) {
+            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, "Error executing find query", "sys_mdb_find_error", this.normalizeError(err));
+        }
+    }
+    /**
+     * Aggregates documents based on criteria with pagination support.
+     * @param collectionName - Name of the collection.
+     * @param criteria - Aggregation pipeline criteria.
+     * @param skip - Number of documents to skip (for pagination).
+     * @param limit - Maximum number of documents to return.
+     */
+    async aggregate(collectionName, criteria, skip = 0, limit = 100) {
+        if (criteria.length === 0) {
+            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, "Aggregation criteria cannot be empty", "sys_mdb_ag_empty");
+        }
+        // Ensure we always exclude soft-deleted documents
+        if (criteria[0].$match) {
+            criteria[0].$match = { ...criteria[0].$match, _deleted: { $ne: true } };
+        }
+        else {
+            criteria.unshift({ $match: { _deleted: { $ne: true } } });
+        }
+        // Add pagination stages to the aggregation pipeline
+        if (skip > 0) {
+            criteria.push({ $skip: skip });
+        }
+        if (limit > 0) {
+            criteria.push({ $limit: limit });
+        }
+        debug(`Aggregating with criteria: ${JSON.stringify(criteria, null, 2)}`);
+        const collection = await this.getCollection(collectionName);
+        // Sanitize criteria
+        const sanitizedCriteria = criteria.map((stage) => {
+            if (stage.$match) {
+                return K2DB.sanitiseCriteria(stage);
+            }
+            return stage;
+        });
+        try {
+            const data = await collection.aggregate(sanitizedCriteria).toArray();
+            // Enforce BaseDocument type on each document
+            return data.map((doc) => doc);
+        }
+        catch (err) {
+            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, "Aggregation failed", "sys_mdb_ag", this.normalizeError(err));
+        }
+    }
+    /**
+     * Creates a new document in the collection.
+     * @param collectionName - Name of the collection.
+     * @param owner - Owner of the document.
+     * @param data - Data to insert.
+     */
+    async create(collectionName, owner, data) {
+        if (!collectionName || !owner || !data) {
+            throw new k2error_1.K2Error(k2error_1.ServiceError.BAD_REQUEST, "Invalid method usage, parameters not defined", "sys_mdb_crv1");
+        }
+        if (typeof owner !== "string") {
+            throw new k2error_1.K2Error(k2error_1.ServiceError.BAD_REQUEST, "Owner must be of a string type", "sys_mdb_crv2");
+        }
+        const collection = await this.getCollection(collectionName);
+        const timestamp = Date.now();
+        // Generate a new UUID
+        const newUuid = (0, uuid_1.v4)();
+        // Spread `data` first, then set internal fields to prevent overwriting
+        const document = {
+            ...data,
+            _created: timestamp,
+            _updated: timestamp,
+            _owner: owner,
+            _uuid: newUuid,
+        };
+        try {
+            const result = await collection.insertOne(document);
+            return { id: document._uuid };
+        }
+        catch (err) {
+            // Use appropriate error typing
+            // Check if the error is a duplicate key error
+            if (err.code === 11000 && err.keyPattern && err.keyPattern._uuid) {
+                throw new k2error_1.K2Error(k2error_1.ServiceError.ALREADY_EXISTS, `A document with _uuid ${document._uuid} already exists.`, "sys_mdb_crv3");
+            }
+            // Log the error details for debugging
+            debug(`Was trying to insert into collection ${collectionName}, data: ${JSON.stringify(document)}`);
+            debug(err);
+            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, "Error saving object to database", "sys_mdb_sav", this.normalizeError(err));
+        }
+    }
+    /**
+     * Updates multiple documents based on criteria.
+     * Can either replace the documents or patch them.
+     * @param collectionName - Name of the collection.
+     * @param criteria - Update criteria.
+     * @param values - Values to update or replace with.
+     * @param replace - If true, replaces the entire document (PUT), otherwise patches (PATCH).
+     */
+    async updateAll(collectionName, criteria, values, replace = false) {
+        const collection = await this.getCollection(collectionName);
+        debug(`Updating ${collectionName} with criteria: ${JSON.stringify(criteria)}`);
+        values._updated = Date.now();
+        // Exclude soft-deleted documents unless _deleted is explicitly specified in criteria
+        if (!("_deleted" in criteria)) {
+            criteria = {
+                ...criteria,
+                _deleted: { $ne: true },
+            };
+        }
+        // Determine update operation based on the replace flag
+        const updateOperation = replace ? values : { $set: values };
+        try {
+            const res = await collection.updateMany(criteria, updateOperation);
+            return {
+                found: res.matchedCount,
+                modified: res.modifiedCount,
+                updated: res.acknowledged,
+            };
+        }
+        catch (err) {
+            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, `Error updating ${collectionName}`, "sys_mdb_update1", this.normalizeError(err));
+        }
+    }
+    /**
+     * Updates a single document by UUID.
+     * Can either replace the document or patch it.
+     * @param collectionName - Name of the collection.
+     * @param id - UUID string to identify the document.
+     * @param data - Data to update or replace with.
+     * @param replace - If true, replaces the entire document (PUT), otherwise patches (PATCH).
+     * @param objectTypeName - Optional object type name.
+     */
+    async update(collectionName, id, data, replace = false, objectTypeName) {
+        const collection = await this.getCollection(collectionName);
+        data._updated = Date.now();
+        try {
+            // Call updateAll with the UUID criteria and replace flag
+            const res = await this.updateAll(collectionName, { _uuid: id }, data, replace);
+            if (res.modified === 1) {
+                return { id: id };
+            }
+            if (res.modified === 0) {
+                throw new k2error_1.K2Error(k2error_1.ServiceError.NOT_FOUND, `Object in ${collectionName} not found`, "sys_mdb_update2");
+            }
+        }
+        catch (err) {
+            if (err instanceof k2error_1.K2Error) {
+                throw err;
+            }
+            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, `Error updating ${collectionName}`, "sys_mdb_update1", this.normalizeError(err));
+        }
+    }
+    /**
+     * Removes (soft deletes) multiple documents based on criteria.
+     * @param collectionName - Name of the collection.
+     * @param criteria - Removal criteria.
+     */
+    async deleteAll(collectionName, criteria) {
+        const collection = await this.getCollection(collectionName);
+        let foundCount;
+        try {
+            // Step 1: Count documents matching the original criteria
+            foundCount = await collection.countDocuments(criteria);
+        }
+        catch (err) {
+            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, `Error updating ${collectionName}`, "sys_mdb_deleteall_count", this.normalizeError(err));
+        }
+        // Step 2: Modify criteria to exclude already deleted documents
+        const modifiedCriteria = {
+            ...criteria,
+            _deleted: { $ne: true },
+        };
+        let result;
+        try {
+            // Perform the update
+            result = await this.updateAll(collectionName, modifiedCriteria, {
+                _deleted: true,
+            });
+        }
+        catch (err) {
+            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, `Error updating ${collectionName}`, "sys_mdb_deleteall_update", this.normalizeError(err));
+        }
+        // Step 3: Return the result, adjusting the 'found' count
+        return {
+            ...result,
+            found: foundCount, // Use the original count here
+        };
+    }
+    /**
+     * Removes (soft deletes) a single document by UUID.
+     * @param collectionName - Name of the collection.
+     * @param id - UUID of the document.
+     */
+    async delete(collectionName, id) {
+        try {
+            await this.deleteAll(collectionName, { _uuid: id });
+            return { id };
+        }
+        catch (err) {
+            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, "Error removing object from collection", "sys_mdb_remove_upd", this.normalizeError(err));
+        }
+    }
+    /**
+     * Permanently deletes a document that has been soft-deleted.
+     * @param collectionName - Name of the collection.
+     * @param id - UUID of the document.
+     */
+    async purge(collectionName, id) {
+        const collection = await this.getCollection(collectionName);
+        try {
+            const item = await collection.findOne({
+                _uuid: id,
+                _deleted: true,
+            });
+            if (!item) {
+                throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, "Cannot purge item that is not deleted", "sys_mdb_gcol_pg2");
+            }
+            await collection.deleteMany({ _uuid: id });
+            return { id };
+        }
+        catch (err) {
+            if (err instanceof k2error_1.K2Error) {
+                throw err;
+            }
+            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, `Error purging item with id: ${id}`, "sys_mdb_pg", this.normalizeError(err));
+        }
+    }
+    /**
+     * Restores a soft-deleted document.
+     * @param collectionName - Name of the collection.
+     * @param criteria - Criteria to identify the document.
+     */
+    async restore(collectionName, criteria) {
+        const collection = await this.getCollection(collectionName);
+        criteria._deleted = true;
+        try {
+            const res = await collection.updateMany(criteria, {
+                $set: { _deleted: false },
+            });
+            return { status: "restored", modified: res.modifiedCount };
+        }
+        catch (err) {
+            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, "Error restoring a deleted item", "sys_mdb_pres", this.normalizeError(err));
+        }
+    }
+    /**
+     * Counts documents based on criteria.
+     * @param collectionName - Name of the collection.
+     * @param criteria - Counting criteria.
+     */
+    async count(collectionName, criteria) {
+        const collection = await this.getCollection(collectionName);
+        try {
+            const cnt = await collection.countDocuments(criteria);
+            return { count: cnt };
+        }
+        catch (err) {
+            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, "Error counting objects with given criteria", "sys_mdb_cn", this.normalizeError(err));
+        }
+    }
+    /**
+     * Drops an entire collection.
+     * @param collectionName - Name of the collection.
+     */
+    async drop(collectionName) {
+        const collection = await this.getCollection(collectionName);
+        try {
+            await collection.drop();
+            return { status: "ok" };
+        }
+        catch (err) {
+            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, "Error dropping collection", "sys_mdb_drop", this.normalizeError(err));
+        }
+    }
+    /**
+     * Sanitizes aggregation criteria.
+     * @param criteria - Aggregation stage criteria.
+     */
+    static sanitiseCriteria(criteria) {
+        if (criteria.$match) {
+            for (const key of Object.keys(criteria.$match)) {
+                if (typeof criteria.$match[key] !== "string") {
+                    criteria.$match[key] = K2DB.sanitiseCriteria({
+                        [key]: criteria.$match[key],
+                    })[key];
+                }
+                else {
+                    if (key === "$exists") {
+                        criteria.$match[key] = criteria.$match[key] === "true";
+                    }
+                }
+            }
+        }
+        return criteria;
+    }
+    /**
+     * Optional: Executes a transaction with the provided operations.
+     * @param operations - A function that performs operations within a transaction session.
+     */
+    async executeTransaction(operations) {
+        const session = this.connection.startSession();
+        session.startTransaction();
+        try {
+            await operations(session);
+            await session.commitTransaction();
+        }
+        catch (error) {
+            await session.abortTransaction();
+            throw this.normalizeError(error);
+        }
+        finally {
+            session.endSession();
+        }
+    }
+    /**
+     * Optional: Creates an index on the specified collection.
+     * @param collectionName - Name of the collection.
+     * @param indexSpec - Specification of the index.
+     * @param options - Optional index options.
+     */
+    async createIndex(collectionName, indexSpec, options) {
+        const collection = await this.getCollection(collectionName);
+        try {
+            await collection.createIndex(indexSpec, options);
+            debug(`Index created on ${collectionName}: ${JSON.stringify(indexSpec)}`);
+        }
+        catch (err) {
+            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, `Error creating index on ${collectionName}`, "sys_mdb_idx", this.normalizeError(err));
+        }
+    }
+    /**
+     * Releases the MongoDB connection.
+     */
+    async release() {
+        await this.connection.close();
+        debug("MongoDB connection released");
+    }
+    /**
+     * Closes the MongoDB connection.
+     */
+    close() {
+        this.connection.close();
+    }
+    /**
+     * Drops the entire database.
+     */
+    async dropDatabase() {
+        try {
+            await this.db.dropDatabase();
+            debug("Database dropped successfully");
+        }
+        catch (err) {
+            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, "Error dropping database", "sys_mdb_drop_db", this.normalizeError(err));
+        }
+    }
+    /**
+     * Validates the MongoDB collection name.
+     * @param collectionName - The name of the collection to validate.
+     * @throws {K2Error} - If the collection name is invalid.
+     */
+    validateCollectionName(collectionName) {
+        // Check for null character
+        if (collectionName.includes("\0")) {
+            throw new k2error_1.K2Error(k2error_1.ServiceError.BAD_REQUEST, "Collection name cannot contain null characters", "sys_mdb_invalid_collection_name");
+        }
+        // Check if it starts with 'system.'
+        if (collectionName.startsWith("system.")) {
+            throw new k2error_1.K2Error(k2error_1.ServiceError.BAD_REQUEST, "Collection name cannot start with 'system.'", "sys_mdb_invalid_collection_name");
+        }
+        // Check for invalid characters (e.g., '$')
+        if (collectionName.includes("$")) {
+            throw new k2error_1.K2Error(k2error_1.ServiceError.BAD_REQUEST, "Collection name cannot contain the '$' character", "sys_mdb_invalid_collection_name");
+        }
+        // Additional checks can be added here as needed
+    }
+    /**
+     * Optional: Checks the health of the database connection.
+     */
+    async isHealthy() {
+        try {
+            await this.db.command({ ping: 1 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Utility to normalize the error type.
+     * @param err - The caught error of type `unknown`.
+     * @returns A normalized error of type `Error`.
+     */
+    normalizeError(err) {
+        return err instanceof Error ? err : new Error(String(err));
+    }
+}
+exports.K2DB = K2DB;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frogfish/k2db",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "A data handling library for K2 applications.",
   "main": "data.js",
   "types": "data.d.ts",
@@ -14,6 +14,8 @@
   },
   "files": [
     "data.d.ts",
-    "db.d.ts"
+    "data.js",
+    "db.d.ts",
+    "db.js"
   ]
 }