@anteros/core 0.0.25 → 0.0.26

package/database/db.cache.ts

@@ -0,0 +1,197 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import type { FindOptions, FindCallOptions } from "../types/mongo";
+import { Cache, useFilesystemCache, useMemoryCache, useRedisCache } from "../utils/cache";
+import { cfg } from "../server/config";
+
+/**
+ * DB query cache — cache-aside for `find` with `{ useCache: true }`.
+ * (`findOne` is never cached — point queries, no gain.)
+ *
+ * - Key = sha1(collection params + options) → stored in a per-collection namespace
+ *   (`db:{tenant}:{collection}`).
+ * - Every cached query is **tagged with the `_id`s of its results** (including the
+ *   `_id`s of `$include`d documents) via bentocache's client-side tagging
+ *   (`ctx.setTags` — adaptive caching, tags known after the factory runs).
+ * - On a write with known ids (update/delete), `deleteByTag` removes exactly the
+ *   cached queries whose result contains one of those `_id`s (targeted). Writes
+ *   with unknown/new ids (insert, bulk, findOneAndUpdate) clear the namespace.
+ * - Relations are tracked: if `orders` caches a query with `$include: ['clients']`,
+ *   its entries are tagged with the embedded client `_id`s too — so modifying a
+ *   client invalidates exactly the `orders` queries that embed it.
+ */
+
+const NAMESPACE = 'db';
+const REL_NS = 'db:rel';
+
+/** Sanitary cap on tags per entry (bentocache high-cardinality guidance) — configurable via `server.cache.maxTags`. The cost is ~0.18µs per tag check on each hit, negligible vs the cost of the real query */
+const DEFAULT_MAX_TAGS = 50_000;
+
+let dbCache: Cache | null = null;
+
+/** Lazy singleton — configured once from `cfg.server.cache` (default: memory) */
+function resolveCache(): Cache {
+    if (!dbCache) {
+        const conf = cfg.server.cache ?? {};
+        const driver = conf.driver ?? 'memory';
+        if (driver === 'redis') {
+            dbCache = useRedisCache({
+                connection: {
+                    host: conf.redis?.host ?? 'localhost',
+                    port: conf.redis?.port ?? 6379,
+                    password: conf.redis?.password ?? '',
+                },
+                pruneInterval: conf.pruneInterval,
+            });
+        } else if (driver === 'filesystem') {
+            dbCache = useFilesystemCache({
+                directory: conf.directory ?? path.join(process.cwd(), '.cache'),
+                pruneInterval: conf.pruneInterval ?? '1h',
+            });
+        } else {
+            dbCache = useMemoryCache();
+        }
+    }
+    return dbCache;
+}
+
+function isEnabled(): boolean {
+    // Opt-in: the DB query cache is disabled unless `cache.enabled: true`
+    return cfg.server.cache?.enabled === true;
+}
+
+function colNs(tenant: string, collection: string): string {
+    return `${NAMESPACE}:${tenant}:${collection}`;
+}
+
+function relNs(tenant: string): string {
+    return `${REL_NS}:${tenant}`;
+}
+
+function hashQuery(params: FindOptions, options: FindCallOptions = {}): string {
+    return createHash('sha1').update(JSON.stringify({ params, options })).digest('hex');
+}
+
+/** Effective TTL: query option (server-side only) > collection def > server config > default '5m' */
+function ttlFor(collection: string, optionsTtl?: string | number): string | number {
+    const col = cfg.collections?.find((c) => c.slug === collection);
+    return optionsTtl ?? col?.cache?.ttl ?? cfg.server.cache?.ttl ?? '5m';
+}
+
+/** `$include` field names — used to tag embedded `_id`s for cross-collection invalidation */
+function includeFields(params: FindOptions): string[] {
+    return (params.$include ?? []).map((inc) => (typeof inc === 'string' ? inc : inc?.localField ?? inc?.from ?? '')).filter(Boolean);
+}
+
+/** Collect the `_id`s of a result — main docs + `$include`d embedded docs */
+function extractResultIds(result: any, includes: string[]): string[] {
+    const ids = new Set<string>();
+    const add = (v: any) => {
+        if (v && typeof v === 'object' && v._id !== undefined) ids.add(String(v._id));
+    };
+    for (const doc of Array.isArray(result) ? result : [result]) {
+        add(doc);
+        for (const inc of includes) {
+            const embedded = doc?.[inc];
+            if (Array.isArray(embedded)) embedded.forEach(add);
+            else add(embedded);
+        }
+    }
+    return [...ids];
+}
+
+/**
+ * Cache-aside read-through: serve the cached result for this query, otherwise run
+ * the factory (the real query) and store it, tagged by the result `_id`s.
+ */
+export async function dbGetOrSet<T>(
+    collection: string,
+    tenant: string,
+    params: FindOptions,
+    options: FindCallOptions,
+    factory: () => Promise<T>,
+): Promise<T> {
+    if (!isEnabled()) return factory();
+    const cache = resolveCache();
+    const key = hashQuery(params, options);
+    const ns = cache.namespace(colNs(tenant, collection));
+    const includes = includeFields(params);
+
+    // Adaptive caching: the tags (result `_id`s) are only known after the factory runs
+    const value = await ns.getOrSet({
+        key,
+        ttl: ttlFor(collection, options.ttl),
+        factory: async (ctx: any) => {
+            const fresh = await factory();
+            const maxTags = cfg.server.cache?.maxTags ?? DEFAULT_MAX_TAGS;
+            const tags = extractResultIds(fresh, includes).slice(0, maxTags).map((id) => `id:${id}`);
+            if (tags.length) ctx.setTags(tags);
+            return fresh;
+        },
+    });
+
+    await recordRelations(cache, tenant, collection, params);
+    return value as T;
+}
+
+/**
+ * Register the collections this query depends on (via `$include` / `$lookup`) so a
+ * write on the *included* collection invalidates the *parent* collection too.
+ */
+async function recordRelations(cache: Cache, tenant: string, collection: string, params: FindOptions) {
+    const col = cfg.collections?.find((c) => c.slug === collection && c._tenant_ === tenant);
+    const targets = new Set<string>();
+    for (const inc of params.$include ?? []) {
+        if (typeof inc === 'string') {
+            const f = col?.fields.find((f) => f.name === inc);
+            if (f?.type === 'relationship' && f.relation?.to) targets.add(f.relation.to);
+        } else if (inc?.from) {
+            targets.add(inc.from);
+        }
+    }
+    if (!targets.size) return;
+    const rel = cache.namespace(relNs(tenant));
+    for (const target of targets) {
+        if (target === collection) continue;
+        const deps = ((await rel.get({ key: target })) as string[]) ?? [];
+        if (!deps.includes(collection)) {
+            deps.push(collection);
+            await rel.set({ key: target, value: deps, ttl: '7d' });
+        }
+    }
+}
+
+/**
+ * Invalidate a collection's cached queries after a write.
+ * - `ids` provided (update/delete of known documents) → **targeted**: only the
+ *   cached queries tagged with one of those `_id`s are removed (deleteByTag).
+ * - `ids` omitted (insert, bulk, unknown) → the whole collection namespace is cleared.
+ * Relations ($include) are invalidated the same way on the dependent collections.
+ */
+export async function dbInvalidate(collection: string, tenant: string, ids?: string[]) {
+    if (!isEnabled()) return;
+    const cache = resolveCache();
+    const ns = cache.namespace(colNs(tenant, collection));
+
+    if (ids?.length) {
+        // String(id) normalizes native ObjectIds to their 24-hex form
+        await ns.deleteByTag({ tags: ids.map((id) => `id:${String(id)}`) });
+    } else {
+        await ns.clear();
+    }
+
+    // Relations: collections that $include this one embed its docs → invalidate them too
+    const rel = cache.namespace(relNs(tenant));
+    const dependents = ((await rel.get({ key: collection })) as string[]) ?? [];
+    for (const dep of dependents) {
+        const depNs = cache.namespace(colNs(tenant, dep));
+        if (ids?.length) {
+            await depNs.deleteByTag({ tags: ids.map((id) => `id:${String(id)}`) });
+        } else {
+            await depNs.clear();
+        }
+    }
+    await rel.set({ key: collection, value: [] });
+}
+
+export { resolveCache as getDbCache };

