@frogfish/k2db 1.0.6 → 1.0.8

package/data.d.ts

@@ -0,0 +1,98 @@
+import { K2DB, BaseDocument } from "./db";
+export declare class K2Data {
+    private db;
+    private owner;
+    constructor(db: K2DB, owner: string);
+    /**
+     * Retrieves a single document by UUID.
+     * @param collectionName - Name of the collection.
+     * @param uuid - UUID of the document.
+     */
+    get(collectionName: string, uuid: string): Promise<BaseDocument>;
+    /**
+     * Retrieves a single document matching the criteria.
+     * @param collectionName - Name of the collection.
+     * @param criteria - Search criteria.
+     * @param fields - Optional fields to include.
+     */
+    findOne(collectionName: string, criteria: any, fields?: Array<string>): Promise<BaseDocument | null>;
+    /**
+     * Finds documents based on filter with optional parameters and pagination.
+     */
+    find(collectionName: string, filter: any, params?: any, skip?: number, limit?: number): Promise<BaseDocument[]>;
+    /**
+     * Aggregates documents based on criteria with pagination support.
+     */
+    aggregate(collectionName: string, criteria: any[], skip?: number, limit?: number): Promise<BaseDocument[]>;
+    /**
+     * Creates a new document in the collection.
+     */
+    create(collectionName: string, data: Partial<BaseDocument>): Promise<{
+        id: string;
+    }>;
+    /**
+     * Updates multiple documents based on criteria.
+     */
+    updateAll(collectionName: string, criteria: any, values: Partial<BaseDocument>, replace?: boolean): Promise<{
+        updated: number;
+    }>;
+    /**
+     * Updates a single document by UUID.
+     */
+    update(collectionName: string, id: string, data: Partial<BaseDocument>, replace?: boolean, objectTypeName?: string): Promise<{
+        updated: number;
+    }>;
+    /**
+     * Removes (soft deletes) multiple documents based on criteria.
+     */
+    deleteAll(collectionName: string, criteria: any): Promise<{
+        deleted: number;
+    }>;
+    /**
+     * Removes (soft deletes) a single document by UUID.
+     */
+    delete(collectionName: string, id: string): Promise<{
+        deleted: number;
+    }>;
+    /**
+     * Permanently deletes a document that has been soft-deleted.
+     */
+    purge(collectionName: string, id: string): Promise<{
+        id: string;
+    }>;
+    /**
+     * Restores a soft-deleted document.
+     */
+    restore(collectionName: string, criteria: any): Promise<{
+        status: string;
+        modified: number;
+    }>;
+    /**
+     * Counts documents based on criteria.
+     */
+    count(collectionName: string, criteria: any): Promise<{
+        count: number;
+    }>;
+    /**
+     * Drops an entire collection.
+     */
+    drop(collectionName: string): Promise<{
+        status: string;
+    }>;
+    /**
+     * Executes a transaction with the provided operations.
+     */
+    executeTransaction(operations: (session: any) => Promise<void>): Promise<void>;
+    /**
+     * Creates an index on the specified collection.
+     */
+    createIndex(collectionName: string, indexSpec: any, options?: any): Promise<void>;
+    /**
+     * Drops the entire database.
+     */
+    dropDatabase(): Promise<void>;
+    /**
+     * Checks the health of the database connection.
+     */
+    isHealthy(): Promise<boolean>;
+}

