embedded-raptor 2.1.1 → 2.1.3

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Christoffer Artmann <artgaard@gmail.com>
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 Christoffer Artmann <artgaard@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -109,10 +109,19 @@ Create a new embedding engine.
 
 ```typescript
 const engine = new EmbeddingEngine({
-  storePath: './database.raptor' // Path to storage file
+  storePath: './database.raptor', // Path to storage file
+  embeddingCacheSize: 100 // Optional: cache up to 100 text-to-embedding mappings
 })
 ```
 
+**Options:**
+
+- `storePath` - Path to the database file (required)
+- `cacheDir` - Directory to cache downloaded models (default: `./.cache/models`)
+- `readOnly` - Open database in read-only mode (default: `false`)
+- `embeddingCacheSize` - Size of the LRU cache for text-to-embedding lookups
+  (default: `0` = disabled)
+
 #### `store(key, text)`
 
 Store a single text entry with auto-generated embedding.
@@ -221,6 +230,9 @@ dimensions)
 - **Memory efficient**: Reads file in 64KB chunks, handles large databases
 - **Fast search**: Cosine similarity comparison across all embeddings
 - **Deduplication**: Latest entry automatically used for duplicate keys
+- **Embedding cache**: Use `embeddingCacheSize` to cache text-to-embedding
+  mappings and avoid regenerating embeddings for repeated text inputs (~1.7KB
+  per cached entry)
 
 ## Contributing
 

package/dist/cli.cjs

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-const require_engine = require('./engine-DKn_V99U.cjs');
+const require_engine = require('./engine-DZWQXLVm.cjs');
 let node_path = require("node:path");
 node_path = require_engine.__toESM(node_path);
-let node_fs = require("node:fs");
-node_fs = require_engine.__toESM(node_fs);
 let cleye = require("cleye");
 cleye = require_engine.__toESM(cleye);
+let node_fs = require("node:fs");
+node_fs = require_engine.__toESM(node_fs);
 let node_url = require("node:url");
 node_url = require_engine.__toESM(node_url);
 

package/dist/cli.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { i as opType, n as Wal, r as fileExtensions, t as EmbeddingEngine } from "./engine-Zax2PJSW.mjs";
+import { o as fileExtensions, r as Wal, s as opType, t as EmbeddingEngine } from "./engine-CjiGgePO.mjs";
 import { dirname, resolve } from "node:path";
-import { readFileSync } from "node:fs";
 import { cli, command } from "cleye";
+import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
 //#region src/commands/flags.ts

package/dist/{engine-Zax2PJSW.mjs → engine-CjiGgePO.mjs}

@@ -2,7 +2,6 @@ import { LlamaLogLevel, getLlama, resolveModelFile } from "node-llama-cpp";
 import invariant from "tiny-invariant";
 import { copyFile, mkdir, open, rm, stat } from "node:fs/promises";
 import { dirname } from "node:path";