package/database/decorator.ts

@@ -1,6 +1,38 @@
 import { ObjectId } from "mongodb";
 import { getCollection } from "./collection";
 import { AppError } from "../lib/error";
+import { logger } from "../utils/logger";
+import { cfg } from "../server/config";
+
+
+// Logs operations slower than cfg.server.logging.slowQueryMs (default 200ms) —
+// the MongoDB-style slow query log for Anteros
+
+export function LogSlowQuery(): any {
+    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor): any {
+        if (!descriptor || !descriptor.value) {
+            return descriptor;
+        }
+        const originalMethod = descriptor.value;
+        descriptor.value = async function (this: any, ...args: any[]) {
+            const start = performance.now();
+            try {
+                return await originalMethod.apply(this, args);
+            } finally {
+                const duration = performance.now() - start;
+                const slowMs = cfg.server.logging?.slowQueryMs ?? 200;
+                if (duration >= slowMs) {
+                    logger.warn(`Slow ${propertyKey} (${Math.round(duration)}ms)`, {
+                        collection: args[0],
+                        tenant: this.tenant_id,
+                        duration: Math.round(duration),
+                    });
+                }
+            }
+        };
+        return descriptor;
+    }
+}
 
 
 // decoration function checkCollectionExists

package/database/mongodbadapter.ts