package/data.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.K2Data = void 0;
+class K2Data {
+    constructor(db, owner) {
+        this.db = db;
+        this.owner = owner;
+    }
+    /**
+     * Retrieves a single document by UUID.
+     * @param collectionName - Name of the collection.
+     * @param uuid - UUID of the document.
+     */
+    async get(collectionName, uuid) {
+        return this.db.get(collectionName, uuid);
+    }
+    /**
+     * Retrieves a single document matching the criteria.
+     * @param collectionName - Name of the collection.
+     * @param criteria - Search criteria.
+     * @param fields - Optional fields to include.
+     */
+    async findOne(collectionName, criteria, fields) {
+        return this.db.findOne(collectionName, criteria, fields);
+    }
+    /**
+     * Finds documents based on filter with optional parameters and pagination.
+     */
+    async find(collectionName, filter, params, skip, limit) {
+        return this.db.find(collectionName, filter, params, skip, limit);
+    }
+    /**
+     * Aggregates documents based on criteria with pagination support.
+     */
+    async aggregate(collectionName, criteria, skip, limit) {
+        return this.db.aggregate(collectionName, criteria, skip, limit);
+    }
+    /**
+     * Creates a new document in the collection.
+     */
+    async create(collectionName, data) {
+        return this.db.create(collectionName, this.owner, data);
+    }
+    /**
+     * Updates multiple documents based on criteria.
+     */
+    async updateAll(collectionName, criteria, values, replace = false) {
+        // Ensure it returns { updated: number }
+        return this.db.updateAll(collectionName, criteria, values, replace);
+    }
+    /**
+     * Updates a single document by UUID.
+     */
+    async update(collectionName, id, data, replace = false, objectTypeName) {
+        // Ensure it returns { updated: number }
+        return this.db.update(collectionName, id, data, replace, objectTypeName);
+    }
+    /**
+     * Removes (soft deletes) multiple documents based on criteria.
+     */
+    async deleteAll(collectionName, criteria) {
+        // Ensure it returns { deleted: number }
+        return this.db.deleteAll(collectionName, criteria);
+    }
+    /**
+     * Removes (soft deletes) a single document by UUID.
+     */
+    async delete(collectionName, id) {
+        return this.db.delete(collectionName, id);
+    }
+    /**
+     * Permanently deletes a document that has been soft-deleted.
+     */
+    async purge(collectionName, id) {
+        return this.db.purge(collectionName, id);
+    }
+    /**
+     * Restores a soft-deleted document.
+     */
+    async restore(collectionName, criteria) {
+        return this.db.restore(collectionName, criteria);
+    }
+    /**
+     * Counts documents based on criteria.
+     */
+    async count(collectionName, criteria) {
+        return this.db.count(collectionName, criteria);
+    }
+    /**
+     * Drops an entire collection.
+     */
+    async drop(collectionName) {
+        return this.db.drop(collectionName);
+    }
+    /**
+     * Executes a transaction with the provided operations.
+     */
+    async executeTransaction(operations) {
+        return this.db.executeTransaction(operations);
+    }
+    /**
+     * Creates an index on the specified collection.
+     */
+    async createIndex(collectionName, indexSpec, options) {
+        return this.db.createIndex(collectionName, indexSpec, options);
+    }
+    /**
+     * Drops the entire database.
+     */
+    async dropDatabase() {
+        return this.db.dropDatabase();
+    }
+    /**
+     * Checks the health of the database connection.
+     */
+    async isHealthy() {
+        return this.db.isHealthy();
+    }
+}
+exports.K2Data = K2Data;

package/db.d.ts

