@frogfish/k2db 1.0.15 → 2.0.3

package/dist/db.js

@@ -0,0 +1,903 @@
+// src/db.ts
+import { K2Error, ServiceError } from "@frogfish/k2error"; // Keep the existing error structure
+import { MongoClient, } from "mongodb";
+import { v4 as uuidv4 } from "uuid";
+import debugLib from "debug";
+import { z } from "zod";
+const debug = debugLib("k2:db");
+export class K2DB {
+    conf;
+    db;
+    connection;
+    schemas = new Map();
+    constructor(conf) {
+        this.conf = conf;
+    }
+    /**
+     * Initializes the MongoDB connection.
+     */
+    async init() {
+        // Build URI and options
+        const { uri, options } = this.buildMongoUri();
+        const dbName = this.conf.name;
+        // Mask sensitive information in logs
+        const safeConnectUrl = uri.replace(/\/\/.*?:.*?@/, "//*****:*****@");
+        debug(`Connecting to MongoDB: ${safeConnectUrl}`);
+        try {
+            // 8. Establish MongoDB connection
+            this.connection = await MongoClient.connect(uri, options);
+            this.db = this.connection.db(dbName);
+            debug("Successfully connected to MongoDB");
+        }
+        catch (err) {
+            // 9. Handle connection error
+            throw new K2Error(ServiceError.SYSTEM_ERROR, `Failed to connect to MongoDB: ${err.message}`, "sys_mdb_init", this.normalizeError(err));
+        }
+    }
+    /**
+     * Build a robust MongoDB URI based on config (supports SRV and standard).
+     */
+    buildMongoUri() {
+        if (!this.conf.hosts || this.conf.hosts.length === 0) {
+            throw new K2Error(ServiceError.CONFIGURATION_ERROR, "No valid hosts provided in configuration", "sys_mdb_no_hosts");
+        }
+        const auth = this.conf.user && this.conf.password
+            ? `${encodeURIComponent(this.conf.user)}:${encodeURIComponent(this.conf.password)}@`
+            : "";
+        const singleNoPort = this.conf.hosts.length === 1 && !this.conf.hosts[0].port;
+        const useSrv = singleNoPort;
+        const dbName = this.conf.name;
+        let uri;
+        if (useSrv) {
+            const host = this.conf.hosts[0].host;
+            uri = `mongodb+srv://${auth}${host}/${dbName}?retryWrites=true&w=majority`;
+        }
+        else {
+            const hostList = this.conf.hosts
+                .map((h) => `${h.host}:${h.port || 27017}`)
+                .join(",");
+            const params = ["retryWrites=true", "w=majority"];
+            if (this.conf.replicaset)
+                params.push(`replicaSet=${this.conf.replicaset}`);
+            uri = `mongodb://${auth}${hostList}/${dbName}?${params.join("&")}`;
+        }
+        const options = {
+            connectTimeoutMS: 2000,
+            serverSelectionTimeoutMS: 2000,
+        };
+        return { uri, options };
+    }
+    /** Load DatabaseConfig from environment variables. */
+    static fromEnv(prefix = "K2DB_") {
+        const get = (k) => globalThis.process?.env?.[`${prefix}${k}`];
+        const name = get("NAME");
+        const hostsEnv = get("HOSTS");
+        if (!name || !hostsEnv) {
+            throw new Error("K2DB_NAME and K2DB_HOSTS are required in environment");
+        }
+        const hosts = hostsEnv.split(",").map((h) => {
+            const [host, port] = h.trim().split(":");
+            return { host, port: port ? parseInt(port, 10) : undefined };
+        });
+        const conf = {
+            name,
+            hosts,
+            user: get("USER"),
+            password: get("PASSWORD"),
+            replicaset: get("REPLICASET"),
+        };
+        const slow = get("SLOW_MS");
+        if (slow)
+            conf.slowQueryMs = parseInt(slow, 10);
+        return conf;
+    }
+    /**
+     * 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) {
+                throw err;
+            }
+            throw new K2Error(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,
+            _deleted: { $ne: true },
+        });
+        if (!res) {
+            throw new K2Error(ServiceError.NOT_FOUND, "Document not found", "sys_mdb_get_not_found");
+        }
+        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 = {};
+        // Exclude soft-deleted documents by default unless caller specifies otherwise
+        const query = {
+            ...criteria,
+            ...(criteria && Object.prototype.hasOwnProperty.call(criteria, "_deleted")
+                ? {}
+                : { _deleted: { $ne: true } }),
+        };
+        if (fields && fields.length > 0) {
+            fields.forEach((field) => {
+                projection[field] = 1;
+            });
+        }
+        try {
+            const item = await this.runTimed("findOne", { collectionName, query, projection }, async () => await collection.findOne(query, { projection }));
+            if (item) {
+                const { _id, ...rest } = item;
+                return rest;
+            }
+            return null;
+        }
+        catch (err) {
+            throw new K2Error(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 && !Object.prototype.hasOwnProperty.call(criteria, "_deleted")) {
+            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;
+        if (typeof params.filter === "string" && params.filter === "all") {
+            projection = {}; // Include all fields
+        }
+        else if (Array.isArray(params.filter)) {
+            projection = {};
+            params.filter.forEach((field) => {
+                projection[field] = 1; // Only include the specified fields
+            });
+            projection._id = 0; // Hide _id when using include list
+        }
+        else if (Array.isArray(params.exclude)) {
+            projection = { _id: 0 }; // Start by hiding _id
+            params.exclude.forEach((field) => {
+                projection[field] = 0; // Exclude the specified fields
+            });
+        }
+        else {
+            projection = { _id: 0 }; // Default: hide _id only
+        }
+        // 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 this.runTimed("find", { collectionName, criteria, projection, sort, skip, limit }, async () => 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(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(ServiceError.SYSTEM_ERROR, "Aggregation criteria cannot be empty", "sys_mdb_ag_empty");
+        }
+        // Enforce soft-delete behavior: never return documents marked as deleted
+        criteria = K2DB.enforceNoDeletedInPipeline(criteria);
+        // 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 this.runTimed("aggregate", { collectionName, pipeline: sanitizedCriteria }, async () => await collection.aggregate(sanitizedCriteria).toArray());
+            // Enforce BaseDocument type on each document
+            return data.map((doc) => doc);
+        }
+        catch (err) {
+            throw new K2Error(ServiceError.SYSTEM_ERROR, "Aggregation failed", "sys_mdb_ag", this.normalizeError(err));
+        }
+    }
+    /**
+     * Ensures an aggregation pipeline excludes soft-deleted documents for the root
+     * collection and any joined collections ($lookup, $unionWith, $graphLookup, $facet).
+     */
+    static enforceNoDeletedInPipeline(pipeline) {
+        const cloned = Array.isArray(pipeline) ? pipeline.map((s) => ({ ...s })) : [];
+        // Insert a $match to exclude deleted near the start, but after any
+        // first-stage-only operators like $search, $geoNear, $vectorSearch.
+        const reservedFirst = ["$search", "$geoNear", "$vectorSearch"];
+        let insertIdx = 0;
+        while (insertIdx < cloned.length &&
+            typeof cloned[insertIdx] === "object" &&
+            cloned[insertIdx] !== null &&
+            Object.keys(cloned[insertIdx]).length === 1 &&
+            reservedFirst.includes(Object.keys(cloned[insertIdx])[0])) {
+            insertIdx++;
+        }
+        const nonDeletedMatch = { $match: { _deleted: { $ne: true } } };
+        cloned.splice(insertIdx, 0, nonDeletedMatch);
+        // Walk stages and enforce inside nested pipelines
+        const mapStage = (stage) => {
+            if (!stage || typeof stage !== "object")
+                return stage;
+            if (stage.$lookup) {
+                const lu = { ...stage.$lookup };
+                if (Array.isArray(lu.pipeline)) {
+                    // Ensure the foreign pipeline excludes deleted
+                    lu.pipeline = K2DB.enforceNoDeletedInPipeline(lu.pipeline);
+                }
+                else if (lu.localField && lu.foreignField) {
+                    // Convert simple lookup to pipeline lookup to filter _deleted
+                    const localVar = "__lk";
+                    lu.let = { [localVar]: `$${lu.localField}` };
+                    lu.pipeline = [
+                        {
+                            $match: {
+                                $expr: {
+                                    $and: [
+                                        { $eq: ["$" + lu.foreignField, "$$" + localVar] },
+                                        { $ne: ["$_deleted", true] },
+                                    ],
+                                },
+                            },
+                        },
+                    ];
+                    delete lu.localField;
+                    delete lu.foreignField;
+                }
+                return { $lookup: lu };
+            }
+            if (stage.$unionWith) {
+                const uw = stage.$unionWith;
+                if (typeof uw === "string") {
+                    return {
+                        $unionWith: {
+                            coll: uw,
+                            pipeline: [{ $match: { _deleted: { $ne: true } } }],
+                        },
+                    };
+                }
+                else if (uw && typeof uw === "object") {
+                    const uwc = { ...uw };
+                    uwc.pipeline = K2DB.enforceNoDeletedInPipeline(uwc.pipeline || []);
+                    return { $unionWith: uwc };
+                }
+            }
+            if (stage.$graphLookup) {
+                const gl = { ...stage.$graphLookup };
+                const existing = gl.restrictSearchWithMatch || {};
+                gl.restrictSearchWithMatch = { ...existing, _deleted: { $ne: true } };
+                return { $graphLookup: gl };
+            }
+            if (stage.$facet) {
+                const facets = { ...stage.$facet };
+                for (const key of Object.keys(facets)) {
+                    facets[key] = K2DB.enforceNoDeletedInPipeline(facets[key] || []);
+                }
+                return { $facet: facets };
+            }
+            return stage;
+        };
+        return cloned.map(mapStage);
+    }
+    /**
+     * 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(ServiceError.BAD_REQUEST, "Invalid method usage, parameters not defined", "sys_mdb_crv1");
+        }
+        if (typeof owner !== "string") {
+            throw new K2Error(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 = uuidv4();
+        // Remove reserved fields from user data, then validate/transform via schema if present
+        const safeData = K2DB.stripReservedFields(data);
+        const validated = this.applySchema(collectionName, safeData, /*partial*/ false);
+        // Spread validated data first, then set internal fields to prevent overwriting
+        const document = {
+            ...validated,
+            _created: timestamp,
+            _updated: timestamp,
+            _owner: owner,
+            _uuid: newUuid,
+        };
+        try {
+            const result = await this.runTimed("insertOne", { collectionName }, async () => 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(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(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.
+     */
+    async updateAll(collectionName, criteria, values) {
+        this.validateCollectionName(collectionName);
+        const collection = await this.getCollection(collectionName);
+        debug(`Updating ${collectionName} with criteria: ${JSON.stringify(criteria)}`);
+        values = K2DB.stripReservedFields(values);
+        values = this.applySchema(collectionName, values, /*partial*/ true);
+        values._updated = Date.now();
+        criteria = {
+            ...criteria,
+            _deleted: { $ne: true },
+        };
+        try {
+            const res = await this.runTimed("updateMany", { collectionName, criteria, values }, async () => await collection.updateMany(criteria, { $set: values }));
+            return {
+                updated: res.modifiedCount,
+            };
+        }
+        catch (err) {
+            throw new K2Error(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).
+     */
+    async update(collectionName, id, data, replace = false) {
+        this.validateCollectionName(collectionName);
+        const collection = await this.getCollection(collectionName);
+        data = K2DB.stripReservedFields(data);
+        data = this.applySchema(collectionName, data, /*partial*/ !replace);
+        data._updated = Date.now(); // Set the _updated timestamp
+        try {
+            let res;
+            // If replacing the document, first get the original document
+            if (replace) {
+                // Get the original document to preserve fields starting with underscore
+                const originalDoc = await this.get(collectionName, id);
+                // Override all fields starting with underscore from the original document
+                const fieldsToPreserve = Object.keys(originalDoc).reduce((acc, key) => {
+                    if (key.startsWith("_")) {
+                        acc[key] = originalDoc[key];
+                    }
+                    return acc;
+                }, {});
+                // Merge the preserved fields into the data
+                data = { ...data, ...fieldsToPreserve };
+                data._updated = Date.now();
+                // Now replace the document with the merged data
+                res = await this.runTimed("replaceOne", { collectionName, _uuid: id }, async () => await collection.replaceOne({ _uuid: id, _deleted: { $ne: true } }, data));
+            }
+            else {
+                // If patching, just update specific fields using $set
+                res = await this.runTimed("updateOne", { collectionName, _uuid: id }, async () => await collection.updateOne({ _uuid: id, _deleted: { $ne: true } }, { $set: data }));
+            }
+            // Use matchedCount to determine existence; modifiedCount indicates actual change
+            if (res.matchedCount === 0) {
+                throw new K2Error(ServiceError.NOT_FOUND, `Object in ${collectionName} with UUID ${id} not found`, "sys_mdb_update_not_found");
+            }
+            return { updated: res.modifiedCount };
+        }
+        catch (err) {
+            if (err instanceof K2Error) {
+                throw err;
+            }
+            // Catch any other unhandled errors and throw a system error
+            throw new K2Error(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) {
+        this.validateCollectionName(collectionName);
+        try {
+            let result = await this.updateAll(collectionName, criteria, {
+                _deleted: true,
+            });
+            return { deleted: result.updated };
+        }
+        catch (err) {
+            throw new K2Error(ServiceError.SYSTEM_ERROR, `Error updating ${collectionName}`, "sys_mdb_deleteall_update", this.normalizeError(err));
+        }
+    }
+    /**
+     * 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(ServiceError.NOT_FOUND, "Document not found", "sys_mdb_remove_not_found");
+            }
+            else {
+                // More than one document was deleted, which is unexpected
+                throw new K2Error(ServiceError.SYSTEM_ERROR, "Multiple documents deleted when only one was expected", "sys_mdb_remove_multiple_deleted");
+            }
+        }
+        catch (err) {
+            throw new K2Error(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 this.runTimed("findOne", { collectionName, _uuid: id, _deleted: true }, async () => await collection.findOne({
+                _uuid: id,
+                _deleted: true,
+            }));
+            if (!item) {
+                throw new K2Error(ServiceError.SYSTEM_ERROR, "Cannot purge item that is not deleted", "sys_mdb_gcol_pg2");
+            }
+            await this.runTimed("deleteOne", { collectionName, _uuid: id }, async () => await collection.deleteOne({ _uuid: id }));
+            return { id };
+        }
+        catch (err) {
+            if (err instanceof K2Error) {
+                throw err;
+            }
+            throw new K2Error(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);
+        const query = { ...(criteria || {}), _deleted: true };
+        try {
+            const res = await this.runTimed("updateMany", { collectionName, query }, async () => await collection.updateMany(query, {
+                $set: { _deleted: false },
+            }));
+            return { status: "restored", modified: res.modifiedCount };
+        }
+        catch (err) {
+            throw new K2Error(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 query = {
+                ...criteria,
+                ...(criteria && Object.prototype.hasOwnProperty.call(criteria, "_deleted")
+                    ? {}
+                    : { _deleted: { $ne: true } }),
+            };
+            const cnt = await this.runTimed("countDocuments", { collectionName, query }, async () => await collection.countDocuments(query));
+            return { count: cnt };
+        }
+        catch (err) {
+            throw new K2Error(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(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;
+    }
+    /** Strip any user-provided fields that start with '_' (reserved). */
+    static stripReservedFields(obj) {
+        const out = {};
+        for (const [k, v] of Object.entries(obj || {})) {
+            if (!k.startsWith("_"))
+                out[k] = v;
+        }
+        return out;
+    }
+    /**
+     * Run an async DB operation with timing, slow logging, and hooks.
+     */
+    async runTimed(op, details, fn) {
+        try {
+            this.conf.hooks?.beforeQuery?.(op, details);
+        }
+        catch { }
+        const start = Date.now();
+        try {
+            const res = await fn();
+            const dur = Date.now() - start;
+            const slow = this.conf.slowQueryMs ?? 200;
+            if (dur > slow) {
+                debug(`[SLOW ${op}] ${dur}ms ${JSON.stringify(details)}`);
+            }
+            try {
+                this.conf.hooks?.afterQuery?.(op, { ...details, ok: true }, dur);
+            }
+            catch { }
+            return res;
+        }
+        catch (e) {
+            const dur = Date.now() - start;
+            try {
+                this.conf.hooks?.afterQuery?.(op, { ...details, ok: false, error: e instanceof Error ? e.message : String(e) }, dur);
+            }
+            catch { }
+            throw e;
+        }
+    }
+    /**
+     * Ensure commonly needed indexes exist.
+     */
+    async ensureIndexes(collectionName, opts = {}) {
+        const { uuidUnique = false, uuidPartialUnique = true, ownerIndex = true, deletedIndex = true, } = opts;
+        const collection = await this.getCollection(collectionName);
+        if (uuidPartialUnique) {
+            await collection.createIndex({ _uuid: 1 }, { unique: true, partialFilterExpression: { _deleted: { $ne: true } } });
+        }
+        else if (uuidUnique) {
+            await collection.createIndex({ _uuid: 1 }, { unique: true });
+        }
+        if (ownerIndex) {
+            await collection.createIndex({ _owner: 1 });
+        }
+        if (deletedIndex) {
+            await collection.createIndex({ _deleted: 1 });
+        }
+    }
+    /**
+     * 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(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(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(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(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(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));
+    }
+    // ===== Versioning helpers and APIs =====
+    /** Name of the history collection for a given collection. */
+    historyName(collectionName) {
+        return `${collectionName}__history`;
+    }
+    // ===== Zod schema registry (opt-in) =====
+    /** Register a Zod schema for a collection. */
+    setSchema(collectionName, schema, options = {}) {
+        const mode = options.mode ?? "strip";
+        this.schemas.set(collectionName, { schema, mode });
+    }
+    /** Clear a collection's schema. */
+    clearSchema(collectionName) {
+        this.schemas.delete(collectionName);
+    }
+    /** Clear all schemas. */
+    clearSchemas() {
+        this.schemas.clear();
+    }
+    /** Apply registered schema (if any) to data. For updates, partial=true allows partial input. */
+    applySchema(collectionName, data, partial) {
+        const entry = this.schemas.get(collectionName);
+        if (!entry)
+            return data;
+        let s = entry.schema;
+        // If schema is an object, apply unknown key policy and partial when needed
+        if (s instanceof z.ZodObject) {
+            const so = s;
+            const shaped = entry.mode === "strict" ? so.strict() : entry.mode === "passthrough" ? so.passthrough() : so.strip();
+            s = partial ? shaped.partial() : shaped;
+        }
+        else {
+            // Non-object schema: partial has no effect; leave as-is
+        }
+        const parsed = s.safeParse(data);
+        if (!parsed.success) {
+            throw new K2Error(ServiceError.BAD_REQUEST, "Validation failed", "sys_mdb_schema_validation", new Error(parsed.error.message));
+        }
+        return parsed.data;
+    }
+    /** Get the history collection. */
+    async getHistoryCollection(collectionName) {
+        return this.db.collection(this.historyName(collectionName));
+    }
+    /** Ensure indexes for history tracking. */
+    async ensureHistoryIndexes(collectionName) {
+        const hc = await this.getHistoryCollection(collectionName);
+        await hc.createIndex({ _uuid: 1, _v: 1 }, { unique: true });
+        await hc.createIndex({ _uuid: 1, _at: -1 });
+    }
+    /** Compute the next version number for a document. */
+    async nextVersion(collectionName, id) {
+        const hc = await this.getHistoryCollection(collectionName);
+        const last = await hc
+            .find({ _uuid: id })
+            .project({ _v: 1 })
+            .sort({ _v: -1 })
+            .limit(1)
+            .toArray();
+        return last.length ? last[0]._v + 1 : 1;
+    }
+    /** Save a snapshot of the current document into the history collection. */
+    async snapshotCurrent(collectionName, current) {
+        const hc = await this.getHistoryCollection(collectionName);
+        const version = await this.nextVersion(collectionName, current._uuid);
+        await hc.insertOne({
+            _uuid: current._uuid,
+            _v: version,
+            _at: Date.now(),
+            snapshot: current,
+        });
+        return { version };
+    }
+    /**
+     * Update a document and keep the previous version in a history collection.
+     * If maxVersions is provided, prunes oldest snapshots beyond that number.
+     */
+    async updateVersioned(collectionName, id, data, replace = false, maxVersions) {
+        // Get current doc (excludes deleted) and snapshot it
+        const current = await this.get(collectionName, id);
+        await this.ensureHistoryIndexes(collectionName);
+        const { version } = await this.snapshotCurrent(collectionName, current);
+        // Perform update
+        const res = await this.update(collectionName, id, data, replace);
+        // Optionally prune old versions
+        if (typeof maxVersions === "number" && maxVersions >= 0) {
+            const hc = await this.getHistoryCollection(collectionName);
+            const count = await hc.countDocuments({ _uuid: id });
+            const overflow = count - maxVersions;
+            if (overflow > 0) {
+                const olds = await hc
+                    .find({ _uuid: id })
+                    .project({ _v: 1 })
+                    .sort({ _v: 1 })
+                    .limit(overflow)
+                    .toArray();
+                const vs = olds.map((o) => o._v);
+                if (vs.length) {
+                    await hc.deleteMany({ _uuid: id, _v: { $in: vs } });
+                }
+            }
+        }
+        return [{ updated: res.updated, versionSaved: version }];
+    }
+    /** List versions (latest first). */
+    async listVersions(collectionName, id, skip = 0, limit = 20) {
+        const hc = await this.getHistoryCollection(collectionName);
+        const rows = await hc
+            .find({ _uuid: id })
+            .project({ _uuid: 1, _v: 1, _at: 1 })
+            .sort({ _v: -1 })
+            .skip(skip)
+            .limit(limit)
+            .toArray();
+        return rows;
+    }
+    /** Revert the current document to a specific historical version (preserves metadata). */
+    async revertToVersion(collectionName, id, version) {
+        const hc = await this.getHistoryCollection(collectionName);
+        const row = await hc.findOne({ _uuid: id, _v: version });
+        if (!row) {
+            throw new K2Error(ServiceError.NOT_FOUND, `Version ${version} for ${id} not found`, "sys_mdb_version_not_found");
+        }
+        const snapshot = row.snapshot;
+        // Only apply non-underscore fields; metadata is preserved by replace=true path
+        const apply = {};
+        for (const [k, v] of Object.entries(snapshot)) {
+            if (!k.startsWith("_"))
+                apply[k] = v;
+        }
+        return this.update(collectionName, id, apply, true);
+    }
+}