@junejs/juno 0.0.12 → 0.0.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junejs/juno",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "description": "Juno — June's ergonomic data layer over the JuneDb contract. The default that ships with the agent-native magic (Tier 3).",
   "type": "module",
   "license": "MIT",
@@ -16,10 +16,10 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@junejs/core": "0.0.12"
+    "@junejs/core": "0.0.13"
   },
   "devDependencies": {
-    "@junejs/server": "0.0.12"
+    "@junejs/server": "0.0.13"
   },
   "repository": {
     "type": "git",

package/src/index.ts

@@ -12,8 +12,10 @@ import type { JuneDb, RunResult } from "@junejs/core/resources";
 import { recordTableRead, recordTableWrite } from "@junejs/core/instrumentation";
 
 import { tableLoader, type Loader } from "./batch";
+import { taggingDb } from "./tag";
 
 export { createLoader, tableLoader, type Loader } from "./batch";
+export { tablesFromSql, tagSql, taggingDb, type SqlTouch } from "./tag";
 
 export type Row = Record<string, unknown>;
 
@@ -28,6 +30,10 @@ export class Table<T extends Row = Row> {
   constructor(
     private readonly db: JuneDb,
     private readonly name: string,
+    // Per-request ambient-loader registry, shared across the juno() handle's
+    // .table() calls so concurrent findBy coalesce. Optional/defaulted so a
+    // standalone `new Table(db, name)` still works (it just batches alone).
+    private readonly loaders: Map<string, Loader<string | number, Row>> = new Map(),
   ) {}
 
   async all(): Promise<T[]> {
@@ -36,12 +42,35 @@ export class Table<T extends Row = Row> {
   }
 
   async findBy(where: Partial<T>): Promise<T | undefined> {
-    recordTableRead(this.name);
-    const keys = Object.keys(where).map(ident);
-    const clause = keys.length ? ` where ${keys.map((k) => `${k} = ?`).join(" and ")}` : "";
+    recordTableRead(this.name); // sync, in-trace: cache() auto-tags table:<name> here
+    const keys = Object.keys(where);
+    // Ambient auto-batch: a single-column equality lookup coalesces with other
+    // concurrent findBy on the same (table, column) this request into ONE
+    // `where col in (...)` query — N+1 → 1, with no loader to manage. There is no
+    // cross-tick cache, so a read AFTER a write (a later tick) re-queries and sees
+    // the new value. Multi-column or empty `where` falls back to a direct query.
+    const [col] = keys;
+    if (keys.length === 1 && col !== undefined) {
+      const hit = await this.ambientLoader(col).load((where as Row)[col] as string | number);
+      return (hit ?? undefined) as T | undefined;
+    }
+    const cols = keys.map(ident);
+    const clause = cols.length ? ` where ${cols.map((k) => `${k} = ?`).join(" and ")}` : "";
     return this.db.get<T>(`select * from ${ident(this.name)}${clause} limit 1`, Object.values(where));
   }
 
+  // get-or-create the per-request ambient loader for (table, column). tableLoader
+  // validates both identifiers and emits recordTableRead in its batch.
+  private ambientLoader(col: string): Loader<string | number, T> {
+    const key = `${this.name}::${col}`;
+    let loader = this.loaders.get(key);
+    if (!loader) {
+      loader = tableLoader<Row>(this.db, this.name, col);
+      this.loaders.set(key, loader);
+    }
+    return loader as Loader<string | number, T>;
+  }
+
   async insert(values: Partial<T>): Promise<RunResult> {
     recordTableWrite(this.name); // auto-invalidate: invokeAction drops table:<name>
     const cols = Object.keys(values).map(ident);
@@ -78,15 +107,36 @@ export class Table<T extends Row = Row> {
 
 export type Juno = {
   table<T extends Row = Row>(name: string): Table<T>;
+  // Raw escape hatch. Reads/writes through it auto-tag by parsed table name, so a
+  // `cache(() => db.query("select ... from posts"))` is invalidated by a posts
+  // write instead of going silently stale.
   db: JuneDb;
+  // Explicit tag escape hatch for SQL the parser can't classify (CTEs over a
+  // function, dynamic table names, a read computed outside SQL). `reads()` makes a
+  // cache() pick up the tag; `writes()` invalidates it. Explicit, so it can't
+  // silently break — the failure mode the implicit-only design had.
+  reads(...tables: string[]): void;
+  writes(...tables: string[]): void;
 };
 
-// Wrap any JuneDb handle (ctx.db) in Juno's ergonomic surface.
+// Wrap any JuneDb handle (ctx.db) in Juno's ergonomic surface. Build ONE per
+// request: the ambient-loader registry it carries is what makes concurrent
+// findBy across components coalesce — and scoping it to the per-request handle
+// is what keeps keys from leaking across requests.
 export function juno(db: JuneDb): Juno {
+  const loaders = new Map<string, Loader<string | number, Row>>();
   return {
-    db,
+    // Table API uses the raw db and tags explicitly (precise, parser-independent);
+    // the exposed handle wraps it so the raw escape hatch auto-tags too.
+    db: taggingDb(db),
     table<T extends Row = Row>(name: string) {
-      return new Table<T>(db, name);
+      return new Table<T>(db, name, loaders);
+    },
+    reads(...tables: string[]) {
+      for (const t of tables) recordTableRead(t);
+    },
+    writes(...tables: string[]) {
+      for (const t of tables) recordTableWrite(t);
     },
   };
 }

package/src/tag.ts

@@ -0,0 +1,83 @@
+// Best-effort extraction of the table(s) a SQL statement touches, so RAW queries
+// through the juno handle participate in the same auto-tag / auto-invalidate as
+// the typed table API — closing the "raw query inside cache() is silently stale"
+// gap (positioning Appendix 3). Heuristic by design: it covers single-table reads,
+// JOINs, and the three write verbs. Anything it can't classify falls back to the
+// explicit j.reads()/j.writes() escape hatch, so the failure mode is "developer
+// tags it" — never silent staleness slipping past a correct-looking call.
+
+import { recordTableRead, recordTableWrite } from "@junejs/core/instrumentation";
+import type { JuneDb } from "@junejs/core/resources";
+
+export type SqlTouch = { kind: "read" | "write" | "other"; tables: string[] };
+
+// A table reference: optional quote/bracket, an identifier that may be schema-qualified.
+const TABLE = "[`\"'\\[]?([A-Za-z_][\\w.]*)[`\"'\\]]?";
+
+// schema.table -> table (tags use the bare name, as the table API does)
+function bare(token: string): string {
+  const dot = token.lastIndexOf(".");
+  return dot >= 0 ? token.slice(dot + 1) : token;
+}
+
+function normalize(sql: string): string {
+  return sql
+    .replace(/--[^\n]*/g, " ") // line comments
+    .replace(/\/\*[\s\S]*?\*\//g, " ") // block comments
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function collect(sql: string, re: RegExp): string[] {
+  const out = new Set<string>();
+  for (const m of sql.matchAll(re)) if (m[1]) out.add(bare(m[1]));
+  return [...out];
+}
+
+// Classify a statement by its leading verb and pull the table(s) it touches.
+export function tablesFromSql(sqlRaw: string): SqlTouch {
+  const sql = normalize(sqlRaw);
+  const verb = (sql.match(/^(\w+)/)?.[1] ?? "").toLowerCase();
+  switch (verb) {
+    case "select":
+    case "with": // CTE names may over-match → over-invalidate (safe), never under
+      return { kind: "read", tables: collect(sql, new RegExp(`\\b(?:from|join)\\s+${TABLE}`, "gi")) };
+    case "insert":
+      return { kind: "write", tables: collect(sql, new RegExp(`\\binto\\s+${TABLE}`, "gi")) };
+    case "update":
+      return { kind: "write", tables: collect(sql, new RegExp(`^update\\s+${TABLE}`, "gi")) };
+    case "delete":
+      return { kind: "write", tables: collect(sql, new RegExp(`\\bfrom\\s+${TABLE}`, "gi")) };
+    default:
+      return { kind: "other", tables: [] };
+  }
+}
+
+// Record the reads/writes a raw statement implies, for cache auto-tag/invalidate.
+export function tagSql(sql: string): void {
+  const t = tablesFromSql(sql);
+  if (t.kind === "read") for (const name of t.tables) recordTableRead(name);
+  else if (t.kind === "write") for (const name of t.tables) recordTableWrite(name);
+}
+
+// Wrap a JuneDb so raw query/get/run auto-tag by parsed table name. The typed
+// table API keeps tagging explicitly (precise, parser-independent); this covers
+// the raw escape hatch so `cache(() => db.query("select ... from posts"))` is
+// invalidated by a posts write instead of going silently stale.
+export function taggingDb(db: JuneDb): JuneDb {
+  return {
+    ...db,
+    query<T = unknown>(sql: string, params?: unknown[]) {
+      tagSql(sql);
+      return db.query<T>(sql, params);
+    },
+    get<T = unknown>(sql: string, params?: unknown[]) {
+      tagSql(sql);
+      return db.get<T>(sql, params);
+    },
+    run(sql: string, params?: unknown[]) {
+      tagSql(sql);
+      return db.run(sql, params);
+    },
+  };
+}