bff-store 0.1.1 → 0.1.2

package/.claude/settings.local.json

@@ -48,7 +48,11 @@
       "Bash(echo \"---mongodb status: $\\([ -d node_modules/mongodb ] && echo 'INSTALLED' || echo 'NOT INSTALLED'\\)\")",
       "Bash(echo \"---mongodb: $\\([ -d node_modules/mongodb ] && echo 'INSTALLED' || echo 'NOT INSTALLED'\\)\")",
       "Bash(xargs kill:*)",
-      "Bash(npm start:*)"
+      "Bash(npm start:*)",
+      "Bash(mv 01-server-async-startup.md 01-server-async-startup.high.md)",
+      "Bash(mv 07-jsonl-key-collision.md 07-jsonl-key-collision.high.md)",
+      "Bash(mv 11-mongodb-storage-leak.md 11-mongodb-storage-leak.high.md)",
+      "Bash(mv 12-setEntityId-stale-closure.md 12-setEntityId-stale-closure.high.md)"
     ]
   }
 }

package/README.md

@@ -1,42 +1,77 @@
 # bff-store
 
-A jotai-based state management library with pluggable storage adapters and built-in BFF (Backend for Frontend) for browser/Next.js environments.
+A jotai-based state management library with pluggable storage adapters and a built-in BFF (Backend for Frontend) for browser/Next.js environments.
 
 ## Features
 
 - **Configuration-driven**: Define multiple states via array configuration
-- **Pluggable storage**: Use memory, JSONL files, MongoDB, or remote server
+- **Pluggable storage**: Use memory, JSONL files, MongoDB, or a remote server
 - **Auto-generated hooks**: React hooks auto-generated from config
 - **Loading states**: Built-in loading state tracking
-- **Debounced saves**: Automatic debouncing for non-critical data
+- **Debounced saves**: Automatic debouncing for non-critical data (800ms default)
 - **Built-in BFF**: Embedded sidecar API server for browser/Next.js environments
+- **Multi-tenant**: Per-entityId isolation via `setEntityId()`
+- **Unmount cleanup**: Pending writes cancelled on component unmount
+- **Embedded Sidecar**: Like a serverless function that auto-starts on first use — no manual server deployment required
 
 ## Architecture
 
 ```
 ┌─────────────────────────────────────────────────────────┐
-│                    Your Application                       │
-│                   (Next.js/Browser)                      │
-│                                                          │
-│  useStore() ──► remoteStorage ──► localhost:3847        │
-│                         │                                │
-│                         ▼                                │
-│              ┌─────────────────────┐                     │
-│              │   BFF (Sidecar)     │                     │
-│              │  bff-store │                     │
-│              │                     │                     │
-│              │  /storage/get/:key  │                     │
-│              │  /storage/set/:key  │                     │
-│              │  /storage/delete   │                     │
-│              └──────────┬──────────┘                     │
-│                         │                                │
-│                         ▼                                │
-│              ┌─────────────────────┐                     │
-│              │   JSONL / MongoDB   │                     │
-│              └─────────────────────┘                     │
+│                    Your Application                      │
+│                   (Next.js / Browser)                   │
+│                                                         │
+│  useStore() ──► remoteStorage ──► localhost:3847      │
+│                         │                               │
+│                         ▼                               │
+│              ┌─────────────────────┐                  │
+│              │     BFF (Sidecar)    │                  │
+│              │                     │                  │
+│              │  /storage/get/:key  │                  │
+│              │  /storage/set/:key  │                  │
+│              │  /storage/batch-*   │                  │
+│              └──────────┬──────────┘                  │
+│                         │                               │
+│                         ▼                               │
+│              ┌─────────────────────┐                  │
+│              │   JSONL / MongoDB   │                  │
+│              │    (multi-tenant)    │                  │
+│              └─────────────────────┘                  │
 └─────────────────────────────────────────────────────────┘
 ```
 
