@frogfish/k2db 2.0.7 → 3.0.2

package/dist/db.js

@@ -1,1063 +0,0 @@
-// src/db.ts
-import { K2Error, ServiceError } from "@frogfish/k2error"; // Keep the existing error structure
-import { MongoClient, } from "mongodb";
-import { randomBytes } from "crypto";
-import debugLib from "debug";
-import { z } from "zod";
-const debug = debugLib("k2:db");
-// Crockford Base32 alphabet (no I, L, O, U)
-const CROCKFORD32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
-/**
- * Generates a UUIDv7 (time-ordered) and encodes it as Crockford Base32 with hyphens.
- * Format: 26 base32 chars grouped as 8-4-4-4-6 (total 26)
- */
-function uuidv7Base32Hyphenated() {
-    // 1) Build UUIDv7 bytes
-    // Layout per RFC: time_low(32) | time_mid(16) | time_hi_and_version(16) | clock_seq(16) | node(48)
-    // Encode 60-bit ms timestamp across time_* fields, version 7, RFC4122 variant in clock_seq_hi.
-    const ts = BigInt(Date.now()); // milliseconds
-    const timeLow = Number((ts >> 28n) & 0xffffffffn);
-    const timeMid = Number((ts >> 12n) & 0xffffn);
-    const timeHi = Number(ts & 0xfffn); // lower 12 bits
-    const bytes = new Uint8Array(16);
-    // time_low (big-endian)
-    bytes[0] = (timeLow >>> 24) & 0xff;
-    bytes[1] = (timeLow >>> 16) & 0xff;
-    bytes[2] = (timeLow >>> 8) & 0xff;
-    bytes[3] = timeLow & 0xff;
-    // time_mid (big-endian)
-    bytes[4] = (timeMid >>> 8) & 0xff;
-    bytes[5] = timeMid & 0xff;
-    // time_high_and_version: version 7 in high nibble + top 4 bits of timeHi
-    bytes[6] = 0x70 | ((timeHi >>> 8) & 0x0f); // 0x7- version
-    bytes[7] = timeHi & 0xff;
-    // clock_seq + node: 8 random bytes; set RFC4122 variant (10xxxxxx)
-    const rnd = randomBytes(8);
-    bytes.set(rnd, 8);
-    bytes[8] = (bytes[8] & 0x3f) | 0x80; // set variant 10xxxxxx
-    // 2) Encode as Crockford Base32 (26 chars). 128 bits -> 26*5 bits (pad 2 high bits)
-    let value = 0n;
-    for (let i = 0; i < 16; i++) {
-        value = (value << 8n) | BigInt(bytes[i]);
-    }
-    value <<= 2n; // pad to 130 bits so we can take 26 groups cleanly
-    let encoded = "";
-    for (let i = 25; i >= 0; i--) {
-        const idx = Number((value >> BigInt(i * 5)) & 0x1fn);
-        encoded += CROCKFORD32[idx];
-    }
-    // 3) Insert hyphens in groups: 8-4-4-4-6
-    return (encoded.slice(0, 8) +
-        "-" +
-        encoded.slice(8, 12) +
-        "-" +
-        encoded.slice(12, 16) +
-        "-" +
-        encoded.slice(16, 20) +
-        "-" +
-        encoded.slice(20));
-}
-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 id = K2DB.normalizeId(uuid);
-        const res = await this.findOne(collectionName, {
-            _uuid: id,
-            _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 normalizedCriteria = K2DB.normalizeCriteriaIds(criteria || {});
-        const query = {
-            ...normalizedCriteria,
-            ...(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
-        let criteria = { ...(filter || {}) };
-        criteria = K2DB.normalizeCriteriaIds(criteria);
-        // 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 UUIDv7 encoded as Crockford Base32 with hyphens
-        const newUuid = uuidv7Base32Hyphenated();
-        // 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)}`);
-        // Preserve intent to set _deleted during internal soft-delete operations.
-        // stripReservedFields removes underscore-prefixed keys (by design) to protect
-        // internal fields from user updates. However, deleteAll() legitimately passes
-        // {_deleted: true}. Capture and restore it here.
-        const deletedFlag = Object.prototype.hasOwnProperty.call(values, "_deleted")
-            ? values._deleted
-            : undefined;
-        values = K2DB.stripReservedFields(values);
-        values = this.applySchema(collectionName, values, /*partial*/ true);
-        values._updated = Date.now();
-        if (deletedFlag !== undefined) {
-            values._deleted = deletedFlag;
-        }
-        criteria = K2DB.normalizeCriteriaIds(criteria || {});
-        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) {
-        id = K2DB.normalizeId(id);
-        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) {
-        id = K2DB.normalizeId(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) {
-            // Preserve existing K2Error classifications (e.g., NOT_FOUND)
-            if (err instanceof K2Error) {
-                throw 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) {
-        id = K2DB.normalizeId(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));
-        }
-    }
-    /**
-     * Permanently deletes all documents that are soft-deleted and whose _updated
-     * timestamp is older than the provided threshold (in milliseconds ago).
-     * @param collectionName - Name of the collection.
-     * @param olderThanMs - Age threshold in milliseconds; documents with
-     *                      `_updated <= (Date.now() - olderThanMs)` will be purged.
-     */
-    async purgeDeletedOlderThan(collectionName, olderThanMs) {
-        this.validateCollectionName(collectionName);
-        if (typeof olderThanMs !== 'number' || !isFinite(olderThanMs) || olderThanMs < 0) {
-            throw new K2Error(ServiceError.BAD_REQUEST, 'olderThanMs must be a non-negative number', 'sys_mdb_purge_older_invalid');
-        }
-        const collection = await this.getCollection(collectionName);
-        const cutoff = Date.now() - olderThanMs;
-        try {
-            const res = await this.runTimed('deleteMany', { collectionName, olderThanMs, cutoff }, async () => await collection.deleteMany({
-                _deleted: true,
-                _updated: { $lte: cutoff },
-            }));
-            return { purged: res.deletedCount ?? 0 };
-        }
-        catch (err) {
-            throw new K2Error(ServiceError.SYSTEM_ERROR, 'Error purging deleted items by age', 'sys_mdb_purge_older', 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 crit = K2DB.normalizeCriteriaIds(criteria || {});
-        const query = { ...crit, _deleted: true };
-        try {
-            const res = await this.runTimed("updateMany", { collectionName, query }, async () => await collection.updateMany(query, {
-                // Restoring is a data change: flip _deleted and bump _updated
-                $set: { _deleted: false, _updated: Date.now() },
-            }));
-            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 norm = K2DB.normalizeCriteriaIds(criteria || {});
-            const query = {
-                ...norm,
-                ...(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) {
-            // Normalize any _uuid values in the match object to uppercase
-            criteria.$match = K2DB.normalizeCriteriaIds(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;
-    }
-    /** Recursively uppercases any values for fields named `_uuid` within a query object. */
-    static normalizeCriteriaIds(obj) {
-        if (!obj || typeof obj !== "object")
-            return obj;
-        if (Array.isArray(obj))
-            return obj.map((v) => K2DB.normalizeCriteriaIds(v));
-        const out = Array.isArray(obj) ? [] : { ...obj };
-        for (const [k, v] of Object.entries(obj)) {
-            if (k === "_uuid") {
-                out[k] = K2DB.normalizeUuidField(v);
-            }
-            else if (v && typeof v === "object") {
-                out[k] = K2DB.normalizeCriteriaIds(v);
-            }
-            else if (Array.isArray(v)) {
-                out[k] = v.map((x) => K2DB.normalizeCriteriaIds(x));
-            }
-            else {
-                out[k] = v;
-            }
-        }
-        return out;
-    }
-    /** Uppercase helper for `_uuid` field supporting operators like $in/$nin/$eq/$ne and arrays. */
-    static normalizeUuidField(val) {
-        if (typeof val === "string")
-            return val.toUpperCase();
-        if (Array.isArray(val))
-            return val.map((x) => (typeof x === "string" ? x.toUpperCase() : x));
-        if (val && typeof val === "object") {
-            const out = { ...val };
-            for (const op of ["$in", "$nin", "$eq", "$ne", "$all"]) {
-                if (op in out)
-                    out[op] = K2DB.normalizeUuidField(out[op]);
-            }
-            return out;
-        }
-        return val;
-    }
-    /** 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;
-    }
-    /** True if string matches K2 ID format (Crockford Base32, 8-4-4-4-6, uppercase). */
-    static isK2ID(id) {
-        if (typeof id !== "string")
-            return false;
-        const s = id.trim().toUpperCase();
-        const CROCK_RE = /^[0-9A-HJKMNPQRSTVWXYZ]{8}-[0-9A-HJKMNPQRSTVWXYZ]{4}-[0-9A-HJKMNPQRSTVWXYZ]{4}-[0-9A-HJKMNPQRSTVWXYZ]{4}-[0-9A-HJKMNPQRSTVWXYZ]{6}$/;
-        return CROCK_RE.test(s);
-    }
-    /** Uppercase incoming IDs for case-insensitive lookups. */
-    static normalizeId(id) {
-        return id.toUpperCase();
-    }
-    /**
-     * 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) {
-            // Use a compound unique index to ensure at most one non-deleted document per _uuid
-            // without relying on partialFilterExpression (which may be limited in some environments).
-            await collection.createIndex({ _uuid: 1, _deleted: 1 }, { unique: 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) {
-        id = K2DB.normalizeId(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) {
-        id = K2DB.normalizeId(id);
-        // 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) {
-        id = K2DB.normalizeId(id);
-        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) {
-        id = K2DB.normalizeId(id);
-        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);
-    }
-}