mongolite-ts 0.4.0 → 0.6.0

package/README.md

@@ -16,6 +16,49 @@ A MongoDB-like client that uses SQLite as its underlying persistent store. Writt
 * Written in TypeScript with strong typing.
 * 100% test coverage (aiming for).
 * **Interactive Query Debugger** - Debug complex queries with `npx mongolite-debug`
+* **JSON Safety & Data Integrity** - Comprehensive protection against malformed JSON and data corruption
+* **Change Streams** - Real-time change tracking similar to MongoDB's `changeStream = collection.watch()`
+
+## JSON Safety & Data Integrity
+
+MongoLite includes robust safeguards to prevent and handle malformed JSON data that could cause application failures or data corruption:
+
+### Document Validation
+- **Pre-storage validation**: Automatically validates documents before insertion to prevent storing invalid data
+- **Type safety**: Rejects non-JSON-serializable data (functions, symbols, BigInt, RegExp, circular references)
+- **Round-trip verification**: Ensures all data can be safely stored and retrieved
+
+### Malformed JSON Recovery
+- **Graceful degradation**: Handles corrupted JSON data without crashing your application
+- **Automatic recovery**: Attempts to fix common JSON corruption issues (escaped quotes, backslashes)
+- **Fallback objects**: Returns special marker objects for unrecoverable data with debugging information
+- **Error logging**: Detailed logging for debugging and monitoring data integrity issues
+
+### Example Usage
+
+```typescript
+// Document validation prevents invalid data
+try {
+  await collection.insertOne({
+    name: 'user',
+    invalidFunction: () => 'not allowed' // This will be rejected
+  });
+} catch (error) {
+  console.log('Validation error:', error.message);
+  // "Cannot insert document: Document validation failed: Functions are not allowed in documents"
+}
+
+// Corrupted data recovery
+const doc = await collection.findOne({ _id: 'some-id' });
+if (doc && '__mongoLiteCorrupted' in doc) {
+  console.log('Found corrupted document');
+  console.log('Original data:', doc.__originalData);
+  console.log('Error details:', doc.__error);
+  // Handle corruption appropriately
+}
+```
+
+For detailed information about JSON safety features, see [JSON_SAFETY.md](./docs/JSON_SAFETY.md).
 
 ## Installation
 
