bff-store 0.1.0

package/src/storage/adapters/remoteStorage.ts

@@ -0,0 +1,70 @@
+/**
+ * Remote Storage Adapter
+ *
+ * Client-side adapter that calls the embedded sidecar server.
+ * Uses HttpTransport and RestStorageProtocol for HTTP operations.
+ */
+
+import type { Storage, StorageAdapter } from '../base';
+import { HttpTransport, type TransportAdapter } from '../transport';
+import { RestStorageProtocol, createStorageWithProtocol, type StorageHttpProtocol } from '../protocol';
+
+export interface RemoteStorageOptions {
+  baseUrl?: string;  // Default: 'http://localhost:3847'
+  entityId?: string; // Default entityId for all requests
+  transport?: TransportAdapter; // Custom transport (default: HttpTransport)
+  protocol?: StorageHttpProtocol; // Custom protocol (default: RestStorageProtocol)
+  // Storage backend configuration (sent to BFF)
+  backend?: 'mongodb' | 'jsonl';
+  mongoUrl?: string;
+  mongoDb?: string;
+  jsonlDir?: string;
+}
+
+/**
+ * Create a remote storage adapter that connects to the embedded sidecar server.
+ *
+ * @example
+ * ```typescript
+ * import { createStore, remoteStorage } from 'bff-store';
+ *
+ * // Connect to default server (localhost:3847)
+ * const adapter = remoteStorage();
+ *
+ * // Or with custom server URL
+ * const adapter = remoteStorage({ baseUrl: 'http://localhost:3847' });
+ *
+ * // With entityId
+ * const adapter = remoteStorage({ entityId: 'user-123' });
+ *
+ * const store = createStore('user-123', config, { storage: adapter });
+ * ```
+ */
+export function remoteStorage(options: RemoteStorageOptions = {}): StorageAdapter {
+  const baseUrl = options.baseUrl ?? 'http://localhost:3847';
+  const transport = options.transport ?? new HttpTransport();
+  const entityId = { current: options.entityId };
+
+  // Backend config for BFF routing
+  const backendConfig = {
+    backend: options.backend,
+    mongoUrl: options.mongoUrl,
+    mongoDb: options.mongoDb,
+    jsonlDir: options.jsonlDir,
+  };
+
+  const protocol = options.protocol ?? new RestStorageProtocol(baseUrl, entityId.current, backendConfig);
+  const storage = createStorageWithProtocol(transport, protocol);
+
+  const adapter: StorageAdapter = {
+    storage,
+    name: 'remote',
+    setEntityId(id: string) {
+      entityId.current = id;
+    },
+  };
+
+  return adapter;
+}
+
+export { remoteStorage as createRemoteStorage };

package/src/storage/base.ts

@@ -0,0 +1,28 @@
+// ========================================
+// Storage Interface
+// ========================================
+
+export 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>;
+}
+
+// ========================================
+// Storage Adapter Factory Types
+// ========================================
+
+export interface StorageAdapter {
+  storage: Storage;
+  name: string;
+  /** Optional: set the entityId for multi-tenant storage */
+  setEntityId?(entityId: string): void;
+}
+
+export type StorageFactory<T = unknown> = (options?: T) => StorageAdapter;
+
+export type AsyncStorageFactory<T = unknown> = (options: T) => Promise<StorageAdapter>;

package/src/storage/index.ts

@@ -0,0 +1,9 @@
+export { memoryStorage, createMemoryStorage } from './memory';
+export { jsonlStorage, createJsonlStorage } from './jsonl';
+export { mongodbStorage, createMongoStorage } from './mongodb';
+export { remoteStorage, createRemoteStorage } from './adapters/remoteStorage';
+export { HttpTransport, createStorageFromTransport } from './transport';
+export { RestStorageProtocol, createStorageWithProtocol } from './protocol';
+export type { TransportAdapter } from './transport';
+export type { StorageHttpProtocol } from './protocol';
+export type { Storage, StorageAdapter, StorageFactory, AsyncStorageFactory } from './base';

package/src/storage/jsonl-entry.ts

