bff-store 0.1.0

package/dist/storage/jsonl-entry.js

@@ -0,0 +1,112 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/storage/jsonl-entry.ts
+var jsonl_entry_exports = {};
+__export(jsonl_entry_exports, {
+  createJsonlStorage: () => createJsonlStorage,
+  jsonlStorage: () => jsonlStorage
+});
+module.exports = __toCommonJS(jsonl_entry_exports);
+
+// src/storage/jsonl.ts
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+function jsonlStorage(options) {
+  const baseDir = options?.dir ?? "./sessions";
+  let entityId = "default";
+  function getFilePath(eId, key) {
+    const safeKey = key.replace(/[^a-zA-Z0-9_]/g, "_");
+    return path.join(baseDir, eId, `${safeKey}.jsonl`);
+  }
+  const storage = {
+    async get(key) {
+      if (!entityId) return null;
+      const filePath = getFilePath(entityId, key);
+      if (!fs.existsSync(filePath)) {
+        return null;
+      }
+      try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        const lines = content.trim().split("\n").filter(Boolean);
+        if (lines.length === 0) return null;
+        const lastLine = lines[lines.length - 1];
+        const entry = JSON.parse(lastLine);
+        return entry.value;
+      } catch {
+        return null;
+      }
+    },
+    async set(key, value) {
+      if (!entityId) return;
+      const filePath = getFilePath(entityId, key);
+      const dir = path.dirname(filePath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+      const entry = {
+        key,
+        value,
+        timestamp: Date.now()
+      };
+      const line = JSON.stringify(entry) + "\n";
+      fs.appendFileSync(filePath, line, "utf-8");
+    },
+    async remove(key) {
+      if (!entityId) return;
+      const filePath = getFilePath(entityId, key);
+      if (fs.existsSync(filePath)) {
+        fs.unlinkSync(filePath);
+      }
+    },
+    async getMultiple(keys) {
+      const result = /* @__PURE__ */ new Map();
+      for (const key of keys) {
+        const value = await this.get(key);
+        if (value !== null) {
+          result.set(key, value);
+        }
+      }
+      return result;
+    }
+  };
+  return {
+    storage,
+    name: "jsonl",
+    setEntityId(id) {
+      entityId = id;
+    }
+  };
+}
+var createJsonlStorage = jsonlStorage;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createJsonlStorage,
+  jsonlStorage
+});

package/dist/storage/jsonl-entry.mjs

@@ -0,0 +1,74 @@
+// src/storage/jsonl.ts
+import * as fs from "fs";
+import * as path from "path";
+function jsonlStorage(options) {
+  const baseDir = options?.dir ?? "./sessions";
+  let entityId = "default";
+  function getFilePath(eId, key) {
+    const safeKey = key.replace(/[^a-zA-Z0-9_]/g, "_");
+    return path.join(baseDir, eId, `${safeKey}.jsonl`);
+  }
+  const storage = {
+    async get(key) {
+      if (!entityId) return null;
+      const filePath = getFilePath(entityId, key);
+      if (!fs.existsSync(filePath)) {
+        return null;
+      }
+      try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        const lines = content.trim().split("\n").filter(Boolean);
+        if (lines.length === 0) return null;
+        const lastLine = lines[lines.length - 1];
+        const entry = JSON.parse(lastLine);
+        return entry.value;
+      } catch {
+        return null;
+      }
+    },
+    async set(key, value) {
+      if (!entityId) return;
+      const filePath = getFilePath(entityId, key);
+      const dir = path.dirname(filePath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+      const entry = {
+        key,
+        value,
+        timestamp: Date.now()
+      };
+      const line = JSON.stringify(entry) + "\n";
+      fs.appendFileSync(filePath, line, "utf-8");
+    },
+    async remove(key) {
+      if (!entityId) return;
+      const filePath = getFilePath(entityId, key);
+      if (fs.existsSync(filePath)) {
+        fs.unlinkSync(filePath);
+      }
+    },
+    async getMultiple(keys) {
+      const result = /* @__PURE__ */ new Map();
+      for (const key of keys) {
+        const value = await this.get(key);
+        if (value !== null) {
+          result.set(key, value);
+        }
+      }
+      return result;
+    }
+  };
+  return {
+    storage,
+    name: "jsonl",
+    setEntityId(id) {
+      entityId = id;
+    }
+  };
+}
+var createJsonlStorage = jsonlStorage;
+export {
+  createJsonlStorage,
+  jsonlStorage
+};

