@anteros/core 0.0.25 → 0.0.26

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;

package/types/rest.d.ts

@@ -5,6 +5,43 @@ export type RestActions =
 
 export type BulkUpdateOperation = { updateOne: UpdateOneModel } | { updateMany: UpdateManyModel };
 
+/** Options for the streaming cursor methods (findCursor / aggregateCursor / findStream / aggregateStream) */
+export type CursorOptions = {
+    /** Number of documents fetched per batch from the server */
+    batchSize?: number;
+    /** Max execution time in ms — the query aborts with a timeout error if it runs longer */
+    maxTimeMS?: number;
+    /** Comment attached to the query — shows up in MongoDB profiling / slow query logs */
+    comment?: string;
+    /** Index hint — force a specific index: index name (`'email_1'`) or key pattern (`{ email: 1 }`) */
+    hint?: string | Record<string, 1 | -1>;
+    /** Compute the total count of matching docs in the background — each yielded item becomes `{ count, doc }` */
+    withCount?: boolean;
+    /** Abort the stream when the signal fires — iteration stops and the cursor is closed cleanly */
+    signal?: AbortSignal;
+    /** Transform each document on the fly (lazy — no intermediate array). Applied before `withCount` wraps the value */
+    map?: (doc: any) => any;
+    /** Page mode — when set, `findStream` yields `{ count, docs, hasNext() }` batches of this size instead of single docs */
+    pageSize?: number;
+};
+
+/** Tenant-scoped cache API — `rest.cache.*` (namespace `app:{tenant_id}`) */
+export type TenantCache = {
+    set(key: string, value: any, ttl?: string | number): Promise<boolean>;
+    setForever(key: string, value: any): Promise<boolean>;
+    get<T = any>(key: string): Promise<T | undefined>;
+    getOrSet<T = any>(key: string, factory: () => Promise<T> | T, ttl?: string | number): Promise<T>;
+    getOrSetForever<T = any>(key: string, factory: () => Promise<T> | T): Promise<T>;
+    has(key: string): Promise<boolean>;
+    missing(key: string): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    deleteMany(keys: string[]): Promise<boolean>;
+    pull<T = any>(key: string): Promise<T | undefined>;
+    expire(key: string, ttl: string | number): Promise<boolean>;
+    clear(): Promise<void>;
+    namespace(name: string): any;
+};
+
 export type RestOptions = {
     internal?: boolean;
     tenant_id?: string;

package/utils/cache.ts

@@ -33,8 +33,8 @@ class Cache {
 
         if (driver == 'filesystem') {
             store = store.useL2Layer(fileDriver({
-                directory: path.join(process.cwd(), '.cache'),
-                pruneInterval: '1h'
+                directory: options?.filesystem?.directory ?? path.join(process.cwd(), '.cache'),
+                pruneInterval: options?.pruneInterval ?? '1h'
             }))
         }
 

package/utils/func.ts

@@ -689,6 +689,9 @@ function buildPipeline(p: FindOptions, options?: {
     col: Collection
 }) {
 
+    // Never mutate the caller's params (buildPipeline fills defaults like $limit)
+    p = { ...p }
+
     let pipeline = []
     // $Match
     if (p?.$match) {