bff-store 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,45 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm install:*)",
+      "Bash(npm run:*)",
+      "Bash(ls -la *.config.* vitest.config.*)",
+      "Bash(npm test:*)",
+      "Bash(ls -la vitest.config.*)",
+      "Bash(node -e ':*)",
+      "Bash(awk NR>=54 && NR<=95:*)",
+      "Bash(awk NR>=84 && NR<=131:*)",
+      "Bash(awk NR>=1 && NR<=35:*)",
+      "Bash(awk NR>=94 && NR<=120:*)",
+      "Bash(awk NR>=19 && NR<=65:*)",
+      "Bash(grep -l \"handlers\" /Users/Admin/Desktop/jotai-state-store/tests/*.ts)",
+      "Bash(xargs ls:*)",
+      "Bash(grep:*)",
+      "Bash(node:*)",
+      "Bash(npx vitest:*)",
+      "Bash(npx create-next-app@latest . --typescript --eslint --no-tailwind --app --src-dir --no-import-alias --use-npm)",
+      "Bash(npm link:*)",
+      "Bash(curl -s http://localhost:3847/health)",
+      "Bash(curl:*)",
+      "Read(//private/tmp/jotai-state-store-data/**)",
+      "Bash(cat /tmp/jotai-state-store-data/test-app/*.jsonl)",
+      "Bash(npx tsc:*)",
+      "Bash(ls /Users/Admin/Desktop/jotai-state-store/dist/*.d.ts)",
+      "Bash(npx tsup:*)",
+      "Bash(find /Users/Admin/Desktop/jotai-state-store/tests/next_test/node_modules -name \"package.json\" -path \"*/jotai-state-store/*\" -exec cat {} \\\\;)",
+      "Bash(find:*)",
+      "Bash(ls /Users/Admin/Desktop/jotai-state-store/dist/*.ts)",
+      "Read(//Users/Admin/node_modules/jotai-state-store/dist/**)",
+      "Bash(ls:*)",
+      "Bash(kill 89616)",
+      "Bash(python3 -c 'import urllib.parse; print\\(urllib.parse.quote\\(\"mongodb://admin:715705%40Qc123@localhost:27017/jotai_test?directConnection=true&authSource=admin\"\\)\\)')",
+      "Bash(python3 -c 'import urllib.parse.quote\\(\"mongodb://admin:715705%40Qc123@localhost:27017/jotai_test?directConnection=true&authSource=admin\"\\)\\)')",
+      "Read(//tmp/**)",
+      "Bash(kill 68874)",
+      "Bash(npm publish:*)",
+      "Bash(rg -rn \"jotai-state-store\" --type-list)",
+      "Bash(rg -rn \"jotai-state-store\" .)",
+      "Bash(xargs sed:*)"
+    ]
+  }
+}

package/CONTEXT.md

@@ -0,0 +1,53 @@
+# Domain Context
+
+## Core Concepts
+
+### Store (协调者)
+The central coordinator that manages multiple persisted atoms. Created via `createStore()`, it holds:
+- `entityId` - the unique identifier for this store instance
+- `config` - the atom configuration array
+- `atoms` - map of key → WritableAtom
+- `loadingAtoms` - map of key → loading state atom
+
+### Atom Config (原子配置)
+Configuration for a single persisted state field:
+- `key` - unique identifier within the store
+- `defaultValue` - initial value before loading from storage
+- `type` - optional type hint ('string' | 'number' | 'boolean' | 'array' | 'object')
+- `immediate` - if true, save immediately without debouncing
+
+### Storage Adapter (存储适配器)
+The seam between the store and the underlying persistence layer. Implements the `Storage` interface and provides:
+- `storage` - the Storage implementation
+- `name` - identifier for the adapter type
+- Optional lifecycle methods: `setEntityId()`, `close()`
+
+### Storage (存储接口)
+The minimal interface for persistence:
+- `get<T>(key)` - load value by key
+- `set<T>(key, value)` - save value
+- `remove(key)` - delete value
+- Optional: `getMultiple()`, `setMultiple()` for batch operations
+
+### Debouncer (防抖器)
+Manages delayed execution of save operations. Prevents excessive writes by:
+- Buffering rapid changes
+- Saving after a quiet period (default 800ms)
+- Supporting immediate mode for critical data
+
+## Relationships
+
+```
+Store (coordinates)
+  ├── config: AtomConfig[]
+  ├── atoms: Map<key, WritableAtom>
+  └── storage: StorageAdapter (seam to persistence)
+      └── storage: Storage (data interface)
+```
+
+## Setter Naming Convention
+
+For an atom config with key `theme`:
+- Value access: `store.atoms.theme.get()`
+- Setter name: `setTheme` (derived via capitalize)
+- Via hook: `{ theme, setTheme } = useStore(store)`

