@lingo.dev/compiler 0.3.6 → 0.3.7

package/README.md

@@ -330,6 +330,58 @@ LINGO_BUILD_MODE=cache-only npm run build
 2. **CI**: Generate real translations with `buildMode: "translate"` and real API keys
 3. **Production Build**: Use `buildMode: "cache-only"` (no API keys needed)
 
+## React Client API
+
+The compiler provides hooks and components for managing locale in your React components.
+
+### `useLingoContext()`
+
+Access the translation context to get the current locale and change it.
+
+**Returns:**
+- `locale` (string): Current locale code
+- `setLocale` (function): Change the locale
+- `translations` (object): Translation dictionary
+- `isLoading` (boolean): Whether translations are loading
+
+```tsx
+"use client";
+import { useLingoContext } from "@lingo.dev/compiler/react";
+
+export function LanguageSwitcher() {
+  const { locale, setLocale } = useLingoContext();
+
+  return (
+    <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+      <option value="en">English</option>
+      <option value="es">Español</option>
+      <option value="de">Deutsch</option>
+    </select>
+  );
+}
+```
+
+### `LocaleSwitcher` Component
+
+A pre-built dropdown component for switching locales (no hooks needed):
+
+```tsx
+"use client";
+import { LocaleSwitcher } from "@lingo.dev/compiler/react";
+
+export function Header() {
+  return (
+    <LocaleSwitcher
+      locales={[
+        { code: "en", label: "English" },
+        { code: "es", label: "Español" },
+        { code: "de", label: "Deutsch" },
+      ]}
+    />
+  );
+}
+```
+
 ## Custom Locale Resolvers
 
 Customize how locales are detected and persisted by providing custom resolver files:
@@ -395,9 +447,10 @@ The compiler is organized into several key modules:
 
 #### `src/metadata/` - Translation metadata management
 
-- **`manager.ts`** - CRUD operations for `.lingo/metadata.json`
-- Thread-safe metadata file operations with file locking
+- **`manager.ts`** - CRUD operations for LMDB metadata database
+- Uses LMDB for high-performance key-value storage with built-in concurrency
 - Manages translation entries with hash-based identifiers
+- Stores metadata in `.lingo/metadata-dev/` (development) or `.lingo/metadata-build/` (production)
 
 #### `src/translators/` - Translation provider abstraction
 

package/build/metadata/manager.cjs

@@ -1,131 +1,100 @@
 const require_rolldown_runtime = require('../_virtual/rolldown_runtime.cjs');
 const require_logger = require('../utils/logger.cjs');
-const require_timeout = require('../utils/timeout.cjs');
 const require_path_helpers = require('../utils/path-helpers.cjs');
-let fs_promises = require("fs/promises");
-fs_promises = require_rolldown_runtime.__toESM(fs_promises);
 let path = require("path");
 path = require_rolldown_runtime.__toESM(path);
 let fs = require("fs");
 fs = require_rolldown_runtime.__toESM(fs);
-let proper_lockfile = require("proper-lockfile");
-proper_lockfile = require_rolldown_runtime.__toESM(proper_lockfile);
+let lmdb = require("lmdb");
 
 //#region src/metadata/manager.ts