@@ -0,0 +1,187 @@
+import { ObjectId } from "mongodb";
+export interface HostConfig {
+    host: string;
+    port?: number;
+}
+export interface DatabaseConfig {
+    name: string;
+    user?: string;
+    password?: string;
+    hosts?: HostConfig[];
+    replicaset?: string;
+}
+export interface BaseDocument {
+    _id?: ObjectId;
+    _uuid: string;
+    _created: number;
+    _updated: number;
+    _owner: string;
+    _deleted?: boolean;
+    [key: string]: any;
+}
+export declare class K2DB {
+    private conf;
+    private db;
+    private connection;
+    constructor(conf: DatabaseConfig);
+    /**
+     * Initializes the MongoDB connection.
+     */
+    init(): Promise<void>;
+    /**
+     * Retrieves a collection from the database.
+     * @param collectionName - Name of the collection.
+     */
+    private getCollection;
+    get(collectionName: string, uuid: string): Promise<BaseDocument>;
+    /**
+     * 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.
+     */
+    findOne(collectionName: string, criteria: any, fields?: Array<string>): Promise<BaseDocument | null>;
+    /**
+     * 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.
+     */
+    find(collectionName: string, filter: any, params?: any, skip?: number, limit?: number): Promise<BaseDocument[]>;
+    /**
+     * 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.
+     */
+    aggregate(collectionName: string, criteria: any[], skip?: number, limit?: number): Promise<BaseDocument[]>;
+    /**
+     * Creates a new document in the collection.
+     * @param collectionName - Name of the collection.
+     * @param owner - Owner of the document.
+     * @param data - Data to insert.
+     */
+    create(collectionName: string, owner: string, data: Partial<BaseDocument>): Promise<{
+        id: string;
+    }>;
+    /**
+     * 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).
+     */
+    updateAll(collectionName: string, criteria: any, values: Partial<BaseDocument>, replace?: boolean): Promise<{
+        updated: number;
+    }>;
+    /**
+     * 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.
+     */
+    update(collectionName: string, id: string, data: Partial<BaseDocument>, replace?: boolean, objectTypeName?: string): Promise<{
+        updated: number;
+    }>;
+    /**
+     * Removes (soft deletes) multiple documents based on criteria.
+     * @param collectionName - Name of the collection.
+     * @param criteria - Removal criteria.
+     */
+    deleteAll(collectionName: string, criteria: any): Promise<{
+        deleted: number;
+    }>;
+    /**
+     * Removes (soft deletes) a single document by UUID.
+     * @param collectionName - Name of the collection.
+     * @param id - UUID of the document.
+     */
+    delete(collectionName: string, id: string): Promise<{
+        deleted: number;
+    }>;
+    /**
+     * Permanently deletes a document that has been soft-deleted.
+     * @param collectionName - Name of the collection.
+     * @param id - UUID of the document.
+     */
+    purge(collectionName: string, id: string): Promise<{
+        id: string;
+    }>;
+    /**
+     * Restores a soft-deleted document.
+     * @param collectionName - Name of the collection.
+     * @param criteria - Criteria to identify the document.
+     */
+    restore(collectionName: string, criteria: any): Promise<{
+        status: string;
+        modified: number;
+    }>;
+    /**
+     * Counts documents based on criteria.
+     * @param collectionName - Name of the collection.
+     * @param criteria - Counting criteria.
+     */
+    count(collectionName: string, criteria: any): Promise<{
+        count: number;
+    }>;
+    /**
+     * Drops an entire collection.
+     * @param collectionName - Name of the collection.
+     */
+    drop(collectionName: string): Promise<{
+        status: string;
+    }>;
+    /**
+     * Sanitizes aggregation criteria.
+     * @param criteria - Aggregation stage criteria.
+     */
+    private static sanitiseCriteria;
+    /**
+     * Optional: Executes a transaction with the provided operations.
+     * @param operations - A function that performs operations within a transaction session.
+     */
+    executeTransaction(operations: (session: any) => Promise<void>): Promise<void>;
+    /**
+     * 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.
+     */
+    createIndex(collectionName: string, indexSpec: any, options?: any): Promise<void>;
+    /**
+     * Releases the MongoDB connection.
+     */
+    release(): Promise<void>;
+    /**
+     * Closes the MongoDB connection.
+     */
+    close(): void;
+    /**
+     * Drops the entire database.
+     */
+    dropDatabase(): Promise<void>;
+    /**
+     * Validates the MongoDB collection name.
+     * @param collectionName - The name of the collection to validate.
+     * @throws {K2Error} - If the collection name is invalid.
+     */
+    validateCollectionName(collectionName: string): void;
+    /**
+     * Optional: Checks the health of the database connection.
+     */
+    isHealthy(): Promise<boolean>;
+    /**
+     * Utility to normalize the error type.
+     * @param err - The caught error of type `unknown`.
+     * @returns A normalized error of type `Error`.
+     */
+    private normalizeError;
+}

