mongolite-ts 0.4.0 → 0.6.0

package/dist/changeStream.js

@@ -0,0 +1,338 @@
+import { EventEmitter } from 'events';
+export class ChangeStream extends EventEmitter {
+    constructor(db, collectionName, options = {}) {
+        super();
+        this.db = db;
+        this.collectionName = collectionName;
+        this.options = options;
+        this.closed = false;
+        this.pollInterval = null;
+        this.lastProcessedId = 0;
+        this.buffer = [];
+        this.maxBufferSize = options.maxBufferSize || 1000;
+        this.setupChangeTracking();
+        this.startPolling();
+    }
+    /**
+     * Sets up the change tracking infrastructure
+     */
+    async setupChangeTracking() {
+        await this.ensureChangeLogTable();
+        await this.setupTriggers();
+    }
+    /**
+     * Creates the change log table if it doesn't exist
+     */
+    async ensureChangeLogTable() {
+        const createTableSQL = `
+      CREATE TABLE IF NOT EXISTS __mongolite_changes__ (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
+        operation_type TEXT NOT NULL,
+        collection_name TEXT NOT NULL,
+        document_id TEXT NOT NULL,
+        full_document TEXT,
+        full_document_before TEXT,
+        updated_fields TEXT,
+        removed_fields TEXT,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+      );
+    `;
+        const createIndexSQL = `
+      CREATE INDEX IF NOT EXISTS idx_mongolite_changes_collection_timestamp 
+      ON __mongolite_changes__ (collection_name, timestamp);
+    `;
+        await this.db.exec(createTableSQL);
+        await this.db.exec(createIndexSQL);
+    }
+    /**
+     * Sets up triggers for tracking changes on the collection
+     */
+    async setupTriggers() {
+        const collectionName = this.collectionName;
+        // Drop existing triggers for this collection
+        await this.db.exec(`DROP TRIGGER IF EXISTS "${collectionName}_insert_trigger"`);
+        await this.db.exec(`DROP TRIGGER IF EXISTS "${collectionName}_update_trigger"`);
+        await this.db.exec(`DROP TRIGGER IF EXISTS "${collectionName}_delete_trigger"`);
+        // Insert trigger
+        const insertTriggerSQL = `
+      CREATE TRIGGER "${collectionName}_insert_trigger"
+      AFTER INSERT ON "${collectionName}"
+      FOR EACH ROW
+      BEGIN
+        INSERT INTO __mongolite_changes__ (
+          operation_type, collection_name, document_id, full_document
+        ) VALUES (
+          'insert', '${collectionName}', NEW._id, NEW.data
+        );
+      END;
+    `;
+        // Update trigger
+        const updateTriggerSQL = `
+      CREATE TRIGGER "${collectionName}_update_trigger"
+      AFTER UPDATE ON "${collectionName}"
+      FOR EACH ROW
+      BEGIN
+        INSERT INTO __mongolite_changes__ (
+          operation_type, collection_name, document_id, 
+          full_document, full_document_before
+        ) VALUES (
+          'update', '${collectionName}', NEW._id, 
+          NEW.data, OLD.data
+        );
+      END;
+    `;
+        // Delete trigger
+        const deleteTriggerSQL = `
+      CREATE TRIGGER "${collectionName}_delete_trigger"
+      AFTER DELETE ON "${collectionName}"
+      FOR EACH ROW
+      BEGIN
+        INSERT INTO __mongolite_changes__ (
+          operation_type, collection_name, document_id, full_document_before
+        ) VALUES (
+          'delete', '${collectionName}', OLD._id, OLD.data
+        );
+      END;
+    `;
+        await this.db.exec(insertTriggerSQL);
+        await this.db.exec(updateTriggerSQL);
+        await this.db.exec(deleteTriggerSQL);
+    }
+    /**
+     * Starts polling for new changes
+     */
+    startPolling() {
+        if (this.closed)
+            return;
+        this.pollInterval = setInterval(async () => {
+            try {
+                await this.pollForChanges();
+            }
+            catch (error) {
+                this.emit('error', error);
+            }
+        }, 100); // Poll every 100ms
+    }
+    /**
+     * Polls for new changes from the change log
+     */
+    async pollForChanges() {
+        if (this.closed)
+            return;
+        const changes = await this.db.all(`SELECT * FROM __mongolite_changes__ 
+       WHERE collection_name = ? AND id > ? 
+       ORDER BY id ASC LIMIT 100`, [this.collectionName, this.lastProcessedId]);
+        for (const change of changes) {
+            if (this.closed)
+                break;
+            const changeDoc = await this.transformChangeEvent(change);
+            if (this.passesFilter(changeDoc)) {
+                this.buffer.push(changeDoc);
+                // Emit the change event
+                this.emit('change', changeDoc);
+                // Clean buffer if it gets too large
+                if (this.buffer.length > this.maxBufferSize) {
+                    this.buffer = this.buffer.slice(-this.maxBufferSize);
+                }
+            }
+            this.lastProcessedId = change.id;
+        }
+    }
+    /**
+     * Transforms a raw change event from the database into a ChangeStreamDocument
+     */
+    async transformChangeEvent(change) {
+        const fullDocument = change.full_document ? JSON.parse(change.full_document) : undefined;
+        const fullDocumentBefore = change.full_document_before
+            ? JSON.parse(change.full_document_before)
+            : undefined;
+        let updateDescription;
+        if (change.operation_type === 'update' && fullDocument && fullDocumentBefore) {
+            updateDescription = this.computeUpdateDescription(fullDocumentBefore, fullDocument);
+        }
+        const changeDoc = {
+            _id: `${change.id}`, // Use the change log ID as the change stream document ID
+            operationType: change.operation_type,
+            clusterTime: new Date(change.timestamp),
+            documentKey: { _id: change.document_id },
+            ns: {
+                db: 'mongolite', // You could make this configurable
+                coll: change.collection_name,
+            },
+        };
+        // Add full document based on options
+        if (this.shouldIncludeFullDocument(change.operation_type)) {
+            changeDoc.fullDocument = fullDocument
+                ? { _id: change.document_id, ...fullDocument }
+                : undefined;
+        }
+        // Add full document before change based on options
+        if (this.shouldIncludeFullDocumentBefore(change.operation_type)) {
+            changeDoc.fullDocumentBeforeChange = fullDocumentBefore
+                ? { _id: change.document_id, ...fullDocumentBefore }
+                : undefined;
+        }
+        if (updateDescription) {
+            changeDoc.updateDescription = updateDescription;
+        }
+        return changeDoc;
+    }
+    /**
+     * Computes the update description by comparing before and after documents
+     */
+    computeUpdateDescription(before, after) {
+        const updatedFields = {};
+        const removedFields = [];
+        // Type guard to ensure we have objects to compare
+        if (typeof before !== 'object' ||
+            before === null ||
+            typeof after !== 'object' ||
+            after === null) {
+            return { updatedFields, removedFields };
+        }
+        // Simple comparison - this could be made more sophisticated
+        const beforeObj = before;
+        const afterObj = after;
+        const allKeys = new Set([...Object.keys(beforeObj), ...Object.keys(afterObj)]);
+        for (const key of allKeys) {
+            if (!(key in afterObj)) {
+                removedFields.push(key);
+            }
+            else if (!(key in beforeObj) ||
+                JSON.stringify(beforeObj[key]) !== JSON.stringify(afterObj[key])) {
+                updatedFields[key] = afterObj[key];
+            }
+        }
+        return { updatedFields, removedFields };
+    }
+    /**
+     * Determines if the full document should be included
+     */
+    shouldIncludeFullDocument(operationType) {
+        const option = this.options.fullDocument || 'default';
+        switch (option) {
+            case 'default':
+                return operationType === 'insert';
+            case 'updateLookup':
+            case 'whenAvailable':
+            case 'required':
+                return (operationType === 'insert' || operationType === 'update' || operationType === 'replace');
+            default:
+                return false;
+        }
+    }
+    /**
+     * Determines if the full document before change should be included
+     */
+    shouldIncludeFullDocumentBefore(operationType) {
+        const option = this.options.fullDocumentBeforeChange || 'off';
+        if (option === 'off')
+            return false;
+        return operationType === 'update' || operationType === 'replace' || operationType === 'delete';
+    }
+    /**
+     * Checks if a change document passes the filter
+     */
+    passesFilter(changeDoc) {
+        if (!this.options.filter)
+            return true;
+        // Simple filter implementation - could be enhanced
+        // For now, just check basic equality filters
+        for (const [key, value] of Object.entries(this.options.filter)) {
+            const docValue = changeDoc[key];
+            if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                // Handle operators like $in, $eq, etc.
+                // This is a simplified implementation
+                continue;
+            }
+            else if (docValue !== value) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Returns an async iterator for the change stream
+     */
+    async *[Symbol.asyncIterator]() {
+        while (!this.closed) {
+            if (this.buffer.length > 0) {
+                yield this.buffer.shift();
+            }
+            else {
+                // Wait for next change
+                await new Promise((resolve) => {
+                    const onChange = () => {
+                        this.removeListener('change', onChange);
+                        this.removeListener('close', onClose);
+                        resolve();
+                    };
+                    const onClose = () => {
+                        this.removeListener('change', onChange);
+                        this.removeListener('close', onClose);
+                        resolve();
+                    };
+                    this.once('change', onChange);
+                    this.once('close', onClose);
+                });
+            }
+        }
+    }
+    /**
+     * Closes the change stream
+     */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.pollInterval) {
+            clearInterval(this.pollInterval);
+            this.pollInterval = null;
+        }
+        this.emit('close');
+        this.removeAllListeners();
+    }
+    /**
+     * Returns the next change document
+     */
+    async next() {
+        if (this.closed) {
+            return { value: {}, done: true };
+        }
+        if (this.buffer.length > 0) {
+            return { value: this.buffer.shift(), done: false };
+        }
+        // Wait for next change
+        return new Promise((resolve) => {
+            const onChange = (changeDoc) => {
+                this.removeListener('change', onChange);
+                this.removeListener('close', onClose);
+                resolve({ value: changeDoc, done: false });
+            };
+            const onClose = () => {
+                this.removeListener('change', onChange);
+                this.removeListener('close', onClose);
+                resolve({ value: {}, done: true });
+            };
+            this.once('change', onChange);
+            this.once('close', onClose);
+        });
+    }
+    /**
+     * Cleanup triggers when the change stream is destroyed
+     */
+    async cleanup() {
+        const collectionName = this.collectionName;
+        try {
+            await this.db.exec(`DROP TRIGGER IF EXISTS "${collectionName}_insert_trigger"`);
+            await this.db.exec(`DROP TRIGGER IF EXISTS "${collectionName}_update_trigger"`);
+            await this.db.exec(`DROP TRIGGER IF EXISTS "${collectionName}_delete_trigger"`);
+        }
+        catch (error) {
+            // Ignore errors during cleanup
+            console.warn('Error during change stream cleanup:', error);
+        }
+    }
+}
+//# sourceMappingURL=changeStream.js.map

