tersejson 0.3.0 → 0.3.1

package/README.md

@@ -181,6 +181,45 @@ If you access 3 fields from a 21-field object:
 - Protobuf: All 21 fields deserialized into memory
 - TerseJSON: Only 3 fields materialize
 
+## MongoDB Integration (Zero-Config)
+
+**NEW:** Automatic memory-efficient queries with MongoDB native driver.
+
+```typescript
+import { terseMongo } from 'tersejson/mongodb';
+import { MongoClient } from 'mongodb';
+
+// Call once at app startup
+await terseMongo();
+
+// All queries automatically return Proxy-wrapped results
+const client = new MongoClient(uri);
+const users = await client.db('mydb').collection('users').find().toArray();
+
+// Access properties normally - 70% less memory
+console.log(users[0].firstName); // Works transparently!
+```
+
+**What gets patched:**
+- `find().toArray()` - arrays of documents
+- `find().next()` - single document iteration
+- `for await (const doc of cursor)` - async iteration
+- `findOne()` - single document queries
+- `aggregate().toArray()` - aggregation results
+
+**Options:**
+```typescript
+await terseMongo({
+  minArrayLength: 5,    // Only compress arrays with 5+ items
+  skipSingleDocs: true, // Don't wrap findOne results
+  minKeyLength: 4,      // Only compress keys with 4+ chars
+});
+
+// Restore original behavior
+import { unterse } from 'tersejson/mongodb';
+await unterse();
+```
+
 ## Server-Side Memory Optimization
 
 TerseJSON includes utilities for memory-efficient server-side data handling:

package/dist/mongodb.d.mts

@@ -0,0 +1,107 @@
+import { C as CompressOptions } from './types-BTonKlz8.mjs';
+
+/**
+ * TerseJSON MongoDB Integration
+ *
+ * Zero-config integration with MongoDB native driver.
+ * Call terseMongo() once at startup and all queries automatically
+ * return memory-efficient Proxy-wrapped results.
+ *
+ * @example
+ * ```typescript
+ * import { terseMongo } from 'tersejson/mongodb';
+ * import { MongoClient } from 'mongodb';
+ *
+ * terseMongo(); // Patch once at startup
+ *
+ * const client = new MongoClient(uri);
+ * const users = await client.db('mydb').collection('users').find().toArray();
+ * // users is automatically Proxy-wrapped - 70% less memory
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Options for terseMongo initialization
+ */
+interface TerseMongoOptions extends Partial<CompressOptions> {
+    /**
+     * Enable/disable compression (default: true)
+     */
+    enabled?: boolean;
+    /**
+     * Minimum array length to compress (default: 1)
+     * Single documents are always wrapped for consistency
+     */
+    minArrayLength?: number;
+    /**
+     * Skip compression for single document queries like findOne (default: false)
+     * Set to true if you don't want overhead on single doc fetches
+     */
+    skipSingleDocs?: boolean;
+}
+/**
+ * Initialize TerseJSON integration with MongoDB native driver.
+ *
+ * Call this once at application startup, before any MongoDB queries.
+ * All subsequent queries will automatically return Proxy-wrapped results.
+ *
+ * @example
+ * ```typescript
+ * import { terseMongo } from 'tersejson/mongodb';
+ *
+ * // Basic usage
+ * await terseMongo();
+ *
+ * // With options
+ * await terseMongo({
+ *   minKeyLength: 4,        // Only compress keys with 4+ characters
+ *   minArrayLength: 5,      // Only compress arrays with 5+ items
+ *   skipSingleDocs: true,   // Don't wrap findOne results
+ * });
+ * ```
+ *
+ * @param options - Configuration options
+ */
+declare function terseMongo(options?: TerseMongoOptions): Promise<void>;
+/**
+ * Synchronous version of terseMongo for CommonJS compatibility.
+ *
+ * Note: This requires mongodb to already be loaded in the module cache.
+ * For best results, use the async terseMongo() instead.
+ *
+ * @param options - Configuration options
+ */
+declare function terseMongoSync(options?: TerseMongoOptions): void;
+/**
+ * Remove TerseJSON patches from MongoDB driver.
+ *
+ * Useful for testing or when you need to temporarily disable compression.
+ *
+ * @example
+ * ```typescript
+ * import { terseMongo, unterse } from 'tersejson/mongodb';
+ *
+ * await terseMongo();
+ * // ... queries are Proxy-wrapped
+ *
+ * await unterse();
+ * // ... queries return normal documents
+ * ```
+ */
+declare function unterse(): Promise<void>;
+/**
+ * Check if TerseJSON MongoDB patching is active
+ */
+declare function isTerseMongoActive(): boolean;
+/**
+ * Get current TerseJSON MongoDB options
+ */
+declare function getTerseMongoOptions(): TerseMongoOptions;
+/**
+ * Update TerseJSON MongoDB options without re-patching
+ */
+declare function setTerseMongoOptions(options: Partial<TerseMongoOptions>): void;
+
+export { type TerseMongoOptions, getTerseMongoOptions, isTerseMongoActive, setTerseMongoOptions, terseMongo, terseMongoSync, unterse };

