@frogfish/k2db 2.0.7 → 3.0.2

package/dist/README.md

@@ -1,315 +0,0 @@
-# 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`
-
-## UUID
-
-_uuid = Crockford Base32 encoded UUID V7, Uppercase, with hyphens
-
-0J4F2-H6M8Q-7RX4V-9D3TN-8K2WZ
-
-// Canonical uppercase form with hyphens
-const CROCKFORD_ID_REGEX = /^[0-9A-HJKMNP-TV-Z]{5}-[0-9A-HJKMNP-TV-Z]{5}-[0-9A-HJKMNP-TV-Z]{5}-[0-9A-HJKMNP-TV-Z]{5}-[0-9A-HJKMNP-TV-Z]{6}$/;
-
-// Example usage:
-const id = "0J4F2-H6M8Q-7RX4V-9D3TN-8K2WZ";
-console.log(CROCKFORD_ID_REGEX.test(id)); // true
-
-Usage examples:
-
-import { isK2ID, K2DB } from '@frogfish/k2db'
-isK2ID('01HZY2AB-3JKM-4NPQ-5RST-6VWXYZ')