@sochdb/sochdb 0.4.0

package/dist/types/embedded/database.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Embedded Database - FFI Mode
+ *
+ * Direct FFI access to SochDB native library.
+ * No server required - similar to Python SDK's Database class.
+ */
+import { NativeBindings } from './ffi/bindings';
+import { EmbeddedTransaction } from './transaction';
+export interface EmbeddedDatabaseConfig {
+    walEnabled?: boolean;
+    syncMode?: 'full' | 'normal' | 'off';
+    memtableSizeBytes?: number;
+    groupCommit?: boolean;
+    indexPolicy?: 'write_optimized' | 'balanced' | 'scan_optimized' | 'append_only';
+}
+/**
+ * Embedded Database using direct FFI
+ *
+ * @example
+ * ```typescript
+ * import { EmbeddedDatabase } from '@sushanth/sochdb';
+ *
+ * const db = await EmbeddedDatabase.open('./mydb');
+ * await db.put(Buffer.from('key'), Buffer.from('value'));
+ * const value = await db.get(Buffer.from('key'));
+ * await db.close();
+ * ```
+ */
+export declare class EmbeddedDatabase {
+    private handle;
+    private bindings;
+    private closed;
+    private path;
+    private constructor();
+    /**
+     * Open a database at the specified path
+     *
+     * @param path - Path to database directory
+     * @param config - Optional configuration
+     * @returns EmbeddedDatabase instance
+     */
+    static open(path: string, config?: EmbeddedDatabaseConfig): EmbeddedDatabase;
+    /**
+     * Put a key-value pair (auto-transaction)
+     */
+    put(key: Buffer, value: Buffer): Promise<void>;
+    /**
+     * Get a value by key (auto-transaction)
+     */
+    get(key: Buffer): Promise<Buffer | null>;
+    /**
+     * Delete a key (auto-transaction)
+     */
+    delete(key: Buffer): Promise<void>;
+    /**
+     * Put value at path (auto-transaction)
+     */
+    putPath(path: string, value: Buffer): Promise<void>;
+    /**
+     * Get value at path (auto-transaction)
+     */
+    getPath(path: string): Promise<Buffer | null>;
+    /**
+     * Scan keys with prefix
+     */
+    scanPrefix(prefix: Buffer): AsyncGenerator<[Buffer, Buffer]>;
+    /**
+     * Begin a transaction
+     */
+    transaction(): EmbeddedTransaction;
+    /**
+     * Execute operations within a transaction (with auto-commit/abort)
+     */
+    withTransaction<T>(fn: (txn: EmbeddedTransaction) => Promise<T>): Promise<T>;
+    /**
+     * Force a checkpoint
+     */
+    checkpoint(): Promise<bigint>;
+    /**
+     * Get storage statistics
+     */
+    stats(): Promise<{
+        memtableSizeBytes: bigint;
+        walSizeBytes: bigint;
+        activeTransactions: number;
+        minActiveSnapshot: bigint;
+        lastCheckpointLsn: bigint;
+    }>;
+    /**
+     * Close the database
+     */
+    close(): void;
+    private ensureOpen;
+    /**
+     * Get internal handle (for transactions)
+     * @internal
+     */
+    getHandle(): any;
+    /**
+     * Get bindings instance (for transactions)
+     * @internal
+     */
+    getBindings(): NativeBindings;
+}
+//# sourceMappingURL=database.d.ts.map

package/dist/types/embedded/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../../src/embedded/database.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAGpD,MAAM,WAAW,sBAAsB;IACnC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACrC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,iBAAiB,GAAG,UAAU,GAAG,gBAAgB,GAAG,aAAa,CAAC;CACnF;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,gBAAgB;IACzB,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,IAAI,CAAS;IAErB,OAAO;IAMP;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,sBAAsB,GAAG,gBAAgB;IA4B5E;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAapD;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAc9C;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAaxC;;OAEG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAazD;;OAEG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAcnD;;OAEG;IACI,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAenE;;OAEG;IACH,WAAW,IAAI,mBAAmB;IAOlC;;OAEG;IACG,eAAe,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,mBAAmB,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAYlF;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAMnC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC;QACnB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,YAAY,EAAE,MAAM,CAAC;QACrB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,iBAAiB,EAAE,MAAM,CAAC;QAC1B,iBAAiB,EAAE,MAAM,CAAC;KAC7B,CAAC;IAiBF;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb,OAAO,CAAC,UAAU;IAMlB;;;OAGG;IACH,SAAS,IAAI,GAAG;IAIhB;;;OAGG;IACH,WAAW,IAAI,cAAc;CAGhC"}