@@ -3,16 +3,18 @@ import type { Tenant } from "../types/tenant";
 import type { MongoClientOptions, Db, ClientSession, UpdateOptions, UpdateFilter, Document, DeleteResult, ChangeStreamOptions, ChangeStream, ChangeStreamDocument, AnyBulkWriteOperation, BulkWriteOptions, BulkWriteResult, UpdateResult } from "mongodb";
 import { MongoClient, ObjectId, AggregationCursor } from "mongodb";
 import type { FindOptions, findOneOptions } from "../types/mongo";
+import type { FindCallOptions } from "../types/mongo";
+import { dbGetOrSet, dbInvalidate, getDbCache } from "./db.cache";
 import { sessionCtxStorage, asyncContextStorage, requestCtxStorage } from "../lib/asyncContextStorage";
 import * as func from "../utils/func"
 import { AppError, fn } from "../lib/error";
 import { createWorkflow } from "./workflow";
 import { getTenant } from "./tenant";
 import { getCollection, getCollectionKeys } from "./collection"
-import type { RestActions, BulkUpdateOperation, RestOptions } from "../types/rest";
+import type { RestActions, BulkUpdateOperation, RestOptions, CursorOptions, TenantCache } from "../types/rest";
 import type Joi from "joi";
 import type { Collection } from "../types/collection";
-import { CheckBulkWriteOperations, CheckIfCollectionExists, CheckIfId, CheckInsertData, CheckIfArrayOfIds, CheckFilter } from "./decorator";
+import { CheckBulkWriteOperations, CheckIfCollectionExists, CheckIfId, CheckInsertData, CheckIfArrayOfIds, CheckFilter, LogSlowQuery } from "./decorator";
 import type { ActionsApiList, updateApiOptions } from "../types/api";
 import type { ActivityInput } from "../types/activity";
 import * as os from 'node:os';
@@ -214,13 +216,20 @@ class MongoRest {
         action: string,
         collection: string,
         input: any,
-        fn: () => Promise<T>
+        fn: () => Promise<T>,
+        options?: { invalidate?: boolean | string[] }
     ): Promise<T> {
         const start = Date.now()
         try {
             const result = await fn()
             const duration = Date.now() - start
             this.#logActivity({ action, collection, input, result, duration })
+            // Writes invalidate the collection's query cache (and its $include dependents).
+            // An array of ids = targeted invalidation (only queries containing those ids),
+            // `true` = clear the whole collection namespace.
+            if (options?.invalidate) {
+                await this.#invalidateCache(collection, typeof options.invalidate === 'boolean' ? undefined : options.invalidate)
+            }
             return result
         } catch (err: any) {
             const duration = Date.now() - start
@@ -229,6 +238,11 @@ class MongoRest {
         }
     }
 
+    /** Invalidate the DB query cache for a collection after a write (targeted by ids when known) */
+    #invalidateCache(collection: string, ids?: string[]) {
+        return dbInvalidate(collection, this.tenant_id, ids)
+    }
+
     async connect(options?: {
         uri?: string;
         options?: MongoClientOptions;
@@ -269,6 +283,7 @@ class MongoRest {
         })
     }
 
