bff-store 0.1.0 → 0.1.2

package/.claude/settings.local.json

@@ -39,7 +39,20 @@
       "Bash(npm publish:*)",
       "Bash(rg -rn \"jotai-state-store\" --type-list)",
       "Bash(rg -rn \"jotai-state-store\" .)",
-      "Bash(xargs sed:*)"
+      "Bash(xargs sed:*)",
+      "Bash(npx tsx:*)",
+      "Bash(npm ls:*)",
+      "Bash(perl -e 'alarm 5; exec @ARGV' -- node debug-simple.js)",
+      "Bash(echo \"exit: $?\")",
+      "Bash([ -d node_modules/mongodb ])",
+      "Bash(echo \"---mongodb status: $\\([ -d node_modules/mongodb ] && echo 'INSTALLED' || echo 'NOT INSTALLED'\\)\")",
+      "Bash(echo \"---mongodb: $\\([ -d node_modules/mongodb ] && echo 'INSTALLED' || echo 'NOT INSTALLED'\\)\")",
+      "Bash(xargs kill:*)",
+      "Bash(npm start:*)",
+      "Bash(mv 01-server-async-startup.md 01-server-async-startup.high.md)",
+      "Bash(mv 07-jsonl-key-collision.md 07-jsonl-key-collision.high.md)",
+      "Bash(mv 11-mongodb-storage-leak.md 11-mongodb-storage-leak.high.md)",
+      "Bash(mv 12-setEntityId-stale-closure.md 12-setEntityId-stale-closure.high.md)"
     ]
   }
 }

package/README.md

@@ -1,42 +1,77 @@
 # bff-store
 
-A jotai-based state management library with pluggable storage adapters and built-in BFF (Backend for Frontend) for browser/Next.js environments.
+A jotai-based state management library with pluggable storage adapters and a 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
+- **Pluggable storage**: Use memory, JSONL files, MongoDB, or a 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
+- **Debounced saves**: Automatic debouncing for non-critical data (800ms default)
 - **Built-in BFF**: Embedded sidecar API server for browser/Next.js environments
+- **Multi-tenant**: Per-entityId isolation via `setEntityId()`
+- **Unmount cleanup**: Pending writes cancelled on component unmount
+- **Embedded Sidecar**: Like a serverless function that auto-starts on first use — no manual server deployment required
 
 ## Architecture
 
 ```
 ┌─────────────────────────────────────────────────────────┐
-│                    Your Application                       │
-│                   (Next.js/Browser)                      │
-│                                                          │
-│  useStore() ──► remoteStorage ──► localhost:3847        │
-│                         │                                │
-│                         ▼                                │
-│              ┌─────────────────────┐                     │
-│              │   BFF (Sidecar)     │                     │
-│              │  bff-store │                     │
-│              │                     │                     │
-│              │  /storage/get/:key  │                     │
-│              │  /storage/set/:key  │                     │
-│              │  /storage/delete   │                     │
-│              └──────────┬──────────┘                     │
-│                         │                                │
-│                         ▼                                │
-│              ┌─────────────────────┐                     │
-│              │   JSONL / MongoDB   │                     │
-│              └─────────────────────┘                     │
+│                    Your Application                      │
+│                   (Next.js / Browser)                   │
+│                                                         │
+│  useStore() ──► remoteStorage ──► localhost:3847      │
+│                         │                               │
+│                         ▼                               │
+│              ┌─────────────────────┐                  │
+│              │     BFF (Sidecar)    │                  │
+│              │                     │                  │
+│              │  /storage/get/:key  │                  │
+│              │  /storage/set/:key  │                  │
+│              │  /storage/batch-*   │                  │
+│              └──────────┬──────────┘                  │
+│                         │                               │
+│                         ▼                               │
+│              ┌─────────────────────┐                  │
+│              │   JSONL / MongoDB   │                  │
+│              │    (multi-tenant)    │                  │
+│              └─────────────────────┘                  │
 └─────────────────────────────────────────────────────────┘
 ```
 
