@sochdb/sochdb 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +3349 -0
  3. package/_bin/aarch64-apple-darwin/libsochdb_storage.dylib +0 -0
  4. package/_bin/aarch64-apple-darwin/sochdb-bulk +0 -0
  5. package/_bin/aarch64-apple-darwin/sochdb-grpc-server +0 -0
  6. package/_bin/aarch64-apple-darwin/sochdb-server +0 -0
  7. package/_bin/x86_64-pc-windows-msvc/sochdb-bulk.exe +0 -0
  8. package/_bin/x86_64-pc-windows-msvc/sochdb-grpc-server.exe +0 -0
  9. package/_bin/x86_64-pc-windows-msvc/sochdb_storage.dll +0 -0
  10. package/_bin/x86_64-unknown-linux-gnu/libsochdb_storage.so +0 -0
  11. package/_bin/x86_64-unknown-linux-gnu/sochdb-bulk +0 -0
  12. package/_bin/x86_64-unknown-linux-gnu/sochdb-grpc-server +0 -0
  13. package/_bin/x86_64-unknown-linux-gnu/sochdb-server +0 -0
  14. package/bin/sochdb-bulk.js +80 -0
  15. package/bin/sochdb-grpc-server.js +80 -0
  16. package/bin/sochdb-server.js +84 -0
  17. package/dist/cjs/analytics.js +196 -0
  18. package/dist/cjs/database.js +929 -0
  19. package/dist/cjs/embedded/database.js +236 -0
  20. package/dist/cjs/embedded/ffi/bindings.js +113 -0
  21. package/dist/cjs/embedded/ffi/library-finder.js +135 -0
  22. package/dist/cjs/embedded/index.js +14 -0
  23. package/dist/cjs/embedded/transaction.js +172 -0
  24. package/dist/cjs/errors.js +71 -0
  25. package/dist/cjs/format.js +176 -0
  26. package/dist/cjs/grpc-client.js +328 -0
  27. package/dist/cjs/index.js +75 -0
  28. package/dist/cjs/ipc-client.js +504 -0
  29. package/dist/cjs/query.js +154 -0
  30. package/dist/cjs/server-manager.js +295 -0
  31. package/dist/cjs/sql-engine.js +874 -0
  32. package/dist/esm/analytics.js +196 -0
  33. package/dist/esm/database.js +931 -0
  34. package/dist/esm/embedded/database.js +239 -0
  35. package/dist/esm/embedded/ffi/bindings.js +142 -0
  36. package/dist/esm/embedded/ffi/library-finder.js +135 -0
  37. package/dist/esm/embedded/index.js +14 -0
  38. package/dist/esm/embedded/transaction.js +176 -0
  39. package/dist/esm/errors.js +71 -0
  40. package/dist/esm/format.js +179 -0
  41. package/dist/esm/grpc-client.js +333 -0
  42. package/dist/esm/index.js +75 -0
  43. package/dist/esm/ipc-client.js +505 -0
  44. package/dist/esm/query.js +159 -0
  45. package/dist/esm/server-manager.js +295 -0
  46. package/dist/esm/sql-engine.js +875 -0
  47. package/dist/types/analytics.d.ts +66 -0
  48. package/dist/types/analytics.d.ts.map +1 -0
  49. package/dist/types/database.d.ts +523 -0
  50. package/dist/types/database.d.ts.map +1 -0
  51. package/dist/types/embedded/database.d.ts +105 -0
  52. package/dist/types/embedded/database.d.ts.map +1 -0
  53. package/dist/types/embedded/ffi/bindings.d.ts +24 -0
  54. package/dist/types/embedded/ffi/bindings.d.ts.map +1 -0
  55. package/dist/types/embedded/ffi/library-finder.d.ts +17 -0
  56. package/dist/types/embedded/ffi/library-finder.d.ts.map +1 -0
  57. package/dist/types/embedded/index.d.ts +9 -0
  58. package/dist/types/embedded/index.d.ts.map +1 -0
  59. package/dist/types/embedded/transaction.d.ts +21 -0
  60. package/dist/types/embedded/transaction.d.ts.map +1 -0
  61. package/dist/types/errors.d.ts +36 -0
  62. package/dist/types/errors.d.ts.map +1 -0
  63. package/dist/types/format.d.ts +117 -0
  64. package/dist/types/format.d.ts.map +1 -0
  65. package/dist/types/grpc-client.d.ts +120 -0
  66. package/dist/types/grpc-client.d.ts.map +1 -0
  67. package/dist/types/index.d.ts +50 -0
  68. package/dist/types/index.d.ts.map +1 -0
  69. package/dist/types/ipc-client.d.ts +177 -0
  70. package/dist/types/ipc-client.d.ts.map +1 -0
  71. package/dist/types/query.d.ts +85 -0
  72. package/dist/types/query.d.ts.map +1 -0
  73. package/dist/types/server-manager.d.ts +29 -0
  74. package/dist/types/server-manager.d.ts.map +1 -0
  75. package/dist/types/sql-engine.d.ts +100 -0
  76. package/dist/types/sql-engine.d.ts.map +1 -0
  77. package/package.json +90 -0
  78. package/scripts/postinstall.js +50 -0
