bff-store 0.1.1 → 0.1.2

package/docs/bugs/08-dead-code-getStorageForRequest.md

@@ -0,0 +1,18 @@
+# BUG-08: `getStorageForRequest` 死代码
+
+**Severity**: Medium
+**Location**: `src/server/handlers.ts:128-146`
+**Type**: Dead Code
+
+## 问题
+
+函数 `getStorageForRequest` 定义后从未被调用，与 `resolveStorage` 功能重复。
+
+## 修复
+
+已删除。
+
+## 验证
+
+- Build: ✅
+- Tests: ✅ (69 passed)

package/docs/bugs/09-waitForLoad-infinite.md

@@ -0,0 +1,37 @@
+# BUG-09: `waitForLoad` 无限等待
+
+**Severity**: Low
+**Location**: `src/nodeStore.ts:47-72`
+**Type**: Infinite Wait
+
+## 问题
+
+`waitForLoad()` 使用 `setInterval` 轮询 loading atoms，无超时保护。若 storage 持续故障，promise 永不 resolve。
+
+## 修复
+
+添加 5s 超时，超时时 reject：
+
+```typescript
+async function waitForLoad(timeoutMs: number = 5000): Promise<void> {
+  return new Promise((resolve, reject) => {
+    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);
+  });
+}
+```
+
+## 验证
+
+- Build: ✅
+- Tests: ✅ (69 passed)

package/docs/bugs/10-parseBody-silent-failure.md

@@ -0,0 +1,32 @@
+# BUG-10: `parseBody` 失败静默忽略
+
+**Severity**: Low
+**Location**: `src/server/handlers.ts:159`
+**Type**: Error Swallowing
+
+## 问题
+
+`resolveStorage` 中 `parseBody` 失败时静默忽略，导致 backend 配置丢失无法定位问题：
+
+```typescript
+try {
+  body = await parseBody<Record<string, unknown>>(req);
+} catch {
+  // Ignore parse errors  ← 无日志
+}
+```
+
+## 修复
+
+添加 `console.warn` 记录：
+
+```typescript
+} catch {
+  console.warn('[bff-store] Failed to parse request body, using URL config only');
+}
+```
+
+## 验证
+
+- Build: ✅
+- Tests: ✅ (69 passed)

package/docs/bugs/11-mongodb-storage-leak.high.md

@@ -0,0 +1,35 @@
+# BUG-11: MongoDB `set` 无限积累旧版本
+
+**Severity**: High
+**Location**: `src/storage/mongodb.ts:63`
+**Type**: Storage Leak
+
+## 问题
+
+`set` 使用 `insertOne` 每次都插入新 document，从不清理旧版本：
+
+```typescript
+await collection.insertOne({
+  key, value, timestamp: Date.now(), entityId: currentEntityId,
+});
+// 每次 set 都插入新行，旧版本永远存在 → collection 无限膨胀
+```
+
+`remove` 使用 `deleteMany` 留下 tombstone（空 collection 仍存在）。
+
+## 修复
+
+改用 `updateOne` + `upsert: true` 原地更新：
+
+```typescript
+await collection.updateOne(
+  { key, entityId: currentEntityId },
+  { $set: { value, timestamp: Date.now() } },
+  { upsert: true }
+);
+```
+
+## 验证
+
+- Build: ✅
+- Tests: ✅ (69 passed)

package/docs/bugs/12-setEntityId-stale-closure.high.md

