bff-store 0.1.0 → 0.1.1

package/docs/BUG_FIX_MONGODB_CHILD_PROCESS.md

@@ -0,0 +1,129 @@
+# BUG: child_process / mongodb 错误
+
+**日期**: 2026-06-03
+
+## 问题现象
+
+Next.js 构建时报错：
+```
+Module not found: Can't resolve 'child_process'
+./tests/next_test/node_modules/mongodb/lib/client-side-encryption/mongocryptd_manager.js:38
+const { spawn } = require('child_process');
+```
+
+## 根因分析
+
+**不是本次改动引起的，是之前就存在的依赖架构问题。**
+
+### 1. bff-store 的 `package.json` 把 mongodb 放在 `dependencies`
+
+```json
+// bff-store/package.json
+{
+  "dependencies": {
+    "mongodb": "^6.21.0"
+  }
+}
+```
+
+### 2. next_test 通过 `file:` 路径安装 bff-store
+
+```json
+// next_test/package.json
+{
+  "bff-store": "file:../../dist"
+}
+```
+
+### 3. npm install 时把 mongodb 也装进了 next_test/node_modules
+
+```
+next_test/node_modules/mongodb/   ← 被安装了
+```
+
+### 4. Next.js/Webpack 在静态分析时解析到了 mongodb
+
+即使 `dist/index.mjs` 实际不引用 mongodb（`tsup external: ['mongodb']`），但 Next.js 的 bundler 在分析依赖时看到了 `node_modules/mongodb`，尝试解析它，然后触发了 `child_process` 的引用。
+
+## 验证
+
+- `dist/index.mjs` 实际 bundle：干净（0 个 mongodb 引用）
+- tsup 的 external 配置：正确（mongodb 被 external）
+- 清理 next_test 的 `node_modules` 和 `package-lock.json` 后重装，mongodb 没再被安装，构建成功
+
+## 结论
+
+| 环节 | 状态 |
+|------|------|
+| 本次新增代码（environment.ts、nodeStore.ts）| 无问题 |
+| `dist/index.mjs` 实际 bundle | 干净（0 个 mongodb 引用）|
+| tsup 的 external 配置 | 正确（mongodb 被 external）|
+| **根本原因** | `package.json` 的 `dependencies` 里有 mongodb |
+
+这是之前就存在的问题，只是以前 next_test 可能没走到触发这个解析的代码路径。
+
+## 修复（2026-06-03）
+
+已将 `mongodb` 从 `package.json` 的 `dependencies` 移到 `devDependencies`。
+
+**原因**：
+- `tsup` 构建 `mongodb-entry.ts` 时会将 mongodb 打包进 `dist/storage/mongodb-entry.js`
+- 根 `package.json` 的 `dependencies` 不需要 mongodb
+- npm install 时不会为消费者安装 devDependencies，所以 next_test 不再被强制安装 mongodb
+
+**修复后验证**：
+- next_test 重新 `npm install` 后，`node_modules/mongodb` 不存在
+- Next.js 构建成功，无 `child_process` 错误
+
+---
+
+## 问题二：Can't resolve 'bff-store'
+
+**日期**: 2026-06-03
+
+### 问题现象
+
+Next.js dev 时报错：
+```
+Module not found: Can't resolve 'bff-store'
+import { createStore, useStore, remoteStorage } from 'bff-store';
+```
+
+### 根因分析
+
+`package.json` exports 的 `require` 字段指向不存在的文件：
+
+```json
+"exports": {
+  ".": {
+    "types": "./dist/index.d.ts",
+    "import": "./dist/index.mjs",
+    "require": "./dist/index.js"  // ← 这个文件不存在！
+  }
+}
+```
+
+tsup 只生成 ESM（`.mjs`），没有生成 CJS（`.js`）。但 exports 里写了 `require` 字段指向 `index.js`，Node.js CJS resolver 尝试解析时找不到文件就报错了。
+
+### 修复
+
+移除 exports 中的 `require` 字段（ESM-only 库）：
+
+```json
+"exports": {
+  ".": {
+    "types": "./dist/index.d.ts",
+    "import": "./dist/index.mjs"
+  }
+}
+```
+
+### ESM-only 的影响
+
+| 方式 | 支持 |
+|------|------|
+| `import from 'bff-store'` | ✅ 正常 |
+| `node --input-type=module` + import | ✅ 正常 |
+| `const x = require('bff-store')` | ❌ 报错 |
+
+bff-store 主打 React + 新项目，用 ESM 语法不受影响。老项目用 `require` 的场景暂不支持。

package/docs/FRONTEND_BACKEND_ISOLATION.md

