bff-store 0.1.0

package/src/types.ts

@@ -0,0 +1,76 @@
+import type { WritableAtom, Atom } from 'jotai';
+
+// ========================================
+// Atom Configuration Types
+// ========================================
+
+export type AtomType = 'string' | 'number' | 'boolean' | 'array' | 'object';
+
+export interface AtomConfig<T = unknown> {
+  key: string;
+  defaultValue: T;
+  type?: AtomType;
+  /** If true, save immediately without debounce */
+  immediate?: boolean;
+}
+
+export type AtomConfigs = readonly AtomConfig[];
+
+// ========================================
+// Store Types
+// ========================================
+
+export interface PersistedAtomWithLoading<T> {
+  atom: WritableAtom<T, [update: T | ((prev: T) => T)], void>;
+  loadingAtom: Atom<boolean>;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type StoreAtoms = Record<string, WritableAtom<any, [any], void>>;
+export type StoreLoadingAtoms = Record<string, Atom<boolean>>;
+
+export interface Store {
+  entityId: string;
+  config: AtomConfigs;
+  atoms: StoreAtoms;
+  loadingAtoms: StoreLoadingAtoms;
+}
+
+// ========================================
+// Hook Return Types
+// ========================================
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type UseStoreReturn = Record<string, any> & {
+  isLoading: boolean;
+};
+
+// ========================================
+// Storage Options
+// ========================================
+
+export interface StorageOptions {
+  debounceMs?: number;
+}
+
+export interface JsonlStorageOptions extends StorageOptions {
+  dir?: string;
+}
+
+export interface MongoStorageOptions extends StorageOptions {
+  url: string;
+  database?: string;
+}
+
+export interface MemoryStorageOptions extends StorageOptions {}
+
+// ========================================
+// Backend Config (shared between protocol and handlers)
+// ========================================
+
+export interface BackendConfig {
+  backend?: 'mongodb' | 'jsonl';
+  mongoUrl?: string;
+  mongoDb?: string;
+  jsonlDir?: string;
+}

package/src/useStore.ts

@@ -0,0 +1,83 @@
+import { useAtom } from 'jotai';
+import { useEffect, useState } from 'react';
+import { getDefaultStore } from 'jotai';
+import type { Store, UseStoreReturn } from './types';
+
+/**
+ * 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);
+ *   // ...
+ * }
+ * ```
+ */
+export function useStore(store: Store): UseStoreReturn {
+  const [isLoading, setIsLoading] = useState(true);
+
+  // Subscribe to loading states
+  useEffect(() => {
+    const storeInstance = getDefaultStore();
+    const loadingAtoms = Object.values(store.loadingAtoms);
+
+    if (loadingAtoms.length === 0) {
+      setIsLoading(false);
+      return;
+    }
+
+    const checkLoadingStatus = () => {
+      const loadingStates = loadingAtoms.map((atom) => storeInstance.get(atom));
+      const anyLoading = loadingStates.some((loading) => loading === true);
+      setIsLoading(anyLoading);
+    };
+
+    checkLoadingStatus();
+
+    const unsubscribers = loadingAtoms.map((atom) =>
+      storeInstance.sub(atom, checkLoadingStatus)
+    );
+
+    return () => {
+      unsubscribers.forEach((unsub) => unsub());
+    };
+  }, [store.loadingAtoms]);
+
+  // Build a dynamic result based on config
+  // Note: React hooks must be called unconditionally and in the same order
+  const result = buildStoreResult(store, isLoading);
+
+  return result;
+}
+
+/**
+ * Build store result object - calls useAtom for each atom
+ * This must be called unconditionally with the same atoms each render
+ */
+function buildStoreResult(store: Store, isLoading: boolean): UseStoreReturn {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const result: any = { isLoading };
+
+  // Iterate over store.config which is always stable
+  // Each config always has a corresponding atom in store.atoms (created together in createStore)
+  for (let i = 0; i < store.config.length; i++) {
+    const config = store.config[i];
+    const atom = store.atoms[config.key];
+    // atom always exists - created in createStore for every config
+    const [value, setter] = useAtom(atom);
+    result[config.key] = value;
+    result[`set${capitalize(config.key)}`] = setter;
+  }
+
+  return result;
+}
+
+function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}