@@ -0,0 +1,35 @@
+# BUG-12: `setEntityId` 不生效（闭包捕获快照值）
+
+**Severity**: High
+**Location**: `src/storage/adapters/remoteStorage.ts:56`
+**Type**: Stale Closure
+
+## 问题
+
+`RestStorageProtocol` 构造时传入 `entityId.current`（string）的快照值，后续 `setEntityId()` 更新 `entityId.current` 但 protocol 内部的 `getEntityId()` 仍读旧值：
+
+```typescript
+// remoteStorage.ts
+const entityId = { current: options.entityId };
+const protocol = new RestStorageProtocol(baseUrl, entityId.current, ...);  // ← 快照 string
+
+// RestStorageProtocol.getEntityId()
+return typeof this.entityId === 'object'
+  ? this.entityId.current  // 只有 string，访问 .current 返回 undefined
+  : this.entityId;
+```
+
+## 修复
+
+传入 `{ current }` 对象引用而非字符串快照：
+
+```typescript
+const protocol = new RestStorageProtocol(baseUrl, entityId, ...);  // ← live 引用
+```
+
+`getEntityId()` 每次调用时动态读取 `this.entityId.current`。
+
+## 验证
+
+- Build: ✅
+- Tests: ✅ (69 passed)

package/docs/bugs/14-dead-code-isServerRunning.md

@@ -0,0 +1,18 @@
+# BUG-14: `isServerRunning()` 未使用
+
+**Severity**: Low
+**Location**: `src/server/index.ts:41-43`
+**Type**: Dead Code
+
+## 问题
+
+函数 `isServerRunning()` 定义后从未被调用。
+
+## 修复
+
+已删除。
+
+## 验证
+
+- Build: ✅
+- Tests: ✅ (69 passed)

package/docs/bugs/15-unmount-data-loss.md

@@ -0,0 +1,37 @@
+# BUG-15: unmount 时 pending writes 丢失
+
+**Severity**: Medium
+**Location**: `src/atomCreator.ts:25-41`
+**Type**: Data Loss
+
+## 问题
+
+`baseAtom.onMount` 未返回 cleanup 函数，组件卸载时 pending debounced writes 仍在计时器队列中：
+
+1. 用户快速编辑 → 触发多个 debounced writes
+2. 组件卸载（如路由切换）→ pending writes 仍在队列
+3. 计时器触发时，`getDefaultStore()` 在已销毁的上下文中被调用
+4. 数据写入丢失
+
+## 修复
+
+`onMount` 返回 cleanup 函数取消 pending writes：
+
+```typescript
+baseAtom.onMount = (setValue) => {
+  storage.get<T>(config.key)
+    .then((value) => { if (value != null) setValue(value); })
+    .catch((err) => { console.error(`[bff-store] Failed to load atom "${config.key}":`, err); })
+    .finally(() => { /* loadingAtom = false */ });
+
+  return () => {
+    const debounceKey = `${entityId}:${config.key}`;
+    debouncerMap.cancel(debounceKey);
+  };
+};
+```
+
+## 验证
+
+- Build: ✅
+- Tests: ✅ (69 passed)

package/docs/bugs/17-unused-parameter.md

@@ -0,0 +1,26 @@
+# BUG-17: `handleHealth` 未使用参数
+
+**Severity**: Low
+**Location**: `src/server/handlers.ts:240`
+**Type**: Unused Parameter
+
+## 问题
+
+`handleHealth` 的 `req` 参数未使用：
+
+```typescript
+async function handleHealth(req: IncomingMessage, res: ServerResponse): Promise<void> {
+```
+
+## 修复
+
+标记为 `_req` 明确表示未使用：
+
+```typescript
+async function handleHealth(_req: IncomingMessage, res: ServerResponse): Promise<void> {
+```
+
+## 验证
+
+- Build: ✅
+- Tests: ✅ (69 passed)

package/docs/bugs/18-storage-get-silent-error.md

@@ -0,0 +1,28 @@
+# BUG-18: `storage.get` 失败时静默忽略
+
+**Severity**: Low
+**Location**: `src/atomCreator.ts:25-41`
+**Type**: Silent Error
+
+## 问题
+
+`baseAtom.onMount` 中 `storage.get().catch(console.error)` 吞掉加载错误，开发者无法感知数据加载失败：
+
+```typescript
+.catch(console.error)  // 只打 console.error，无结构化日志
+```
+
+## 修复
+
+添加包含 atom key 的错误信息：
+
+```typescript
+.catch((err) => {
+  console.error(`[bff-store] Failed to load atom "${config.key}":`, err);
+})
+```
+
+## 验证
+
+- Build: ✅
+- Tests: ✅ (69 passed)

