bff-store 0.1.0 → 0.1.2

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');

package/tsconfig.json

@@ -3,6 +3,7 @@
     "target": "ES2020",
     "module": "ESNext",
     "lib": ["ES2020", "DOM"],
+    "types": ["node"],
     "moduleResolution": "bundler",
     "strict": true,
     "esModuleInterop": true,

package/docs/BUG_DIAGNOSIS_REMOTE_STORAGE_OPTIONS.md

@@ -1,104 +0,0 @@
-# Bug 诊断：`'backend' does not exist in type 'RemoteStorageOptions'`
-
-## 现象
-
-在 `tests/next_test` 中使用 `bff-store`（通过 `"file:../../dist"` 安装）时，TypeScript 报错：
-
-```
-Object literal may only specify known properties, and 'backend' does not exist in type 'RemoteStorageOptions'.ts(2353)
-```
-
-触发代码：
-
-```typescript
-import { remoteStorage } from 'bff-store';
-
-const adapter = remoteStorage({
-  backend: 'jsonl',
-  jsonlDir: '/tmp/test',
-});
-```
-
-## 根因分析
-
-问题由**两个因素叠加**导致：
-
-### 因素一（主因）：`dist/package.json` 路径错误
-
-构建脚本 `npm run build` 直接将项目根目录的 `package.json` 复制到 `dist/`。根目录的 `package.json` 中，`exports`、`main`、`module`、`types` 字段的路径都带有 `./dist/` 前缀：
-
-```json
-{
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
-    }
-  }
-}
-```
-
-这些路径在 npm 发布时是正确的（因为 `dist/` 是项目根目录的子目录）。但当通过 `"file:../../dist"` 本地安装时，**包根目录就是 `dist/` 本身**，`./dist/index.d.ts` 就会解析为 `dist/dist/index.d.ts` —— 该文件不存在。
-
-| 场景 | 包根目录 | `./dist/index.d.ts` 解析结果 | 存在? |
-|------|----------|---------------------------|------|
-| npm 发布 | 项目根目录 | `项目根/dist/index.d.ts` | 是 |
-| `file:../../dist` | `dist/` | `dist/dist/index.d.ts` | **否** |
-
-因此 TypeScript 无法通过本地 symlink 解析到正确的类型声明文件。
-
-### 因素二（助推）：全局安装了旧版本
-
-由于本地 symlink 解析失败，TypeScript 沿目录树向上查找，最终在 `/Users/Admin/node_modules/bff-store/` 找到了全局安装的 **v0.1.1**（当前项目版本为 v0.1.3）。
-
-该旧版本的 `RemoteStorageOptions` 接口**没有** `backend` 等新增字段：
-
-- v0.1.1（旧）:
-  ```typescript
-  interface RemoteStorageOptions {
-      baseUrl?: string;
-      entityId?: string;
-      transport?: TransportAdapter;
-      protocol?: StorageHttpProtocol;
-  }
-  ```
-
-- v0.1.3（当前源码/dist）:
-  ```typescript
-  interface RemoteStorageOptions {
-      baseUrl?: string;
-      entityId?: string;
-      transport?: TransportAdapter;
-      protocol?: StorageHttpProtocol;
-      backend?: 'mongodb' | 'jsonl';   // 新增
-      mongoUrl?: string;                // 新增
-      mongoDb?: string;                 // 新增
-      jsonlDir?: string;                // 新增
-  }
-  ```
-
-## 修复方案
-
-新增 `scripts/adapt-dist-package.js`，在构建时将 `dist/package.json` 中的路径从"相对于项目根目录"改写为"相对于 dist/"：
-
-- `./dist/index.d.ts` → `./index.d.ts`
-- `./dist/index.mjs` → `./index.mjs`
-- `./dist/index.js` → `./index.js`
-- `./dist/storage/...` → `./storage/...`
-- `./dist/server/...` → `./server/...`
-
-同时更新 `package.json` 的 `build` 脚本，在 `tsup` 和 `cp` 之间插入该脚本。
-
-## 修复文件
-
-- **新增**: `scripts/adapt-dist-package.js` — 路径改写脚本
-- **修改**: `package.json` — build 脚本中调用 `node scripts/adapt-dist-package.js`
-
-## 验证
-
-- `npx tsc --noEmit` in `tests/next_test`：**0 errors**（修复前 4 errors）
-- `npx vitest run`：68/69 通过（1 个 pre-existing failure，与本 bug 无关）