+### Data Flow
+
+1. **Init**: `createStore()` creates atoms, `remoteStorage` auto-starts the BFF server
+2. **Read**: `useStore()` returns from jotai store directly — no I/O
+3. **Write**: Update local jotai atom first (sync UI response), then debounce-persist to storage
+4. **Unmount**: Automatically cancel pending writes to prevent writes from destroyed components
+
+## Embedded Sidecar Pattern
+
+bff-store borrows the **embedded sidecar** pattern from microservices: the BFF server is co-located with your application process, auto-started on first use, with the lifecycle managed transparently.
+
+| Aspect | Classic Microservice Sidecar | bff-store Embedded Sidecar |
+|--------|----------------------------|--------------------------|
+| Deployment | Separate container, same pod | In-process, same Node.js process |
+| Startup | Kubernetes orchestrates | `createStore()` triggers `import('./server')` |
+| Singleton | One per pod | One per process (singleton `startServer`) |
+| State | External DB / volume | JSONL / MongoDB |
+| Scaling | Horizontal pod scaling | Multiple store instances share one server |
+| Cold start | Pod scheduling overhead | Module import + server listen (~100ms) |
+
+This gives you the **transparency of serverless** (no manual server deployment) with the **control of a long-running process** (full backend, no 100ms timeout, no cold starts after first invocation).
+
+### How it compares to serverless
+
+| | Serverless (Lambda) | bff-store Sidecar |
+|--|---------------------|-------------------|
+| Cold start | 100ms–1s (platform) | ~100ms (import + listen) |
+| State | External KV store (S3/Dynamo) | JSONL / MongoDB (local) |
+| Concurrency | One invocation per instance | All stores share one server |
+| Tenant isolation | Separate functions | Separate collections / directories |
+| Failure mode | Invocation fails | Server restarts, pending writes lost (mitigated by unmount cancel) |
+
 ## Installation
 
 ```bash
@@ -47,7 +82,7 @@ pnpm add bff-store
 
 ## Client Usage (Browser / Next.js)
 
-BFF Server 会自动启动，客户端只需使用 `remoteStorage()` 并指定存储后端：
+The BFF server starts automatically. Use `remoteStorage()` to specify the storage backend:
 
 ```typescript
 import { createStore, useStore, remoteStorage } from 'bff-store';
@@ -55,9 +90,10 @@ import { createStore, useStore, remoteStorage } from 'bff-store';
 const config = [
   { key: 'theme', defaultValue: 'dark' },
   { key: 'characters', defaultValue: [] },
+  { key: 'settings', defaultValue: {}, immediate: true },  // persist immediately, no debounce
 ] as const;
 