package/dist/types/embedded/ffi/bindings.d.ts

@@ -0,0 +1,24 @@
+export declare class NativeBindings {
+    private static instance;
+    private lib;
+    sochdb_open: any;
+    sochdb_open_with_config: any;
+    sochdb_close: any;
+    sochdb_begin_txn: any;
+    sochdb_commit: any;
+    sochdb_abort: any;
+    sochdb_put: any;
+    sochdb_get: any;
+    sochdb_delete: any;
+    sochdb_put_path: any;
+    sochdb_get_path: any;
+    sochdb_scan_prefix: any;
+    sochdb_iterator_next: any;
+    sochdb_iterator_close: any;
+    sochdb_stats: any;
+    sochdb_checkpoint: any;
+    sochdb_free_bytes: any;
+    private constructor();
+    static getInstance(): NativeBindings;
+}
+//# sourceMappingURL=bindings.d.ts.map

package/dist/types/embedded/ffi/bindings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.d.ts","sourceRoot":"","sources":["../../../../src/embedded/ffi/bindings.ts"],"names":[],"mappings":"AAsCA,qBAAa,cAAc;IACvB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAiB;IACxC,OAAO,CAAC,GAAG,CAAM;IAGV,WAAW,EAAE,GAAG,CAAC;IACjB,uBAAuB,EAAE,GAAG,CAAC;IAC7B,YAAY,EAAE,GAAG,CAAC;IAGlB,gBAAgB,EAAE,GAAG,CAAC;IACtB,aAAa,EAAE,GAAG,CAAC;IACnB,YAAY,EAAE,GAAG,CAAC;IAIlB,UAAU,EAAE,GAAG,CAAC;IAEhB,UAAU,EAAE,GAAG,CAAC;IAEhB,aAAa,EAAE,GAAG,CAAC;IAGnB,eAAe,EAAE,GAAG,CAAC;IACrB,eAAe,EAAE,GAAG,CAAC;IAGrB,kBAAkB,EAAE,GAAG,CAAC;IACxB,oBAAoB,EAAE,GAAG,CAAC;IAC1B,qBAAqB,EAAE,GAAG,CAAC;IAG3B,YAAY,EAAE,GAAG,CAAC;IAClB,iBAAiB,EAAE,GAAG,CAAC;IAGvB,iBAAiB,EAAE,GAAG,CAAC;IAE9B,OAAO;WA2CO,WAAW,IAAI,cAAc;CAM9C"}

package/dist/types/embedded/ffi/library-finder.d.ts

@@ -0,0 +1,17 @@
+/**
+ * FFI Library Finder
+ *
+ * Locates the SochDB native library for the current platform.
+ * Search order matches Python SDK for consistency.
+ */
+/**
+ * Find the SochDB native library
+ *
+ * Search order:
+ * 1. SOCHDB_LIB_PATH environment variable
+ * 2. Bundled library in package (_bin/{target}/)
+ * 3. Development build (../target/release, ../target/debug)
+ * 4. System paths
+ */
+export declare function findLibrary(): string;
+//# sourceMappingURL=library-finder.d.ts.map

package/dist/types/embedded/ffi/library-finder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"library-finder.d.ts","sourceRoot":"","sources":["../../../../src/embedded/ffi/library-finder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAyCH;;;;;;;;GAQG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAyDpC"}

package/dist/types/embedded/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Embedded Mode - FFI Support
+ *
+ * Direct FFI bindings to SochDB native library.
+ * No server required.
+ */
+export { EmbeddedDatabase, EmbeddedDatabaseConfig } from './database';
+export { EmbeddedTransaction } from './transaction';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/embedded/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/embedded/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC"}

package/dist/types/embedded/transaction.d.ts

@@ -0,0 +1,21 @@
+import { EmbeddedDatabase } from './database';
+export declare class EmbeddedTransaction {
+    private db;
+    private dbHandle;
+    private txnHandle;
+    private bindings;
+    private committed;
+    private aborted;
+    constructor(db: EmbeddedDatabase, dbHandle: any, txnHandle: any);
+    put(key: Buffer, value: Buffer): Promise<void>;
+    get(key: Buffer): Promise<Buffer | null>;
+    delete(key: Buffer): Promise<void>;
+    putPath(path: string, value: Buffer): Promise<void>;
+    getPath(path: string): Promise<Buffer | null>;
+    scanPrefix(prefix: Buffer): AsyncGenerator<[Buffer, Buffer]>;
+    commit(): Promise<void>;
+    abort(): Promise<void>;
+    private isActive;
+    private ensureActive;
+}
+//# sourceMappingURL=transaction.d.ts.map