package/docs/bugs/README.md

@@ -0,0 +1,35 @@
+# Bug 索引
+
+Post-Mortem 2026-07-05 四轮审查共发现 **18 个 bug**，**15 个已修复**。
+
+> High severity 文件名末尾标注 `.high`。
+
+## 已修复
+
+| # | Severity | File | Bug |
+|---|----------|------|-----|
+| 01 | High | [01-server-async-startup.high.md](./01-server-async-startup.high.md) | server 异步启动未等待 |
+| 03 | Medium | [03-storage-cache-eviction.md](./03-storage-cache-eviction.md) | 缓存满时只驱逐 1 个 entry |
+| 04 | Medium | [04-http-error-body-loss.md](./04-http-error-body-loss.md) | HTTP 错误响应 body 丢失 |
+| 05 | Low | [05-debouncer-ms-ignored.md](./05-debouncer-ms-ignored.md) | debouncer ms 参数后续调用无效 |
+| 07 | High | [07-jsonl-key-collision.high.md](./07-jsonl-key-collision.high.md) | JSONL key 碰撞导致数据覆盖 |
+| 08 | Medium | [08-dead-code-getStorageForRequest.md](./08-dead-code-getStorageForRequest.md) | `getStorageForRequest` 死代码 |
+| 09 | Low | [09-waitForLoad-infinite.md](./09-waitForLoad-infinite.md) | `waitForLoad` 无限等待 |
+| 10 | Low | [10-parseBody-silent-failure.md](./10-parseBody-silent-failure.md) | `parseBody` 失败静默忽略 |
+| 11 | High | [11-mongodb-storage-leak.high.md](./11-mongodb-storage-leak.high.md) | MongoDB `set` 无限积累旧版本 |
+| 12 | High | [12-setEntityId-stale-closure.high.md](./12-setEntityId-stale-closure.high.md) | `setEntityId` 不生效（闭包捕获快照值） |
+| 14 | Low | [14-dead-code-isServerRunning.md](./14-dead-code-isServerRunning.md) | `isServerRunning()` 未使用 |
+| 15 | Medium | [15-unmount-data-loss.md](./15-unmount-data-loss.md) | unmount 时 pending writes 丢失 |
+| 17 | Low | [17-unused-parameter.md](./17-unused-parameter.md) | `handleHealth` 未使用参数 |
+| 18 | Low | [18-storage-get-silent-error.md](./18-storage-get-silent-error.md) | `storage.get` 失败时静默忽略 |
+
+## 未修复（设计选择）
+
+| # | Reason |
+|---|--------|
+| BUG-06 | module-level `debouncerMap` 通过 `entityId:key` 隔离键名，实际无跨 store 干扰 |
+| BUG-13 | `createStorageFromTransport.get` 所有错误返回 null — 符合 storage graceful degradation 哲学 |
+| BUG-16 | serverInitPromise 时序 — 符合 fire-and-forget 设计，`waitForServer()` 可供显式等待 |
+| BUG-19 | GET 请求解析 body — 无害 no-op |
+| BUG-20 | MongoDB 无复合索引 — 用户在数据库层处理 |
+| BUG-21 | `setTimeout` unmount 后触发 — 无害 side effect |

package/package.json

@@ -1,10 +1,7 @@
 {
   "name": "bff-store",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "A jotai-based state management library with pluggable storage adapters",
-  "publishConfig": {
-    "access": "public"
-  },
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",

package/src/atomCreator.ts

@@ -30,14 +30,22 @@ export function createPersistedAtom<T>(
           setValue(value);
         }
       })
