@frogfish/k2db 2.0.6 → 3.0.1

package/README.md

@@ -23,9 +23,10 @@ Where it fits in the stack
 
 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.
+- Connection reuse: Create and reuse `K2DB` instances.
+  - The underlying MongoDB connection pool is shared across `K2DB` instances created with the same cluster/auth settings (hosts/user/password/authSource/replicaset).
+  - This means you can safely keep one `K2DB` instance per logical database name (`name`) without creating a new TCP pool per database.
+  - `release()` is ref-counted: it only closes the shared pool when the last instance releases it.
 - Example (AWS Lambda):
   ```ts
   import { K2DB } from "@frogfish/k2db";
@@ -38,7 +39,24 @@ Deployment tips (Nomad, Lambda, etc.)
     return { statusCode: 200, body: JSON.stringify(res) };
   };
   ```
-- Pooling and timeouts: The driver manages a small pool by default.
+  If you serve multiple logical databases (multi-project / multi-tenant), cache `K2DB` by database name. Instances will still share a single underlying connection pool:
+
+  ```ts
+  import { K2DB } from "@frogfish/k2db";
+
+  const base = { hosts: [{ host: "cluster0.example.mongodb.net" }], user: process.env.DB_USER, password: process.env.DB_PASS };
+  const byName = new Map<string, K2DB>();
+
+  function dbFor(name: string) {
+    let db = byName.get(name);
+    if (!db) {
+      db = new K2DB({ ...base, name });
+      byName.set(name, db);
+    }
+    return db;
+  }
+  ```
+- Pooling and timeouts: The MongoDB driver manages a small pool by default, and k2db reuses that pool across `K2DB` instances that share cluster/auth config.
   - 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.
@@ -90,10 +108,11 @@ Config
 import { K2DB } from "@frogfish/k2db";
 
 const db = new K2DB({
-  name: "mydb",
+  name: "mydb", // logical database name; instances with the same hosts/auth share one connection pool
   hosts: [{ host: "cluster0.example.mongodb.net" }], // SRV if single host without port
   user: process.env.DB_USER,
   password: process.env.DB_PASS,
+  authSource: process.env.DB_AUTH_SOURCE, // optional (defaults to "admin" when user+password provided)
   slowQueryMs: 300,
   hooks: {
     beforeQuery: (op, d) => {},
@@ -107,7 +126,19 @@ await db.ensureIndexes("myCollection");
 
 Environment loader
 ```ts
-const conf = K2DB.fromEnv(); // K2DB_NAME, K2DB_HOSTS, K2DB_USER, K2DB_PASSWORD, K2DB_REPLICASET, K2DB_SLOW_MS
+const conf = K2DB.fromEnv(); // K2DB_NAME (logical db), K2DB_HOSTS, K2DB_USER, K2DB_PASSWORD, K2DB_AUTH_SOURCE, K2DB_REPLICASET, K2DB_SLOW_MS
+```
+
+Testing
+
+If you run many test suites in a single Node process and want to fully tear down shared MongoDB pools between suites, you can use the test helper:
+
+```ts
+import { resetSharedMongoClientsForTests } from "@frogfish/k2db";
+
+afterAll(async () => {
+  await resetSharedMongoClientsForTests();
+});
 ```
 
 Tips
@@ -168,6 +199,7 @@ export K2DB_NAME=mydb
 export K2DB_HOSTS=cluster0.xxxxxx.mongodb.net
 export K2DB_USER=your_user
 export K2DB_PASSWORD=your_pass
+export K2DB_AUTH_SOURCE=admin
 node hello.mjs
 ```
 ```ts
@@ -194,7 +226,7 @@ const db = new K2DB({
   password: process.env.DB_PASS,
 });
 
-await db.init();
+await db.init(); // safe to call multiple times; concurrent calls are deduped
 await db.ensureIndexes("hello"); // unique _uuid among non-deleted, plus helpful indexes
 
 // Create a document (owner is required)
@@ -295,3 +327,21 @@ Returns by method
   - `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 Crockford 32
+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') 

package/{dist/data.d.ts → data.d.ts}

@@ -1,4 +1,5 @@
-import type { K2DB, BaseDocument, CreateResult, UpdateResult, DeleteResult, RestoreResult, CountResult, DropResult, VersionedUpdateResult, VersionInfo } from "./db.js";
+import { K2DB } from "./db.js";
+import type { BaseDocument, CreateResult, UpdateResult, DeleteResult, RestoreResult, CountResult, DropResult, VersionedUpdateResult, VersionInfo } from "./db.js";
 export declare class K2Data {
     private db;
     private owner;
@@ -100,4 +101,5 @@ export declare class K2Data {
     isHealthy(): Promise<boolean>;
 }
 export { K2DB } from "./db.js";
+export declare const isK2ID: (id: string) => boolean;
 export type { DatabaseConfig, BaseDocument, CreateResult, UpdateResult, DeleteResult, RestoreResult, CountResult, DropResult, VersionedUpdateResult, VersionInfo, } from "./db.js";

package/{dist/data.js → data.js}

@@ -1,3 +1,4 @@
+import { K2DB } from "./db.js";
 export class K2Data {
     db;
     owner;
@@ -148,3 +149,4 @@ export class K2Data {
 }
 // Re-export K2DB (runtime) and types from the root entry
 export { K2DB } from "./db.js";
+export const isK2ID = (id) => K2DB.isK2ID(id);

package/{dist/db.d.ts → db.d.ts}

@@ -1,5 +1,12 @@
 import { ObjectId } from "mongodb";
 import { ZodTypeAny } from "zod";
+/**
+ * Test helper: fully reset the shared MongoClient pool.
+ *
+ * Not for production usage; intended for test runners to clean up
+ * between suites without restarting the process.
+ */
+export declare function resetSharedMongoClientsForTests(): Promise<void>;
 export interface HostConfig {
     host: string;
     port?: number;
@@ -8,6 +15,7 @@ export interface DatabaseConfig {
     name: string;
     user?: string;
     password?: string;
+    authSource?: string;
     hosts?: HostConfig[];
     replicaset?: string;
     slowQueryMs?: number;
@@ -63,6 +71,9 @@ export declare class K2DB {
     private conf;
     private db;
     private connection;
+    private clientKey?;
+    private initialized;
+    private initPromise?;
     private schemas;
     constructor(conf: DatabaseConfig);
     /**
@@ -183,8 +194,16 @@ export declare class K2DB {
      * @param criteria - Aggregation stage criteria.
      */
     private static sanitiseCriteria;
+    /** Recursively uppercases any values for fields named `_uuid` within a query object. */
+    private static normalizeCriteriaIds;
+    /** Uppercase helper for `_uuid` field supporting operators like $in/$nin/$eq/$ne and arrays. */
+    private static normalizeUuidField;
     /** Strip any user-provided fields that start with '_' (reserved). */
     private static stripReservedFields;
+    /** True if string matches K2 ID format (Crockford Base32, 8-4-4-4-6, uppercase). */
+    static isK2ID(id: string): boolean;
+    /** Uppercase incoming IDs for case-insensitive lookups. */
+    private static normalizeId;
     /**
      * Run an async DB operation with timing, slow logging, and hooks.
      */
@@ -232,12 +251,6 @@ export declare class K2DB {
      * Optional: Checks the health of the database connection.
      */
     isHealthy(): Promise<boolean>;
-    /**
-     * Utility to normalize the error type.
-     * @param err - The caught error of type `unknown`.
-     * @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. */