@frogfish/k2db 1.0.14 → 2.0.1

package/db.js

@@ -1,16 +1,15 @@
-"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 {
+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;
     }
@@ -18,76 +17,80 @@ class K2DB {
      * Initializes the MongoDB connection.
      */
     async init() {
-        // 1. dbName from config
+        // Build URI and options
+        const { uri, options } = this.buildMongoUri();
         const dbName = this.conf.name;
-        // 2. Build the connection string with user/password if available
-        //    (Change 'mongodb+srv://' back to 'mongodb://' if you're not using an SRV connection)
-        let connectUrl = "mongodb+srv://";
-        if (this.conf.user && this.conf.password) {
-            connectUrl += `${encodeURIComponent(this.conf.user)}:${encodeURIComponent(this.conf.password)}@`;
-        }
-        // 3. If no hosts, throw an error
-        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");
-        }
-        // 4. Handle single vs multiple hosts
-        //    - If SRV, you typically only specify the first host (no port)
-        //    - If non-SRV, you'd do: .map((host) => `${host.host}:${host.port || 27017}`).join(",")
-        //
-        // For SRV, we *usually* just do the first host:
-        connectUrl += this.conf.hosts[0].host;
-        // 5. Append the DB name
-        //    If SRV with Atlas, you can also append `retryWrites=true&w=majority`, etc.
-        //    If you need to pass additional params (e.g., replicaSet), you can do so below.
-        connectUrl += `/${dbName}`;
-        // 6. Append replicaset if more than one host and replicaset is defined.
-        //    (Typically, SRV records handle the replicaSet automatically, so you may not need this.
-        //     But if you do, keep this logic.)
-        if (this.conf.hosts.length > 1 && this.conf.replicaset) {
-            // If you already have `/${dbName}?...`, you need to add `&` instead of `?`.
-            // For simplicity, we do a conditional:
-            if (connectUrl.includes("?")) {
-                connectUrl += `&replicaSet=${this.conf.replicaset}&keepAlive=true&autoReconnect=true&socketTimeoutMS=0`;
-            }
-            else {
-                connectUrl += `?replicaSet=${this.conf.replicaset}&keepAlive=true&autoReconnect=true&socketTimeoutMS=0`;
-            }
-        }
-        else {
-            // For SRV + Atlas: often we want at least `?retryWrites=true&w=majority`
-            if (!connectUrl.includes("?")) {
-                connectUrl += "?retryWrites=true&w=majority";
-            }
-            else {
-                connectUrl += "&retryWrites=true&w=majority";
-            }
-        }
         // Mask sensitive information in logs
-        const safeConnectUrl = connectUrl.replace(/\/\/.*?:.*?@/, "//*****:*****@");
+        const safeConnectUrl = uri.replace(/\/\/.*?:.*?@/, "//*****:*****@");
         debug(`Connecting to MongoDB: ${safeConnectUrl}`);
-        // 7. Define connection options with timeouts
-        //    (Keep from original code, or update as needed)
-        const options = {
-            connectTimeoutMS: 2000,
-            serverSelectionTimeoutMS: 2000,
-            // If you want the Stable API (like in your _init), do:
-            // serverApi: {
-            //   version: ServerApiVersion.v1,
-            //   strict: true,
-            //   deprecationErrors: true,
-            // },
-        };
         try {
             // 8. Establish MongoDB connection
-            this.connection = await mongodb_1.MongoClient.connect(connectUrl, options);
+            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_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, "Failed to connect to MongoDB", "sys_mdb_init", this.normalizeError(err));
+            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.
@@ -100,10 +103,10 @@ class K2DB {
         }
         catch (err) {
             // If the error is already an K2Error, rethrow it
-            if (err instanceof k2error_1.K2Error) {
+            if (err instanceof K2Error) {
                 throw err;
             }
-            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, `Error getting collection: ${collectionName}`, "sys_mdb_gc", this.normalizeError(err));
+            throw new K2Error(ServiceError.SYSTEM_ERROR, `Error getting collection: ${collectionName}`, "sys_mdb_gc", this.normalizeError(err));
         }
     }
     async get(collectionName, uuid) {
@@ -112,7 +115,7 @@ class K2DB {
             _deleted: { $ne: true },
         });
         if (!res) {
-            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, "Error getting the document with provided identity", "sys_mdb_get");
+            throw new K2Error(ServiceError.NOT_FOUND, "Document not found", "sys_mdb_get_not_found");
         }
         return res;
     }