@@ -0,0 +1,66 @@
1
+ /**
2
+ * SochDB Analytics - Anonymous usage tracking with PostHog
3
+ *
4
+ * This module provides anonymous, privacy-respecting analytics to help
5
+ * improve SochDB. All tracking can be disabled by setting:
6
+ *
7
+ * SOCHDB_DISABLE_ANALYTICS=true
8
+ *
9
+ * No personally identifiable information (PII) is collected. Only aggregate
10
+ * usage patterns are tracked to understand:
11
+ * - Which features are most used
12
+ * - Performance characteristics
13
+ * - Error patterns for debugging
14
+ *
15
+ * Copyright 2025 Sushanth (https://github.com/sushanthpy)
16
+ * Licensed under the Apache License, Version 2.0
17
+ */
18
+ /**
19
+ * Check if analytics is disabled via environment variable.
20
+ *
21
+ * Analytics is disabled when SOCHDB_DISABLE_ANALYTICS is set to 'true', '1', 'yes', or 'on'.
22
+ *
23
+ * @returns true if analytics is disabled
24
+ */
25
+ export declare function isAnalyticsDisabled(): boolean;
26
+ export interface EventProperties {
27
+ [key: string]: string | number | boolean | null | undefined;
28
+ }
29
+ /**
30
+ * Capture an analytics event.
31
+ *
32
+ * This function is a no-op if:
33
+ * - SOCHDB_DISABLE_ANALYTICS=true
34
+ * - posthog-node package is not installed
35
+ * - Any error occurs (fails silently)
36
+ *
37
+ * @param event - Event name (e.g., "database_opened", "vector_search")
38
+ * @param properties - Optional event properties
39
+ * @param distinctId - Optional distinct ID (defaults to anonymous machine ID)
40
+ */
41
+ export declare function capture(event: string, properties?: EventProperties, distinctId?: string): Promise<void>;
42
+ /**
43
+ * Capture an error event for debugging.
44
+ *
45
+ * Only sends static information - no dynamic error messages.
46
+ *
47
+ * @param errorType - Static error category (e.g., "connection_error", "query_error", "timeout_error")
48
+ * @param location - Static code location (e.g., "database.open", "query.execute", "transaction.commit")
49
+ * @param properties - Optional additional static properties only
50
+ *
51
+ * @example
52
+ * ```typescript
53
+ * captureError('connection_error', 'database.open');
54
+ * captureError('query_error', 'sql.execute', { query_type: 'SELECT' });
55
+ * ```
56
+ */
57
+ export declare function captureError(errorType: string, location: string, properties?: EventProperties): Promise<void>;
58
+ /**
59
+ * Flush any pending events and shutdown the client.
60
+ */
61
+ export declare function shutdown(): Promise<void>;
62
+ /**
63
+ * Track database open event.
64
+ */
65
+ export declare function trackDatabaseOpen(dbPath: string, mode?: string): Promise<void>;
66
+ //# sourceMappingURL=analytics.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../../src/analytics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAaH;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAK7C;AAmED,MAAM,WAAW,eAAe;IAC9B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;CAC7D;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,OAAO,CAC3B,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,eAAe,EAC5B,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAgCf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,eAAe,GAC3B,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;GAEG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAY9C;AAID;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,MAAmB,GACxB,OAAO,CAAC,IAAI,CAAC,CAKf"}
@@ -0,0 +1,523 @@
1
+ /**
2
+ * SochDB Embedded Database
3
+ *
4
+ * Direct database access via IPC to the SochDB server.
5
+ * This provides the same API as the Python SDK's Database class.
6
+ *
7
+ * @packageDocumentation
8
+ */
9
+ import { Query } from './query';
10
+ /**
11
+ * Configuration options for the Database.
12
+ */
13
+ export interface DatabaseConfig {
14
+ /** Path to the database directory */
15
+ path: string;
16
+ /** Whether to create the database if it doesn't exist (default: true) */
17
+ createIfMissing?: boolean;
18
+ /** Enable WAL (Write-Ahead Logging) for durability (default: true) */
19
+ walEnabled?: boolean;
20
+ /** Sync mode: 'full' | 'normal' | 'off' (default: 'normal') */
21
+ syncMode?: 'full' | 'normal' | 'off';
22
+ /** Maximum size of the memtable before flushing (default: 64MB) */
23
+ memtableSizeBytes?: number;
24
+ /**
25
+ * Whether to automatically start an embedded server (default: true)
26
+ * Set to false if connecting to an existing external server
27
+ */
28
+ embedded?: boolean;
29
+ }
30
+ /**
31
+ * Result of a SQL query execution.
32
+ */
33
+ export interface SQLQueryResult {
34
+ /** Result rows */
35
+ rows: Array<Record<string, any>>;
36
+ /** Column names */
37
+ columns: string[];
38
+ /** Number of rows affected (for INSERT/UPDATE/DELETE) */
39
+ rowsAffected: number;
40
+ }
41
+ /**
42
+ * Transaction handle for atomic operations.
43
+ */
44
+ export declare class Transaction {
45
+ private _db;
46
+ private _txnId;
47
+ private _committed;
48
+ private _aborted;
49
+ constructor(db: Database);
50
+ /**
51
+ * Begin the transaction.
52
+ * @internal
53
+ */
54
+ begin(): Promise<void>;
55
+ /**
56
+ * Get a value by key within this transaction.
57
+ */
58
+ get(key: Buffer | string): Promise<Buffer | null>;
59
+ /**
60
+ * Put a key-value pair within this transaction.
61
+ */
62
+ put(key: Buffer | string, value: Buffer | string): Promise<void>;
63
+ /**
64
+ * Delete a key within this transaction.
65
+ */
66
+ delete(key: Buffer | string): Promise<void>;
67
+ /**
68
+ * Scan keys with a prefix within this transaction.
69
+ * @param prefix - The prefix to scan for
70
+ * @param end - Optional end boundary (exclusive)
71
+ */
72
+ scan(prefix: string | Buffer, end?: string | Buffer): AsyncGenerator<[Buffer, Buffer]>;
73
+ /**
74
+ * Get a value by path within this transaction.
75
+ */
76
+ getPath(pathStr: string): Promise<Buffer | null>;
77
+ /**
78
+ * Put a value at a path within this transaction.
79
+ */
80
+ putPath(pathStr: string, value: Buffer | string): Promise<void>;
81
+ /**
82
+ * Commit the transaction.
83
+ *
84
+ * After committing, an optional checkpoint is triggered to ensure writes
85
+ * are durable. This prevents race conditions where subsequent reads might
86
+ * not see committed data due to async flush timing.
87
+ */
88
+ commit(): Promise<void>;
89
+ /**
90
+ * Abort/rollback the transaction.
91
+ */
92
+ abort(): Promise<void>;
93
+ private _ensureActive;
94
+ }
95
+ /**
96
+ * SochDB Database client.
97
+ *
98
+ * Provides access to SochDB with full transaction support.
99
+ *
100
+ * @example
101
+ * ```typescript
102
+ * import { Database } from '@sushanth/sochdb';
103
+ *
104
+ * // Open a database
105
+ * const db = await Database.open('./my_database');
106
+ *
107
+ * // Simple key-value operations
108
+ * await db.put(Buffer.from('user:123'), Buffer.from('{"name": "Alice"}'));
109
+ * const value = await db.get(Buffer.from('user:123'));
110
+ *
111
+ * // Path-native API
112
+ * await db.putPath('users/alice/email', Buffer.from('alice@example.com'));
113
+ * const email = await db.getPath('users/alice/email');
114
+ *
115
+ * // Transactions
116
+ * await db.withTransaction(async (txn) => {
117
+ * await txn.put(Buffer.from('key1'), Buffer.from('value1'));
118
+ * await txn.put(Buffer.from('key2'), Buffer.from('value2'));
119
+ * });
120
+ *
121
+ * // Clean up
122
+ * await db.close();
123
+ * ```
124
+ */
125
+ export declare class Database {
126
+ private _client;
127
+ private _config;
128
+ private _closed;
129
+ private _embeddedServerStarted;
130
+ private constructor();
131
+ /**
132
+ * Open a database at the specified path.
133
+ *
134
+ * @param pathOrConfig - Path to the database directory or configuration object
135
+ * @returns A new Database instance
136
+ *
137
+ * @example
138
+ * ```typescript
139
+ * // Simple usage (embedded mode - starts server automatically)
140
+ * const db = await Database.open('./my_database');
141
+ *
142
+ * // With configuration
143
+ * const db = await Database.open({
144
+ * path: './my_database',
145
+ * walEnabled: true,
146
+ * syncMode: 'full',
147
+ * });
148
+ *
149
+ * // Connect to existing external server
150
+ * const db = await Database.open({
151
+ * path: './my_database',
152
+ * embedded: false, // Don't start embedded server
153
+ * });
154
+ * ```
155
+ */
156
+ static open(pathOrConfig: string | DatabaseConfig): Promise<Database>;
157
+ /**
158
+ * Get a value by key.
159
+ *
160
+ * @param key - The key to look up (Buffer or string)
161
+ * @returns The value as a Buffer, or null if not found
162
+ */
163
+ get(key: Buffer | string): Promise<Buffer | null>;
164
+ /**
165
+ * Put a key-value pair.
166
+ *
167
+ * @param key - The key (Buffer or string)
168
+ * @param value - The value (Buffer or string)
169
+ */
170
+ put(key: Buffer | string, value: Buffer | string): Promise<void>;
171
+ /**
172
+ * Delete a key.
173
+ *
174
+ * @param key - The key to delete (Buffer or string)
175
+ */
176
+ delete(key: Buffer | string): Promise<void>;
177
+ /**
178
+ * Get a value by path.
179
+ *
180
+ * @param pathStr - The path (e.g., "users/alice/email")
181
+ * @returns The value as a Buffer, or null if not found
182
+ */
183
+ getPath(pathStr: string): Promise<Buffer | null>;
184
+ /**
185
+ * Put a value at a path.
186
+ *
187
+ * @param pathStr - The path (e.g., "users/alice/email")
188
+ * @param value - The value (Buffer or string)
189
+ */
190
+ putPath(pathStr: string, value: Buffer | string): Promise<void>;
191
+ /**
192
+ * Create a query builder for the given path prefix.
193
+ *
194
+ * @param pathPrefix - The path prefix to query (e.g., "users/")
195
+ * @returns A Query builder instance
196
+ *
197
+ * @example
198
+ * ```typescript
199
+ * const results = await db.query('users/')
200
+ * .limit(10)
201
+ * .select(['name', 'email'])
202
+ * .execute();
203
+ * ```
204
+ */
205
+ query(pathPrefix: string): Query;
206
+ /**
207
+ * Scan for keys with a prefix, returning key-value pairs.
208
+ * This is the preferred method for simple prefix-based iteration.
209
+ *
210
+ * @param prefix - The prefix to scan for (e.g., "users/", "tenants/tenant1/")
211
+ * @returns Array of key-value pairs
212
+ *
213
+ * @example
214
+ * ```typescript
215
+ * const results = await db.scan('tenants/tenant1/');
216
+ * for (const { key, value } of results) {
217
+ * console.log(`${key.toString()}: ${value.toString()}`);
218
+ * }
219
+ * ```
220
+ */
221
+ scan(prefix: string): Promise<Array<{
222
+ key: Buffer;
223
+ value: Buffer;
224
+ }>>;
225
+ /**
226
+ * Scan for keys with a prefix using an async generator.
227
+ * This allows for memory-efficient iteration over large result sets.
228
+ *
229
+ * @param prefix - The prefix to scan for
230
+ * @param end - Optional end boundary (exclusive)
231
+ * @returns Async generator yielding [key, value] tuples
232
+ *
233
+ * @example
234
+ * ```typescript
235
+ * for await (const [key, value] of db.scanGenerator('users/')) {
236
+ * console.log(`${key.toString()}: ${value.toString()}`);
237
+ * }
238
+ * ```
239
+ */
240
+ scanGenerator(prefix: string | Buffer, end?: string | Buffer): AsyncGenerator<[Buffer, Buffer]>;
241
+ /**
242
+ * Execute operations within a transaction.
243
+ *
244
+ * The transaction automatically commits on success or aborts on error.
245
+ *
246
+ * @param fn - Async function that receives a Transaction object
247
+ *
248
+ * @example
249
+ * ```typescript
250
+ * await db.withTransaction(async (txn) => {
251
+ * await txn.put(Buffer.from('key1'), Buffer.from('value1'));
252
+ * await txn.put(Buffer.from('key2'), Buffer.from('value2'));
253
+ * // Automatically commits
254
+ * });
255
+ * ```
256
+ */
257
+ withTransaction<T>(fn: (txn: Transaction) => Promise<T>): Promise<T>;
258
+ /**
259
+ * Create a new transaction.
260
+ *
261
+ * @returns A new Transaction instance
262
+ * @deprecated Use withTransaction() for automatic commit/abort handling
263
+ */
264
+ transaction(): Promise<Transaction>;
265
+ /**
266
+ * Force a checkpoint to persist memtable to disk.
267
+ */
268
+ checkpoint(): Promise<void>;
269
+ /**
270
+ * Get storage statistics.
271
+ */
272
+ stats(): Promise<{
273
+ memtableSizeBytes: number;
274
+ walSizeBytes: number;
275
+ activeTransactions: number;
276
+ }>;
277
+ /**
278
+ * Execute a SQL query.
279
+ *
280
+ * SochDB supports a subset of SQL for relational data stored on top of
281
+ * the key-value engine. Tables and rows are stored as:
282
+ * - Schema: _sql/tables/{table_name}/schema
283
+ * - Rows: _sql/tables/{table_name}/rows/{row_id}
284
+ *
285
+ * Supported SQL:
286
+ * - CREATE TABLE table_name (col1 TYPE, col2 TYPE, ...)
287
+ * - DROP TABLE table_name
288
+ * - INSERT INTO table_name (cols) VALUES (vals)
289
+ * - SELECT cols FROM table_name [WHERE ...] [ORDER BY ...] [LIMIT ...]
290
+ * - UPDATE table_name SET col=val [WHERE ...]
291
+ * - DELETE FROM table_name [WHERE ...]
292
+ *
293
+ * Supported types: INT, TEXT, FLOAT, BOOL, BLOB
294
+ *
295
+ * @param sql - SQL query string
296
+ * @returns SQLQueryResult with rows and metadata
297
+ *
298
+ * @example
299
+ * ```typescript
300
+ * // Create a table
301
+ * await db.execute("CREATE TABLE users (id INT PRIMARY KEY, name TEXT, age INT)");
302
+ *
303
+ * // Insert data
304
+ * await db.execute("INSERT INTO users (id, name, age) VALUES (1, 'Alice', 30)");
305
+ *
306
+ * // Query data
307
+ * const result = await db.execute("SELECT * FROM users WHERE age > 26");
308
+ * result.rows.forEach(row => console.log(row));
309
+ * ```
310
+ */
311
+ execute(sql: string): Promise<SQLQueryResult>;
312
+ /**
313
+ * Convert records to TOON format for token-efficient LLM context.
314
+ *
315
+ * TOON format achieves 40-66% token reduction compared to JSON by using
316
+ * a columnar text format with minimal syntax.
317
+ *
318
+ * @param tableName - Name of the table/collection
319
+ * @param records - Array of objects with the data
320
+ * @param fields - Optional array of field names to include
321
+ * @returns TOON-formatted string
322
+ *
323
+ * @example
324
+ * ```typescript
325
+ * const records = [
326
+ * { id: 1, name: 'Alice', email: 'alice@ex.com' },
327
+ * { id: 2, name: 'Bob', email: 'bob@ex.com' }
328
+ * ];
329
+ * console.log(Database.toToon('users', records, ['name', 'email']));
330
+ * // users[2]{name,email}:Alice,alice@ex.com;Bob,bob@ex.com
331
+ * ```
332
+ */
333
+ static toToon(tableName: string, records: Array<Record<string, any>>, fields?: string[]): string;
334
+ /**
335
+ * Convert records to JSON format for easy application decoding.
336
+ *
337
+ * While TOON format is optimized for LLM context (40-66% token reduction),
338
+ * JSON is often easier for applications to parse. Use this method when
339
+ * the output will be consumed by application code rather than LLMs.
340
+ *
341
+ * @param tableName - Name of the table/collection
342
+ * @param records - Array of objects with the data
343
+ * @param fields - Optional array of field names to include
344
+ * @param compact - If true (default), outputs minified JSON
345
+ * @returns JSON-formatted string
346
+ *
347
+ * @example
348
+ * ```typescript
349
+ * const records = [
350
+ * { id: 1, name: 'Alice' },
351
+ * { id: 2, name: 'Bob' }
352
+ * ];
353
+ * console.log(Database.toJson('users', records));
354
+ * // {"table":"users","count":2,"records":[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]}
355
+ * ```
356
+ */
357
+ static toJson(tableName: string, records: Array<Record<string, any>>, fields?: string[], compact?: boolean): string;
358
+ /**
359
+ * Parse a JSON format string back to structured data.
360
+ *
361
+ * @param jsonStr - JSON-formatted string (from toJson)
362
+ * @returns Object with table, fields, and records
363
+ */
364
+ static fromJson(jsonStr: string): {
365
+ table: string;
366
+ fields: string[];
367
+ records: Array<Record<string, any>>;
368
+ };
369
+ /**
370
+ * Add a node to the graph overlay.
371
+ *
372
+ * @param namespace - Namespace for the graph
373
+ * @param nodeId - Unique node identifier
374
+ * @param nodeType - Type of node (e.g., "person", "document", "concept")
375
+ * @param properties - Optional node properties
376
+ *
377
+ * @example
378
+ * ```typescript
379
+ * await db.addNode('default', 'alice', 'person', { role: 'engineer' });
380
+ * await db.addNode('default', 'project_x', 'project', { status: 'active' });
381
+ * ```
382
+ */
383
+ addNode(namespace: string, nodeId: string, nodeType: string, properties?: Record<string, string>): Promise<void>;
384
+ /**
385
+ * Add an edge between nodes in the graph overlay.
386
+ *
387
+ * @param namespace - Namespace for the graph
388
+ * @param fromId - Source node ID
389
+ * @param edgeType - Type of relationship
390
+ * @param toId - Target node ID
391
+ * @param properties - Optional edge properties
392
+ *
393
+ * @example
394
+ * ```typescript
395
+ * await db.addEdge('default', 'alice', 'works_on', 'project_x');
396
+ * await db.addEdge('default', 'alice', 'knows', 'bob', { since: '2020' });
397
+ * ```
398
+ */
399
+ addEdge(namespace: string, fromId: string, edgeType: string, toId: string, properties?: Record<string, string>): Promise<void>;
400
+ /**
401
+ * Traverse the graph from a starting node.
402
+ *
403
+ * @param namespace - Namespace for the graph
404
+ * @param startNode - Node ID to start traversal from
405
+ * @param maxDepth - Maximum traversal depth (default: 10)
406
+ * @param order - "bfs" for breadth-first, "dfs" for depth-first
407
+ * @returns Object with nodes and edges arrays
408
+ *
409
+ * @example
410
+ * ```typescript
411
+ * const { nodes, edges } = await db.traverse('default', 'alice', 2);
412
+ * for (const node of nodes) {
413
+ * console.log(`Node: ${node.id} (${node.node_type})`);
414
+ * }
415
+ * ```
416
+ */
417
+ traverse(namespace: string, startNode: string, maxDepth?: number, order?: 'bfs' | 'dfs'): Promise<{
418
+ nodes: any[];
419
+ edges: any[];
420
+ }>;
421
+ /**
422
+ * Store a value in the semantic cache with its embedding.
423
+ *
424
+ * @param cacheName - Name of the cache
425
+ * @param key - Cache key (for display/debugging)
426
+ * @param value - Value to cache
427
+ * @param embedding - Embedding vector for similarity matching
428
+ * @param ttlSeconds - Time-to-live in seconds (0 = no expiry)
429
+ *
430
+ * @example
431
+ * ```typescript
432
+ * await db.cachePut(
433
+ * 'llm_responses',
434
+ * 'What is Python?',
435
+ * 'Python is a programming language...',
436
+ * [0.1, 0.2, 0.3, ...], // 384-dim
437
+ * 3600
438
+ * );
439
+ * ```
440
+ */
441
+ cachePut(cacheName: string, key: string, value: string, embedding: number[], ttlSeconds?: number): Promise<void>;
442
+ /**
443
+ * Look up a value in the semantic cache by embedding similarity.
444
+ *
445
+ * @param cacheName - Name of the cache
446
+ * @param queryEmbedding - Query embedding to match against
447
+ * @param threshold - Minimum cosine similarity threshold (0.0 to 1.0)
448
+ * @returns Cached value if similarity >= threshold, null otherwise
449
+ *
450
+ * @example
451
+ * ```typescript
452
+ * const result = await db.cacheGet(
453
+ * 'llm_responses',
454
+ * [0.12, 0.18, ...], // Similar to "What is Python?"
455
+ * 0.85
456
+ * );
457
+ * if (result) {
458
+ * console.log(`Cache hit: ${result}`);
459
+ * }
460
+ * ```
461
+ */
462
+ cacheGet(cacheName: string, queryEmbedding: number[], threshold?: number): Promise<string | null>;
463
+ private _cosineSimilarity;
464
+ /**
465
+ * Start a new trace.
466
+ *
467
+ * @param name - Name of the trace (e.g., "user_request", "batch_job")
468
+ * @returns Object with traceId and rootSpanId
469
+ *
470
+ * @example
471
+ * ```typescript
472
+ * const { traceId, rootSpanId } = await db.startTrace('user_query');
473
+ * // ... do work ...
474
+ * await db.endSpan(traceId, rootSpanId, 'ok');
475
+ * ```
476
+ */
477
+ startTrace(name: string): Promise<{
478
+ traceId: string;
479
+ rootSpanId: string;
480
+ }>;
481
+ /**
482
+ * Start a child span within a trace.
483
+ *
484
+ * @param traceId - ID of the parent trace
485
+ * @param parentSpanId - ID of the parent span
486
+ * @param name - Name of this span
487
+ * @returns The new span ID
488
+ *
489
+ * @example
490
+ * ```typescript
491
+ * const { traceId, rootSpanId } = await db.startTrace('user_query');
492
+ * const dbSpan = await db.startSpan(traceId, rootSpanId, 'database_lookup');
493
+ * // ... do database work ...
494
+ * const duration = await db.endSpan(traceId, dbSpan, 'ok');
495
+ * ```
496
+ */
497
+ startSpan(traceId: string, parentSpanId: string, name: string): Promise<string>;
498
+ /**
499
+ * End a span and record its duration.
500
+ *
501
+ * @param traceId - ID of the trace
502
+ * @param spanId - ID of the span to end
503
+ * @param status - "ok", "error", or "unset"
504
+ * @returns Duration in microseconds
505
+ *
506
+ * @example
507
+ * ```typescript
508
+ * const duration = await db.endSpan(traceId, spanId, 'ok');
509
+ * console.log(`Operation took ${duration}µs`);
510
+ * ```
511
+ */
512
+ endSpan(traceId: string, spanId: string, status?: 'ok' | 'error' | 'unset'): Promise<number>;
513
+ /**
514
+ * Close the database connection.
515
+ * If running in embedded mode, also stops the embedded server.
516
+ */
517
+ close(): Promise<void>;
518
+ private _beginTransaction;
519
+ private _commitTransaction;
520
+ private _abortTransaction;
521
+ private _ensureOpen;
522
+ }
523
+ //# sourceMappingURL=database.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/database.ts"],"names":[],"mappings":"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"}