bff-store 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,232 @@
+import { WritableAtom, Atom } from 'jotai';
+
+type AtomType = 'string' | 'number' | 'boolean' | 'array' | 'object';
+interface AtomConfig<T = unknown> {
+    key: string;
+    defaultValue: T;
+    type?: AtomType;
+    /** If true, save immediately without debounce */
+    immediate?: boolean;
+}
+type AtomConfigs = readonly AtomConfig[];
+interface PersistedAtomWithLoading<T> {
+    atom: WritableAtom<T, [update: T | ((prev: T) => T)], void>;
+    loadingAtom: Atom<boolean>;
+}
+type StoreAtoms = Record<string, WritableAtom<any, [any], void>>;
+type StoreLoadingAtoms = Record<string, Atom<boolean>>;
+interface Store {
+    entityId: string;
+    config: AtomConfigs;
+    atoms: StoreAtoms;
+    loadingAtoms: StoreLoadingAtoms;
+}
+type UseStoreReturn = Record<string, any> & {
+    isLoading: boolean;
+};
+interface StorageOptions {
+    debounceMs?: number;
+}
+interface MemoryStorageOptions extends StorageOptions {
+}
+interface BackendConfig {
+    backend?: 'mongodb' | 'jsonl';
+    mongoUrl?: string;
+    mongoDb?: string;
+    jsonlDir?: string;
+}
+
+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 StorageFactory<T = unknown> = (options?: T) => StorageAdapter;
+type AsyncStorageFactory<T = unknown> = (options: T) => Promise<StorageAdapter>;
+
+/**
+ * Creates a store with multiple persisted atoms
+ *
+ * @param entityId - Unique identifier for this store instance
+ * @param config - Array of atom configurations
+ * @param options - Store options including storage adapter
+ *
+ * @example
+ * ```typescript
+ * const config = [
+ *   { key: 'theme', defaultValue: '' },
+ *   { key: 'characters', defaultValue: [] },
+ * ] as const;
+ *
+ * const adapter = jsonlStorage({ dir: './sessions' });
+ *
+ * const store = createStore('novel-123', config, {
+ *   storage: adapter,
+ * });
+ * ```
+ */
+declare function createStore(entityId: string, config: AtomConfigs, options?: {
+    storage: StorageAdapter;
+    debounceMs?: number;
+}): Store;
+
+/**
+ * React Hook to use a store
+ *
+ * @example
+ * ```typescript
+ * const store = createStore('user-123', [
+ *   { key: 'name', defaultValue: '' },
+ *   { key: 'age', defaultValue: 0 },
+ * ], { storage });
+ *
+ * function UserProfile() {
+ *   const { name, age, setName, setAge, isLoading } = useStore(store);
+ *   // ...
+ * }
+ * ```
+ */
+declare function useStore(store: Store): UseStoreReturn;
+
+/**
+ * Creates a persisted atom with loading state tracking
+ */
+declare function createPersistedAtom<T>(config: AtomConfig<T>, entityId: string, storage: Storage, options?: {
+    immediate?: boolean;
+    debounceMs?: number;
+}): PersistedAtomWithLoading<T>;
+
+/**
+ * In-memory storage adapter for development and testing
+ */
+declare function memoryStorage(_options?: MemoryStorageOptions): StorageAdapter;
+declare const createMemoryStorage: StorageFactory<MemoryStorageOptions>;
+
+/**
+ * Transport Adapter Interface
+ *
+ * Abstracts the transport layer for remote storage operations.
+ * Can be implemented as HTTP, WebSocket, or other protocols.
+ */
+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
+ */
+declare class HttpTransport implements TransportAdapter {
+    get<T>(url: string): Promise<T>;
+    post<T, R>(url: string, body: T): Promise<R>;
+    delete(url: string): Promise<void>;
+}
+
+declare function createStorageFromTransport(transport: TransportAdapter, baseUrl: string): Storage;
+
+/**
+ * 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.
+ */
+
+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
+ */
+declare class RestStorageProtocol implements StorageHttpProtocol {
+    private baseUrl;
+    private entityId?;
+    private backendConfig;
+    constructor(baseUrl: string, entityId?: string | {
+        current?: string;
+    } | undefined, backendConfig?: BackendConfig);
+    private getEntityId;
+    private appendBackendParams;
+    private buildUrl;
+    buildGetUrl(key: string): string;
+    buildSetUrl(key: string): string;
+    buildDeleteUrl(key: string): string;
+    buildBatchGetUrl(): string;
+    buildBatchSetUrl(): string;
+    getBackendConfig(): BackendConfig;
+    withEntityId(entityId: string): RestStorageProtocol;
+}
+/**
+ * Create a storage that uses a specific protocol
+ */
+declare 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>;
+};
+
+/**
+ * Remote Storage Adapter
+ *
+ * Client-side adapter that calls the embedded sidecar server.
+ * Uses HttpTransport and RestStorageProtocol for HTTP operations.
+ */
+
+interface RemoteStorageOptions {
+    baseUrl?: string;
+    entityId?: string;
+    transport?: TransportAdapter;
+    protocol?: StorageHttpProtocol;
+    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 });
+ * ```
+ */
+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 };

package/dist/index.d.ts

@@ -0,0 +1,232 @@
+import { WritableAtom, Atom } from 'jotai';
+
+type AtomType = 'string' | 'number' | 'boolean' | 'array' | 'object';
+interface AtomConfig<T = unknown> {
+    key: string;
+    defaultValue: T;
+    type?: AtomType;
+    /** If true, save immediately without debounce */
+    immediate?: boolean;
+}
+type AtomConfigs = readonly AtomConfig[];
+interface PersistedAtomWithLoading<T> {
+    atom: WritableAtom<T, [update: T | ((prev: T) => T)], void>;
+    loadingAtom: Atom<boolean>;
+}
+type StoreAtoms = Record<string, WritableAtom<any, [any], void>>;
+type StoreLoadingAtoms = Record<string, Atom<boolean>>;
+interface Store {
+    entityId: string;
+    config: AtomConfigs;
+    atoms: StoreAtoms;
+    loadingAtoms: StoreLoadingAtoms;
+}
+type UseStoreReturn = Record<string, any> & {
+    isLoading: boolean;
+};
+interface StorageOptions {
+    debounceMs?: number;
+}
+interface MemoryStorageOptions extends StorageOptions {
+}
+interface BackendConfig {
+    backend?: 'mongodb' | 'jsonl';
+    mongoUrl?: string;
+    mongoDb?: string;
+    jsonlDir?: string;
+}
+
+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 StorageFactory<T = unknown> = (options?: T) => StorageAdapter;
+type AsyncStorageFactory<T = unknown> = (options: T) => Promise<StorageAdapter>;
+
+/**
+ * Creates a store with multiple persisted atoms
+ *
+ * @param entityId - Unique identifier for this store instance
+ * @param config - Array of atom configurations
+ * @param options - Store options including storage adapter
+ *
+ * @example
+ * ```typescript
+ * const config = [
+ *   { key: 'theme', defaultValue: '' },
+ *   { key: 'characters', defaultValue: [] },
+ * ] as const;
+ *
+ * const adapter = jsonlStorage({ dir: './sessions' });
+ *
+ * const store = createStore('novel-123', config, {
+ *   storage: adapter,
+ * });
+ * ```
+ */
+declare function createStore(entityId: string, config: AtomConfigs, options?: {
+    storage: StorageAdapter;
+    debounceMs?: number;
+}): Store;
+
+/**
+ * React Hook to use a store
+ *
+ * @example
+ * ```typescript
+ * const store = createStore('user-123', [
+ *   { key: 'name', defaultValue: '' },
+ *   { key: 'age', defaultValue: 0 },
+ * ], { storage });
+ *
+ * function UserProfile() {
+ *   const { name, age, setName, setAge, isLoading } = useStore(store);
+ *   // ...
+ * }
+ * ```
+ */
+declare function useStore(store: Store): UseStoreReturn;
+
+/**
+ * Creates a persisted atom with loading state tracking
+ */
+declare function createPersistedAtom<T>(config: AtomConfig<T>, entityId: string, storage: Storage, options?: {
+    immediate?: boolean;
+    debounceMs?: number;
+}): PersistedAtomWithLoading<T>;
+
+/**
+ * In-memory storage adapter for development and testing
+ */
+declare function memoryStorage(_options?: MemoryStorageOptions): StorageAdapter;
+declare const createMemoryStorage: StorageFactory<MemoryStorageOptions>;
+
+/**
+ * Transport Adapter Interface
+ *
+ * Abstracts the transport layer for remote storage operations.
+ * Can be implemented as HTTP, WebSocket, or other protocols.
+ */
+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
+ */
+declare class HttpTransport implements TransportAdapter {
+    get<T>(url: string): Promise<T>;
+    post<T, R>(url: string, body: T): Promise<R>;
+    delete(url: string): Promise<void>;
+}
+
+declare function createStorageFromTransport(transport: TransportAdapter, baseUrl: string): Storage;
+
+/**
+ * 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.
+ */
+
+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
+ */
+declare class RestStorageProtocol implements StorageHttpProtocol {
+    private baseUrl;
+    private entityId?;
+    private backendConfig;
+    constructor(baseUrl: string, entityId?: string | {
+        current?: string;
+    } | undefined, backendConfig?: BackendConfig);
+    private getEntityId;
+    private appendBackendParams;
+    private buildUrl;
+    buildGetUrl(key: string): string;
+    buildSetUrl(key: string): string;
+    buildDeleteUrl(key: string): string;
+    buildBatchGetUrl(): string;
+    buildBatchSetUrl(): string;
+    getBackendConfig(): BackendConfig;
+    withEntityId(entityId: string): RestStorageProtocol;
+}
+/**
+ * Create a storage that uses a specific protocol
+ */
+declare 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>;
+};
+
+/**
+ * Remote Storage Adapter
+ *
+ * Client-side adapter that calls the embedded sidecar server.
+ * Uses HttpTransport and RestStorageProtocol for HTTP operations.
+ */
+
+interface RemoteStorageOptions {
+    baseUrl?: string;
+    entityId?: string;
+    transport?: TransportAdapter;
+    protocol?: StorageHttpProtocol;
+    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 });
+ * ```
+ */
+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 };