@@ -113,6 +156,154 @@ async function main() {
 main();
 ```
 
+## Change Streams
+
+MongoLite supports real-time change tracking through change streams, similar to MongoDB's `collection.watch()` feature. Change streams allow you to monitor and react to data changes (inserts, updates, deletes) in real-time.
+
+### Basic Usage
+
+```typescript
+import { MongoLite } from 'mongolite-ts';
+
+const client = new MongoLite('./mydatabase.sqlite');
+const collection = client.collection('users');
+
+// Create a change stream
+const changeStream = collection.watch({
+  fullDocument: 'updateLookup',           // Include full document on updates
+  fullDocumentBeforeChange: 'whenAvailable'  // Include document before change
+});
+
+// Listen for changes
+changeStream.on('change', (change) => {
+  console.log('Change detected:', {
+    operation: change.operationType,        // 'insert', 'update', 'delete'
+    documentId: change.documentKey._id,
+    collection: change.ns.coll,
+    timestamp: change.clusterTime
+  });
+
+  if (change.fullDocument) {
+    console.log('New document state:', change.fullDocument);
+  }
+
+  if (change.updateDescription) {
+    console.log('Updated fields:', change.updateDescription.updatedFields);
+    console.log('Removed fields:', change.updateDescription.removedFields);
+  }
+});
+
+// Handle errors
+changeStream.on('error', (error) => {
+  console.error('Change stream error:', error);
+});
+
+// Perform operations - changes will be captured
+await collection.insertOne({ name: 'Alice', age: 30 });
+await collection.updateOne({ name: 'Alice' }, { $set: { age: 31 } });
+await collection.deleteOne({ name: 'Alice' });
+
+// Close the change stream when done
+changeStream.close();
+```
+
+### Async Iteration
+
+Change streams support async iteration for a more declarative approach:
+
+```typescript
+const changeStream = collection.watch();
+
+// Use async iteration
+for await (const change of changeStream) {
+  console.log('Change detected:', change.operationType);
+  
+  // Process the change...
+  
+  // Break after processing some changes
+  if (someCondition) {
+    changeStream.close();
+    break;
+  }
+}
+```
+
+### Change Stream Options
+
+```typescript
+interface ChangeStreamOptions {
+  // Filter to apply to change events
+  filter?: Filter<ChangeStreamDocument>;
+  
+  // Whether to include the full document in insert and update operations
+  fullDocument?: 'default' | 'updateLookup' | 'whenAvailable' | 'required';
+  
+  // Whether to include the full document before the change
+  fullDocumentBeforeChange?: 'off' | 'whenAvailable' | 'required';
+  
+  // Maximum number of events to buffer
+  maxBufferSize?: number;
+}
+
+// Example with options
+const changeStream = collection.watch({
+  fullDocument: 'updateLookup',
+  fullDocumentBeforeChange: 'whenAvailable',
+  maxBufferSize: 500
+});
+```
+
+### Change Document Structure
+
+Each change event contains detailed information about the operation:
+
+```typescript
+interface ChangeStreamDocument {
+  _id: string;                    // Unique change event ID
+  operationType: 'insert' | 'update' | 'delete' | 'replace';
+  clusterTime?: Date;             // Timestamp of the change
+  fullDocument?: T;               // Full document (based on options)
+  fullDocumentBeforeChange?: T;   // Document before change (based on options)
+  documentKey: { _id: string };   // ID of the affected document
+  ns: {                          // Namespace information
+    db: string;                   // Database name
+    coll: string;                 // Collection name
+  };
+  updateDescription?: {           // Update details (for update operations)
+    updatedFields: Record<string, unknown>;
+    removedFields: string[];
+  };
+}
+```
+
+### Implementation Details
+
+- **SQLite Triggers**: Uses SQLite triggers to capture changes automatically
+- **Change Log Table**: Stores change events in a dedicated `__mongolite_changes__` table
+- **Polling**: Efficiently polls for new changes every 100ms
+- **Cleanup**: Automatically cleans up triggers when change streams are closed
+- **Error Handling**: Robust error handling for database operations and malformed data
+
+### Best Practices
+
+1. **Close Change Streams**: Always close change streams when done to free resources
+2. **Error Handling**: Implement proper error handling for change stream events
+3. **Buffer Management**: Consider the `maxBufferSize` option for high-volume scenarios
+4. **Cleanup**: Call `changeStream.cleanup()` to remove triggers if needed
+
+```typescript
+// Proper cleanup
+try {
+  const changeStream = collection.watch();
+  
+  // ... use change stream
+  
+} finally {
+  changeStream.close();
+  await changeStream.cleanup(); // Remove triggers if needed
+}
+```
+
 ## Query Debugger
 
 MongoLite includes an interactive query debugger to help you debug complex queries and understand how MongoDB-style filters are converted to SQL.
@@ -214,6 +405,38 @@ Deletes a single document matching the filter.
 * `filter`: The selection criteria for the deletion.
 * Returns `DeleteResult`: `{ acknowledged: boolean; deletedCount: number; }`.
 
+#### `watch(options?: ChangeStreamOptions<T>): ChangeStream<T>`
+
+Opens a change stream to watch for changes on this collection. Returns a ChangeStream that emits events when documents are inserted, updated, or deleted.
+
+* `options`: Optional configuration for the change stream
+  * `fullDocument`: Controls when to include the full document ('default', 'updateLookup', 'whenAvailable', 'required')
+  * `fullDocumentBeforeChange`: Controls when to include the document before change ('off', 'whenAvailable', 'required')  
+  * `maxBufferSize`: Maximum number of events to buffer (default: 1000)
+* Returns a `ChangeStream` instance that extends EventEmitter and supports async iteration.
+
+```typescript
+// Basic change stream
+const changeStream = collection.watch();
+changeStream.on('change', (change) => {
+  console.log('Change detected:', change);
+});
+
+// With options
+const changeStream = collection.watch({
+  fullDocument: 'updateLookup',
+  fullDocumentBeforeChange: 'whenAvailable'
+});
+
+// Async iteration
+for await (const change of changeStream) {
+  console.log('Change:', change.operationType);
+}
+
+// Always close when done
+changeStream.close();
+```
+
 
 ### `FindCursor<T>`
 

package/dist/bin/mongolite-debug.js

@@ -71,7 +71,7 @@ async function main() {
             'database.db',
             'database.sqlite',
             'app.db',
-            'app.sqlite'
+            'app.sqlite',
         ];
         // Check if any common database files exist
         const { existsSync } = await import('fs');
@@ -108,7 +108,7 @@ async function main() {
         process.exit(1);
     }
 }
-main().catch(error => {
+main().catch((error) => {
     console.error('Unexpected error:', error);
     process.exit(1);
 });

package/dist/bin/mongolite-debug.js.map

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

package/dist/changeStream.d.ts

@@ -0,0 +1,114 @@
+import { EventEmitter } from 'events';
+import { SQLiteDB } from './db.js';
+import { DocumentWithId, Filter } from './types.js';
+export type ChangeOperationType = 'insert' | 'update' | 'delete' | 'replace';
+export interface ChangeStreamDocument<T extends DocumentWithId = DocumentWithId> {
+    _id: string;
+    operationType: ChangeOperationType;
+    clusterTime?: Date;
+    fullDocument?: T;
+    fullDocumentBeforeChange?: T;
+    documentKey: {
+        _id: string;
+    };
+    ns: {
+        db: string;
+        coll: string;
+    };
+    updateDescription?: {
+        updatedFields: Record<string, unknown>;
+        removedFields: string[];
+    };
+}
+export interface ChangeStreamOptions<T extends DocumentWithId = DocumentWithId> {
+    /**
+     * Filter to apply to change events
+     */
+    filter?: Filter<ChangeStreamDocument<T>>;
+    /**
+     * Whether to include the full document in insert and update operations
+     */
+    fullDocument?: 'default' | 'updateLookup' | 'whenAvailable' | 'required';
+    /**
+     * Whether to include the full document before the change for update operations
+     */
+    fullDocumentBeforeChange?: 'off' | 'whenAvailable' | 'required';
+    /**
+     * Resume token for resuming change streams (not implemented in this version)
+     */
+    resumeAfter?: string;
+    /**
+     * Maximum number of events to buffer
+     */
+    maxBufferSize?: number;
+}
+export declare class ChangeStream<T extends DocumentWithId = DocumentWithId> extends EventEmitter {
+    private readonly db;
+    private readonly collectionName;
+    private readonly options;
+    private closed;
+    private pollInterval;
+    private lastProcessedId;
+    private buffer;
+    private readonly maxBufferSize;
+    constructor(db: SQLiteDB, collectionName: string, options?: ChangeStreamOptions<T>);
+    /**
+     * Sets up the change tracking infrastructure
+     */
+    private setupChangeTracking;
+    /**
+     * Creates the change log table if it doesn't exist
+     */
+    private ensureChangeLogTable;
+    /**
+     * Sets up triggers for tracking changes on the collection
+     */
+    private setupTriggers;
+    /**
+     * Starts polling for new changes
+     */
+    private startPolling;
+    /**
+     * Polls for new changes from the change log
+     */
+    private pollForChanges;
+    /**
+     * Transforms a raw change event from the database into a ChangeStreamDocument
+     */
+    private transformChangeEvent;
+    /**
+     * Computes the update description by comparing before and after documents
+     */
+    private computeUpdateDescription;
+    /**
+     * Determines if the full document should be included
+     */
+    private shouldIncludeFullDocument;
+    /**
+     * Determines if the full document before change should be included
+     */
+    private shouldIncludeFullDocumentBefore;
+    /**
+     * Checks if a change document passes the filter
+     */
+    private passesFilter;
+    /**
+     * Returns an async iterator for the change stream
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<ChangeStreamDocument<T>>;
+    /**
+     * Closes the change stream
+     */
+    close(): void;
+    /**
+     * Returns the next change document
+     */
+    next(): Promise<{
+        value: ChangeStreamDocument<T>;
+        done: boolean;
+    }>;
+    /**
+     * Cleanup triggers when the change stream is destroyed
+     */
+    cleanup(): Promise<void>;
+}