-// 使用 MongoDB 存储
+// Using MongoDB
 const store = createStore('my-app', config, {
   storage: remoteStorage({
     backend: 'mongodb',
@@ -66,7 +102,7 @@ const store = createStore('my-app', config, {
   }),
 });
 
-// 或使用 JSONL 存储
+// Or using JSONL
 // const store = createStore('my-app', config, {
 //   storage: remoteStorage({
 //     backend: 'jsonl',
@@ -75,71 +111,127 @@ const store = createStore('my-app', config, {
 // });
 ```
 
-### 在 React 组件中使用
+### In a React Component
 
 ```typescript
 function App() {
-  const { theme, setTheme, isLoading } = useStore(store);
+  const { theme, setTheme, characters, setCharacters, isLoading } = useStore(store);
 
   if (isLoading) return <div>Loading...</div>;
 
-  return <input value={theme} onChange={e => setTheme(e.target.value)} />;
+  return (
+    <input value={theme} onChange={e => setTheme(e.target.value)} />
+  );
 }
 ```
 
-### 自定义 BFF 服务器地址
+### Immediate Persistence (no debounce)
+
+For critical data, use `immediate: true`:
 
 ```typescript
-// 如果 BFF 运行在其他地址
-const adapter = remoteStorage({ baseUrl: 'http://localhost:3847' });
-const adapter = remoteStorage({ entityId: 'user-123' });  // 多租户支持
+const config = [
+  { key: 'autosave', defaultValue: '', immediate: true },
+] as const;
 ```
 
-### Memory Storage (不持久化)
+### Waiting for the Server
 
-适用于开发环境或不需要持久化的场景：
+`createStore` is synchronous, but server startup is asynchronous. Optionally wait:
 
 ```typescript
-import { createStore, useStore, memoryStorage } from 'bff-store';
+import { createStore, waitForServer } from 'bff-store';
 
-const store = createStore('my-app', config, {
-  storage: memoryStorage(),  // 不走 BFF，数据仅存在内存
-});
+const store = createStore('my-app', config, { storage: adapter });
+await waitForServer();
 ```
 
-## Advanced: 手动启动 BFF Server
+### Multi-Tenant Switching
 
-大多数情况不需要手动启动 BFF，它会自动启动。如需手动控制：
+Switch tenants dynamically via `setEntityId`:
 
 ```typescript
-import { startServer } from 'bff-store/server';
+const adapter = remoteStorage({ entityId: 'tenant-A' });
+const store = createStore('tenant-A', config, { storage: adapter });
 
-await startServer({
-  port: 3847,
+// Switch tenant
+adapter.setEntityId('tenant-B');
+```
+
+### Memory Storage (non-persistent)
+
+For development or non-persistent use cases:
+
+```typescript
+import { createStore, useStore, memoryStorage } from 'bff-store';
+
+const store = createStore('my-app', config, {
+  storage: memoryStorage(),  // data lives only in memory
 });
 ```
 
-## Node.js 直接使用 Storage Adapters
+## Node.js Direct Storage Adapter Usage
 
-如果不通过 BFF，可以直接在 Node.js 中使用存储适配器：
+You can also use storage adapters directly in Node.js without the BFF:
 
 ```typescript
-import { createStore } from 'bff-store';
+import { createNodeStore, getDefaultStore } from 'bff-store';
 import { jsonlStorage } from 'bff-store/jsonl';
 import { mongodbStorage } from 'bff-store/mongodb';
 
-// 使用 JSONL
-const adapter = jsonlStorage({ dir: './sessions' });
+// Using JSONL
+const store = createNodeStore('entity-123', [
+  { key: 'theme', defaultValue: 'dark' },
+  { key: 'count', defaultValue: 0 },
+], {
+  storage: jsonlStorage({ dir: './sessions' }),
+});
 
-// 使用 MongoDB
-const adapter = await mongodbStorage({
-  url: 'mongodb://localhost:27017',
-  database: 'myapp',
+// Wait for initial load (5s timeout)
+await store.waitForLoad();
+
+// Read/write via jotai getDefaultStore()
+const jotai = getDefaultStore();
+jotai.set(store.atoms.theme, 'light');   // auto-debounce persists
+console.log(jotai.get(store.atoms.count));
+
+// Or using MongoDB
+const store2 = createNodeStore('entity-456', [
+  { key: 'data', defaultValue: null },
+], {
+  storage: await mongodbStorage({
+    url: 'mongodb://localhost:27017',
+    database: 'myapp',
+  }),
 });
+```
+
+### Environment Detection
 
-const store = createStore('entity-123', config, { storage: adapter });
+```typescript
+import { isNode, isBrowser } from 'bff-store';
+
+if (isNode()) { /* Node.js */ }
+if (isBrowser()) { /* Browser */ }
 ```
 
+## Storage Backends
+
+### JSONL
+
+File format: `{dir}/{entityId}/{encodeURIComponent(key)}.jsonl`
+
+Each line is a JSON object with timestamp. `get` reads the last line for the latest value.
+
+### MongoDB
+
+Collection name: `state_{entityId}`. Each key uses upsert — only the latest value is kept.
+
+> For production, create a compound index on `key + entityId`:
+> ```javascript
+> db.state_<entityId>.createIndex({ key: 1, entityId: 1 }, { unique: true })
+> ```
+
 ## API Endpoints (BFF Server)
 
 | Method | Endpoint | Body | Description |
@@ -162,9 +254,18 @@ Creates a store with multiple persisted atoms.
 - `options.storage`: Storage adapter (required)
 - `options.debounceMs`: Debounce delay in ms (default: 800)
 
+### `waitForServer()`
+
+Returns a promise that resolves when the auto-started BFF server is ready. Only meaningful in Node.js with `remoteStorage`.
+
+```typescript
+import { waitForServer } from 'bff-store';
+await waitForServer();
+```
+
 ### `useStore(store)`
 
-React hook to use the store in components.
+React hook to consume the store in components.
 
 Returns: `{ ...data, ...setters, isLoading }`
 
@@ -172,26 +273,39 @@ Setter names are derived by capitalizing the config key:
 - `theme` → `setTheme`
 - `userName` → `setUserName`
 
+### `createNodeStore(entityId, config, options)`
+
+Node.js environment store with `waitForLoad()`.
+
+```typescript
+const store = createNodeStore('entity-123', config, { storage: adapter });
+await store.waitForLoad();  // 5s timeout
+```
+
 ### `remoteStorage(options?)`
 
 Creates a remote storage adapter for connecting to the BFF server.
 
 ```typescript
-// 基本用法 - BFF 使用默认存储后端
+// Basic
 const adapter = remoteStorage();
 
-// 指定使用 MongoDB
+// Use MongoDB
 const adapter = remoteStorage({
   backend: 'mongodb',
   mongoUrl: 'mongodb://user:pass@host:27017',
   mongoDb: 'myapp',
 });
 
-// 指定使用 JSONL
+// Use JSONL
 const adapter = remoteStorage({
   backend: 'jsonl',
   jsonlDir: '/tmp/my-app-data',
 });
+
+// Multi-tenant
+const adapter = remoteStorage({ entityId: 'user-123' });
+adapter.setEntityId('user-456');  // switch tenant
 ```
 
 - `options.baseUrl`: BFF server URL (default: `http://localhost:3847`)
@@ -199,24 +313,43 @@ const adapter = remoteStorage({
 - `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)
+- `options.jsonlDir`: JSONL storage directory (default: `./data`)
 
 ### `startServer(options)`
 
 Starts the BFF server (singleton pattern). Import from `bff-store/server`.
 
-- `options.port`: Server port (default: 3847)
+```typescript
+import { startServer } from 'bff-store/server';
 
-Note: Storage backend is configured by the client via `remoteStorage()` options, not by the server.
+await startServer({
+  port: 3847,
+  backend: 'jsonl',
+  jsonlDir: './data',
+});
+```
 
 ## Package Exports
 
 | Export | Description | Environment |
 |--------|-------------|-------------|
-| `bff-store` | Main entry: createStore, useStore, memoryStorage, remoteStorage | Browser + Node.js |
+| `bff-store` | Main: createStore, useStore, createNodeStore, waitForServer, isNode, isBrowser, 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 |
+| `bff-store/mongodb` | MongoDB storage adapter (async factory) | Node.js only |
+| `bff-store/server` | BFF server: startServer, Router, EntityIdCache | Node.js only |
+
+## Changelog
+
+### v0.1.1 (2026-07-05)
+
+- `createStore` with `remote` storage now waits for server startup to complete
+- `waitForServer()` added for explicit server readiness
+- `remoteStorage.setEntityId()` now works correctly (live entityId reference)
+- MongoDB `set` uses upsert mode — no more unbounded document accumulation
+- JSONL key encoding changed to `encodeURIComponent` — prevents `a.b` / `a-b` collision
+- `atom.onMount` unmount cleanup cancels pending debounced writes
+- `waitForLoad()` now has a 5s timeout
+- HTTP error responses now include server-returned error details
 
 ## License
 

package/dist/cli.js

@@ -32025,12 +32025,11 @@ async function mongodbStorage(options2) {
     },
     async set(key, value) {
       const collection = getCollection(currentEntityId);
-      await collection.insertOne({
-        key,
-        value,
-        timestamp: Date.now(),
-        entityId: currentEntityId
-      });
+      await collection.updateOne(
+        { key, entityId: currentEntityId },
+        { $set: { value, timestamp: Date.now() } },
+        { upsert: true }
+      );
     },
     async remove(key) {
       const collection = getCollection(currentEntityId);
@@ -32133,7 +32132,7 @@ function jsonlStorage(options2) {
   const baseDir = options2?.dir ?? "./sessions";
   let entityId = "default";
   function getFilePath(eId, key) {
-    const safeKey = key.replace(/[^a-zA-Z0-9_]/g, "_");
+    const safeKey = encodeURIComponent(key);
     return path.join(baseDir, eId, `${safeKey}.jsonl`);
   }
   const storage = {
@@ -32281,7 +32280,7 @@ async function getCachedStorage(config, entityId) {
     }
     return entry.adapter.storage;
   }
-  if (storageCache.size >= MAX_CACHE_SIZE) {
+  while (storageCache.size >= MAX_CACHE_SIZE && storageCache.size > 0) {
     let oldestKey = null;
     let oldestTime = Infinity;
     for (const [k, entry] of storageCache.entries()) {
@@ -32292,6 +32291,8 @@ async function getCachedStorage(config, entityId) {
     }
     if (oldestKey) {
       storageCache.delete(oldestKey);
+    } else {
+      break;
     }
   }
   let adapter;
@@ -32324,6 +32325,7 @@ function createStorageHandlers(options2) {
       try {
         body = await parseBody(req);
       } catch {
+        console.warn("[bff-store] Failed to parse request body, using URL config only");
       }
     }
     const config = body ? {
@@ -32399,7 +32401,7 @@ function createStorageHandlers(options2) {
     res.writeHead(200);
     res.end(JSON.stringify({ success: true }));
   }
-  async function handleHealth(req, res) {
+  async function handleHealth(_req, res) {
     res.setHeader("Content-Type", "application/json");
     res.writeHead(200);
     res.end(JSON.stringify({ status: "ok" }));

package/dist/index.d.mts

@@ -79,6 +79,12 @@ declare function createStore(entityId: string, config: AtomConfigs, options?: {
     storage: StorageAdapter;
     debounceMs?: number;
 }): Store;
+/**
+ * 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.
+ */
+declare function waitForServer(): Promise<void> | undefined;
 
 /**
  * React Hook to use a store
@@ -229,4 +235,45 @@ interface RemoteStorageOptions {
  */
 declare function remoteStorage(options?: RemoteStorageOptions): StorageAdapter;
 
-export { type AsyncStorageFactory, type AtomConfig, type AtomConfigs, type AtomType, HttpTransport, type MemoryStorageOptions, RestStorageProtocol, type Storage, type StorageAdapter, type StorageFactory, type StorageHttpProtocol, type StorageOptions, type Store, type TransportAdapter, type UseStoreReturn, createMemoryStorage, createPersistedAtom, remoteStorage as createRemoteStorage, createStorageFromTransport, createStorageWithProtocol, createStore, memoryStorage, remoteStorage, useStore };
+/**
+ * Environment detection utilities
+ */
+declare function isNode(): boolean;
+declare function isBrowser(): boolean;
+
+/**
+ * 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');
+ * ```
+ */
+declare 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>;
+};
+
+export { type AsyncStorageFactory, type AtomConfig, type AtomConfigs, type AtomType, HttpTransport, type MemoryStorageOptions, RestStorageProtocol, type Storage, type StorageAdapter, type StorageFactory, type StorageHttpProtocol, type StorageOptions, type Store, type TransportAdapter, type UseStoreReturn, createMemoryStorage, createNodeStore, createPersistedAtom, remoteStorage as createRemoteStorage, createStorageFromTransport, createStorageWithProtocol, createStore, isBrowser, isNode, memoryStorage, remoteStorage, useStore, waitForServer };

package/dist/index.d.ts

@@ -79,6 +79,12 @@ declare function createStore(entityId: string, config: AtomConfigs, options?: {
     storage: StorageAdapter;
     debounceMs?: number;
 }): Store;
+/**
+ * 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.
+ */
+declare function waitForServer(): Promise<void> | undefined;
 
 /**
  * React Hook to use a store
@@ -229,4 +235,45 @@ interface RemoteStorageOptions {
  */
 declare function remoteStorage(options?: RemoteStorageOptions): StorageAdapter;
 
-export { type AsyncStorageFactory, type AtomConfig, type AtomConfigs, type AtomType, HttpTransport, type MemoryStorageOptions, RestStorageProtocol, type Storage, type StorageAdapter, type StorageFactory, type StorageHttpProtocol, type StorageOptions, type Store, type TransportAdapter, type UseStoreReturn, createMemoryStorage, createPersistedAtom, remoteStorage as createRemoteStorage, createStorageFromTransport, createStorageWithProtocol, createStore, memoryStorage, remoteStorage, useStore };
+/**
+ * Environment detection utilities
+ */
+declare function isNode(): boolean;
+declare function isBrowser(): boolean;
+
+/**
+ * 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');
+ * ```
+ */
+declare 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>;
+};
+
+export { type AsyncStorageFactory, type AtomConfig, type AtomConfigs, type AtomType, HttpTransport, type MemoryStorageOptions, RestStorageProtocol, type Storage, type StorageAdapter, type StorageFactory, type StorageHttpProtocol, type StorageOptions, type Store, type TransportAdapter, type UseStoreReturn, createMemoryStorage, createNodeStore, createPersistedAtom, remoteStorage as createRemoteStorage, createStorageFromTransport, createStorageWithProtocol, createStore, isBrowser, isNode, memoryStorage, remoteStorage, useStore, waitForServer };