@@ -0,0 +1,9 @@
+/**
+ * JSONL storage adapter entry point
+ * Import from 'bff-store/jsonl' instead of 'bff-store'
+ *
+ * @example
+ * import { jsonlStorage } from 'bff-store/jsonl';
+ */
+export { jsonlStorage, createJsonlStorage } from './jsonl';
+export type { JsonlStorageOptions } from '../types';

package/src/storage/jsonl.ts

@@ -0,0 +1,111 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { Storage, StorageAdapter, StorageFactory } from './base';
+import type { JsonlStorageOptions } from '../types';
+
+interface JsonlEntry {
+  key: string;
+  value: unknown;
+  timestamp: number;
+}
+
+interface JsonlStorageInstance extends StorageAdapter {
+  storage: Storage;
+  setEntityId(id: string): void;
+}
+
+/**
+ * JSONL file storage adapter
+ * Stores data as {dir}/{entityId}/{key}.jsonl
+ * Each line is a JSON object with key, value, and timestamp
+ *
+ * Usage:
+ *   const adapter = jsonlStorage({ dir: './sessions' });
+ *   adapter.setEntityId('user-123');
+ *   const store = createStore('user-123', config, { storage: adapter.storage });
+ */
+export function jsonlStorage(options?: JsonlStorageOptions): JsonlStorageInstance {
+  const baseDir = options?.dir ?? './sessions';
+  let entityId: string = 'default';
+
+  function getFilePath(eId: string, key: string): string {
+    const safeKey = key.replace(/[^a-zA-Z0-9_]/g, '_');
+    return path.join(baseDir, eId, `${safeKey}.jsonl`);
+  }
+
+  const storage: Storage = {
+    async get<T>(key: string): Promise<T | null> {
+      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;
+
+        // Read the last line for the latest value
+        const lastLine = lines[lines.length - 1];
+        const entry: JsonlEntry = JSON.parse(lastLine);
+        return entry.value as T;
+      } catch {
+        return null;
+      }
+    },
+
+    async set<T>(key: string, value: T): Promise<void> {
+      if (!entityId) return;
+
+      const filePath = getFilePath(entityId, key);
+      const dir = path.dirname(filePath);
+
+      // Ensure directory exists
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+
+      const entry: JsonlEntry = {
+        key,
+        value,
+        timestamp: Date.now(),
+      };
+
+      const line = JSON.stringify(entry) + '\n';
+      fs.appendFileSync(filePath, line, 'utf-8');
+    },
+
+    async remove(key: string): Promise<void> {
+      if (!entityId) return;
+
+      const filePath = getFilePath(entityId, key);
+      if (fs.existsSync(filePath)) {
+        fs.unlinkSync(filePath);
+      }
+    },
+
+    async getMultiple<T>(keys: string[]): Promise<Map<string, T>> {
+      const result = new Map<string, T>();
+      for (const key of keys) {
+        const value = await this.get<T>(key);
+        if (value !== null) {
+          result.set(key, value);
+        }
+      }
+      return result;
+    },
+  };
+
+  return {
+    storage,
+    name: 'jsonl',
+    setEntityId(id: string) {
+      entityId = id;
+    },
+  };
+}
+
+export const createJsonlStorage: StorageFactory<JsonlStorageOptions> = jsonlStorage;

package/src/storage/memory.ts

@@ -0,0 +1,49 @@
+import { Storage, StorageAdapter, StorageFactory } from './base';
+import type { MemoryStorageOptions } from '../types';
+
+/**
+ * In-memory storage adapter for development and testing
+ */
+export function memoryStorage(
+  _options?: MemoryStorageOptions
+): StorageAdapter {
+  const store = new Map<string, unknown>();
+
+  const storage: Storage = {
+    async get<T>(key: string): Promise<T | null> {
+      return (store.get(key) as T) ?? null;
+    },
+
+    async set<T>(key: string, value: T): Promise<void> {
+      store.set(key, value);
+    },
+
+    async remove(key: string): Promise<void> {
+      store.delete(key);
+    },
+
+    async getMultiple<T>(keys: string[]): Promise<Map<string, T>> {
+      const result = new Map<string, T>();
+      for (const key of keys) {
+        const value = store.get(key) as T;
+        if (value !== undefined) {
+          result.set(key, value);
+        }
+      }
+      return result;
+    },
+
+    async setMultiple<T>(entries: Map<string, T>): Promise<void> {
+      entries.forEach((value, key) => {
+        store.set(key, value);
+      });
+    },
+  };
+
+  return {
+    storage,
+    name: 'memory',
+  };
+}
+
+export const createMemoryStorage: StorageFactory<MemoryStorageOptions> = memoryStorage;