-function createEmptyMetadata() {
-	return {
-		entries: {},
-		stats: {
-			totalEntries: 0,
-			lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
-		}
-	};
-}
-function loadMetadata(path$2) {
-	return new MetadataManager(path$2).loadMetadata();
-}
-function cleanupExistingMetadata(metadataFilePath) {
-	require_logger.logger.debug(`Attempting to cleanup metadata file: ${metadataFilePath}`);
+const METADATA_DIR_DEV = "metadata-dev";
+const METADATA_DIR_BUILD = "metadata-build";
+/**
+* Opens an LMDB connection for a single operation.
+*
+* lmdb-js deduplicates open() calls to the same path (ref-counted at C++ level),
+* so this is cheap. Each open() also clears stale readers from terminated workers.
+*/
+function openDatabaseConnection(dbPath, noSync) {
 	try {
-		fs.default.unlinkSync(metadataFilePath);
-		require_logger.logger.info(`🧹 Cleaned up build metadata file: ${metadataFilePath}`);
+		fs.default.mkdirSync(dbPath, { recursive: true });
+		return (0, lmdb.open)({
+			path: dbPath,
+			compression: true,
+			noSync
+		});
 	} catch (error) {
-		if (error.code === "ENOENT") require_logger.logger.debug(`Metadata file already deleted or doesn't exist: ${metadataFilePath}`);
-		else require_logger.logger.warn(`Failed to cleanup metadata file: ${error.message}`);
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to open LMDB at ${dbPath}: ${message}`);
 	}
 }
 /**
-* Get the absolute path to the metadata file
-*
-* @param config - Config with sourceRoot, lingoDir, and environment
-* @returns Absolute path to metadata file
+* Closes the LMDB connection. Also prevents EBUSY/EPERM on Windows during
+* directory cleanup.
 */
-function getMetadataPath(config) {
-	const filename = config.environment === "development" ? "metadata-dev.json" : "metadata-build.json";
-	return path.default.join(require_path_helpers.getLingoDir(config), filename);
-}
-var MetadataManager = class {
-	constructor(filePath) {
-		this.filePath = filePath;
-	}
-	/**
-	* Load metadata from disk
-	* Creates empty metadata if file doesn't exist
-	* Times out after 15 seconds to prevent indefinite hangs
-	*/
-	async loadMetadata() {
-		try {
-			const content = await require_timeout.withTimeout(fs_promises.default.readFile(this.filePath, "utf-8"), require_timeout.DEFAULT_TIMEOUTS.METADATA, "Load metadata");
-			return JSON.parse(content);
-		} catch (error) {
-			if (error.code === "ENOENT") return createEmptyMetadata();
-			throw error;
-		}
+async function closeDatabaseConnection(db, dbPath) {
+	try {
+		await db.close();
+	} catch (e) {
+		require_logger.logger.debug(`Error closing database at ${dbPath}: ${e}`);
 	}
-	/**
-	* Save metadata to disk
-	* Times out after 15 seconds to prevent indefinite hangs
-	*/
-	async saveMetadata(metadata) {
-		await require_timeout.withTimeout(fs_promises.default.mkdir(path.default.dirname(this.filePath), { recursive: true }), require_timeout.DEFAULT_TIMEOUTS.FILE_IO, "Create metadata directory");
-		metadata.stats = {
-			totalEntries: Object.keys(metadata.entries).length,
-			lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
-		};
-		const dir = path.default.dirname(this.filePath);
-		const base = path.default.basename(this.filePath);
-		const tmpPath = path.default.join(dir, `.${base}.tmp-${process.pid}-${Date.now()}`);
-		const json = JSON.stringify(metadata, null, 2);
-		await require_timeout.withTimeout(fs_promises.default.writeFile(tmpPath, json, "utf-8"), require_timeout.DEFAULT_TIMEOUTS.METADATA, "Save metadata (tmp write)");
-		try {
-			await require_timeout.withTimeout(fs_promises.default.rename(tmpPath, this.filePath), require_timeout.DEFAULT_TIMEOUTS.METADATA, "Save metadata (atomic rename)");
-		} catch (error) {
-			if (error && typeof error === "object" && "code" in error && error.code === "EPERM") {
-				await require_timeout.withTimeout(fs_promises.default.writeFile(this.filePath, json, "utf-8"), require_timeout.DEFAULT_TIMEOUTS.METADATA, "Save metadata (EPERM fallback direct write)");
-				return;
-			}
-			throw error;
-		} finally {
-			await fs_promises.default.unlink(tmpPath).catch(() => {});
-		}
+}
+/**
+* Opens a database connection, runs the callback, and ensures the connection
+* is closed afterwards.
+*/
+async function runWithDbConnection(dbPath, noSync, fn) {
+	const db = openDatabaseConnection(dbPath, noSync);
+	try {
+		return fn(db);
+	} finally {
+		await closeDatabaseConnection(db, dbPath);
 	}
-	/**
-	* Thread-safe save operation that atomically updates metadata with new entries
-	* Uses file locking to prevent concurrent write corruption
-	*
-	* @param entries - Translation entries to add/update
-	* @returns The updated metadata schema
-	*/
-	async saveMetadataWithEntries(entries) {
-		const lockDir = path.default.dirname(this.filePath);
-		await fs_promises.default.mkdir(lockDir, { recursive: true });
-		try {
-			await fs_promises.default.access(this.filePath);
-		} catch {
-			await fs_promises.default.writeFile(this.filePath, JSON.stringify(createEmptyMetadata(), null, 2), "utf-8");
-		}
-		const release = await proper_lockfile.default.lock(this.filePath, {
-			retries: {
-				retries: 20,
-				minTimeout: 50,
-				maxTimeout: 2e3
-			},
-			stale: 5e3
+}
+function readEntriesFromDb(db) {
+	const entries = {};
+	for (const { key, value } of db.getRange()) entries[key] = value;
+	return entries;
+}
+async function loadMetadata(dbPath, noSync = false) {
+	return runWithDbConnection(dbPath, noSync, readEntriesFromDb);
+}
+/**
+* Persists translation entries to LMDB in a single atomic transaction.
+*/
+async function saveMetadata(dbPath, entries, noSync = false) {
+	return runWithDbConnection(dbPath, noSync, (db) => {
+		db.transactionSync(() => {
+			for (const entry of entries) db.putSync(entry.hash, entry);
 		});
-		try {
-			const currentMetadata = await this.loadMetadata();
-			for (const entry of entries) currentMetadata.entries[entry.hash] = entry;
-			await this.saveMetadata(currentMetadata);
-			return currentMetadata;
-		} finally {
-			await release();
+	});
+}
+function cleanupExistingMetadata(metadataDbPath) {
+	require_logger.logger.debug(`Cleaning up metadata database: ${metadataDbPath}`);
+	try {
+		fs.default.rmSync(metadataDbPath, {
+			recursive: true,
+			force: true
+		});
+		require_logger.logger.info(`🧹 Cleaned up metadata database: ${metadataDbPath}`);
+	} catch (error) {
+		const code = error instanceof Error && "code" in error ? error.code : void 0;
+		const message = error instanceof Error ? error.message : String(error);
+		if (code === "ENOENT") {
+			require_logger.logger.debug(`Metadata database already deleted or doesn't exist: ${metadataDbPath}`);
+			return;
 		}
+		require_logger.logger.warn(`Failed to cleanup metadata database: ${message}`);
 	}
-};
+}
+function getMetadataPath(config) {
+	const dirname = config.environment === "development" ? METADATA_DIR_DEV : METADATA_DIR_BUILD;
+	return path.default.join(require_path_helpers.getLingoDir(config), dirname);
+}
 
 //#endregion