+    @LogSlowQuery()
     @CheckIfCollectionExists()
     async aggregate(collection: string, pipeline: any[]): Promise<Document[]> {
         const action = 'aggregate' as ActionsApiList
@@ -310,38 +325,192 @@ class MongoRest {
         }
     }
 
+    /**
+     * Apply cursor methods (batchSize, maxTimeMS). comment/hint are passed
+     * through the aggregate() options (not available on AggregationCursor in v7).
+     */
+    #applyCursorOptions(cursor: AggregationCursor, options: CursorOptions) {
+        if (options.batchSize) cursor.batchSize(options.batchSize)
+        if (options.maxTimeMS) cursor.maxTimeMS(options.maxTimeMS)
+    }
 
+    /**
+     * Stream `find`-style results one by one — JSON-converted docs, cursor auto-closed.
+     * Iterates everything (no default $limit, unlike find() which caps at 100).
+     *
+     * With `{ withCount: true }`, a background `countDocuments` runs in parallel
+     * and each yielded item becomes `{ count, doc }` — the total + the document.
+     *
+     * @example
+     * for await (const doc of rest.findStream('orders', { $match: { status: 'paid' } }, { batchSize: 500 })) { … }
+     * for await (const d of rest.findStream('orders', { $match: { status: 'paid' } }, { withCount: true })) {
+     *   console.log(d.count, d.doc); // total + document
+     * }
+     * for await (const u of rest.findStream<User>('users', { $match: { active: true } }, {
+     *   map: (u) => ({ id: u._id, name: u.name }),
+     *   signal: controller.signal,
+     * })) { … }
+     * // Page mode: { pageSize } yields { count, docs, hasNext() } batches
+     * for await (const page of rest.findStream('orders', { $match: { status: 'paid' } }, { pageSize: 50 })) {
+     *   console.log(page.count, page.docs.length, page.hasNext());
+     * }
+     */
     @CheckIfCollectionExists()