package/dist/mongodb.d.ts

@@ -0,0 +1,107 @@
+import { C as CompressOptions } from './types-BTonKlz8.js';
+
+/**
+ * TerseJSON MongoDB Integration
+ *
+ * Zero-config integration with MongoDB native driver.
+ * Call terseMongo() once at startup and all queries automatically
+ * return memory-efficient Proxy-wrapped results.
+ *
+ * @example
+ * ```typescript
+ * import { terseMongo } from 'tersejson/mongodb';
+ * import { MongoClient } from 'mongodb';
+ *
+ * terseMongo(); // Patch once at startup
+ *
+ * const client = new MongoClient(uri);
+ * const users = await client.db('mydb').collection('users').find().toArray();
+ * // users is automatically Proxy-wrapped - 70% less memory
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Options for terseMongo initialization
+ */
+interface TerseMongoOptions extends Partial<CompressOptions> {
+    /**
+     * Enable/disable compression (default: true)
+     */
+    enabled?: boolean;
+    /**
+     * Minimum array length to compress (default: 1)
+     * Single documents are always wrapped for consistency
+     */
+    minArrayLength?: number;
+    /**
+     * Skip compression for single document queries like findOne (default: false)
+     * Set to true if you don't want overhead on single doc fetches
+     */
+    skipSingleDocs?: boolean;
+}
+/**
+ * Initialize TerseJSON integration with MongoDB native driver.
+ *
+ * Call this once at application startup, before any MongoDB queries.
+ * All subsequent queries will automatically return Proxy-wrapped results.
+ *
+ * @example
+ * ```typescript
+ * import { terseMongo } from 'tersejson/mongodb';
+ *
+ * // Basic usage
+ * await terseMongo();
+ *
+ * // With options
+ * await terseMongo({
+ *   minKeyLength: 4,        // Only compress keys with 4+ characters
+ *   minArrayLength: 5,      // Only compress arrays with 5+ items
+ *   skipSingleDocs: true,   // Don't wrap findOne results
+ * });
+ * ```
+ *
+ * @param options - Configuration options
+ */
+declare function terseMongo(options?: TerseMongoOptions): Promise<void>;
+/**
+ * Synchronous version of terseMongo for CommonJS compatibility.
+ *
+ * Note: This requires mongodb to already be loaded in the module cache.
+ * For best results, use the async terseMongo() instead.
+ *
+ * @param options - Configuration options
+ */
+declare function terseMongoSync(options?: TerseMongoOptions): void;
+/**
+ * Remove TerseJSON patches from MongoDB driver.
+ *
+ * Useful for testing or when you need to temporarily disable compression.
+ *
+ * @example
+ * ```typescript
+ * import { terseMongo, unterse } from 'tersejson/mongodb';
+ *
+ * await terseMongo();
+ * // ... queries are Proxy-wrapped
+ *
+ * await unterse();
+ * // ... queries return normal documents
+ * ```
+ */
+declare function unterse(): Promise<void>;
+/**
+ * Check if TerseJSON MongoDB patching is active
+ */
+declare function isTerseMongoActive(): boolean;
+/**
+ * Get current TerseJSON MongoDB options
+ */
+declare function getTerseMongoOptions(): TerseMongoOptions;
+/**
+ * Update TerseJSON MongoDB options without re-patching
+ */
+declare function setTerseMongoOptions(options: Partial<TerseMongoOptions>): void;
+
+export { type TerseMongoOptions, getTerseMongoOptions, isTerseMongoActive, setTerseMongoOptions, terseMongo, terseMongoSync, unterse };