-exports.MetadataManager = MetadataManager;
 exports.cleanupExistingMetadata = cleanupExistingMetadata;
-exports.createEmptyMetadata = createEmptyMetadata;
 exports.getMetadataPath = getMetadataPath;
-exports.loadMetadata = loadMetadata;
+exports.loadMetadata = loadMetadata;
+exports.saveMetadata = saveMetadata;

package/build/metadata/manager.mjs

@@ -1,123 +1,95 @@
 import { logger } from "../utils/logger.mjs";
-import { DEFAULT_TIMEOUTS, withTimeout } from "../utils/timeout.mjs";
 import { getLingoDir } from "../utils/path-helpers.mjs";
-import fs from "fs/promises";
 import path from "path";
-import fs$1 from "fs";
-import lockfile from "proper-lockfile";
+import fs from "fs";
+import { open } from "lmdb";
 
 //#region src/metadata/manager.ts
-function createEmptyMetadata() {
-	return {
-		entries: {},
-		stats: {
-			totalEntries: 0,
-			lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
-		}
-	};
-}
-function loadMetadata(path$1) {
-	return new MetadataManager(path$1).loadMetadata();
-}
-function cleanupExistingMetadata(metadataFilePath) {
-	logger.debug(`Attempting to cleanup metadata file: ${metadataFilePath}`);
+const METADATA_DIR_DEV = "metadata-dev";
+const METADATA_DIR_BUILD = "metadata-build";
+/**
+* Opens an LMDB connection for a single operation.
+*
+* lmdb-js deduplicates open() calls to the same path (ref-counted at C++ level),
+* so this is cheap. Each open() also clears stale readers from terminated workers.
+*/
+function openDatabaseConnection(dbPath, noSync) {
 	try {
-		fs$1.unlinkSync(metadataFilePath);
-		logger.info(`🧹 Cleaned up build metadata file: ${metadataFilePath}`);
+		fs.mkdirSync(dbPath, { recursive: true });
+		return open({
+			path: dbPath,
+			compression: true,
+			noSync
+		});
 	} catch (error) {
-		if (error.code === "ENOENT") logger.debug(`Metadata file already deleted or doesn't exist: ${metadataFilePath}`);
-		else logger.warn(`Failed to cleanup metadata file: ${error.message}`);
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to open LMDB at ${dbPath}: ${message}`);
 	}
 }
 /**
-* Get the absolute path to the metadata file
-*
-* @param config - Config with sourceRoot, lingoDir, and environment
-* @returns Absolute path to metadata file
+* Closes the LMDB connection. Also prevents EBUSY/EPERM on Windows during
+* directory cleanup.
 */
-function getMetadataPath(config) {
-	const filename = config.environment === "development" ? "metadata-dev.json" : "metadata-build.json";
-	return path.join(getLingoDir(config), filename);
-}
-var MetadataManager = class {
-	constructor(filePath) {
-		this.filePath = filePath;
-	}
-	/**
-	* Load metadata from disk
-	* Creates empty metadata if file doesn't exist
-	* Times out after 15 seconds to prevent indefinite hangs
-	*/
-	async loadMetadata() {
-		try {
-			const content = await withTimeout(fs.readFile(this.filePath, "utf-8"), DEFAULT_TIMEOUTS.METADATA, "Load metadata");
-			return JSON.parse(content);
-		} catch (error) {
-			if (error.code === "ENOENT") return createEmptyMetadata();
-			throw error;
-		}
+async function closeDatabaseConnection(db, dbPath) {
+	try {
+		await db.close();
+	} catch (e) {
+		logger.debug(`Error closing database at ${dbPath}: ${e}`);
 	}
-	/**
-	* Save metadata to disk
-	* Times out after 15 seconds to prevent indefinite hangs
-	*/
-	async saveMetadata(metadata) {
-		await withTimeout(fs.mkdir(path.dirname(this.filePath), { recursive: true }), DEFAULT_TIMEOUTS.FILE_IO, "Create metadata directory");
-		metadata.stats = {
-			totalEntries: Object.keys(metadata.entries).length,
-			lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
-		};
-		const dir = path.dirname(this.filePath);
-		const base = path.basename(this.filePath);
-		const tmpPath = path.join(dir, `.${base}.tmp-${process.pid}-${Date.now()}`);
-		const json = JSON.stringify(metadata, null, 2);
-		await withTimeout(fs.writeFile(tmpPath, json, "utf-8"), DEFAULT_TIMEOUTS.METADATA, "Save metadata (tmp write)");
-		try {
-			await withTimeout(fs.rename(tmpPath, this.filePath), DEFAULT_TIMEOUTS.METADATA, "Save metadata (atomic rename)");
-		} catch (error) {
-			if (error && typeof error === "object" && "code" in error && error.code === "EPERM") {
-				await withTimeout(fs.writeFile(this.filePath, json, "utf-8"), DEFAULT_TIMEOUTS.METADATA, "Save metadata (EPERM fallback direct write)");
-				return;
-			}
-			throw error;
-		} finally {
-			await fs.unlink(tmpPath).catch(() => {});
-		}
+}
+/**
+* Opens a database connection, runs the callback, and ensures the connection
+* is closed afterwards.
+*/
+async function runWithDbConnection(dbPath, noSync, fn) {
+	const db = openDatabaseConnection(dbPath, noSync);
+	try {
+		return fn(db);
+	} finally {
+		await closeDatabaseConnection(db, dbPath);
 	}
-	/**
-	* Thread-safe save operation that atomically updates metadata with new entries
-	* Uses file locking to prevent concurrent write corruption
-	*
-	* @param entries - Translation entries to add/update
-	* @returns The updated metadata schema
-	*/
-	async saveMetadataWithEntries(entries) {
-		const lockDir = path.dirname(this.filePath);
-		await fs.mkdir(lockDir, { recursive: true });
-		try {
-			await fs.access(this.filePath);
-		} catch {
-			await fs.writeFile(this.filePath, JSON.stringify(createEmptyMetadata(), null, 2), "utf-8");
-		}
-		const release = await lockfile.lock(this.filePath, {
-			retries: {
-				retries: 20,
-				minTimeout: 50,
-				maxTimeout: 2e3
-			},
-			stale: 5e3
+}
+function readEntriesFromDb(db) {
+	const entries = {};
+	for (const { key, value } of db.getRange()) entries[key] = value;
+	return entries;
+}
+async function loadMetadata(dbPath, noSync = false) {
+	return runWithDbConnection(dbPath, noSync, readEntriesFromDb);
+}
+/**
+* Persists translation entries to LMDB in a single atomic transaction.
+*/
+async function saveMetadata(dbPath, entries, noSync = false) {
+	return runWithDbConnection(dbPath, noSync, (db) => {
+		db.transactionSync(() => {
+			for (const entry of entries) db.putSync(entry.hash, entry);
 		});
-		try {
-			const currentMetadata = await this.loadMetadata();
-			for (const entry of entries) currentMetadata.entries[entry.hash] = entry;
-			await this.saveMetadata(currentMetadata);
-			return currentMetadata;
-		} finally {
-			await release();
+	});
+}
+function cleanupExistingMetadata(metadataDbPath) {
+	logger.debug(`Cleaning up metadata database: ${metadataDbPath}`);
+	try {
+		fs.rmSync(metadataDbPath, {
+			recursive: true,
+			force: true
+		});
+		logger.info(`🧹 Cleaned up metadata database: ${metadataDbPath}`);
+	} catch (error) {
+		const code = error instanceof Error && "code" in error ? error.code : void 0;
+		const message = error instanceof Error ? error.message : String(error);
+		if (code === "ENOENT") {
+			logger.debug(`Metadata database already deleted or doesn't exist: ${metadataDbPath}`);
+			return;
 		}
+		logger.warn(`Failed to cleanup metadata database: ${message}`);
 	}
-};
+}
+function getMetadataPath(config) {
+	const dirname = config.environment === "development" ? METADATA_DIR_DEV : METADATA_DIR_BUILD;
+	return path.join(getLingoDir(config), dirname);
+}
 
 //#endregion