-    async find(collection: string, params: FindOptions = {}, options = {}): Promise<Document[]> {
-        const action = 'find' as ActionsApiList
+    async *findStream<T = any>(collection: string, params: FindOptions = {}, options: CursorOptions = {}): AsyncGenerator<any> {
+        const pageSize = options.pageSize;
+        // Page mode counts by default (opt-out with withCount: false); per-doc mode counts only when withCount: true
+        const withCount = pageSize ? options.withCount !== false : options.withCount === true;
+        // Background total count (runs in parallel with the iteration)
+        const countPromise = withCount
+            ? this.countDocuments(collection, params.$match ?? {})
+            : null;
+        const col = getCollection(collection, this.#tenant.id) as Collection
+        let pipeline = func.buildPipeline({ ...params, $limit: params.$limit ?? 0 }, { col: col })
+        pipeline = await func.buildInput(pipeline, { rest: this })
+        pipeline = func.toBson(pipeline, { col })
+        const cursor = this.db.collection(collection).aggregate(pipeline, {
+            session: this.session,
+            allowDiskUse: true,
+            comment: options.comment,
+            hint: options.hint,
+        }) as AggregationCursor
+        this.#applyCursorOptions(cursor, options)
+        // Resolve the count ONCE before iterating — the value is reused on every yield
+        const count = countPromise ? await countPromise : null
         try {
-            const col = getCollection(collection, this.#tenant.id) as Collection
-            let pipeline = func.buildPipeline(params, { col: col })
-            pipeline = await func.buildInput(pipeline, { rest: this })
-            pipeline = func.toBson(pipeline, { col })
-
-            const meta: any = { action, collection, params, options }
-            if (col.hooks?.beforeOperation) {
-                await col.hooks.beforeOperation({ rest: this, io, action, meta })
+            if (pageSize) {
+                // ── Page mode: batches of `pageSize` → { count?, docs, hasNext() } ──
+                while (await cursor.hasNext()) {
+                    if (options.signal?.aborted) break
+                    const docs: any[] = []
+                    for (let i = 0; i < pageSize && await cursor.hasNext(); i++) {
+                        let value: any = func.toJson(await cursor.next())
+                        if (options.map) value = options.map(value as T)
+                        docs.push(value)
+                    }
+                    const hasMore = await cursor.hasNext()
+                    yield {
+                        ...(withCount ? { count } : {}),
+                        docs,
+                        hasNext: () => hasMore,
+                    }
+                }
+            } else {
+                // ── Per-doc mode: doc or { count, doc } ──
+                for await (const doc of cursor) {
+                    if (options.signal?.aborted) break
+                    let value: any = func.toJson(doc)
+                    if (options.map) value = options.map(value as T)
+                    if (options.withCount) {
+                        yield { count, doc: value }
+                    } else {
+                        yield value
+                    }
+                }
             }
+        } finally {
+            await cursor.close().catch(() => {})
+        }
+    }
 
-            let result = await this.db.collection(collection).aggregate(pipeline, {
+    /**
+     * Stream `aggregate` results one by one (same safety checks as `aggregate`) —
+     * JSON-converted docs, cursor auto-closed.
+     *
+     * @example
+     * for await (const doc of rest.aggregateStream('orders', [{ $match: { status: 'paid' } }], { batchSize: 500 })) { … }
+     * for await (const d of rest.aggregateStream('orders', [{ $group: { _id: '$status', n: { $sum: 1 } } }], { withCount: true })) {
+     *   console.log(d.count, d.doc); // total pipeline results + each doc
+     * }
+     */
+    @CheckIfCollectionExists()
+    async *aggregateStream<T = any>(collection: string, pipeline: any[] = [], options: CursorOptions = {}): AsyncGenerator<any> {
+        const col = getCollection(collection, this.#tenant.id) as Collection
+        const allowedCollections = [
+            ...(cfg.collections ?? []).filter((c) => c._tenant_ === this.tenant_id).map((c) => c.slug),
+            ...(cfg.fileCollections ?? []).filter((fc) => fc._tenant_ === this.tenant_id).map((fc) => fc.slug),
+            '_activities_', '_locks_', '_workflows_',
+        ];
+        const isSafe = func.isSafeAggregatePipeline(pipeline, allowedCollections);
+        if (!isSafe.isSafe) {
+            throw isSafe.error;
+        }
+        pipeline = func.toBson(pipeline, { col })
+        // Background total count of the pipeline OUTPUT (via a $count stage) —
+        // parallel with the iteration; best-effort (fails silently for $out/$merge)
+        const countPromise = options.withCount
+            ? this.db.collection(collection).aggregate([...pipeline, { $count: 'count' }], {
                 session: this.session,
-                allowDiskUse: true
-            }).toArray()
-            result = func.toJson(result)
-            meta.result = result
+                allowDiskUse: true,
+            }).toArray().then((r) => (r[0]?.count as number) ?? 0).catch(() => 0)
+            : null;
+        const cursor = this.db.collection(collection).aggregate(pipeline, {
+            session: this.session,
+            allowDiskUse: true,
+            comment: options.comment,
+            hint: options.hint,
+        }) as AggregationCursor
+        this.#applyCursorOptions(cursor, options)
+        // Resolve the count ONCE before iterating — the value is reused on every yield
+        const count = countPromise ? await countPromise : null
+        try {
+            for await (const doc of cursor) {
+                if (options.signal?.aborted) break
+                let value: any = func.toJson(doc)
+                if (options.map) value = options.map(value as T)
+                if (options.withCount) {
+                    yield { count, doc: value }
+                } else {
+                    yield value
+                }
+            }
+        } finally {
+            await cursor.close().catch(() => {})
+        }
+    }
 
-            if (col.hooks?.afterOperation) {
-                await col.hooks.afterOperation({ rest: this, io, action, meta })
+    @LogSlowQuery()
+    @CheckIfCollectionExists()
+    async find(collection: string, params: FindOptions = {}, options: FindCallOptions = {}): Promise<Document[]> {
+        const action = 'find' as ActionsApiList
+        try {
+            // Real query — hooks + pipeline + toArray
+            const run = async (): Promise<Document[]> => {
+                const col = getCollection(collection, this.#tenant.id) as Collection
+                let pipeline = func.buildPipeline(params, { col: col })
+                pipeline = await func.buildInput(pipeline, { rest: this })
+                pipeline = func.toBson(pipeline, { col })
+
+                const meta: any = { action, collection, params, options }
+                if (col.hooks?.beforeOperation) {
+                    await col.hooks.beforeOperation({ rest: this, io, action, meta })
+                }
+
+                let result = await this.db.collection(collection).aggregate(pipeline, {
+                    session: this.session,
+                    allowDiskUse: true
+                }).toArray()
+                result = func.toJson(result)
+                meta.result = result
+
+                if (col.hooks?.afterOperation) {
+                    await col.hooks.afterOperation({ rest: this, io, action, meta })
+                }
+
+                return result as any[]
             }
 
-            return result as any[]
+            // Cache-first when `useCache: true` — served from the query cache, populated on miss
+            if (options.useCache === true) {
+                return await dbGetOrSet(collection, this.tenant_id, params, options, run)
+            }
+            return await run()
         } catch (err: any) {
             throw err instanceof AppError ? err : new AppError(err?.message || 'Internal server error', { code: 'INTERNAL_API_ERROR', status: 500 })
         }
     }
 
+    @LogSlowQuery()
     @CheckIfCollectionExists()
     async findOne(collection: string, _id: string, params?: findOneOptions): Promise<any> {
         const action = 'findOne' as ActionsApiList
@@ -377,6 +546,7 @@ class MongoRest {
         }
     }
 
+    @LogSlowQuery()
     @CheckIfCollectionExists()
     @CheckInsertData('insertOne')
     async insertOne<T>(collection: string, data: T): Promise<T & { _id: string }> {
@@ -406,9 +576,10 @@ class MongoRest {
             }
 
             return result
-        })
+        }, { invalidate: true })
     }
 
+    @LogSlowQuery()
     @CheckIfCollectionExists()
     @CheckInsertData('insertMany')
     async insertMany<T>(collection: string, data: T[]): Promise<(T & { _id: string })[]> {
@@ -445,9 +616,10 @@ class MongoRest {
             }
 
             return result as (T & { _id: string })[]
-        })
+        }, { invalidate: true })
     }
 