package/docs/BUG_FIX_REMOTE_STORAGE_OPTIONS.md

@@ -1,63 +0,0 @@
-# Bug Fix: `'backend' does not exist in type 'RemoteStorageOptions'`
-
-## 现象
-
-`tests/next_test` 中使用 `"bff-store": "file:../../dist"` 时，TypeScript 报错：
-
-```
-Object literal may only specify known properties, and 'backend' does not exist in type 'RemoteStorageOptions'.ts(2353)
-```
-
-## 根因
-
-### 因素一（主因）：dist/package.json 路径错误
-
-根目录 `package.json` 的 `main`/`module`/`types`/`exports` 字段路径都带有 `./dist/` 前缀：
-
-```json
-"main": "dist/index.js",
-"exports": { ".": { "types": "./dist/index.d.ts", ... } }
-```
-
-当通过 `"file:../../dist"` 本地安装时，包根目录就是 `dist/` 本身，`./dist/index.d.ts` 解析为 `dist/dist/index.d.ts` —— 该文件不存在。
-
-| 场景 | 包根目录 | `./dist/index.d.ts` 解析结果 | 存在? |
-|------|----------|---------------------------|------|
-| npm 发布 | 项目根 | `项目根/dist/index.d.ts` | 是 |
-| `file:../../dist` | `dist/` | `dist/dist/index.d.ts` | 否 |
-
-### 因素二（助推）：全局安装了旧版本
-
-本地 symlink 解析失败后，TypeScript 沿目录树向上查找，在 `/Users/Admin/node_modules/bff-store/` 找到全局安装的旧版本（v0.1.1），该版本 `RemoteStorageOptions` 没有 `backend` 等新字段。
-
-## 修复方案
-
-1. **新增** `scripts/adapt-dist-package.js` — 构建后将 `dist/package.json` 中的路径从"相对于项目根"改写为"相对于 dist/"：
-   - `dist/index.js` → `index.js`
-   - `./dist/index.d.ts` → `./index.d.ts`
-   - `./dist/storage/...` → `./storage/...`
-   - `./dist/server/...` → `./server/...`
-
-2. **修改** `package.json` 的 `build` 脚本：
-   ```
-   "build": "tsup && cp package.json dist/package.json && node scripts/adapt-dist-package.js && for f in dist/*.d.mts; do cp \"$f\" \"${f%.d.mts}.d.ts\"; done"
-   ```
-   完整流程：
-   - `tsup` — 构建到 dist/
-   - `cp package.json dist/package.json` — 复制配置到 dist
-   - `node scripts/adapt-dist-package.js` — 改写路径
-   - shell 循环 — 复制 `.d.mts` → `.d.ts`（主入口 tsup 只生成 `.d.mts`）
-
-## 修复文件
-
-| 文件 | 操作 |
-|------|------|
-| `scripts/adapt-dist-package.js` | 新增 — 路径改写脚本 |
-| `package.json` | 修改 — build 脚本 |
-| `tests/next_test/test-regression-remote-storage.ts` | 新增 — jsonl/mongodb/默认三种场景类型回归测试 |
-| `tests/next_test/src/app/test-regression-store.tsx` | 新增 — createStore + storage 的 .tsx 回归测试 |
-
-## 验证
-
-- `npm run build`：构建成功，dist/package.json 路径正确
-- `npx tsc --noEmit` in `tests/next_test`：0 errors