-export { MetadataManager, cleanupExistingMetadata, createEmptyMetadata, getMetadataPath, loadMetadata };
+export { cleanupExistingMetadata, getMetadataPath, loadMetadata, saveMetadata };
 //# sourceMappingURL=manager.mjs.map

package/build/metadata/manager.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"manager.mjs","names":["path","error: any","filePath: string","fsPromises"],"sources":["../../src/metadata/manager.ts"],"sourcesContent":["import fsPromises from \"fs/promises\";\nimport fs from \"fs\";\nimport path from \"path\";\nimport lockfile from \"proper-lockfile\";\nimport type { MetadataSchema, PathConfig, TranslationEntry } from \"../types\";\nimport { DEFAULT_TIMEOUTS, withTimeout } from \"../utils/timeout\";\nimport { getLingoDir } from \"../utils/path-helpers\";\nimport { logger } from \"../utils/logger\";\n\nexport function createEmptyMetadata(): MetadataSchema {\n  return {\n    entries: {},\n    stats: {\n      totalEntries: 0,\n      lastUpdated: new Date().toISOString(),\n    },\n  };\n}\n\nexport function loadMetadata(path: string) {\n  return new MetadataManager(path).loadMetadata();\n}\n\nexport function cleanupExistingMetadata(metadataFilePath: string) {\n  // General cleanup. Delete metadata and stop the server if any was started.\n  logger.debug(`Attempting to cleanup metadata file: ${metadataFilePath}`);\n\n  try {\n    fs.unlinkSync(metadataFilePath);\n    logger.info(`🧹 Cleaned up build metadata file: ${metadataFilePath}`);\n  } catch (error: any) {\n    // Ignore if file doesn't exist\n    if (error.code === \"ENOENT\") {\n      logger.debug(\n        `Metadata file already deleted or doesn't exist: ${metadataFilePath}`,\n      );\n    } else {\n      logger.warn(`Failed to cleanup metadata file: ${error.message}`);\n    }\n  }\n}\n\n/**\n * Get the absolute path to the metadata file\n *\n * @param config - Config with sourceRoot, lingoDir, and environment\n * @returns Absolute path to metadata file\n */\nexport function getMetadataPath(config: PathConfig): string {\n  const filename =\n    // Similar to next keeping dev build separate, let's keep the build metadata clean of any dev mode additions\n    config.environment === \"development\"\n      ? \"metadata-dev.json\"\n      : \"metadata-build.json\";\n  return path.join(getLingoDir(config), filename);\n}\n\nexport class MetadataManager {\n  constructor(private readonly filePath: string) {}\n\n  /**\n   * Load metadata from disk\n   * Creates empty metadata if file doesn't exist\n   * Times out after 15 seconds to prevent indefinite hangs\n   */\n  async loadMetadata(): Promise<MetadataSchema> {\n    try {\n      const content = await withTimeout(\n        fsPromises.readFile(this.filePath, \"utf-8\"),\n        DEFAULT_TIMEOUTS.METADATA,\n        \"Load metadata\",\n      );\n      return JSON.parse(content) as MetadataSchema;\n    } catch (error: any) {\n      if (error.code === \"ENOENT\") {\n        // File doesn't exist, create new metadata\n        return createEmptyMetadata();\n      }\n      throw error;\n    }\n  }\n\n  /**\n   * Save metadata to disk\n   * Times out after 15 seconds to prevent indefinite hangs\n   */\n  private async saveMetadata(metadata: MetadataSchema): Promise<void> {\n    await withTimeout(\n      fsPromises.mkdir(path.dirname(this.filePath), { recursive: true }),\n      DEFAULT_TIMEOUTS.FILE_IO,\n      \"Create metadata directory\",\n    );\n\n    metadata.stats = {\n      totalEntries: Object.keys(metadata.entries).length,\n      lastUpdated: new Date().toISOString(),\n    };\n\n    // Per LLM writing to a file is not an atomic operation while rename is, so nobody should get partial content.\n    // Sounds reasonable.\n    const dir = path.dirname(this.filePath);\n    const base = path.basename(this.filePath);\n\n    // Keep temp file in the same directory to maximize chance that rename is atomic\n    const tmpPath = path.join(dir, `.${base}.tmp-${process.pid}-${Date.now()}`);\n\n    const json = JSON.stringify(metadata, null, 2);\n\n    await withTimeout(\n      fsPromises.writeFile(tmpPath, json, \"utf-8\"),\n      DEFAULT_TIMEOUTS.METADATA,\n      \"Save metadata (tmp write)\",\n    );\n\n    try {\n      // TODO (AleksandrSl 14/12/2025): LLM says that we may want to remove older file first for windows, but it seems lo work fine as is.\n      await withTimeout(\n        fsPromises.rename(tmpPath, this.filePath),\n        DEFAULT_TIMEOUTS.METADATA,\n        \"Save metadata (atomic rename)\",\n      );\n    } catch (error) {\n      // On Windows, rename() can fail with EPERM if something briefly holds the file.\n      // As a fallback, try writing directly to the destination (not atomic).\n      if (\n        error &&\n        typeof error === \"object\" &&\n        \"code\" in error &&\n        error.code === \"EPERM\"\n      ) {\n        await withTimeout(\n          fsPromises.writeFile(this.filePath, json, \"utf-8\"),\n          DEFAULT_TIMEOUTS.METADATA,\n          \"Save metadata (EPERM fallback direct write)\",\n        );\n        return;\n      }\n      throw error;\n    } finally {\n      // Best-effort cleanup if rename failed for some reason\n      await fsPromises.unlink(tmpPath).catch(() => {});\n    }\n  }\n\n  /**\n   * Thread-safe save operation that atomically updates metadata with new entries\n   * Uses file locking to prevent concurrent write corruption\n   *\n   * @param entries - Translation entries to add/update\n   * @returns The updated metadata schema\n   */\n  async saveMetadataWithEntries(\n    entries: TranslationEntry[],\n  ): Promise<MetadataSchema> {\n    const lockDir = path.dirname(this.filePath);\n\n    await fsPromises.mkdir(lockDir, { recursive: true });\n\n    try {\n      await fsPromises.access(this.filePath);\n    } catch {\n      await fsPromises.writeFile(\n        this.filePath,\n        JSON.stringify(createEmptyMetadata(), null, 2),\n        \"utf-8\",\n      );\n    }\n\n    const release = await lockfile.lock(this.filePath, {\n      retries: {\n        retries: 20,\n        minTimeout: 50,\n        maxTimeout: 2000,\n      },\n      stale: 5000,\n    });\n\n    try {\n      // Re-load metadata inside lock to get latest state\n      const currentMetadata = await this.loadMetadata();\n      for (const entry of entries) {\n        currentMetadata.entries[entry.hash] = entry;\n      }\n      await this.saveMetadata(currentMetadata);\n      return currentMetadata;\n    } finally {\n      await release();\n    }\n  }\n}\n"],"mappings":";;;;;;;;;AASA,SAAgB,sBAAsC;AACpD,QAAO;EACL,SAAS,EAAE;EACX,OAAO;GACL,cAAc;GACd,8BAAa,IAAI,MAAM,EAAC,aAAa;GACtC;EACF;;AAGH,SAAgB,aAAa,QAAc;AACzC,QAAO,IAAI,gBAAgBA,OAAK,CAAC,cAAc;;AAGjD,SAAgB,wBAAwB,kBAA0B;AAEhE,QAAO,MAAM,wCAAwC,mBAAmB;AAExE,KAAI;AACF,OAAG,WAAW,iBAAiB;AAC/B,SAAO,KAAK,sCAAsC,mBAAmB;UAC9DC,OAAY;AAEnB,MAAI,MAAM,SAAS,SACjB,QAAO,MACL,mDAAmD,mBACpD;MAED,QAAO,KAAK,oCAAoC,MAAM,UAAU;;;;;;;;;AAWtE,SAAgB,gBAAgB,QAA4B;CAC1D,MAAM,WAEJ,OAAO,gBAAgB,gBACnB,sBACA;AACN,QAAO,KAAK,KAAK,YAAY,OAAO,EAAE,SAAS;;AAGjD,IAAa,kBAAb,MAA6B;CAC3B,YAAY,AAAiBC,UAAkB;EAAlB;;;;;;;CAO7B,MAAM,eAAwC;AAC5C,MAAI;GACF,MAAM,UAAU,MAAM,YACpBC,GAAW,SAAS,KAAK,UAAU,QAAQ,EAC3C,iBAAiB,UACjB,gBACD;AACD,UAAO,KAAK,MAAM,QAAQ;WACnBF,OAAY;AACnB,OAAI,MAAM,SAAS,SAEjB,QAAO,qBAAqB;AAE9B,SAAM;;;;;;;CAQV,MAAc,aAAa,UAAyC;AAClE,QAAM,YACJE,GAAW,MAAM,KAAK,QAAQ,KAAK,SAAS,EAAE,EAAE,WAAW,MAAM,CAAC,EAClE,iBAAiB,SACjB,4BACD;AAED,WAAS,QAAQ;GACf,cAAc,OAAO,KAAK,SAAS,QAAQ,CAAC;GAC5C,8BAAa,IAAI,MAAM,EAAC,aAAa;GACtC;EAID,MAAM,MAAM,KAAK,QAAQ,KAAK,SAAS;EACvC,MAAM,OAAO,KAAK,SAAS,KAAK,SAAS;EAGzC,MAAM,UAAU,KAAK,KAAK,KAAK,IAAI,KAAK,OAAO,QAAQ,IAAI,GAAG,KAAK,KAAK,GAAG;EAE3E,MAAM,OAAO,KAAK,UAAU,UAAU,MAAM,EAAE;AAE9C,QAAM,YACJA,GAAW,UAAU,SAAS,MAAM,QAAQ,EAC5C,iBAAiB,UACjB,4BACD;AAED,MAAI;AAEF,SAAM,YACJA,GAAW,OAAO,SAAS,KAAK,SAAS,EACzC,iBAAiB,UACjB,gCACD;WACM,OAAO;AAGd,OACE,SACA,OAAO,UAAU,YACjB,UAAU,SACV,MAAM,SAAS,SACf;AACA,UAAM,YACJA,GAAW,UAAU,KAAK,UAAU,MAAM,QAAQ,EAClD,iBAAiB,UACjB,8CACD;AACD;;AAEF,SAAM;YACE;AAER,SAAMA,GAAW,OAAO,QAAQ,CAAC,YAAY,GAAG;;;;;;;;;;CAWpD,MAAM,wBACJ,SACyB;EACzB,MAAM,UAAU,KAAK,QAAQ,KAAK,SAAS;AAE3C,QAAMA,GAAW,MAAM,SAAS,EAAE,WAAW,MAAM,CAAC;AAEpD,MAAI;AACF,SAAMA,GAAW,OAAO,KAAK,SAAS;UAChC;AACN,SAAMA,GAAW,UACf,KAAK,UACL,KAAK,UAAU,qBAAqB,EAAE,MAAM,EAAE,EAC9C,QACD;;EAGH,MAAM,UAAU,MAAM,SAAS,KAAK,KAAK,UAAU;GACjD,SAAS;IACP,SAAS;IACT,YAAY;IACZ,YAAY;IACb;GACD,OAAO;GACR,CAAC;AAEF,MAAI;GAEF,MAAM,kBAAkB,MAAM,KAAK,cAAc;AACjD,QAAK,MAAM,SAAS,QAClB,iBAAgB,QAAQ,MAAM,QAAQ;AAExC,SAAM,KAAK,aAAa,gBAAgB;AACxC,UAAO;YACC;AACR,SAAM,SAAS"}
+{"version":3,"file":"manager.mjs","names":["entries: MetadataSchema"],"sources":["../../src/metadata/manager.ts"],"sourcesContent":["import fs from \"fs\";\nimport path from \"path\";\nimport { open, type RootDatabase } from \"lmdb\";\nimport type { MetadataSchema, PathConfig, TranslationEntry } from \"../types\";\nimport { getLingoDir } from \"../utils/path-helpers\";\nimport { logger } from \"../utils/logger\";\n\nconst METADATA_DIR_DEV = \"metadata-dev\";\nconst METADATA_DIR_BUILD = \"metadata-build\";\n\n/**\n * Opens an LMDB connection for a single operation.\n *\n * lmdb-js deduplicates open() calls to the same path (ref-counted at C++ level),\n * so this is cheap. Each open() also clears stale readers from terminated workers.\n */\nfunction openDatabaseConnection(dbPath: string, noSync: boolean): RootDatabase {\n  try {\n    fs.mkdirSync(dbPath, { recursive: true });\n    return open({\n      path: dbPath,\n      compression: true,\n      noSync,\n    });\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error);\n    throw new Error(`Failed to open LMDB at ${dbPath}: ${message}`);\n  }\n}\n\n/**\n * Closes the LMDB connection. Also prevents EBUSY/EPERM on Windows during\n * directory cleanup.\n */\nasync function closeDatabaseConnection(\n  db: RootDatabase,\n  dbPath: string,\n): Promise<void> {\n  try {\n    await db.close();\n  } catch (e) {\n    logger.debug(`Error closing database at ${dbPath}: ${e}`);\n  }\n}\n\n/**\n * Opens a database connection, runs the callback, and ensures the connection\n * is closed afterwards.\n */\nasync function runWithDbConnection<T>(\n  dbPath: string,\n  noSync: boolean,\n  fn: (db: RootDatabase) => T,\n): Promise<T> {\n  const db = openDatabaseConnection(dbPath, noSync);\n  try {\n    return fn(db);\n  } finally {\n    await closeDatabaseConnection(db, dbPath);\n  }\n}\n\nfunction readEntriesFromDb(db: RootDatabase): MetadataSchema {\n  const entries: MetadataSchema = {};\n\n  for (const { key, value } of db.getRange()) {\n    entries[key as string] = value as TranslationEntry;\n  }\n\n  return entries;\n}\n\nexport async function loadMetadata(\n  dbPath: string,\n  noSync = false,\n): Promise<MetadataSchema> {\n  return runWithDbConnection(dbPath, noSync, readEntriesFromDb);\n}\n\n/**\n * Persists translation entries to LMDB in a single atomic transaction.\n */\nexport async function saveMetadata(\n  dbPath: string,\n  entries: TranslationEntry[],\n  noSync = false,\n): Promise<void> {\n  return runWithDbConnection(dbPath, noSync, (db) => {\n    db.transactionSync(() => {\n      for (const entry of entries) {\n        db.putSync(entry.hash, entry);\n      }\n    });\n  });\n}\n\nexport function cleanupExistingMetadata(metadataDbPath: string): void {\n  logger.debug(`Cleaning up metadata database: ${metadataDbPath}`);\n\n  try {\n    fs.rmSync(metadataDbPath, { recursive: true, force: true });\n    logger.info(`🧹 Cleaned up metadata database: ${metadataDbPath}`);\n  } catch (error) {\n    const code =\n      error instanceof Error && \"code\" in error\n        ? (error as NodeJS.ErrnoException).code\n        : undefined;\n    const message = error instanceof Error ? error.message : String(error);\n\n    if (code === \"ENOENT\") {\n      logger.debug(\n        `Metadata database already deleted or doesn't exist: ${metadataDbPath}`,\n      );\n      return;\n    }\n\n    logger.warn(`Failed to cleanup metadata database: ${message}`);\n  }\n}\n\nexport function getMetadataPath(config: PathConfig): string {\n  const dirname =\n    config.environment === \"development\"\n      ? METADATA_DIR_DEV\n      : METADATA_DIR_BUILD;\n  return path.join(getLingoDir(config), dirname);\n}\n"],"mappings":";;;;;;;AAOA,MAAM,mBAAmB;AACzB,MAAM,qBAAqB;;;;;;;AAQ3B,SAAS,uBAAuB,QAAgB,QAA+B;AAC7E,KAAI;AACF,KAAG,UAAU,QAAQ,EAAE,WAAW,MAAM,CAAC;AACzC,SAAO,KAAK;GACV,MAAM;GACN,aAAa;GACb;GACD,CAAC;UACK,OAAO;EACd,MAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;AACtE,QAAM,IAAI,MAAM,0BAA0B,OAAO,IAAI,UAAU;;;;;;;AAQnE,eAAe,wBACb,IACA,QACe;AACf,KAAI;AACF,QAAM,GAAG,OAAO;UACT,GAAG;AACV,SAAO,MAAM,6BAA6B,OAAO,IAAI,IAAI;;;;;;;AAQ7D,eAAe,oBACb,QACA,QACA,IACY;CACZ,MAAM,KAAK,uBAAuB,QAAQ,OAAO;AACjD,KAAI;AACF,SAAO,GAAG,GAAG;WACL;AACR,QAAM,wBAAwB,IAAI,OAAO;;;AAI7C,SAAS,kBAAkB,IAAkC;CAC3D,MAAMA,UAA0B,EAAE;AAElC,MAAK,MAAM,EAAE,KAAK,WAAW,GAAG,UAAU,CACxC,SAAQ,OAAiB;AAG3B,QAAO;;AAGT,eAAsB,aACpB,QACA,SAAS,OACgB;AACzB,QAAO,oBAAoB,QAAQ,QAAQ,kBAAkB;;;;;AAM/D,eAAsB,aACpB,QACA,SACA,SAAS,OACM;AACf,QAAO,oBAAoB,QAAQ,SAAS,OAAO;AACjD,KAAG,sBAAsB;AACvB,QAAK,MAAM,SAAS,QAClB,IAAG,QAAQ,MAAM,MAAM,MAAM;IAE/B;GACF;;AAGJ,SAAgB,wBAAwB,gBAA8B;AACpE,QAAO,MAAM,kCAAkC,iBAAiB;AAEhE,KAAI;AACF,KAAG,OAAO,gBAAgB;GAAE,WAAW;GAAM,OAAO;GAAM,CAAC;AAC3D,SAAO,KAAK,oCAAoC,iBAAiB;UAC1D,OAAO;EACd,MAAM,OACJ,iBAAiB,SAAS,UAAU,QAC/B,MAAgC,OACjC;EACN,MAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;AAEtE,MAAI,SAAS,UAAU;AACrB,UAAO,MACL,uDAAuD,iBACxD;AACD;;AAGF,SAAO,KAAK,wCAAwC,UAAU;;;AAIlE,SAAgB,gBAAgB,QAA4B;CAC1D,MAAM,UACJ,OAAO,gBAAgB,gBACnB,mBACA;AACN,QAAO,KAAK,KAAK,YAAY,OAAO,EAAE,QAAQ"}

