embedded-raptor 2.0.0 → 2.1.1

package/dist/candidate-set.d.ts

@@ -1,11 +1,24 @@
+/**
+ * A fixed-size collection that maintains the top N highest-value entries.
+ * Uses a min-heap internally for O(log n) insertion when at capacity.
+ */
 export declare class CandidateSet {
     readonly size: number;
-    protected readonly entries: CandidateSetEntry[];
+    private readonly heap;
     constructor(size?: number);
     add(key: string, value: number): void;
     count(): number;
     getEntries(): CandidateSetEntry[];
     getKeys(): string[];
+    /**
+     * Bubble up element at index to maintain min-heap property
+     */
+    private bubbleUp;
+    /**
+     * Bubble down element at index to maintain min-heap property
+     */
+    private bubbleDown;
+    private swap;
 }
 declare class CandidateSetEntry {
     readonly key: string;

package/dist/candidate-set.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"candidate-set.d.ts","sourceRoot":"","sources":["../src/candidate-set.ts"],"names":[],"mappings":"AAEA,qBAAa,YAAY;IACvB,SAAgB,IAAI,EAAE,MAAM,CAAA;IAC5B,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,EAAE,CAAK;gBAExC,IAAI,SAAI;IAMpB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAyBrC,KAAK,IAAI,MAAM;IAIf,UAAU,IAAI,iBAAiB,EAAE;IAIjC,OAAO,IAAI,MAAM,EAAE;CAGpB;AAED,cAAM,iBAAiB;IACrB,SAAgB,GAAG,EAAE,MAAM,CAAA;IAC3B,SAAgB,KAAK,EAAE,MAAM,CAAA;gBAEjB,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAIvC"}
+{"version":3,"file":"candidate-set.d.ts","sourceRoot":"","sources":["../src/candidate-set.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,qBAAa,YAAY;IACvB,SAAgB,IAAI,EAAE,MAAM,CAAA;IAC5B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0B;gBAEnC,IAAI,SAAI;IAMpB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAmBrC,KAAK,IAAI,MAAM;IAIf,UAAU,IAAI,iBAAiB,EAAE;IAKjC,OAAO,IAAI,MAAM,EAAE;IAInB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAWhB;;OAEG;IACH,OAAO,CAAC,UAAU;IAgClB,OAAO,CAAC,IAAI;CAKb;AAED,cAAM,iBAAiB;IACrB,SAAgB,GAAG,EAAE,MAAM,CAAA;IAC3B,SAAgB,KAAK,EAAE,MAAM,CAAA;gBAEjB,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAIvC"}

package/dist/cli.cjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const require_engine = require('./engine-DLM7PWhV.cjs');
+const require_engine = require('./engine-DKn_V99U.cjs');
 let node_path = require("node:path");
 node_path = require_engine.__toESM(node_path);
 let node_fs = require("node:fs");
@@ -35,36 +35,49 @@ const searchFlags = {
 //#region src/commands/store.ts
 const store = (0, cleye.command)({
 	name: "store",
-	description: "Store a text embedding with a key",
 	parameters: ["<key>", "<text>"],
-	flags: { ...sharedFlags }
+	flags: { ...sharedFlags },
+	help: {
+		description: "Store a text embedding with a key",
+		examples: ["raptor store doc1 \"Machine learning is awesome\"", "raptor store -s ./my-db.raptor mykey \"Some text to embed\""]
+	}
 }, async (argv) => {
 	const engine = new require_engine.EmbeddingEngine({ storePath: argv.flags.storePath });
-	const [key, text] = argv._;
-	await engine.store(key, text);
-	console.log(`✓ Stored embedding for key: ${key}`);
+	try {
+		const [key, text] = argv._;
+		await engine.store(key, text);
+		console.log(`Stored embedding for key: ${key}`);
+	} finally {
+		await engine.dispose();
+	}
 });
 
 //#endregion
 //#region src/commands/get.ts
 const get = (0, cleye.command)({
 	name: "get",
-	description: "Retrieve an embedding entry by key",
 	parameters: ["<key>"],
-	flags: { ...sharedFlags }
+	flags: { ...sharedFlags },
+	help: {
+		description: "Retrieve an embedding entry by key",
+		examples: ["raptor get doc1", "raptor get -s ./my-db.raptor mykey"]
+	}
 }, async (argv) => {
 	const engine = new require_engine.EmbeddingEngine({ storePath: argv.flags.storePath });
-	const [key] = argv._;
-	const entry = await engine.get(key);
-	if (entry) console.log(JSON.stringify({
-		key: entry.key,
-		text: entry.text,
-		embeddingDimensions: entry.embedding.length,
-		timestamp: new Date(entry.timestamp).toISOString()
-	}, null, 2));
-	else {
-		console.log(`Key "${key}" not found`);
-		process.exit(1);
+	try {
+		const [key] = argv._;
+		const entry = await engine.get(key);
+		if (entry) console.log(JSON.stringify({
+			key: entry.key,
+			embeddingDimensions: entry.embedding.length,
+			timestamp: new Date(entry.timestamp).toISOString()
+		}, null, 2));
+		else {
+			console.log(`Key "${key}" not found`);
+			process.exit(1);
+		}
+	} finally {
+		await engine.dispose();
 	}
 });
 
@@ -72,20 +85,31 @@ const get = (0, cleye.command)({
 //#region src/commands/search.ts
 const search = (0, cleye.command)({
 	name: "search",
-	description: "Search for similar embeddings using a query",
 	parameters: ["<query>"],
 	flags: {
 		...sharedFlags,
 		...searchFlags
+	},
+	help: {
+		description: "Search for similar embeddings using a query",
+		examples: [
+			"raptor search \"artificial intelligence\"",
+			"raptor search -l 5 -m 0.7 \"machine learning\"",
+			"raptor search -s ./my-db.raptor \"find similar docs\""
+		]
 	}
 }, async (argv) => {
 	const engine = new require_engine.EmbeddingEngine({ storePath: argv.flags.storePath });
-	const [query] = argv._;
-	const results = await engine.search(query, argv.flags.limit, argv.flags.minSimilarity);
-	if (results.length === 0) console.log("No results found");
-	else {
-		console.log(`Found ${results.length} result(s):\n`);
-		for (const result of results) console.log(`${result.key}: ${result.similarity.toFixed(6)}`);
+	try {
+		const [query] = argv._;
+		const results = await engine.search(query, argv.flags.limit, argv.flags.minSimilarity);
+		if (results.length === 0) console.log("No results found");
+		else {
+			console.log(`Found ${results.length} result(s):\n`);
+			for (const result of results) console.log(`${result.key}: ${result.similarity.toFixed(6)}`);
+		}
+	} finally {
+		await engine.dispose();
 	}
 });
 
@@ -93,9 +117,12 @@ const search = (0, cleye.command)({
 //#region src/commands/delete.ts
 const deleteCmd = (0, cleye.command)({
 	name: "delete",
-	description: "Delete an embedding entry by key",
 	parameters: ["<key>"],
-	flags: { ...sharedFlags }
+	flags: { ...sharedFlags },
+	help: {
+		description: "Delete an embedding entry by key",
+		examples: ["raptor delete doc1", "raptor delete -s ./my-db.raptor mykey"]
+	}
 }, async (argv) => {
 	const engine = new require_engine.EmbeddingEngine({ storePath: argv.flags.storePath });
 	try {
@@ -110,6 +137,43 @@ const deleteCmd = (0, cleye.command)({
 	}
 });
 
+//#endregion
+//#region src/commands/wal.ts
+const opTypeNames = {
+	[require_engine.opType.insert]: "INSERT",
+	[require_engine.opType.update]: "UPDATE",
+	[require_engine.opType.delete]: "DELETE"
+};
+function formatKeyHash(hash) {
+	return Array.from(hash.slice(0, 8)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+const walCmd = (0, cleye.command)({
+	name: "wal",
+	flags: { ...sharedFlags },
+	help: {
+		description: "Display WAL entries in human-readable format",
+		examples: ["raptor wal", "raptor wal -s ./my-db.raptor"]
+	}
+}, async (argv) => {
+	const wal = new require_engine.Wal(argv.flags.storePath.replace(/\.raptor$/, "") + require_engine.fileExtensions.wal);
+	try {
+		let count = 0;
+		for await (const entry of wal.recover()) {
+			const opName = opTypeNames[entry.opType] ?? `UNKNOWN(${entry.opType})`;
+			const keyHashHex = formatKeyHash(entry.keyHash);
+			console.log(`[${entry.sequenceNumber}] ${opName}`);
+			console.log(`  offset: ${entry.offset}, length: ${entry.length}`);
+			console.log(`  keyHash: ${keyHashHex}`);
+			console.log();
+			count++;
+		}
+		if (count === 0) console.log("WAL is empty");
+		else console.log(`Total: ${count} entries`);
+	} finally {
+		await wal.close();
+	}
+});
+
 //#endregion
 //#region src/cli.ts
 const __dirname$1 = (0, node_path.dirname)((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href));
@@ -122,7 +186,8 @@ function main() {
 			store,
 			get,
 			search,
-			deleteCmd
+			deleteCmd,
+			walCmd
 		]
 	}, () => {});
 }

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as EmbeddingEngine } from "./engine-Cuz0P5Od.mjs";
+import { i as opType, n as Wal, r as fileExtensions, t as EmbeddingEngine } from "./engine-Zax2PJSW.mjs";
 import { dirname, resolve } from "node:path";
 import { readFileSync } from "node:fs";
 import { cli, command } from "cleye";
@@ -31,36 +31,49 @@ const searchFlags = {
 //#region src/commands/store.ts
 const store = command({
 	name: "store",
-	description: "Store a text embedding with a key",
 	parameters: ["<key>", "<text>"],
-	flags: { ...sharedFlags }
+	flags: { ...sharedFlags },
+	help: {
+		description: "Store a text embedding with a key",
+		examples: ["raptor store doc1 \"Machine learning is awesome\"", "raptor store -s ./my-db.raptor mykey \"Some text to embed\""]
+	}
 }, async (argv) => {
 	const engine = new EmbeddingEngine({ storePath: argv.flags.storePath });
-	const [key, text] = argv._;
-	await engine.store(key, text);
-	console.log(`✓ Stored embedding for key: ${key}`);
+	try {
+		const [key, text] = argv._;
+		await engine.store(key, text);
+		console.log(`Stored embedding for key: ${key}`);
+	} finally {
+		await engine.dispose();
+	}
 });
 
 //#endregion
 //#region src/commands/get.ts
 const get = command({
 	name: "get",
-	description: "Retrieve an embedding entry by key",
 	parameters: ["<key>"],
-	flags: { ...sharedFlags }
+	flags: { ...sharedFlags },
+	help: {
+		description: "Retrieve an embedding entry by key",
+		examples: ["raptor get doc1", "raptor get -s ./my-db.raptor mykey"]
+	}
 }, async (argv) => {
 	const engine = new EmbeddingEngine({ storePath: argv.flags.storePath });
-	const [key] = argv._;
-	const entry = await engine.get(key);
-	if (entry) console.log(JSON.stringify({
-		key: entry.key,
-		text: entry.text,
-		embeddingDimensions: entry.embedding.length,
-		timestamp: new Date(entry.timestamp).toISOString()
-	}, null, 2));
-	else {
-		console.log(`Key "${key}" not found`);
-		process.exit(1);
+	try {
+		const [key] = argv._;
+		const entry = await engine.get(key);
+		if (entry) console.log(JSON.stringify({
+			key: entry.key,
+			embeddingDimensions: entry.embedding.length,
+			timestamp: new Date(entry.timestamp).toISOString()
+		}, null, 2));
+		else {
+			console.log(`Key "${key}" not found`);
+			process.exit(1);
+		}
+	} finally {
+		await engine.dispose();
 	}
 });
 
@@ -68,20 +81,31 @@ const get = command({
 //#region src/commands/search.ts
 const search = command({
 	name: "search",
-	description: "Search for similar embeddings using a query",
 	parameters: ["<query>"],
 	flags: {
 		...sharedFlags,
 		...searchFlags
+	},
+	help: {
+		description: "Search for similar embeddings using a query",
+		examples: [
+			"raptor search \"artificial intelligence\"",
+			"raptor search -l 5 -m 0.7 \"machine learning\"",
+			"raptor search -s ./my-db.raptor \"find similar docs\""
+		]
 	}
 }, async (argv) => {
 	const engine = new EmbeddingEngine({ storePath: argv.flags.storePath });
-	const [query] = argv._;
-	const results = await engine.search(query, argv.flags.limit, argv.flags.minSimilarity);
-	if (results.length === 0) console.log("No results found");
-	else {
-		console.log(`Found ${results.length} result(s):\n`);
-		for (const result of results) console.log(`${result.key}: ${result.similarity.toFixed(6)}`);
+	try {
+		const [query] = argv._;
+		const results = await engine.search(query, argv.flags.limit, argv.flags.minSimilarity);
+		if (results.length === 0) console.log("No results found");
+		else {
+			console.log(`Found ${results.length} result(s):\n`);
+			for (const result of results) console.log(`${result.key}: ${result.similarity.toFixed(6)}`);
+		}
+	} finally {
+		await engine.dispose();
 	}
 });
 
@@ -89,9 +113,12 @@ const search = command({
 //#region src/commands/delete.ts
 const deleteCmd = command({
 	name: "delete",
-	description: "Delete an embedding entry by key",
 	parameters: ["<key>"],
-	flags: { ...sharedFlags }
+	flags: { ...sharedFlags },
+	help: {
+		description: "Delete an embedding entry by key",
+		examples: ["raptor delete doc1", "raptor delete -s ./my-db.raptor mykey"]
+	}
 }, async (argv) => {
 	const engine = new EmbeddingEngine({ storePath: argv.flags.storePath });
 	try {
@@ -106,6 +133,43 @@ const deleteCmd = command({
 	}
 });
 
+//#endregion
+//#region src/commands/wal.ts
+const opTypeNames = {
+	[opType.insert]: "INSERT",
+	[opType.update]: "UPDATE",
+	[opType.delete]: "DELETE"
+};
+function formatKeyHash(hash) {
+	return Array.from(hash.slice(0, 8)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+const walCmd = command({
+	name: "wal",
+	flags: { ...sharedFlags },
+	help: {
+		description: "Display WAL entries in human-readable format",
+		examples: ["raptor wal", "raptor wal -s ./my-db.raptor"]
+	}
+}, async (argv) => {
+	const wal = new Wal(argv.flags.storePath.replace(/\.raptor$/, "") + fileExtensions.wal);
+	try {
+		let count = 0;
+		for await (const entry of wal.recover()) {
+			const opName = opTypeNames[entry.opType] ?? `UNKNOWN(${entry.opType})`;
+			const keyHashHex = formatKeyHash(entry.keyHash);
+			console.log(`[${entry.sequenceNumber}] ${opName}`);
+			console.log(`  offset: ${entry.offset}, length: ${entry.length}`);
+			console.log(`  keyHash: ${keyHashHex}`);
+			console.log();
+			count++;
+		}
+		if (count === 0) console.log("WAL is empty");
+		else console.log(`Total: ${count} entries`);
+	} finally {
+		await wal.close();
+	}
+});
+
 //#endregion
 //#region src/cli.ts
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -118,7 +182,8 @@ function main() {
 			store,
 			get,
 			search,
-			deleteCmd
+			deleteCmd,
+			walCmd
 		]
 	}, () => {});
 }

package/dist/commands/delete.d.ts

@@ -1,6 +1,5 @@
 export declare const deleteCmd: import("cleye").Command<{
     name: "delete";
-    description: string;
     parameters: "<key>"[];
     flags: {
         storePath: {
@@ -10,6 +9,10 @@ export declare const deleteCmd: import("cleye").Command<{
             readonly alias: "s";
         };
     };
+    help: {
+        description: string;
+        examples: string[];
+    };
 }, {
     command: "delete";
 } & import("type-flag").TypeFlag<{

package/dist/commands/delete.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"delete.d.ts","sourceRoot":"","sources":["../../src/commands/delete.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;sBA6B2kM,CAAC;;;;;;;;;;;;EADjmM,CAAA"}
+{"version":3,"file":"delete.d.ts","sourceRoot":"","sources":["../../src/commands/delete.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBAgCs+L,CAAC;;;;;;;;;;;;EAD5/L,CAAA"}

package/dist/commands/get.d.ts

@@ -1,6 +1,5 @@
 export declare const get: import("cleye").Command<{
     name: "get";
-    description: string;
     parameters: "<key>"[];
     flags: {
         storePath: {
@@ -10,6 +9,10 @@ export declare const get: import("cleye").Command<{
             readonly alias: "s";
         };
     };
+    help: {
+        description: string;
+        examples: string[];
+    };
 }, {
     command: "get";
 } & import("type-flag").TypeFlag<{

package/dist/commands/get.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get.d.ts","sourceRoot":"","sources":["../../src/commands/get.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;sBAoCk7L,CAAC;;;;;;;;;;;;EADl8L,CAAA"}
+{"version":3,"file":"get.d.ts","sourceRoot":"","sources":["../../src/commands/get.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBA0CgxL,CAAC;;;;;;;;;;;;EADhyL,CAAA"}

package/dist/commands/index.d.ts

@@ -2,4 +2,5 @@ export { store } from './store';
 export { get } from './get';
 export { search } from './search';
 export { deleteCmd } from './delete';
+export { walCmd } from './wal';
 //# sourceMappingURL=index.d.ts.map

package/dist/commands/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAC3B,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAC3B,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,OAAO,CAAA"}

package/dist/commands/search.d.ts

@@ -1,6 +1,5 @@
 export declare const search: import("cleye").Command<{
     name: "search";
-    description: string;
     parameters: "<query>"[];
     flags: {
         limit: {
@@ -22,6 +21,10 @@ export declare const search: import("cleye").Command<{
             readonly alias: "s";
         };
     };
+    help: {
+        description: string;
+        examples: string[];
+    };
 }, {
     command: "search";
 } & import("type-flag").TypeFlag<{

package/dist/commands/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/commands/search.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBAgCi7L,CAAC;;;;;;;;;;;;EADp8L,CAAA"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/commands/search.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBA2CgoL,CAAC;;;;;;;;;;;;EADnpL,CAAA"}

package/dist/commands/store.d.ts

@@ -1,6 +1,5 @@
 export declare const store: import("cleye").Command<{
     name: "store";
-    description: string;
     parameters: ("<key>" | "<text>")[];
     flags: {
         storePath: {
@@ -10,6 +9,10 @@ export declare const store: import("cleye").Command<{
             readonly alias: "s";
         };
     };
+    help: {
+        description: string;
+        examples: string[];
+    };
 }, {
     command: "store";
 } & import("type-flag").TypeFlag<{

package/dist/commands/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/commands/store.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBAmBwvM,CAAC;;;;;;;;;;;;EAD1wM,CAAA"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/commands/store.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBA6BygM,CAAC;;;;;;;;;;;;EAD3hM,CAAA"}

package/dist/commands/wal.d.ts

@@ -0,0 +1,41 @@
+export declare const walCmd: import("cleye").Command<{
+    name: "wal";
+    flags: {
+        storePath: {
+            readonly type: StringConstructor;
+            readonly description: "Path to the embeddings store file";
+            readonly default: "./database.raptor";
+            readonly alias: "s";
+        };
+    };
+    help: {
+        description: string;
+        examples: string[];
+    };
+}, {
+    command: "wal";
+} & import("type-flag").TypeFlag<{
+    storePath: {
+        readonly type: StringConstructor;
+        readonly description: "Path to the embeddings store file";
+        readonly default: "./database.raptor";
+        readonly alias: "s";
+    };
+} & {
+    help: BooleanConstructor;
+}> & {
+    _: {};
+    showHelp: (options?: {
+        version?: string;
+        description?: string;
+        usage?: false | string | string[];
+        examples?: string | string[];
+        render?: (nodes: {
+            id?: string;
+            type: keyof import("cleye").Renderers;
+            data: any;
+        }[], renderers: import("cleye").Renderers) => string;
+    }) => void;
+    showVersion: () => void;
+}>;
+//# sourceMappingURL=wal.d.ts.map

package/dist/commands/wal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wal.d.ts","sourceRoot":"","sources":["../../src/commands/wal.ts"],"names":[],"mappings":"AAiBA,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;sBAyCiuK,CAAC;;;;;;;;;;;;EADpvK,CAAA"}