@anteros/core 0.0.25 → 0.0.26

package/index.ts

@@ -13,6 +13,7 @@ import * as crypto from "./utils/crypto";
 
 // BentoCache-based caching (memory L1 + filesystem/Redis L2)
 import { useMemoryCache, useFilesystemCache, useRedisCache } from "./utils/cache";
+import { logger } from "./utils/logger";
 const cache = {
     useMemoryCache,
     useFilesystemCache,
@@ -31,4 +32,5 @@ export {
     utils,
     cache,
     crypto,
+    logger,
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@anteros/core",
   "module": "index.ts",
-  "version": "0.0.25",
+  "version": "0.0.26",
   "type": "module",
   "description": "Anteros Core",
   "private": false,

package/server/api.ts

@@ -174,7 +174,7 @@ type CrudHandler = (rest: InstanceType<typeof useRest>, collection: string, body
 
 const crudHandlers: Record<string, CrudHandler> = {
     aggregate:       (rest, collection, body) => rest.aggregate(collection, body?.pipeline || []),
-    find:            (rest, collection, body) => rest.find(collection, body?.params || {}),
+    find:            (rest, collection, body) => rest.find(collection, body?.params || {}, { useCache: body?.options?.useCache }),
     findOne:         (rest, collection, body) => rest.findOne(collection, body?.id, body?.params || {}),
     insertOne:       (rest, collection, body) => rest.insertOne(collection, body?.data),
     insertMany:      (rest, collection, body) => rest.insertMany(collection, body?.data),

package/server/boot.ts

@@ -1,5 +1,5 @@
 
-import { createApp } from './hono'
+import { createApp, collectHeaders } from './hono'
 import type { ServerConfig } from '../types/config'
 import dayjs from 'dayjs';
 import pkg from '../package.json';
@@ -23,6 +23,7 @@ import os from 'node:os';
 import { registerMetrics, getMetrics, trackRequest } from './metrics';
 import { startMaster, aggregateMetrics } from './cluster';
 import tcpPortUsed from 'tcp-port-used';
+import { logger } from '../utils/logger';
 
 type BootAppOptions = ServerConfig & {
 
@@ -34,6 +35,15 @@ async function bootApp(options: BootAppOptions = {} as BootAppOptions) {
         // Load required resources
         //******************************* */
         options = formatConfig(options);
+
+        // Logging: configure from cfg.server.logging (console + file, e.g. logs/anteros.log)
+        logger.configure(cfg.server.logging);
+        logger.info('Starting Anteros server', {
+            name: cfg.server.name ?? process.env.APP_NAME ?? 'SERVER',
+            port: cfg.server.port ?? 4000,
+            env: process.env.NODE_ENV || Bun.env.NODE_ENV || 'dev',
+            tenants: cfg.tenants?.map((t) => t.id),
+        });
         await syncTenants(); // sync tenants and connect to database
         await syncCollections(); // sync collections and create collections on database
         await syncFileCollections(); // sync file collections
@@ -160,7 +170,39 @@ async function bootApp(options: BootAppOptions = {} as BootAppOptions) {
                     });
 
                 if (url.pathname === "/socket.io/") {
-                    return respond(engineIo.handleRequest(req, server));
+                    const start = performance.now();
+                    return respond(engineIo.handleRequest(req, server)).then((res) => {
+                        // Access log for the Socket.IO upgrade path (handled outside Hono) —
+                        // same Caddy-compatible structure as the API access log
+                        const remote: any = (server as any).requestIP?.(req);
+                        const remoteIp = remote?.address ?? null;
+                        const remotePort = remote?.port ?? null;
+                        logger.info(`${req.method} ${url.pathname}${url.search} → ${res.status}`, {
+                            logger: 'http.log.access',
+                            status: res.status,
+                            duration: Math.round((performance.now() - start) * 10) / 10,
+                            method: req.method,
+                            uri: url.pathname + url.search,
+                            remote_ip: remoteIp,
+                            bytes_read: Number(req.headers.get('content-length')) || 0,
+                            size: Number(res.headers.get('content-length')) || 0,
+                            user_id: '',
+                            ip: remoteIp ?? 'unknown',
+                            traceId: null,
+                            tenant: null,
+                            request: {
+                                headers: collectHeaders(req.headers),
+                                client_ip: remoteIp ?? 'unknown',
+                                host: req.headers.get('host') ?? '',
+                                method: req.method,
+                                remote_ip: remoteIp,
+                                remote_port: remotePort,
+                                uri: url.pathname + url.search,
+                            },
+                            resp_headers: collectHeaders(res.headers),
+                        });
+                        return res;
+                    });
                 }
                 return respond(app.fetch(req, server));
             },
@@ -224,8 +266,29 @@ async function bootApp(options: BootAppOptions = {} as BootAppOptions) {
 
         }, 150);
 
+        // Boot event — recorded in the log file only (the console banner already
+        // shows name / PID / role / URL, so this line would be redundant on screen)
+        logger.file('Server started', {
+            name: NAME,
+            pid: process.pid,
+            role,
+            url: `http://localhost:${PORT}`,
+            env: env || 'dev',
+            logFile: logger.filePath || undefined,
+        });
+
+        // Uncaught errors → log file (MongoDB-style), then exit
+        process.on('uncaughtException', (err) => {
+            logger.error('Uncaught exception', { message: err?.message, stack: err?.stack });
+            process.exit(1);
+        });
+        process.on('unhandledRejection', (reason: any) => {
+            logger.error('Unhandled rejection', { message: reason?.message ?? String(reason), stack: reason?.stack });
+        });
+
         return server;
     } catch (err: any) {
+        logger.error('Failed to boot server', cfg.debug ? { error: err, message: err?.message } : { message: err?.message });
         console.error('Failed to boot server', cfg.debug ? err : err?.message);
         process.exit(1);
     }

package/server/hono.ts

@@ -18,8 +18,24 @@ import { getGlobalMiddlewares } from "../lib/middleware";
 import { jwt } from "../utils/func";
 import { AppError } from "../lib/error";
 import { getMetrics } from "./metrics";
+import { logger } from "../utils/logger";
 import type { HonoVariables } from "./env";
 
+/**
+ * Caddy-style header collection (array values); sensitive headers stripped
+ * (`authorization`, `cookie`, `proxy-authorization`, `set-cookie`).
+ */
+export function collectHeaders(h: Headers): Record<string, string[]> {
+    const EXCLUDE = ['authorization', 'cookie', 'proxy-authorization', 'set-cookie'];
+    const out: Record<string, string[]> = {};
+    for (const [name, value] of h.entries()) {
+        const key = name.toLowerCase();
+        if (EXCLUDE.includes(key)) continue;
+        out[key] = [value];
+    }
+    return out;
+}
+
 // ─── Redis-backed rate limiting (C3) ─────────────────────────────────────────
 // Lazy singleton: created once per process and reused across createApp() calls.
 // Each increment falls back to the in-memory store if Redis is unavailable,
@@ -200,6 +216,51 @@ function createApp(): Hono<{ Variables: HonoVariables }> {
         await next();
     });
 
+    // Access log — registered before /health & routes so EVERY request is logged.
+    // Runs around the async-context middleware, so traceId/tenant are readable here.
+    // Caddy-compatible JSONL payload: `request`/`resp_headers` blocks + flat fields.
+    app.use(async (c, next) => {
+        const start = performance.now();
+        try {
+            await next();
+        } finally {
+            const duration = performance.now() - start;
+            const trace = requestCtxStorage.get<{ id: string }>('trace');
+            const conn = c.get('connInfo');
+            const token = c.get('token');
+            const url = new URL(c.req.raw.url);
+            const uri = url.pathname + url.search;
+            const ip = c.get('clientIp') ?? 'unknown';
+            const remoteIp = conn?.remote?.address ?? null;
+            const remotePort = conn?.remote?.port ?? null;
+
+            logger.info(`${c.req.method} ${uri} → ${c.res.status}`, {
+                logger: 'http.log.access',
+                status: c.res.status,
+                duration: Math.round(duration * 10) / 10,
+                method: c.req.method,
+                uri,
+                remote_ip: remoteIp,
+                bytes_read: Number(c.req.header('content-length')) || 0,
+                size: Number(c.res.headers.get('content-length')) || 0,
+                user_id: (token?.decoded as Record<string, unknown> | null)?.['sub'] as string ?? '',
+                ip,
+                traceId: trace?.id ?? crypto.randomUUID(),
+                tenant: requestCtxStorage.get<string>('tenant_id') ?? null,
+                request: {
+                    headers: collectHeaders(c.req.raw.headers),
+                    client_ip: ip,
+                    host: c.req.header('host') ?? '',
+                    method: c.req.method,
+                    remote_ip: remoteIp,
+                    remote_port: remotePort,
+                    uri,
+                },
+                resp_headers: collectHeaders(c.res.headers),
+            });
+        }
+    });
+
     // Reuse the cached connInfo instead of re-querying the socket per middleware
     const cachedGetConnInfo: GetConnInfo = (c) =>
         (c as Context<{ Variables: HonoVariables }>).get('connInfo') ?? safeGetConnInfo(c);
@@ -320,6 +381,8 @@ function createApp(): Hono<{ Variables: HonoVariables }> {
                 c.set('token', emptyToken);
             }
 
+            // (access log is a dedicated middleware registered earlier — see top of createApp)
+
             return await next();
         })
     })

