tersejson 0.2.1 → 0.3.1

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 };

package/dist/mongodb.js

@@ -0,0 +1,472 @@
+'use strict';
+
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/core.ts
+function alphaGenerator(index) {
+  let key = "";
+  let remaining = index;
+  do {
+    key = String.fromCharCode(97 + remaining % 26) + key;
+    remaining = Math.floor(remaining / 26) - 1;
+  } while (remaining >= 0);
+  return key;
+}
+function numericGenerator(index) {
+  return String(index);
+}
+function alphanumericGenerator(index) {
+  const letterIndex = Math.floor(index / 9);
+  const numIndex = index % 9 + 1;
+  return alphaGenerator(letterIndex) + numIndex;
+}
+function shortGenerator(index) {
+  if (index === 0) return "_";
+  return alphaGenerator(index - 1);
+}
+function prefixedGenerator(prefix, style = "numeric") {
+  return (index) => {
+    if (style === "alpha") {
+      return prefix + alphaGenerator(index);
+    }
+    return prefix + index;
+  };
+}
+function createKeyGenerator(pattern) {
+  if (typeof pattern === "function") {
+    return { generator: pattern, name: "custom" };
+  }
+  if (typeof pattern === "string") {
+    switch (pattern) {
+      case "alpha":
+        return { generator: alphaGenerator, name: "alpha" };
+      case "numeric":
+        return { generator: numericGenerator, name: "numeric" };
+      case "alphanumeric":
+        return { generator: alphanumericGenerator, name: "alphanumeric" };
+      case "short":
+        return { generator: shortGenerator, name: "short" };
+      case "prefixed":
+        return { generator: prefixedGenerator("k"), name: "prefixed:k" };
+      default:
+        return { generator: alphaGenerator, name: "alpha" };
+    }
+  }
+  if (typeof pattern === "object" && "prefix" in pattern) {
+    return {
+      generator: prefixedGenerator(pattern.prefix, pattern.style || "numeric"),
+      name: `prefixed:${pattern.prefix}`
+    };
+  }
+  return { generator: alphaGenerator, name: "alpha" };
+}
+function resolveNestedDepth(handling, maxDepth) {
+  if (handling === void 0 || handling === "deep") {
+    return maxDepth;
+  }
+  if (handling === "shallow") {
+    return 1;
+  }
+  if (handling === "arrays") {
+    return maxDepth;
+  }
+  if (typeof handling === "number") {
+    return handling;
+  }
+  return maxDepth;
+}
+function collectKeys(data, options, currentDepth = 0) {
+  const keys = /* @__PURE__ */ new Set();
+  const { minKeyLength, maxDepth, nestedHandling, excludeKeys, includeKeys } = options;
+  if (currentDepth >= maxDepth) return keys;
+  const keyCounts = /* @__PURE__ */ new Map();
+  for (const item of data) {
+    if (typeof item !== "object" || item === null) continue;
+    for (const key of Object.keys(item)) {
+      if (excludeKeys?.includes(key)) continue;
+      const shouldInclude = includeKeys?.includes(key) || key.length >= minKeyLength;
+      if (shouldInclude) {
+        keys.add(key);
+        keyCounts.set(key, (keyCounts.get(key) || 0) + 1);
+      }
+      const value = item[key];
+      if (nestedHandling === "shallow") {
+        continue;
+      }
+      if (Array.isArray(value) && value.length > 0 && isCompressibleArray(value)) {
+        const nestedKeys = collectKeys(
+          value,
+          options,
+          currentDepth + 1
+        );
+        nestedKeys.forEach((k) => keys.add(k));
+      } else if (nestedHandling !== "arrays" && typeof value === "object" && value !== null && !Array.isArray(value)) {
+        const nestedKeys = collectKeys(
+          [value],
+          options,
+          currentDepth + 1
+        );
+        nestedKeys.forEach((k) => keys.add(k));
+      }
+    }
+  }
+  if (options.homogeneousOnly && data.length > 0) {
+    for (const [key, count] of keyCounts) {
+      if (count < data.length) {
+        keys.delete(key);
+      }
+    }
+  }
+  return keys;
+}
+function isCompressibleArray(data) {
+  if (!Array.isArray(data) || data.length === 0) return false;
+  return data.every(
+    (item) => typeof item === "object" && item !== null && !Array.isArray(item)
+  );
+}
+function compressObject(obj, keyToShort, maxDepth, currentDepth = 0) {
+  if (currentDepth >= maxDepth) return obj;
+  const compressed = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const shortKey = keyToShort.get(key) ?? key;
+    if (Array.isArray(value) && isCompressibleArray(value)) {
+      compressed[shortKey] = value.map(
+        (item) => compressObject(
+          item,
+          keyToShort,
+          maxDepth,
+          currentDepth + 1
+        )
+      );
+    } else if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      compressed[shortKey] = compressObject(
+        value,
+        keyToShort,
+        maxDepth,
+        currentDepth + 1
+      );
+    } else {
+      compressed[shortKey] = value;
+    }
+  }
+  return compressed;
+}
+function compress(data, options = {}) {
+  const {
+    minKeyLength = 3,
+    maxDepth = 10,
+    keyPattern = "alpha",
+    nestedHandling = "deep",
+    homogeneousOnly = false,
+    excludeKeys,
+    includeKeys
+  } = options;
+  const { generator, name: patternName } = createKeyGenerator(keyPattern);
+  const effectiveDepth = resolveNestedDepth(nestedHandling, maxDepth);
+  const allKeys = collectKeys(data, {
+    minKeyLength,
+    maxDepth: effectiveDepth,
+    nestedHandling,
+    excludeKeys,
+    includeKeys,
+    homogeneousOnly
+  });
+  const sortedKeys = Array.from(allKeys).sort();
+  const keyToShort = /* @__PURE__ */ new Map();
+  const keyMap = {};
+  sortedKeys.forEach((key, index) => {
+    const shortKey = generator(index);
+    if (shortKey.length < key.length) {
+      keyToShort.set(key, shortKey);
+      keyMap[shortKey] = key;
+    }
+  });
+  const compressed = data.map(
+    (item) => compressObject(item, keyToShort, effectiveDepth)
+  );
+  return {
+    __terse__: true,
+    v: 1,
+    k: keyMap,
+    d: compressed,
+    p: patternName
+  };
+}
+function createTerseProxy(compressed, keyMap) {
+  const originalToShort = new Map(
+    Object.entries(keyMap).map(([short, original]) => [original, short])
+  );
+  const handler = {
+    get(target, prop) {
+      if (typeof prop === "symbol") {
+        return Reflect.get(target, prop);
+      }
+      const shortKey = originalToShort.get(prop);
+      const actualKey = shortKey ?? prop;
+      const value = target[actualKey];
+      if (Array.isArray(value)) {
+        return value.map((item) => {
+          if (typeof item === "object" && item !== null && !Array.isArray(item)) {
+            return createTerseProxy(item, keyMap);
+          }
+          return item;
+        });
+      }
+      if (typeof value === "object" && value !== null) {
+        return createTerseProxy(value, keyMap);
+      }
+      return value;
+    },
+    has(target, prop) {
+      if (typeof prop === "symbol") {
+        return Reflect.has(target, prop);
+      }
+      const shortKey = originalToShort.get(prop);
+      return (shortKey ?? prop) in target;
+    },
+    ownKeys(target) {
+      return Object.keys(target).map((shortKey) => keyMap[shortKey] ?? shortKey);
+    },
+    getOwnPropertyDescriptor(target, prop) {
+      if (typeof prop === "symbol") {
+        return Reflect.getOwnPropertyDescriptor(target, prop);
+      }
+      const shortKey = originalToShort.get(prop);
+      const actualKey = shortKey ?? prop;
+      const descriptor = Object.getOwnPropertyDescriptor(target, actualKey);
+      if (descriptor) {
+        return { ...descriptor, enumerable: true, configurable: true };
+      }
+      return void 0;
+    }
+  };
+  return new Proxy(compressed, handler);
+}
+function wrapWithProxy(payload) {
+  if (Array.isArray(payload.d)) {
+    return payload.d.map((item) => {
+      if (typeof item === "object" && item !== null && !Array.isArray(item)) {
+        return createTerseProxy(item, payload.k);
+      }
+      return item;
+    });
+  }
+  if (typeof payload.d === "object" && payload.d !== null) {
+    return createTerseProxy(payload.d, payload.k);
+  }
+  return payload.d;
+}
+
+// src/mongodb.ts
+var isPatched = false;
+var globalOptions = {};
+var originalMethods = {};
+function wrapResults(results) {
+  if (globalOptions.enabled === false) {
+    return results;
+  }
+  if (results.length < (globalOptions.minArrayLength ?? 1)) {
+    return results;
+  }
+  if (!isCompressibleArray(results)) {
+    return results;
+  }
+  const payload = compress(results, globalOptions);
+  return wrapWithProxy(payload);
+}
+function wrapSingleDoc(doc) {
+  if (globalOptions.enabled === false || globalOptions.skipSingleDocs) {
+    return doc;
+  }
+  if (doc === null || doc === void 0) {
+    return doc;
+  }
+  if (typeof doc !== "object") {
+    return doc;
+  }
+  const payload = compress([doc], globalOptions);
+  const wrapped = wrapWithProxy(payload);
+  return wrapped[0];
+}
+async function patchMongoDB() {
+  let mongodb;
+  try {
+    mongodb = await import('mongodb');
+  } catch {
+    throw new Error(
+      "terseMongo requires mongodb to be installed. Run: npm install mongodb"
+    );
+  }
+  const { FindCursor, AggregationCursor, Collection } = mongodb;
+  if (FindCursor?.prototype) {
+    originalMethods.findCursorToArray = FindCursor.prototype.toArray;
+    FindCursor.prototype.toArray = async function() {
+      const results = await originalMethods.findCursorToArray.call(this);
+      return wrapResults(results);
+    };
+    originalMethods.findCursorNext = FindCursor.prototype.next;
+    FindCursor.prototype.next = async function() {
+      const doc = await originalMethods.findCursorNext.call(this);
+      return doc ? wrapSingleDoc(doc) : null;
+    };
+    originalMethods.findCursorIterator = FindCursor.prototype[Symbol.asyncIterator];
+    FindCursor.prototype[Symbol.asyncIterator] = async function* () {
+      const iterator = originalMethods.findCursorIterator.call(this);
+      for await (const doc of iterator) {
+        yield wrapSingleDoc(doc);
+      }
+    };
+  }
+  if (AggregationCursor?.prototype) {
+    originalMethods.aggregationCursorToArray = AggregationCursor.prototype.toArray;
+    AggregationCursor.prototype.toArray = async function() {
+      const results = await originalMethods.aggregationCursorToArray.call(this);
+      return wrapResults(results);
+    };
+    originalMethods.aggregationCursorNext = AggregationCursor.prototype.next;
+    AggregationCursor.prototype.next = async function() {
+      const doc = await originalMethods.aggregationCursorNext.call(this);
+      return doc ? wrapSingleDoc(doc) : null;
+    };
+    originalMethods.aggregationCursorIterator = AggregationCursor.prototype[Symbol.asyncIterator];
+    AggregationCursor.prototype[Symbol.asyncIterator] = async function* () {
+      const iterator = originalMethods.aggregationCursorIterator.call(this);
+      for await (const doc of iterator) {
+        yield wrapSingleDoc(doc);
+      }
+    };
+  }
+  if (Collection?.prototype) {
+    originalMethods.collectionFindOne = Collection.prototype.findOne;
+    Collection.prototype.findOne = async function(...args) {
+      const doc = await originalMethods.collectionFindOne.apply(this, args);
+      return doc ? wrapSingleDoc(doc) : null;
+    };
+  }
+}
+async function unpatchMongoDB() {
+  let mongodb;
+  try {
+    mongodb = await import('mongodb');
+  } catch {
+    return;
+  }
+  const { FindCursor, AggregationCursor, Collection } = mongodb;
+  if (FindCursor?.prototype && originalMethods.findCursorToArray) {
+    FindCursor.prototype.toArray = originalMethods.findCursorToArray;
+    FindCursor.prototype.next = originalMethods.findCursorNext;
+    FindCursor.prototype[Symbol.asyncIterator] = originalMethods.findCursorIterator;
+  }
+  if (AggregationCursor?.prototype && originalMethods.aggregationCursorToArray) {
+    AggregationCursor.prototype.toArray = originalMethods.aggregationCursorToArray;
+    AggregationCursor.prototype.next = originalMethods.aggregationCursorNext;
+    AggregationCursor.prototype[Symbol.asyncIterator] = originalMethods.aggregationCursorIterator;
+  }
+  if (Collection?.prototype && originalMethods.collectionFindOne) {
+    Collection.prototype.findOne = originalMethods.collectionFindOne;
+  }
+}
+async function terseMongo(options = {}) {
+  if (isPatched) {
+    globalOptions = { minArrayLength: 1, ...options };
+    return;
+  }
+  globalOptions = { minArrayLength: 1, ...options };
+  await patchMongoDB();
+  isPatched = true;
+}
+function terseMongoSync(options = {}) {
+  if (isPatched) {
+    globalOptions = { minArrayLength: 1, ...options };
+    return;
+  }
+  globalOptions = { minArrayLength: 1, ...options };
+  let mongodb;
+  try {
+    mongodb = __require("mongodb");
+  } catch {
+    throw new Error(
+      "terseMongo requires mongodb to be installed. Run: npm install mongodb"
+    );
+  }
+  const { FindCursor, AggregationCursor, Collection } = mongodb;
+  if (FindCursor?.prototype) {
+    originalMethods.findCursorToArray = FindCursor.prototype.toArray;
+    FindCursor.prototype.toArray = async function() {
+      const results = await originalMethods.findCursorToArray.call(this);
+      return wrapResults(results);
+    };
+    originalMethods.findCursorNext = FindCursor.prototype.next;
+    FindCursor.prototype.next = async function() {
+      const doc = await originalMethods.findCursorNext.call(this);
+      return doc ? wrapSingleDoc(doc) : null;
+    };
+    originalMethods.findCursorIterator = FindCursor.prototype[Symbol.asyncIterator];
+    FindCursor.prototype[Symbol.asyncIterator] = async function* () {
+      const iterator = originalMethods.findCursorIterator.call(this);
+      for await (const doc of iterator) {
+        yield wrapSingleDoc(doc);
+      }
+    };
+  }
+  if (AggregationCursor?.prototype) {
+    originalMethods.aggregationCursorToArray = AggregationCursor.prototype.toArray;
+    AggregationCursor.prototype.toArray = async function() {
+      const results = await originalMethods.aggregationCursorToArray.call(this);
+      return wrapResults(results);
+    };
+    originalMethods.aggregationCursorNext = AggregationCursor.prototype.next;
+    AggregationCursor.prototype.next = async function() {
+      const doc = await originalMethods.aggregationCursorNext.call(this);
+      return doc ? wrapSingleDoc(doc) : null;
+    };
+    originalMethods.aggregationCursorIterator = AggregationCursor.prototype[Symbol.asyncIterator];
+    AggregationCursor.prototype[Symbol.asyncIterator] = async function* () {
+      const iterator = originalMethods.aggregationCursorIterator.call(this);
+      for await (const doc of iterator) {
+        yield wrapSingleDoc(doc);
+      }
+    };
+  }
+  if (Collection?.prototype) {
+    originalMethods.collectionFindOne = Collection.prototype.findOne;
+    Collection.prototype.findOne = async function(...args) {
+      const doc = await originalMethods.collectionFindOne.apply(this, args);
+      return doc ? wrapSingleDoc(doc) : null;
+    };
+  }
+  isPatched = true;
+}
+async function unterse() {
+  if (!isPatched) return;
+  await unpatchMongoDB();
+  Object.keys(originalMethods).forEach((key) => {
+    delete originalMethods[key];
+  });
+  isPatched = false;
+  globalOptions = {};
+}
+function isTerseMongoActive() {
+  return isPatched;
+}
+function getTerseMongoOptions() {
+  return { ...globalOptions };
+}
+function setTerseMongoOptions(options) {
+  globalOptions = { ...globalOptions, ...options };
+}
+
+exports.getTerseMongoOptions = getTerseMongoOptions;
+exports.isTerseMongoActive = isTerseMongoActive;
+exports.setTerseMongoOptions = setTerseMongoOptions;
+exports.terseMongo = terseMongo;
+exports.terseMongoSync = terseMongoSync;
+exports.unterse = unterse;
+//# sourceMappingURL=mongodb.js.map
+//# sourceMappingURL=mongodb.js.map