bff-store 0.1.0 → 0.1.2

package/docs/bugs/04-http-error-body-loss.md

@@ -0,0 +1,38 @@
+# BUG-04: HTTP 错误响应 body 丢失
+
+**Severity**: Medium
+**Location**: `src/storage/transport.ts:22-26`
+**Type**: Error Info Loss
+
+## 问题
+
+`HttpTransport` 的 GET/POST/DELETE 在 HTTP 错误时只返回 `statusText`，丢失 server 返回的错误详情：
+
+```typescript
+if (!res.ok) {
+  throw new Error(`GET ${url} failed: ${res.statusText}`);
+  // 若 server 返回 { "error": "entity not found" }，此处只有 "Not Found"
+}
+```
+
+## 修复
+
+尝试读取响应 body 作为错误详情：
+
+```typescript
+if (!res.ok) {
+  let detail = res.statusText;
+  try {
+    const body = await res.clone().json();
+    detail = body?.error ?? body?.message ?? detail;
+  } catch {
+    // body is not JSON or unreadable
+  }
+  throw new Error(`GET ${url} failed: ${detail}`);
+}
+```
+
+## 验证
+
+- Build: ✅
+- Tests: ✅ (69 passed)

package/docs/bugs/05-debouncer-ms-ignored.md

@@ -0,0 +1,41 @@
+# BUG-05: debouncer ms 参数后续调用无效
+
+**Severity**: Low
+**Location**: `src/debouncer.ts:48-55`
+**Type**: Logic Error
+
+## 问题
+
+`DebouncerMap.getDebouncer()` 在 key 已存在时忽略传入的 `ms` 参数：
+
+```typescript
+getDebouncer(key: string, ms?: number): Debouncer {
+  let debouncer = this.debouncers.get(key);
+  if (!debouncer) {
+    debouncer = createDebouncer(ms ?? this.defaultMs);
+    this.debouncers.set(key, debouncer);
+  }
+  return debouncer;  // 后续传入不同 ms 被忽略
+}
+```
+
+## 修复
+
+ms 不同时替换已有 debouncer 实例：
+
+```typescript
+getDebouncer(key: string, ms?: number): Debouncer {
+  const effectiveMs = ms ?? this.defaultMs;
+  let debouncer = this.debouncers.get(key);
+  if (!debouncer || debouncer.ms !== effectiveMs) {
+    debouncer = createDebouncer(effectiveMs);
+    this.debouncers.set(key, debouncer);
+  }
+  return debouncer;
+}
+```
+
+## 验证
+
+- Build: ✅
+- Tests: ✅ (10 debouncer tests passed)

package/docs/bugs/07-jsonl-key-collision.high.md

@@ -0,0 +1,31 @@
+# BUG-07: JSONL key 碰撞导致数据覆盖
+
+**Severity**: High
+**Location**: `src/storage/jsonl.ts:32`
+**Type**: Key Collision
+
+## 问题
+
+`getFilePath` 将所有非字母数字字符替换为 `_`：
+
+```typescript
+const safeKey = key.replace(/[^a-zA-Z0-9_]/g, '_');
+// "user.name" → "user_name"
+// "user-name" → "user_name"  ← 碰撞！
+```
+
+## 修复
+
+改用 `encodeURIComponent` 生成碰撞安全的文件名：
+
+```typescript
+const safeKey = encodeURIComponent(key);
+// "user.name" → "user.name"  (实际 "user%2Ename")
+// "user-name" → "user-name"
+// "user name" → "user%20name"
+```
+
+## 验证
+
+- Build: ✅
+- Tests: ✅ (11 jsonl tests passed，含碰撞回归测试)

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,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": "dist/index.js",
   "module": "dist/index.mjs",
@@ -8,8 +8,7 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
+      "import": "./dist/index.mjs"
     },
     "./jsonl": {
       "types": "./dist/storage/jsonl-entry.d.ts",
@@ -50,13 +49,11 @@
     "@types/react": "^19.2.16",
     "jotai": "^2.6.0",
     "jsdom": "^29.1.1",
+    "mongodb": "^6.21.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
     "vitest": "^1.0.0"
-  },
-  "dependencies": {
-    "mongodb": "^6.21.0"
   }
 }

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/environment.ts

@@ -0,0 +1,11 @@
+/**
+ * Environment detection utilities
+ */
+
+export function isNode(): boolean {
+  return typeof window === 'undefined' && typeof process !== 'undefined';
+}
+
+export function isBrowser(): boolean {
+  return typeof window !== 'undefined';
+}

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';
 
@@ -33,3 +33,10 @@ export { HttpTransport, createStorageFromTransport } from './storage/transport';
 export { RestStorageProtocol, createStorageWithProtocol } from './storage/protocol';
 export type { TransportAdapter } from './storage/transport';
 export type { StorageHttpProtocol } from './storage/protocol';
+
+// ========================================
+// Node.js Utilities
+// ========================================
+
+export { isNode, isBrowser } from './environment';
+export { createNodeStore } from './nodeStore';

package/src/nodeStore.ts

@@ -0,0 +1,86 @@
+import { getDefaultStore } from 'jotai';
+import { createStore } from './createStore';
+import type { AtomConfigs, StoreAtoms, StoreLoadingAtoms } from './types';
+import type { StorageAdapter } from './storage/base';
+
+/**
+ * Create a store for Node.js environments.
+ *
+ * @example
+ * ```typescript
+ * import { jsonlStorage } from 'bff-store/jsonl';
+ * import { createNodeStore } from 'bff-store';
+ *
+ * const store = createNodeStore('entity-123', [
+ *   { key: 'theme', defaultValue: 'dark' },
+ * ], {
+ *   storage: jsonlStorage({ dir: './sessions' }),
+ * });
+ *
+ * await store.waitForLoad();
+ *
+ * const jotai = getDefaultStore();
+ * jotai.set(store.atoms.theme, 'light');
+ * ```
+ */
+export function createNodeStore(
+  entityId: string,
+  config: AtomConfigs,
+  options: {
+    storage: StorageAdapter;
+    debounceMs?: number;
+  }
+): {
+  /** Atoms to use with getDefaultStore().get/set */
+  atoms: StoreAtoms;
+  /** Loading state atoms */
+  loadingAtoms: StoreLoadingAtoms;
+  /**
+   * Wait for all atoms to finish loading from storage.
+   * Call this after creating the store to ensure data is ready.
+   */
+  waitForLoad(): Promise<void>;
+} {
+  const store = createStore(entityId, config, options);
+  const jotaiStore = getDefaultStore();
+
+  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)) {
+      jotaiStore.sub(atom, () => {});
+    }
+
+    // Now wait for all loading atoms to become false
+    return new Promise((resolve, reject) => {
+      const loadingAtoms = Object.values(store.loadingAtoms);
+      const stillLoading = () => loadingAtoms.some((atom) => jotaiStore.get(atom));
+
+      if (!stillLoading()) {
+        resolve();
+        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);
+    });
+  }
+
+  return {
+    atoms: store.atoms,
+    loadingAtoms: store.loadingAtoms,
+    waitForLoad,
+  };
+}