data-cache top-level await fix (#99)

bryanpackman · web-flow · commit 5f7e87cf6371 · 2026-05-01T11:03:27.000-07:00
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,9 @@
+# CLAUDE.md
+
+## Never use top-level await
+
+Do not use `await` at module top level anywhere in this repo's package sources. Defer async work to a lazy-init pattern: store the in-flight promise in a closure and `await` it inside the methods that need it.
+
+**Why:** Bundlers (Rolldown / Vite 8) wrap any module containing TLA — and every module that transitively imports it — in an async lazy-init function whose exports are only available via `await`. When those wrappers participate in an import cycle (very common through barrel re-exports), the cycle becomes a circular-await chain with no live-binding escape hatch, and the whole graph deadlocks silently. Native ESM in dev resolves cycles via live bindings, so dev appears fine; only the bundled output hangs, with no console error.
+
+See `packages/data/src/cache/data-cache.ts` (`createGlobalDataCache`) for the lazy-init pattern, and `packages/data/src/cache/blob-store.ts` (`cachePromise` inside `createBlobStore`) for the same idea applied at factory scope.
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "data-monorepo",
-  "version": "0.9.53",
+  "version": "0.9.54",
   "private": true,
   "scripts": {
     "build": "pnpm -r run build",
diff --git a/packages/data-lit-tictactoe/package.json b/packages/data-lit-tictactoe/package.json
@@ -1,6 +1,6 @@
 {
   "name": "data-lit-tictactoe",
-  "version": "0.9.53",
+  "version": "0.9.54",
   "description": "Tic-Tac-Toe sample - Lit web components with @adobe/data-lit and AgenticService",
   "type": "module",
   "private": true,
diff --git a/packages/data-lit-todo/package.json b/packages/data-lit-todo/package.json
@@ -1,6 +1,6 @@
 {
   "name": "data-lit-todo",
-  "version": "0.9.53",
+  "version": "0.9.54",
   "description": "Todo sample app demonstrating @adobe/data with Lit",
   "type": "module",
   "private": true,
diff --git a/packages/data-lit/package.json b/packages/data-lit/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data-lit",
-  "version": "0.9.53",
+  "version": "0.9.54",
   "description": "Adobe data Lit bindings - hooks, elements, decorators",
   "type": "module",
   "private": false,
diff --git a/packages/data-react-hello/package.json b/packages/data-react-hello/package.json
@@ -1,6 +1,6 @@
 {
   "name": "data-react-hello",
-  "version": "0.9.53",
+  "version": "0.9.54",
   "description": "Hello World sample - click counter using @adobe/data-react",
   "type": "module",
   "private": true,
diff --git a/packages/data-react-pixie/package.json b/packages/data-react-pixie/package.json
@@ -1,6 +1,6 @@
 {
   "name": "data-react-pixie",
-  "version": "0.9.53",
+  "version": "0.9.54",
   "description": "PixiJS React sample - ECS sprites (bunny, fox) with @adobe/data-react",
   "type": "module",
   "private": true,
diff --git a/packages/data-react/package.json b/packages/data-react/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data-react",
-  "version": "0.9.53",
+  "version": "0.9.54",
   "description": "Adobe data React bindings — hooks and context for ECS database",
   "type": "module",
   "private": false,
diff --git a/packages/data-solid-dashboard/package.json b/packages/data-solid-dashboard/package.json
@@ -1,6 +1,6 @@
 {
   "name": "data-solid-dashboard",
-  "version": "0.9.53",
+  "version": "0.9.54",
   "description": "Mini dashboard sample — multiple components sharing one @adobe/data ECS database with SolidJS",
   "type": "module",
   "private": true,
diff --git a/packages/data-solid/package.json b/packages/data-solid/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data-solid",
-  "version": "0.9.53",
+  "version": "0.9.54",
   "description": "Adobe data SolidJS bindings — context and provider for ECS database",
   "type": "module",
   "private": false,
diff --git a/packages/data/package.json b/packages/data/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data",
-  "version": "0.9.53",
+  "version": "0.9.54",
   "description": "Adobe data oriented programming library",
   "type": "module",
   "sideEffects": false,
diff --git a/packages/data/src/cache/data-cache.test.ts b/packages/data/src/cache/data-cache.test.ts
@@ -1,9 +1,24 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
-import { getDataCache } from "./data-cache.js";
+import { dataCache, getDataCache } from "./data-cache.js";
 import { beforeAll, describe, expect, it } from "vitest";
 
 describe("DataCache", () => {
   beforeAll(() => {});
+  it("dataCache is not a top-level await", () => {
+    expect(typeof (dataCache as any).then === "undefined");
+  });
+
+  it("dataCache is lazily initialized and supports put/match/delete directly", async () => {
+    const key = { test: "lazy-init", n: Date.now() };
+    const value = { hello: "world" };
+
+    await dataCache.put(key, value);
+    expect(await dataCache.match(key)).toEqual(value);
+
+    await dataCache.delete(key);
+    expect(await dataCache.match(key)).toBeUndefined();
+  });
+
   it("should allow storing and retrieving values in namespaced/versioned caches", async () => {
     //  get a namespaced cache
     const cache = await getDataCache("test:v1");
@@ -32,7 +47,7 @@ describe("DataCache", () => {
 
     //  output from different named cache is undefined
     expect(await (await getDataCache("test2:v1")).match(key)).toEqual(
-      undefined
+      undefined,
     );
 
     //  output from different cache version is undefined
diff --git a/packages/data/src/cache/data-cache.ts b/packages/data/src/cache/data-cache.ts
@@ -115,16 +115,37 @@ export function createBlobRefAwareDataCache<
   };
 }
 
-const managedPersistentCache = await getManagedPersistentCache("datacache", {
-  maximumMemoryEntries: 100,
-  maximumStorageEntries: 1000,
-});
-const blobRefAwareDataCache = await createBlobRefAwareDataCache(
-  createDataCache(managedPersistentCache)
-);
-export const dataCache: DataCache<Data, Data> = createExpiringDataCache(
-  blobRefAwareDataCache
-);
+// Lazy-init the global cache to avoid a top-level await. Rolldown / Vite 8
+// can deadlock when modules with TLA are reachable through a barrel cycle
+// in downstream bundles, so we defer the async work to first use.
+function createGlobalDataCache(): DataCache<Data, Data> {
+  let cachePromise: Promise<DataCache<Data, Data>> | undefined;
+  const init = (): Promise<DataCache<Data, Data>> =>
+    (cachePromise ??= (async () => {
+      const managedPersistentCache = await getManagedPersistentCache("datacache", {
+        maximumMemoryEntries: 100,
+        maximumStorageEntries: 1000,
+      });
+      const blobRefAwareDataCache = await createBlobRefAwareDataCache(
+        createDataCache(managedPersistentCache)
+      );
+      return createExpiringDataCache(blobRefAwareDataCache);
+    })());
+
+  return {
+    async match(key) {
+      return (await init()).match(key);
+    },
+    async put(key, value, options) {
+      return (await init()).put(key, value, options);
+    },
+    async delete(key) {
+      return (await init()).delete(key);
+    },
+  };
+}
+
+export const dataCache: DataCache<Data, Data> = createGlobalDataCache();
 
 /**
  * Retrieves a namespaced data cache. Calling it multiple times will return an equivalent cache.

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "data-monorepo",`
`3`		`- "version": "0.9.53",`
	`3`	`+ "version": "0.9.54",`
`4`	`4`	`"private": true,`
`5`	`5`	`"scripts": {`
`6`	`6`	`"build": "pnpm -r run build",`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "data-lit-tictactoe",`
`3`		`- "version": "0.9.53",`
	`3`	`+ "version": "0.9.54",`
`4`	`4`	`"description": "Tic-Tac-Toe sample - Lit web components with @adobe/data-lit and AgenticService",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"private": true,`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "data-lit-todo",`
`3`		`- "version": "0.9.53",`
	`3`	`+ "version": "0.9.54",`
`4`	`4`	`"description": "Todo sample app demonstrating @adobe/data with Lit",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"private": true,`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@adobe/data-lit",`
`3`		`- "version": "0.9.53",`
	`3`	`+ "version": "0.9.54",`
`4`	`4`	`"description": "Adobe data Lit bindings - hooks, elements, decorators",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"private": false,`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "data-react-hello",`
`3`		`- "version": "0.9.53",`
	`3`	`+ "version": "0.9.54",`
`4`	`4`	`"description": "Hello World sample - click counter using @adobe/data-react",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"private": true,`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "data-react-pixie",`
`3`		`- "version": "0.9.53",`
	`3`	`+ "version": "0.9.54",`
`4`	`4`	`"description": "PixiJS React sample - ECS sprites (bunny, fox) with @adobe/data-react",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"private": true,`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@adobe/data-react",`
`3`		`- "version": "0.9.53",`
	`3`	`+ "version": "0.9.54",`
`4`	`4`	`"description": "Adobe data React bindings — hooks and context for ECS database",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"private": false,`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "data-solid-dashboard",`
`3`		`- "version": "0.9.53",`
	`3`	`+ "version": "0.9.54",`
`4`	`4`	`"description": "Mini dashboard sample — multiple components sharing one @adobe/data ECS database with SolidJS",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"private": true,`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@adobe/data-solid",`
`3`		`- "version": "0.9.53",`
	`3`	`+ "version": "0.9.54",`
`4`	`4`	`"description": "Adobe data SolidJS bindings — context and provider for ECS database",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"private": false,`