package/dist/changeStream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"changeStream.js","sourceRoot":"","sources":["../src/changeStream.ts"],"names":[],"mappings":"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"}

package/dist/collection.d.ts

@@ -1,6 +1,7 @@
 import { SQLiteDB } from './db.js';
 import { DocumentWithId, Filter, UpdateFilter, InsertOneResult, UpdateResult, DeleteResult, Projection, IndexSpecification, CreateIndexOptions, CreateIndexResult, DropIndexResult, IndexInfo } from './types.js';
 import { FindCursor } from './cursors/findCursor.js';
+import { ChangeStream, ChangeStreamOptions } from './changeStream.js';
 /**
  * MongoLiteCollection provides methods to interact with a specific SQLite table
  * as if it were a MongoDB collection.
@@ -147,6 +148,31 @@ export declare class MongoLiteCollection<T extends DocumentWithId> {
      * @returns {Promise<number>} The count of matching documents.
      */
     countDocuments(filter?: Filter<T>): Promise<number>;
+    /**
+     * Opens a change stream to watch for changes on this collection.
+     * Returns a ChangeStream that emits events when documents are inserted, updated, or deleted.
+     *
+     * @param options Options for the change stream
+     * @returns A ChangeStream instance
+     *
+     * @example
+     * ```typescript
+     * const changeStream = collection.watch();
+     *
+     * changeStream.on('change', (change) => {
+     *   console.log('Change detected:', change);
+     * });
+     *
+     * // Or use async iteration
+     * for await (const change of changeStream) {
+     *   console.log('Change detected:', change);
+     * }
+     *
+     * // Close the change stream when done
+     * changeStream.close();
+     * ```
+     */
+    watch(options?: ChangeStreamOptions<T>): ChangeStream<T>;
     /**
      * Retries an operation with exponential backoff when SQLITE_BUSY errors occur.
      * @param operation The operation function to retry.

package/dist/collection.js

@@ -1,6 +1,138 @@
 import { ObjectId } from 'bson';
 import { FindCursor } from './cursors/findCursor.js';
 import { extractRawIndexColumns } from './utils/indexing.js';
+import { ChangeStream } from './changeStream.js';
+/**
+ * Safely stringifies JSON data with validation and error handling.
+ * Prevents storing malformed JSON that could cause parsing issues later.
+ * @param data The data to stringify
+ * @param context Optional context for error messages
+ * @returns The JSON string
+ * @throws Error if the data cannot be safely stringified
+ */
+function safeJsonStringify(data, context) {
+    try {
+        // First, validate that the data is JSON-serializable by attempting to stringify it
+        const jsonString = JSON.stringify(data);
+        // Verify that the stringified data can be parsed back (round-trip test)
+        try {
+            const parsed = JSON.parse(jsonString);
+            // Basic validation that the round-trip preserved the data structure
+            if (typeof data === 'object' && data !== null && typeof parsed !== 'object') {
+                throw new Error('Round-trip JSON validation failed: type mismatch');
+            }
+        }
+        catch (parseError) {
+            throw new Error(`Round-trip JSON validation failed: ${parseError instanceof Error ? parseError.message : 'Unknown parse error'}`);
+        }
+        return jsonString;
+    }
+    catch (error) {
+        const contextMsg = context ? ` in ${context}` : '';
+        if (error instanceof Error) {
+            throw new Error(`Failed to safely stringify JSON data${contextMsg}: ${error.message}`);
+        }
+        throw new Error(`Failed to safely stringify JSON data${contextMsg}: Unknown error`);
+    }
+}
+/**
+ * Safely parses JSON data with fallback mechanisms for malformed JSON.
+ * @param jsonString The JSON string to parse
+ * @param context Optional context for error messages and recovery
+ * @returns The parsed object or a fallback object
+ */
+function safeJsonParse(jsonString, context) {
+    if (!jsonString || typeof jsonString !== 'string') {
+        console.warn(`Invalid JSON string${context ? ` in ${context}` : ''}: not a string or empty`);
+        return {};
+    }
+    try {
+        return JSON.parse(jsonString);
+    }
+    catch (error) {
+        // Log the error for debugging
+        console.error(`JSON parse error${context ? ` in ${context}` : ''}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        console.error(`Malformed JSON string: ${jsonString.substring(0, 500)}${jsonString.length > 500 ? '...' : ''}`);
+        // Attempt to recover from common JSON corruption issues
+        try {
+            // Try to fix common escaping issues
+            let fixedJson = jsonString;
+            // Fix double-escaped quotes
+            fixedJson = fixedJson.replace(/\\"/g, '"');
+            // Fix improperly escaped backslashes
+            fixedJson = fixedJson.replace(/\\\\/g, '\\');
+            // Try parsing the fixed JSON
+            const recovered = JSON.parse(fixedJson);
+            console.warn(`Successfully recovered malformed JSON${context ? ` in ${context}` : ''}`);
+            return recovered;
+        }
+        catch (recoveryError) {
+            console.error(`JSON recovery failed${context ? ` in ${context}` : ''}: ${recoveryError instanceof Error ? recoveryError.message : 'Unknown error'}`);
+            // Last resort: return an empty object with a special marker
+            return {
+                __mongoLiteCorrupted: true,
+                __originalData: jsonString,
+                __error: error instanceof Error ? error.message : 'Unknown JSON parse error',
+            };
+        }
+    }
+}
+/**
+ * Validates that a document is safe to store (no functions, circular references, etc.)
+ * @param doc The document to validate
+ * @param path Current path for error reporting
+ * @throws Error if the document contains invalid data
+ */
+function validateDocumentForStorage(doc, path = 'root') {
+    if (doc === null || doc === undefined) {
+        return;
+    }
+    if (typeof doc === 'function') {
+        throw new Error(`Document validation failed: Functions are not allowed in documents (found at ${path})`);
+    }
+    if (typeof doc === 'symbol') {
+        throw new Error(`Document validation failed: Symbols are not allowed in documents (found at ${path})`);
+    }
+    if (typeof doc === 'bigint') {
+        throw new Error(`Document validation failed: BigInt values are not supported, use regular numbers or strings (found at ${path})`);
+    }
+    if (doc instanceof RegExp) {
+        throw new Error(`Document validation failed: RegExp objects are not supported in documents (found at ${path})`);
+    }
+    if (Array.isArray(doc)) {
+        doc.forEach((item, index) => {
+            validateDocumentForStorage(item, `${path}[${index}]`);
+        });
+    }
+    else if (typeof doc === 'object') {
+        // Check for circular references by maintaining a Set of visited objects
+        const visited = new Set();
+        function checkCircular(obj, currentPath) {
+            if (visited.has(obj)) {
+                throw new Error(`Document validation failed: Circular reference detected at ${currentPath}`);
+            }
+            visited.add(obj);
+            for (const [key, value] of Object.entries(obj)) {
+                if (typeof value === 'object' && value !== null) {
+                    checkCircular(value, `${currentPath}.${key}`);
+                }
+            }
+            visited.delete(obj);
+        }
+        try {
+            checkCircular(doc, path);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('Circular reference')) {
+                throw error;
+            }
+        }
+        // Validate each property
+        for (const [key, value] of Object.entries(doc)) {
+            validateDocumentForStorage(value, `${path}.${key}`);
+        }
+    }
+}
 /**
  * MongoLiteCollection provides methods to interact with a specific SQLite table
  * as if it were a MongoDB collection.
@@ -54,7 +186,14 @@ export class MongoLiteCollection {
         const docId = doc._id || new ObjectId().toString();
         // eslint-disable-next-line @typescript-eslint/no-unused-vars
         const { _id, ...dataToStore } = { ...doc, _id: docId }; // Ensure _id is part of the internal structure
-        const jsonData = JSON.stringify(dataToStore);
+        // Validate the document before storing
+        try {
+            validateDocumentForStorage(dataToStore);
+        }
+        catch (error) {
+            throw new Error(`Cannot insert document: ${error instanceof Error ? error.message : 'Unknown validation error'}`);
+        }
+        const jsonData = safeJsonStringify(dataToStore, `insertOne for document ${docId}`);
         const sql = `INSERT INTO "${this.name}" (_id, data) VALUES (?, ?)`;
         try {
             await this.db.run(sql, [docId, jsonData]);
@@ -103,13 +242,20 @@ export class MongoLiteCollection {
     async insertBatch(docs) {
         const results = [];
         // Prepare all documents and their data upfront
-        const preparedDocs = docs.map(doc => {
+        const preparedDocs = docs.map((doc) => {
             const docId = doc._id || new ObjectId().toString();
             // eslint-disable-next-line @typescript-eslint/no-unused-vars
             const { _id, ...dataToStore } = { ...doc, _id: docId };
+            // Validate the document before storing
+            try {
+                validateDocumentForStorage(dataToStore);
+            }
+            catch (error) {
+                throw new Error(`Cannot insert document ${docId}: ${error instanceof Error ? error.message : 'Unknown validation error'}`);
+            }
             return {
                 id: docId,
-                data: JSON.stringify(dataToStore)
+                data: safeJsonStringify(dataToStore, `insertBatch for document ${docId}`),
             };
         });
         const insertBatchOperation = async () => {
@@ -139,7 +285,7 @@ export class MongoLiteCollection {
                 if (error.code === 'SQLITE_CONSTRAINT') {
                     // Find which document caused the constraint violation
                     const errorMessage = error.message;
-                    const duplicateId = preparedDocs.find(doc => errorMessage.includes(doc.id))?.id || 'unknown';
+                    const duplicateId = preparedDocs.find((doc) => errorMessage.includes(doc.id))?.id || 'unknown';
                     throw new Error(`Duplicate _id: ${duplicateId}`);
                 }
                 throw error;
@@ -211,7 +357,7 @@ export class MongoLiteCollection {
             const newDocId = update.$set?._id || new ObjectId().toString();
             const newDoc = { _id: newDocId, ...update.$set }; // Assuming $set is used for upsert
             // Ensure _id is set
-            const jsonData = JSON.stringify(newDoc);
+            const jsonData = safeJsonStringify(newDoc, `upsert for document ${newDocId}`);
             const insertSql = `INSERT INTO "${this.name}" (_id, data) VALUES (?, ?)`;
             try {
                 await this.db.run(insertSql, [newDocId, jsonData]);
@@ -233,7 +379,7 @@ export class MongoLiteCollection {
         if (!rowToUpdate) {
             return { acknowledged: true, matchedCount: 0, modifiedCount: 0, upsertedId: null };
         }
-        const currentDoc = JSON.parse(rowToUpdate.data);
+        const currentDoc = safeJsonParse(rowToUpdate.data, `updateOne for document ${rowToUpdate._id}`);
         let modified = false;
         // Process update operators
         for (const operator in update) {
@@ -322,7 +468,10 @@ export class MongoLiteCollection {
         if (modified) {
             // Update the document in SQLite
             const updateSql = `UPDATE "${this.name}" SET data = ? WHERE _id = ?`;
-            const updateParams = [JSON.stringify(currentDoc), rowToUpdate._id];
+            const updateParams = [
+                safeJsonStringify(currentDoc, `updateOne for document ${rowToUpdate._id}`),
+                rowToUpdate._id,
+            ];
             try {
                 await this.db.run(updateSql, updateParams);
             }
@@ -366,7 +515,7 @@ export class MongoLiteCollection {
         let modifiedCount = 0;
         const updatedIds = [];
         for (const rowToUpdate of rowsToUpdate) {
-            const currentDoc = JSON.parse(rowToUpdate.data);
+            const currentDoc = safeJsonParse(rowToUpdate.data, `updateMany for document ${rowToUpdate._id}`);
             let modified = false;
             // Process update operators
             for (const operator in update) {
@@ -458,7 +607,10 @@ export class MongoLiteCollection {
             if (modified) {
                 // Update the document in SQLite
                 const updateSql = `UPDATE "${this.name}" SET data = ? WHERE _id = ?`;
-                const updateParams = [JSON.stringify(currentDoc), rowToUpdate._id];
+                const updateParams = [
+                    safeJsonStringify(currentDoc, `updateMany for document ${rowToUpdate._id}`),
+                    rowToUpdate._id,
+                ];
                 try {
                     await this.db.run(updateSql, updateParams);
                     modifiedCount++;
@@ -760,6 +912,33 @@ export class MongoLiteCollection {
         const result = await this.db.get(countSql, paramsForCount);
         return result?.count || 0;
     }
+    /**
+     * Opens a change stream to watch for changes on this collection.
+     * Returns a ChangeStream that emits events when documents are inserted, updated, or deleted.
+     *
+     * @param options Options for the change stream
+     * @returns A ChangeStream instance
+     *
+     * @example
+     * ```typescript
+     * const changeStream = collection.watch();
+     *
+     * changeStream.on('change', (change) => {
+     *   console.log('Change detected:', change);
+     * });
+     *
+     * // Or use async iteration
+     * for await (const change of changeStream) {
+     *   console.log('Change detected:', change);
+     * }
+     *
+     * // Close the change stream when done
+     * changeStream.close();
+     * ```
+     */
+    watch(options = {}) {
+        return new ChangeStream(this.db, this.name, options);
+    }
     /**
      * Retries an operation with exponential backoff when SQLITE_BUSY errors occur.
      * @param operation The operation function to retry.