@frogfish/k2db 1.0.14 → 2.0.1

package/README.md

@@ -1 +1,297 @@
-# k2db
+# k2db
+
+Lightweight MongoDB data layer that stays schemaless by default while enforcing consistent metadata and soft-delete.
+
+Why this, not an ORM?
+- Thin driver wrapper: Sits directly atop the official MongoDB driver. No models, decorators, or migrations to manage.
+- Loose by default: Store arbitrary data while consistently enforcing `_uuid`, `_owner`, `_created`, `_updated`, `_deleted`.
+- Opinionated guardrails: Soft‑delete and metadata are enforced everywhere, including aggregates, without changing your payloads.
+- Opt‑in structure: Add Zod schemas per collection only if you want validation/coercion; skip entirely if you don’t.
+- Predictable behavior: No hidden population, no query magic, and explicit return types. What you query is what runs.
+
+What you get
+- Concrete API for Mongo: Avoid re‑implementing the same metadata, soft‑delete, and versioning patterns across services. This wrapper centralizes those policies so teams don’t write boilerplate.
+- Guardrails without heavy ORM: Prisma/Mongoose add ceremony (models, migrations, plugins) that can be overkill in microservices/serverless. k2db gives you just enough safety with minimal overhead.
+- Soft deletes done properly: Automatically enforced everywhere (including aggregates and joins), so you don’t accidentally leak or operate on deleted data.
+- Versioning baked in: `updateVersioned`, `listVersions`, and `revertToVersion` provide low‑friction “undo to N levels” that many DALs lack, increasing confidence in production changes.
+
+Where it fits in the stack
+- Below your API/service layer and above the MongoDB driver.
+- Use it as a shared data access layer (DAL) across services that need flexible shapes but strict lifecycle rules.
+- Keep ownership/authorization in your API; this library only guarantees metadata and deletion semantics.
+- Designed for microservices and edge computing: tiny footprint, fast cold starts, and no heavy runtime dependencies.
+
+Deployment tips (Nomad, Lambda, etc.)
+- Environments: Targets Node.js runtimes (Node 18/20). Not suitable for non‑TCP “edge JS” (e.g., Cloudflare Workers) that cannot open Mongo sockets.
+- Connection reuse: Create one `K2DB` instance per process and reuse it.
+  - Lambda: instantiate outside the handler and `await init()` lazily once.
+  - Nomad: init on service start; reuse for the lifetime of the task.
+- Example (AWS Lambda):
+  ```ts
+  import { K2DB } from "@frogfish/k2db";
+  const db = new K2DB(K2DB.fromEnv());
+  let ready: Promise<void> | null = null;
+  export const handler = async (event) => {
+    ready = ready || db.init();
+    await ready; // reused across warm invocations
+    const res = await db.find("hello", { _owner: event.userId }, {}, 0, 10);
+    return { statusCode: 200, body: JSON.stringify(res) };
+  };
+  ```
+- Pooling and timeouts: The driver manages a small pool by default.
+  - Serverless: keep `minPoolSize=0` (default), consider `maxIdleTimeMS` to drop idle sockets faster.
+  - Long‑lived services (Nomad): you can tune pool sizing if needed.
+  - You can adjust `connectTimeoutMS/serverSelectionTimeoutMS` in the code if your environment needs higher values.
+- Networking:
+  - Atlas from Lambda: prefer VPC + PrivateLink or NAT egress; ensure security groups allow outbound to Atlas.
+  - Nomad: ensure egress to Atlas/DB, or run Mongo in the same network; set DNS to resolve SRV if using SRV.
+- Secrets:
+  - Lambda: use AWS Secrets Manager/Parameter Store → env vars consumed by `K2DB.fromEnv()`.
+  - Nomad: pair with HashiCorp Vault templates/env inject; keep credentials out of images.
+- Health/readiness:
+  - Use `db.isHealthy()` in readiness checks (Nomad) and `db.release()` on shutdown. For Lambda there’s no explicit shutdown.
+- Bundling:
+  - ESM friendly; keep dependencies minimal. If you bundle, exclude native modules you don’t use.
+
+When to pick this
+- You want Mongo’s flexibility with light, reliable guardrails (soft delete, timestamps, owner, UUID).
+- You’d rather not pull in a heavier ORM (Mongoose/Prisma) and prefer direct control of queries and indexes.
+- Your payloads vary by tenant/feature and rigid schemas get in the way, but you still want optional validation.
+
+When to consider something else
+- Rich modeling, relations, and ecosystem plugins → Mongoose.
+- Cross‑DB modeling, migrations, and schema‑first DX → Prisma.
+- If you already standardized on an ORM and like its trade‑offs, this library aims to stay out of your way.
+
+Core invariants
+- _uuid: unique identifier generated on create (unique among non-deleted by default).
+- _created/_updated: timestamps managed by the library.
+- _owner: required on create; preserved across updates.
+- _deleted: soft-delete flag. All reads exclude deleted by default; writes do not touch deleted docs. Purge hard-deletes only when `_deleted: true`.
+
+Modernized behavior
+- ESM build, TypeScript, NodeNext resolution.
+- Soft-delete enforced across find, findOne, count, update, updateAll.
+- Aggregate never returns deleted documents (also enforced across `$lookup`, `$unionWith`, `$graphLookup`, `$facet`).
+- Reserved fields: user input cannot set keys starting with `_`; the library owns all underscore-prefixed metadata.
+- Slow query logging: operations slower than `slowQueryMs` (default 200ms) are logged via `debug("k2:db")`.
+- Hooks: optional `beforeQuery(op, details)` and `afterQuery(op, details, durationMs)` for observability.
+- Index helper: `ensureIndexes(collection, { uuidPartialUnique: true, ownerIndex: true, deletedIndex: true })`.
+
+Ownership (`_owner`)
+- Purpose: `_owner` is not a tenant ID nor a technical auth scope. It’s a required, opinionated piece of metadata that records who a document belongs to (the data subject or system principal that created/owns it).
+- Why it matters: Enables clear data lineage and supports privacy/jurisdiction workflows (GDPR/DSAR: “export all my data”, “delete my data”), audits, and stewardship.
+- Typical values: a user’s UUID when a signed-in human creates the record; for automated/system operations use a stable identifier like `"system"`, `"service:mailer"`, or `"migration:2024-09-01"`.
+- Not authorization: The library does not enforce access control based on `_owner`. Apply your authorization rules in the API/service layer using `_owner` as a helpful filter or join key.
+- Multi-tenant setups: If you have tenants, keep a distinct `tenantId` (or similar) alongside `_owner`. `_owner` continues to model “who owns this record” rather than “which tenant it belongs to”.
+
+Config
+```ts
+import { K2DB } from "@frogfish/k2db";
+
+const db = new K2DB({
+  name: "mydb",
+  hosts: [{ host: "cluster0.example.mongodb.net" }], // SRV if single host without port
+  user: process.env.DB_USER,
+  password: process.env.DB_PASS,
+  slowQueryMs: 300,
+  hooks: {
+    beforeQuery: (op, d) => {},
+    afterQuery: (op, d, ms) => {},
+  },
+});
+
+await db.init();
+await db.ensureIndexes("myCollection");
+```
+
+Environment loader
+```ts
+const conf = K2DB.fromEnv(); // K2DB_NAME, K2DB_HOSTS, K2DB_USER, K2DB_PASSWORD, K2DB_REPLICASET, K2DB_SLOW_MS
+```
+
+Tips
+- Use `restore()` to clear `_deleted`.
+- Use `purge()` to hard-delete; only works on soft-deleted docs.
+- For aggregates with joins, the library automatically injects non-deleted filters in root and nested pipelines.
+
+Versioning (optional)
+- Per-document history is stored in a sibling collection named `<collection>__history`.
+- Use `updateVersioned()` to snapshot the previous state before updating.
+- Use `listVersions()` to see available versions and `revertToVersion()` to roll back (preserves metadata like `_uuid`, `_owner`, `_created`).
+
+Example:
+```ts
+// Save previous version and keep up to 20 versions
+await db.ensureHistoryIndexes("hello");
+await db.updateVersioned("hello", id, { message: "Hello v2" }, false, 20);
+
+// List latest 5 versions
+const versions = await db.listVersions("hello", id, 0, 5);
+
+// Revert to a specific version
+await db.revertToVersion("hello", id, versions[0]._v);
+```
+
+Further examples:
+```ts
+// Versioned replace
+await db.updateVersioned("hello", id, { message: "replace payload" }, true);
+
+// Keep only the most recent prior state (maxVersions = 1)
+await db.updateVersioned("hello", id, { message: "v3" }, false, 1);
+```
+
+**MongoDB Atlas**
+- Create a Database User in Atlas and allow your IP under Network Access.
+- Find your cluster address (looks like `cluster0.xxxxxx.mongodb.net`).
+- Minimal config uses SRV (no port) when a single host is provided.
+
+Example (direct config):
+```ts
+import { K2DB } from "@frogfish/k2db";
+
+const db = new K2DB({
+  name: "mydb", // your database name
+  hosts: [{ host: "cluster0.xxxxxx.mongodb.net" }], // Atlas SRV host
+  user: process.env.DB_USER, // Atlas DB user
+  password: process.env.DB_PASS, // Atlas DB password
+  slowQueryMs: 300,
+});
+
+await db.init();
+```
+
+Example (env-based):
+```bash
+export K2DB_NAME=mydb
+export K2DB_HOSTS=cluster0.xxxxxx.mongodb.net
+export K2DB_USER=your_user
+export K2DB_PASSWORD=your_pass
+node hello.mjs
+```
+```ts
+// hello.mjs (Node 18+, ESM)
+import { K2DB } from "@frogfish/k2db";
+
+const conf = K2DB.fromEnv();
+const db = new K2DB(conf);
+await db.init();
+```
+
+**Hello World**
+- Connect to Atlas, insert into `hello` collection, then read it back.
+
+```ts
+// hello-world.mjs
+import { K2DB } from "@frogfish/k2db";
+
+// Configure via env or inline config
+const db = new K2DB({
+  name: "mydb",
+  hosts: [{ host: "cluster0.xxxxxx.mongodb.net" }],
+  user: process.env.DB_USER,
+  password: process.env.DB_PASS,
+});
+
+await db.init();
+await db.ensureIndexes("hello"); // unique _uuid among non-deleted, plus helpful indexes
+
+// Create a document (owner is required)
+const { id } = await db.create("hello", "demo-owner", { message: "Hello, world!" });
+console.log("Inserted id:", id);
+
+// Read it back
+const doc = await db.get("hello", id); // excludes soft-deleted by default
+console.log("Retrieved:", doc);
+
+// Soft delete it (optional)
+await db.delete("hello", id);
+
+// Restore it (optional)
+await db.restore("hello", { _uuid: id });
+
+await db.release();
+```
+
+Notes
+- Use Node 18+ (preferably Node 20+) for ESM + JSON imports.
+- Atlas SRV requires only the cluster hostname (no port); the client handles TLS and topology.
+
+Updates
+- Patch vs Replace
+  - `update(collection, id, data)` patches by default using `$set` (fields you pass are updated, others remain).
+  - `update(collection, id, data, true)` replaces non‑metadata fields (PUT‑like). Metadata (`_uuid`, `_owner`, `_created`, `_updated`, `_deleted`) is preserved.
+  - Underscore‑prefixed fields in your input are ignored; `_updated` is refreshed automatically.
+
+Examples:
+```ts
+// Patch specific fields
+await db.update("hello", id, { message: "patched value" });
+
+// Replace (preserves metadata, overwrites non‑underscore fields)
+await db.update("hello", id, { message: "entire new doc", count: 1 }, true);
+```
+
+Schemas (optional, Zod)
+- You can register a Zod schema per collection at runtime; it validates and (optionally) strips unknown fields on writes. Nothing is stored in DB.
+- Modes: `strict` (reject unknown fields), `strip` (remove unknown; default), `passthrough` (allow unknown).
+
+Example:
+```ts
+import { z } from "zod";
+
+// Define
+const Hello = z
+  .object({
+    message: z.string(),
+    count: z.number().int().default(0),
+  })
+  .strip(); // default unknown-key behavior
+
+// Register (in-memory for this instance)
+db.setSchema("hello", Hello, { mode: "strip" });
+
+// On create: full schema validation; on patch: partial validation
+await db.create("hello", ownerId, { message: "hey", extra: "ignored" });
+await db.update("hello", id, { count: 2 }); // partial OK
+
+// To clear
+db.clearSchema("hello");
+```
+
+**Type Reference (Cheat Sheet)**
+- `BaseDocument`: Core shape enforced by the library; apps may extend.
+- `CreateResult`: `{ id: string }`
+- `UpdateResult`: `{ updated: number }`
+- `DeleteResult`: `{ deleted: number }`
+- `RestoreResult`: `{ status: string; modified: number }`
+- `CountResult`: `{ count: number }`
+- `DropResult`: `{ status: string }`
+- `PurgeResult`: `{ id: string }`
+- `VersionedUpdateResult`: `{ updated: number; versionSaved: number }`
+- `VersionInfo`: `{ _uuid: string; _v: number; _at: number }`
+
+Returns by method
+- `get(collection, id)`: `Promise<BaseDocument>`
+- `find(collection, filter, params?, skip?, limit?)`: `Promise<BaseDocument[]>`
+- `findOne(collection, criteria, fields?)`: `Promise<BaseDocument|null>`
+- `aggregate(collection, pipeline, skip?, limit?)`: `Promise<BaseDocument[]>`
+- `create(collection, owner, data)`: `Promise<CreateResult>`
+- `update(collection, id, data, replace?)`: `Promise<UpdateResult>`
+- `updateAll(collection, criteria, values)`: `Promise<UpdateResult>`
+- `delete(collection, id)`: `Promise<DeleteResult>`
+- `deleteAll(collection, criteria)`: `Promise<DeleteResult>`
+- `purge(collection, id)`: `Promise<PurgeResult>`
+- `restore(collection, criteria)`: `Promise<RestoreResult>`
+- `count(collection, criteria)`: `Promise<CountResult>`
+- `drop(collection)`: `Promise<DropResult>`
+- `ensureIndexes(collection, opts?)`: `Promise<void>`
+- `ensureHistoryIndexes(collection)`: `Promise<void>`
+- `updateVersioned(collection, id, data, replace?, maxVersions?)`: `Promise<VersionedUpdateResult[]>`
+- `listVersions(collection, id, skip?, limit?)`: `Promise<VersionInfo[]>`
+- `revertToVersion(collection, id, version)`: `Promise<UpdateResult>`
+- Zod registry:
+  - `setSchema(collection, zodSchema, { mode }?)`: `void`
+  - `clearSchema(collection)`: `void`
+  - `clearSchemas()`: `void`