package/db.js

@@ -0,0 +1,584 @@
+"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) {
+        // Return type changed to JSON object {updated: number}
+        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 the updated count in JSON format
+            return { updated: res.modifiedCount };
+        }
+        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(); // Set the _updated timestamp
+        try {
+            // Call updateAll with the UUID criteria and replace flag
+            const res = await this.updateAll(collectionName, { _uuid: id }, data, replace);
+            // Check if exactly one document was updated
+            if (res.updated === 1) {
+                return { updated: 1 };
+            }
+            // If no document was updated, throw a NOT_FOUND error
+            if (res.updated === 0) {
+                throw new k2error_1.K2Error(k2error_1.ServiceError.NOT_FOUND, `Object in ${collectionName} with UUID ${id} not found`, "sys_mdb_update_not_found");
+            }
+            // If more than one document was updated, throw a SYSTEM_ERROR
+            if (res.updated > 1) {
+                throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, `Multiple objects in ${collectionName} were updated when only one was expected`, "sys_mdb_update_multiple_found");
+            }
+            // Since we've handled all possible valid cases, we return undefined in case of unforeseen errors (for type safety)
+            return { updated: 0 }; // Should never reach this line, here for type safety
+        }
+        catch (err) {
+            if (err instanceof k2error_1.K2Error) {
+                throw err;
+            }
+            // Catch any other unhandled errors and throw a system error
+            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, `Error updating ${collectionName}`, "sys_mdb_update_error", 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);
+        try {
+            // Step 1: Count documents matching the original criteria (this is not strictly necessary if you only want the deleted count)
+            const 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 to soft delete the documents
+            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 number of records that were marked as deleted
+        return {
+            deleted: result.updated, // Map the updated count to 'deleted'
+        };
+    }
+    /**
+     * 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 {
+            // Call deleteAll to soft delete the document by UUID
+            const result = await this.deleteAll(collectionName, { _uuid: id });
+            // Check the result of the deleteAll operation
+            if (result.deleted === 1) {
+                // Successfully deleted one document
+                return { deleted: 1 };
+            }
+            else if (result.deleted === 0) {
+                // No document was found to delete
+                throw new k2error_1.K2Error(k2error_1.ServiceError.NOT_FOUND, "Document not found", "sys_mdb_remove_not_found");
+            }
+            else {
+                // More than one document was deleted, which is unexpected
+                throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, "Multiple documents deleted when only one was expected", "sys_mdb_remove_multiple_deleted");
+            }
+        }
+        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,36 +1,11 @@
 {
   "name": "@frogfish/k2db",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "A data handling library for K2 applications.",
-  "main": "data.js",  
-  "types": "data.d.ts",  
-  "scripts": {
-    "test": "jest",
-    "test:coverage": "jest --coverage",
-    "dist": "tsc && jest && gulp && npm publish --access public",
-    "build": "tsc",
-    "build:watch": "tsc --watch"
-  },
+  "main": "data.js",
+  "types": "data.d.ts",
   "author": "El'Diablo",
   "license": "GPL-3.0-only",
-  "devDependencies": {
-    "@types/axios": "^0.9.36",
-    "@types/debug": "^4.1.12",
-    "@types/jest": "^29.5.13",
-    "@types/mongodb": "^4.0.6",
-    "@types/uuid": "^10.0.0",
-    "jest": "^29.7.0",
-    "mongodb-memory-server": "^10.0.1",
-    "ts-jest": "^29.2.5",
-    "ts-node": "^10.9.2",
-    "typescript": "^5.6.2",
-    "gulp": "^5.0.0",
-    "gulp-bump": "^3.2.0",
-    "gulp-clean": "^0.4.0",
-    "gulp-json-transform": "^0.5.0",
-    "gulp-tsc": "^1.3.2",
-    "gulp-typescript": "^6.0.0-alpha.1"
-  },
   "dependencies": {
     "@frogfish/k2error": "^1.0.1",
     "debug": "^4.3.7",