package/src/storage/mongodb-entry.ts

@@ -0,0 +1,9 @@
+/**
+ * MongoDB storage adapter entry point
+ * Import from 'bff-store/mongodb' instead of 'bff-store'
+ *
+ * @example
+ * import { mongodbStorage } from 'bff-store/mongodb';
+ */
+export { mongodbStorage, createMongoStorage } from './mongodb';
+export type { MongoStorageOptions } from '../types';

package/src/storage/mongodb.ts

@@ -0,0 +1,132 @@
+import { MongoClient, Collection, Db } from 'mongodb';
+import { Storage, StorageAdapter, AsyncStorageFactory } from './base';
+import type { MongoStorageOptions } from '../types';
+
+interface MongoEntry {
+  key: string;
+  value: unknown;
+  timestamp: number;
+  entityId: 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.
+ */
+export async function mongodbStorage(
+  options: MongoStorageOptions
+): Promise<MongoStorageAdapter> {
+  const {
+    url,
+    database = 'jotai_state_store',
+  } = options;
+
+  const client = new MongoClient(url);
+  await client.connect();
+
+  const db: Db = client.db(database);
+
+  // Current entityId - defaults to 'default'
+  let currentEntityId = 'default';
+
+  // Get collection name for an entityId
+  function getCollectionName(eId: string): string {
+    return `state_${eId}`;
+  }
+
+  // Get or create collection for an entityId
+  function getCollection(eId: string): Collection<MongoEntry> {
+    return db.collection<MongoEntry>(getCollectionName(eId));
+  }
+
+  const storage: Storage = {
+    async get<T>(key: string): Promise<T | null> {
+      const collection = getCollection(currentEntityId);
+
+      const entry = await collection.findOne(
+        { key },
+        { sort: { timestamp: -1 } }
+      );
+
+      return entry ? (entry.value as T) : null;
+    },
+
+    async set<T>(key: string, value: T): Promise<void> {
+      const collection = getCollection(currentEntityId);
+
+      await collection.insertOne({
+        key,
+        value,
+        timestamp: Date.now(),
+        entityId: currentEntityId,
+      });
+    },
+
+    async remove(key: string): Promise<void> {
+      const collection = getCollection(currentEntityId);
+
+      await collection.deleteMany({ key });
+    },
+
+    async getMultiple<T>(keys: string[]): Promise<Map<string, T>> {
+      const collection = getCollection(currentEntityId);
+
+      const entries = await collection
+        .find({ key: { $in: keys } })
+        .sort({ timestamp: -1 })
+        .toArray();
+
+      const result = new Map<string, T>();
+      const seen = new Set<string>();
+
+      for (const entry of entries) {
+        if (!seen.has(entry.key)) {
+          result.set(entry.key, entry.value as T);
+          seen.add(entry.key);
+        }
+      }
+
+      return result;
+    },
+
+    async setMultiple<T>(entries: Map<string, T>): Promise<void> {
+      const collection = getCollection(currentEntityId);
+
+      const docs: MongoEntry[] = [];
+      entries.forEach((value, key) => {
+        docs.push({
+          key,
+          value,
+          timestamp: Date.now(),
+          entityId: currentEntityId,
+        });
+      });
+
+      if (docs.length > 0) {
+        await collection.insertMany(docs);
+      }
+    },
+  };
+
+  const adapter: MongoStorageAdapter = {
+    storage,
+    name: 'mongodb',
+    client,
+    setEntityId(id: string) {
+      currentEntityId = id;
+    },
+    async close() {
+      await client.close();
+    },
+  };
+
+  return adapter;
+}
+
+export const createMongoStorage: AsyncStorageFactory<MongoStorageOptions> = mongodbStorage;

package/src/storage/protocol.ts

@@ -0,0 +1,170 @@
+/**
+ * Storage HTTP Protocol Interface
+ *
+ * Defines the request/response contract for storage operations over HTTP.
+ * This allows the protocol to be implemented differently without changing
+ * the storage semantics.
+ */
+
+import type { TransportAdapter } from './transport';
+import type { BackendConfig } from '../types';
+export type { BackendConfig } from '../types';
+
+export interface StorageHttpProtocol {
+  /** Build URL for get operation */
+  buildGetUrl(key: string): string;
+  /** Build URL for set operation */
+  buildSetUrl(key: string): string;
+  /** Build URL for delete operation */
+  buildDeleteUrl(key: string): string;
+  /** Build URL for batch get */
+  buildBatchGetUrl(): string;
+  /** Build URL for batch set */
+  buildBatchSetUrl(): string;
+  /** Get backend config */
+  getBackendConfig(): BackendConfig;
+}
+
+/**
+ * Default protocol implementation using standard REST paths
+ */
+export class RestStorageProtocol implements StorageHttpProtocol {
+  constructor(
+    private baseUrl: string,
+    private entityId?: string | { current?: string },
+    private backendConfig: BackendConfig = {}
+  ) {}
+
+  private getEntityId(): string | undefined {
+    return typeof this.entityId === 'object' ? this.entityId.current : this.entityId;
+  }
+
+  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);
+    }
+  }
+
+  private buildUrl(path: string, key: string): string {
+    const url = `${this.baseUrl}${path}${encodeURIComponent(key)}`;
+    const params = new URLSearchParams();
+    const eid = this.getEntityId();
+    if (eid) {
+      params.set('entityId', eid);
+    }
+    this.appendBackendParams(params);
+    const queryString = params.toString();
+    return queryString ? `${url}?${queryString}` : url;
+  }
+
+  buildGetUrl(key: string): string {
+    return this.buildUrl('/storage/get/', key);
+  }
+
+  buildSetUrl(key: string): string {
+    return this.buildUrl('/storage/set/', key);
+  }
+
+  buildDeleteUrl(key: string): string {
+    return this.buildUrl('/storage/delete/', key);
+  }
+
+  buildBatchGetUrl(): string {
+    const url = `${this.baseUrl}/storage/batch-get`;
+    const params = new URLSearchParams();
+    const eid = this.getEntityId();
+    if (eid) {
+      params.set('entityId', eid);
+    }
+    this.appendBackendParams(params);
+    const queryString = params.toString();
+    return queryString ? `${url}?${queryString}` : url;
+  }
+
+  buildBatchSetUrl(): string {
+    const url = `${this.baseUrl}/storage/batch-set`;
+    const params = new URLSearchParams();
+    const eid = this.getEntityId();
+    if (eid) {
+      params.set('entityId', eid);
+    }
+    this.appendBackendParams(params);
+    const queryString = params.toString();
+    return queryString ? `${url}?${queryString}` : url;
+  }
+
+  getBackendConfig(): BackendConfig {
+    return this.backendConfig;
+  }
+
+  withEntityId(entityId: string): RestStorageProtocol {
+    return new RestStorageProtocol(this.baseUrl, entityId, this.backendConfig);
+  }
+}
+
+/**
+ * Create a storage that uses a specific protocol
+ */
+export function createStorageWithProtocol(
+  transport: TransportAdapter,
+  protocol: StorageHttpProtocol
+): {
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T): Promise<void>;
+  remove(key: string): Promise<void>;
+  getMultiple<T>(keys: string[]): Promise<Map<string, T>>;
+  setMultiple<T>(entries: Map<string, T>): Promise<void>;
+} {
+  // Get backend config from protocol if available
+  const backendConfig = 'getBackendConfig' in protocol
+    ? protocol.getBackendConfig()
+    : {};
+
+  return {
+    async get<T>(key: string): Promise<T | null> {
+      try {
+        const res = await transport.get<{ value: T }>(protocol.buildGetUrl(key));
+        return res.value;
+      } catch (err: any) {
+        if (err.message.includes('failed')) {
+          return null;
+        }
+        throw err;
+      }
+    },
+
+    async set<T>(key: string, value: T): Promise<void> {
+      const body: Record<string, unknown> = { value, ...backendConfig };
+      await transport.post(protocol.buildSetUrl(key), body);
+    },
+
+    async remove(key: string): Promise<void> {
+      await transport.delete(protocol.buildDeleteUrl(key));
+    },
+
+    async getMultiple<T>(keys: string[]): Promise<Map<string, T>> {
+      const res = await transport.post<{ keys: string[] }, { entries: Record<string, T> }>(
+        protocol.buildBatchGetUrl(),
+        { keys, ...backendConfig }
+      );
+      return new Map(Object.entries(res.entries));
+    },
+
+    async setMultiple<T>(entries: Map<string, T>): Promise<void> {
+      const obj: Record<string, T> = {};
+      entries.forEach((value, key) => {
+        obj[key] = value;
+      });
+      await transport.post(protocol.buildBatchSetUrl(), { entries: obj, ...backendConfig });
+    },
+  };
+}

