axiodb 12.10.26 → 13.0.0

package/lib/Services/Index/IndexCache.service.d.ts

@@ -6,6 +6,13 @@ interface IndexData {
     indexEntries: {
         [value: string]: string[];
     };
+    /**
+     * Sorted, de-duplicated numeric values for this field - enables O(log U + M)
+     * range queries ($gt/$gte/$lt/$lte) instead of a full collection scan.
+     * Optional for backward compatibility with indexes written before range
+     * support existed; those are lazily backfilled on first insert/delete.
+     */
+    sortedValues?: number[];
 }
 /**
  * In-memory cache for index data
@@ -19,23 +26,44 @@ interface IndexData {
  *
  * @example
  * ```typescript
- * const indexCache = new IndexCache('/path/to/collection');
+ * const indexCache = IndexCache.getInstance('/path/to/collection');
  * await indexCache.loadAllIndexes();  // Eager load
  * const indexData = await indexCache.getIndex('email');  // O(1) memory access
  * ```
  */
 export declare class IndexCache {
+    private static instances;
     private cache;
     private readonly indexFolderPath;
     private readonly indexMetaPath;
     private readonly fileManager;
     private readonly converter;
-    private locks;
+    private lockChains;
     private cleanupInterval;
     private static readonly MIN_TTL_MS;
     private static readonly MAX_TTL_MS;
     private static readonly CLEANUP_INTERVAL_MS;
-    constructor(collectionPath: string);
+    private constructor();
+    /**
+     * Returns the shared IndexCache for a collection path, creating it on first use.
+     * All index services (Insert/Read/Delete/Collection) must go through this instead of
+     * constructing their own instance, otherwise locking and caching are per-call and
+     * provide no real coordination.
+     *
+     * @param collectionPath - Absolute path of the collection this cache belongs to
+     */
+    static getInstance(collectionPath: string): IndexCache;
+    /**
+     * Releases the shared IndexCache for a collection path (e.g. when the collection
+     * itself is deleted), stopping its cleanup timer and dropping it from the registry.
+     *
+     * @param collectionPath - Absolute path of the collection whose cache should be released
+     */
+    static releaseInstance(collectionPath: string): void;
+    /**
+     * Stops the cleanup timer and clears cached state. Called via releaseInstance().
+     */
+    dispose(): void;
     /**
      * Generates a random TTL between 5-15 minutes
      * Randomization prevents cache stampede (thundering herd problem)
@@ -91,20 +119,19 @@ export declare class IndexCache {
      */
     invalidateAll(): Promise<void>;
     /**
-     * Simple lock acquisition for thread safety
-     * Waits if another operation is currently holding the lock
+     * Acquires a per-field mutex, queuing behind any in-flight holder for the same key.
+     *
+     * Implemented as a chained promise queue: each call captures the current tail of the
+     * chain, awaits it (so it truly blocks until every earlier holder has released), then
+     * appends its own pending promise as the new tail. The caller MUST invoke the returned
+     * release function exactly once (typically in a `finally` block) to hand the lock to
+     * the next queued waiter.
      *
      * @param key - The lock key (typically field name)
+     * @returns A release function that unblocks the next waiter for this key
      * @private
      */
     private acquireLock;
-    /**
-     * Releases the lock for a specific key
-     *
-     * @param key - The lock key to release
-     * @private
-     */
-    private releaseLock;
     /**
      * Gets current cache statistics for monitoring
      *

package/lib/Services/Index/IndexCache.service.js

@@ -30,7 +30,7 @@ const Converter_helper_1 = __importDefault(require("../../Helper/Converter.helpe
  *
  * @example
  * ```typescript
- * const indexCache = new IndexCache('/path/to/collection');
+ * const indexCache = IndexCache.getInstance('/path/to/collection');
  * await indexCache.loadAllIndexes();  // Eager load
  * const indexData = await indexCache.getIndex('email');  // O(1) memory access
  * ```
@@ -43,9 +43,49 @@ class IndexCache {
         this.indexMetaPath = `${this.indexFolderPath}/index.meta.json`;
         this.fileManager = new FileManager_1.default();
         this.converter = new Converter_helper_1.default();
-        this.locks = new Map();
+        this.lockChains = new Map();
         this.startCleanupInterval();
     }
+    /**
+     * Returns the shared IndexCache for a collection path, creating it on first use.
+     * All index services (Insert/Read/Delete/Collection) must go through this instead of
+     * constructing their own instance, otherwise locking and caching are per-call and
+     * provide no real coordination.
+     *
+     * @param collectionPath - Absolute path of the collection this cache belongs to
+     */
+    static getInstance(collectionPath) {
+        let instance = IndexCache.instances.get(collectionPath);
+        if (!instance) {
+            instance = new IndexCache(collectionPath);
+            IndexCache.instances.set(collectionPath, instance);
+        }
+        return instance;
+    }
+    /**
+     * Releases the shared IndexCache for a collection path (e.g. when the collection
+     * itself is deleted), stopping its cleanup timer and dropping it from the registry.
+     *
+     * @param collectionPath - Absolute path of the collection whose cache should be released
+     */
+    static releaseInstance(collectionPath) {
+        const instance = IndexCache.instances.get(collectionPath);
+        if (instance) {
+            instance.dispose();
+            IndexCache.instances.delete(collectionPath);
+        }
+    }
+    /**
+     * Stops the cleanup timer and clears cached state. Called via releaseInstance().
+     */
+    dispose() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        this.cache.clear();
+        this.lockChains.clear();
+    }
     /**
      * Generates a random TTL between 5-15 minutes
      * Randomization prevents cache stampede (thundering herd problem)
@@ -193,7 +233,7 @@ class IndexCache {
     updateIndex(fieldName, indexData) {
         return __awaiter(this, void 0, void 0, function* () {
             // Acquire lock for this field to prevent concurrent writes
-            yield this.acquireLock(fieldName);
+            const release = yield this.acquireLock(fieldName);
             try {
                 const indexPath = `${this.indexFolderPath}/${fieldName}${Keys_1.General.DBMS_File_EXT}`;
                 // Write to disk first for durability (disk = source of truth)
@@ -211,7 +251,7 @@ class IndexCache {
                 return true;
             }
             finally {
-                this.releaseLock(fieldName);
+                release();
             }
         });
     }
@@ -237,35 +277,31 @@ class IndexCache {
         });
     }
     /**
-     * Simple lock acquisition for thread safety
-     * Waits if another operation is currently holding the lock
+     * Acquires a per-field mutex, queuing behind any in-flight holder for the same key.
+     *
+     * Implemented as a chained promise queue: each call captures the current tail of the
+     * chain, awaits it (so it truly blocks until every earlier holder has released), then
+     * appends its own pending promise as the new tail. The caller MUST invoke the returned
+     * release function exactly once (typically in a `finally` block) to hand the lock to
+     * the next queued waiter.
      *
      * @param key - The lock key (typically field name)
+     * @returns A release function that unblocks the next waiter for this key
      * @private
      */
     acquireLock(key) {
         return __awaiter(this, void 0, void 0, function* () {
-            const existingLock = this.locks.get(key);
-            if (existingLock) {
-                yield existingLock;
-            }
-            // Create new lock promise for this operation
-            let releaseFn;
-            const lockPromise = new Promise((resolve) => {
-                releaseFn = resolve;
+            var _a;
+            const previousTail = (_a = this.lockChains.get(key)) !== null && _a !== void 0 ? _a : Promise.resolve();
+            let release;
+            const currentLock = new Promise((resolve) => {
+                release = resolve;
             });
-            this.locks.set(key, lockPromise);
+            this.lockChains.set(key, previousTail.then(() => currentLock));
+            yield previousTail;
+            return release;
         });
     }
-    /**
-     * Releases the lock for a specific key
-     *
-     * @param key - The lock key to release
-     * @private
-     */
-    releaseLock(key) {
-        this.locks.delete(key);
-    }
     /**
      * Gets current cache statistics for monitoring
      *
@@ -279,6 +315,10 @@ class IndexCache {
     }
 }
 exports.IndexCache = IndexCache;
+// One IndexCache per collection path - shared across Insert/Read/Delete/Collection
+// so the lock and the memory cache actually serialize/coordinate across operations
+// instead of each call site racing on its own private state.
+IndexCache.instances = new Map();
 // TTL constants (5-15 minutes in milliseconds)
 IndexCache.MIN_TTL_MS = 5 * 60 * 1000; // 5 minutes
 IndexCache.MAX_TTL_MS = 15 * 60 * 1000; // 15 minutes

package/lib/Services/Index/IndexCache.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"IndexCache.service.js","sourceRoot":"","sources":["../../../source/Services/Index/IndexCache.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"IndexCache.service.js","sourceRoot":"","sources":["../../../source/Services/Index/IndexCache.service.ts"],"names":[],"mappings":"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"}

package/lib/Services/Index/InsertIndex.service.js

@@ -8,15 +8,19 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 /* eslint-disable @typescript-eslint/no-explicit-any */
 const Keys_1 = require("../../config/Keys/Keys");
 const Index_service_1 = require("./Index.service");
 const IndexCache_service_1 = require("./IndexCache.service");
+const SortedIndexValues_helper_1 = __importDefault(require("../../Helper/SortedIndexValues.helper"));
 class InsertIndex extends Index_service_1.IndexManager {
     constructor(path) {
         super(path);
-        this.indexCache = new IndexCache_service_1.IndexCache(path);
+        this.indexCache = IndexCache_service_1.IndexCache.getInstance(path);
     }
     /**
    * Inserts a document identifier into one or more index files as defined by the global index meta.
@@ -75,6 +79,10 @@ class InsertIndex extends Index_service_1.IndexManager {
                         continue;
                     }
                     const fieldValue = document[indexName];
+                    // Lazily backfill sortedValues for indexes written before range support existed
+                    if (!indexData.sortedValues) {
+                        indexData.sortedValues = SortedIndexValues_helper_1.default.backfillFromKeys(Object.keys(indexData.indexEntries));
+                    }
                     // Add document to index entries
                     const alreadyhave = Object.keys(indexData.indexEntries).some(keys => keys == fieldValue);
                     if (alreadyhave) {
@@ -82,6 +90,10 @@ class InsertIndex extends Index_service_1.IndexManager {
                     }
                     else {
                         indexData.indexEntries[fieldValue] = [documentFileName];
+                        const numericValue = Number(fieldValue);
+                        if (!Number.isNaN(numericValue)) {
+                            SortedIndexValues_helper_1.default.insertSorted(indexData.sortedValues, numericValue);
+                        }
                     }
                     // Update both memory cache and disk atomically
                     const updateSuccess = yield this.indexCache.updateIndex(indexName, indexData);

package/lib/Services/Index/InsertIndex.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"InsertIndex.service.js","sourceRoot":"","sources":["../../../source/Services/Index/InsertIndex.service.ts"],"names":[],"mappings":";;;;;;;;;;;AAAA,uDAAuD;AACvD,iDAAiD;AACjD,mDAA+C;AAC/C,6DAAkD;AAElD,iBAAiC,SAAQ,4BAAY;IAGnD,YAAa,IAAY;QACvB,KAAK,CAAC,IAAI,CAAC,CAAC;QACZ,IAAI,CAAC,UAAU,GAAG,IAAI,+BAAU,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC;IAGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA4BC;IACY,aAAa,CAAC,QAAa;;YACpC,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,qBAAqB,CAAC,QAAQ,CAAC,CAAC;YAEhE,IAAI,YAAY,EAAC,CAAC;gBAElB,IAAI,YAAY,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;oBAC7B,OAAO,KAAK,CAAC;gBACf,CAAC;gBAED,IAAI,MAAM,GAAY,KAAK,CAAC;gBAC5B,KAAK,MAAM,OAAO,IAAI,YAAY,EAAE,CAAC;oBACnC,MAAM,SAAS,GAAW,OAAO,CAAC,cAAc,CAAC;oBACjD,MAAM,gBAAgB,GAAG,GAAG,QAAQ,CAAC,UAAU,GAAG,cAAO,CAAC,aAAa,EAAE,CAAC;oBAE1E,6EAA6E;oBAC7E,IAAI,SAAS,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;oBAE1D,IAAI,CAAC,SAAS,EAAE,CAAC;wBACf,iEAAiE;wBACjE,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;wBACnE,IAAI,YAAY,CAAC,MAAM,EAAE,CAAC;4BACxB,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;wBACzD,CAAC;6BAAM,CAAC;4BACN,6CAA6C;4BAC7C,SAAS;wBACX,CAAC;oBACH,CAAC;oBAED,IAAI,CAAC,SAAS,EAAE,CAAC;wBACf,SAAS;oBACX,CAAC;oBAED,MAAM,UAAU,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;oBAEvC,gCAAgC;oBAChC,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,IAAI,UAAU,CAAC,CAAC;oBACzF,IAAI,WAAW,EAAC,CAAC;wBACf,SAAS,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;oBAC5D,CAAC;yBACI,CAAC;wBACJ,SAAS,CAAC,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;oBAC1D,CAAC;oBAED,+CAA+C;oBAC/C,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;oBAC9E,MAAM,GAAG,aAAa,CAAC;gBACzB,CAAC;gBACD,OAAO,MAAM,CAAC;YAChB,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;KAAA;CAEF"}
+{"version":3,"file":"InsertIndex.service.js","sourceRoot":"","sources":["../../../source/Services/Index/InsertIndex.service.ts"],"names":[],"mappings":"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"}

package/lib/Services/Index/ReadIndex.service.d.ts

@@ -70,6 +70,37 @@ export declare class ReadIndex extends IndexManager {
      * const files = await readIndex.getFilesForPrefixQuery('name', 'John', true);
      */
     getFilesForPrefixQuery(fieldName: string, prefix: string, caseInsensitive?: boolean): Promise<string[]>;
+    /**
+     * Retrieve file paths from an index for documents whose field value falls within
+     * a numeric range ($gt/$gte/$lt/$lte).
+     *
+     * OPTIMIZED: Binary-searches the index's sorted value array for the matching bounds,
+     * then unions only the file lists for values inside that range - avoids the full
+     * collection scan that unindexed range queries require.
+     *
+     * @param fieldName - The field name to query (must have an index)
+     * @param range - Range operators to apply, e.g. `{ $gt: 25 }` or `{ $gte: 18, $lte: 65 }`
+     *
+     * @returns Promise resolving to an array of unique file paths matching the range,
+     *          or an empty array if the field has no index, the index predates range
+     *          support (not yet backfilled), or no values fall in range.
+     *
+     * @remarks
+     * - O(log U) to find the bounds + O(K) to union file lists, where U = unique indexed
+     *   values and K = unique values within the range - independent of collection size.
+     * - Only numeric values participate (matches `Searcher.matchesQuery`, which already
+     *   rejects range comparisons against non-numbers).
+     *
+     * @example
+     * // For query: { age: { $gt: 25 } }
+     * const files = await readIndex.getFilesForRangeOperator('age', { $gt: 25 });
+     */
+    getFilesForRangeOperator(fieldName: string, range: {
+        $gt?: number;
+        $gte?: number;
+        $lt?: number;
+        $lte?: number;
+    }): Promise<string[]>;
     /**
    * Finds index metadata entries that correspond to properties present on the provided document.
    *

package/lib/Services/Index/ReadIndex.service.js

@@ -8,15 +8,19 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReadIndex = void 0;
 /* eslint-disable @typescript-eslint/no-explicit-any */
 const Index_service_1 = require("./Index.service");
 const IndexCache_service_1 = require("./IndexCache.service");
+const SortedIndexValues_helper_1 = __importDefault(require("../../Helper/SortedIndexValues.helper"));
 class ReadIndex extends Index_service_1.IndexManager {
     constructor(path) {
         super(path);
-        this.indexCache = new IndexCache_service_1.IndexCache(path);
+        this.indexCache = IndexCache_service_1.IndexCache.getInstance(path);
     }
     /**
      * Retrieve file path(s) from an index that match the provided query.
@@ -147,6 +151,51 @@ class ReadIndex extends Index_service_1.IndexManager {
             return Array.from(fileSet);
         });
     }
+    /**
+     * Retrieve file paths from an index for documents whose field value falls within
+     * a numeric range ($gt/$gte/$lt/$lte).
+     *
+     * OPTIMIZED: Binary-searches the index's sorted value array for the matching bounds,
+     * then unions only the file lists for values inside that range - avoids the full
+     * collection scan that unindexed range queries require.
+     *
+     * @param fieldName - The field name to query (must have an index)
+     * @param range - Range operators to apply, e.g. `{ $gt: 25 }` or `{ $gte: 18, $lte: 65 }`
+     *
+     * @returns Promise resolving to an array of unique file paths matching the range,
+     *          or an empty array if the field has no index, the index predates range
+     *          support (not yet backfilled), or no values fall in range.
+     *
+     * @remarks
+     * - O(log U) to find the bounds + O(K) to union file lists, where U = unique indexed
+     *   values and K = unique values within the range - independent of collection size.
+     * - Only numeric values participate (matches `Searcher.matchesQuery`, which already
+     *   rejects range comparisons against non-numbers).
+     *
+     * @example
+     * // For query: { age: { $gt: 25 } }
+     * const files = await readIndex.getFilesForRangeOperator('age', { $gt: 25 });
+     */
+    getFilesForRangeOperator(fieldName, range) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const indexData = yield this.indexCache.getIndex(fieldName);
+            if (!indexData || !indexData.sortedValues || indexData.sortedValues.length === 0) {
+                return [];
+            }
+            const bounds = SortedIndexValues_helper_1.default.resolveRange(indexData.sortedValues, range);
+            if (!bounds) {
+                return [];
+            }
+            const fileSet = new Set();
+            for (let i = bounds.startIndex; i <= bounds.endIndex; i++) {
+                const files = indexData.indexEntries[indexData.sortedValues[i]];
+                if (files) {
+                    files.forEach(f => fileSet.add(f));
+                }
+            }
+            return Array.from(fileSet);
+        });
+    }
     /**
    * Finds index metadata entries that correspond to properties present on the provided document.
    *

package/lib/Services/Index/ReadIndex.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"ReadIndex.service.js","sourceRoot":"","sources":["../../../source/Services/Index/ReadIndex.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ReadIndex.service.js","sourceRoot":"","sources":["../../../source/Services/Index/ReadIndex.service.ts"],"names":[],"mappings":"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"}

package/lib/Services/Transaction/LockManager.service.d.ts

@@ -1,6 +1,7 @@
 import { ErrorInterface, SuccessInterface } from "../../config/Interfaces/Helper/response.helper.interface";
 import { LockInfo } from "../../config/Interfaces/Transaction/transaction.interface";
 export default class LockManager {
+    private static instances;
     private readonly collectionPath;
     private readonly lockDir;
     private readonly FileManager;
@@ -9,8 +10,12 @@ export default class LockManager {
     private readonly ResponseHelper;
     private readonly maxWaitTime;
     private readonly pollInterval;
-    constructor(collectionPath: string);
+    private constructor();
+    /** Returns the shared LockManager for a collection path, creating it on first use. */
+    static getInstance(collectionPath: string): LockManager;
     acquireLock(documentId: string, transactionId: string, transactionTimestamp: number): Promise<SuccessInterface | ErrorInterface>;
+    /** Builds the checksummed lock-file content; keeps format in sync with getLockOwner(). */
+    private buildLockContent;
     releaseLock(documentId: string): Promise<SuccessInterface | ErrorInterface>;
     releaseAllLocks(documentIds: string[]): Promise<void>;
     isLocked(documentId: string): Promise<boolean>;

package/lib/Services/Transaction/LockManager.service.js

@@ -29,6 +29,15 @@ class LockManager {
         this.Converter = new Converter_helper_1.default();
         this.ResponseHelper = new response_helper_1.default();
     }
+    /** Returns the shared LockManager for a collection path, creating it on first use. */
+    static getInstance(collectionPath) {
+        let instance = LockManager.instances.get(collectionPath);
+        if (!instance) {
+            instance = new LockManager(collectionPath);
+            LockManager.instances.set(collectionPath, instance);
+        }
+        return instance;
+    }
     acquireLock(documentId, transactionId, transactionTimestamp) {
         return __awaiter(this, void 0, void 0, function* () {
             try {
@@ -37,36 +46,22 @@ class LockManager {
                     yield this.FolderManager.CreateDirectory(this.lockDir);
                 }
                 const lockFilePath = `${this.lockDir}/${documentId}.lock`;
+                const lockContent = this.buildLockContent(documentId, transactionId, transactionTimestamp);
                 const startTime = Date.now();
                 while (Date.now() - startTime < this.maxWaitTime) {
-                    const fileExists = yield this.FileManager.FileExists(lockFilePath);
-                    if (!fileExists.status) {
-                        const lockInfo = {
-                            documentId,
-                            transactionId,
-                            lockType: 'WRITE',
-                            timestamp: transactionTimestamp,
-                        };
-                        const lockData = this.Converter.ToString(lockInfo);
-                        const checksum = (0, crypto_1.createHash)('sha256').update(lockData).digest('hex');
-                        const lockContent = this.Converter.ToString({ lockInfo, checksum });
-                        const writeResult = yield this.FileManager.WriteFile(lockFilePath, lockContent);
-                        if (writeResult.status) {
-                            return this.ResponseHelper.Success({ message: "Lock acquired", documentId });
-                        }
+                    // Atomic acquire-if-free - avoids the FileExists-then-WriteFile race.
+                    const acquired = yield this.FileManager.WriteFileExclusive(lockFilePath, lockContent);
+                    if (acquired.status) {
+                        return this.ResponseHelper.Success({ message: "Lock acquired", documentId });
                     }
-                    else {
-                        const lockOwner = yield this.getLockOwner(documentId);
-                        if (lockOwner) {
-                            const ownerTimestamp = lockOwner.timestamp;
-                            if (transactionTimestamp < ownerTimestamp) {
-                                yield this.sleep(this.pollInterval);
-                                continue;
-                            }
-                            else {
-                                return this.ResponseHelper.Error(`Deadlock detected: Transaction ${transactionId} aborted (Wait-Die)`);
-                            }
+                    // Wait-Die: older transactions wait, younger ones abort.
+                    const lockOwner = yield this.getLockOwner(documentId);
+                    if (lockOwner) {
+                        if (transactionTimestamp < lockOwner.timestamp) {
+                            yield this.sleep(this.pollInterval);
+                            continue;
                         }
+                        return this.ResponseHelper.Error(`Deadlock detected: Transaction ${transactionId} aborted (Wait-Die)`);
                     }
                     yield this.sleep(this.pollInterval);
                 }
@@ -77,6 +72,19 @@ class LockManager {
             }
         });
     }
+    /** Builds the checksummed lock-file content; keeps format in sync with getLockOwner(). */
+    buildLockContent(documentId, transactionId, transactionTimestamp) {
+        const lockInfo = {
+            documentId,
+            transactionId,
+            lockType: 'WRITE',
+            timestamp: transactionTimestamp,
+        };
+        const checksum = (0, crypto_1.createHash)('sha256')
+            .update(this.Converter.ToString(lockInfo))
+            .digest('hex');
+        return this.Converter.ToString({ lockInfo, checksum });
+    }
     releaseLock(documentId) {
         return __awaiter(this, void 0, void 0, function* () {
             try {
@@ -147,5 +155,7 @@ class LockManager {
         return new Promise(resolve => setTimeout(resolve, ms));
     }
 }
+// One LockManager per collection path, shared across every caller.
+LockManager.instances = new Map();
 exports.default = LockManager;
 //# sourceMappingURL=LockManager.service.js.map

package/lib/Services/Transaction/LockManager.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"LockManager.service.js","sourceRoot":"","sources":["../../../source/Services/Transaction/LockManager.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"LockManager.service.js","sourceRoot":"","sources":["../../../source/Services/Transaction/LockManager.service.ts"],"names":[],"mappings":"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"}

package/lib/Services/Transaction/Session.service.d.ts

@@ -8,14 +8,12 @@ import Transaction from "./Transaction.service";
 export default class Session {
     private readonly sessionId;
     private readonly collectionPath;
-    private readonly isEncrypted;
-    private readonly encryptionKey?;
     private readonly options;
     private readonly ResponseHelper;
     private readonly startTime;
     private isActive;
     private currentTransaction;
-    constructor(collectionPath: string, isEncrypted?: boolean, encryptionKey?: string, options?: SessionOptions);
+    constructor(collectionPath: string, options?: SessionOptions);
     /**
      * Gets the session ID
      */

package/lib/Services/Transaction/Session.service.js

@@ -21,14 +21,12 @@ const Transaction_service_1 = __importDefault(require("./Transaction.service"));
  * Supports automatic retry, timeout handling, and the withTransaction pattern.
  */
 class Session {
-    constructor(collectionPath, isEncrypted = false, encryptionKey, options = {}) {
+    constructor(collectionPath, options = {}) {
         var _a, _b, _c;
         this.isActive = true;
         this.currentTransaction = null;
         this.sessionId = new UniqueGenerator_helper_1.default(20).RandomWord(true);
         this.collectionPath = collectionPath;
-        this.isEncrypted = isEncrypted;
-        this.encryptionKey = encryptionKey;
         this.startTime = Date.now();
         this.ResponseHelper = new response_helper_1.default();
         // Default options
@@ -70,7 +68,7 @@ class Session {
         if (this.currentTransaction) {
             throw new Error("A transaction is already active in this session. Commit or rollback first.");
         }
-        this.currentTransaction = new Transaction_service_1.default(this.collectionPath, this.isEncrypted, this.encryptionKey);
+        this.currentTransaction = new Transaction_service_1.default(this.collectionPath);
         return this.currentTransaction;
     }
     /**