SiftDB TypeScript Client

Official TypeScript/JavaScript client library for SiftDB HTTP API.

Installation

npm install siftdb

For Node.js environments without built-in fetch support (Node.js < 18), also install:

npm install node-fetch
npm install --save-dev @types/node-fetch

Quick Start

Basic Usage

import { SiftDBClient } from 'siftdb';

// Create client instance
const client = new SiftDBClient({
  baseUrl: 'http://localhost:8080',
  defaultCollection: '/path/to/my/collection'
});

// Search for text
const results = await client.search('function main', {
  pathFilter: '**/*.rs',
  limit: 50
});

console.log(`Found ${results.total_matches} matches in ${results.duration_ms}ms`);
results.results.forEach(hit => {
  console.log(`${hit.file_path}:${hit.line_number}: ${hit.line_content}`);
});

Import Files

// Import files into a collection
const importResult = await client.importFiles('/path/to/source', {
  includePatterns: ['**/*.ts', '**/*.js'],
  excludePatterns: ['**/node_modules/**']
});

console.log(`Imported ${importResult.files_ingested} files`);

List Collections

// List available collections
const collections = await client.listCollections();
collections.collections.forEach(collection => {
  console.log(`${collection.name}: ${collection.total_files} files`);
});

API Reference

Client Configuration

interface ClientOptions {
  baseUrl?: string;        // Default: 'http://localhost:8080'
  timeout?: number;        // Default: 30000 (30 seconds)
  defaultCollection?: string;
}

Search Options

interface SearchOptions {
  collection?: string;     // Override default collection
  pathFilter?: string;     // Glob pattern to filter files
  regex?: boolean;         // Treat query as regex pattern
  limit?: number;          // Max results (default: 1000)
}

Import Options

interface ImportOptions {
  collection?: string;         // Override default collection
  includePatterns?: string[];  // Glob patterns to include
  excludePatterns?: string[];  // Glob patterns to exclude
}

Error Handling

import { SiftDBClient, SiftDBException } from 'siftdb-client';

try {
  const results = await client.search('my query');
} catch (error) {
  if (error instanceof SiftDBException) {
    console.error(`SiftDB Error: ${error.message}`);
    if (error.statusCode) {
      console.error(`HTTP Status: ${error.statusCode}`);
    }
  } else {
    console.error('Unexpected error:', error);
  }
}

Browser Usage

The client works in browsers with built-in fetch support:

<script type="module">
import { SiftDBClient } from 'siftdb';

const client = new SiftDBClient({
  baseUrl: 'https://my-siftdb-server.com'
});

// Use client methods...
</script>

Node.js Usage

For Node.js 18+, no additional dependencies needed. For older versions:

// Install node-fetch first: npm install node-fetch @types/node-fetch
import { SiftDBClient } from 'siftdb';

const client = new SiftDBClient();
// Client will automatically use node-fetch if global fetch is unavailable

License

MIT