package/build/plugin/build-translator.cjs

@@ -28,15 +28,15 @@ async function processBuildTranslations(options) {
 	const { config, publicOutputPath, metadataFilePath } = options;
 	const buildMode = process.env.LINGO_BUILD_MODE || config.buildMode;
 	require_logger.logger.info(`🌍 Build mode: ${buildMode}`);
-	const metadata = await require_manager.loadMetadata(metadataFilePath);
-	if (!metadata || Object.keys(metadata.entries).length === 0) {
+	const metadata = await require_manager.loadMetadata(metadataFilePath, true);
+	if (!metadata || Object.keys(metadata).length === 0) {
 		require_logger.logger.info("No translations to process (metadata is empty)");
 		return {
 			success: true,
 			stats: {}
 		};
 	}
-	const totalEntries = Object.keys(metadata.entries).length;
+	const totalEntries = Object.keys(metadata).length;
 	require_logger.logger.info(`📊 Found ${totalEntries} translatable entries`);
 	const cache = require_cache_factory.createCache(config);
 	if (buildMode === "cache-only") {
@@ -107,7 +107,7 @@ async function processBuildTranslations(options) {
 * @throws Error if cache is incomplete or missing
 */
 async function validateCache(config, metadata, cache) {
-	const allHashes = Object.keys(metadata.entries);
+	const allHashes = Object.keys(metadata);
 	const missingLocales = [];
 	const incompleteLocales = [];
 	const allLocales = config.pluralization?.enabled === true ? [config.sourceLocale, ...config.targetLocales] : config.targetLocales;
@@ -138,7 +138,7 @@ async function validateCache(config, metadata, cache) {
 	}
 }
 function buildCacheStats(config, metadata) {
-	const totalEntries = Object.keys(metadata.entries).length;
+	const totalEntries = Object.keys(metadata).length;
 	const stats = {};
 	const allLocales = config.pluralization?.enabled === true ? [config.sourceLocale, ...config.targetLocales] : config.targetLocales;
 	for (const locale of allLocales) stats[locale] = {
@@ -151,7 +151,7 @@ function buildCacheStats(config, metadata) {
 async function copyStaticFiles(config, publicOutputPath, metadata, cache) {
 	require_logger.logger.info(`📦 Generating static translation files in ${publicOutputPath}`);
 	await fs_promises.default.mkdir(publicOutputPath, { recursive: true });
-	const usedHashes = new Set(Object.keys(metadata.entries));
+	const usedHashes = new Set(Object.keys(metadata));
 	require_logger.logger.info(`📊 Filtering translations to ${usedHashes.size} used hash(es)`);
 	const allLocales = config.pluralization?.enabled === true ? [config.sourceLocale, ...config.targetLocales] : config.targetLocales;
 	for (const locale of allLocales) {

package/build/plugin/build-translator.mjs

@@ -25,15 +25,15 @@ async function processBuildTranslations(options) {
 	const { config, publicOutputPath, metadataFilePath } = options;
 	const buildMode = process.env.LINGO_BUILD_MODE || config.buildMode;
 	logger.info(`🌍 Build mode: ${buildMode}`);
-	const metadata = await loadMetadata(metadataFilePath);
-	if (!metadata || Object.keys(metadata.entries).length === 0) {
+	const metadata = await loadMetadata(metadataFilePath, true);
+	if (!metadata || Object.keys(metadata).length === 0) {
 		logger.info("No translations to process (metadata is empty)");
 		return {
 			success: true,
 			stats: {}
 		};
 	}
-	const totalEntries = Object.keys(metadata.entries).length;
+	const totalEntries = Object.keys(metadata).length;
 	logger.info(`📊 Found ${totalEntries} translatable entries`);
 	const cache = createCache(config);
 	if (buildMode === "cache-only") {
@@ -104,7 +104,7 @@ async function processBuildTranslations(options) {
 * @throws Error if cache is incomplete or missing
 */
 async function validateCache(config, metadata, cache) {
-	const allHashes = Object.keys(metadata.entries);
+	const allHashes = Object.keys(metadata);
 	const missingLocales = [];
 	const incompleteLocales = [];
 	const allLocales = config.pluralization?.enabled === true ? [config.sourceLocale, ...config.targetLocales] : config.targetLocales;
@@ -135,7 +135,7 @@ async function validateCache(config, metadata, cache) {
 	}
 }
 function buildCacheStats(config, metadata) {
-	const totalEntries = Object.keys(metadata.entries).length;
+	const totalEntries = Object.keys(metadata).length;
 	const stats = {};
 	const allLocales = config.pluralization?.enabled === true ? [config.sourceLocale, ...config.targetLocales] : config.targetLocales;
 	for (const locale of allLocales) stats[locale] = {
@@ -148,7 +148,7 @@ function buildCacheStats(config, metadata) {
 async function copyStaticFiles(config, publicOutputPath, metadata, cache) {
 	logger.info(`📦 Generating static translation files in ${publicOutputPath}`);
 	await fs.mkdir(publicOutputPath, { recursive: true });
-	const usedHashes = new Set(Object.keys(metadata.entries));
+	const usedHashes = new Set(Object.keys(metadata));
 	logger.info(`📊 Filtering translations to ${usedHashes.size} used hash(es)`);
 	const allLocales = config.pluralization?.enabled === true ? [config.sourceLocale, ...config.targetLocales] : config.targetLocales;
 	for (const locale of allLocales) {