@anteros/core 0.0.24 → 0.0.26

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

package/tests/db-cache.test.ts

@@ -0,0 +1,214 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { ObjectId } from "mongodb";
+import { useRest } from "../database/rest";
+import { formatConfig, cfg } from "../server/config";
+import { syncTenants } from "../database/tenant";
+import { syncCollections } from "../database/collection";
+
+const TEST_TENANT = "cache-test";
+const TEST_DB = "mongodb://localhost:27017/_DB_CACHE_TEST";
+
+let rest: InstanceType<typeof useRest>;
+
+beforeAll(async () => {
+    formatConfig({
+        server: { port: 4000, cache: { driver: "memory", enabled: true } },
+        tenants: [
+            { id: TEST_TENANT, dir: "src", database: { uri: TEST_DB } },
+            { id: "cache-test-2", dir: "src", database: { uri: TEST_DB } },
+        ],
+    });
+    await syncTenants();
+    await syncCollections();
+    (cfg as any).collections = [
+        { _tenant_: TEST_TENANT, slug: "items", fields: [{ name: "title", type: "string" }, { name: "count", type: "number" }], api: { access: { "*": true } } },
+        { _tenant_: TEST_TENANT, slug: "orders", fields: [{ name: "code", type: "string" }, { name: "author", type: "relationship", relation: { to: "clients" } }], api: { access: { "*": true } } },
+        { _tenant_: TEST_TENANT, slug: "clients", fields: [{ name: "name", type: "string" }], api: { access: { "*": true } } },
+    ];
+    rest = new useRest({ internal: false, tenant_id: TEST_TENANT });
+});
+
+afterAll(async () => {
+    try { await rest.db.collection("items").drop(); } catch {}
+    try { await rest.db.collection("orders").drop(); } catch {}
+    try { await rest.db.collection("clients").drop(); } catch {}
+});
+
+describe("DB query cache (useCache)", () => {
+    it("serves from cache and invalidates on framework writes", async () => {
+        const marker = `dc-${crypto.randomUUID()}`;
+        await rest.insertMany("items", [{ title: marker }, { title: marker }]);
+        const params = { $match: { title: marker } };
+
+        const r1 = await rest.find("items", params, { useCache: true });
+        expect(r1.length).toBe(2);
+
+        // direct DB write (bypasses the framework) → cache is still served (stale)
+        await rest.db.collection("items").insertOne({ title: marker });
+        const r2 = await rest.find("items", params, { useCache: true });
+        expect(r2.length).toBe(2); // from cache
+
+        // framework insert → invalidates → refetches (now 4 docs: 2 + direct + framework)
+        await rest.insertOne("items", { title: marker });
+        const r3 = await rest.find("items", params, { useCache: true });
+        expect(r3.length).toBe(4); // refetched
+
+        // framework delete → invalidates
+        await rest.deleteMany("items", [r3[0]!._id]);
+        const r4 = await rest.find("items", params, { useCache: true });
+        expect(r4.length).toBe(3);
+
+        await rest.db.collection("items").deleteMany({ title: marker });
+    });
+
+    it("different params produce different cache entries", async () => {
+        const marker = `dp-${crypto.randomUUID()}`;
+        await rest.insertMany("items", [{ title: marker, count: 1 }, { title: marker, count: 2 }]);
+        await rest.find("items", { $match: { title: marker, count: 1 } }, { useCache: true });
+        const r = await rest.find("items", { $match: { title: marker, count: 2 } }, { useCache: true });
+        expect(r.length).toBe(1);
+        expect(r[0]!.count).toBe(2);
+        await rest.db.collection("items").deleteMany({ title: marker });
+    });
+
+    it("relations: modifying the included collection invalidates the parent cache", async () => {
+        const client = await rest.insertOne("clients", { name: "Old" });
+        const order = await rest.insertOne("orders", { code: "O1", author: client._id });
+
+        const params = { $match: { _id: order._id }, $include: ["author"] };
+        const r1: any = await rest.find("orders", params, { useCache: true });
+        expect(r1[0]!.author.name).toBe("Old");
+
+        // direct DB write on clients (bypass) → orders cache still stale
+        await rest.db.collection("clients").updateOne({ _id: new ObjectId(client._id) }, { $set: { name: "Direct" } });
+        const r2: any = await rest.find("orders", params, { useCache: true });
+        expect(r2[0]!.author.name).toBe("Old"); // from cache
+
+        // framework write on clients → invalidates orders cache too (relation)
+        await rest.updateOne("clients", client._id, { $set: { name: "New" } });
+        const r3: any = await rest.find("orders", params, { useCache: true });
+        expect(r3[0]!.author.name).toBe("New"); // refetched
+
+        await rest.db.collection("orders").deleteMany({ _id: order._id });
+        await rest.db.collection("clients").deleteMany({ _id: client._id });
+    });
+
+    it("collection cache.ttl default applies without the option", async () => {
+        (cfg.collections as any)[0]!.cache = { ttl: "1m" };
+        const marker = `cttl-${crypto.randomUUID()}`;
+        await rest.insertOne("items", { title: marker });
+        const r1 = await rest.find("items", { $match: { title: marker } }, { useCache: true });
+        expect(r1.length).toBe(1);
+        delete (cfg.collections as any)[0]!.cache;
+        await rest.db.collection("items").deleteMany({ title: marker });
+    });
+
+    it("targeted invalidation: an id NOT in the cached result keeps the cache", async () => {
+        const marker = `ti-out-${crypto.randomUUID()}`;
+        const feb1 = await rest.insertOne("items", { title: marker, month: "feb" });
+        const feb2 = await rest.insertOne("items", { title: marker, month: "feb" });
+        const jan = await rest.insertOne("items", { title: marker, month: "jan" });
+
+        const params = { $match: { title: marker, month: "feb" } };
+        const r1 = await rest.find("items", params, { useCache: true });
+        expect(r1.length).toBe(2); // cached (ids: feb1, feb2)
+
+        // update a JANUARY doc (id not in the cached result) → no invalidation
+        await rest.updateOne("items", jan._id, { $set: { month: "feb" } });
+        const r2 = await rest.find("items", params, { useCache: true });
+        expect(r2.length).toBe(2); // served from cache — jan's doc NOT in the result
+
+        await rest.db.collection("items").deleteMany({ title: marker });
+    });
+
+    it("targeted invalidation: an id IN the cached result invalidates it", async () => {
+        const marker = `ti-in-${crypto.randomUUID()}`;
+        const a = await rest.insertOne("items", { title: marker, count: 1 });
+        const b = await rest.insertOne("items", { title: marker, count: 2 });
+
+        const params = { $match: { title: marker } };
+        const r1: any = await rest.find("items", params, { useCache: true });
+        expect(r1.find((d: any) => d._id === a._id)!.count).toBe(1);
+
+        // update a doc that IS in the cached result → targeted invalidation → refetch
+        await rest.updateOne("items", a._id, { $set: { count: 99 } });
+        const r2: any = await rest.find("items", params, { useCache: true });
+        expect(r2.find((d: any) => d._id === a._id)!.count).toBe(99);
+        expect(r2.length).toBe(2);
+
+        // delete a doc in the cache → invalidated → refetch
+        await rest.deleteOne("items", b._id);
+        const r3 = await rest.find("items", params, { useCache: true });
+        expect(r3.length).toBe(1);
+
+        await rest.db.collection("items").deleteMany({ title: marker });
+    });
+
+    it("targeted invalidation works with native ObjectId ids", async () => {
+        const marker = `ti-oid-${crypto.randomUUID()}`;
+        const a = await rest.insertOne("items", { title: marker, count: 1 });
+
+        const params = { $match: { title: marker } };
+        const r1: any = await rest.find("items", params, { useCache: true });
+        expect(r1[0]!.count).toBe(1);
+
+        // update avec un ObjectId NATIF (pas un string) — la normalisation String(id) doit matcher l'index
+        await rest.updateOne("items", new ObjectId(a._id), { $set: { count: 77 } });
+        const r2: any = await rest.find("items", params, { useCache: true });
+        expect(r2[0]!.count).toBe(77); // invalidé + refetch
+
+        await rest.db.collection("items").deleteMany({ title: marker });
+    });
+
+    it("maxTags configurable caps the tagged ids", async () => {
+        const cacheConf = (cfg.server as any).cache;
+        (cfg.server as any).cache = { ...cacheConf, maxTags: 2 };
+        const marker = `mt-${crypto.randomUUID()}`;
+        const a = await rest.insertOne("items", { title: marker, count: 1 });
+        const b = await rest.insertOne("items", { title: marker, count: 2 });
+        const c = await rest.insertOne("items", { title: marker, count: 3 });
+
+        const params = { $match: { title: marker }, $sort: { count: 1 } }; // ordre garanti: a(1), b(2), c(3)
+        await rest.find("items", params, { useCache: true }); // cache peuplé (3 docs)
+
+        // le 3e id (c) n'est PAS taggé (maxTags: 2) → pas d'invalidation ciblée
+        await rest.updateOne("items", c._id, { $set: { count: 33 } });
+        const r1: any = await rest.find("items", params, { useCache: true });
+        expect(r1.find((d: any) => d._id === c._id)!.count).toBe(3); // cache conservé
+
+        // le 1er id (a) est taggé → invalidation ciblée
+        await rest.updateOne("items", a._id, { $set: { count: 11 } });
+        const r2: any = await rest.find("items", params, { useCache: true });
+        expect(r2.find((d: any) => d._id === a._id)!.count).toBe(11); // refetch
+
+        (cfg.server as any).cache = cacheConf; // restore
+        await rest.db.collection("items").deleteMany({ title: marker });
+    });
+
+    it("rest.cache is tenant-scoped", async () => {
+        // write from tenant A
+        await rest.cache.set("price:42", { total: 99 }, "5m");
+        expect(await rest.cache.get("price:42")).toEqual({ total: 99 });
+        expect(await rest.cache.has("price:42")).toBe(true);
+
+        // tenant B does NOT see tenant A's keys
+        const restB = new useRest({ tenant_id: "cache-test-2" });
+        expect(await restB.cache.get("price:42")).toBeUndefined();
+        await restB.cache.set("price:42", { total: 0 });
+        expect(await restB.cache.get("price:42")).toEqual({ total: 0 });
+        // tenant A unchanged
+        expect(await rest.cache.get("price:42")).toEqual({ total: 99 });
+
+        // getOrSet + delete
+        let calls = 0;
+        const v = await rest.cache.getOrSet("stats", async () => { calls++; return { n: 1 }; });
+        expect(v).toEqual({ n: 1 });
+        const v2 = await rest.cache.getOrSet("stats", async () => { calls++; return { n: 2 }; });
+        expect(v2).toEqual({ n: 1 });
+        expect(calls).toBe(1);
+
+        await rest.cache.delete("price:42");
+        await rest.cache.delete("stats");
+        expect(await rest.cache.get("price:42")).toBeUndefined();
+    });
+});