+    @LogSlowQuery()
     @CheckIfCollectionExists()
     @CheckIfId('updateOne')
     async updateOne(collection: string, _id: string, update: UpdateFilter<any>) {
@@ -482,9 +654,10 @@ class MongoRest {
             }
 
             return result
-        })
+        }, { invalidate: [_id] })
     }
 
+    @LogSlowQuery()
     @CheckIfCollectionExists()
     @CheckFilter()
     async findOneAndUpdate(collection: string, filter: Document, update: UpdateFilter<any>, options?: updateApiOptions): Promise<Document | null> {
@@ -549,9 +722,10 @@ class MongoRest {
             }
 
             return result as Document | null
-        })
+        }, { invalidate: true })
     }
 
+    @LogSlowQuery()
     @CheckIfCollectionExists()
     @CheckIfArrayOfIds('updateMany')
     async updateMany(collection: string, _ids: string[], update: UpdateFilter<any>): Promise<UpdateResult> {
@@ -583,9 +757,10 @@ class MongoRest {
             }
 
             return result as UpdateResult
-        })
+        }, { invalidate: _ids })
     }
 
+    @LogSlowQuery()
     @CheckIfCollectionExists()
     @CheckIfId('deleteOne')
     async deleteOne(collection: string, _id: string) {
@@ -610,10 +785,11 @@ class MongoRest {
             }
 
             return result
-        })
+        }, { invalidate: [_id] })
     }
 
 