-import { constants } from "node:fs";
 
 //#region src/storage-engine/constants.ts
 /**
@@ -163,7 +162,7 @@ function readKeyFromBuffer(data, startOffset = 0) {
 function serializeHeader(dimension) {
 	const buffer = new Uint8Array(headerSize);
 	const view = new DataView(buffer.buffer);
-	view.setUint32(headerOffsets.magic, headerMagic, true);
+	view.setUint32(headerOffsets.magic, headerMagic, false);
 	view.setUint16(headerOffsets.version, headerVersionV2, true);
 	view.setUint32(headerOffsets.dimension, dimension, true);
 	return buffer;
@@ -174,7 +173,7 @@ function serializeHeader(dimension) {
 function deserializeHeader(data) {
 	if (data.length < headerSize) return null;
 	const view = new DataView(data.buffer, data.byteOffset);
-	if (view.getUint32(headerOffsets.magic, true) !== headerMagic) return null;
+	if (view.getUint32(headerOffsets.magic, false) !== headerMagic) return null;
 	return {
 		version: view.getUint16(headerOffsets.version, true),
 		dimension: view.getUint32(headerOffsets.dimension, true)
@@ -265,19 +264,106 @@ function deserializeWalEntry(data, startOffset = 0) {
 	};
 }
 
+//#endregion
+//#region src/storage-engine/file-lock.ts
+const defaultLockTimeout = 1e4;
+const retryInterval = 100;
+/**
+* Exclusive file lock for preventing multiple processes from
+* accessing the same database simultaneously.
+*
+* Uses atomic file creation with O_EXCL flag to ensure only one
+* process can acquire the lock at a time.
+*/
+var FileLock = class {
+	locked = false;
+	filePath;
+	timeoutMs;
+	constructor(filePath, timeoutMs = defaultLockTimeout) {
+		this.filePath = filePath;
+		this.timeoutMs = timeoutMs;
+	}
+	/**
+	* Acquire an exclusive lock on the file.
+	* Creates the lock file if it doesn't exist.
+	* Retries for up to timeoutMs before throwing DatabaseLockedError.
+	*/
+	async acquire() {
+		if (this.locked) throw new Error("Lock already acquired");
+		await mkdir(dirname(this.filePath), { recursive: true });
+		const startTime = Date.now();
+		while (true) try {
+			const fileHandle = await open(this.filePath, "wx");
+			await fileHandle.write(`${process.pid}\n`);
+			await fileHandle.close();
+			this.locked = true;
+			return;
+		} catch (error) {
+			if (error instanceof Error && "code" in error && error.code === "EEXIST") {
+				if (Date.now() - startTime >= this.timeoutMs) throw new DatabaseLockedError(`Database is locked by another process (timeout after ${this.timeoutMs}ms): ${this.filePath}`);
+				await sleep(retryInterval);
+				continue;
+			}
+			throw error;
+		}
+	}
+	/**
+	* Release the lock by deleting the lock file.
+	*/
+	async release() {
+		if (!this.locked) return;
+		try {
+			await rm(this.filePath, { force: true });
+		} finally {
+			this.locked = false;
+		}
+	}
+	/**
+	* Check if this instance currently holds the lock.
+	*/
+	isLocked() {
+		return this.locked;
+	}
+};
+/**
+* Error thrown when attempting to open a database that is
+* already locked by another process.
+*/
+var DatabaseLockedError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "DatabaseLockedError";
+	}
+};
+/**
+* Error thrown when attempting to write to a database opened in read-only mode.
+*/
+var ReadOnlyError = class extends Error {
+	constructor(message = "Cannot write to a read-only database") {
+		super(message);
+		this.name = "ReadOnlyError";
+	}
+};
+function sleep(ms) {
+	return new Promise((resolve$1) => setTimeout(resolve$1, ms));
+}
+
 //#endregion
 //#region src/storage-engine/wal.ts
 var Wal = class {
 	filePath;
+	readOnly;
 	fileHandle = null;
-	constructor(filePath) {
+	constructor(filePath, readOnly = false) {
 		this.filePath = filePath;
+		this.readOnly = readOnly;
 	}
 	/**
 	* Append a WAL entry and sync to disk.
 	* This is the commit point - once this returns, the operation is durable.
 	*/
 	async append(entry) {
+		if (this.readOnly) throw new ReadOnlyError();
 		const buffer = serializeWalEntry(entry);
 		await mkdir(dirname(this.filePath), { recursive: true });
 		this.fileHandle ??= await open(this.filePath, "a");
@@ -290,6 +376,7 @@ var Wal = class {
 	* @returns The number of entries written
 	*/
 	async appendBatch(entries) {
+		if (this.readOnly) throw new ReadOnlyError();
 		if (entries.length === 0) return 0;
 		await mkdir(dirname(this.filePath), { recursive: true });
 		this.fileHandle ??= await open(this.filePath, "a");
@@ -449,81 +536,6 @@ var KeyIndex = class KeyIndex {
 	}
 };
 
-//#endregion
-//#region src/storage-engine/file-lock.ts
-const defaultLockTimeout = 1e4;
-const retryInterval = 100;
-/**
-* Exclusive file lock for preventing multiple processes from
-* accessing the same database simultaneously.
-*
-* Uses atomic file creation with O_EXCL flag to ensure only one
-* process can acquire the lock at a time.
-*/
-var FileLock = class {
-	locked = false;
-	filePath;
-	timeoutMs;
-	constructor(filePath, timeoutMs = defaultLockTimeout) {
-		this.filePath = filePath;
-		this.timeoutMs = timeoutMs;
-	}
-	/**
-	* Acquire an exclusive lock on the file.
-	* Creates the lock file if it doesn't exist.
-	* Retries for up to timeoutMs before throwing DatabaseLockedError.
-	*/
-	async acquire() {
-		if (this.locked) throw new Error("Lock already acquired");
-		await mkdir(dirname(this.filePath), { recursive: true });
-		const startTime = Date.now();
-		while (true) try {
-			const fileHandle = await open(this.filePath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY);
-			await fileHandle.write(`${process.pid}\n`);
-			await fileHandle.close();
-			this.locked = true;
-			return;
-		} catch (error) {
-			if (error instanceof Error && "code" in error && error.code === "EEXIST") {
-				if (Date.now() - startTime >= this.timeoutMs) throw new DatabaseLockedError(`Database is locked by another process (timeout after ${this.timeoutMs}ms): ${this.filePath}`);
-				await sleep(retryInterval);
-				continue;
-			}
-			throw error;
-		}
-	}
-	/**
-	* Release the lock by deleting the lock file.
-	*/
-	async release() {
-		if (!this.locked) return;
-		try {
-			await rm(this.filePath, { force: true });
-		} finally {
-			this.locked = false;
-		}
-	}
-	/**
-	* Check if this instance currently holds the lock.
-	*/
-	isLocked() {
-		return this.locked;
-	}
-};
-/**
-* Error thrown when attempting to open a database that is
-* already locked by another process.
-*/
-var DatabaseLockedError = class extends Error {
-	constructor(message) {
-		super(message);
-		this.name = "DatabaseLockedError";
-	}
-};
-function sleep(ms) {
-	return new Promise((resolve$1) => setTimeout(resolve$1, ms));
-}
-
 //#endregion
 //#region src/storage-engine/mutex.ts
 /**
@@ -743,6 +755,7 @@ var StorageEngine = class StorageEngine {
 	walPath;
 	lockPath;
 	dimension;
+	readOnly;
 	wal;
 	index;
 	fileLock;
@@ -751,7 +764,7 @@ var StorageEngine = class StorageEngine {
 	dataHandle = null;
 	dataHandlePromise = null;
 	sequenceCounter = 0n;
-	constructor(dataPath, walPath, lockPath, dimension, wal, index, fileLock, sequenceCounter, writeBatcher) {
+	constructor(dataPath, walPath, lockPath, dimension, wal, index, fileLock, sequenceCounter, writeBatcher, readOnly) {
 		this.dataPath = dataPath;
 		this.walPath = walPath;
 		this.lockPath = lockPath;
@@ -762,6 +775,7 @@ var StorageEngine = class StorageEngine {
 		this.writeMutex = new Mutex();
 		this.sequenceCounter = sequenceCounter;
 		this.writeBatcher = writeBatcher;
+		this.readOnly = readOnly;
 	}
 	/**
 	* Create or open a storage engine.
@@ -773,21 +787,32 @@ var StorageEngine = class StorageEngine {
 		const walPath = basePath + fileExtensions.wal;
 		const lockPath = basePath + fileExtensions.lock;
 		const dimension = options.dimension ?? 384;
-		await mkdir(dirname(dataPath), { recursive: true });
-		const fileLock = new FileLock(lockPath, options.lockTimeout);
-		await fileLock.acquire();
+		const readOnly = options.readOnly ?? false;
+		if (!readOnly) await mkdir(dirname(dataPath), { recursive: true });
+		else {
+			const dataExists = await stat(dataPath).catch(() => null);
+			const walExists = await stat(walPath).catch(() => null);
+			if (!dataExists && !walExists) throw new Error(`Cannot open database in read-only mode: no database exists at ${dataPath}`);
+		}
+		let fileLock = null;
+		if (!readOnly) {
+			fileLock = new FileLock(lockPath, options.lockTimeout);
+			await fileLock.acquire();
+		}
 		try {
-			if (await StorageEngine.checkNeedsMigration(dataPath)) throw new Error(`Database at ${dataPath} uses old format (v1). Please run migration first.`);
-			const wal = new Wal(walPath);
+			if (!readOnly) {
+				if (await StorageEngine.checkNeedsMigration(dataPath)) throw new Error(`Database at ${dataPath} uses old format (v1). Please run migration first.`);
+			}
+			const wal = new Wal(walPath, readOnly);
 			const { index, maxSequence } = await KeyIndex.buildFromWal(wal, dataPath);
 			let writeBatcher = null;
-			if (options.batchingEnabled !== false) {
+			if (!readOnly && options.batchingEnabled !== false) {
 				writeBatcher = new WriteBatcher(dataPath, wal, index, dimension, options.batchOptions);
 				await writeBatcher.initialize();
 			}
-			return new StorageEngine(dataPath, walPath, lockPath, dimension, wal, index, fileLock, maxSequence + 1n, writeBatcher);
+			return new StorageEngine(dataPath, walPath, lockPath, dimension, wal, index, fileLock, maxSequence + 1n, writeBatcher, readOnly);
 		} catch (error) {
-			await fileLock.release();
+			if (fileLock) await fileLock.release();
 			throw error;
 		}
 	}
@@ -814,6 +839,7 @@ var StorageEngine = class StorageEngine {
 	* Implements: data → fsync → WAL → fsync → index
 	*/
 	async writeRecord(key, embedding, op = opType.insert) {
+		if (this.readOnly) throw new ReadOnlyError();
 		if (embedding.length !== this.dimension) throw new Error(`Embedding dimension mismatch: expected ${this.dimension}, got ${embedding.length}`);
 		if (this.writeBatcher) return this.writeRecordBatched(key, embedding, op, this.writeBatcher);
 		return this.writeRecordImmediate(key, embedding, op);
@@ -969,7 +995,13 @@ var StorageEngine = class StorageEngine {
 			this.dataHandle = null;
 		}
 		await this.wal.close();
-		await this.fileLock.release();
+		if (this.fileLock) await this.fileLock.release();
+	}
+	/**
+	* Check if the storage engine is in read-only mode.
+	*/
+	isReadOnly() {
+		return this.readOnly;
 	}
 	/**
 	* Append data to the data file.
@@ -1003,6 +1035,11 @@ var StorageEngine = class StorageEngine {
 	async getDataHandle() {
 		if (this.dataHandle) return this.dataHandle;
 		this.dataHandlePromise ??= (async () => {
+			if (this.readOnly) {
+				const handle$1 = await open(this.dataPath, "r");
+				this.dataHandle = handle$1;
+				return handle$1;
+			}
 			await mkdir(dirname(this.dataPath), { recursive: true });
 			const handle = await open(this.dataPath, "r+").catch(async () => {
 				return open(this.dataPath, "w+");
@@ -1027,7 +1064,7 @@ async function detectVersion(filePath) {
 			const buffer = new Uint8Array(headerSize);
 			await fileHandle.read(buffer, 0, headerSize, 0);
 			const view = new DataView(buffer.buffer);
-			if (view.getUint32(0, true) !== headerMagic) return null;
+			if (view.getUint32(0, false) !== headerMagic) return null;
 			return view.getUint16(4, true);
 		} finally {
 			await fileHandle.close();
@@ -1141,7 +1178,7 @@ var CandidateSet = class {
 	}
 	add(key, value) {
 		invariant(key, "Key must be provided.");
-		invariant(value, "Value must be provided.");
+		invariant(value !== void 0 && value !== null, "Value must be provided.");
 		if (this.heap.length < this.size) {
 			this.heap.push(new CandidateSetEntry(key, value));
 			this.bubbleUp(this.heap.length - 1);
@@ -1203,6 +1240,80 @@ var CandidateSetEntry = class {
 	}
 };
 
+//#endregion
+//#region src/lru-cache.ts
+/**
+* Generic LRU (Least Recently Used) cache with O(1) get/set operations.
+* Uses JavaScript Map which maintains insertion order - LRU is first key, MRU is last.
+*/
+var LRUCache = class {
+	cache;
+	maxSize;
+	/**
+	* Creates a new LRU cache with the specified maximum size.
+	* @param maxSize - Maximum number of entries to cache (must be positive)
+	*/
+	constructor(maxSize) {
+		invariant(typeof maxSize === "number", "maxSize must be a number");
+		invariant(Number.isInteger(maxSize), "maxSize must be an integer");
+		invariant(maxSize > 0, "maxSize must be a positive integer");
+		this.maxSize = maxSize;
+		this.cache = /* @__PURE__ */ new Map();
+	}
+	/**
+	* Clears all entries from the cache.
+	*/
+	clear() {
+		this.cache.clear();
+	}
+	/**
+	* Gets a value from the cache and moves it to MRU position.
+	* @param key - The key to look up
+	* @returns The cached value, or undefined if not found
+	*/
+	get(key) {
+		const value = this.cache.get(key);
+		if (value === void 0) return;
+		this.cache.delete(key);
+		this.cache.set(key, value);
+		return value;
+	}
+	/**
+	* Returns the maximum number of entries the cache can hold.
+	*/
+	getMaxSize() {
+		return this.maxSize;
+	}
+	/**
+	* Checks if a key exists in the cache without affecting LRU order.
+	* @param key - The key to check
+	* @returns true if the key exists, false otherwise
+	*/
+	has(key) {
+		return this.cache.has(key);
+	}
+	/**
+	* Sets a value in the cache. If the cache is at capacity, evicts the LRU entry.
+	* If the key already exists, updates the value and moves to MRU position.
+	* @param key - The key to set
+	* @param value - The value to cache
+	*/
+	set(key, value) {
+		if (this.cache.has(key)) this.cache.delete(key);
+		else if (this.cache.size >= this.maxSize) {
+			const firstKey = this.cache.keys().next().value;
+			this.cache.delete(firstKey);
+		}
+		this.cache.set(key, value);
+	}
+	/**
+	* Returns the current number of entries in the cache.
+	*/
+	size() {
+		return this.cache.size;
+	}
+};
+
 //#endregion
 //#region src/engine.ts
 const defaultModelUri = "hf:CompendiumLabs/bge-small-en-v1.5-gguf/bge-small-en-v1.5-q8_0.gguf";
@@ -1213,16 +1324,20 @@ var EmbeddingEngine = class {
 	storePath;
 	cacheDir;
 	dimension;
+	readOnly;
 	llama;
 	model;
 	embeddingContext;
 	initPromise;
 	storageInitPromise;
 	embeddingCache = null;
+	textEmbeddingCache = null;
 	constructor(options) {
 		this.storePath = options.storePath;
 		this.cacheDir = options.cacheDir ?? defaultCacheDir;
 		this.dimension = defaultDimension;
+		this.readOnly = options.readOnly ?? false;
+		if (options.embeddingCacheSize && options.embeddingCacheSize > 0) this.textEmbeddingCache = new LRUCache(options.embeddingCacheSize);
 	}
 	/**
 	* Gets or initializes the storage engine
@@ -1236,10 +1351,11 @@ var EmbeddingEngine = class {
 		return this.storageEngine;
 	}
 	async initializeStorage() {
-		await ensureV2Format(this.storePath, this.dimension);
+		if (!this.readOnly) await ensureV2Format(this.storePath, this.dimension);
 		return StorageEngine.create({
 			dataPath: this.storePath,
-			dimension: this.dimension
+			dimension: this.dimension,
+			readOnly: this.readOnly
 		});
 	}
 	/**
@@ -1306,13 +1422,20 @@ var EmbeddingEngine = class {
 	/**
 	* Internal method that returns embedding as Float32Array for performance
 	* Uses Float32Array throughout internal operations to avoid boxing overhead
+	* Checks the text embedding cache first to avoid regenerating embeddings
 	*/
 	async generateEmbeddingFloat32(text) {
+		if (this.textEmbeddingCache) {
+			const cached = this.textEmbeddingCache.get(text);
+			if (cached) return cached;
+		}
 		await this.ensureModelLoaded();
 		invariant(this.embeddingContext, "Embedding context not initialized");
 		const truncatedText = this.truncateToContextSize(text);
 		const embedding = await this.embeddingContext.getEmbeddingFor(truncatedText);
-		return new Float32Array(embedding.vector);
+		const result = new Float32Array(embedding.vector);
+		if (this.textEmbeddingCache) this.textEmbeddingCache.set(text, result);
+		return result;
 	}
 	/**
 	* Retrieves an embedding entry by key
@@ -1375,6 +1498,7 @@ var EmbeddingEngine = class {
 	* @param text - Text to embed and store
 	*/
 	async store(key, text) {
+		if (this.readOnly) throw new ReadOnlyError();
 		invariant(key, "Key must be provided.");
 		invariant(text, "Text must be provided.");
 		const embedding = await this.generateEmbeddingFloat32(text);
@@ -1387,17 +1511,25 @@ var EmbeddingEngine = class {
 	* Stores multiple text embeddings in batch
 	* More efficient than calling store() multiple times
 	* Generates embeddings in parallel and writes records sequentially
+	* Uses text embedding cache to avoid regenerating embeddings for duplicate texts
 	* @param items - Array of {key, text} objects to store
 	*/
 	async storeMany(items) {
+		if (this.readOnly) throw new ReadOnlyError();
 		invariant(items.length > 0, "Items array must not be empty.");
 		await this.ensureModelLoaded();
 		const embeddingContext = this.embeddingContext;
 		invariant(embeddingContext, "Embedding context not initialized");
 		const embeddingPromises = items.map(async (item) => {
+			if (this.textEmbeddingCache) {
+				const cached = this.textEmbeddingCache.get(item.text);
+				if (cached) return cached;
+			}
 			const truncatedText = this.truncateToContextSize(item.text);
 			const embedding = await embeddingContext.getEmbeddingFor(truncatedText);
-			return new Float32Array(embedding.vector);
+			const result = new Float32Array(embedding.vector);
+			if (this.textEmbeddingCache) this.textEmbeddingCache.set(item.text, result);
+			return result;
 		});
 		const embeddingsList = await Promise.all(embeddingPromises);
 		const storage = await this.ensureStorageEngine();
@@ -1419,6 +1551,7 @@ var EmbeddingEngine = class {
 	* @returns true if the entry was deleted, false if it didn't exist
 	*/
 	async delete(key) {
+		if (this.readOnly) throw new ReadOnlyError();
 		invariant(key, "Key must be provided.");
 		const deleted = await (await this.ensureStorageEngine()).deleteRecord(key);
 		if (deleted && this.embeddingCache !== null) this.embeddingCache.delete(key);
@@ -1461,11 +1594,32 @@ var EmbeddingEngine = class {
 		return dotProduct / (magnitudeA * magnitudeB);
 	}
 	/**
+	* Check if the engine is in read-only mode.
+	*/
+	isReadOnly() {
+		return this.readOnly;
+	}
+	/**
+	* Gets statistics about the text embedding cache.
+	* @returns Cache stats if enabled, null if cache is disabled
+	*/
+	getTextEmbeddingCacheStats() {
+		if (!this.textEmbeddingCache) return null;
+		return {
+			size: this.textEmbeddingCache.size(),
+			maxSize: this.textEmbeddingCache.getMaxSize()
+		};
+	}
+	/**
 	* Disposes of resources and closes the storage engine
 	* Call this when you're done using the engine to free up memory
 	*/
 	async dispose() {
 		this.embeddingCache = null;
+		if (this.textEmbeddingCache) {
+			this.textEmbeddingCache.clear();
+			this.textEmbeddingCache = null;
+		}
 		if (this.storageEngine) {
 			await this.storageEngine.close();
 			this.storageEngine = null;
@@ -1485,4 +1639,4 @@ var EmbeddingEngine = class {
 };
 
 //#endregion
-export { opType as i, Wal as n, fileExtensions as r, EmbeddingEngine as t };
+export { ReadOnlyError as a, DatabaseLockedError as i, LRUCache as n, fileExtensions as o, Wal as r, opType as s, EmbeddingEngine as t };