@@ -126,13 +129,20 @@ class K2DB {
     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 collection.findOne(criteria, { projection });
+            const item = await this.runTimed("findOne", { collectionName, query, projection }, async () => await collection.findOne(query, { projection }));
             if (item) {
                 const { _id, ...rest } = item;
                 return rest;
@@ -140,7 +150,7 @@ class K2DB {
             return null;
         }
         catch (err) {
-            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, "Error finding document", "sys_mdb_fo", this.normalizeError(err));
+            throw new K2Error(ServiceError.SYSTEM_ERROR, "Error finding document", "sys_mdb_fo", this.normalizeError(err));
         }
     }
     /**
@@ -154,32 +164,37 @@ class K2DB {
     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 || {};
+        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
+        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 = { _id: 0 }; // Exclude _id by default
+        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
         }
-        if (Array.isArray(params.exclude)) {
+        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) {
@@ -195,7 +210,7 @@ class K2DB {
             if (sort) {
                 cursor = cursor.sort(sort);
             }
-            const data = await cursor.toArray();
+            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;
@@ -204,7 +219,7 @@ class K2DB {
             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));
+            throw new K2Error(ServiceError.SYSTEM_ERROR, "Error executing find query", "sys_mdb_find_error", this.normalizeError(err));
         }
     }
     /**
@@ -216,15 +231,10 @@ class K2DB {
      */
     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 } } });