package/tests/logger.test.ts

@@ -0,0 +1,123 @@
+import { describe, it, expect, afterAll } from "bun:test";
+import fs from "node:fs";
+import path from "node:path";
+import { logger } from "../utils/logger";
+
+const DIR = path.join(import.meta.dir, ".tmp-logger");
+
+/** Read the log file and parse every line as JSONL */
+function readLogLines(rel: string): any[] {
+    return fs.readFileSync(path.join(DIR, rel), "utf-8")
+        .trim().split("\n").filter(Boolean).map((l) => JSON.parse(l));
+}
+
+async function flush() {
+    await logger.flush(); // wait for all pending writes
+    await Bun.sleep(10);
+}
+
+afterAll(() => {
+    try { fs.rmSync(DIR, { recursive: true, force: true }); } catch {}
+    logger.configure({ console: false, file: false });
+});
+
+describe("logger", () => {
+    it("writes JSONL lines with the Caddy envelope", async () => {
+        logger.configure({ dir: path.join(DIR, "basic"), file: true, console: false, level: "debug" });
+        logger.debug("dbg", { a: 1 });
+        logger.info("hello", { port: 4000 });
+        logger.warn("careful", { code: "X" });
+        logger.error("boom");
+        await flush();
+        const lines = readLogLines("basic/anteros.log");
+        expect(lines.length).toBe(4);
+        const hello = lines.find((l) => l.msg === "hello")!;
+        expect(hello.level).toBe("info");
+        expect(hello.port).toBe(4000);
+        expect(typeof hello.ts).toBe("number");
+        expect(lines.find((l) => l.msg === "boom")!.level).toBe("error");
+        expect(lines.find((l) => l.msg === "dbg")!.level).toBe("debug");
+    });
+
+    it("respects the level filter", async () => {
+        logger.configure({ dir: path.join(DIR, "filter"), file: true, console: false, level: "warn" });
+        logger.info("hidden-info");
+        logger.debug("hidden-debug");
+        logger.warn("shown-warn");
+        logger.error("shown-error");
+        await flush();
+        const lines = readLogLines("filter/anteros.log");
+        expect(lines.some((l) => l.msg === "hidden-info")).toBe(false);
+        expect(lines.some((l) => l.msg === "hidden-debug")).toBe(false);
+        expect(lines.some((l) => l.msg === "shown-warn")).toBe(true);
+        expect(lines.some((l) => l.msg === "shown-error")).toBe(true);
+    });
+
+    it("supports a custom file path", async () => {
+        const custom = path.join(DIR, "custom", "my-app.log");
+        logger.configure({ file: custom, console: false });
+        logger.info("custom path", { ok: true });
+        await flush();
+        const lines = fs.readFileSync(custom, "utf-8").trim().split("\n").filter(Boolean).map((l) => JSON.parse(l));
+        expect(lines[0]!.msg).toBe("custom path");
+        expect(lines[0]!.ok).toBe(true);
+    });
+
+    it("rotates the file when maxSize is exceeded", async () => {
+        const dir = path.join(DIR, "rotate");
+        logger.configure({ dir, file: true, console: false, maxSize: 200, maxFiles: 3 });
+        for (let i = 0; i < 20; i++) logger.info(`line ${i} with some padding ${'x'.repeat(30)}`);
+        await flush();
+        const rotated = fs.readdirSync(dir).filter((f) => f !== "anteros.log");
+        // Dated naming: anteros-YYYY-MM-DD-N.log
+        const dated = /^anteros-\d{4}-\d{2}-\d{2}-\d+\.log$/;
+        expect(rotated.length).toBeGreaterThan(0);
+        expect(rotated.every((f) => dated.test(f))).toBe(true);
+        // maxFiles: 3 → never more than 3 rotated files kept
+        expect(rotated.length).toBeLessThanOrEqual(3);
+        // the live file is never removed
+        expect(fs.existsSync(path.join(dir, "anteros.log"))).toBe(true);
+    });
+
+    it("handles circular / non-JSON meta safely", async () => {
+        logger.configure({ dir: path.join(DIR, "safe"), file: true, console: false });
+        const circular: any = { name: "x" };
+        circular.self = circular;
+        logger.info("circular meta", circular);
+        logger.info("bigint meta", { n: 123n });
+        await flush();
+        const lines = readLogLines("safe/anteros.log");
+        expect(lines.some((l) => l.msg === "circular meta")).toBe(true);
+        const raw = fs.readFileSync(path.join(DIR, "safe", "anteros.log"), "utf-8");
+        expect(raw).toContain("[Circular]");
+        expect(lines.find((l) => l.msg === "bigint meta")!.n).toBe("123");
+    });
+
+    it("keeps user-provided envelope keys", async () => {
+        logger.configure({ dir: path.join(DIR, "ts"), file: true, console: false });
+        logger.info("custom ts", { ts: 123.5, customField: 1 });
+        await flush();
+        const lines = readLogLines("ts/anteros.log");
+        expect(lines[0]!.ts).toBe(123.5);
+        expect(lines[0]!.customField).toBe(1);
+        expect(lines[0]!.msg).toBe("custom ts");
+    });
+
+    it("logger.file writes to the file but never to the console", async () => {
+        const out: string[] = [];
+        const orig = console.log;
+        console.log = (...a: any[]) => { out.push(a.join(" ")); };
+
+        logger.configure({ dir: path.join(DIR, "fileonly"), file: true, console: true });
+        logger.file("Server started", { pid: 1 });
+        logger.info("visible info", { a: 1 });
+        await flush();
+        console.log = orig;
+
+        const lines = readLogLines("fileonly/anteros.log");
+        expect(lines.some((l) => l.msg === "Server started")).toBe(true);
+        expect(lines.some((l) => l.msg === "visible info")).toBe(true);
+        expect(out.some((l) => l.includes("visible info"))).toBe(true);
+        expect(out.some((l) => l.includes("Server started"))).toBe(false);
+    });
+});