package/docs/BUG_FIX_SESSION_2026-06-03.md

@@ -1,171 +0,0 @@
-# Bug Fix Session — 2026-06-03
-
-本次会话诊断并修复了 4 个 bug，覆盖类型解析、协议层、存储适配器三个层面。
-
----
-
-## Bug 1 (P0): `'backend' does not exist in type 'RemoteStorageOptions'`
-
-### 现象
-
-`tests/next_test` 中 `"bff-store": "file:../../dist"` 安装时，TypeScript 报错：
-
-```
-Object literal may only specify known properties, and 'backend' does not exist in type 'RemoteStorageOptions'.ts(2353)
-```
-
-### 根因
-
-**因素一（主因）：dist/package.json 路径错误。** 根目录 `package.json` 的路径字段带有 `./dist/` 前缀：
-
-```json
-"main": "dist/index.js",
-"exports": { ".": { "types": "./dist/index.d.ts", ... } }
-```
-
-当通过 `"file:../../dist"` 本地安装时，包根目录就是 `dist/` 本身，`./dist/index.d.ts` 解析为 `dist/dist/index.d.ts` —— 文件不存在。
-
-| 场景 | 包根目录 | `./dist/index.d.ts` 解析 | 存在? |
-|------|----------|-------------------------|------|
-| npm 发布 | 项目根 | `项目根/dist/index.d.ts` | 是 |
-| `file:../../dist` | `dist/` | `dist/dist/index.d.ts` | 否 |
-
-**因素二（助推）：全局安装了旧版本。** 本地 symlink 解析失败后，TypeScript 沿目录树向上查找，在 `/Users/Admin/node_modules/bff-store/` 找到旧版 v0.1.1，该版本 `RemoteStorageOptions` 无 `backend` 字段。
-
-### 修复
-
-1. **新增** `scripts/adapt-dist-package.js` — 构建后将 `dist/package.json` 路径改写为相对 dist/：
-   - `dist/index.js` → `index.js`
-   - `./dist/index.d.ts` → `./index.d.ts`
-   - `./dist/storage/...` → `./storage/...`
-
-2. **修改** `package.json` build 脚本：
-   ```
-   "build": "tsup && cp package.json dist/package.json && node scripts/adapt-dist-package.js && for f in dist/*.d.mts; do cp \"$f\" \"${f%.d.mts}.d.ts\"; done"
-   ```
-
-### 涉及文件
-
-| 文件 | 操作 |
-|------|------|
-| `scripts/adapt-dist-package.js` | 新增 |
-| `package.json` | 修改 build 脚本 |
-
----
-
-## Bug 2 (P0): GET/DELETE 请求拿不到 `mongoUrl`
-
-### 现象
-
-BFF 模式下，POST (`/storage/set`) 正常，但 GET (`/storage/get`) 返回：
-
-```
-{"error":"Error: mongoUrl is required for mongodb backend"}
-```
-
-### 根因
-
-`src/storage/protocol.ts` 的 `buildUrl` / `buildBatchGetUrl` / `buildBatchSetUrl` 方法只将 `backend` 和 `entityId` 拼入 URL query params，`mongoUrl`、`mongoDb`、`jsonlDir` 仅通过 POST body 传递（`createStorageWithProtocol` 中将 `backendConfig` spread 到 body）。
-
-GET/DELETE 无 body → server 端 `resolveStorage` 从 URL query params 解析不到 `mongoUrl` → 尝试 `mongodbStorage({ url: undefined })` → 抛错。
-
-### 修复
-
-抽取 `appendBackendParams()` 方法，将全部 backend 参数拼入 URL query params：
-
-```typescript
-private appendBackendParams(params: URLSearchParams): void {
-  if (this.backendConfig.backend)   params.set('backend', this.backendConfig.backend);
-  if (this.backendConfig.mongoUrl)  params.set('mongoUrl', this.backendConfig.mongoUrl);
-  if (this.backendConfig.mongoDb)   params.set('mongoDb', this.backendConfig.mongoDb);
-  if (this.backendConfig.jsonlDir)  params.set('jsonlDir', this.backendConfig.jsonlDir);
-}
-```
-
-### 涉及文件
-
-| 文件 | 操作 |
-|------|------|
-| `src/storage/protocol.ts` | 新增 `appendBackendParams()`，`buildUrl` / `buildBatchGetUrl` / `buildBatchSetUrl` 调用之 |
-
----
-
-## Bug 3 (P2): JSONL adapter 静默失败（entityId 默认 null）
-
-### 现象
-
-BFF server 使用 JSONL backend 时，SET 返回 `{"success":true}` 但数据未写入磁盘，GET 返回 `{"value":null}`。
-
-### 根因
-
-`src/storage/jsonl.ts` 中 `entityId` 初始值为 `null`，GET 和 SET 操作均有 `if (!entityId) return` 守卫，导致静默跳过。对比 MongoDB adapter 默认 `currentEntityId = 'default'`，行为不一致。
-
-### 修复
-
-```typescript
-// Before
-let entityId: string | null = null;
-
-// After
-let entityId: string = 'default';
-```
-
-### 涉及文件
-
-| 文件 | 操作 |
-|------|------|
-| `src/storage/jsonl.ts` | `entityId` 默认值 `null` → `'default'` |
-
----
-
-## Bug 4 (P2): MongoDB 副本集连接失败
-
-### 现象
-
-BFF server 连接 MongoDB 时报：
-
-```
-MongoServerSelectionError: connection <monitor> to 172.16.42.101:27017 closed
-TopologyDescription { type: 'ReplicaSetNoPrimary', setName: 'rs0' }
-```
-
-### 根因
-
-`localhost:27017` 属于副本集 `rs0`，成员地址 `172.16.42.101:27017`。MongoDB driver 自动发现副本集后切换到该地址，但该地址网络不通。
-
-### 修复
-
-在 MongoDB URL 中拼接 `?directConnection=true&authSource=admin` 绕过副本集发现。
-
-```typescript
-const mongoUrl = `mongodb://${user}:${pwd}@${host}/${db}?directConnection=true&authSource=admin`;
-```
-
-### 涉及文件
-
-| 文件 | 操作 |
-|------|------|
-| `tests/next_test/src/app/page.tsx` | 添加 URL 参数 |
-
----
-
-## 测试覆盖
-
-| 文件 | 内容 |
-|------|------|
-| `tests/next_test/test-types.ts` | 原始 bug 用例 — `backend: 'jsonl'` |
-| `tests/next_test/test-similar-root.tsx` | 同上 .tsx 版本 |
-| `tests/next_test/test-regression-remote-storage.ts` | 全参数组合：jsonl / mongodb / 可选字段 / 默认构造 |
-| `tests/next_test/src/app/test-similar.tsx` | .tsx 中 remoteStorage 类型测试 |
-| `tests/next_test/src/app/test-regression-store.tsx` | createStore + remoteStorage 组合测试 |
-| `tests/next_test/src/app/test-mongodb.tsx` | MongoDB 前端组件测试 |
-| `tests/next_test/test-mongodb-direct.ts` | mongodbStorage 直接调用测试脚本 |
-| `tests/next_test/test-mongodb-remote.ts` | remoteStorage → MongoDB 路由测试脚本 |
-| `tests/next_test/src/app/page.tsx` | 浏览器端到端测试（可切换 jsonl/mongodb） |
-
-## 验证结果
-
-- `npm run build`（项目根）：构建成功
-- `npx tsc --noEmit`（tests/next_test）：0 errors
-- `curl` 测试 JSONL SET/GET/DELETE 全链路：通过
-- `curl` 测试 MongoDB SET/GET/DELETE 全链路：通过