package/dist/types/embedded/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../../src/embedded/transaction.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG9C,qBAAa,mBAAmB;IAC5B,OAAO,CAAC,EAAE,CAAmB;IAC7B,OAAO,CAAC,QAAQ,CAAM;IACtB,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAAS;gBAEZ,EAAE,EAAE,gBAAgB,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG;IAOzD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ9C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA2BxC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQlC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQnD,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAuB5C,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IA6C7D,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAYvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAO5B,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,YAAY;CAKvB"}

package/dist/types/errors.d.ts

@@ -0,0 +1,36 @@
+/**
+ * SochDB Error Classes
+ *
+ * @packageDocumentation
+ */
+/**
+ * Base error class for all SochDB errors.
+ */
+export declare class SochDBError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when connection to the database fails.
+ */
+export declare class ConnectionError extends SochDBError {
+    constructor(message: string);
+}
+/**
+ * Error thrown when a transaction operation fails.
+ */
+export declare class TransactionError extends SochDBError {
+    constructor(message: string);
+}
+/**
+ * Error thrown when there's a protocol error in IPC communication.
+ */
+export declare class ProtocolError extends SochDBError {
+    constructor(message: string);
+}
+/**
+ * Error thrown when a database operation fails.
+ */
+export declare class DatabaseError extends SochDBError {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/types/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAK5B;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,WAAW;gBAClC,OAAO,EAAE,MAAM;CAK5B;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,WAAW;gBACnC,OAAO,EAAE,MAAM;CAK5B;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,WAAW;gBAChC,OAAO,EAAE,MAAM;CAK5B;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,WAAW;gBAChC,OAAO,EAAE,MAAM;CAK5B"}

package/dist/types/format.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Copyright 2025 Sushanth (https://github.com/sushanthpy)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Unified Output Format Semantics
+ *
+ * Provides format enums for query results and LLM context packaging.
+ * This mirrors the Rust sochdb-client format module for consistency.
+ */
+/**
+ * Error when format conversion fails.
+ */
+export declare class FormatConversionError extends Error {
+    fromFormat: string;
+    toFormat: string;
+    reason: string;
+    constructor(fromFormat: string, toFormat: string, reason: string);
+}
+/**
+ * Output format for query results sent to clients.
+ *
+ * These formats are optimized for transmission efficiency and
+ * client-side processing.
+ */
+export declare enum WireFormat {
+    /**
+     * TOON format (default, 40-66% fewer tokens than JSON).
+     * Optimized for LLM consumption.
+     */
+    TOON = "toon",
+    /**
+     * Standard JSON for compatibility.
+     */
+    JSON = "json",
+    /**
+     * Raw columnar format for analytics.
+     * More efficient for large result sets with projection pushdown.
+     */
+    COLUMNAR = "columnar"
+}
+export declare namespace WireFormat {
+    /**
+     * Parse format from string.
+     */
+    function fromString(s: string): WireFormat;
+}
+/**
+ * Output format for LLM context packaging.
+ *
+ * These formats are optimized for readability and token efficiency
+ * when constructing prompts for language models.
+ */
+export declare enum ContextFormat {
+    /**
+     * TOON format (default, token-efficient).
+     * Structured data with minimal syntax overhead.
+     */
+    TOON = "toon",
+    /**
+     * JSON format.
+     * Widely understood by LLMs, good for structured data.
+     */
+    JSON = "json",
+    /**
+     * Markdown format.
+     * Best for human-readable context with formatting.
+     */
+    MARKDOWN = "markdown"
+}
+export declare namespace ContextFormat {
+    /**
+     * Parse format from string.
+     */
+    function fromString(s: string): ContextFormat;
+}
+/**
+ * Canonical storage format (server-side only).
+ *
+ * This is the format used for internal storage and is optimized
+ * for storage efficiency and query performance.
+ */
+export declare enum CanonicalFormat {
+    /**
+     * TOON canonical format.
+     */
+    TOON = "toon"
+}
+/**
+ * Helper to check format capabilities and conversions.
+ */
+export declare class FormatCapabilities {
+    /**
+     * Convert WireFormat to ContextFormat if compatible.
+     */
+    static wireToContext(wire: WireFormat): ContextFormat | null;
+    /**
+     * Convert ContextFormat to WireFormat if compatible.
+     */
+    static contextToWire(ctx: ContextFormat): WireFormat | null;
+    /**
+     * Check if format supports round-trip: decode(encode(x)) = x.
+     */
+    static supportsRoundTrip(fmt: WireFormat): boolean;
+}
+//# sourceMappingURL=format.d.ts.map

package/dist/types/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;GAKG;AAEH;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAErC,UAAU,EAAE,MAAM;IAClB,QAAQ,EAAE,MAAM;IAChB,MAAM,EAAE,MAAM;gBAFd,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM;CAKxB;AAED;;;;;GAKG;AACH,oBAAY,UAAU;IACpB;;;OAGG;IACH,IAAI,SAAS;IAEb;;OAEG;IACH,IAAI,SAAS;IAEb;;;OAGG;IACH,QAAQ,aAAa;CACtB;AAED,yBAAiB,UAAU,CAAC;IAC1B;;OAEG;IACH,SAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU,CAiBhD;CACF;AAED;;;;;GAKG;AACH,oBAAY,aAAa;IACvB;;;OAGG;IACH,IAAI,SAAS;IAEb;;;OAGG;IACH,IAAI,SAAS;IAEb;;;OAGG;IACH,QAAQ,aAAa;CACtB;AAED,yBAAiB,aAAa,CAAC;IAC7B;;OAEG;IACH,SAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,aAAa,CAiBnD;CACF;AAED;;;;;GAKG;AACH,oBAAY,eAAe;IACzB;;OAEG;IACH,IAAI,SAAS;CACd;AAED;;GAEG;AACH,qBAAa,kBAAkB;IAC7B;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,aAAa,GAAG,IAAI;IAW5D;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,UAAU,GAAG,IAAI;IAW3D;;OAEG;IACH,MAAM,CAAC,iBAAiB,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO;CAGnD"}

package/dist/types/grpc-client.d.ts

@@ -0,0 +1,120 @@
+/**
+ * SochDB gRPC Client - Thin SDK Wrapper
+ *
+ * This module provides a thin gRPC client wrapper for the SochDB server.
+ * All business logic runs on the server (Thick Server / Thin Client architecture).
+ *
+ * The client is approximately ~250 lines of code, delegating all operations to the server.
+ */
+export interface SearchResult {
+    id: number;
+    distance: number;
+}
+export interface Document {
+    id: string;
+    content: string;
+    embedding: number[];
+    metadata: Record<string, string>;
+}
+export interface GraphNode {
+    id: string;
+    nodeType: string;
+    properties: Record<string, string>;
+}
+export interface GraphEdge {
+    fromId: string;
+    edgeType: string;
+    toId: string;
+    properties: Record<string, string>;
+}
+export interface SochDBClientOptions {
+    address?: string;
+    secure?: boolean;
+    protoPath?: string;
+}
+/**
+ * Thin gRPC client for SochDB.
+ *
+ * All operations are delegated to the SochDB gRPC server.
+ * This client provides a TypeScript interface over the gRPC protocol.
+ *
+ * Usage:
+ * ```typescript
+ * const client = new SochDBClient({ address: 'localhost:50051' });
+ *
+ * // Create collection
+ * await client.createCollection('docs', { dimension: 384 });
+ *
+ * // Add documents
+ * await client.addDocuments('docs', [
+ *   { id: '1', content: 'Hello', embedding: [...] }
+ * ]);
+ *
+ * // Search
+ * const results = await client.search('docs', queryVector, 5);
+ * ```
+ */
+export declare class SochDBClient {
+    private address;
+    private credentials;
+    private stubs;
+    private protoPath;
+    private packageDefinition;
+    private proto;
+    constructor(options?: SochDBClientOptions);
+    private getStub;
+    private promisify;
+    /**
+     * Close all gRPC connections.
+     */
+    close(): void;
+    createIndex(name: string, dimension: number, options?: {
+        metric?: string;
+        m?: number;
+        efConstruction?: number;
+    }): Promise<boolean>;
+    insertVectors(indexName: string, ids: number[], vectors: number[][]): Promise<number>;
+    search(indexName: string, query: number[], k?: number, ef?: number): Promise<SearchResult[]>;
+    createCollection(name: string, options: {
+        dimension: number;
+        namespace?: string;
+        metric?: string;
+    }): Promise<boolean>;
+    addDocuments(collectionName: string, documents: Array<{
+        id?: string;
+        content?: string;
+        embedding?: number[];
+        metadata?: Record<string, string>;
+    }>, namespace?: string): Promise<string[]>;
+    searchCollection(collectionName: string, query: number[], k?: number, options?: {
+        namespace?: string;
+        filter?: Record<string, string>;
+    }): Promise<Document[]>;
+    addNode(nodeId: string, nodeType: string, properties?: Record<string, string>, namespace?: string): Promise<boolean>;
+    addEdge(fromId: string, edgeType: string, toId: string, properties?: Record<string, string>, namespace?: string): Promise<boolean>;
+    traverse(startNode: string, options?: {
+        maxDepth?: number;
+        order?: 'bfs' | 'dfs';
+        namespace?: string;
+    }): Promise<{
+        nodes: GraphNode[];
+        edges: GraphEdge[];
+    }>;
+    cacheGet(cacheName: string, queryEmbedding: number[], threshold?: number): Promise<string | null>;
+    cachePut(cacheName: string, key: string, value: string, keyEmbedding: number[], ttlSeconds?: number): Promise<boolean>;
+    startTrace(name: string): Promise<{
+        traceId: string;
+        rootSpanId: string;
+    }>;
+    startSpan(traceId: string, parentSpanId: string, name: string): Promise<string>;
+    endSpan(traceId: string, spanId: string, status?: 'ok' | 'error' | 'unset'): Promise<number>;
+    get(key: Buffer, namespace?: string): Promise<Buffer | null>;
+    put(key: Buffer, value: Buffer, namespace?: string, ttlSeconds?: number): Promise<boolean>;
+    delete(key: Buffer, namespace?: string): Promise<boolean>;
+}
+/**
+ * Connect to SochDB gRPC server.
+ */
+export declare function connect(address?: string, options?: Omit<SochDBClientOptions, 'address'>): SochDBClient;
+export declare const GrpcClient: typeof SochDBClient;
+//# sourceMappingURL=grpc-client.d.ts.map

package/dist/types/grpc-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grpc-client.d.ts","sourceRoot":"","sources":["../../src/grpc-client.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * SochDB Node.js SDK v0.4.0
+ *
+ * Dual-mode architecture: Embedded (FFI) + Server (gRPC/IPC)
+ *
+ * Architecture: Flexible Deployment
+ * ==================================
+ * This SDK supports BOTH modes:
+ *
+ * 1. Embedded Mode (FFI) - For single-process apps:
+ *    - Direct FFI bindings to Rust libraries
+ *    - No server required - just npm install and run
+ *    - Best for: Local development, simple apps
+ *
+ * 2. Server Mode (gRPC/IPC) - For distributed systems:
+ *    - Thin client connecting to sochdb-grpc server
+ *    - Best for: Production, multi-language, scalability
+ *
+ * @example Embedded Mode
+ * ```typescript
+ * import { Database } from '@sochdb/sochdb';
+ *
+ * // Direct FFI - no server needed
+ * const db = await Database.open('./mydb');
+ * await db.put(Buffer.from('key'), Buffer.from('value'));
+ * await db.close();
+ * ```
+ *
+ * @example Server Mode
+ * ```typescript
+ * import { SochDBClient } from '@sochdb/sochdb';
+ *
+ * // Connect to server
+ * const client = new SochDBClient({ address: 'localhost:50051' });
+ * await client.putKv('key', Buffer.from('value'));
+ * ```
+ */
+export declare const VERSION = "0.4.0";
+export { EmbeddedDatabase, EmbeddedDatabaseConfig } from './embedded';
+export { EmbeddedTransaction } from './embedded';
+export { EmbeddedDatabase as Database } from './embedded';
+export { SochDBClient } from './grpc-client';
+export type { SearchResult, Document, GraphNode, GraphEdge, } from './grpc-client';
+export { IpcClient } from './ipc-client';
+export { WireFormat, ContextFormat, CanonicalFormat, FormatCapabilities, FormatConversionError, } from './format';
+export { Query } from './query';
+export type { QueryResult } from './query';
+export { SochDBError, ConnectionError, TransactionError, ProtocolError, DatabaseError, } from './errors';
+export { SochDBClient as GrpcClient } from './grpc-client';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,eAAO,MAAM,OAAO,UAAU,CAAC;AAG/B,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGjD,OAAO,EAAE,gBAAgB,IAAI,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG1D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,YAAY,EACV,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,SAAS,GACV,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGzC,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,OAAO,EACL,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,aAAa,GACd,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,YAAY,IAAI,UAAU,EAAE,MAAM,eAAe,CAAC"}