@dikolab/kbdb 0.1.6 → 0.2.0

package/docs/details/library-api.md

@@ -0,0 +1,406 @@
+# Library API Reference
+
+## Overview
+
+kbdb can be used as a library in Node.js and Deno
+projects. The main entry point is
+`createWorkerClient()`, which connects to a
+background worker daemon and returns a typed client
+for all knowledge base operations.
+
+## Installation
+
+```
+npm install @dikolab/kbdb       # Node.js
+deno add @dikolab/kbdb          # Deno
+```
+
+## Quick Start
+
+```typescript
+import { createWorkerClient } from '@dikolab/kbdb';
+
+const client = await createWorkerClient({
+   contextPath: '/path/to/.kbdb',
+});
+
+const results = await client.search({
+   query: 'authentication',
+   limit: 10,
+});
+
+console.log(results);
+client.disconnect();
+```
+
+## API Reference
+
+### Factory
+
+#### `createWorkerClient(options?)`
+
+Creates and connects a `WorkerClient` to the worker
+daemon. Resolves the database path, discovers or
+spawns the daemon, and returns a connected client.
+
+```typescript
+function createWorkerClient(
+   options?: WorkerClientOptions,
+): Promise<WorkerClient>;
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `options.dbPath` | `string?` | Directory containing `.kbdb`. Defaults to `cwd()`. |
+| `options.contextPath` | `string?` | Absolute path to `.kbdb` directory. Skips discovery. |
+| `options.autoSpawn` | `boolean?` | Auto-spawn daemon if not running. Default `true`. |
+| `options.connectTimeoutMs` | `number?` | Max ms to wait for daemon. Default `10000`. |
+| `options.workerScript` | `string?` | Path to worker daemon script. |
+
+---
+
+### Search
+
+#### `search(params)`
+
+Queries the knowledge base and returns ranked
+results.
+
+```typescript
+search(params: SearchParams): Promise<SearchResult[]>
+```
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `params.query` | `string` | Search query string. |
+| `params.mode` | `'sections' \| 'documents' \| 'stats'?` | Entity type to return. Default `'sections'`. |
+| `params.limit` | `number?` | Maximum results to return. |
+
+---
+
+### Sections
+
+#### `readSections(kbids)`
+
+Fetches sections by their knowledge-base
+identifiers.
+
+```typescript
+readSections(kbids: string[]): Promise<Section[]>
+```
+
+#### `addSection(params)`
+
+Imports content as a new section into the knowledge
+base.
+
+```typescript
+addSection(
+   params: AddSectionParams,
+): Promise<AddSectionResult>
+```
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `params.sectionType` | `string` | Semantic type label for the section. |
+| `params.content` | `string` | Raw text content. |
+| `params.docid` | `string?` | Parent document to attach to. |
+
+#### `updateSection(kbid, params)`
+
+Replaces an existing section's content and metadata.
+
+```typescript
+updateSection(
+   kbid: string,
+   params: AddSectionParams,
+): Promise<string>
+```
+
+Returns the knowledge-base identifier of the
+updated section.
+
+#### `removeSection(kbid)`
+
+Deletes a section from the knowledge base.
+
+```typescript
+removeSection(kbid: string): Promise<RemoveSectionResult>
+```
+
+#### `listByType(sectionType)`
+
+Retrieves all sections matching the given type name.
+
+```typescript
+listByType(sectionType: string): Promise<SectionRecord[]>
+```
+
+---
+
+### Documents
+
+#### `groupSections(title, kbids, docType?)`
+
+Creates a document by grouping sections under a
+title.
+
+```typescript
+groupSections(
+   title: string,
+   kbids: string[],
+   docType?: string,
+): Promise<string>
+```
+
+Returns the assigned document identifier.
+
+#### `removeGrouping(docid)`
+
+Removes a document grouping. The sections themselves
+are not deleted.
+
+```typescript
+removeGrouping(docid: string): Promise<void>
+```
+
+#### `retrieveDocument(docid)`
+
+Fetches a full document record including its
+sections.
+
+```typescript
+retrieveDocument(docid: string): Promise<unknown>
+```
+
+#### `listDocumentsByType(docType)`
+
+Retrieves all documents matching the given type
+name.
+
+```typescript
+listDocumentsByType(
+   docType: string,
+): Promise<DocumentManifest[]>
+```
+
+---
+
+### Content
+
+#### `content(ids)`
+
+Composes rendered Markdown from one or more kbid or
+docid identifiers (may be mixed).
+
+```typescript
+content(ids: string[]): Promise<ContentResult>
+```
+
+Returns a `ContentResult` with the composed Markdown
+string and character count.
+
+---
+
+### Maintenance
+
+#### `integrityCheck()`
+
+Verifies database integrity and reports all issues
+found.
+
+```typescript
+integrityCheck(): Promise<IntegrityCheckResult>
+```
+
+#### `gc()`
+
+Garbage collects unreferenced sections from the
+database.
+
+```typescript
+gc(): Promise<GcResult>
+```
+
+#### `rebuildIndexes()`
+
+Reconstructs all index files from section files and
+document manifests on disk.
+
+```typescript
+rebuildIndexes(): Promise<RebuildResult>
+```
+
+#### `initDirectory(targetPath)`
+
+Initialises a new `.kbdb` database directory at the
+given path.
+
+```typescript
+initDirectory(targetPath: string): Promise<void>
+```
+
+#### `migrateDatabase(targetPath)`
+
+Runs all pending database migrations for the
+`.kbdb` directory at the given path.
+
+```typescript
+migrateDatabase(
+   targetPath: string,
+): Promise<MigrateResult>
+```
+
+#### `checkVersion(targetPath)`
+
+Checks format version compatibility of the `.kbdb`
+database against the current WASM engine. Read-only.
+
+```typescript
+checkVersion(
+   targetPath: string,
+): Promise<VersionStatus>
+```
+
+---
+
+### Cache
+
+#### `invalidate(kbid)`
+
+Evicts a single section from the daemon's in-memory
+cache.
+
+```typescript
+invalidate(kbid: string): Promise<void>
+```
+
+#### `invalidateAll()`
+
+Clears all entries from the daemon's in-memory
+cache.
+
+```typescript
+invalidateAll(): Promise<void>
+```
+
+---
+
+### Lifecycle
+
+#### `status()`
+
+Returns diagnostic status including initialization
+state and cache statistics.
+
+```typescript
+status(): Promise<StatusResult>
+```
+
+#### `dbStatus()`
+
+Returns database metadata and status from the
+daemon's cached state.
+
+```typescript
+dbStatus(): Promise<StatusResult>
+```
+
+#### `disconnect()`
+
+Destroys the IPC socket and closes the connection.
+
+```typescript
+disconnect(): void
+```
+
+---
+
+## Types
+
+### `WorkerClientOptions`
+
+```typescript
+interface WorkerClientOptions {
+   readonly dbPath?: string;
+   readonly contextPath?: string;
+   readonly autoSpawn?: boolean;
+   readonly connectTimeoutMs?: number;
+   readonly workerScript?: string;
+}
+```
+
+### `SearchParams`
+
+```typescript
+interface SearchParams {
+   readonly query: string;
+   readonly mode?: 'sections' | 'documents' | 'stats';
+   readonly limit?: number;
+}
+```
+
+### `SearchResult`
+
+```typescript
+interface SearchResult {
+   readonly kbid: string;
+   readonly score: number;
+   readonly matches: readonly {
+      readonly term: string;
+      readonly frequency: number;
+   }[];
+}
+```
+
+### `Section`
+
+```typescript
+interface Section {
+   readonly kbid: string;
+   readonly docid?: string;
+   readonly sectionType: string;
+   readonly content: string;
+   readonly size: number;
+   readonly createdAt: number;
+   readonly checksum: string;
+}
+```
+
+### `AddSectionParams`
+
+```typescript
+interface AddSectionParams {
+   readonly sectionType: string;
+   readonly content: string;
+   readonly docid?: string;
+}
+```
+
+### `StatusResult`
+
+```typescript
+interface StatusResult {
+   readonly initialized: boolean;
+   readonly contextPath: string;
+   readonly cacheStats: {
+      readonly contentCount: number;
+      readonly indexCount: number;
+   };
+}
+```
+
+---
+
+## How It Works
+
+The client spawns a background worker daemon that
+loads the Rust/WASM search engine. Communication
+between the client and daemon happens over a local
+IPC socket using JSON-RPC 2.0 with newline-delimited
+framing. The daemon auto-starts on first use and
+persists across invocations; if the connection drops,
+the client automatically rediscovers or respawns the
+daemon on the next method call.