@ignex/ninox 0.1.2 → 0.1.4

package/dist/index.js

@@ -16,8 +16,11 @@ var withTimeout = (promise, timeoutMs, label) => {
     if (timer !== void 0) clearTimeout(timer);
   });
 };
-var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-var sleepJittered = (ms, jitterMs = 1e3) => sleep(ms + Math.floor(Math.random() * Math.min(ms, jitterMs)));
+var sleep = (ms, unref = false) => new Promise((resolve) => {
+  const timer = setTimeout(resolve, ms);
+  if (unref) timer.unref?.();
+});
+var sleepJittered = (ms, jitterMs = 1e3, unref = false) => sleep(ms + Math.floor(Math.random() * Math.min(ms, jitterMs)), unref);
 
 // src/capabilities.ts
 var createMongoCapabilitiesStore = () => {
@@ -82,7 +85,7 @@ var AppError = class extends Error {
     this.name = "AppError";
     this.code = code;
     this.statusCode = statusCode;
-    this.extra = extra;
+    if (extra !== void 0) this.extra = extra;
   }
   /**
    * Stable, client-safe serialization for framework error middleware: a
@@ -466,6 +469,18 @@ var RefreshTicker = class {
 // src/cache/hot-cache/types.ts
 var WATCH_SEP = "\0";
 
+// src/utils/watch-errors.ts
+var isPermanentWatchError = (message) => (
+  // Standalone server: `$changeStream` is not supported at all.
+  /only supported on replica sets/i.test(message) || // Credentials/authorization problems: the user cannot run `aggregate` on
+  // this collection/server. Wrong creds, missing roles, or a user created
+  // without the `read`/`changeStream` privilege will never start working by
+  // retrying — fail once and stop instead of retrying forever.
+  /requires authentication|not authorized|unauthorized|authentication failed|Command .* requires authentication/i.test(
+    message
+  )
+);
+
 // src/cache/hot-cache/watcher.ts
 var WatchCoordinator = class {
   constructor(host) {
@@ -513,7 +528,10 @@ var WatchCoordinator = class {
    * Long-lived change-stream consumer for one collection. Each data change
    * invalidates the queries bound to it. On permanent "not supported" errors the
    * watcher is dropped and, if every planned stream failed, the cache falls back
-   * to the standalone ticker. Transient errors retry with backoff.
+   * to the standalone ticker. Transient errors (including resume-token expiry,
+   * rollbacks, and `invalidate` events) retry with backoff and invalidate the
+   * collection on reopen so entries missed during the outage are re-fetched —
+   * see the module doc for the full failure-semantics contract.
    */
   async watchLoop(key, ref) {
     let backoff = 0;
@@ -548,14 +566,14 @@ var WatchCoordinator = class {
           } catch {
           }
         }
-        if (/only supported on replica sets|not supported|ChangeStream/i.test(message)) {
+        if (isPermanentWatchError(message)) {
           this.markStreamFailed(key);
           return;
         }
       }
       if (this.stopped) return;
       backoff = Math.min(backoff + 1e3, 5e3);
-      await sleepJittered(backoff);
+      await sleepJittered(backoff, 1e3, true);
     }
   }
   markStreamFailed(key) {
@@ -657,7 +675,7 @@ var HotCache = class {
       ttlMs: config.ttlMs ?? this.options.defaultTtlMs ?? 0,
       refreshIntervalMs: config.refreshIntervalMs ?? 0,
       clone: config.clone ?? false,
-      maxValueBytes: config.maxValueBytes,
+      ...config.maxValueBytes !== void 0 ? { maxValueBytes: config.maxValueBytes } : {},
       gen: 0,
       hits: 0,
       misses: 0,
@@ -880,6 +898,8 @@ var cacheCollectionKey = (dbName, physical) => `${dbName}${NS_SEP}${physical}`;
 var QueryCache = class {
   lru;
   index = /* @__PURE__ */ new Map();
+  /** Per-collection version — bumped on every invalidation/clear of that collection. */
+  colVersions = /* @__PURE__ */ new Map();
   ttlMs;
   clone;
   hits = 0;
@@ -914,6 +934,14 @@ var QueryCache = class {
   key(collection, filterHash) {
     return `${collection}${SEP}${filterHash}`;
   }
+  /**
+   * Current version of a collection key (db-namespaced, e.g. from
+   * `cacheCollectionKey`). Reads capture it BEFORE fetching and pass it to
+   * `set()` so a concurrent invalidation can never be hidden by a late write.
+   */
+  versionOf(collection) {
+    return this.colVersions.get(collection) ?? 0;
+  }
   get(key) {
     const entry = this.lru.get(key);
     if (!entry) {
@@ -925,22 +953,38 @@ var QueryCache = class {
       this.misses++;
       return void 0;
     }
+    if (entry.versions) {
+      for (const [col, ver] of Object.entries(entry.versions)) {
+        if (this.versionOf(col) !== ver) {
+          this.lru.delete(key);
+          this.misses++;
+          return void 0;
+        }
+      }
+    }
     this.hits++;
     return this.clone ? cloneDeep(entry.value) : entry.value;
   }
-  set(key, value, ttlMs) {
+  set(key, value, ttlMs, collections, versions) {
     this.sets++;
     const ttl = ttlMs ?? this.ttlMs;
     const expiresAt = ttl > 0 ? Date.now() + ttl : Infinity;
-    this.lru.set(key, { value, expiresAt });
+    this.lru.set(key, {
+      value,
+      expiresAt,
+      ...versions !== void 0 ? { versions } : {}
+    });
     const sep = key.indexOf(SEP);
-    const collection = sep === -1 ? key : key.slice(0, sep);
-    let keys = this.index.get(collection);
-    if (!keys) {
-      keys = /* @__PURE__ */ new Set();
-      this.index.set(collection, keys);
+    const primary = sep === -1 ? key : key.slice(0, sep);
+    const collectionKeys = /* @__PURE__ */ new Set([primary, ...collections ?? []]);
+    for (const collection of collectionKeys) {
+      let keys = this.index.get(collection);
+      if (!keys) {
+        keys = /* @__PURE__ */ new Set();
+        this.index.set(collection, keys);
+      }
+      keys.add(key);
     }
-    keys.add(key);
   }
   delete(key) {
     this.deletes++;
@@ -948,6 +992,7 @@ var QueryCache = class {
   }
   /** Drop every cached entry belonging to a physical collection. */
   invalidateByCollection(collection) {
+    this.colVersions.set(collection, (this.colVersions.get(collection) ?? 0) + 1);
     const keys = this.index.get(collection);
     if (!keys) return;
     this.invalidateEvents++;
@@ -956,6 +1001,9 @@ var QueryCache = class {
   }
   clear() {
     this.clearEvents++;
+    for (const collection of this.index.keys()) {
+      this.colVersions.set(collection, (this.colVersions.get(collection) ?? 0) + 1);
+    }
     this.lru.clear();
     this.index.clear();
   }
@@ -963,7 +1011,9 @@ var QueryCache = class {
 
 // src/graceful-transaction.ts
 var withGracefulMongoTransaction = async (runner, fn, options = {}) => {
-  const enabled = options.capabilities === void 0 || mongoTransactionsEnabled(options.capabilities, { urlHint: options.urlHint });
+  const enabled = options.capabilities === void 0 || mongoTransactionsEnabled(options.capabilities, {
+    ...options.urlHint !== void 0 ? { urlHint: options.urlHint } : {}
+  });
   if (!enabled) return fn(null);
   try {
     return await runner.transaction(fn);
@@ -2227,13 +2277,13 @@ var CacheInvalidator = class {
           } catch {
           }
         }
-        if (/only supported on replica sets/i.test(message)) {
+        if (isPermanentWatchError(message)) {
           this.disabled = true;
           if (!this.warnedUnsupported) {
             this.warnedUnsupported = true;
             this.logger.warn?.(
               { collection: ref.collection, error: message },
-              "cacheWatch: change streams are not supported here (standalone?) \u2014 the query cache stays write-through only; set cache: { ttlMs } or disable cacheWatch"
+              "cacheWatch: change streams unavailable permanently \u2014 the query cache stays write-through only; set cache: { ttlMs } or disable cacheWatch"
             );
           }
           return;
@@ -2244,7 +2294,7 @@ var CacheInvalidator = class {
           "cacheWatch: change stream error, retrying with backoff"
         );
         backoff = Math.min(backoff + 1e3, 5e3);
-        await sleepJittered(backoff);
+        await sleepJittered(backoff, 1e3, true);
       }
     }
   }
@@ -2393,15 +2443,15 @@ var createHealth = (db) => async () => {
 
 // src/relation/populate.ts
 var createForeignKeyLoader = (deps2, collection, foreignField, options = {}) => new DataLoader({
-  maxBatchSize: options.maxBatchSize,
-  cache: options.cache,
+  ...options.maxBatchSize !== void 0 ? { maxBatchSize: options.maxBatchSize } : {},
+  ...options.cache !== void 0 ? { cache: options.cache } : {},
   keyOf: canonicalKey,
   batch: async (keys) => {
     const docs = await deps2.findMany(
       collection,
       { [foreignField]: { $in: keys } },
       {
-        limit: options.maxDocs
+        ...options.maxDocs !== void 0 ? { limit: options.maxDocs } : {}
       }
     );
     const index = /* @__PURE__ */ new Map();
@@ -2506,11 +2556,23 @@ var asCollectionDefinition = (value) => {
 };
 
 // src/service/trace-db-op.ts
+var debugQueryCache;
+var probeDebugQuery = async () => {
+  if (debugQueryCache !== void 0) return;
+  try {
+    const mod = await import('@ignex/core/debug');
+    debugQueryCache = typeof mod.debugQuery === "function" ? mod.debugQuery : null;
+  } catch {
+    debugQueryCache = null;
+  }
+};
 var traceDbOp = async (logger, meta, fn, options = {}) => {
   const start = performance.now();
   logger.debug({ ...meta, operation: "start" }, "start");
   try {
-    const result = await fn();
+    if (debugQueryCache === void 0) await probeDebugQuery();
+    const debugQuery = debugQueryCache;
+    const result = debugQuery ? await debugQuery(`${meta.collection}.${meta.op}`, void 0, () => fn()) : await fn();
     const durationMs = performance.now() - start;
     logger.info({ ...meta, durationMs }, "ok");
     return result;
@@ -2555,10 +2617,16 @@ var resolveQueryOptions = (options) => {
   return {
     maxAttempts,
     retryDelayMs,
-    dedupe,
-    cache,
-    retryWrites,
-    sdk: { session, maxTimeMS, hint, batchSize, drift },
+    ...dedupe !== void 0 ? { dedupe } : {},
+    ...cache !== void 0 ? { cache } : {},
+    ...retryWrites !== void 0 ? { retryWrites } : {},
+    sdk: {
+      ...session !== void 0 ? { session } : {},
+      ...maxTimeMS !== void 0 ? { maxTimeMS } : {},
+      ...hint !== void 0 ? { hint } : {},
+      ...batchSize !== void 0 ? { batchSize } : {},
+      ...drift !== void 0 ? { drift } : {}
+    },
     driverOpts: rest
   };
 };
@@ -2664,28 +2732,48 @@ var PipelineBuilder = class _PipelineBuilder {
   /* ------------------------------ terminals ---------------------------- */
   /** Run the pipeline and return every output document. */
   toArray() {
+    const run = (r) => this.deps.coll().aggregate(this.stages, this.deps.mergeDriver(r.driverOpts, r.sdk)).toArray();
+    if (this.deps.cachedAggregate) {
+      return this.deps.cachedAggregate({
+        collection: this.deps.logical,
+        opName: "mongo.pipeline",
+        pipeline: this.stages,
+        ...this.deps.options !== void 0 ? { options: this.deps.options } : {},
+        execute: run
+      });
+    }
     return defineCrudOp(
       this.deps.crudDeps,
       this.deps.logical,
       "mongo.pipeline",
-      (r) => this.deps.coll().aggregate(this.stages, this.deps.mergeDriver(r.driverOpts, r.sdk)).toArray(),
+      run,
       this.deps.options
     );
   }
   /** Run the pipeline and return the first output document (or null). */
   async first() {
+    const run = async (r) => {
+      const cursor = this.deps.coll().aggregate(this.stages, this.deps.mergeDriver(r.driverOpts, r.sdk));
+      try {
+        return await cursor.tryNext();
+      } finally {
+        await cursor.close();
+      }
+    };
+    if (this.deps.cachedAggregate) {
+      return this.deps.cachedAggregate({
+        collection: this.deps.logical,
+        opName: "mongo.pipeline.first",
+        pipeline: this.stages,
+        ...this.deps.options !== void 0 ? { options: this.deps.options } : {},
+        execute: run
+      });
+    }
     return defineCrudOp(
       this.deps.crudDeps,
       this.deps.logical,
-      "mongo.pipeline",
-      async (r) => {
-        const cursor = this.deps.coll().aggregate(this.stages, this.deps.mergeDriver(r.driverOpts, r.sdk));
-        try {
-          return await cursor.tryNext();
-        } finally {
-          await cursor.close();
-        }
-      },
+      "mongo.pipeline.first",
+      run,
       this.deps.options
     );
   }
@@ -2797,7 +2885,7 @@ var buildAggregationStages = () => {
 
 // src/service/aggregation/aggregate.ts
 var makeAggregateOps = (ctx) => {
-  const { deps: deps2, coll, mergeAggOptions: mergeAggOptions2 } = ctx;
+  const { deps: deps2, coll, mergeAggOptions: mergeAggOptions2, cachedAggregate } = ctx;
   const aggregate = async (collection, pipelineBuilder, options) => {
     const stages = buildAggregationStages();
     const pipeline2 = pipelineBuilder(stages);
@@ -2814,7 +2902,8 @@ var makeAggregateOps = (ctx) => {
     coll: () => coll(collection),
     crudDeps: deps2,
     mergeDriver: mergeAggOptions2,
-    options
+    ...options !== void 0 ? { options } : {},
+    cachedAggregate
   });
   return { aggregate, pipeline };
 };
@@ -2822,10 +2911,10 @@ var makeAggregateOps = (ctx) => {
 // src/service/aggregation/helpers.ts
 var mergeAggOptions = (driverOpts, sdk) => ({
   ...driverOpts,
-  session: sdk.session,
-  maxTimeMS: sdk.maxTimeMS,
-  hint: sdk.hint,
-  batchSize: sdk.batchSize
+  ...sdk.session !== void 0 ? { session: sdk.session } : {},
+  ...sdk.maxTimeMS !== void 0 ? { maxTimeMS: sdk.maxTimeMS } : {},
+  ...sdk.hint !== void 0 ? { hint: sdk.hint } : {},
+  ...sdk.batchSize !== void 0 ? { batchSize: sdk.batchSize } : {}
 });
 var DATE_PART_FORMATS = {
   hour: "%Y-%m-%dT%H",
@@ -2834,10 +2923,103 @@ var DATE_PART_FORMATS = {
   month: "%Y-%m",
   year: "%Y"
 };
+var collectAggSources = (primaryLogical, pipeline, extraLogical = []) => {
+  const sources = /* @__PURE__ */ new Set([primaryLogical, ...extraLogical]);
+  const visit = (stages) => {
+    if (!Array.isArray(stages)) return;
+    for (const stage of stages) {
+      if (!stage || typeof stage !== "object") continue;
+      const s2 = stage;
+      const lookup = s2.$lookup;
+      if (lookup && typeof lookup === "object") {
+        if (typeof lookup.from === "string") sources.add(lookup.from);
+        if (Array.isArray(lookup.pipeline)) visit(lookup.pipeline);
+      }
+      const union = s2.$unionWith;
+      if (union && typeof union === "object") {
+        if (typeof union.coll === "string") sources.add(union.coll);
+        if (Array.isArray(union.pipeline)) visit(union.pipeline);
+      }
+      const facet = s2.$facet;
+      if (facet && typeof facet === "object") {
+        for (const branch of Object.values(facet)) visit(branch);
+      }
+    }
+  };
+  visit(pipeline);
+  return [...sources];
+};
+var isCacheablePipeline = (pipeline) => {
+  for (const stage of pipeline) {
+    if (!stage || typeof stage !== "object") continue;
+    if ("$out" in stage || "$merge" in stage || "$sample" in stage) return false;
+    const s2 = stage;
+    const lookup = s2.$lookup;
+    if (lookup && Array.isArray(lookup.pipeline) && !isCacheablePipeline(lookup.pipeline)) {
+      return false;
+    }
+    const facet = s2.$facet;
+    if (facet && typeof facet === "object") {
+      for (const branch of Object.values(facet)) {
+        if (Array.isArray(branch) && !isCacheablePipeline(branch)) return false;
+      }
+    }
+  }
+  return true;
+};
+
+// src/service/aggregation/cached-read.ts
+var createCachedAggregate = (ctx) => {
+  const { client, deps: deps2, opts, resolve } = ctx;
+  const cache = opts.cache;
+  return async (input) => {
+    const { collection: collectionName, opName, pipeline, options, sources = [], execute } = input;
+    const collection = collectionName;
+    const physical = resolve(String(collection));
+    const resolved = resolveQueryOptions(options);
+    const noSession = !resolved.sdk.session;
+    const useCache = cache !== void 0 && noSession && resolved.cache !== false && isCacheablePipeline(pipeline);
+    const shouldDedupe = resolved.dedupe !== false && (resolved.dedupe === true || opts.dedupeReads === true && noSession) && opts.inFlight !== void 0;
+    const runDriver = () => defineCrudOp(deps2, collection, opName, execute, options);
+    const key = useCache ? cache.key(
+      cacheCollectionKey(client.databaseName, physical),
+      stableHash([opName, pipeline, options])
+    ) : void 0;
+    const toSourceKeys = () => collectAggSources(String(collection), pipeline, sources).map((name) => {
+      try {
+        return cacheCollectionKey(client.databaseName, resolve(name));
+      } catch {
+        return cacheCollectionKey(client.databaseName, name);
+      }
+    });
+    const runOnce = () => {
+      if (useCache && key) {
+        const sourceKeys = toSourceKeys();
+        const primaryKey = cacheCollectionKey(client.databaseName, physical);
+        const versions = { [primaryKey]: cache.versionOf(primaryKey) };
+        for (const col of sourceKeys) {
+          if (!(col in versions)) versions[col] = cache.versionOf(col);
+        }
+        const hit = cache.get(key);
+        if (hit !== void 0) return Promise.resolve(hit);
+        return runDriver().then((value) => {
+          cache.set(key, value, void 0, sourceKeys, versions);
+          return value;
+        });
+      }
+      return runDriver();
+    };
+    if (shouldDedupe) {
+      const dedupeKey = `${cacheCollectionKey(client.databaseName, physical)}|${opName}|${stableHash([pipeline, options])}`;
+      return opts.inFlight.run(dedupeKey, runOnce);
+    }
+    return runOnce();
+  };
+};
 
 // src/service/aggregation/group.ts
 var makeGroupOps = (ctx) => {
-  const { deps: deps2, coll, mergeAggOptions: mergeAggOptions2 } = ctx;
+  const { coll, mergeAggOptions: mergeAggOptions2, cachedAggregate } = ctx;
   const groupBy = async (collection, baseFilter, config, customization = {}, options) => {
     if (config.limit !== void 0 && (!Number.isFinite(config.limit) || config.limit < 0)) {
       throw new BadRequest("groupBy: `limit` must be a non-negative finite number");
@@ -2850,13 +3032,13 @@ var makeGroupOps = (ctx) => {
       ...config.limit !== void 0 ? [{ $limit: config.limit }] : [],
       ...customization.postPipeline ?? []
     ];
-    return defineCrudOp(
-      deps2,
+    return cachedAggregate({
       collection,
-      "mongo.groupBy",
-      (r) => coll(collection).aggregate(pipeline, mergeAggOptions2(r.driverOpts, r.sdk)).toArray(),
-      options
-    );
+      opName: "mongo.groupBy",
+      pipeline,
+      ...options !== void 0 ? { options } : {},
+      execute: (r) => coll(collection).aggregate(pipeline, mergeAggOptions2(r.driverOpts, r.sdk)).toArray()
+    });
   };
   const dateRangeAnalysis = async (collection, baseFilter, dateConfig, analysisConfig = {}, customization = {}, options) => {
     if (analysisConfig.limit !== void 0 && (!Number.isFinite(analysisConfig.limit) || analysisConfig.limit < 0)) {
@@ -2880,20 +3062,20 @@ var makeGroupOps = (ctx) => {
       ...analysisConfig.limit !== void 0 ? [{ $limit: analysisConfig.limit }] : [],
       ...customization.postPipeline ?? []
     ];
-    return defineCrudOp(
-      deps2,
+    return cachedAggregate({
       collection,
-      "mongo.dateRangeAnalysis",
-      (r) => coll(collection).aggregate(pipeline, mergeAggOptions2(r.driverOpts, r.sdk)).toArray(),
-      options
-    );
+      opName: "mongo.dateRangeAnalysis",
+      pipeline,
+      ...options !== void 0 ? { options } : {},
+      execute: (r) => coll(collection).aggregate(pipeline, mergeAggOptions2(r.driverOpts, r.sdk)).toArray()
+    });
   };
   return { groupBy, dateRangeAnalysis };
 };
 
 // src/service/aggregation/lookup-join.ts
 var makeLookupJoinOp = (ctx) => {
-  const { deps: deps2, coll, mergeAggOptions: mergeAggOptions2, resolve } = ctx;
+  const { coll, mergeAggOptions: mergeAggOptions2, resolve, cachedAggregate } = ctx;
   const lookupJoin = async (collection, baseFilter, lookups, customization = {}, options) => {
     const pipeline = [
       ...customization.prePipeline ?? [],
@@ -2912,13 +3094,15 @@ var makeLookupJoinOp = (ctx) => {
       })),
       ...customization.postPipeline ?? []
     ];
-    return defineCrudOp(
-      deps2,
+    return cachedAggregate({
       collection,
-      "mongo.lookupJoin",
-      (r) => coll(collection).aggregate(pipeline, mergeAggOptions2(r.driverOpts, r.sdk)).toArray(),
-      options
-    );
+      opName: "mongo.lookupJoin",
+      pipeline,
+      ...options !== void 0 ? { options } : {},
+      // Writes to any joined collection must invalidate the cached join.
+      sources: lookups.map((l) => l.fromCollection),
+      execute: (r) => coll(collection).aggregate(pipeline, mergeAggOptions2(r.driverOpts, r.sdk)).toArray()
+    });
   };
   return { lookupJoin };
 };
@@ -2985,10 +3169,13 @@ var buildSearchStages = (baseFilter, searchConfig) => searchConfig.useRegex ? bu
 
 // src/service/aggregation/text-search.ts
 var makeTextSearchOp = (ctx) => {
-  const { deps: deps2, coll, mergeAggOptions: mergeAggOptions2 } = ctx;
+  const { coll, mergeAggOptions: mergeAggOptions2, cachedAggregate } = ctx;
   const textSearch = async (collection, baseFilter, searchConfig, paginationConfig = {}, customization = {}, options) => {
     const normalized = normalizePageLimit(
-      { page: paginationConfig.page, limit: paginationConfig.limit },
+      {
+        ...paginationConfig.page !== void 0 ? { page: paginationConfig.page } : {},
+        ...paginationConfig.limit !== void 0 ? { limit: paginationConfig.limit } : {}
+      },
       paginationConfig.maxLimit ?? DEFAULT_MAX_LIMIT
     );
     const searchStages = buildSearchStages(
@@ -3011,19 +3198,19 @@ var makeTextSearchOp = (ctx) => {
         }
       }
     ];
-    return defineCrudOp(
-      deps2,
+    return cachedAggregate({
       collection,
-      "mongo.textSearch",
-      async (r) => {
+      opName: "mongo.textSearch",
+      pipeline,
+      ...options !== void 0 ? { options } : {},
+      execute: async (r) => {
         const rows = await coll(collection).aggregate(pipeline, mergeAggOptions2(r.driverOpts, r.sdk)).toArray();
         const row = rows[0];
         const data = row?.data ?? [];
         const totalCount = row?.totalCount?.[0]?.count ?? 0;
         return buildPaginationResult(data, totalCount, normalized.page, normalized.limit);
-      },
-      options
-    );
+      }
+    });
   };
   return { textSearch };
 };
@@ -3037,7 +3224,8 @@ var makeAggregationOps = (client, dbLabel, logger, opts) => {
     resolve,
     deps: deps2,
     coll,
-    mergeAggOptions
+    mergeAggOptions,
+    cachedAggregate: createCachedAggregate({ client, deps: deps2, opts, resolve })
   };
   return {
     ...makeAggregateOps(ctx),
@@ -3132,7 +3320,12 @@ var createCrudContext = (client, dbLabel, logger, opts) => {
       if (resolved.driverOpts.projection !== void 0) return;
       const docs = shape === "many" ? value : shape === "one" && value !== null ? [value] : [];
       checkDocsDrift(
-        { logger, db: dbLabel, drift: mode, getSchema: opts.getSchema },
+        {
+          logger,
+          db: dbLabel,
+          drift: mode,
+          ...opts.getSchema !== void 0 ? { getSchema: opts.getSchema } : {}
+        },
         String(collection),
         opName,
         docs
@@ -3155,10 +3348,12 @@ var createCrudContext = (client, dbLabel, logger, opts) => {
     });
     const runOnce = () => {
       if (useCache && key) {
+        const colKey = cacheCollectionKey(client.databaseName, physical);
+        const versions = { [colKey]: opts.cache.versionOf(colKey) };
         const hit = opts.cache.get(key);
         if (hit !== void 0) return Promise.resolve(hit);
         return fetchAndCheck().then((value) => {
-          opts.cache.set(key, value);
+          opts.cache.set(key, value, void 0, void 0, versions);
           return value;
         });
       }
@@ -3210,7 +3405,7 @@ var mergeMongoActiveFilter = (softDelete, filter) => {
 
 // src/service/crud/read-ops.ts
 var makeReadOps = (ctx) => {
-  const { client, opts } = ctx;
+  const { opts } = ctx;
   const { coll, toDriverFilter, read, normalizeFindOptions } = ctx;
   const getOne = async (collection, filter, options) => {
     const f = filter ?? {};
@@ -3223,9 +3418,9 @@ var makeReadOps = (ctx) => {
       async (r) => {
         const opts2 = {
           ...r.driverOpts,
-          session: r.sdk.session,
-          maxTimeMS: r.sdk.maxTimeMS,
-          hint: r.sdk.hint
+          ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {},
+          ...r.sdk.maxTimeMS !== void 0 ? { maxTimeMS: r.sdk.maxTimeMS } : {},
+          ...r.sdk.hint !== void 0 ? { hint: r.sdk.hint } : {}
         };
         return coll(collection).findOne(toDriverFilter(f), opts2);
       },
@@ -3268,9 +3463,9 @@ var makeReadOps = (ctx) => {
       async (r) => {
         const opts2 = {
           ...r.driverOpts,
-          session: r.sdk.session,
-          maxTimeMS: r.sdk.maxTimeMS,
-          hint: r.sdk.hint
+          ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {},
+          ...r.sdk.maxTimeMS !== void 0 ? { maxTimeMS: r.sdk.maxTimeMS } : {},
+          ...r.sdk.hint !== void 0 ? { hint: r.sdk.hint } : {}
         };
         return coll(collection).find(toDriverFilter(filter ?? {}), opts2).toArray();
       },
@@ -3317,9 +3512,9 @@ var makeReadOps = (ctx) => {
     async (r) => {
       const opts2 = {
         ...r.driverOpts,
-        session: r.sdk.session,
-        maxTimeMS: r.sdk.maxTimeMS,
-        hint: r.sdk.hint
+        ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {},
+        ...r.sdk.maxTimeMS !== void 0 ? { maxTimeMS: r.sdk.maxTimeMS } : {},
+        ...r.sdk.hint !== void 0 ? { hint: r.sdk.hint } : {}
       };
       return coll(collection).countDocuments(toDriverFilter(filter ?? {}), opts2);
     },
@@ -3336,9 +3531,9 @@ var makeReadOps = (ctx) => {
       async (r) => {
         const opts2 = {
           ...r.driverOpts,
-          session: r.sdk.session,
-          maxTimeMS: r.sdk.maxTimeMS,
-          hint: r.sdk.hint
+          ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {},
+          ...r.sdk.maxTimeMS !== void 0 ? { maxTimeMS: r.sdk.maxTimeMS } : {},
+          ...r.sdk.hint !== void 0 ? { hint: r.sdk.hint } : {}
         };
         return coll(collection).distinct(
           String(field),
@@ -3355,8 +3550,8 @@ var makeReadOps = (ctx) => {
     async (r) => {
       const opts2 = {
         ...r.driverOpts,
-        session: r.sdk.session,
-        maxTimeMS: r.sdk.maxTimeMS
+        ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {},
+        ...r.sdk.maxTimeMS !== void 0 ? { maxTimeMS: r.sdk.maxTimeMS } : {}
       };
       return coll(collection).estimatedDocumentCount(opts2);
     },
@@ -3393,9 +3588,9 @@ var makeWatchOps = (ctx) => {
         async (r) => {
           const opts = {
             ...r.driverOpts,
-            session: r.sdk.session,
-            maxTimeMS: r.sdk.maxTimeMS,
-            hint: r.sdk.hint
+            ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {},
+            ...r.sdk.maxTimeMS !== void 0 ? { maxTimeMS: r.sdk.maxTimeMS } : {},
+            ...r.sdk.hint !== void 0 ? { hint: r.sdk.hint } : {}
           };
           return execute(opts);
         },
@@ -3426,7 +3621,7 @@ var makeWriteOps = (ctx, readOps) => {
       async (r) => {
         const insertOpts = {
           ...r.driverOpts,
-          session: r.sdk.session
+          ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {}
         };
         return coll(collection).insertOne(doc, insertOpts);
       },
@@ -3456,7 +3651,7 @@ var makeWriteOps = (ctx, readOps) => {
       async (r) => {
         const bulkOpts = {
           ...r.driverOpts,
-          session: r.sdk.session
+          ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {}
         };
         return coll(collection).insertMany(
           docs,
@@ -3484,7 +3679,7 @@ var makeWriteOps = (ctx, readOps) => {
       async (r) => {
         const updateOpts = {
           ...r.driverOpts,
-          session: r.sdk.session
+          ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {}
         };
         return coll(collection).updateOne(
           toDriverFilter(filter),
@@ -3509,7 +3704,7 @@ var makeWriteOps = (ctx, readOps) => {
       async (r) => {
         const updateOpts = {
           ...r.driverOpts,
-          session: r.sdk.session
+          ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {}
         };
         return coll(collection).updateMany(
           toDriverFilter(filter),
@@ -3530,9 +3725,9 @@ var makeWriteOps = (ctx, readOps) => {
       async (r) => {
         const fOpts = {
           ...r.driverOpts,
-          session: r.sdk.session,
-          maxTimeMS: r.sdk.maxTimeMS,
-          hint: r.sdk.hint,
+          ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {},
+          ...r.sdk.maxTimeMS !== void 0 ? { maxTimeMS: r.sdk.maxTimeMS } : {},
+          ...r.sdk.hint !== void 0 ? { hint: r.sdk.hint } : {},
           // `after` is the ORM's default, but honor an explicit caller override.
           returnDocument: r.driverOpts.returnDocument ?? "after"
         };
@@ -3555,9 +3750,9 @@ var makeWriteOps = (ctx, readOps) => {
       async (r) => {
         const fOpts = {
           ...r.driverOpts,
-          session: r.sdk.session,
-          maxTimeMS: r.sdk.maxTimeMS,
-          hint: r.sdk.hint,
+          ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {},
+          ...r.sdk.maxTimeMS !== void 0 ? { maxTimeMS: r.sdk.maxTimeMS } : {},
+          ...r.sdk.hint !== void 0 ? { hint: r.sdk.hint } : {},
           // `after` is the ORM's default, but honor an explicit caller override.
           returnDocument: r.driverOpts.returnDocument ?? "after"
         };
@@ -3579,7 +3774,7 @@ var makeWriteOps = (ctx, readOps) => {
       async (r) => {
         const repOpts = {
           ...r.driverOpts,
-          session: r.sdk.session
+          ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {}
         };
         return coll(collection).replaceOne(
           toDriverFilter(filter),
@@ -3603,7 +3798,7 @@ var makeWriteOps = (ctx, readOps) => {
       async (r) => {
         const delOpts = {
           ...r.driverOpts,
-          session: r.sdk.session
+          ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {}
         };
         return coll(collection).deleteOne(toDriverFilter(filter), delOpts);
       },
@@ -3623,7 +3818,7 @@ var makeWriteOps = (ctx, readOps) => {
       async (r) => {
         const delOpts = {
           ...r.driverOpts,
-          session: r.sdk.session
+          ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {}
         };
         return coll(collection).deleteMany(toDriverFilter(filter), delOpts);
       },
@@ -3639,9 +3834,9 @@ var makeWriteOps = (ctx, readOps) => {
       async (r) => {
         const fOpts = {
           ...r.driverOpts,
-          session: r.sdk.session,
-          maxTimeMS: r.sdk.maxTimeMS,
-          hint: r.sdk.hint
+          ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {},
+          ...r.sdk.maxTimeMS !== void 0 ? { maxTimeMS: r.sdk.maxTimeMS } : {},
+          ...r.sdk.hint !== void 0 ? { hint: r.sdk.hint } : {}
         };
         return coll(collection).findOneAndDelete(
           toDriverFilter(filter),
@@ -3661,7 +3856,7 @@ var makeWriteOps = (ctx, readOps) => {
       async (r) => {
         const updateOpts = {
           ...r.driverOpts,
-          session: r.sdk.session
+          ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {}
         };
         return coll(collection).updateOne(
           active,
@@ -3682,7 +3877,7 @@ var makeWriteOps = (ctx, readOps) => {
       async (r) => {
         const updateOpts = {
           ...r.driverOpts,
-          session: r.sdk.session,
+          ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {},
           upsert: true
         };
         return coll(collection).updateOne(toDriverFilter(filter), formatted, updateOpts);
@@ -3711,7 +3906,7 @@ var makeWriteOps = (ctx, readOps) => {
       async (r) => {
         const bulkOpts = {
           ...r.driverOpts,
-          session: r.sdk.session
+          ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {}
         };
         return coll(collection).bulkWrite(writes, bulkOpts);
       },
@@ -3732,7 +3927,7 @@ var makeWriteOps = (ctx, readOps) => {
       async (r) => {
         const bulkOpts = {
           ...r.driverOpts,
-          session: r.sdk.session
+          ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {}
         };
         return coll(collection).bulkWrite(operations, bulkOpts);
       },
@@ -3870,7 +4065,7 @@ var makePaginateCursor = (ctx) => {
       throw new BadRequest("paginateCursor: provide either `after` or `before`, not both");
     }
     const limit = normalizePageLimit(
-      { page: 1, limit: config.limit },
+      { page: 1, ...config.limit !== void 0 ? { limit: config.limit } : {} },
       config.maxLimit ?? DEFAULT_MAX_LIMIT,
       { limit: DEFAULT_FIND_LIMIT }
     ).limit;
@@ -3897,9 +4092,9 @@ var makePaginateCursor = (ctx) => {
       async (r) => {
         const findOpts = {
           ...r.driverOpts,
-          session: r.sdk.session,
-          maxTimeMS: r.sdk.maxTimeMS,
-          hint: r.sdk.hint
+          ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {},
+          ...r.sdk.maxTimeMS !== void 0 ? { maxTimeMS: r.sdk.maxTimeMS } : {},
+          ...r.sdk.hint !== void 0 ? { hint: r.sdk.hint } : {}
         };
         return client.collection(resolve(String(collection))).find(filter, findOpts).sort(effectiveSort).limit(limit + 1).toArray();
       },
@@ -3912,7 +4107,7 @@ var makePaginateCursor = (ctx) => {
         logger,
         db: dbLabel,
         drift: resolveDriftMode(config.queryOptions?.drift, opts.drift),
-        getSchema: opts.getSchema
+        ...opts.getSchema !== void 0 ? { getSchema: opts.getSchema } : {}
       },
       String(collection),
       "mongo.paginateCursor",
@@ -3930,10 +4125,13 @@ var makePaginateCursor = (ctx) => {
 
 // src/service/pagination/offset.ts
 var makePaginateFlexible = (ctx) => {
-  const { client, dbLabel, logger, opts, resolve, deps: deps2 } = ctx;
+  const { client, dbLabel, logger, opts, resolve, cachedAggregate } = ctx;
   const paginateFlexible = async (collection, baseFilter, config = {}) => {
     const normalized = normalizePageLimit(
-      { page: config.page, limit: config.limit },
+      {
+        ...config.page !== void 0 ? { page: config.page } : {},
+        ...config.limit !== void 0 ? { limit: config.limit } : {}
+      },
       config.maxLimit ?? DEFAULT_MAX_LIMIT
     );
     const dataStages = [
@@ -3952,17 +4150,18 @@ var makePaginateFlexible = (ctx) => {
         }
       }
     ];
-    return defineCrudOp(
-      deps2,
+    return cachedAggregate({
       collection,
-      "mongo.paginateFlexible",
-      async (r) => {
+      opName: "mongo.paginateFlexible",
+      pipeline,
+      ...config.queryOptions !== void 0 ? { options: config.queryOptions } : {},
+      execute: async (r) => {
         const aggOptions = {
           ...r.driverOpts,
-          session: r.sdk.session,
-          maxTimeMS: r.sdk.maxTimeMS,
-          hint: r.sdk.hint,
-          batchSize: r.sdk.batchSize
+          ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {},
+          ...r.sdk.maxTimeMS !== void 0 ? { maxTimeMS: r.sdk.maxTimeMS } : {},
+          ...r.sdk.hint !== void 0 ? { hint: r.sdk.hint } : {},
+          ...r.sdk.batchSize !== void 0 ? { batchSize: r.sdk.batchSize } : {}
         };
         const rows = await client.collection(resolve(String(collection))).aggregate(pipeline, aggOptions).toArray();
         const row = rows[0];
@@ -3973,16 +4172,15 @@ var makePaginateFlexible = (ctx) => {
             logger,
             db: dbLabel,
             drift: resolveDriftMode(config.queryOptions?.drift, opts.drift),
-            getSchema: opts.getSchema
+            ...opts.getSchema !== void 0 ? { getSchema: opts.getSchema } : {}
           },
           String(collection),
           "mongo.paginateFlexible",
           data
         );
         return buildPaginationResult(data, totalCount, normalized.page, normalized.limit);
-      },
-      config.queryOptions
-    );
+      }
+    });
   };
   return { paginateFlexible };
 };
@@ -3997,7 +4195,8 @@ var makePaginationOps = (client, dbLabel, logger, opts) => {
     logger,
     opts,
     resolve,
-    deps: deps2
+    deps: deps2,
+    cachedAggregate: createCachedAggregate({ client, deps: deps2, opts, resolve })
   };
   return {
     ...makePaginateFlexible(ctx),
@@ -4174,23 +4373,29 @@ var buildManager = (deps2, dbKey, dbName, client) => {
   const crud = makeCrudOps(handle, dbName, logger, {
     resolveCollectionName,
     wrapMongoErrors: deps2.wrapMongoErrors,
-    cache: sharedCache,
+    ...sharedCache !== void 0 ? { cache: sharedCache } : {},
     dedupeReads,
     inFlight,
     hooks,
     timestamps,
-    drift: deps2.drift,
-    getSchema: (logical) => getDefinition(logical)?.schema
+    ...deps2.drift !== void 0 ? { drift: deps2.drift } : {},
+    ...getDefinition !== void 0 ? { getSchema: (logical) => getDefinition(logical)?.schema } : {}
   });
   const pagination = makePaginationOps(handle, dbName, logger, {
     resolveCollectionName,
     wrapMongoErrors: deps2.wrapMongoErrors,
-    drift: deps2.drift,
-    getSchema: (logical) => getDefinition(logical)?.schema
+    ...deps2.drift !== void 0 ? { drift: deps2.drift } : {},
+    ...getDefinition !== void 0 ? { getSchema: (logical) => getDefinition(logical)?.schema } : {},
+    ...sharedCache !== void 0 ? { cache: sharedCache } : {},
+    dedupeReads,
+    inFlight
   });
   const aggregation = makeAggregationOps(handle, dbName, logger, {
     resolveCollectionName,
-    wrapMongoErrors: deps2.wrapMongoErrors
+    wrapMongoErrors: deps2.wrapMongoErrors,
+    ...sharedCache !== void 0 ? { cache: sharedCache } : {},
+    dedupeReads,
+    inFlight
   });
   const schema = makeSchemaOps(handle, logger, { resolveCollectionName, getDefinition });
   const transactionOps = makeTransactionOps(client, handle, logger, config, {
@@ -4201,7 +4406,7 @@ var buildManager = (deps2, dbKey, dbName, client) => {
     findMany: async (logical, filter, options) => {
       const physical = resolveCollectionName(logical);
       return handle.collection(physical).find(filter, {
-        projection: options?.projection,
+        ...options?.projection !== void 0 ? { projection: options.projection } : {},
         limit: options?.limit ?? 1e4
       }).toArray();
     }
@@ -4241,11 +4446,11 @@ var createMongoService = (dbClients, configOverrides = {}) => {
         dbClients,
         config,
         logger,
-        sharedCache,
+        ...sharedCache !== void 0 ? { sharedCache } : {},
         dedupeReads,
         inFlight,
         wrapMongoErrors: runtime.wrapMongoErrors,
-        drift: configOverrides.drift,
+        ...configOverrides.drift !== void 0 ? { drift: configOverrides.drift } : {},
         collectionRefs,
         db
       },