+### Data Flow
+
+1. **Init**: `createStore()` creates atoms, `remoteStorage` auto-starts the BFF server
+2. **Read**: `useStore()` returns from jotai store directly — no I/O
+3. **Write**: Update local jotai atom first (sync UI response), then debounce-persist to storage
+4. **Unmount**: Automatically cancel pending writes to prevent writes from destroyed components
+
+## Embedded Sidecar Pattern
+
+bff-store borrows the **embedded sidecar** pattern from microservices: the BFF server is co-located with your application process, auto-started on first use, with the lifecycle managed transparently.
+
+| Aspect | Classic Microservice Sidecar | bff-store Embedded Sidecar |
+|--------|----------------------------|--------------------------|
+| Deployment | Separate container, same pod | In-process, same Node.js process |
+| Startup | Kubernetes orchestrates | `createStore()` triggers `import('./server')` |
+| Singleton | One per pod | One per process (singleton `startServer`) |
+| State | External DB / volume | JSONL / MongoDB |
+| Scaling | Horizontal pod scaling | Multiple store instances share one server |
+| Cold start | Pod scheduling overhead | Module import + server listen (~100ms) |
+
+This gives you the **transparency of serverless** (no manual server deployment) with the **control of a long-running process** (full backend, no 100ms timeout, no cold starts after first invocation).
+
+### How it compares to serverless
+
+| | Serverless (Lambda) | bff-store Sidecar |
+|--|---------------------|-------------------|
+| Cold start | 100ms–1s (platform) | ~100ms (import + listen) |
+| State | External KV store (S3/Dynamo) | JSONL / MongoDB (local) |
+| Concurrency | One invocation per instance | All stores share one server |
+| Tenant isolation | Separate functions | Separate collections / directories |
+| Failure mode | Invocation fails | Server restarts, pending writes lost (mitigated by unmount cancel) |
+
 ## Installation
 
 ```bash
@@ -47,7 +82,7 @@ pnpm add bff-store
 
 ## Client Usage (Browser / Next.js)
 
-BFF Server 会自动启动，客户端只需使用 `remoteStorage()` 并指定存储后端：
+The BFF server starts automatically. Use `remoteStorage()` to specify the storage backend:
 
 ```typescript
 import { createStore, useStore, remoteStorage } from 'bff-store';
@@ -55,9 +90,10 @@ import { createStore, useStore, remoteStorage } from 'bff-store';
 const config = [
   { key: 'theme', defaultValue: 'dark' },
   { key: 'characters', defaultValue: [] },
+  { key: 'settings', defaultValue: {}, immediate: true },  // persist immediately, no debounce
 ] as const;
 