package/src/storage/transport.ts

@@ -0,0 +1,95 @@
+/**
+ * Transport Adapter Interface
+ *
+ * Abstracts the transport layer for remote storage operations.
+ * Can be implemented as HTTP, WebSocket, or other protocols.
+ */
+
+export interface TransportAdapter {
+  /** GET request */
+  get<T>(url: string): Promise<T>;
+  /** POST request with JSON body */
+  post<T, R>(url: string, body: T): Promise<R>;
+  /** DELETE request */
+  delete(url: string): Promise<void>;
+}
+
+/**
+ * HTTP Transport Adapter using fetch
+ */
+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}`);
+    }
+    return res.json();
+  }
+
+  async post<T, R>(url: string, body: T): Promise<R> {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      throw new Error(`POST ${url} failed: ${res.statusText}`);
+    }
+    return res.json();
+  }
+
+  async delete(url: string): Promise<void> {
+    const res = await fetch(url, { method: 'DELETE' });
+    if (!res.ok) {
+      throw new Error(`DELETE ${url} failed: ${res.statusText}`);
+    }
+  }
+}
+
+/**
+ * Create a StorageAdapter that wraps a TransportAdapter and base URL
+ */
+import type { Storage, StorageAdapter } from './base';
+
+export function createStorageFromTransport(
+  transport: TransportAdapter,
+  baseUrl: string
+): Storage {
+  return {
+    async get<T>(key: string): Promise<T | null> {
+      try {
+        const res = await transport.get<{ value: T }>(`${baseUrl}/storage/get/${encodeURIComponent(key)}`);
+        return res.value;
+      } catch (err: any) {
+        if (err.message.includes('failed')) {
+          return null;
+        }
+        throw err;
+      }
+    },
+
+    async set<T>(key: string, value: T): Promise<void> {
+      await transport.post(`${baseUrl}/storage/set/${encodeURIComponent(key)}`, { value });
+    },
+
+    async remove(key: string): Promise<void> {
+      await transport.delete(`${baseUrl}/storage/delete/${encodeURIComponent(key)}`);
+    },
+
+    async getMultiple<T>(keys: string[]): Promise<Map<string, T>> {
+      const res = await transport.post<{ keys: string[] }, { entries: Record<string, T> }>(
+        `${baseUrl}/storage/batch-get`,
+        { keys }
+      );
+      return new Map(Object.entries(res.entries));
+    },
+
+    async setMultiple<T>(entries: Map<string, T>): Promise<void> {
+      const obj: Record<string, T> = {};
+      entries.forEach((value, key) => {
+        obj[key] = value;
+      });
+      await transport.post(`${baseUrl}/storage/batch-set`, { entries: obj });
+    },
+  };
+}