-      .catch(console.error)
+      .catch((err) => {
+        console.error(`[bff-store] Failed to load atom "${config.key}":`, err);
+      })
       .finally(() => {
-        // Mark as loaded
+        // Mark as loaded regardless of success or failure
         setTimeout(() => {
           const store = getDefaultStore();
           store.set(loadingAtom, false);
         }, 0);
       });
+
+    // Cancel pending debounced write on unmount to avoid writes from a destroyed component
+    return () => {
+      const debounceKey = `${entityId}:${config.key}`;
+      debouncerMap.cancel(debounceKey);
+    };
   };
 
   // Create write atom with persistence

package/src/createStore.ts

@@ -2,6 +2,13 @@ import type { AtomConfigs, Store, StoreAtoms, StoreLoadingAtoms } from './types'
 import type { StorageAdapter } from './storage/base';
 import { createPersistedAtom } from './atomCreator';
 
+/**
+ * Module-level promise for the auto-started server.
+ * Shared across all createStore calls so concurrent invocations
+ * wait on the same server instance.
+ */
+let serverInitPromise: Promise<unknown> | null = null;
+
 /**
  * Creates a store with multiple persisted atoms
  *
@@ -36,9 +43,11 @@ export function createStore(
 
   // Auto-start embedded server when using remote storage (Node.js only)
   // In browser/Next.js environments, remoteStorage connects to an already-running BFF server
+  // serverInitPromise is module-level so concurrent createStore calls share the same promise
   if (adapter?.name === 'remote' && typeof window === 'undefined' && typeof process !== 'undefined') {
     import('./server').then(({ startServer }) => {
-      startServer().catch((err) => {
+      // startServer is a singleton; concurrent calls share the same promise
+      serverInitPromise = startServer().then(() => void 0).catch((err) => {
         console.error('[bff-store] Failed to auto-start server:', err);
       });
     });
@@ -75,3 +84,12 @@ export function createStore(
     loadingAtoms,
   };
 }
+
+/**
+ * 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.
+ */
+export function waitForServer(): Promise<void> | undefined {
+  return serverInitPromise as Promise<void> | undefined;
+}

package/src/debouncer.ts