package/types/collection.d.ts

@@ -79,6 +79,12 @@ export type Collection = {
     actions?: {
         [key: string]: CollectionAction;
     };
+    /** Per-collection query caching — default TTL for `useCache` queries on this collection */
+    cache?: {
+        enabled?: boolean;
+        /** Default TTL for cached queries — human string ('5m', '2h') or ms */
+        ttl?: string | number;
+    };
     /**
      * The tenant id of the collection
      * @type {string}

package/types/config.d.ts

@@ -58,6 +58,43 @@ export type ServerConfig = {
                 max?: number;
             };
         };
+        logging?: {
+            /** Minimum level emitted (default: 'info') */
+            level?: 'debug' | 'info' | 'warn' | 'error';
+            /** Also write to the console (default: true) */
+            console?: boolean;
+            /** File logging: true → <dir>/anteros.log, string → custom path, false → disabled (default: true) */
+            file?: boolean | string;
+            /** Directory used when `file` is true (default: '.logs') */
+            dir?: string;
+            /** Rotate when the log file exceeds this size in bytes (default: 10MB) */
+            maxSize?: number;
+            /** Keep this many rotated files (default: 5) */
+            maxFiles?: number;
+            /** Log database operations slower than this many ms (default: 200) */
+            slowQueryMs?: number;
+        };
+        /** DB query caching (find + useCache) — driver + defaults for the query cache */
+        cache?: {
+            enabled?: boolean;
+            /** Driver: 'memory' (default), 'filesystem' (.cache/ folder), 'redis' */
+            driver?: 'memory' | 'filesystem' | 'redis';
+            /** Filesystem driver directory (default: ./.cache) */
+            directory?: string;
+            /** Redis connection (driver: 'redis') */
+            redis?: {
+                url?: string;
+                host?: string;
+                port?: number;
+                password?: string;
+            };
+            /** Filesystem prune interval (default: '1h') */
+            pruneInterval?: string;
+            /** Default TTL for cached queries — human string ('5m') or ms (default: '5m') */
+            ttl?: string | number;
+            /** Max `_id` tags per cached entry — large results are tagged up to this count (default: 50000; each tag costs ~0.18µs per cache hit) */
+            maxTags?: number;
+        };
     }
     tenants: Tenant[];
 }

package/types/mongo.d.ts

@@ -50,6 +50,16 @@ export type findOneOptions = {
     $project?: Record<string, unknown>;
 }
 
+/** Third parameter of `find`/`findOne` — query options */
+export type FindCallOptions = {
+    /** Serve from the DB query cache — cache-first, populated on miss, invalidated on any write */
+    useCache?: boolean;
+    /** TTL override for this query — human string ('5m', '2h') or ms (default: collection/server config, else '5m') */
+    ttl?: string | number;
+    /** Clean undefined/null/empty values from the result (SDK parity) */
+    cleanDeep?: boolean;
+}
+
 export type LookupOptions = {
     from: string;
     localField: string;