@junejs/db 0.0.34-dev.1 → 0.1.0-dev.2

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { RequestScope, blob, currentLocale, currentServices, db, ensureScope, kv, registerSqlTagger, requestLocal, runInScope, setRequestLocale } from "./scope.js";
-export { type RequestScope, blob, currentLocale, currentServices, db, ensureScope, kv, registerSqlTagger, requestLocal, runInScope, setRequestLocale };
+import { RequestScope, blob, currentLocale, currentServices, db, ensureScope, isolateLocal, kv, registerSqlTagger, requestLocal, runInScope, setRequestLocale } from "./scope.js";
+export { type RequestScope, blob, currentLocale, currentServices, db, ensureScope, isolateLocal, kv, registerSqlTagger, requestLocal, runInScope, setRequestLocale };

package/dist/index.js

@@ -1,2 +1,2 @@
-import { blob, currentLocale, currentServices, db, ensureScope, kv, registerSqlTagger, requestLocal, runInScope, setRequestLocale } from "./scope.js";
-export { blob, currentLocale, currentServices, db, ensureScope, kv, registerSqlTagger, requestLocal, runInScope, setRequestLocale };
+import { blob, currentLocale, currentServices, db, ensureScope, isolateLocal, kv, registerSqlTagger, requestLocal, runInScope, setRequestLocale } from "./scope.js";
+export { blob, currentLocale, currentServices, db, ensureScope, isolateLocal, kv, registerSqlTagger, requestLocal, runInScope, setRequestLocale };

package/dist/scope.d.ts

@@ -9,6 +9,7 @@ type RequestScope = {
 declare function ensureScope(): Promise<void>;
 declare function runInScope<T>(scope: RequestScope, fn: () => T): T;
 declare function requestLocal<T>(key: symbol, make: () => T): T;
+declare function isolateLocal<T>(key: string | symbol, make: () => T): T;
 declare function setRequestLocale(locale: string): void;
 declare function currentLocale(): string | undefined;
 declare function currentServices<T = unknown>(): T | undefined;
@@ -17,4 +18,4 @@ declare const db: JuneDb;
 declare const kv: JuneKv;
 declare const blob: JuneBlob;
 //#endregion
-export { RequestScope, blob, currentLocale, currentServices, db, ensureScope, kv, registerSqlTagger, requestLocal, runInScope, setRequestLocale };
+export { RequestScope, blob, currentLocale, currentServices, db, ensureScope, isolateLocal, kv, registerSqlTagger, requestLocal, runInScope, setRequestLocale };

package/dist/scope.js

@@ -20,6 +20,12 @@ function requestLocal(key, make) {
 	if (!locals.has(key)) locals.set(key, make());
 	return locals.get(key);
 }
+const ISOLATE_LOCALS_KEY = Symbol.for("june.isolateLocals");
+const isolateLocals = globalThis[ISOLATE_LOCALS_KEY] ??= /* @__PURE__ */ new Map();
+function isolateLocal(key, make) {
+	if (!isolateLocals.has(key)) isolateLocals.set(key, make());
+	return isolateLocals.get(key);
+}
 function setRequestLocale(locale) {
 	const store = als?.getStore();
 	if (store) store.locale = locale;
@@ -59,4 +65,4 @@ const db = new Proxy({}, { get(_t, prop) {
 const kv = ambient("kv");
 const blob = ambient("blob");
 //#endregion
-export { blob, currentLocale, currentServices, db, ensureScope, kv, registerSqlTagger, requestLocal, runInScope, setRequestLocale };
+export { blob, currentLocale, currentServices, db, ensureScope, isolateLocal, kv, registerSqlTagger, requestLocal, runInScope, setRequestLocale };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junejs/db",
-  "version": "0.0.34-dev.1",
+  "version": "0.1.0-dev.2",
   "description": "June — the agent-native React framework. Ambient data resources (db/kv/blob).",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -10,6 +10,7 @@ export {
   runInScope,
   ensureScope,
   requestLocal,
+  isolateLocal,
   setRequestLocale,
   currentLocale,
   currentServices,

package/src/scope.ts

@@ -95,6 +95,48 @@ export function requestLocal<T>(key: symbol, make: () => T): T {
   return locals.get(key) as T;
 }
 
+// ── isolate-scoped state (the sibling of requestLocal) ────────────────────────
+//
+// `requestLocal` holds state that MUST die with the request. This holds state
+// that must OUTLIVE it: a connection pool, a token cache, a compiled index —
+// anything expensive whose whole value is being reused across requests.
+//
+// It exists because June's own architecture makes the naive version wrong. A
+// ChannelFactory and the `services` provider are resolved PER REQUEST (a Worker
+// has no env at module top-level, so the host must call them inside an
+// invocation). Anything they construct — including a `new Map()` cache — is
+// therefore rebuilt per request, and an app that "added a 5-minute cache"
+// silently never gets a hit. Hoisting to module scope by hand works but has to
+// be re-derived by every app, and a hand-rolled module Map also splits in two
+// when workspace symlinks give the app and the framework different copies of a
+// module. This keys off `globalThis` (the same trick ACTION_REGISTRY uses), so
+// one key means one value per isolate however many module instances load.
+//
+// ⚠ That cross-instance guarantee needs a key with cross-instance identity: a
+// STRING, or `Symbol.for("…")` from the global symbol registry. A plain
+// `Symbol("…")` is a fresh identity in each module instance, so two copies of
+// the module would each make their own value — fine when a single module owns
+// the key privately, wrong if sharing is the point.
+//
+// "Isolate" = the Worker isolate, or the Node/Bun process. Lifetime is the
+// host's, not the request's: values are never evicted here, so anything with a
+// bound (a TTL cache, an LRU) must bound itself.
+//
+//   const tokens = isolateLocal("myapp.tokens", () => new Map<string, string>());
+//
+// Keys are namespaced strings (or symbols) — prefix with your app/package name.
+// A key collision returns the FIRST value, so an unprefixed "cache" is a bug
+// waiting to happen across packages.
+const ISOLATE_LOCALS_KEY = Symbol.for("june.isolateLocals");
+const isolateLocals: Map<string | symbol, unknown> = ((
+  globalThis as Record<symbol, Map<string | symbol, unknown> | undefined>
+)[ISOLATE_LOCALS_KEY] ??= new Map());
+
+export function isolateLocal<T>(key: string | symbol, make: () => T): T {
+  if (!isolateLocals.has(key)) isolateLocals.set(key, make());
+  return isolateLocals.get(key) as T;
+}
+
 // The host sets the resolved locale onto the active scope after it resolves it
 // (the scope is opened before routing, so the locale arrives mid-request). A no-op
 // outside a scope, like the ambient resources.