@@ -0,0 +1,150 @@
+# 前端/后端隔离机制
+
+## 概述
+
+bff-store 通过构建配置和 package.json exports 条件导出实现前端/后端隔离，确保 Node.js 特有模块（fs、mongodb）不会进入前端 bundle。
+
+---
+
+## 1. 构建层面隔离（tsup）
+
+tsup.config.ts 定义了 5 个独立的构建入口：
+
+| 入口 | 输出 | external |
+|------|------|----------|
+| `src/index.ts` | `dist/index.mjs` | `react, jotai, mongodb` |
+| `src/storage/jsonl-entry.ts` | `dist/storage/jsonl-entry.mjs` | `react, jotai` |
+| `src/storage/mongodb-entry.ts` | `dist/storage/mongodb-entry.mjs` | `react, jotai` |
+| `src/server/entry.ts` | `dist/server/entry.mjs` | `react, jotai` |
+| `src/server/cli.ts` | `dist/cli.js` | `react, jotai` + noExternal: mongodb |
+
+**关键**：主入口的 tsup external 里标了 `mongodb`，所以 `dist/index.mjs` 不会打包 mongodb。fs 同理。
+
+---
+
+## 2. package.json 条件导出
+
+```json
+"exports": {
+  ".": {
+    "types": "./dist/index.d.ts",
+    "import": "./dist/index.mjs",
+    "require": "./dist/index.js"
+  },
+  "./jsonl": {
+    "types": "./dist/storage/jsonl-entry.d.ts",
+    "import": "./dist/storage/jsonl-entry.mjs",
+    "require": "./dist/storage/jsonl-entry.js"
+  },
+  "./mongodb": {
+    "types": "./dist/storage/mongodb-entry.d.ts",
+    "import": "./dist/storage/mongodb-entry.mjs",
+    "require": "./dist/storage/mongodb-entry.js"
+  },
+  "./server": {
+    "types": "./dist/server/entry.d.ts",
+    "import": "./dist/server/entry.mjs",
+    "require": "./dist/server/entry.js"
+  }
+}
+```
+
+用户不主动 `import from 'bff-store/jsonl'` 或 `bff-store/mongodb'`，就拿不到包含 fs/mongodb 的模块。
+
+---
+
+## 3. 主入口 index.ts 干净
+
+`src/index.ts` 只导出前端安全的模块：
+
+- `createStore`, `useStore`, `createPersistedAtom`
+- `memoryStorage`, `remoteStorage`
+- `isNode`, `isBrowser`, `createNodeStore`
+
+**没有**引用 `jsonl.ts` 或 `mongodb.ts`。
+
+---
+
+## 4. 引用 fs/mongodb 的文件
+
+| 文件 | 引用 |
+|------|------|
+| `src/storage/jsonl.ts` | `import * as fs from 'fs'` |
+| `src/storage/mongodb.ts` | `import { MongoClient } from 'mongodb'` |
+| `src/server/index.ts` | `import { mongodbStorage } from '../storage/mongodb'` |
+
+这些文件**只会被** `jsonl-entry.ts`、`mongodb-entry.ts`、`server/entry.ts` 引用，不会被主入口 `index.ts` 引用。
+
+### 为什么 index.ts 不引用 fs/mongodb 很重要？
+
+**不是"空间换时间"，是避免运行时错误。**
+
+tsup 的 `external` 配置是保险，但 `import` 语句本身就会触发模块解析：
+
+```typescript
+// index.ts 如果这样写
+import * as fs from 'fs';  // ← 加了这行
+export { createStore } from './createStore';
+```
+
+1. tsup external 会让 fs 代码不打包进 bundle
+2. 但 bundler（webpack/rollup）看到 `import` 语句仍会尝试解析
+3. Next.js 环境有 node_modules/fs → 解析成功，但运行时会出问题
+4. 纯浏览器环境没有 fs → 运行时直接报错
+
+**不让源头存在，比靠 external 兜底更安全。**
+
+---
+
+## 5. createNodeStore 的安全性
+
+`createNodeStore` 在 `src/nodeStore.ts` 中实现，它的 import：
+
+```typescript
+import { getDefaultStore } from 'jotai';
+import { createStore } from './createStore';
+import type { AtomConfigs, StoreAtoms, StoreLoadingAtoms } from './types';
+import type { StorageAdapter } from './storage/base';
+```
+
+**没有**引用 fs 或 mongodb，所以即使在 index.ts 中导出，前端也不会被打包进去。
+
+---
+
+## 6. 之前 mongodb 进 next_test 的原因
+
+不是代码问题，是 **package.json dependencies** 的问题。
+
+```json
+// 原先的 package.json
+{
+  "dependencies": {
+    "mongodb": "^6.21.0"  // ← 问题在这里
+  }
+}
+```
+
+next_test 通过 `file:../../dist` 安装 bff-store 时，npm install 会安装 `dependencies` 中的包，导致 mongodb 被装进 next_test/node_modules，即使用不到也会被 Next.js bundler 解析到。
+
+**修复**：将 mongodb 移到 `devDependencies`，因为 tsup 构建时会把它打包进 `dist/storage/mongodb-entry.js`，不需要作为独立依赖安装。
+
+---
+
+## 验证方法
+
+### 检查主入口是否干净
+```bash
+grep -c "mongodb" dist/index.mjs  # 应为 0
+grep -c "fs" dist/index.mjs        # 应为 0
+```
+
+### 检查子入口是否包含目标模块
+```bash
+grep -c "mongodb" dist/storage/mongodb-entry.mjs  # 应 > 0
+grep -c "fs" dist/storage/jsonl-entry.mjs          # 应 > 0
+```
+
+### 检查 next_test 是否被安装 mongodb
+```bash
+ls node_modules/mongodb  # 应不存在
+```