package/server/mcp.ts

@@ -13,6 +13,7 @@ import { StreamableHTTPTransport } from "@hono/mcp";
 import type Joi from "joi";
 import { cfg } from "./config";
 import { useRest } from "../database/rest";
+import { logger } from "../utils/logger";
 import type { McpTool, McpResource } from "../types/mcp";
 import type { HonoVariables } from "./env";
 
@@ -113,24 +114,32 @@ function buildServer(tenantId: string, tools: McpTool[], resources: McpResource[
         { capabilities: { tools: {}, resources: {} } }
     );
 
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: tools.map((t) => ({
+    const ms = (start: number) => Math.round((performance.now() - start) * 10) / 10;
+
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const start = performance.now();
+        const toolsList = tools.map((t) => ({
             name: t.name,
             title: t.name,
             description: t.description,
             inputSchema: joiToJsonSchema(t.inputSchema),
-        })),
-    }));
+        }));
+        logger.info('MCP tools/list', { method: 'tools/list', tenant: tenantId, count: toolsList.length, duration: ms(start) });
+        return { tools: toolsList };
+    });
 
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const start = performance.now();
         const tool = tools.find((t) => t.name === req.params.name);
         if (!tool) {
+            logger.warn('MCP tools/call', { method: 'tools/call', tenant: tenantId, tool: req.params.name, error: 'unknown tool', duration: ms(start) });
             throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${req.params.name}`);
         }
 
         const raw = req.params.arguments ?? {};
         const { error, value } = tool.inputSchema.validate(raw, { allowUnknown: false });
         if (error) {
+            logger.warn('MCP tools/call', { method: 'tools/call', tenant: tenantId, tool: req.params.name, args: raw, error: 'invalid arguments', duration: ms(start) });
             return {
                 content: [{ type: 'text' as const, text: `Invalid arguments: ${error.message}` }],
                 isError: true,
@@ -140,10 +149,13 @@ function buildServer(tenantId: string, tools: McpTool[], resources: McpResource[
         const rest = new useRest({ tenant_id: tenantId });
         try {
             const result = await tool.exec({ c: undefined as any, rest, args: value });
+            const isError = !!(result as any)?.isError;
+            logger[isError ? 'warn' : 'info']('MCP tools/call', { method: 'tools/call', tenant: tenantId, tool: req.params.name, args: value, isError, duration: ms(start) });
             if (result && Array.isArray(result.content)) return result;
             const text = typeof result === 'string' ? result : JSON.stringify(result);
             return { content: [{ type: 'text' as const, text }] };
         } catch (err: any) {
+            logger.warn('MCP tools/call', { method: 'tools/call', tenant: tenantId, tool: req.params.name, args: value, error: err?.message ?? 'unknown', duration: ms(start) });
             return {
                 content: [{ type: 'text' as const, text: `Error: ${err?.message ?? 'unknown'}` }],
                 isError: true,
@@ -151,32 +163,40 @@ function buildServer(tenantId: string, tools: McpTool[], resources: McpResource[
         }
     });
 
-    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
-        resources: resources
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        const start = performance.now();
+        const resourcesList = resources
             .filter((r) => !r.uri.includes('{')) // static only; templates are listed separately
             .map((r) => ({
                 uri: r.uri,
                 name: r.name,
                 description: r.description,
                 mimeType: r.mimeType,
-            })),
-    }));
+            }));
+        logger.info('MCP resources/list', { method: 'resources/list', tenant: tenantId, count: resourcesList.length, duration: ms(start) });
+        return { resources: resourcesList };
+    });
 
-    server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
-        resourceTemplates: resources
+    server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
+        const start = performance.now();
+        const templates = resources
             .filter((r) => r.uri.includes('{'))
             .map((r) => ({
                 uriTemplate: r.uri,
                 name: r.name,
                 description: r.description,
                 mimeType: r.mimeType,
-            })),
-    }));
+            }));
+        logger.info('MCP resources/templates/list', { method: 'resources/templates/list', tenant: tenantId, count: templates.length, duration: ms(start) });
+        return { resourceTemplates: templates };
+    });
 
     server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+        const start = performance.now();
         const uri = req.params.uri;
         const matched = matchUri(uri, resources);
         if (!matched) {
+            logger.warn('MCP resources/read', { method: 'resources/read', tenant: tenantId, uri, error: 'unknown uri', duration: ms(start) });
             throw new McpError(ErrorCode.InvalidParams, `Unknown resource URI: ${uri}`);
         }
 
@@ -188,8 +208,10 @@ function buildServer(tenantId: string, tools: McpTool[], resources: McpResource[
                 params: matched.params,
                 uri,
             });
+            logger.info('MCP resources/read', { method: 'resources/read', tenant: tenantId, uri, resource: matched.resource.name, params: matched.params, duration: ms(start) });
             return result;
         } catch (err: any) {
+            logger.warn('MCP resources/read', { method: 'resources/read', tenant: tenantId, uri, error: err?.message ?? 'unknown', duration: ms(start) });
             throw new McpError(ErrorCode.InternalError, `Failed to read resource: ${err?.message ?? 'unknown'}`);
         }
     });

package/server/routes.ts

@@ -4,6 +4,7 @@ import path from "path";
 import { jwt } from "../utils/func";
 import { useRest } from "../database/rest";
 import { io } from "./io";
+import { requestCtxStorage } from "../lib/asyncContextStorage";
 import type { HonoVariables } from "./env";
 
 function initializeRoutes(app: Hono<{ Variables: HonoVariables }>) {
@@ -12,10 +13,17 @@ function initializeRoutes(app: Hono<{ Variables: HonoVariables }>) {
           let method = route.method.toLocaleLowerCase();
           let routePath = path.posix.join(route._prefix_, route.path);
 
+            // Resolve the tenant in the request context so the access log,
+            // nested useRest() calls and audit see the right tenant_id
+            const resolveTenant = () => {
+                requestCtxStorage.set('tenant_id', route._tenant_);
+            };
+
 
 
             if (route.method == "GET") {
                 app.get(routePath, async (c) => { //
+                    resolveTenant();
                     return route.handler({
                         c,
                         rest: new useRest({
@@ -29,6 +37,7 @@ function initializeRoutes(app: Hono<{ Variables: HonoVariables }>) {
 
             if (route.method == 'POST') {
                 app.post(routePath, async (c) => {
+                    resolveTenant();
                     return route.handler({
                         c,
                         rest: new useRest({
@@ -42,6 +51,7 @@ function initializeRoutes(app: Hono<{ Variables: HonoVariables }>) {
 
             if (route.method == "PUT") {
                 app.put(routePath, async (c) => { //
+                    resolveTenant();
                     return route.handler({
                         c,
                         rest: new useRest({

package/tests/api.test.ts

@@ -73,6 +73,216 @@ describe("find", () => {
     });
 });
 
+describe("cursors / streaming", () => {
+    it("findStream iterates all matching docs (no default limit)", async () => {
+        const marker = `stream-${crypto.randomUUID()}`;
+        await rest.bulkWrite("items", Array.from({ length: 150 }, (_, i) => ({
+            insertOne: { document: { title: marker, count: i } },
+        })) as any);
+
+        const docs: any[] = [];
+        for await (const doc of rest.findStream("items", { $match: { title: marker } })) {
+            docs.push(doc);
+        }
+        expect(docs.length).toBe(150); // no 100-cap (unlike find())
+        expect(docs.every((d) => d.title === marker)).toBe(true);
+
+        await rest.db.collection("items").deleteMany({ title: marker });
+    });
+
+    it("aggregateStream yields JSON-converted docs", async () => {
+        const marker = `astream-${crypto.randomUUID()}`;
+        await rest.insertMany("items", [
+            { title: marker, count: 5 },
+            { title: marker, count: 7 },
+        ]);
+
+        const docs: any[] = [];
+        for await (const doc of rest.aggregateStream("items", [{ $match: { title: marker } }])) {
+            docs.push(doc);
+        }
+        expect(docs.length).toBe(2);
+
+        await rest.db.collection("items").deleteMany({ title: marker });
+    });
+
+    it("findStream honors the batchSize option", async () => {
+        const marker = `bsize-${crypto.randomUUID()}`;
+        await rest.bulkWrite("items", Array.from({ length: 50 }, (_, i) => ({
+            insertOne: { document: { title: marker, count: i } },
+        })) as any);
+
+        const docs: any[] = [];
+        for await (const doc of rest.findStream("items", { $match: { title: marker } }, { batchSize: 10 })) {
+            docs.push(doc);
+        }
+        expect(docs.length).toBe(50);
+        // JSON-converted (id as string, ISO dates)
+        expect(typeof docs[0]!._id).toBe("string");
+        expect(docs[0]!.createdAt).toMatch(/\d{4}-\d{2}-\d{2}/);
+
+        await rest.db.collection("items").deleteMany({ title: marker });
+    });
+
+    it("cursor options: maxTimeMS + comment + hint", async () => {
+        const marker = `copts-${crypto.randomUUID()}`;
+        await rest.insertMany("items", [{ title: marker }, { title: marker }]);
+
+        const docs: any[] = [];
+        for await (const doc of rest.findStream("items", { $match: { title: marker } }, {
+            batchSize: 5,
+            maxTimeMS: 30000,
+            comment: `test-${marker}`,
+            hint: { _id: 1 },
+        })) {
+            docs.push(doc);
+        }
+        expect(docs.length).toBe(2);
+
+        await rest.db.collection("items").deleteMany({ title: marker });
+    });
+
+    it("findStream withCount yields { count, doc } per document", async () => {
+        const marker = `wcount-${crypto.randomUUID()}`;
+        await rest.bulkWrite("items", Array.from({ length: 25 }, (_, i) => ({
+            insertOne: { document: { title: marker, count: i } },
+        })) as any);
+        // non-matching doc to prove the count only covers the $match
+        await rest.insertOne("items", { title: "other" });
+
+        let iterations = 0;
+        for await (const d of rest.findStream("items", { $match: { title: marker } }, { withCount: true })) {
+            expect(d.count).toBe(25);
+            expect(d.doc.title).toBe(marker);
+            iterations++;
+        }
+        expect(iterations).toBe(25);
+
+        await rest.db.collection("items").deleteMany({ title: { $in: [marker, "other"] } });
+    });
+
+    it("findStream pageSize yields { count, docs, hasNext } per page", async () => {
+        const marker = `pages-${crypto.randomUUID()}`;
+        await rest.bulkWrite("items", Array.from({ length: 25 }, (_, i) => ({
+            insertOne: { document: { title: marker, count: i } },
+        })) as any);
+        await rest.insertOne("items", { title: "other" });
+
+        const pages: any[] = [];
+        for await (const page of rest.findStream("items", { $match: { title: marker } }, { pageSize: 10 })) {
+            pages.push(page);
+            expect(page.count).toBe(25);          // total matching docs, not the page size
+            expect(page.docs.length).toBeLessThanOrEqual(10); // pageSize
+            expect(page.docs.every((d: any) => d.title === marker)).toBe(true);
+        }
+        // 25 docs / pageSize 10 → 3 pages: 10 + 10 + 5
+        expect(pages.length).toBe(3);
+        expect(pages[0]!.docs.length).toBe(10);
+        expect(pages[0]!.hasNext()).toBe(true);
+        expect(pages[1]!.docs.length).toBe(10);
+        expect(pages[1]!.hasNext()).toBe(true);
+        expect(pages[2]!.docs.length).toBe(5);
+        expect(pages[2]!.hasNext()).toBe(false);
+        const total = pages.reduce((acc: number, p: any) => acc + p.docs.length, 0);
+        expect(total).toBe(25);
+
+        await rest.db.collection("items").deleteMany({ title: { $in: [marker, "other"] } });
+    });
+
+    it("findStream pageSize withCount: false skips the count query", async () => {
+        const marker = `nocount-${crypto.randomUUID()}`;
+        await rest.bulkWrite("items", Array.from({ length: 12 }, (_, i) => ({
+            insertOne: { document: { title: marker, count: i } },
+        })) as any);
+
+        const pages: any[] = [];
+        for await (const page of rest.findStream("items", { $match: { title: marker } }, { pageSize: 10, withCount: false })) {
+            pages.push(page);
+            expect("count" in page).toBe(false); // no count field
+            expect(page.docs.length).toBeLessThanOrEqual(10);
+            expect(typeof page.hasNext).toBe("function");
+        }
+        expect(pages.length).toBe(2); // 10 + 2
+        expect(pages[0]!.hasNext()).toBe(true);
+        expect(pages[1]!.hasNext()).toBe(false);
+
+        await rest.db.collection("items").deleteMany({ title: marker });
+    });
+
+    it("findStream map transforms each doc on the fly", async () => {
+        const marker = `map-${crypto.randomUUID()}`;
+        await rest.insertMany("items", [{ title: marker, count: 1 }, { title: marker, count: 2 }]);
+
+        const out: any[] = [];
+        for await (const doc of rest.findStream("items", { $match: { title: marker } }, {
+            map: (d: any) => ({ id: d._id, n: d.count }),
+        })) {
+            out.push(doc);
+        }
+        expect(out.length).toBe(2);
+        expect(out.every((m) => "id" in m && "n" in m && !("title" in m))).toBe(true);
+
+        await rest.db.collection("items").deleteMany({ title: marker });
+    });
+
+    it("findStream signal aborts the stream and closes the cursor", async () => {
+        const marker = `sig-${crypto.randomUUID()}`;
+        await rest.bulkWrite("items", Array.from({ length: 20 }, (_, i) => ({
+            insertOne: { document: { title: marker, count: i } },
+        })) as any);
+
+        const ac = new AbortController();
+        let seen = 0;
+        for await (const doc of rest.findStream("items", { $match: { title: marker } }, { signal: ac.signal })) {
+            seen++;
+            if (seen === 3) ac.abort();
+        }
+        expect(seen).toBe(3); // stopped early, cursor closed by the generator
+
+        await rest.db.collection("items").deleteMany({ title: marker });
+    });
+
+    it("findStream pageSize map + signal", async () => {
+        const marker = `psig-${crypto.randomUUID()}`;
+        await rest.bulkWrite("items", Array.from({ length: 30 }, (_, i) => ({
+            insertOne: { document: { title: marker, count: i } },
+        })) as any);
+
+        const ac = new AbortController();
+        let pages = 0;
+        for await (const page of rest.findStream("items", { $match: { title: marker } }, {
+            pageSize: 10,
+            map: (d: any) => ({ id: d._id }),
+            signal: ac.signal,
+        })) {
+            pages++;
+            expect(page.docs.every((d: any) => "id" in d && !("title" in d))).toBe(true);
+            if (pages === 2) ac.abort();
+        }
+        expect(pages).toBe(2); // stopped after 2 pages
+
+        await rest.db.collection("items").deleteMany({ title: marker });
+    });
+
+    it("aggregateStream withCount counts the pipeline output", async () => {
+        const marker = `acount-${crypto.randomUUID()}`;
+        await rest.insertMany("items", [
+            { title: marker, count: 1 },
+            { title: marker, count: 2 },
+            { title: marker, count: 3 },
+        ]);
+
+        const out: any[] = [];
+        for await (const d of rest.aggregateStream("items", [{ $match: { title: marker } }], { withCount: true })) {
+            expect(d.count).toBe(3);
+            out.push(d.doc);
+        }
+        expect(out.length).toBe(3);
+
+        await rest.db.collection("items").deleteMany({ title: marker });
+    });
+});
+
 describe("$limit", () => {
     it("$limit: 0 means no limit (returns all matching docs)", async () => {
         const marker = `limit-zero-${crypto.randomUUID()}`;
@@ -196,9 +406,13 @@ describe("countDocuments", () => {
         expect(typeof n).toBe("number");
     });
     it("counts with filter", async () => {
-        await rest.insertOne("items", { title: "count-me" });
-        const n = await rest.countDocuments("items", { title: "count-me" });
-        expect(n).toBeGreaterThanOrEqual(1);
+        const marker = `count-me-${crypto.randomUUID()}`;
+        await rest.insertOne("items", { title: marker });
+        await rest.insertOne("items", { title: "count-other" });
+        const n = await rest.countDocuments("items", { title: marker });
+        expect(n).toBe(1); // only the matching doc — not the whole collection
+
+        await rest.db.collection("items").deleteMany({ title: marker });
     });
 });