package/tests/atomCreator.test.ts

@@ -0,0 +1,153 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { getDefaultStore } from 'jotai';
+import { createPersistedAtom } from '../src/atomCreator';
+import type { Storage } from '../src/storage/base';
+
+function createMockStorage(initialData: Record<string, unknown> = {}): Storage {
+  const data = new Map(Object.entries(initialData));
+  return {
+    async get<T>(key: string): Promise<T | null> {
+      return (data.get(key) as T) ?? null;
+    },
+    async set<T>(key: string, value: T): Promise<void> {
+      data.set(key, value);
+    },
+    async remove(key: string): Promise<void> {
+      data.delete(key);
+    },
+  };
+}
+
+describe('createPersistedAtom', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  describe('basic creation', () => {
+    it('should create atom with default value', () => {
+      const storage = createMockStorage();
+      const result = createPersistedAtom(
+        { key: 'theme', defaultValue: 'dark' },
+        storage
+      );
+
+      expect(result.atom).toBeDefined();
+      expect(result.loadingAtom).toBeDefined();
+    });
+
+    it('should have different atoms for different keys', () => {
+      const storage = createMockStorage();
+      const result1 = createPersistedAtom({ key: 'a', defaultValue: 1 }, storage);
+      const result2 = createPersistedAtom({ key: 'b', defaultValue: 2 }, storage);
+
+      expect(result1.atom).not.toBe(result2.atom);
+      expect(result1.loadingAtom).not.toBe(result2.loadingAtom);
+    });
+
+    it('should have loading atom starting as true', () => {
+      const storage = createMockStorage();
+      const { loadingAtom } = createPersistedAtom(
+        { key: 'theme', defaultValue: 'dark' },
+        storage
+      );
+
+      const store = getDefaultStore();
+      expect(store.get(loadingAtom)).toBe(true);
+    });
+  });
+
+  describe('atom read', () => {
+    it('should return default value via read', () => {
+      const storage = createMockStorage();
+      const { atom: persistedAtom } = createPersistedAtom(
+        { key: 'theme', defaultValue: 'dark' },
+        storage
+      );
+
+      const store = getDefaultStore();
+      expect(store.get(persistedAtom)).toBe('dark');
+    });
+  });
+
+  describe('atom write with immediate', () => {
+    it('should update value immediately in store', () => {
+      const storage = createMockStorage();
+      const { atom: persistedAtom } = createPersistedAtom(
+        { key: 'theme', defaultValue: 'dark', immediate: true },
+        storage
+      );
+
+      const store = getDefaultStore();
+      store.set(persistedAtom, 'light');
+      expect(store.get(persistedAtom)).toBe('light');
+    });
+  });
+
+  describe('atom write with debounce', () => {
+    it('should update value in store immediately', () => {
+      const storage = createMockStorage();
+      const { atom: persistedAtom } = createPersistedAtom(
+        { key: 'theme', defaultValue: 'dark', immediate: false },
+        storage
+      );
+
+      const store = getDefaultStore();
+      store.set(persistedAtom, 'light');
+      expect(store.get(persistedAtom)).toBe('light');
+    });
+  });
+
+  describe('function updates', () => {
+    it('should handle function updates correctly', () => {
+      const storage = createMockStorage();
+      const { atom: persistedAtom } = createPersistedAtom(
+        { key: 'count', defaultValue: 5 },
+        storage
+      );
+
+      const store = getDefaultStore();
+      expect(store.get(persistedAtom)).toBe(5);
+
+      store.set(persistedAtom, (prev) => (prev as number) + 1);
+      expect(store.get(persistedAtom)).toBe(6);
+    });
+  });
+
+  describe('type handling', () => {
+    it('should handle string type', () => {
+      const storage = createMockStorage();
+      const { atom: persistedAtom } = createPersistedAtom(
+        { key: 'name', defaultValue: '', type: 'string' },
+        storage
+      );
+      expect(persistedAtom).toBeDefined();
+    });
+
+    it('should handle number type', () => {
+      const storage = createMockStorage();
+      const { atom: persistedAtom } = createPersistedAtom(
+        { key: 'count', defaultValue: 0, type: 'number' },
+        storage
+      );
+      expect(persistedAtom).toBeDefined();
+    });
+
+    it('should handle array type', () => {
+      const storage = createMockStorage();
+      const { atom: persistedAtom } = createPersistedAtom(
+        { key: 'items', defaultValue: [], type: 'array' },
+        storage
+      );
+      expect(persistedAtom).toBeDefined();
+    });
+
+    it('should handle object type', () => {
+      const storage = createMockStorage();
+      const { atom: persistedAtom } = createPersistedAtom(
+        { key: 'data', defaultValue: {}, type: 'object' },
+        storage
+      );
+      expect(persistedAtom).toBeDefined();
+    });
+  });
+});

