@push.rocks/smartmongo 3.0.0 → 4.1.1

package/dist_ts/tsmdb/storage/WAL.js

@@ -0,0 +1,286 @@
+import * as plugins from '../tsmdb.plugins.js';
+/**
+ * Write-Ahead Log (WAL) for durability and crash recovery
+ *
+ * The WAL ensures durability by writing operations to a log file before
+ * they are applied to the main storage. On crash recovery, uncommitted
+ * operations can be replayed to restore the database to a consistent state.
+ */
+export class WAL {
+    walPath;
+    currentLsn = 0;
+    lastCheckpointLsn = 0;
+    entries = [];
+    isInitialized = false;
+    fs = new plugins.smartfs.SmartFs(new plugins.smartfs.SmartFsProviderNode());
+    // In-memory uncommitted entries per transaction
+    uncommittedTxns = new Map();
+    // Checkpoint interval (number of entries between checkpoints)
+    checkpointInterval = 1000;
+    constructor(walPath, options) {
+        this.walPath = walPath;
+        if (options?.checkpointInterval) {
+            this.checkpointInterval = options.checkpointInterval;
+        }
+    }
+    /**
+     * Initialize the WAL, loading existing entries and recovering if needed
+     */
+    async initialize() {
+        if (this.isInitialized) {
+            return { recoveredEntries: [] };
+        }
+        // Ensure WAL directory exists
+        const walDir = this.walPath.substring(0, this.walPath.lastIndexOf('/'));
+        if (walDir) {
+            await this.fs.directory(walDir).recursive().create();
+        }
+        // Try to load existing WAL
+        const exists = await this.fs.file(this.walPath).exists();
+        if (exists) {
+            const content = await this.fs.file(this.walPath).encoding('utf8').read();
+            const lines = content.split('\n').filter(line => line.trim());
+            for (const line of lines) {
+                try {
+                    const entry = JSON.parse(line);
+                    // Verify checksum
+                    if (this.verifyChecksum(entry)) {
+                        this.entries.push(entry);
+                        if (entry.lsn > this.currentLsn) {
+                            this.currentLsn = entry.lsn;
+                        }
+                        if (entry.operation === 'checkpoint') {
+                            this.lastCheckpointLsn = entry.lsn;
+                        }
+                    }
+                }
+                catch {
+                    // Skip corrupted entries
+                    console.warn('Skipping corrupted WAL entry');
+                }
+            }
+        }
+        this.isInitialized = true;
+        // Return entries after last checkpoint that need recovery
+        const recoveredEntries = this.entries.filter(e => e.lsn > this.lastCheckpointLsn &&
+            (e.operation === 'insert' || e.operation === 'update' || e.operation === 'delete'));
+        return { recoveredEntries };
+    }
+    /**
+     * Log an insert operation
+     */
+    async logInsert(dbName, collName, doc, txnId) {
+        return this.appendEntry({
+            operation: 'insert',
+            dbName,
+            collName,
+            documentId: doc._id.toHexString(),
+            data: this.serializeDocument(doc),
+            txnId,
+        });
+    }
+    /**
+     * Log an update operation
+     */
+    async logUpdate(dbName, collName, oldDoc, newDoc, txnId) {
+        return this.appendEntry({
+            operation: 'update',
+            dbName,
+            collName,
+            documentId: oldDoc._id.toHexString(),
+            data: this.serializeDocument(newDoc),
+            previousData: this.serializeDocument(oldDoc),
+            txnId,
+        });
+    }
+    /**
+     * Log a delete operation
+     */
+    async logDelete(dbName, collName, doc, txnId) {
+        return this.appendEntry({
+            operation: 'delete',
+            dbName,
+            collName,
+            documentId: doc._id.toHexString(),
+            previousData: this.serializeDocument(doc),
+            txnId,
+        });
+    }
+    /**
+     * Log transaction begin
+     */
+    async logBeginTransaction(txnId) {
+        this.uncommittedTxns.set(txnId, []);
+        return this.appendEntry({
+            operation: 'begin',
+            dbName: '',
+            collName: '',
+            documentId: '',
+            txnId,
+        });
+    }
+    /**
+     * Log transaction commit
+     */
+    async logCommitTransaction(txnId) {
+        this.uncommittedTxns.delete(txnId);
+        return this.appendEntry({
+            operation: 'commit',
+            dbName: '',
+            collName: '',
+            documentId: '',
+            txnId,
+        });
+    }
+    /**
+     * Log transaction abort
+     */
+    async logAbortTransaction(txnId) {
+        this.uncommittedTxns.delete(txnId);
+        return this.appendEntry({
+            operation: 'abort',
+            dbName: '',
+            collName: '',
+            documentId: '',
+            txnId,
+        });
+    }
+    /**
+     * Get entries to roll back for an aborted transaction
+     */
+    getTransactionEntries(txnId) {
+        return this.entries.filter(e => e.txnId === txnId);
+    }
+    /**
+     * Create a checkpoint - marks a consistent point in the log
+     */
+    async checkpoint() {
+        const lsn = await this.appendEntry({
+            operation: 'checkpoint',
+            dbName: '',
+            collName: '',
+            documentId: '',
+        });
+        this.lastCheckpointLsn = lsn;
+        // Truncate old entries (keep only entries after checkpoint)
+        await this.truncate();
+        return lsn;
+    }
+    /**
+     * Truncate the WAL file, removing entries before the last checkpoint
+     */
+    async truncate() {
+        // Keep entries after last checkpoint
+        const newEntries = this.entries.filter(e => e.lsn >= this.lastCheckpointLsn);
+        this.entries = newEntries;
+        // Rewrite the WAL file
+        const lines = this.entries.map(e => JSON.stringify(e)).join('\n');
+        await this.fs.file(this.walPath).encoding('utf8').write(lines);
+    }
+    /**
+     * Get current LSN
+     */
+    getCurrentLsn() {
+        return this.currentLsn;
+    }
+    /**
+     * Get entries after a specific LSN (for recovery)
+     */
+    getEntriesAfter(lsn) {
+        return this.entries.filter(e => e.lsn > lsn);
+    }
+    /**
+     * Close the WAL
+     */
+    async close() {
+        if (this.isInitialized) {
+            // Final checkpoint before close
+            await this.checkpoint();
+        }
+        this.isInitialized = false;
+    }
+    // ============================================================================
+    // Private Methods
+    // ============================================================================
+    async appendEntry(partial) {
+        await this.initialize();
+        this.currentLsn++;
+        const entry = {
+            ...partial,
+            lsn: this.currentLsn,
+            timestamp: Date.now(),
+            checksum: 0, // Will be calculated
+        };
+        // Calculate checksum
+        entry.checksum = this.calculateChecksum(entry);
+        // Track in transaction if applicable
+        if (partial.txnId && this.uncommittedTxns.has(partial.txnId)) {
+            this.uncommittedTxns.get(partial.txnId).push(entry);
+        }
+        // Add to in-memory log
+        this.entries.push(entry);
+        // Append to file (append mode for durability)
+        await this.fs.file(this.walPath).encoding('utf8').append(JSON.stringify(entry) + '\n');
+        // Check if we need a checkpoint
+        if (this.entries.length - this.lastCheckpointLsn >= this.checkpointInterval) {
+            await this.checkpoint();
+        }
+        return entry.lsn;
+    }
+    serializeDocument(doc) {
+        // Serialize document to BSON and encode as base64
+        const bsonData = plugins.bson.serialize(doc);
+        return Buffer.from(bsonData).toString('base64');
+    }
+    deserializeDocument(data) {
+        // Decode base64 and deserialize from BSON
+        const buffer = Buffer.from(data, 'base64');
+        return plugins.bson.deserialize(buffer);
+    }
+    calculateChecksum(entry) {
+        // Simple CRC32-like checksum
+        const str = JSON.stringify({
+            lsn: entry.lsn,
+            timestamp: entry.timestamp,
+            operation: entry.operation,
+            dbName: entry.dbName,
+            collName: entry.collName,
+            documentId: entry.documentId,
+            data: entry.data,
+            previousData: entry.previousData,
+            txnId: entry.txnId,
+        });
+        let crc = 0xFFFFFFFF;
+        for (let i = 0; i < str.length; i++) {
+            crc ^= str.charCodeAt(i);
+            for (let j = 0; j < 8; j++) {
+                crc = (crc >>> 1) ^ (crc & 1 ? 0xEDB88320 : 0);
+            }
+        }
+        return (~crc) >>> 0;
+    }
+    verifyChecksum(entry) {
+        const savedChecksum = entry.checksum;
+        entry.checksum = 0;
+        const calculatedChecksum = this.calculateChecksum(entry);
+        entry.checksum = savedChecksum;
+        return calculatedChecksum === savedChecksum;
+    }
+    /**
+     * Recover document from WAL entry
+     */
+    recoverDocument(entry) {
+        if (!entry.data)
+            return null;
+        return this.deserializeDocument(entry.data);
+    }
+    /**
+     * Recover previous document state from WAL entry (for rollback)
+     */
+    recoverPreviousDocument(entry) {
+        if (!entry.previousData)
+            return null;
+        return this.deserializeDocument(entry.previousData);
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiV0FMLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vdHMvdHNtZGIvc3RvcmFnZS9XQUwudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxxQkFBcUIsQ0FBQztBQTJDL0M7Ozs7OztHQU1HO0FBQ0gsTUFBTSxPQUFPLEdBQUc7SUFDTixPQUFPLENBQVM7SUFDaEIsVUFBVSxHQUFXLENBQUMsQ0FBQztJQUN2QixpQkFBaUIsR0FBVyxDQUFDLENBQUM7SUFDOUIsT0FBTyxHQUFnQixFQUFFLENBQUM7SUFDMUIsYUFBYSxHQUFZLEtBQUssQ0FBQztJQUMvQixFQUFFLEdBQUcsSUFBSSxPQUFPLENBQUMsT0FBTyxDQUFDLE9BQU8sQ0FBQyxJQUFJLE9BQU8sQ0FBQyxPQUFPLENBQUMsbUJBQW1CLEVBQUUsQ0FBQyxDQUFDO0lBRXBGLGdEQUFnRDtJQUN4QyxlQUFlLEdBQTZCLElBQUksR0FBRyxFQUFFLENBQUM7SUFFOUQsOERBQThEO0lBQ3RELGtCQUFrQixHQUFXLElBQUksQ0FBQztJQUUxQyxZQUFZLE9BQWUsRUFBRSxPQUF5QztRQUNwRSxJQUFJLENBQUMsT0FBTyxHQUFHLE9BQU8sQ0FBQztRQUN2QixJQUFJLE9BQU8sRUFBRSxrQkFBa0IsRUFBRSxDQUFDO1lBQ2hDLElBQUksQ0FBQyxrQkFBa0IsR0FBRyxPQUFPLENBQUMsa0JBQWtCLENBQUM7UUFDdkQsQ0FBQztJQUNILENBQUM7SUFFRDs7T0FFRztJQUNILEtBQUssQ0FBQyxVQUFVO1FBQ2QsSUFBSSxJQUFJLENBQUMsYUFBYSxFQUFFLENBQUM7WUFDdkIsT0FBTyxFQUFFLGdCQUFnQixFQUFFLEVBQUUsRUFBRSxDQUFDO1FBQ2xDLENBQUM7UUFFRCw4QkFBOEI7UUFDOUIsTUFBTSxNQUFNLEdBQUcsSUFBSSxDQUFDLE9BQU8sQ0FBQyxTQUFTLENBQUMsQ0FBQyxFQUFFLElBQUksQ0FBQyxPQUFPLENBQUMsV0FBVyxDQUFDLEdBQUcs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

package/dist_ts/tsmdb/utils/checksum.d.ts

@@ -0,0 +1,30 @@
+/**
+ * CRC32 checksum utilities for data integrity
+ */
+/**
+ * Calculate CRC32 checksum for a string
+ */
+export declare function calculateCRC32(data: string): number;
+/**
+ * Calculate CRC32 checksum for a Buffer
+ */
+export declare function calculateCRC32Buffer(data: Buffer): number;
+/**
+ * Calculate checksum for a document (serialized as JSON)
+ */
+export declare function calculateDocumentChecksum(doc: Record<string, any>): number;
+/**
+ * Add checksum to a document
+ */
+export declare function addChecksum<T extends Record<string, any>>(doc: T): T & {
+    _checksum: number;
+};
+/**
+ * Verify checksum of a document
+ * Returns true if checksum is valid or if document has no checksum
+ */
+export declare function verifyChecksum(doc: Record<string, any>): boolean;
+/**
+ * Remove checksum from a document
+ */
+export declare function removeChecksum<T extends Record<string, any>>(doc: T): Omit<T, '_checksum'>;

package/dist_ts/tsmdb/utils/checksum.js

@@ -0,0 +1,77 @@
+/**
+ * CRC32 checksum utilities for data integrity
+ */
+// CRC32 lookup table
+const CRC32_TABLE = [];
+// Initialize the CRC32 table
+function initCRC32Table() {
+    if (CRC32_TABLE.length > 0)
+        return;
+    for (let i = 0; i < 256; i++) {
+        let crc = i;
+        for (let j = 0; j < 8; j++) {
+            crc = (crc & 1) ? (0xEDB88320 ^ (crc >>> 1)) : (crc >>> 1);
+        }
+        CRC32_TABLE[i] = crc >>> 0;
+    }
+}
+/**
+ * Calculate CRC32 checksum for a string
+ */
+export function calculateCRC32(data) {
+    initCRC32Table();
+    let crc = 0xFFFFFFFF;
+    for (let i = 0; i < data.length; i++) {
+        const byte = data.charCodeAt(i) & 0xFF;
+        crc = CRC32_TABLE[(crc ^ byte) & 0xFF] ^ (crc >>> 8);
+    }
+    return (~crc) >>> 0;
+}
+/**
+ * Calculate CRC32 checksum for a Buffer
+ */
+export function calculateCRC32Buffer(data) {
+    initCRC32Table();
+    let crc = 0xFFFFFFFF;
+    for (let i = 0; i < data.length; i++) {
+        crc = CRC32_TABLE[(crc ^ data[i]) & 0xFF] ^ (crc >>> 8);
+    }
+    return (~crc) >>> 0;
+}
+/**
+ * Calculate checksum for a document (serialized as JSON)
+ */
+export function calculateDocumentChecksum(doc) {
+    // Exclude _checksum field from calculation
+    const { _checksum, ...docWithoutChecksum } = doc;
+    const json = JSON.stringify(docWithoutChecksum);
+    return calculateCRC32(json);
+}
+/**
+ * Add checksum to a document
+ */
+export function addChecksum(doc) {
+    const checksum = calculateDocumentChecksum(doc);
+    return { ...doc, _checksum: checksum };
+}
+/**
+ * Verify checksum of a document
+ * Returns true if checksum is valid or if document has no checksum
+ */
+export function verifyChecksum(doc) {
+    if (!('_checksum' in doc)) {
+        // No checksum to verify
+        return true;
+    }
+    const storedChecksum = doc._checksum;
+    const calculatedChecksum = calculateDocumentChecksum(doc);
+    return storedChecksum === calculatedChecksum;
+}
+/**
+ * Remove checksum from a document
+ */
+export function removeChecksum(doc) {
+    const { _checksum, ...docWithoutChecksum } = doc;
+    return docWithoutChecksum;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2hlY2tzdW0uanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi90cy90c21kYi91dGlscy9jaGVja3N1bS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7R0FFRztBQUVILHFCQUFxQjtBQUNyQixNQUFNLFdBQVcsR0FBYSxFQUFFLENBQUM7QUFFakMsNkJBQTZCO0FBQzdCLFNBQVMsY0FBYztJQUNyQixJQUFJLFdBQVcsQ0FBQyxNQUFNLEdBQUcsQ0FBQztRQUFFLE9BQU87SUFFbkMsS0FBSyxJQUFJLENBQUMsR0FBRyxDQUFDLEVBQUUsQ0FBQyxHQUFHLEdBQUcsRUFBRSxDQUFDLEVBQUUsRUFBRSxDQUFDO1FBQzdCLElBQUksR0FBRyxHQUFHLENBQUMsQ0FBQztRQUNaLEtBQUssSUFBSSxDQUFDLEdBQUcsQ0FBQyxFQUFFLENBQUMsR0FBRyxDQUFDLEVBQUUsQ0FBQyxFQUFFLEVBQUUsQ0FBQztZQUMzQixHQUFHLEdBQUcsQ0FBQyxHQUFHLEdBQUcsQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUMsVUFBVSxHQUFHLENBQUMsR0FBRyxLQUFLLENBQUMsQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUMsR0FBRyxLQUFLLENBQUMsQ0FBQyxDQUFDO1FBQzdELENBQUM7UUFDRCxXQUFXLENBQUMsQ0FBQyxDQUFDLEdBQUcsR0FBRyxLQUFLLENBQUMsQ0FBQztJQUM3QixDQUFDO0FBQ0gsQ0FBQztBQUVEOztHQUVHO0FBQ0gsTUFBTSxVQUFVLGNBQWMsQ0FBQyxJQUFZO0lBQ3pDLGNBQWMsRUFBRSxDQUFDO0lBRWpCLElBQUksR0FBRyxHQUFHLFVBQVUsQ0FBQztJQUNyQixLQUFLLElBQUksQ0FBQyxHQUFHLENBQUMsRUFBRSxDQUFDLEdBQUcsSUFBSSxDQUFDLE1BQU0sRUFBRSxDQUFDLEVBQUUsRUFBRSxDQUFDO1FBQ3JDLE1BQU0sSUFBSSxHQUFHLElBQUksQ0FBQyxVQUFVLENBQUMsQ0FBQyxDQUFDLEdBQUcsSUFBSSxDQUFDO1FBQ3ZDLEdBQUcsR0FBRyxXQUFXLENBQUMsQ0FBQyxHQUFHLEdBQUcsSUFBSSxDQUFDLEdBQUcsSUFBSSxDQUFDLEdBQUcsQ0FBQyxHQUFHLEtBQUssQ0FBQyxDQUFDLENBQUM7SUFDdkQsQ0FBQztJQUNELE9BQU8sQ0FBQyxDQUFDLEdBQUcsQ0FBQyxLQUFLLENBQUMsQ0FBQztBQUN0QixDQUFDO0FBRUQ7O0dBRUc7QUFDSCxNQUFNLFVBQVUsb0JBQW9CLENBQUMsSUFBWTtJQUMvQyxjQUFjLEVBQUUsQ0FBQztJQUVqQixJQUFJLEdBQUcsR0FBRyxVQUFVLENBQUM7SUFDckIsS0FBSyxJQUFJLENBQUMsR0FBRyxDQUFDLEVBQUUsQ0FBQyxHQUFHLElBQUksQ0FBQyxNQUFNLEVBQUUsQ0FBQyxFQUFFLEVBQUUsQ0FBQztRQUNyQyxHQUFHLEdBQUcsV0FBVyxDQUFDLENBQUMsR0FBRyxHQUFHLElBQUksQ0FBQyxDQUFDLENBQUMsQ0FBQyxHQUFHLElBQUksQ0FBQyxHQUFHLENBQUMsR0FBRyxLQUFLLENBQUMsQ0FBQyxDQUFDO0lBQzFELENBQUM7SUFDRCxPQUFPLENBQUMsQ0FBQyxHQUFHLENBQUMsS0FBSyxDQUFDLENBQUM7QUFDdEIsQ0FBQztBQUVEOztHQUVHO0FBQ0gsTUFBTSxVQUFVLHlCQUF5QixDQUFDLEdBQXdCO0lBQ2hFLDJDQUEyQztJQUMzQyxNQUFNLEVBQUUsU0FBUyxFQUFFLEdBQUcsa0JBQWtCLEVBQUUsR0FBRyxHQUFHLENBQUM7SUFDakQsTUFBTSxJQUFJLEdBQUcsSUFBSSxDQUFDLFNBQVMsQ0FBQyxrQkFBa0IsQ0FBQyxDQUFDO0lBQ2hELE9BQU8sY0FBYyxDQUFDLElBQUksQ0FBQyxDQUFDO0FBQzlCLENBQUM7QUFFRDs7R0FFRztBQUNILE1BQU0sVUFBVSxXQUFXLENBQWdDLEdBQU07SUFDL0QsTUFBTSxRQUFRLEdBQUcseUJBQXlCLENBQUMsR0FBRyxDQUFDLENBQUM7SUFDaEQsT0FBTyxFQUFFLEdBQUcsR0FBRyxFQUFFLFNBQVMsRUFBRSxRQUFRLEVBQUUsQ0FBQztBQUN6QyxDQUFDO0FBRUQ7OztHQUdHO0FBQ0gsTUFBTSxVQUFVLGNBQWMsQ0FBQyxHQUF3QjtJQUNyRCxJQUFJLENBQUMsQ0FBQyxXQUFXLElBQUksR0FBRyxDQUFDLEVBQUUsQ0FBQztRQUMxQix3QkFBd0I7UUFDeEIsT0FBTyxJQUFJLENBQUM7SUFDZCxDQUFDO0lBRUQsTUFBTSxjQUFjLEdBQUcsR0FBRyxDQUFDLFNBQVMsQ0FBQztJQUNyQyxNQUFNLGtCQUFrQixHQUFHLHlCQUF5QixDQUFDLEdBQUcsQ0FBQyxDQUFDO0lBRTFELE9BQU8sY0FBYyxLQUFLLGtCQUFrQixDQUFDO0FBQy9DLENBQUM7QUFFRDs7R0FFRztBQUNILE1BQU0sVUFBVSxjQUFjLENBQWdDLEdBQU07SUFDbEUsTUFBTSxFQUFFLFNBQVMsRUFBRSxHQUFHLGtCQUFrQixFQUFFLEdBQUcsR0FBRyxDQUFDO0lBQ2pELE9BQU8sa0JBQTBDLENBQUM7QUFDcEQsQ0FBQyJ9

package/dist_ts/tsmdb/utils/index.d.ts

@@ -0,0 +1 @@
+export * from './checksum.js';

package/dist_ts/tsmdb/utils/index.js

@@ -0,0 +1,2 @@
+export * from './checksum.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi90cy90c21kYi91dGlscy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjLGVBQWUsQ0FBQyJ9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartmongo",
-  "version": "3.0.0",
+  "version": "4.1.1",
   "private": false,
   "description": "A module for creating and managing a local MongoDB instance for testing purposes.",
   "main": "dist_ts/index.js",
@@ -9,7 +9,7 @@
   "author": "Lossless GmbH",
   "license": "MIT",
   "scripts": {
-    "test": "(tstest test/)",
+    "test": "(tstest test/. --verbose --logfile --timeout 60)",
     "build": "(tsbuild --web)",
     "buildDocs": "tsdoc"
   },

package/readme.md

@@ -134,8 +134,8 @@ await server.start();
 console.log(server.getConnectionUri()); // mongodb://127.0.0.1:27017
 
 // Server properties
-console.log(server.running);           // true
-console.log(server.getUptime());       // seconds
+console.log(server.running);              // true
+console.log(server.getUptime());          // seconds
 console.log(server.getConnectionCount()); // active connections
 
 await server.stop();
@@ -279,7 +279,7 @@ console.log(result.deletedCount);   // 1
 
 ### Storage Adapters
 
-TsmDB supports pluggable storage:
+TsmDB supports pluggable storage with data integrity features:
 
 ```typescript
 // In-memory (default) - fast, data lost on stop
@@ -292,13 +292,118 @@ const server = new tsmdb.TsmdbServer({
   persistIntervalMs: 30000  // Save every 30 seconds
 });
 
-// File-based - persistent storage
-const server = new tsmdb.TsmdbServer({
-  storage: 'file',
-  storagePath: './data/tsmdb'
+// File-based - persistent storage with optional checksums
+import { FileStorageAdapter } from '@push.rocks/smartmongo/tsmdb';
+
+const adapter = new FileStorageAdapter('./data/tsmdb', {
+  enableChecksums: true,   // CRC32 checksums for data integrity
+  strictChecksums: false   // Log warnings vs throw on mismatch
 });
 ```
 
+## ⚡ Performance & Reliability Features
+
+TsmDB includes enterprise-grade features for robustness:
+
+### 🔍 Index-Accelerated Queries
+
+Indexes are automatically used to accelerate queries. Instead of scanning all documents, TsmDB uses:
+
+- **Hash indexes** for equality queries (`$eq`, `$in`)
+- **B-tree indexes** for range queries (`$gt`, `$gte`, `$lt`, `$lte`)
+
+```typescript
+// Create an index
+await collection.createIndex({ email: 1 });
+await collection.createIndex({ age: 1 });
+
+// These queries will use the index (fast!)
+await collection.findOne({ email: 'alice@example.com' }); // Uses hash lookup
+await collection.find({ age: { $gte: 18, $lt: 65 } });    // Uses B-tree range scan
+```
+
+### 📊 Query Planner
+
+TsmDB includes a query planner that analyzes queries and selects optimal execution strategies:
+
+```typescript
+import { tsmdb } from '@push.rocks/smartmongo';
+
+// For debugging, you can access the query planner
+const planner = new tsmdb.QueryPlanner(indexEngine);
+const plan = planner.createPlan(filter);
+
+console.log(plan);
+// {
+//   type: 'IXSCAN',           // or 'IXSCAN_RANGE', 'COLLSCAN'
+//   indexName: 'email_1',
+//   estimatedCost: 1,
+//   selectivity: 0.001
+// }
+```
+
+### 📝 Write-Ahead Logging (WAL)
+
+For durability, TsmDB supports write-ahead logging:
+
+```typescript
+import { tsmdb } from '@push.rocks/smartmongo';
+
+const wal = new tsmdb.WAL('./data/wal.log');
+await wal.initialize();
+
+// WAL entries include:
+// - LSN (Log Sequence Number)
+// - Timestamp
+// - Operation type (insert, update, delete, checkpoint)
+// - Document data (BSON serialized)
+// - CRC32 checksum
+
+// Recovery support
+const entries = await wal.getEntriesAfter(lastCheckpointLsn);
+```
+
+### 🔐 Session Management
+
+TsmDB tracks client sessions with automatic timeout and transaction linking:
+
+```typescript
+// Sessions are automatically managed when using the MongoDB driver
+const session = client.startSession();
+
+try {
+  session.startTransaction();
+  await collection.insertOne({ name: 'Alice' }, { session });
+  await collection.updateOne({ name: 'Bob' }, { $inc: { balance: 100 } }, { session });
+  await session.commitTransaction();
+} catch (error) {
+  await session.abortTransaction();
+} finally {
+  session.endSession();
+}
+
+// Session features:
+// - Automatic session timeout (30 minutes default)
+// - Transaction auto-abort on session expiry
+// - Session activity tracking
+```
+
+### ✅ Data Integrity Checksums
+
+File-based storage supports CRC32 checksums to detect corruption:
+
+```typescript
+import { FileStorageAdapter } from '@push.rocks/smartmongo/tsmdb';
+
+const adapter = new FileStorageAdapter('./data', {
+  enableChecksums: true,
+  strictChecksums: true  // Throw error on corruption (vs warning)
+});
+
+// Documents are checksummed on write, verified on read
+// Checksums are automatically stripped before returning to client
+```
+
 ### 📋 Supported Wire Protocol Commands
 
 | Category | Commands |
@@ -307,7 +412,9 @@ const server = new tsmdb.TsmdbServer({
 | **CRUD** | `find`, `insert`, `update`, `delete`, `findAndModify`, `getMore`, `killCursors` |
 | **Aggregation** | `aggregate`, `count`, `distinct` |
 | **Indexes** | `createIndexes`, `dropIndexes`, `listIndexes` |
-| **Admin** | `ping`, `listDatabases`, `listCollections`, `drop`, `dropDatabase`, `create`, `serverStatus`, `buildInfo` |
+| **Transactions** | `startTransaction`, `commitTransaction`, `abortTransaction` |
+| **Sessions** | `startSession`, `endSessions` |
+| **Admin** | `ping`, `listDatabases`, `listCollections`, `drop`, `dropDatabase`, `create`, `serverStatus`, `buildInfo`, `dbStats`, `collStats` |
 
 TsmDB supports MongoDB wire protocol versions 0-21, compatible with MongoDB 3.6 through 7.0 drivers.
 
@@ -317,7 +424,7 @@ TsmDB supports MongoDB wire protocol versions 0-21, compatible with MongoDB 3.6
 
 ```typescript
 import { tsmdb } from '@push.rocks/smartmongo';
-import { MongoClient } from 'mongodb';
+import { MongoClient, Db } from 'mongodb';
 
 let server: tsmdb.TsmdbServer;
 let client: MongoClient;
@@ -421,21 +528,37 @@ export default tap.start();
                           ▼
 ┌─────────────────────────────────────────────────────────────┐
 │                       Engines                               │
-│  ┌───────────┐ ┌────────────┐ ┌────────────┐ ┌───────────┐ │
-│  │  Query    │ │   Update   │ │Aggregation │ │   Index   │ │
-│  │  Engine   │ │   Engine   │ │  Engine    │ │  Engine   │ │
-│  └───────────┘ └────────────┘ └────────────┘ └───────────┘ │
+│  ┌─────────┐ ┌────────┐ ┌───────────┐ ┌───────┐ ┌───────┐ │
+│  │ Query   │ │ Update │ │Aggregation│ │ Index │ │Session│ │
+│  │ Planner │ │ Engine │ │  Engine   │ │Engine │ │Engine │ │
+│  └─────────┘ └────────┘ └───────────┘ └───────┘ └───────┘ │
+│                   ┌──────────────────────┐                  │
+│                   │ Transaction Engine   │                  │
+│                   └──────────────────────┘                  │
 └─────────────────────────┬───────────────────────────────────┘
                           │
                           ▼
 ┌─────────────────────────────────────────────────────────────┐
-│                   Storage Adapters                          │
-│       ┌──────────────────┐  ┌──────────────────┐           │
-│       │  MemoryStorage   │  │   FileStorage    │           │
-│       └──────────────────┘  └──────────────────┘           │
+│                   Storage Layer                              │
+│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────┐  │
+│  │  MemoryStorage   │  │   FileStorage    │  │   WAL    │  │
+│  │                  │  │  (+ Checksums)   │  │          │  │
+│  └──────────────────┘  └──────────────────┘  └──────────┘  │
 └─────────────────────────────────────────────────────────────┘
 ```
 
+### Key Components
+
+| Component | Description |
+|-----------|-------------|
+| **WireProtocol** | Parses MongoDB OP_MSG binary protocol |
+| **CommandRouter** | Routes commands to appropriate handlers |
+| **QueryPlanner** | Analyzes queries and selects execution strategy |
+| **IndexEngine** | Manages B-tree and hash indexes |
+| **SessionEngine** | Tracks client sessions and timeouts |
+| **TransactionEngine** | Handles ACID transaction semantics |
+| **WAL** | Write-ahead logging for durability |
+
 ## License and Legal Information
 
 This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartmongo',
-  version: '3.0.0',
+  version: '4.1.1',
   description: 'A module for creating and managing a local MongoDB instance for testing purposes.'
 }