@junejs/db 0.0.13 → 0.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junejs/db",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "June — the agent-native React framework. Ambient data resources (db/kv/blob).",
   "type": "module",
   "license": "MIT",
@@ -16,7 +16,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@junejs/core": "0.0.13"
+    "@junejs/core": "0.0.15"
   },
   "repository": {
     "type": "git",

package/src/index.ts

@@ -3,4 +3,4 @@
 // or action. The host (@junejs/server) opens the resources and runs each request
 // in the scope these read; this package is the worker-safe seam they cross.
 
-export { db, kv, blob, runInScope, ensureScope, type RequestScope } from "./scope";
+export { db, kv, blob, runInScope, ensureScope, requestLocal, registerSqlTagger, type RequestScope } from "./scope";

package/src/scope.ts

@@ -21,7 +21,11 @@
 
 import type { Resources, JuneDb, JuneKv, JuneBlob } from "@junejs/core/resources";
 
-export type RequestScope = { resources: Resources };
+// `locals` is generic per-request state for layers built ON TOP of the resources
+// (e.g. Juno's batch-loader registry). This package never reads it — it just
+// carries it per request so such state is STRUCTURALLY request-scoped and can't be
+// stashed on a long-lived handle. Lazily created by requestLocal().
+export type RequestScope = { resources: Resources; locals?: Map<symbol, unknown> };
 
 // The minimal slice of AsyncLocalStorage we use — kept structural so this module
 // never statically names the runtime.
@@ -56,6 +60,24 @@ export function runInScope<T>(scope: RequestScope, fn: () => T): T {
   return als ? als.run(scope, fn) : fn();
 }
 
+// Per-request local state for a layer built on top of the resources, keyed by a
+// symbol that layer owns. Created once per request and discarded with the scope —
+// so the state is structurally request-scoped and unstashable, the property a
+// long-lived handle (e.g. a module-scope `juno(db)`) can't give. Throws outside a
+// scope, like the ambient resources.
+export function requestLocal<T>(key: symbol, make: () => T): T {
+  const store = als?.getStore();
+  if (!store) {
+    throw new Error(
+      "June: request-scoped state was used outside a request scope. It is only " +
+        "available while a request is being handled (a route loader/view or an action).",
+    );
+  }
+  const locals = (store.locals ??= new Map<symbol, unknown>());
+  if (!locals.has(key)) locals.set(key, make());
+  return locals.get(key) as T;
+}
+
 function pick<K extends keyof Resources>(name: K): NonNullable<Resources[K]> {
   const store = als?.getStore();
   if (!store) {
@@ -87,7 +109,31 @@ function ambient<T extends object>(name: keyof Resources): T {
   });
 }
 
-// The ambient resources. `import { db } from "@junejs/db"` anywhere.
-export const db: JuneDb = ambient<JuneDb>("db");
+// A Tier-3 layer (Juno) registers a tagger so the ambient `db` records the tables
+// each RAW query touches — what lets a raw read inside cache() be auto-invalidated
+// instead of going silently stale. @junejs/db stays generic: it only CALLS the
+// registered fn, never imports it, so the dependency direction stays inward
+// (juno → db, never db → juno). Absent (no Juno) → `db` is raw, untagged.
+let sqlTagger: ((sql: string) => void) | null = null;
+export function registerSqlTagger(tag: (sql: string) => void): void {
+  sqlTagger = tag;
+}
+
+// The ambient resources. `import { db } from "@junejs/db"` anywhere. `db` is the
+// ONE canonical handle (the framework re-exports it); it auto-tags raw query/get/
+// run when a tagger is registered, so installing Juno upgrades it in place — no
+// second `db` to choose between.
+export const db: JuneDb = new Proxy({} as JuneDb, {
+  get(_t, prop) {
+    const handle = pick("db") as unknown as Record<string | symbol, unknown>;
+    const value = handle[prop];
+    if (typeof value !== "function") return value;
+    const fn = (value as (...a: unknown[]) => unknown).bind(handle);
+    if (sqlTagger && (prop === "query" || prop === "get" || prop === "run")) {
+      return (sql: string, params?: unknown[]) => (sqlTagger!(sql), fn(sql, params));
+    }
+    return fn;
+  },
+});
 export const kv: JuneKv = ambient<JuneKv>("kv");
 export const blob: JuneBlob = ambient<JuneBlob>("blob");