package/dist/storage/mongodb-entry.d.mts

@@ -0,0 +1,40 @@
+import { MongoClient } from 'mongodb';
+
+interface Storage {
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T): Promise<void>;
+    remove(key: string): Promise<void>;
+    /** Optional: get multiple keys at once for batch loading */
+    getMultiple?<T>(keys: string[]): Promise<Map<string, T>>;
+    /** Optional: set multiple keys at once for batch saving */
+    setMultiple?<T>(entries: Map<string, T>): Promise<void>;
+}
+interface StorageAdapter {
+    storage: Storage;
+    name: string;
+    /** Optional: set the entityId for multi-tenant storage */
+    setEntityId?(entityId: string): void;
+}
+type AsyncStorageFactory<T = unknown> = (options: T) => Promise<StorageAdapter>;
+
+interface StorageOptions {
+    debounceMs?: number;
+}
+interface MongoStorageOptions extends StorageOptions {
+    url: string;
+    database?: string;
+}
+
+interface MongoStorageAdapter extends StorageAdapter {
+    client: MongoClient;
+    close(): Promise<void>;
+}
+/**
+ * MongoDB storage adapter
+ * Stores data in collection: {database}.state_{entityId}
+ * Each entityId gets its own collection.
+ */
+declare function mongodbStorage(options: MongoStorageOptions): Promise<MongoStorageAdapter>;
+declare const createMongoStorage: AsyncStorageFactory<MongoStorageOptions>;
+
+export { type MongoStorageOptions, createMongoStorage, mongodbStorage };

package/dist/storage/mongodb-entry.d.ts

@@ -0,0 +1,40 @@
+import { MongoClient } from 'mongodb';
+
+interface Storage {
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T): Promise<void>;
+    remove(key: string): Promise<void>;
+    /** Optional: get multiple keys at once for batch loading */
+    getMultiple?<T>(keys: string[]): Promise<Map<string, T>>;
+    /** Optional: set multiple keys at once for batch saving */
+    setMultiple?<T>(entries: Map<string, T>): Promise<void>;
+}
+interface StorageAdapter {
+    storage: Storage;
+    name: string;
+    /** Optional: set the entityId for multi-tenant storage */
+    setEntityId?(entityId: string): void;
+}
+type AsyncStorageFactory<T = unknown> = (options: T) => Promise<StorageAdapter>;
+
+interface StorageOptions {
+    debounceMs?: number;
+}
+interface MongoStorageOptions extends StorageOptions {
+    url: string;
+    database?: string;
+}
+
+interface MongoStorageAdapter extends StorageAdapter {
+    client: MongoClient;
+    close(): Promise<void>;
+}
+/**
+ * MongoDB storage adapter
+ * Stores data in collection: {database}.state_{entityId}
+ * Each entityId gets its own collection.
+ */
+declare function mongodbStorage(options: MongoStorageOptions): Promise<MongoStorageAdapter>;
+declare const createMongoStorage: AsyncStorageFactory<MongoStorageOptions>;
+
+export { type MongoStorageOptions, createMongoStorage, mongodbStorage };

package/dist/storage/mongodb-entry.js

