@frogfish/k2db 2.0.3 → 2.0.7

package/README.md

@@ -295,3 +295,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
+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/README.md

@@ -295,3 +295,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
+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

@@ -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

@@ -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

@@ -47,6 +47,9 @@ export interface DropResult {
 export interface PurgeResult {
     id: string;
 }
+export interface PurgeManyResult {
+    purged: number;
+}
 export interface VersionedUpdateResult {
     updated: number;
     versionSaved: number;
@@ -150,6 +153,14 @@ export declare class K2DB {
      * @param id - UUID of the document.
      */
     purge(collectionName: string, id: string): Promise<PurgeResult>;
+    /**
+     * Permanently deletes all documents that are soft-deleted and whose _updated
+     * timestamp is older than the provided threshold (in milliseconds ago).
+     * @param collectionName - Name of the collection.
+     * @param olderThanMs - Age threshold in milliseconds; documents with
+     *                      `_updated <= (Date.now() - olderThanMs)` will be purged.
+     */
+    purgeDeletedOlderThan(collectionName: string, olderThanMs: number): Promise<PurgeManyResult>;
     /**
      * Restores a soft-deleted document.
      * @param collectionName - Name of the collection.
@@ -172,8 +183,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.
      */

package/dist/db.js

@@ -1,10 +1,62 @@
 // src/db.ts
 import { K2Error, ServiceError } from "@frogfish/k2error"; // Keep the existing error structure
 import { MongoClient, } from "mongodb";
-import { v4 as uuidv4 } from "uuid";
+import { randomBytes } from "crypto";
 import debugLib from "debug";
 import { z } from "zod";
 const debug = debugLib("k2:db");
+// Crockford Base32 alphabet (no I, L, O, U)
+const CROCKFORD32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+/**
+ * Generates a UUIDv7 (time-ordered) and encodes it as Crockford Base32 with hyphens.
+ * Format: 26 base32 chars grouped as 8-4-4-4-6 (total 26)
+ */
+function uuidv7Base32Hyphenated() {
+    // 1) Build UUIDv7 bytes
+    // Layout per RFC: time_low(32) | time_mid(16) | time_hi_and_version(16) | clock_seq(16) | node(48)
+    // Encode 60-bit ms timestamp across time_* fields, version 7, RFC4122 variant in clock_seq_hi.
+    const ts = BigInt(Date.now()); // milliseconds
+    const timeLow = Number((ts >> 28n) & 0xffffffffn);
+    const timeMid = Number((ts >> 12n) & 0xffffn);
+    const timeHi = Number(ts & 0xfffn); // lower 12 bits
+    const bytes = new Uint8Array(16);
+    // time_low (big-endian)
+    bytes[0] = (timeLow >>> 24) & 0xff;
+    bytes[1] = (timeLow >>> 16) & 0xff;
+    bytes[2] = (timeLow >>> 8) & 0xff;
+    bytes[3] = timeLow & 0xff;
+    // time_mid (big-endian)
+    bytes[4] = (timeMid >>> 8) & 0xff;
+    bytes[5] = timeMid & 0xff;
+    // time_high_and_version: version 7 in high nibble + top 4 bits of timeHi
+    bytes[6] = 0x70 | ((timeHi >>> 8) & 0x0f); // 0x7- version
+    bytes[7] = timeHi & 0xff;
+    // clock_seq + node: 8 random bytes; set RFC4122 variant (10xxxxxx)
+    const rnd = randomBytes(8);
+    bytes.set(rnd, 8);
+    bytes[8] = (bytes[8] & 0x3f) | 0x80; // set variant 10xxxxxx
+    // 2) Encode as Crockford Base32 (26 chars). 128 bits -> 26*5 bits (pad 2 high bits)
+    let value = 0n;
+    for (let i = 0; i < 16; i++) {
+        value = (value << 8n) | BigInt(bytes[i]);
+    }
+    value <<= 2n; // pad to 130 bits so we can take 26 groups cleanly
+    let encoded = "";
+    for (let i = 25; i >= 0; i--) {
+        const idx = Number((value >> BigInt(i * 5)) & 0x1fn);
+        encoded += CROCKFORD32[idx];
+    }
+    // 3) Insert hyphens in groups: 8-4-4-4-6
+    return (encoded.slice(0, 8) +
+        "-" +
+        encoded.slice(8, 12) +
+        "-" +
+        encoded.slice(12, 16) +
+        "-" +
+        encoded.slice(16, 20) +
+        "-" +
+        encoded.slice(20));
+}
 export class K2DB {
     conf;
     db;
@@ -110,8 +162,9 @@ export class K2DB {
         }
     }
     async get(collectionName, uuid) {
+        const id = K2DB.normalizeId(uuid);
         const res = await this.findOne(collectionName, {
-            _uuid: uuid,
+            _uuid: id,
             _deleted: { $ne: true },
         });
         if (!res) {
@@ -130,8 +183,9 @@ export class K2DB {
         const collection = await this.getCollection(collectionName);
         const projection = {};
         // Exclude soft-deleted documents by default unless caller specifies otherwise
+        const normalizedCriteria = K2DB.normalizeCriteriaIds(criteria || {});
         const query = {
-            ...criteria,
+            ...normalizedCriteria,
             ...(criteria && Object.prototype.hasOwnProperty.call(criteria, "_deleted")
                 ? {}
                 : { _deleted: { $ne: true } }),
@@ -164,7 +218,8 @@ export 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 || {}) };
+        let criteria = { ...(filter || {}) };
+        criteria = K2DB.normalizeCriteriaIds(criteria);
         // Handle the _deleted field if params specify not to include deleted documents
         if (!params?.includeDeleted && !Object.prototype.hasOwnProperty.call(criteria, "_deleted")) {
             if (params?.deleted === true) {
@@ -358,8 +413,8 @@ export class K2DB {
         }
         const collection = await this.getCollection(collectionName);
         const timestamp = Date.now();
-        // Generate a new UUID
-        const newUuid = uuidv4();
+        // Generate a new UUIDv7 encoded as Crockford Base32 with hyphens
+        const newUuid = uuidv7Base32Hyphenated();
         // Remove reserved fields from user data, then validate/transform via schema if present
         const safeData = K2DB.stripReservedFields(data);
         const validated = this.applySchema(collectionName, safeData, /*partial*/ false);
@@ -398,9 +453,20 @@ export class K2DB {
         this.validateCollectionName(collectionName);
         const collection = await this.getCollection(collectionName);
         debug(`Updating ${collectionName} with criteria: ${JSON.stringify(criteria)}`);
+        // Preserve intent to set _deleted during internal soft-delete operations.
+        // stripReservedFields removes underscore-prefixed keys (by design) to protect
+        // internal fields from user updates. However, deleteAll() legitimately passes
+        // {_deleted: true}. Capture and restore it here.
+        const deletedFlag = Object.prototype.hasOwnProperty.call(values, "_deleted")
+            ? values._deleted
+            : undefined;
         values = K2DB.stripReservedFields(values);
         values = this.applySchema(collectionName, values, /*partial*/ true);
         values._updated = Date.now();
+        if (deletedFlag !== undefined) {
+            values._deleted = deletedFlag;
+        }
+        criteria = K2DB.normalizeCriteriaIds(criteria || {});
         criteria = {
             ...criteria,
             _deleted: { $ne: true },
@@ -424,6 +490,7 @@ export class K2DB {
      * @param replace - If true, replaces the entire document (PUT), otherwise patches (PATCH).
      */
     async update(collectionName, id, data, replace = false) {
+        id = K2DB.normalizeId(id);
         this.validateCollectionName(collectionName);
         const collection = await this.getCollection(collectionName);
         data = K2DB.stripReservedFields(data);
@@ -489,6 +556,7 @@ export class K2DB {
      * @param id - UUID of the document.
      */
     async delete(collectionName, id) {
+        id = K2DB.normalizeId(id);
         try {
             // Call deleteAll to soft delete the document by UUID
             const result = await this.deleteAll(collectionName, { _uuid: id });
@@ -507,6 +575,10 @@ export class K2DB {
             }
         }
         catch (err) {
+            // Preserve existing K2Error classifications (e.g., NOT_FOUND)
+            if (err instanceof K2Error) {
+                throw err;
+            }
             throw new K2Error(ServiceError.SYSTEM_ERROR, "Error removing object from collection", "sys_mdb_remove_upd", this.normalizeError(err));
         }
     }
@@ -516,6 +588,7 @@ export class K2DB {
      * @param id - UUID of the document.
      */
     async purge(collectionName, id) {
+        id = K2DB.normalizeId(id);
         const collection = await this.getCollection(collectionName);
         try {
             const item = await this.runTimed("findOne", { collectionName, _uuid: id, _deleted: true }, async () => await collection.findOne({
@@ -535,6 +608,31 @@ export class K2DB {
             throw new K2Error(ServiceError.SYSTEM_ERROR, `Error purging item with id: ${id}`, "sys_mdb_pg", this.normalizeError(err));
         }
     }
+    /**
+     * Permanently deletes all documents that are soft-deleted and whose _updated
+     * timestamp is older than the provided threshold (in milliseconds ago).
+     * @param collectionName - Name of the collection.
+     * @param olderThanMs - Age threshold in milliseconds; documents with
+     *                      `_updated <= (Date.now() - olderThanMs)` will be purged.
+     */
+    async purgeDeletedOlderThan(collectionName, olderThanMs) {
+        this.validateCollectionName(collectionName);
+        if (typeof olderThanMs !== 'number' || !isFinite(olderThanMs) || olderThanMs < 0) {
+            throw new K2Error(ServiceError.BAD_REQUEST, 'olderThanMs must be a non-negative number', 'sys_mdb_purge_older_invalid');
+        }
+        const collection = await this.getCollection(collectionName);
+        const cutoff = Date.now() - olderThanMs;
+        try {
+            const res = await this.runTimed('deleteMany', { collectionName, olderThanMs, cutoff }, async () => await collection.deleteMany({
+                _deleted: true,
+                _updated: { $lte: cutoff },
+            }));
+            return { purged: res.deletedCount ?? 0 };
+        }
+        catch (err) {
+            throw new K2Error(ServiceError.SYSTEM_ERROR, 'Error purging deleted items by age', 'sys_mdb_purge_older', this.normalizeError(err));
+        }
+    }
     /**
      * Restores a soft-deleted document.
      * @param collectionName - Name of the collection.
@@ -542,10 +640,12 @@ export class K2DB {
      */
     async restore(collectionName, criteria) {
         const collection = await this.getCollection(collectionName);
-        const query = { ...(criteria || {}), _deleted: true };
+        const crit = K2DB.normalizeCriteriaIds(criteria || {});
+        const query = { ...crit, _deleted: true };
         try {
             const res = await this.runTimed("updateMany", { collectionName, query }, async () => await collection.updateMany(query, {
-                $set: { _deleted: false },
+                // Restoring is a data change: flip _deleted and bump _updated
+                $set: { _deleted: false, _updated: Date.now() },
             }));
             return { status: "restored", modified: res.modifiedCount };
         }
@@ -561,8 +661,9 @@ export class K2DB {
     async count(collectionName, criteria) {
         const collection = await this.getCollection(collectionName);
         try {
+            const norm = K2DB.normalizeCriteriaIds(criteria || {});
             const query = {
-                ...criteria,
+                ...norm,
                 ...(criteria && Object.prototype.hasOwnProperty.call(criteria, "_deleted")
                     ? {}
                     : { _deleted: { $ne: true } }),
@@ -594,6 +695,8 @@ export class K2DB {
      */
     static sanitiseCriteria(criteria) {
         if (criteria.$match) {
+            // Normalize any _uuid values in the match object to uppercase
+            criteria.$match = K2DB.normalizeCriteriaIds(criteria.$match);
             for (const key of Object.keys(criteria.$match)) {
                 if (typeof criteria.$match[key] !== "string") {
                     criteria.$match[key] = K2DB.sanitiseCriteria({
@@ -609,6 +712,45 @@ export class K2DB {
         }
         return criteria;
     }
+    /** Recursively uppercases any values for fields named `_uuid` within a query object. */
+    static normalizeCriteriaIds(obj) {
+        if (!obj || typeof obj !== "object")
+            return obj;
+        if (Array.isArray(obj))
+            return obj.map((v) => K2DB.normalizeCriteriaIds(v));
+        const out = Array.isArray(obj) ? [] : { ...obj };
+        for (const [k, v] of Object.entries(obj)) {
+            if (k === "_uuid") {
+                out[k] = K2DB.normalizeUuidField(v);
+            }
+            else if (v && typeof v === "object") {
+                out[k] = K2DB.normalizeCriteriaIds(v);
+            }
+            else if (Array.isArray(v)) {
+                out[k] = v.map((x) => K2DB.normalizeCriteriaIds(x));
+            }
+            else {
+                out[k] = v;
+            }
+        }
+        return out;
+    }
+    /** Uppercase helper for `_uuid` field supporting operators like $in/$nin/$eq/$ne and arrays. */
+    static normalizeUuidField(val) {
+        if (typeof val === "string")
+            return val.toUpperCase();
+        if (Array.isArray(val))
+            return val.map((x) => (typeof x === "string" ? x.toUpperCase() : x));
+        if (val && typeof val === "object") {
+            const out = { ...val };
+            for (const op of ["$in", "$nin", "$eq", "$ne", "$all"]) {
+                if (op in out)
+                    out[op] = K2DB.normalizeUuidField(out[op]);
+            }
+            return out;
+        }
+        return val;
+    }
     /** Strip any user-provided fields that start with '_' (reserved). */
     static stripReservedFields(obj) {
         const out = {};
@@ -618,6 +760,18 @@ export class K2DB {
         }
         return out;
     }
+    /** True if string matches K2 ID format (Crockford Base32, 8-4-4-4-6, uppercase). */
+    static isK2ID(id) {
+        if (typeof id !== "string")
+            return false;
+        const s = id.trim().toUpperCase();
+        const CROCK_RE = /^[0-9A-HJKMNPQRSTVWXYZ]{8}-[0-9A-HJKMNPQRSTVWXYZ]{4}-[0-9A-HJKMNPQRSTVWXYZ]{4}-[0-9A-HJKMNPQRSTVWXYZ]{4}-[0-9A-HJKMNPQRSTVWXYZ]{6}$/;
+        return CROCK_RE.test(s);
+    }
+    /** Uppercase incoming IDs for case-insensitive lookups. */
+    static normalizeId(id) {
+        return id.toUpperCase();
+    }
     /**
      * Run an async DB operation with timing, slow logging, and hooks.
      */
@@ -656,7 +810,9 @@ export class K2DB {
         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 } } });
+            // Use a compound unique index to ensure at most one non-deleted document per _uuid
+            // without relying on partialFilterExpression (which may be limited in some environments).
+            await collection.createIndex({ _uuid: 1, _deleted: 1 }, { unique: true });
         }
         else if (uuidUnique) {
             await collection.createIndex({ _uuid: 1 }, { unique: true });
@@ -820,6 +976,7 @@ export class K2DB {
     }
     /** Compute the next version number for a document. */
     async nextVersion(collectionName, id) {
+        id = K2DB.normalizeId(id);
         const hc = await this.getHistoryCollection(collectionName);
         const last = await hc
             .find({ _uuid: id })
@@ -846,6 +1003,7 @@ export class K2DB {
      * If maxVersions is provided, prunes oldest snapshots beyond that number.
      */
     async updateVersioned(collectionName, id, data, replace = false, maxVersions) {
+        id = K2DB.normalizeId(id);
         // Get current doc (excludes deleted) and snapshot it
         const current = await this.get(collectionName, id);
         await this.ensureHistoryIndexes(collectionName);
@@ -874,6 +1032,7 @@ export class K2DB {
     }
     /** List versions (latest first). */
     async listVersions(collectionName, id, skip = 0, limit = 20) {
+        id = K2DB.normalizeId(id);
         const hc = await this.getHistoryCollection(collectionName);
         const rows = await hc
             .find({ _uuid: id })
@@ -886,6 +1045,7 @@ export class K2DB {
     }
     /** Revert the current document to a specific historical version (preserves metadata). */
     async revertToVersion(collectionName, id, version) {
+        id = K2DB.normalizeId(id);
         const hc = await this.getHistoryCollection(collectionName);
         const row = await hc.findOne({ _uuid: id, _v: version });
         if (!row) {

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frogfish/k2db",
-  "version": "2.0.3",
+  "version": "2.0.7",
   "description": "A data handling library for K2 applications.",
   "type": "module",
   "main": "data.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frogfish/k2db",
-  "version": "2.0.3",
+  "version": "2.0.7",
   "description": "A data handling library for K2 applications.",
   "main": "./dist/data.js",
   "types": "./dist/data.d.ts",