transduck 0.2.5 → 0.4.0

package/src/react/provider.tsx

@@ -8,10 +8,14 @@ interface ReactState {
   language: string;
   sourceLang: string;
   endpoint: string;
+  projectName: string;
   cache: Map<string, string>;
   pluralCache: Map<string, Record<string, string>>;
   pendingStrings: Set<string>; // "text||context"
   pendingPlurals: Set<string>; // "one\x00other||context"
+  knownKeys: Set<string>;
+  knownPlurals: Set<string>;
+  isLanguageSwitch: boolean;
   triggerFetch: (() => void) | null;
 }
 
@@ -19,24 +23,62 @@ let _state: ReactState = {
   language: '',
   sourceLang: 'EN',
   endpoint: '/api/translations',
+  projectName: 'default',
   cache: new Map(),
   pluralCache: new Map(),
   pendingStrings: new Set(),
   pendingPlurals: new Set(),
+  knownKeys: new Set(),
+  knownPlurals: new Set(),
+  isLanguageSwitch: false,
   triggerFetch: null,
 };
 
 // --- Context for triggering child re-renders ---
-// The context value (a version counter) changes when translations are loaded.
+// The context value changes when translations are loaded or language switches.
 // Components that call useTransDuck() subscribe to this and re-render automatically.
-const TransDuckContext = createContext<number>(0);
+
+interface TransDuckContextValue {
+  version: number;
+  language: string;
+  setLanguage: (lang: string) => void;
+  isLoading: boolean;
+}
+
+const defaultContext: TransDuckContextValue = {
+  version: 0,
+  language: '',
+  setLanguage: () => {},
+  isLoading: false,
+};
+
+const TransDuckContext = createContext<TransDuckContextValue>(defaultContext);
 
 /**
- * Hook that subscribes to translation updates. Call this in any component
- * that uses t()/ait() to ensure it re-renders when translations are loaded.
+ * Hook that subscribes to translation updates and returns translation
+ * functions along with language state.
  */