-// 使用 MongoDB 存储
+// Using MongoDB
 const store = createStore('my-app', config, {
   storage: remoteStorage({
     backend: 'mongodb',
@@ -66,7 +102,7 @@ const store = createStore('my-app', config, {
   }),
 });
 
-// 或使用 JSONL 存储
+// Or using JSONL
 // const store = createStore('my-app', config, {
 //   storage: remoteStorage({
 //     backend: 'jsonl',
@@ -75,60 +111,75 @@ const store = createStore('my-app', config, {
 // });
 ```
 
-### 在 React 组件中使用
+### In a React Component
 
 ```typescript
 function App() {
-  const { theme, setTheme, isLoading } = useStore(store);
+  const { theme, setTheme, characters, setCharacters, isLoading } = useStore(store);
 
   if (isLoading) return <div>Loading...</div>;
 
-  return <input value={theme} onChange={e => setTheme(e.target.value)} />;
+  return (
+    <input value={theme} onChange={e => setTheme(e.target.value)} />
+  );
 }
 ```
 
-### 自定义 BFF 服务器地址
+### Immediate Persistence (no debounce)
+
+For critical data, use `immediate: true`:
 
 ```typescript
-// 如果 BFF 运行在其他地址
-const adapter = remoteStorage({ baseUrl: 'http://localhost:3847' });
-const adapter = remoteStorage({ entityId: 'user-123' });  // 多租户支持
+const config = [
+  { key: 'autosave', defaultValue: '', immediate: true },
+] as const;
 ```
 
-### Memory Storage (不持久化)
+### Waiting for the Server
 
-适用于开发环境或不需要持久化的场景：
+`createStore` is synchronous, but server startup is asynchronous. Optionally wait:
 
 ```typescript
-import { createStore, useStore, memoryStorage } from 'bff-store';
+import { createStore, waitForServer } from 'bff-store';
 
-const store = createStore('my-app', config, {
-  storage: memoryStorage(),  // 不走 BFF，数据仅存在内存
-});
+const store = createStore('my-app', config, { storage: adapter });
+await waitForServer();
 ```
 
-## Advanced: 手动启动 BFF Server
+### Multi-Tenant Switching
 
-大多数情况不需要手动启动 BFF，它会自动启动。如需手动控制：
+Switch tenants dynamically via `setEntityId`:
 
 ```typescript
-import { startServer } from 'bff-store/server';
+const adapter = remoteStorage({ entityId: 'tenant-A' });
+const store = createStore('tenant-A', config, { storage: adapter });
 
-await startServer({
-  port: 3847,
+// Switch tenant
+adapter.setEntityId('tenant-B');
+```
+
+### Memory Storage (non-persistent)
+
+For development or non-persistent use cases:
+
+```typescript
+import { createStore, useStore, memoryStorage } from 'bff-store';
+
+const store = createStore('my-app', config, {
+  storage: memoryStorage(),  // data lives only in memory
 });
 ```
 
-## Node.js 直接使用 Storage Adapters
+## Node.js Direct Storage Adapter Usage
 
-如果不通过 BFF，可以直接在 Node.js 中使用存储适配器：
+You can also use storage adapters directly in Node.js without the BFF:
 
 ```typescript
 import { createNodeStore, getDefaultStore } from 'bff-store';
 import { jsonlStorage } from 'bff-store/jsonl';
 import { mongodbStorage } from 'bff-store/mongodb';
 
-// 使用 JSONL
+// Using JSONL
 const store = createNodeStore('entity-123', [
   { key: 'theme', defaultValue: 'dark' },
   { key: 'count', defaultValue: 0 },
@@ -136,15 +187,15 @@ const store = createNodeStore('entity-123', [
   storage: jsonlStorage({ dir: './sessions' }),
 });
 
-// 等待初始加载完成
+// Wait for initial load (5s timeout)
 await store.waitForLoad();
 
-// 使用 jotai getDefaultStore() 读写
+// Read/write via jotai getDefaultStore()
 const jotai = getDefaultStore();
-jotai.set(store.atoms.theme, 'light');   // 自动 debounce 持久化
+jotai.set(store.atoms.theme, 'light');   // auto-debounce persists
 console.log(jotai.get(store.atoms.count));
 
-// 或使用 MongoDB
+// Or using MongoDB
 const store2 = createNodeStore('entity-456', [
   { key: 'data', defaultValue: null },
 ], {
@@ -155,20 +206,32 @@ const store2 = createNodeStore('entity-456', [
 });
 ```
 
-### 环境检测
+### Environment Detection
 
 ```typescript
 import { isNode, isBrowser } from 'bff-store';
 
-if (isNode()) {
-  // Node.js 环境
-}
-
-if (isBrowser()) {
-  // 浏览器环境
-}
+if (isNode()) { /* Node.js */ }
+if (isBrowser()) { /* Browser */ }
 ```
 
+## Storage Backends
+
+### JSONL
+
+File format: `{dir}/{entityId}/{encodeURIComponent(key)}.jsonl`
+
+Each line is a JSON object with timestamp. `get` reads the last line for the latest value.
+
+### MongoDB
+
+Collection name: `state_{entityId}`. Each key uses upsert — only the latest value is kept.
+
+> For production, create a compound index on `key + entityId`:
+> ```javascript
+> db.state_<entityId>.createIndex({ key: 1, entityId: 1 }, { unique: true })
+> ```
+
 ## API Endpoints (BFF Server)
 
 | Method | Endpoint | Body | Description |
@@ -191,9 +254,18 @@ Creates a store with multiple persisted atoms.
 - `options.storage`: Storage adapter (required)
 - `options.debounceMs`: Debounce delay in ms (default: 800)
 
+### `waitForServer()`
+
+Returns a promise that resolves when the auto-started BFF server is ready. Only meaningful in Node.js with `remoteStorage`.
+
+```typescript
+import { waitForServer } from 'bff-store';
+await waitForServer();
+```
+
 ### `useStore(store)`
 
-React hook to use the store in components.
+React hook to consume the store in components.
 
 Returns: `{ ...data, ...setters, isLoading }`
 
@@ -201,26 +273,39 @@ Setter names are derived by capitalizing the config key:
 - `theme` → `setTheme`
 - `userName` → `setUserName`
 
+### `createNodeStore(entityId, config, options)`
+
+Node.js environment store with `waitForLoad()`.
+
+```typescript
+const store = createNodeStore('entity-123', config, { storage: adapter });
+await store.waitForLoad();  // 5s timeout
+```
+
 ### `remoteStorage(options?)`
 
 Creates a remote storage adapter for connecting to the BFF server.
 
 ```typescript
-// 基本用法 - BFF 使用默认存储后端
+// Basic
 const adapter = remoteStorage();
 
-// 指定使用 MongoDB
+// Use MongoDB
 const adapter = remoteStorage({
   backend: 'mongodb',
   mongoUrl: 'mongodb://user:pass@host:27017',
   mongoDb: 'myapp',
 });
 
-// 指定使用 JSONL
+// Use JSONL
 const adapter = remoteStorage({
   backend: 'jsonl',
   jsonlDir: '/tmp/my-app-data',
 });
+
+// Multi-tenant
+const adapter = remoteStorage({ entityId: 'user-123' });
+adapter.setEntityId('user-456');  // switch tenant
 ```
 
 - `options.baseUrl`: BFF server URL (default: `http://localhost:3847`)
@@ -228,24 +313,43 @@ const adapter = remoteStorage({
 - `options.backend`: Storage backend type `'mongodb'` or `'jsonl'`
 - `options.mongoUrl`: MongoDB connection URL (required if backend is mongodb)
 - `options.mongoDb`: MongoDB database name (default: `jotai_state_store`)
-- `options.jsonlDir`: JSONL storage directory (required if backend is jsonl)
+- `options.jsonlDir`: JSONL storage directory (default: `./data`)
 
 ### `startServer(options)`
 
 Starts the BFF server (singleton pattern). Import from `bff-store/server`.
 
-- `options.port`: Server port (default: 3847)
+```typescript
+import { startServer } from 'bff-store/server';
 
-Note: Storage backend is configured by the client via `remoteStorage()` options, not by the server.
+await startServer({
+  port: 3847,
+  backend: 'jsonl',
+  jsonlDir: './data',
+});
+```
 
 ## Package Exports
 
 | Export | Description | Environment |
 |--------|-------------|-------------|
-| `bff-store` | Main entry: createStore, useStore, createNodeStore, isNode, isBrowser, memoryStorage, remoteStorage | Browser + Node.js |
+| `bff-store` | Main: createStore, useStore, createNodeStore, waitForServer, isNode, isBrowser, memoryStorage, remoteStorage | Browser + Node.js |
 | `bff-store/jsonl` | JSONL storage adapter | Node.js only |
-| `bff-store/mongodb` | MongoDB storage adapter | Node.js only |
-| `bff-store/server` | BFF server (startServer, Router, etc.) | Node.js only |
+| `bff-store/mongodb` | MongoDB storage adapter (async factory) | Node.js only |
+| `bff-store/server` | BFF server: startServer, Router, EntityIdCache | Node.js only |
+
+## Changelog
+
+### v0.1.1 (2026-07-05)
+
+- `createStore` with `remote` storage now waits for server startup to complete
+- `waitForServer()` added for explicit server readiness
+- `remoteStorage.setEntityId()` now works correctly (live entityId reference)
+- MongoDB `set` uses upsert mode — no more unbounded document accumulation
+- JSONL key encoding changed to `encodeURIComponent` — prevents `a.b` / `a-b` collision
+- `atom.onMount` unmount cleanup cancels pending debounced writes
+- `waitForLoad()` now has a 5s timeout
+- HTTP error responses now include server-returned error details
 
 ## License
 

package/dist/cli.js

@@ -32025,12 +32025,11 @@ async function mongodbStorage(options2) {
     },
     async set(key, value) {
       const collection = getCollection(currentEntityId);
-      await collection.insertOne({
-        key,
-        value,
-        timestamp: Date.now(),
-        entityId: currentEntityId
-      });
+      await collection.updateOne(
+        { key, entityId: currentEntityId },
+        { $set: { value, timestamp: Date.now() } },
+        { upsert: true }
+      );
     },
     async remove(key) {
       const collection = getCollection(currentEntityId);
@@ -32133,7 +32132,7 @@ function jsonlStorage(options2) {
   const baseDir = options2?.dir ?? "./sessions";
   let entityId = "default";
   function getFilePath(eId, key) {
-    const safeKey = key.replace(/[^a-zA-Z0-9_]/g, "_");
+    const safeKey = encodeURIComponent(key);
     return path.join(baseDir, eId, `${safeKey}.jsonl`);
   }
   const storage = {
@@ -32281,7 +32280,7 @@ async function getCachedStorage(config, entityId) {
     }
     return entry.adapter.storage;
   }
-  if (storageCache.size >= MAX_CACHE_SIZE) {
+  while (storageCache.size >= MAX_CACHE_SIZE && storageCache.size > 0) {
     let oldestKey = null;
     let oldestTime = Infinity;
     for (const [k, entry] of storageCache.entries()) {
@@ -32292,6 +32291,8 @@ async function getCachedStorage(config, entityId) {
     }
     if (oldestKey) {
       storageCache.delete(oldestKey);
+    } else {
+      break;
     }
   }
   let adapter;
@@ -32324,6 +32325,7 @@ function createStorageHandlers(options2) {
       try {
         body = await parseBody(req);
       } catch {
+        console.warn("[bff-store] Failed to parse request body, using URL config only");
       }
     }
     const config = body ? {
@@ -32399,7 +32401,7 @@ function createStorageHandlers(options2) {
     res.writeHead(200);
     res.end(JSON.stringify({ success: true }));
   }
-  async function handleHealth(req, res) {
+  async function handleHealth(_req, res) {
     res.setHeader("Content-Type", "application/json");
     res.writeHead(200);
     res.end(JSON.stringify({ status: "ok" }));

package/dist/index.d.mts

@@ -79,6 +79,12 @@ declare function createStore(entityId: string, config: AtomConfigs, options?: {
     storage: StorageAdapter;
     debounceMs?: number;
 }): Store;
+/**
+ * Wait for the auto-started server to be ready.
+ * Only meaningful when using remote storage in Node.js;
+ * returns a resolved promise in browser environments.
+ */
+declare function waitForServer(): Promise<void> | undefined;
 
 /**
  * React Hook to use a store
@@ -270,4 +276,4 @@ declare function createNodeStore(entityId: string, config: AtomConfigs, options:
     waitForLoad(): Promise<void>;
 };
 
-export { type AsyncStorageFactory, type AtomConfig, type AtomConfigs, type AtomType, HttpTransport, type MemoryStorageOptions, RestStorageProtocol, type Storage, type StorageAdapter, type StorageFactory, type StorageHttpProtocol, type StorageOptions, type Store, type TransportAdapter, type UseStoreReturn, createMemoryStorage, createNodeStore, createPersistedAtom, remoteStorage as createRemoteStorage, createStorageFromTransport, createStorageWithProtocol, createStore, isBrowser, isNode, memoryStorage, remoteStorage, useStore };
+export { type AsyncStorageFactory, type AtomConfig, type AtomConfigs, type AtomType, HttpTransport, type MemoryStorageOptions, RestStorageProtocol, type Storage, type StorageAdapter, type StorageFactory, type StorageHttpProtocol, type StorageOptions, type Store, type TransportAdapter, type UseStoreReturn, createMemoryStorage, createNodeStore, createPersistedAtom, remoteStorage as createRemoteStorage, createStorageFromTransport, createStorageWithProtocol, createStore, isBrowser, isNode, memoryStorage, remoteStorage, useStore, waitForServer };

package/dist/index.d.ts

@@ -79,6 +79,12 @@ declare function createStore(entityId: string, config: AtomConfigs, options?: {
     storage: StorageAdapter;
     debounceMs?: number;
 }): Store;
+/**
+ * Wait for the auto-started server to be ready.
+ * Only meaningful when using remote storage in Node.js;
+ * returns a resolved promise in browser environments.
+ */
+declare function waitForServer(): Promise<void> | undefined;
 
 /**
  * React Hook to use a store
@@ -270,4 +276,4 @@ declare function createNodeStore(entityId: string, config: AtomConfigs, options:
     waitForLoad(): Promise<void>;
 };
 
-export { type AsyncStorageFactory, type AtomConfig, type AtomConfigs, type AtomType, HttpTransport, type MemoryStorageOptions, RestStorageProtocol, type Storage, type StorageAdapter, type StorageFactory, type StorageHttpProtocol, type StorageOptions, type Store, type TransportAdapter, type UseStoreReturn, createMemoryStorage, createNodeStore, createPersistedAtom, remoteStorage as createRemoteStorage, createStorageFromTransport, createStorageWithProtocol, createStore, isBrowser, isNode, memoryStorage, remoteStorage, useStore };
+export { type AsyncStorageFactory, type AtomConfig, type AtomConfigs, type AtomType, HttpTransport, type MemoryStorageOptions, RestStorageProtocol, type Storage, type StorageAdapter, type StorageFactory, type StorageHttpProtocol, type StorageOptions, type Store, type TransportAdapter, type UseStoreReturn, createMemoryStorage, createNodeStore, createPersistedAtom, remoteStorage as createRemoteStorage, createStorageFromTransport, createStorageWithProtocol, createStore, isBrowser, isNode, memoryStorage, remoteStorage, useStore, waitForServer };

package/dist/index.mjs

@@ -30,8 +30,9 @@ var DebouncerMap = class {
   }
   getDebouncer(key, ms) {
     let debouncer = this.debouncers.get(key);
-    if (!debouncer) {
-      debouncer = createDebouncer(ms ?? this.defaultMs);
+    const effectiveMs = ms ?? this.defaultMs;
+    if (!debouncer || debouncer.ms !== effectiveMs) {
+      debouncer = createDebouncer(effectiveMs);
       this.debouncers.set(key, debouncer);
     }
     return debouncer;
@@ -73,12 +74,18 @@ function createPersistedAtom(config, entityId, storage, options) {
       if (value !== null && value !== void 0) {
         setValue(value);
       }
-    }).catch(console.error).finally(() => {
+    }).catch((err) => {
+      console.error(`[bff-store] Failed to load atom "${config.key}":`, err);
+    }).finally(() => {
       setTimeout(() => {
         const store = getDefaultStore();
         store.set(loadingAtom, false);
       }, 0);
     });
+    return () => {
+      const debounceKey = `${entityId}:${config.key}`;
+      debouncerMap.cancel(debounceKey);
+    };
   };
   const writeAtom = atom(
     (get) => get(baseAtom),
@@ -104,12 +111,13 @@ function createPersistedAtom(config, entityId, storage, options) {
 }
 
 // src/createStore.ts
+var serverInitPromise = null;
 function createStore(entityId, config, options) {
   const adapter = options?.storage;
   const debounceMs = options?.debounceMs ?? 800;
   if (adapter?.name === "remote" && typeof window === "undefined" && typeof process !== "undefined") {
-    import("./server-V7WCW4ZB.mjs").then(({ startServer }) => {
-      startServer().catch((err) => {
+    import("./server-2WMLXQ23.mjs").then(({ startServer }) => {
+      serverInitPromise = startServer().then(() => void 0).catch((err) => {
         console.error("[bff-store] Failed to auto-start server:", err);
       });
     });
@@ -138,6 +146,9 @@ function createStore(entityId, config, options) {
     loadingAtoms
   };
 }
+function waitForServer() {
+  return serverInitPromise;
+}
 
 // src/useStore.ts
 import { useAtom } from "jotai";
@@ -224,7 +235,13 @@ var HttpTransport = class {
   async get(url) {
     const res = await fetch(url);
     if (!res.ok) {
-      throw new Error(`GET ${url} failed: ${res.statusText}`);
+      let detail = res.statusText;
+      try {
+        const body = await res.clone().json();
+        detail = body?.error ?? body?.message ?? detail;
+      } catch {
+      }
+      throw new Error(`GET ${url} failed: ${detail}`);
     }
     return res.json();
   }
@@ -235,14 +252,26 @@ var HttpTransport = class {
       body: JSON.stringify(body)
     });
     if (!res.ok) {
-      throw new Error(`POST ${url} failed: ${res.statusText}`);
+      let detail = res.statusText;
+      try {
+        const errBody = await res.clone().json();
+        detail = errBody?.error ?? errBody?.message ?? detail;
+      } catch {
+      }
+      throw new Error(`POST ${url} failed: ${detail}`);
     }
     return res.json();
   }
   async delete(url) {
     const res = await fetch(url, { method: "DELETE" });
     if (!res.ok) {
-      throw new Error(`DELETE ${url} failed: ${res.statusText}`);
+      let detail = res.statusText;
+      try {
+        const errBody = await res.clone().json();
+        detail = errBody?.error ?? errBody?.message ?? detail;
+      } catch {
+      }
+      throw new Error(`DELETE ${url} failed: ${detail}`);
     }
   }
 };
@@ -404,7 +433,7 @@ function remoteStorage(options = {}) {
     mongoDb: options.mongoDb,
     jsonlDir: options.jsonlDir
   };
-  const protocol = options.protocol ?? new RestStorageProtocol(baseUrl, entityId.current, backendConfig);
+  const protocol = options.protocol ?? new RestStorageProtocol(baseUrl, entityId, backendConfig);
   const storage = createStorageWithProtocol(transport, protocol);
   const adapter = {
     storage,
@@ -429,21 +458,26 @@ import { getDefaultStore as getDefaultStore3 } from "jotai";
 function createNodeStore(entityId, config, options) {
   const store = createStore(entityId, config, options);
   const jotaiStore = getDefaultStore3();
-  async function waitForLoad() {
+  async function waitForLoad(timeoutMs = 5e3) {
     for (const atom2 of Object.values(store.atoms)) {
       jotaiStore.sub(atom2, () => {
       });
     }
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
       const loadingAtoms = Object.values(store.loadingAtoms);
       const stillLoading = () => loadingAtoms.some((atom2) => jotaiStore.get(atom2));
       if (!stillLoading()) {
         resolve();
         return;
       }
+      const timeout = setTimeout(() => {
+        clearInterval(interval);
+        reject(new Error(`waitForLoad timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
       const interval = setInterval(() => {
         if (!stillLoading()) {
           clearInterval(interval);
+          clearTimeout(timeout);
           resolve();
         }
       }, 10);
@@ -469,5 +503,6 @@ export {
   isNode,
   memoryStorage,
   remoteStorage,
-  useStore
+  useStore,
+  waitForServer
 };

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bff-store",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A jotai-based state management library with pluggable storage adapters",
   "main": "index.js",
   "module": "index.mjs",