package/README.md

@@ -0,0 +1,223 @@
+# bff-store
+
+A jotai-based state management library with pluggable storage adapters and built-in BFF (Backend for Frontend) for browser/Next.js environments.
+
+## Features
+
+- **Configuration-driven**: Define multiple states via array configuration
+- **Pluggable storage**: Use memory, JSONL files, MongoDB, or remote server
+- **Auto-generated hooks**: React hooks auto-generated from config
+- **Loading states**: Built-in loading state tracking
+- **Debounced saves**: Automatic debouncing for non-critical data
+- **Built-in BFF**: Embedded sidecar API server for browser/Next.js environments
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Your Application                       │
+│                   (Next.js/Browser)                      │
+│                                                          │
+│  useStore() ──► remoteStorage ──► localhost:3847        │
+│                         │                                │
+│                         ▼                                │
+│              ┌─────────────────────┐                     │
+│              │   BFF (Sidecar)     │                     │
+│              │  bff-store │                     │
+│              │                     │                     │
+│              │  /storage/get/:key  │                     │
+│              │  /storage/set/:key  │                     │
+│              │  /storage/delete   │                     │
+│              └──────────┬──────────┘                     │
+│                         │                                │
+│                         ▼                                │
+│              ┌─────────────────────┐                     │
+│              │   JSONL / MongoDB   │                     │
+│              └─────────────────────┘                     │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Installation
+
+```bash
+npm install bff-store
+# or
+pnpm add bff-store
+```
+
+## Client Usage (Browser / Next.js)
+
+BFF Server 会自动启动，客户端只需使用 `remoteStorage()` 并指定存储后端：
+
+```typescript
+import { createStore, useStore, remoteStorage } from 'bff-store';
+
+const config = [
+  { key: 'theme', defaultValue: 'dark' },
+  { key: 'characters', defaultValue: [] },
+] as const;
+
+// 使用 MongoDB 存储
+const store = createStore('my-app', config, {
+  storage: remoteStorage({
+    backend: 'mongodb',
+    mongoUrl: 'mongodb://user:pass@host:27017',
+    mongoDb: 'myapp',
+  }),
+});
+
+// 或使用 JSONL 存储
+// const store = createStore('my-app', config, {
+//   storage: remoteStorage({
+//     backend: 'jsonl',
+//     jsonlDir: '/tmp/my-app-data',
+//   }),
+// });
+```
+
+### 在 React 组件中使用
+
+```typescript
+function App() {
+  const { theme, setTheme, isLoading } = useStore(store);
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return <input value={theme} onChange={e => setTheme(e.target.value)} />;
+}
+```
+
+### 自定义 BFF 服务器地址
+
+```typescript
+// 如果 BFF 运行在其他地址
+const adapter = remoteStorage({ baseUrl: 'http://localhost:3847' });
+const adapter = remoteStorage({ entityId: 'user-123' });  // 多租户支持
+```
+
+### Memory Storage (不持久化)
+
+适用于开发环境或不需要持久化的场景：
+
+```typescript
+import { createStore, useStore, memoryStorage } from 'bff-store';
+
+const store = createStore('my-app', config, {
+  storage: memoryStorage(),  // 不走 BFF，数据仅存在内存
+});
+```
+
+## Advanced: 手动启动 BFF Server
+
+大多数情况不需要手动启动 BFF，它会自动启动。如需手动控制：
+
+```typescript
+import { startServer } from 'bff-store/server';
+
+await startServer({
+  port: 3847,
+});
+```
+
+## Node.js 直接使用 Storage Adapters
+
+如果不通过 BFF，可以直接在 Node.js 中使用存储适配器：
+
+```typescript
+import { createStore } from 'bff-store';
+import { jsonlStorage } from 'bff-store/jsonl';
+import { mongodbStorage } from 'bff-store/mongodb';
+
+// 使用 JSONL
+const adapter = jsonlStorage({ dir: './sessions' });
+
+// 使用 MongoDB
+const adapter = await mongodbStorage({
+  url: 'mongodb://localhost:27017',
+  database: 'myapp',
+});
+
+const store = createStore('entity-123', config, { storage: adapter });
+```
+
+## API Endpoints (BFF Server)
+
+| Method | Endpoint | Body | Description |
+|--------|----------|------|-------------|
+| GET | `/storage/get/:key?entityId=x` | - | Get value by key |
+| POST | `/storage/set/:key?entityId=x` | `{ value }` | Set value |
+| DELETE | `/storage/delete/:key?entityId=x` | - | Delete key |
+| POST | `/storage/batch-get?entityId=x` | `{ keys: [] }` | Batch get |
+| POST | `/storage/batch-set?entityId=x` | `{ entries: {} }` | Batch set |
+| GET | `/health` | - | Health check |
+
+## API Reference
+
+### `createStore(entityId, config, options)`
+
+Creates a store with multiple persisted atoms.
+
+- `entityId`: Unique identifier for this store instance
+- `config`: Array of atom configurations
+- `options.storage`: Storage adapter (required)
+- `options.debounceMs`: Debounce delay in ms (default: 800)
+
+### `useStore(store)`
+
+React hook to use the store in components.
+
+Returns: `{ ...data, ...setters, isLoading }`
+
+Setter names are derived by capitalizing the config key:
+- `theme` → `setTheme`
+- `userName` → `setUserName`
+
+### `remoteStorage(options?)`
+
+Creates a remote storage adapter for connecting to the BFF server.
+
+```typescript
+// 基本用法 - BFF 使用默认存储后端
+const adapter = remoteStorage();
+
+// 指定使用 MongoDB
+const adapter = remoteStorage({
+  backend: 'mongodb',
+  mongoUrl: 'mongodb://user:pass@host:27017',
+  mongoDb: 'myapp',
+});
+
+// 指定使用 JSONL
+const adapter = remoteStorage({
+  backend: 'jsonl',
+  jsonlDir: '/tmp/my-app-data',
+});
+```
+
+- `options.baseUrl`: BFF server URL (default: `http://localhost:3847`)
+- `options.entityId`: Default entityId for all requests
+- `options.backend`: Storage backend type `'mongodb'` or `'jsonl'`
+- `options.mongoUrl`: MongoDB connection URL (required if backend is mongodb)
+- `options.mongoDb`: MongoDB database name (default: `jotai_state_store`)
+- `options.jsonlDir`: JSONL storage directory (required if backend is jsonl)
+
+### `startServer(options)`
+
+Starts the BFF server (singleton pattern). Import from `bff-store/server`.
+
+- `options.port`: Server port (default: 3847)
+
+Note: Storage backend is configured by the client via `remoteStorage()` options, not by the server.
+
+## Package Exports
+
+| Export | Description | Environment |
+|--------|-------------|-------------|
+| `bff-store` | Main entry: createStore, useStore, memoryStorage, remoteStorage | Browser + Node.js |
+| `bff-store/jsonl` | JSONL storage adapter | Node.js only |
+| `bff-store/mongodb` | MongoDB storage adapter | Node.js only |
+| `bff-store/server` | BFF server (startServer, Router, etc.) | Node.js only |
+
+## License
+
+MIT