-export function useTransDuck(): void {
-  useContext(TransDuckContext);
+export interface UseTransDuckReturn {
+  t: typeof t;
+  tPlural: typeof tPlural;
+  ait: typeof t;
+  aitPlural: typeof tPlural;
+  language: string;
+  setLanguage: (lang: string) => void;
+  isLoading: boolean;
+}
+
+export function useTransDuck(): UseTransDuckReturn {
+  const ctx = useContext(TransDuckContext);
+  return {
+    t,
+    tPlural,
+    ait,
+    aitPlural,
+    language: ctx.language,
+    setLanguage: ctx.setLanguage,
+    isLoading: ctx.isLoading,
+  };
 }
 
 export function _resetReactState(): void {
@@ -44,14 +86,22 @@ export function _resetReactState(): void {
     language: '',
     sourceLang: 'EN',
     endpoint: '/api/translations',
+    projectName: 'default',
     cache: new Map(),
     pluralCache: new Map(),
     pendingStrings: new Set(),
     pendingPlurals: new Set(),
+    knownKeys: new Set(),
+    knownPlurals: new Set(),
+    isLanguageSwitch: false,
     triggerFetch: null,
   };
 }
 
+export function _getReactState(): ReactState {
+  return _state;
+}
+
 function interpolateVars(text: string, vars?: Record<string, string | number> | null): string {
   if (!vars) return text;
   let result = text;
@@ -68,13 +118,14 @@ export function t(
   context?: string,
   vars?: Record<string, string | number>,
 ): string {
+  const key = `${sourceText}||${context ?? ''}`;
+  _state.knownKeys.add(key);
+
   // Same language — return source
   if (_state.language.toUpperCase() === _state.sourceLang.toUpperCase()) {
     return interpolateVars(sourceText, vars);
   }
 
-  const key = `${sourceText}||${context ?? ''}`;
-
   // Cache hit
   const cached = _state.cache.get(key);
   if (cached !== undefined) {
@@ -104,6 +155,10 @@ export function tPlural(
     vars = { ...opts.vars };
   }
 
+  const sourceKey = `${one}\x00${other}`;
+  const cacheKey = `${sourceKey}||${context ?? ''}`;
+  _state.knownPlurals.add(cacheKey);
+
   // Same language
   if (_state.language.toUpperCase() === _state.sourceLang.toUpperCase()) {
     const rules = new Intl.PluralRules(_state.sourceLang.toLowerCase());
@@ -111,9 +166,6 @@ export function tPlural(
     return interpolateVars(form, vars);
   }
 
-  const sourceKey = `${one}\x00${other}`;
-  const cacheKey = `${sourceKey}||${context ?? ''}`;
-
   // Cache hit
   const cachedForms = _state.pluralCache.get(cacheKey);
   if (cachedForms) {
@@ -191,21 +243,62 @@ export function TransDuckProvider({
   children,
 }: TransDuckProviderProps) {
   const [version, setVersion] = useState(0);
+  const [languageState, setLanguageState] = useState(language.toUpperCase());
+  const [isLoading, setIsLoading] = useState(false);
 
   // Update module-level state synchronously so t() works during first render
   _state.endpoint = endpoint;
   _state.sourceLang = sourceLang;
+  _state.projectName = projectName;
 
+  // Synchronous first-render initialization only.
+  // Subsequent language changes are handled by switchLanguage / useEffect prop sync.
   const upperLang = language.toUpperCase();
-  if (_state.language !== upperLang) {
+  if (!_state.language) {
     _state.language = upperLang;
-    _state.cache.clear();
-    _state.pluralCache.clear();
     loadFromLocalStorage(projectName, upperLang);
   }
 
+  const switchLanguage = useCallback((lang: string) => {
+    const upper = lang.toUpperCase();
+
+    // Same-language no-op
+    if (upper === _state.language) return;
+
+    // Update React state
+    setLanguageState(upper);
+
+    // Update module-level state synchronously
+    _state.language = upper;
+    _state.cache.clear();
+    _state.pluralCache.clear();
+
+    // Source-language guard: skip fetch, t() short-circuits
+    if (upper === _state.sourceLang.toUpperCase()) {
+      setVersion(v => v + 1);
+      return;
+    }
+
+    // Load cached translations from localStorage
+    loadFromLocalStorage(_state.projectName, upper);
+
+    // Mark as language switch and re-queue known keys
+    _state.isLanguageSwitch = true;
+    setIsLoading(true);
+    for (const key of _state.knownKeys) {
+      _state.pendingStrings.add(key);
+    }
+    for (const key of _state.knownPlurals) {
+      _state.pendingPlurals.add(key);
+    }
+
+    // Bump version to trigger re-render and useEffect flush
+    setVersion(v => v + 1);
+  }, []);
+
   // Set up trigger
   const doFetch = useCallback(async () => {
+    const fetchLanguage = _state.language;
     const stringsToFetch = new Set(_state.pendingStrings);
     const pluralsToFetch = new Set(_state.pendingPlurals);
     _state.pendingStrings.clear();
@@ -219,7 +312,13 @@ export function TransDuckProvider({
       if (_state.pluralCache.has(key)) pluralsToFetch.delete(key);
     }
 
-    if (stringsToFetch.size === 0 && pluralsToFetch.size === 0) return;
+    if (stringsToFetch.size === 0 && pluralsToFetch.size === 0) {
+      if (_state.isLanguageSwitch && _state.language === fetchLanguage) {
+        _state.isLanguageSwitch = false;
+        setIsLoading(false);
+      }
+      return;
+    }
 
     // Build request body
     const strings = Array.from(stringsToFetch).map(key => {
@@ -250,6 +349,9 @@ export function TransDuckProvider({
 
       const data = await response.json();
 
+      // Stale fetch protection: language changed while we were fetching
+      if (_state.language !== fetchLanguage) return;
+
       // Store translations
       if (data.translations) {
         for (const [key, value] of Object.entries(data.translations)) {
@@ -262,16 +364,31 @@ export function TransDuckProvider({
         }
       }
 
-      saveToLocalStorage(projectName, _state.language);
+      saveToLocalStorage(_state.projectName, _state.language);
       setVersion(v => v + 1);
     } catch (err) {
       console.warn('[transduck] Translation fetch error:', err);
+    } finally {
+      if (_state.isLanguageSwitch && _state.language === fetchLanguage) {
+        _state.isLanguageSwitch = false;
+        setIsLoading(false);
+      }
     }
-  }, [endpoint, projectName]);
+  }, [endpoint]);
 
   // Register trigger
   _state.triggerFetch = doFetch;
 
+  // Sync language prop changes — only when the prop itself changes
+  const prevPropRef = React.useRef(upperLang);
+  useEffect(() => {
+    const upper = language.toUpperCase();
+    if (upper !== prevPropRef.current) {
+      prevPropRef.current = upper;
+      switchLanguage(upper);
+    }
+  }, [language, switchLanguage]);
+
   // Flush pending after render
   useEffect(() => {
     if (_state.pendingStrings.size > 0 || _state.pendingPlurals.size > 0) {
@@ -279,8 +396,15 @@ export function TransDuckProvider({
     }
   });
 
+  const contextValue: TransDuckContextValue = {
+    version,
+    language: languageState,
+    setLanguage: switchLanguage,
+    isLoading,
+  };
+
   return (
-    <TransDuckContext.Provider value={version}>
+    <TransDuckContext.Provider value={contextValue}>
       {children}
     </TransDuckContext.Provider>
   );

package/src/storage.ts

@@ -1,79 +1,8 @@
-import { DuckDBInstance, DuckDBResultReader } from '@duckdb/node-api';
-import type { DuckDBConnection } from '@duckdb/node-api';
-
-const SCHEMA_V2 = `
-CREATE TABLE IF NOT EXISTS translations (
-    source_text          TEXT NOT NULL,
-    source_lang          TEXT NOT NULL,
-    target_lang          TEXT NOT NULL,
-    project_context_hash TEXT NOT NULL,
-    string_context_hash  TEXT NOT NULL,
-    plural_category      TEXT NOT NULL DEFAULT '',
-    translated_text      TEXT NOT NULL,
-    model                TEXT NOT NULL,
-    status               TEXT NOT NULL DEFAULT 'translated',
-    created_at           TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
-    PRIMARY KEY(source_text, source_lang, target_lang, project_context_hash, string_context_hash, plural_category)
-);
-`;
-
-const MIGRATION_V1_TO_V2 = `
-CREATE TABLE translations_v2 (
-    source_text          TEXT NOT NULL,
-    source_lang          TEXT NOT NULL,
-    target_lang          TEXT NOT NULL,
-    project_context_hash TEXT NOT NULL,
-    string_context_hash  TEXT NOT NULL,
-    plural_category      TEXT NOT NULL DEFAULT '',
-    translated_text      TEXT NOT NULL,
-    model                TEXT NOT NULL,
-    status               TEXT NOT NULL DEFAULT 'translated',
-    created_at           TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
-    PRIMARY KEY(source_text, source_lang, target_lang, project_context_hash, string_context_hash, plural_category)
-);
-INSERT INTO translations_v2
-    SELECT source_text, source_lang, target_lang, project_context_hash,
-           string_context_hash, '' as plural_category, translated_text,
-           model, status, created_at
-    FROM translations;
-DROP TABLE translations;
-ALTER TABLE translations_v2 RENAME TO translations;
-`;
-
-const CHECK_PLURAL_COLUMN = `
-SELECT column_name FROM information_schema.columns
-WHERE table_name = 'translations' AND column_name = 'plural_category'
-`;
-
-const LOOKUP_SQL = `
-SELECT translated_text FROM translations
-WHERE source_text = $1 AND source_lang = $2 AND target_lang = $3
-  AND project_context_hash = $4 AND string_context_hash = $5
-  AND plural_category = '' AND status = 'translated'
-`;
-
-const INSERT_SQL = `
-INSERT INTO translations
-    (source_text, source_lang, target_lang, project_context_hash,
-     string_context_hash, plural_category, translated_text, model, status)
-VALUES ($1, $2, $3, $4, $5, '', $6, $7, $8)
-ON CONFLICT DO NOTHING
-`;
-
-const LOOKUP_PLURAL_SQL = `
-SELECT plural_category, translated_text FROM translations
-WHERE source_text = $1 AND source_lang = $2 AND target_lang = $3
-  AND project_context_hash = $4 AND string_context_hash = $5
-  AND plural_category != '' AND status = 'translated'
-`;
-
-const INSERT_PLURAL_SQL = `
-INSERT INTO translations
-    (source_text, source_lang, target_lang, project_context_hash,
-     string_context_hash, plural_category, translated_text, model, status)
-VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
-ON CONFLICT DO NOTHING
-`;
+import { open, type Database, type RootDatabase } from 'lmdb';
+import { createHash } from 'crypto';
+
+// 1 GB default map size — plenty for translation caches
+const DEFAULT_MAP_SIZE = 1024 * 1024 * 1024;
 
 export interface LookupParams {
   sourceText: string;
@@ -96,134 +25,184 @@ export interface InsertPluralParams extends LookupParams {
   status: string;
 }
 
+interface StoredEntry {
+  source_text: string;
+  translated_text: string;
+  model: string;
+  status: string;
+  created_at: string;
+  project_context_hash: string;
+  string_context_hash: string;
+}
+
 interface Stats {
   totalTranslations: number;
   totalFailed: number;
   byLanguage: Record<string, number>;
 }
 
+function contentHash(sourceText: string, projectContextHash: string, stringContextHash: string): string {
+  return createHash('sha256')
+    .update(sourceText + '\x00' + projectContextHash + '\x00' + stringContextHash)
+    .digest('hex');
+}
+
+function makeKey(sourceLang: string, targetLang: string, chash: string, pluralCategory: string): string {
+  return `${sourceLang}|${targetLang}|${chash}|${pluralCategory}`;
+}
+
+function parseKey(key: string): { sourceLang: string; targetLang: string; contentHash: string; pluralCategory: string } {
+  const parts = key.split('|');
+  return {
+    sourceLang: parts[0],
+    targetLang: parts[1],
+    contentHash: parts[2],
+    pluralCategory: parts[3] ?? '',
+  };
+}
+
 export class TranslationStore {
   private dbPath: string;
-  private instance: DuckDBInstance | null = null;
-  private conn: DuckDBConnection | null = null;
+  private db: RootDatabase<StoredEntry, string> | null = null;
 
   constructor(dbPath: string) {
     this.dbPath = dbPath;
   }
 
-  private async getConn(): Promise<DuckDBConnection> {
-    if (!this.conn) throw new Error('Store not initialized');
-    return this.conn;
-  }
-
-  private convertRow(row: Record<string, unknown>): Record<string, unknown> {
-    const converted: Record<string, unknown> = {};
-    for (const [key, value] of Object.entries(row)) {
-      if (typeof value === 'bigint') {
-        converted[key] = Number(value);
-      } else {
-        converted[key] = value;
-      }
-    }
-    return converted;
-  }
-
-  async query(sql: string, params: string[] = []): Promise<Record<string, unknown>[]> {
-    const conn = await this.getConn();
-    let result;
-    if (params.length === 0) {
-      result = await conn.run(sql);
-    } else {
-      const stmt = await conn.prepare(sql);
-      for (let i = 0; i < params.length; i++) {
-        stmt.bindVarchar(i + 1, params[i]);
-      }
-      result = await stmt.run();
-    }
-    const reader = new DuckDBResultReader(result);
-    await reader.readAll();
-    return [...reader.getRowObjects()].map(row => this.convertRow(row));
-  }
-
   async initialize(): Promise<void> {
-    this.instance = await DuckDBInstance.create(this.dbPath);
-    this.conn = await this.instance.connect();
-
-    // Check if table exists
-    const tables = await this.query(
-      "SELECT table_name FROM information_schema.tables WHERE table_name = 'translations'"
-    );
-
-    if (tables.length === 0) {
-      // Fresh database — create v2 schema
-      await this.conn.run(SCHEMA_V2);
-      return;
-    }
+    this.db = open<StoredEntry, string>({
+      path: this.dbPath,
+      mapSize: DEFAULT_MAP_SIZE,
+      // Use msgpack (default) for efficient storage
+    });
+  }
 
-    // Table exists — check if it has plural_category (v2)
-    const hasPlural = await this.query(CHECK_PLURAL_COLUMN);
-    if (hasPlural.length === 0) {
-      // Migrate from v1 to v2
-      await this.conn.run(MIGRATION_V1_TO_V2);
-    }
+  private getDb(): RootDatabase<StoredEntry, string> {
+    if (!this.db) throw new Error('Store not initialized');
+    return this.db;
   }
 
   async lookup(params: LookupParams): Promise<string | null> {
-    const rows = await this.query(LOOKUP_SQL, [
-      params.sourceText, params.sourceLang, params.targetLang,
-      params.projectContextHash, params.stringContextHash,
-    ]);
-    return rows.length > 0 ? (rows[0].translated_text as string) : null;
+    const db = this.getDb();
+    const chash = contentHash(params.sourceText, params.projectContextHash, params.stringContextHash);
+    const key = makeKey(params.sourceLang, params.targetLang, chash, '');
+    const entry = db.get(key);
+    if (entry && entry.status === 'translated') {
+      return entry.translated_text;
+    }
+    return null;
   }
 
   async insert(params: InsertParams): Promise<void> {
-    await this.query(INSERT_SQL, [
-      params.sourceText, params.sourceLang, params.targetLang,
-      params.projectContextHash, params.stringContextHash,
-      params.translatedText, params.model, params.status,
-    ]);
+    const db = this.getDb();
+    const chash = contentHash(params.sourceText, params.projectContextHash, params.stringContextHash);
+    const key = makeKey(params.sourceLang, params.targetLang, chash, '');
+    // ON CONFLICT DO NOTHING — only insert if key doesn't exist
+    if (db.get(key) !== undefined) return;
+    await db.put(key, {
+      source_text: params.sourceText,
+      translated_text: params.translatedText,
+      model: params.model,
+      status: params.status,
+      created_at: new Date().toISOString(),
+      project_context_hash: params.projectContextHash,
+      string_context_hash: params.stringContextHash,
+    });
   }
 
   async lookupPlural(params: LookupParams): Promise<Record<string, string>> {
-    const rows = await this.query(LOOKUP_PLURAL_SQL, [
-      params.sourceText, params.sourceLang, params.targetLang,
-      params.projectContextHash, params.stringContextHash,
-    ]);
+    const db = this.getDb();
+    const chash = contentHash(params.sourceText, params.projectContextHash, params.stringContextHash);
+    const prefix = makeKey(params.sourceLang, params.targetLang, chash, '');
     const result: Record<string, string> = {};
-    for (const row of rows) {
-      result[row.plural_category as string] = row.translated_text as string;
+
+    for (const { key, value } of db.getRange({ start: prefix })) {
+      const keyStr = key as string;
+      if (!keyStr.startsWith(prefix)) break;
+      const parsed = parseKey(keyStr);
+      // Skip regular entries (empty plural_category)
+      if (!parsed.pluralCategory) continue;
+      if (value.status === 'translated') {
+        result[parsed.pluralCategory] = value.translated_text;
+      }
     }
     return result;
   }
 
   async insertPlural(params: InsertPluralParams): Promise<void> {
-    await this.query(INSERT_PLURAL_SQL, [
-      params.sourceText, params.sourceLang, params.targetLang,
-      params.projectContextHash, params.stringContextHash,
-      params.pluralCategory, params.translatedText, params.model, params.status,
-    ]);
+    const db = this.getDb();
+    const chash = contentHash(params.sourceText, params.projectContextHash, params.stringContextHash);
+    const key = makeKey(params.sourceLang, params.targetLang, chash, params.pluralCategory);
+    // ON CONFLICT DO NOTHING
+    if (db.get(key) !== undefined) return;
+    await db.put(key, {
+      source_text: params.sourceText,
+      translated_text: params.translatedText,
+      model: params.model,
+      status: params.status,
+      created_at: new Date().toISOString(),
+      project_context_hash: params.projectContextHash,
+      string_context_hash: params.stringContextHash,
+    });
   }
 
   async stats(): Promise<Stats> {
-    const totalRows = await this.query("SELECT count(*) as c FROM translations WHERE status = 'translated'");
-    const failedRows = await this.query("SELECT count(*) as c FROM translations WHERE status = 'failed'");
-    const langRows = await this.query(
-      "SELECT target_lang, count(*) as c FROM translations WHERE status = 'translated' GROUP BY target_lang"
-    );
+    const db = this.getDb();
+    let totalTranslations = 0;
+    let totalFailed = 0;
     const byLanguage: Record<string, number> = {};
-    for (const row of langRows) {
-      byLanguage[row.target_lang as string] = Number(row.c);
+
+    for (const { key, value } of db.getRange({})) {
+      const parsed = parseKey(key as string);
+      if (value.status === 'translated') {
+        totalTranslations++;
+        byLanguage[parsed.targetLang] = (byLanguage[parsed.targetLang] ?? 0) + 1;
+      } else if (value.status === 'failed') {
+        totalFailed++;
+      }
     }
-    return {
-      totalTranslations: Number(totalRows[0].c),
-      totalFailed: Number(failedRows[0].c),
-      byLanguage,
-    };
+
+    return { totalTranslations, totalFailed, byLanguage };
+  }
+
+  /**
+   * Count entries matching optional filters.
+   */
+  count(targetLang?: string, failedOnly?: boolean): number {
+    const db = this.getDb();
+    let n = 0;
+    for (const { key, value } of db.getRange({})) {
+      const parsed = parseKey(key as string);
+      if (targetLang && parsed.targetLang !== targetLang) continue;
+      if (failedOnly && value.status !== 'failed') continue;
+      n++;
+    }
+    return n;
+  }
+
+  /**
+   * Delete entries matching optional filters. Returns count deleted.
+   */
+  async clear(targetLang?: string, failedOnly?: boolean): Promise<number> {
+    const db = this.getDb();
+    const toDelete: string[] = [];
+    for (const { key, value } of db.getRange({})) {
+      const keyStr = key as string;
+      const parsed = parseKey(keyStr);
+      if (targetLang && parsed.targetLang !== targetLang) continue;
+      if (failedOnly && value.status !== 'failed') continue;
+      toDelete.push(keyStr);
+    }
+    for (const k of toDelete) {
+      await db.remove(k);
+    }
+    return toDelete.length;
   }
 
   close(): void {
-    // @duckdb/node-api handles cleanup via GC
-    this.conn = null;
-    this.instance = null;
+    if (this.db) {
+      this.db.close();
+      this.db = null;
+    }
   }
 }

package/tests/ait.test.ts

@@ -15,7 +15,7 @@ function makeConfig(tmpDir: string): TransduckConfig {
     projectContext: 'A test site',
     sourceLang: 'EN',
     targetLangs: ['DE', 'ES'],
-    storagePath: join(tmpDir, 'test.duckdb'),
+    storagePath: join(tmpDir, 'test.lmdb'),
     provider: 'openai',
     apiKeyEnv: 'OPENAI_API_KEY',
     tokenEnv: 'CLAUDE_CODE_OAUTH_TOKEN',

package/tests/backend.test.ts

@@ -8,7 +8,7 @@ function makeConfig(): TransduckConfig {
     projectContext: 'A travel site about Mallorca',
     sourceLang: 'EN',
     targetLangs: ['DE'],
-    storagePath: '/tmp/test.duckdb',
+    storagePath: '/tmp/test.lmdb',
     provider: 'openai',
     apiKeyEnv: 'OPENAI_API_KEY',
     tokenEnv: 'CLAUDE_CODE_OAUTH_TOKEN',