package/tests/createStore.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { getDefaultStore } from 'jotai';
+import { createStore } from '../src/createStore';
+import { memoryStorage } from '../src/storage/memory';
+
+describe('createStore', () => {
+  beforeEach(() => {
+    // Reset store between tests
+  });
+
+  describe('basic creation', () => {
+    it('should create store with single config', () => {
+      const adapter = memoryStorage();
+      const config = [{ key: 'theme', defaultValue: 'dark' }] as const;
+
+      const store = createStore('entity-1', config, { storage: adapter });
+
+      expect(store.entityId).toBe('entity-1');
+      expect(store.config).toBe(config);
+      expect(store.atoms.theme).toBeDefined();
+      expect(store.loadingAtoms.theme).toBeDefined();
+    });
+
+    it('should create store with multiple configs', () => {
+      const adapter = memoryStorage();
+      const config = [
+        { key: 'theme', defaultValue: 'dark' },
+        { key: 'name', defaultValue: '' },
+        { key: 'count', defaultValue: 0 },
+      ] as const;
+
+      const store = createStore('entity-1', config, { storage: adapter });
+
+      expect(store.atoms.theme).toBeDefined();
+      expect(store.atoms.name).toBeDefined();
+      expect(store.atoms.count).toBeDefined();
+      expect(store.loadingAtoms.theme).toBeDefined();
+      expect(store.loadingAtoms.name).toBeDefined();
+      expect(store.loadingAtoms.count).toBeDefined();
+    });
+
+    it('should throw when no storage provided', () => {
+      const config = [{ key: 'theme', defaultValue: 'dark' }] as const;
+
+      expect(() => {
+        createStore('entity-1', config);
+      }).toThrow('Storage adapter is required');
+    });
+
+    it('should use default debounceMs of 800', () => {
+      const adapter = memoryStorage();
+      const config = [{ key: 'theme', defaultValue: 'dark' }] as const;
+
+      const store = createStore('entity-1', config, { storage: adapter });
+
+      expect(store.atoms.theme).toBeDefined();
+    });
+
+    it('should accept custom debounceMs', () => {
+      const adapter = memoryStorage();
+      const config = [{ key: 'theme', defaultValue: 'dark' }] as const;
+
+      const store = createStore('entity-1', config, {
+        storage: adapter,
+        debounceMs: 500,
+      });
+
+      expect(store.atoms.theme).toBeDefined();
+    });
+  });
+
+  describe('entityId handling', () => {
+    it('should store entityId in returned store', () => {
+      const adapter = memoryStorage();
+      const config = [{ key: 'theme', defaultValue: 'dark' }] as const;
+
+      const store = createStore('novel-123', config, { storage: adapter });
+
+      expect(store.entityId).toBe('novel-123');
+    });
+  });
+
+  describe('immediate flag', () => {
+    it('should pass immediate flag to atom creator', () => {
+      const adapter = memoryStorage();
+      const config = [
+        { key: 'normal', defaultValue: '' },
+        { key: 'critical', defaultValue: '', immediate: true },
+      ] as const;
+
+      const store = createStore('entity-1', config, { storage: adapter });
+
+      expect(store.atoms.normal).toBeDefined();
+      expect(store.atoms.critical).toBeDefined();
+    });
+  });
+
+  describe('atom access via jotai store', () => {
+    it('should allow atom access through jotai store', () => {
+      const adapter = memoryStorage();
+      const config = [{ key: 'theme', defaultValue: 'dark' }] as const;
+
+      const store = createStore('entity-1', config, { storage: adapter });
+
+      const jotaiStore = getDefaultStore();
+
+      jotaiStore.set(store.atoms.theme, 'light');
+      expect(jotaiStore.get(store.atoms.theme)).toBe('light');
+
+      jotaiStore.set(store.atoms.theme, (prev) => (prev as string) + '-mode');
+      expect(jotaiStore.get(store.atoms.theme)).toBe('light-mode');
+    });
+  });
+
+  describe('loading atoms', () => {
+    it('should have loading atoms that start true', () => {
+      const adapter = memoryStorage();
+      const config = [{ key: 'theme', defaultValue: 'dark' }] as const;
+
+      const store = createStore('entity-1', config, { storage: adapter });
+
+      const jotaiStore = getDefaultStore();
+      expect(jotaiStore.get(store.loadingAtoms.theme)).toBe(true);
+    });
+  });
+});