package/data.d.ts

@@ -1,4 +1,4 @@
-import { K2DB, BaseDocument } from "./db";
+import { K2DB, BaseDocument, CreateResult, UpdateResult, DeleteResult, RestoreResult, CountResult, DropResult, VersionedUpdateResult, VersionInfo } from "./db.js";
 export declare class K2Data {
     private db;
     private owner;
@@ -27,33 +27,43 @@ export declare class K2Data {
     /**
      * Creates a new document in the collection.
      */
-    create(collectionName: string, data: Partial<BaseDocument>): Promise<{
-        id: string;
-    }>;
+    create(collectionName: string, data: Partial<BaseDocument>): Promise<CreateResult>;
     /**
      * Updates multiple documents based on criteria.
      */
-    updateAll(collectionName: string, criteria: any, values: Partial<BaseDocument>): Promise<{
-        updated: number;
-    }>;
+    updateAll(collectionName: string, criteria: any, values: Partial<BaseDocument>): Promise<UpdateResult>;
     /**
      * Updates a single document by UUID.
      */
-    update(collectionName: string, id: string, data: Partial<BaseDocument>, replace?: boolean): Promise<{
+    update(collectionName: string, id: string, data: Partial<BaseDocument>, replace?: boolean): Promise<UpdateResult>;
+    /**
+     * Updates a single document by UUID and saves the previous version to history.
+     */
+    updateVersioned(collectionName: string, id: string, data: Partial<BaseDocument>, replace?: boolean, maxVersions?: number): Promise<VersionedUpdateResult[]>;
+    /** List versions for a document (latest first). */
+    listVersions(collectionName: string, id: string, skip?: number, limit?: number): Promise<VersionInfo[]>;
+    /** Revert a document to a prior version. */
+    revertToVersion(collectionName: string, id: string, version: number): Promise<{
         updated: number;
     }>;
+    /** Ensure history collection indexes exist. */
+    ensureHistoryIndexes(collectionName: string): Promise<void>;
+    /** Register a Zod schema for a collection (in-memory). */
+    setSchema(collectionName: string, schema: any, options?: {
+        mode?: "strict" | "strip" | "passthrough";
+    }): void;
+    /** Clear a collection's schema. */
+    clearSchema(collectionName: string): void;
+    /** Clear all schemas. */
+    clearSchemas(): void;
     /**
      * Removes (soft deletes) multiple documents based on criteria.
      */
-    deleteAll(collectionName: string, criteria: any): Promise<{
-        deleted: number;
-    }>;
+    deleteAll(collectionName: string, criteria: any): Promise<DeleteResult>;
     /**
      * Removes (soft deletes) a single document by UUID.
      */
-    delete(collectionName: string, id: string): Promise<{
-        deleted: number;
-    }>;
+    delete(collectionName: string, id: string): Promise<DeleteResult>;
     /**
      * Permanently deletes a document that has been soft-deleted.
      */
@@ -63,22 +73,15 @@ export declare class K2Data {
     /**
      * Restores a soft-deleted document.
      */
-    restore(collectionName: string, criteria: any): Promise<{
-        status: string;
-        modified: number;
-    }>;
+    restore(collectionName: string, criteria: any): Promise<RestoreResult>;
     /**
      * Counts documents based on criteria.
      */
-    count(collectionName: string, criteria: any): Promise<{
-        count: number;
-    }>;
+    count(collectionName: string, criteria: any): Promise<CountResult>;
     /**
      * Drops an entire collection.
      */
-    drop(collectionName: string): Promise<{
-        status: string;
-    }>;
+    drop(collectionName: string): Promise<DropResult>;
     /**
      * Executes a transaction with the provided operations.
      */

package/data.js

@@ -1,7 +1,6 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.K2Data = void 0;
-class K2Data {
+export class K2Data {
+    db;
+    owner;
     constructor(db, owner) {
         this.db = db;
         this.owner = owner;
@@ -55,6 +54,36 @@ class K2Data {
         // Ensure it returns { updated: number }
         return this.db.update(collectionName, id, data, replace);
     }
+    /**
+     * Updates a single document by UUID and saves the previous version to history.
+     */
+    async updateVersioned(collectionName, id, data, replace = false, maxVersions) {
+        return this.db.updateVersioned(collectionName, id, data, replace, maxVersions);
+    }
+    /** List versions for a document (latest first). */
+    async listVersions(collectionName, id, skip, limit) {
+        return this.db.listVersions(collectionName, id, skip, limit);
+    }
+    /** Revert a document to a prior version. */
+    async revertToVersion(collectionName, id, version) {
+        return this.db.revertToVersion(collectionName, id, version);
+    }
+    /** Ensure history collection indexes exist. */
+    async ensureHistoryIndexes(collectionName) {
+        return this.db.ensureHistoryIndexes(collectionName);
+    }
+    /** Register a Zod schema for a collection (in-memory). */
+    setSchema(collectionName, schema, options) {
+        return this.db.setSchema(collectionName, schema, options);
+    }
+    /** Clear a collection's schema. */
+    clearSchema(collectionName) {
+        return this.db.clearSchema(collectionName);
+    }
+    /** Clear all schemas. */
+    clearSchemas() {
+        return this.db.clearSchemas();
+    }
     /**
      * Removes (soft deletes) multiple documents based on criteria.
      */
@@ -117,4 +146,3 @@ class K2Data {
         return this.db.isHealthy();
     }
 }
-exports.K2Data = K2Data;

package/db.d.ts

@@ -1,4 +1,5 @@
 import { ObjectId } from "mongodb";
+import { ZodTypeAny } from "zod";
 export interface HostConfig {
     host: string;
     port?: number;
@@ -9,6 +10,11 @@ export interface DatabaseConfig {
     password?: string;
     hosts?: HostConfig[];
     replicaset?: string;
+    slowQueryMs?: number;
+    hooks?: {
+        beforeQuery?: (op: string, details: any) => void;
+        afterQuery?: (op: string, details: any, durationMs: number) => void;
+    };
 }
 export interface BaseDocument {
     _id?: ObjectId;
@@ -19,15 +25,53 @@ export interface BaseDocument {
     _deleted?: boolean;
     [key: string]: any;
 }
+export interface CreateResult {
+    id: string;
+}
+export interface UpdateResult {
+    updated: number;
+}
+export interface DeleteResult {
+    deleted: number;
+}
+export interface RestoreResult {
+    status: string;
+    modified: number;
+}
+export interface CountResult {
+    count: number;
+}
+export interface DropResult {
+    status: string;
+}
+export interface PurgeResult {
+    id: string;
+}
+export interface VersionedUpdateResult {
+    updated: number;
+    versionSaved: number;
+}
+export interface VersionInfo {
+    _uuid: string;
+    _v: number;
+    _at: number;
+}
 export declare class K2DB {
     private conf;
     private db;
     private connection;
+    private schemas;
     constructor(conf: DatabaseConfig);
     /**
      * Initializes the MongoDB connection.
      */
     init(): Promise<void>;
+    /**
+     * Build a robust MongoDB URI based on config (supports SRV and standard).
+     */
+    private buildMongoUri;
+    /** Load DatabaseConfig from environment variables. */
+    static fromEnv(prefix?: string): DatabaseConfig;
     /**
      * Retrieves a collection from the database.
      * @param collectionName - Name of the collection.
@@ -59,15 +103,18 @@ export declare class K2DB {
      * @param limit - Maximum number of documents to return.
      */
     aggregate(collectionName: string, criteria: any[], skip?: number, limit?: number): Promise<BaseDocument[]>;
+    /**
+     * Ensures an aggregation pipeline excludes soft-deleted documents for the root
+     * collection and any joined collections ($lookup, $unionWith, $graphLookup, $facet).
+     */
+    private static enforceNoDeletedInPipeline;
     /**
      * Creates a new document in the collection.
      * @param collectionName - Name of the collection.
      * @param owner - Owner of the document.
      * @param data - Data to insert.
      */
-    create(collectionName: string, owner: string, data: Partial<BaseDocument>): Promise<{
-        id: string;
-    }>;
+    create(collectionName: string, owner: string, data: Partial<BaseDocument>): Promise<CreateResult>;
     /**
      * Updates multiple documents based on criteria.
      * Can either replace the documents or patch them.
@@ -75,9 +122,7 @@ export declare class K2DB {
      * @param criteria - Update criteria.
      * @param values - Values to update or replace with.
      */
-    updateAll(collectionName: string, criteria: any, values: Partial<BaseDocument>): Promise<{
-        updated: number;
-    }>;
+    updateAll(collectionName: string, criteria: any, values: Partial<BaseDocument>): Promise<UpdateResult>;
     /**
      * Updates a single document by UUID.
      * Can either replace the document or patch it.
@@ -86,62 +131,62 @@ export declare class K2DB {
      * @param data - Data to update or replace with.
      * @param replace - If true, replaces the entire document (PUT), otherwise patches (PATCH).
      */
-    update(collectionName: string, id: string, data: Partial<BaseDocument>, replace?: boolean): Promise<{
-        updated: number;
-    }>;
+    update(collectionName: string, id: string, data: Partial<BaseDocument>, replace?: boolean): Promise<UpdateResult>;
     /**
      * Removes (soft deletes) multiple documents based on criteria.
      * @param collectionName - Name of the collection.
      * @param criteria - Removal criteria.
      */
-    deleteAll(collectionName: string, criteria: any): Promise<{
-        deleted: number;
-    }>;
+    deleteAll(collectionName: string, criteria: any): Promise<DeleteResult>;
     /**
      * Removes (soft deletes) a single document by UUID.
      * @param collectionName - Name of the collection.
      * @param id - UUID of the document.
      */
-    delete(collectionName: string, id: string): Promise<{
-        deleted: number;
-    }>;
+    delete(collectionName: string, id: string): Promise<DeleteResult>;
     /**
      * Permanently deletes a document that has been soft-deleted.
      * @param collectionName - Name of the collection.
      * @param id - UUID of the document.
      */
-    purge(collectionName: string, id: string): Promise<{
-        id: string;
-    }>;
+    purge(collectionName: string, id: string): Promise<PurgeResult>;
     /**
      * Restores a soft-deleted document.
      * @param collectionName - Name of the collection.
      * @param criteria - Criteria to identify the document.
      */
-    restore(collectionName: string, criteria: any): Promise<{
-        status: string;
-        modified: number;
-    }>;
+    restore(collectionName: string, criteria: any): Promise<RestoreResult>;
     /**
      * Counts documents based on criteria.
      * @param collectionName - Name of the collection.
      * @param criteria - Counting criteria.
      */
-    count(collectionName: string, criteria: any): Promise<{
-        count: number;
-    }>;
+    count(collectionName: string, criteria: any): Promise<CountResult>;
     /**
      * Drops an entire collection.
      * @param collectionName - Name of the collection.
      */
-    drop(collectionName: string): Promise<{
-        status: string;
-    }>;
+    drop(collectionName: string): Promise<DropResult>;
     /**
      * Sanitizes aggregation criteria.
      * @param criteria - Aggregation stage criteria.
      */
     private static sanitiseCriteria;
+    /** Strip any user-provided fields that start with '_' (reserved). */
+    private static stripReservedFields;
+    /**
+     * Run an async DB operation with timing, slow logging, and hooks.
+     */
+    private runTimed;
+    /**
+     * Ensure commonly needed indexes exist.
+     */
+    ensureIndexes(collectionName: string, opts?: {
+        uuidUnique?: boolean;
+        uuidPartialUnique?: boolean;
+        ownerIndex?: boolean;
+        deletedIndex?: boolean;
+    }): Promise<void>;
     /**
      * Optional: Executes a transaction with the provided operations.
      * @param operations - A function that performs operations within a transaction session.
@@ -182,4 +227,35 @@ export declare class K2DB {
      * @returns A normalized error of type `Error`.
      */
     private normalizeError;
+    /** Name of the history collection for a given collection. */
+    private historyName;
+    /** Register a Zod schema for a collection. */
+    setSchema(collectionName: string, schema: ZodTypeAny, options?: {
+        mode?: "strict" | "strip" | "passthrough";
+    }): void;
+    /** Clear a collection's schema. */
+    clearSchema(collectionName: string): void;
+    /** Clear all schemas. */
+    clearSchemas(): void;
+    /** Apply registered schema (if any) to data. For updates, partial=true allows partial input. */
+    private applySchema;
+    /** Get the history collection. */
+    private getHistoryCollection;
+    /** Ensure indexes for history tracking. */
+    ensureHistoryIndexes(collectionName: string): Promise<void>;
+    /** Compute the next version number for a document. */
+    private nextVersion;
+    /** Save a snapshot of the current document into the history collection. */
+    private snapshotCurrent;
+    /**
+     * Update a document and keep the previous version in a history collection.
+     * If maxVersions is provided, prunes oldest snapshots beyond that number.
+     */
+    updateVersioned(collectionName: string, id: string, data: Partial<BaseDocument>, replace?: boolean, maxVersions?: number): Promise<VersionedUpdateResult[]>;
+    /** List versions (latest first). */
+    listVersions(collectionName: string, id: string, skip?: number, limit?: number): Promise<VersionInfo[]>;
+    /** Revert the current document to a specific historical version (preserves metadata). */
+    revertToVersion(collectionName: string, id: string, version: number): Promise<{
+        updated: number;
+    }>;
 }