package/docs/LOCAL_LINK_STRATEGIES.md

@@ -0,0 +1,117 @@
+# 本地包链接策略
+
+## 背景
+
+开发 bff-store 时，需要在项目中测试自己的包。常见的链接方式有三种。
+
+---
+
+## 方式一：`file:` 路径（当前使用）
+
+### 配置
+
+```json
+// tests/next_test/package.json
+{
+  "dependencies": {
+    "bff-store": "file:../../dist"
+  }
+}
+```
+
+npm install 后会创建 symlink：
+
+```
+tests/next_test/node_modules/bff-store -> bff-store/dist
+```
+
+### 优点
+- 简单直接，改完 `npm run build` 就生效
+- 无需额外命令
+
+### 缺点
+- 不是真实 npm 安装行为，可能有边界情况
+- 路径固定，不够灵活
+
+---
+
+## 方式二：`npm link`（推荐本地开发）
+
+### 配置
+
+```bash
+# 1. 在 bff-store 目录注册全局链接
+cd bff-store
+npm link
+
+# 2. 在目标项目链接全局包
+cd tests/next_test
+npm link bff-store
+```
+
+### 原理
+
+```
+bff-store/ (全局注册的包)
+    ↓
+tests/next_test/node_modules/bff-store -> 全局包的 symlink
+```
+
+### 优点
+- 更接近真实 npm 安装行为
+- 全局一份，多个项目共用
+- 可同时开发多个相互依赖的包
+
+### 缺点
+- 需要两条命令
+- 全局状态管理可能混乱
+
+### 清理
+
+```bash
+cd tests/next_test
+npm unlink bff-store
+
+cd bff-store
+npm link remove bff-store
+```
+
+---
+
+## 方式三：发布到 npm（正式发布）
+
+### 配置
+
+```bash
+# 1. 登录 npm
+npm login
+
+# 2. 发布（需要 package.json 的 name 是唯一的）
+npm publish
+
+# 3. 在项目中使用
+npm install bff-store
+```
+
+### 优点
+- 真实用户安装方式
+- 版本管理规范
+
+### 缺点
+- 需要 npm 账号
+- 版本管理，每次改动都要发版
+- 发布后不能即时生效
+
+---
+
+## 总结
+
+| 方式 | 即时生效 | 配置复杂度 | 接近真实安装 |
+|------|---------|-----------|------------|
+| `file:` | ✅ | 简单 | 一般 |
+| `npm link` | ✅ | 中等 | ✅ |
+| `npm publish` | ❌ | 需要版本管理 | ✅ |
+
+**本地开发推荐**：`npm link` 或保持 `file:`
+
+**正式发布**：用 `npm publish`

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "bff-store",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",
   "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 +52,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/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

@@ -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,79 @@
+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(): 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) => {
+      const loadingAtoms = Object.values(store.loadingAtoms);
+      const stillLoading = () => loadingAtoms.some((atom) => jotaiStore.get(atom));
+
+      if (!stillLoading()) {
+        resolve();
+        return;
+      }
+
+      // Poll until all are loaded
+      const interval = setInterval(() => {
+        if (!stillLoading()) {
+          clearInterval(interval);
+          resolve();
+        }
+      }, 10);
+    });
+  }
+
+  return {
+    atoms: store.atoms,
+    loadingAtoms: store.loadingAtoms,
+    waitForLoad,
+  };
+}

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 无关）