package/tests/debouncer.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { createDebouncer, DebouncerMap } from '../src/debouncer';
+
+describe('Debouncer', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  it('should delay function execution', () => {
+    const debouncer = createDebouncer(100);
+    const fn = vi.fn();
+
+    debouncer.run(fn);
+    expect(fn).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should reset timer on subsequent calls', () => {
+    const debouncer = createDebouncer(100);
+    const fn = vi.fn();
+
+    debouncer.run(fn);
+    vi.advanceTimersByTime(50);
+    debouncer.run(fn);
+
+    expect(fn).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should cancel pending execution', () => {
+    const debouncer = createDebouncer(100);
+    const fn = vi.fn();
+
+    debouncer.run(fn);
+    debouncer.cancel();
+
+    vi.advanceTimersByTime(200);
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it('should expose ms property', () => {
+    const debouncer = createDebouncer(500);
+    expect(debouncer.ms).toBe(500);
+  });
+});
+
+describe('DebouncerMap', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  it('should create debouncer for new key', () => {
+    const map = new DebouncerMap(100);
+    const debouncer1 = map.getDebouncer('key1');
+    const debouncer2 = map.getDebouncer('key2');
+
+    expect(debouncer1).not.toBe(debouncer2);
+    expect(debouncer1.ms).toBe(100);
+  });
+
+  it('should return same debouncer for same key', () => {
+    const map = new DebouncerMap(100);
+    const debouncer1 = map.getDebouncer('key1');
+    const debouncer2 = map.getDebouncer('key1');
+
+    expect(debouncer1).toBe(debouncer2);
+  });
+
+  it('should debounce function calls per key', () => {
+    const map = new DebouncerMap(100);
+    const fn1 = vi.fn();
+    const fn2 = vi.fn();
+
+    map.debounce('key1', fn1);
+    map.debounce('key2', fn2);
+
+    vi.advanceTimersByTime(100);
+
+    expect(fn1).toHaveBeenCalledTimes(1);
+    expect(fn2).toHaveBeenCalledTimes(1);
+  });
+
+  it('should cancel debounced call for specific key', () => {
+    const map = new DebouncerMap(100);
+    const fn = vi.fn();
+
+    map.debounce('key1', fn);
+    map.cancel('key1');
+
+    vi.advanceTimersByTime(200);
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it('should cancel all pending debounced calls', () => {
+    const map = new DebouncerMap(100);
+    const fn1 = vi.fn();
+    const fn2 = vi.fn();
+
+    map.debounce('key1', fn1);
+    map.debounce('key2', fn2);
+    map.cancelAll();
+
+    vi.advanceTimersByTime(200);
+
+    expect(fn1).not.toHaveBeenCalled();
+    expect(fn2).not.toHaveBeenCalled();
+  });
+
+  it('should use custom ms per debounce call', () => {
+    const map = new DebouncerMap(100);
+    const fn = vi.fn();
+
+    map.debounce('key1', fn, 500);
+
+    vi.advanceTimersByTime(100);
+    expect(fn).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(400);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+});