@@ -47,8 +47,11 @@ export class DebouncerMap {
 
   getDebouncer(key: string, ms?: number): Debouncer {
     let debouncer = this.debouncers.get(key);
-    if (!debouncer) {
-      debouncer = createDebouncer(ms ?? this.defaultMs);
+    const effectiveMs = ms ?? this.defaultMs;
+
+    // Create new debouncer if none exists, or if ms differs from existing one
+    if (!debouncer || debouncer.ms !== effectiveMs) {
+      debouncer = createDebouncer(effectiveMs);
       this.debouncers.set(key, debouncer);
     }
     return debouncer;

package/src/index.ts

@@ -2,7 +2,7 @@
 // Main Export
 // ========================================
 
-export { createStore } from './createStore';
+export { createStore, waitForServer } from './createStore';
 export { useStore } from './useStore';
 export { createPersistedAtom } from './atomCreator';
 

package/src/nodeStore.ts

@@ -44,7 +44,7 @@ export function createNodeStore(
   const store = createStore(entityId, config, options);
   const jotaiStore = getDefaultStore();
 
-  async function waitForLoad(): Promise<void> {
+  async function waitForLoad(timeoutMs: number = 5000): Promise<void> {
     // Trigger onMount for all atoms by subscribing to them
     // In Node.js, sub() triggers onMount (unlike get() which doesn't)
     for (const atom of Object.values(store.atoms)) {
@@ -52,7 +52,7 @@ export function createNodeStore(
     }
 
     // Now wait for all loading atoms to become false
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
       const loadingAtoms = Object.values(store.loadingAtoms);
       const stillLoading = () => loadingAtoms.some((atom) => jotaiStore.get(atom));
 
@@ -61,10 +61,17 @@ export function createNodeStore(
         return;
       }
 
+      // Timeout protection
+      const timeout = setTimeout(() => {
+        clearInterval(interval);
+        reject(new Error(`waitForLoad timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+
       // Poll until all are loaded
       const interval = setInterval(() => {
         if (!stillLoading()) {
           clearInterval(interval);
+          clearTimeout(timeout);
           resolve();
         }
       }, 10);

package/src/server/handlers.ts

@@ -81,8 +81,8 @@ async function getCachedStorage(config: BackendConfig, entityId?: string): Promi
     return entry.adapter.storage;
   }
 
-  // Evict oldest if cache is full
-  if (storageCache.size >= MAX_CACHE_SIZE) {
+  // Evict oldest entries until there's space for a new one
+  while (storageCache.size >= MAX_CACHE_SIZE && storageCache.size > 0) {
     let oldestKey: string | null = null;
     let oldestTime = Infinity;
     for (const [k, entry] of storageCache.entries()) {
@@ -93,6 +93,8 @@ async function getCachedStorage(config: BackendConfig, entityId?: string): Promi
     }
     if (oldestKey) {
       storageCache.delete(oldestKey);
+    } else {
+      break; // should not happen, but guard against infinite loop
     }
   }
 
@@ -123,26 +125,6 @@ async function getCachedStorage(config: BackendConfig, entityId?: string): Promi
   return adapter.storage;
 }
 
-async function getStorageForRequest(
-  req: IncomingMessage,
-  entityId?: string
-): Promise<Storage> {
-  const urlConfig = getBackendConfig(req);
-  const body = await parseBody<BackendConfig>(req);
-
-  const config: BackendConfig = {
-    backend: body.backend ?? urlConfig.backend,
-    mongoUrl: body.mongoUrl ?? urlConfig.mongoUrl,
-    mongoDb: body.mongoDb ?? urlConfig.mongoDb,
-    jsonlDir: body.jsonlDir ?? urlConfig.jsonlDir,
-  };
-
-  // Periodic cleanup of expired cache entries
-  cleanExpiredCache();
-
-  return getCachedStorage(config, entityId);
-}
-
 export function createStorageHandlers(options: StorageHandlersOptions) {
   const { getStorage } = options;
 
@@ -157,7 +139,8 @@ export function createStorageHandlers(options: StorageHandlersOptions) {
       try {
         body = await parseBody<Record<string, unknown>>(req);
       } catch {
-        // Ignore parse errors
+        // Ignore parse errors - fall back to urlConfig only
+        console.warn('[bff-store] Failed to parse request body, using URL config only');
       }
     }
 
@@ -254,7 +237,7 @@ export function createStorageHandlers(options: StorageHandlersOptions) {
     res.end(JSON.stringify({ success: true }));
   }
 
-  async function handleHealth(req: IncomingMessage, res: ServerResponse): Promise<void> {
+  async function handleHealth(_req: IncomingMessage, res: ServerResponse): Promise<void> {
     res.setHeader('Content-Type', 'application/json');
     res.writeHead(200);
     res.end(JSON.stringify({ status: 'ok' }));

package/src/server/index.ts

@@ -38,10 +38,6 @@ const defaultOptions: ServerOptions = {
   jsonlDir: './data',
 };
 
-function isServerRunning(): boolean {
-  return serverInstance !== null;
-}
-
 /**
  * Start the embedded API server (singleton).
  *

package/src/storage/adapters/remoteStorage.ts

@@ -53,7 +53,8 @@ export function remoteStorage(options: RemoteStorageOptions = {}): StorageAdapte
     jsonlDir: options.jsonlDir,
   };
 
-  const protocol = options.protocol ?? new RestStorageProtocol(baseUrl, entityId.current, backendConfig);
+  // Pass the entityId object ref so getEntityId() reads the live value on each request
+  const protocol = options.protocol ?? new RestStorageProtocol(baseUrl, entityId, backendConfig);
   const storage = createStorageWithProtocol(transport, protocol);
 
   const adapter: StorageAdapter = {

package/src/storage/jsonl.ts

@@ -29,7 +29,9 @@ export function jsonlStorage(options?: JsonlStorageOptions): JsonlStorageInstanc
   let entityId: string = 'default';
 
   function getFilePath(eId: string, key: string): string {
-    const safeKey = key.replace(/[^a-zA-Z0-9_]/g, '_');
+    // Use encodeURIComponent to avoid key collision:
+    // "user.name", "user-name", "user%2Ename" all produce distinct filenames
+    const safeKey = encodeURIComponent(key);
     return path.join(baseDir, eId, `${safeKey}.jsonl`);
   }
 

package/src/storage/mongodb.ts

@@ -60,12 +60,12 @@ export async function mongodbStorage(
     async set<T>(key: string, value: T): Promise<void> {
       const collection = getCollection(currentEntityId);
 
-      await collection.insertOne({
-        key,
-        value,
-        timestamp: Date.now(),
-        entityId: currentEntityId,
-      });
+      // Use upsert to avoid accumulating duplicate entries over time
+      await collection.updateOne(
+        { key, entityId: currentEntityId },
+        { $set: { value, timestamp: Date.now() } },
+        { upsert: true }
+      );
     },
 
     async remove(key: string): Promise<void> {

package/src/storage/transport.ts

@@ -21,7 +21,14 @@ export class HttpTransport implements TransportAdapter {
   async get<T>(url: string): Promise<T> {
     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 {
+        // body is not JSON or unreadable, use statusText only
+      }
+      throw new Error(`GET ${url} failed: ${detail}`);
     }
     return res.json();
   }
@@ -33,7 +40,14 @@ export class HttpTransport implements TransportAdapter {
       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 {
+        // body is not JSON or unreadable, use statusText only
+      }
+      throw new Error(`POST ${url} failed: ${detail}`);
     }
     return res.json();
   }
@@ -41,7 +55,14 @@ export class HttpTransport implements TransportAdapter {
   async delete(url: string): Promise<void> {
     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 {
+        // body is not JSON or unreadable, use statusText only
+      }
+      throw new Error(`DELETE ${url} failed: ${detail}`);
     }
   }
 }

package/tests/storage/jsonl.test.ts

@@ -79,16 +79,32 @@ describe('jsonlStorage', () => {
       expect(await adapter2.storage.get('key')).toBe('value2');
     });
 
-    it('should sanitize key in filename', async () => {
+    it('should encode key in filename to avoid collision', async () => {
       const adapter = jsonlStorage({ dir: testDir });
       adapter.setEntityId('entity1');
 
       await adapter.storage.set('key with spaces', 'value');
 
-      const filePath = path.join(testDir, 'entity1', 'key_with_spaces.jsonl');
+      // encodeURIComponent converts " " → "%20", producing a collision-safe filename
+      const filePath = path.join(testDir, 'entity1', 'key%20with%20spaces.jsonl');
       expect(fs.existsSync(filePath)).toBe(true);
     });
 
+    it('should not collide on keys with dots and hyphens', async () => {
+      const adapter = jsonlStorage({ dir: testDir });
+      adapter.setEntityId('entity1');
+
+      await adapter.storage.set('user.name', 'value1');
+      await adapter.storage.set('user-name', 'value2');
+
+      const filePath1 = path.join(testDir, 'entity1', 'user.name.jsonl');
+      const filePath2 = path.join(testDir, 'entity1', 'user-name.jsonl');
+      expect(fs.existsSync(filePath1)).toBe(true);
+      expect(fs.existsSync(filePath2)).toBe(true);
+      expect(await adapter.storage.get('user.name')).toBe('value1');
+      expect(await adapter.storage.get('user-name')).toBe('value2');
+    });
+
     it('should handle multiple types', async () => {
       const adapter = jsonlStorage({ dir: testDir });
       adapter.setEntityId('entity1');