@@ -0,0 +1,114 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/storage/mongodb-entry.ts
+var mongodb_entry_exports = {};
+__export(mongodb_entry_exports, {
+  createMongoStorage: () => createMongoStorage,
+  mongodbStorage: () => mongodbStorage
+});
+module.exports = __toCommonJS(mongodb_entry_exports);
+
+// src/storage/mongodb.ts
+var import_mongodb = require("mongodb");
+async function mongodbStorage(options) {
+  const {
+    url,
+    database = "jotai_state_store"
+  } = options;
+  const client = new import_mongodb.MongoClient(url);
+  await client.connect();
+  const db = client.db(database);
+  let currentEntityId = "default";
+  function getCollectionName(eId) {
+    return `state_${eId}`;
+  }
+  function getCollection(eId) {
+    return db.collection(getCollectionName(eId));
+  }
+  const storage = {
+    async get(key) {
+      const collection = getCollection(currentEntityId);
+      const entry = await collection.findOne(
+        { key },
+        { sort: { timestamp: -1 } }
+      );
+      return entry ? entry.value : null;
+    },
+    async set(key, value) {
+      const collection = getCollection(currentEntityId);
+      await collection.insertOne({
+        key,
+        value,
+        timestamp: Date.now(),
+        entityId: currentEntityId
+      });
+    },
+    async remove(key) {
+      const collection = getCollection(currentEntityId);
+      await collection.deleteMany({ key });
+    },
+    async getMultiple(keys) {
+      const collection = getCollection(currentEntityId);
+      const entries = await collection.find({ key: { $in: keys } }).sort({ timestamp: -1 }).toArray();
+      const result = /* @__PURE__ */ new Map();
+      const seen = /* @__PURE__ */ new Set();
+      for (const entry of entries) {
+        if (!seen.has(entry.key)) {
+          result.set(entry.key, entry.value);
+          seen.add(entry.key);
+        }
+      }
+      return result;
+    },
+    async setMultiple(entries) {
+      const collection = getCollection(currentEntityId);
+      const docs = [];
+      entries.forEach((value, key) => {
+        docs.push({
+          key,
+          value,
+          timestamp: Date.now(),
+          entityId: currentEntityId
+        });
+      });
+      if (docs.length > 0) {
+        await collection.insertMany(docs);
+      }
+    }
+  };
+  const adapter = {
+    storage,
+    name: "mongodb",
+    client,
+    setEntityId(id) {
+      currentEntityId = id;
+    },
+    async close() {
+      await client.close();
+    }
+  };
+  return adapter;
+}
+var createMongoStorage = mongodbStorage;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createMongoStorage,
+  mongodbStorage
+});

package/dist/storage/mongodb-entry.mjs

@@ -0,0 +1,86 @@
+// src/storage/mongodb.ts
+import { MongoClient } from "mongodb";
+async function mongodbStorage(options) {
+  const {
+    url,
+    database = "jotai_state_store"
+  } = options;
+  const client = new MongoClient(url);
+  await client.connect();
+  const db = client.db(database);
+  let currentEntityId = "default";
+  function getCollectionName(eId) {
+    return `state_${eId}`;
+  }
+  function getCollection(eId) {
+    return db.collection(getCollectionName(eId));
+  }
+  const storage = {
+    async get(key) {
+      const collection = getCollection(currentEntityId);
+      const entry = await collection.findOne(
+        { key },
+        { sort: { timestamp: -1 } }
+      );
+      return entry ? entry.value : null;
+    },
+    async set(key, value) {
+      const collection = getCollection(currentEntityId);
+      await collection.insertOne({
+        key,
+        value,
+        timestamp: Date.now(),
+        entityId: currentEntityId
+      });
+    },
+    async remove(key) {
+      const collection = getCollection(currentEntityId);
+      await collection.deleteMany({ key });
+    },
+    async getMultiple(keys) {
+      const collection = getCollection(currentEntityId);
+      const entries = await collection.find({ key: { $in: keys } }).sort({ timestamp: -1 }).toArray();
+      const result = /* @__PURE__ */ new Map();
+      const seen = /* @__PURE__ */ new Set();
+      for (const entry of entries) {
+        if (!seen.has(entry.key)) {
+          result.set(entry.key, entry.value);
+          seen.add(entry.key);
+        }
+      }
+      return result;
+    },
+    async setMultiple(entries) {
+      const collection = getCollection(currentEntityId);
+      const docs = [];
+      entries.forEach((value, key) => {
+        docs.push({
+          key,
+          value,
+          timestamp: Date.now(),
+          entityId: currentEntityId
+        });
+      });
+      if (docs.length > 0) {
+        await collection.insertMany(docs);
+      }
+    }
+  };
+  const adapter = {
+    storage,
+    name: "mongodb",
+    client,
+    setEntityId(id) {
+      currentEntityId = id;
+    },
+    async close() {
+      await client.close();
+    }
+  };
+  return adapter;
+}
+var createMongoStorage = mongodbStorage;
+export {
+  createMongoStorage,
+  mongodbStorage
+};

package/docs/BUG_DIAGNOSIS_REMOTE_STORAGE_OPTIONS.md

@@ -0,0 +1,104 @@
+# 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

@@ -0,0 +1,63 @@
+# 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