+    @LogSlowQuery()
     @CheckIfCollectionExists()
     @CheckIfArrayOfIds('deleteMany')
     async deleteMany(collection: string, _ids: string[]): Promise<DeleteResult> {
@@ -638,10 +814,11 @@ class MongoRest {
             }
 
             return result
-        })
+        }, { invalidate: _ids })
     }
 
 
+    @LogSlowQuery()
     @CheckIfCollectionExists()
     @CheckBulkWriteOperations()
     async bulkWrite(collection: string, operations: AnyBulkWriteOperation[], options?: BulkWriteOptions): Promise<BulkWriteResult> {
@@ -704,10 +881,11 @@ class MongoRest {
             })
 
             return result
-        })
+        }, { invalidate: true })
     }
 
 
+    @LogSlowQuery()
     @CheckIfCollectionExists()
     async bulkUpdate(collection: string, operations: BulkUpdateOperation[], options?: BulkWriteOptions): Promise<BulkWriteResult> {
         const action = 'bulkUpdate' as ActionsApiList
@@ -737,16 +915,18 @@ class MongoRest {
             })
 
             return result
-        })
+        }, { invalidate: true })
     }
 
 
 
+    @LogSlowQuery()
     @CheckIfCollectionExists()
     async countDocuments(collection: string, query: any = {}): Promise<number> {
         const action = 'countDocuments' as ActionsApiList
         return this.#executeWithAudit(action, collection, { query }, async () => {
-            return await this.db.collection(collection).countDocuments()
+            // ⚠️ must pass the filter — countDocuments() without args counts the whole collection
+            return await this.db.collection(collection).countDocuments(query)
         })
     }
 
@@ -755,7 +935,7 @@ class MongoRest {
         const action = 'dropCollection' as ActionsApiList
         return this.#executeWithAudit(action, collection, undefined, async () => {
             return await this.db.collection(collection).drop()
-        })
+        }, { invalidate: true })
     }
 
     @CheckIfCollectionExists()
@@ -921,6 +1101,38 @@ class MongoRest {
         }
     }
 
+    /**
+     * Tenant-scoped cache — `rest.cache.*` stores under the `app:{tenant_id}`
+     * namespace, so keys never collide across tenants. Uses the configured
+     * cache driver (server.cache — default filesystem ./.cache).
+     *
+     * @example
+     * await rest.cache.set('price:42', { total: 99 }, '5m');
+     * const v = await rest.cache.getOrSet('stats', () => rest.aggregate('orders', [...]), '1h');
+     * await rest.cache.delete('price:42');
+     * await rest.cache.clear();
+     */
+    get cache(): TenantCache {
+        const tenantId = this.tenant_id;
+        const cache = getDbCache();
+        const ns = () => cache.namespace(`app:${tenantId}`);
+        return {
+            set: (key, value, ttl = '5m') => ns().set({ key, value, ttl }),
+            setForever: (key, value) => ns().setForever({ key, value }),
+            get: (key) => ns().get({ key }),
+            getOrSet: (key, factory, ttl = '5m') => ns().getOrSet({ key, factory, ttl }),
+            getOrSetForever: (key, factory) => ns().getOrSetForever({ key, factory }),
+            has: (key) => ns().has({ key }),
+            missing: (key) => ns().missing({ key }),
+            delete: (key) => ns().delete({ key }),
+            deleteMany: (keys) => ns().deleteMany({ keys }),
+            pull: (key) => ns().pull(key),
+            expire: (key, ttl) => ns().expire({ key, ttl }),
+            clear: () => ns().clear(),
+            namespace: (name) => cache.namespace(`app:${tenantId}:${name}`),
+        };
+    }
+
     /**
      * Acquire a distributed lock for this tenant.
      * Uses MongoDB atomic findOneAndUpdate with upsert.