+            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 });
@@ -242,14 +252,97 @@ class K2DB {
             return stage;
         });
         try {
-            const data = await collection.aggregate(sanitizedCriteria).toArray();
+            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_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, "Aggregation failed", "sys_mdb_ag", this.normalizeError(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.
@@ -258,37 +351,40 @@ class K2DB {
      */
     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");
+            throw new K2Error(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");
+            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 = (0, uuid_1.v4)();
-        // Spread `data` first, then set internal fields to prevent overwriting
+        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 = {
-            ...data,
+            ...validated,
             _created: timestamp,
             _updated: timestamp,
             _owner: owner,
             _uuid: newUuid,
         };
         try {
-            const result = await collection.insertOne(document);
+            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_1.K2Error(k2error_1.ServiceError.ALREADY_EXISTS, `A document with _uuid ${document._uuid} already exists.`, "sys_mdb_crv3");
+                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_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, "Error saving object to database", "sys_mdb_sav", this.normalizeError(err));
+            throw new K2Error(ServiceError.SYSTEM_ERROR, "Error saving object to database", "sys_mdb_sav", this.normalizeError(err));
         }
     }
     /**
@@ -302,19 +398,21 @@ class K2DB {
         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 collection.updateMany(criteria, { $set: values });
+            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_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, `Error updating ${collectionName}`, "sys_mdb_update1", this.normalizeError(err));
+            throw new K2Error(ServiceError.SYSTEM_ERROR, `Error updating ${collectionName}`, "sys_mdb_update1", this.normalizeError(err));
         }
     }
     /**
@@ -328,6 +426,8 @@ class K2DB {
     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;
@@ -346,33 +446,24 @@ class K2DB {
                 data = { ...data, ...fieldsToPreserve };
                 data._updated = Date.now();
                 // Now replace the document with the merged data
-                res = await collection.replaceOne({ _uuid: id }, 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 collection.updateOne({ _uuid: id }, { $set: data });
-            }
-            // Check if exactly one document was updated
-            if (res.modifiedCount === 1) {
-                return { updated: 1 };
-            }
-            // If no document was updated, throw a NOT_FOUND error
-            if (res.modifiedCount === 0) {
-                throw new k2error_1.K2Error(k2error_1.ServiceError.NOT_FOUND, `Object in ${collectionName} with UUID ${id} not found`, "sys_mdb_update_not_found");
+                res = await this.runTimed("updateOne", { collectionName, _uuid: id }, async () => await collection.updateOne({ _uuid: id, _deleted: { $ne: true } }, { $set: data }));
             }
-            // If more than one document was updated (though this should never happen with a single UUID), throw a SYSTEM_ERROR
-            if (res.modifiedCount > 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");
+            // 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: 0 if no documents were modified (though this is unlikely)
-            return { updated: 0 };
+            return { updated: res.modifiedCount };
         }
         catch (err) {
-            if (err instanceof k2error_1.K2Error) {
+            if (err instanceof 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));
+            throw new K2Error(ServiceError.SYSTEM_ERROR, `Error updating ${collectionName}`, "sys_mdb_update_error", this.normalizeError(err));
         }
     }
     /**
@@ -389,7 +480,7 @@ class K2DB {
             return { deleted: result.updated };
         }
         catch (err) {
-            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, `Error updating ${collectionName}`, "sys_mdb_deleteall_update", this.normalizeError(err));
+            throw new K2Error(ServiceError.SYSTEM_ERROR, `Error updating ${collectionName}`, "sys_mdb_deleteall_update", this.normalizeError(err));
         }
     }
     /**
@@ -408,15 +499,15 @@ class K2DB {
             }
             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");
+                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_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, "Multiple documents deleted when only one was expected", "sys_mdb_remove_multiple_deleted");
+                throw new K2Error(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));
+            throw new K2Error(ServiceError.SYSTEM_ERROR, "Error removing object from collection", "sys_mdb_remove_upd", this.normalizeError(err));
         }
     }
     /**
@@ -427,21 +518,21 @@ class K2DB {
     async purge(collectionName, id) {
         const collection = await this.getCollection(collectionName);
         try {
-            const item = await collection.findOne({
+            const item = await this.runTimed("findOne", { collectionName, _uuid: id, _deleted: true }, async () => 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");
+                throw new K2Error(ServiceError.SYSTEM_ERROR, "Cannot purge item that is not deleted", "sys_mdb_gcol_pg2");
             }
-            await collection.deleteMany({ _uuid: id });
+            await this.runTimed("deleteOne", { collectionName, _uuid: id }, async () => await collection.deleteOne({ _uuid: id }));
             return { id };
         }
         catch (err) {
-            if (err instanceof k2error_1.K2Error) {
+            if (err instanceof 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));
+            throw new K2Error(ServiceError.SYSTEM_ERROR, `Error purging item with id: ${id}`, "sys_mdb_pg", this.normalizeError(err));
         }
     }
     /**
@@ -451,15 +542,15 @@ class K2DB {
      */
     async restore(collectionName, criteria) {
         const collection = await this.getCollection(collectionName);
-        criteria._deleted = true;
+        const query = { ...(criteria || {}), _deleted: true };
         try {
-            const res = await collection.updateMany(criteria, {
+            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_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, "Error restoring a deleted item", "sys_mdb_pres", this.normalizeError(err));
+            throw new K2Error(ServiceError.SYSTEM_ERROR, "Error restoring a deleted item", "sys_mdb_pres", this.normalizeError(err));
         }
     }
     /**
@@ -470,11 +561,17 @@ class K2DB {
     async count(collectionName, criteria) {
         const collection = await this.getCollection(collectionName);
         try {
-            const cnt = await collection.countDocuments(criteria);
+            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_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, "Error counting objects with given criteria", "sys_mdb_cn", this.normalizeError(err));
+            throw new K2Error(ServiceError.SYSTEM_ERROR, "Error counting objects with given criteria", "sys_mdb_cn", this.normalizeError(err));
         }
     }
     /**
@@ -488,7 +585,7 @@ class K2DB {
             return { status: "ok" };
         }
         catch (err) {
-            throw new k2error_1.K2Error(k2error_1.ServiceError.SYSTEM_ERROR, "Error dropping collection", "sys_mdb_drop", this.normalizeError(err));
+            throw new K2Error(ServiceError.SYSTEM_ERROR, "Error dropping collection", "sys_mdb_drop", this.normalizeError(err));
         }
     }
     /**
@@ -512,6 +609,65 @@ class K2DB {
         }
         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.
@@ -544,7 +700,7 @@ class K2DB {
             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));
+            throw new K2Error(ServiceError.SYSTEM_ERROR, `Error creating index on ${collectionName}`, "sys_mdb_idx", this.normalizeError(err));
         }
     }
     /**
@@ -569,7 +725,7 @@ class K2DB {
             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));
+            throw new K2Error(ServiceError.SYSTEM_ERROR, "Error dropping database", "sys_mdb_drop_db", this.normalizeError(err));
         }
     }
     /**
@@ -580,15 +736,15 @@ class K2DB {
     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");
+            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_1.K2Error(k2error_1.ServiceError.BAD_REQUEST, "Collection name cannot start with 'system.'", "sys_mdb_invalid_collection_name");
+            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_1.K2Error(k2error_1.ServiceError.BAD_REQUEST, "Collection name cannot contain the '$' character", "sys_mdb_invalid_collection_name");
+            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
     }
@@ -612,5 +768,136 @@ class K2DB {
     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);
+    }
 }
-exports.K2DB = K2DB;