Skip to content

contextlite 1.1.23

Install from the command line:
Learn more about npm packages
$ npm install @michael-a-kuykendall/contextlite@1.1.23
Install via package.json:
"@michael-a-kuykendall/contextlite": "1.1.23"

About this version

ContextLite npm Package

npm version Node.js versions License: MIT

A Node.js wrapper for ContextLite - an ultra-fast context engine for retrieval and AI applications.

πŸš€ Quick Start

Installation

# Install globally for CLI access
npm install -g contextlite

# Or install locally for programmatic use
npm install contextlite

CLI Usage

# Start ContextLite server
contextlite --port 8080

# Get help
contextlite --help

# Use with npx (no global install needed)
npx contextlite --port 9090

Programmatic Usage

import { ContextLiteClient } from 'contextlite';

// Auto-start server and add documents
const client = new ContextLiteClient();

try {
    // Add some documents
    await client.addDocument("The quick brown fox jumps over the lazy dog.", "doc1");
    await client.addDocument("Node.js is a great runtime for server applications.", "doc2");
    await client.addDocument("TypeScript adds type safety to JavaScript development.", "doc3");
    
    // Query for relevant content
    const results = await client.query("server applications");
    console.log(`Found ${results.documents.length} relevant documents`);
    
    for (const doc of results.documents) {
        console.log(`Score: ${doc.score.toFixed(3)} - ${doc.content.slice(0, 50)}...`);
    }
} finally {
    await client.close();
}

With Auto-cleanup

import { withContextLiteClient } from 'contextlite';

await withContextLiteClient({ port: 8080 }, async (client) => {
    await client.addDocument("Hello from Node.js!");
    const results = await client.query("hello");
    console.log(results);
    // Client automatically closed when function exits
});

πŸ“‹ Features

  • πŸ”₯ Ultra-Fast: Native Go binary performance with Node.js convenience
  • πŸ› οΈ Auto-Management: Automatically detects, downloads, and manages ContextLite binary
  • πŸ”Œ Easy Integration: Simple async/await API with TypeScript support
  • 🌍 Cross-Platform: Works on Windows, macOS, and Linux (x64 and ARM64)
  • πŸ“¦ Zero Config: Works out of the box with automatic binary detection
  • 🎯 CLI Ready: Global installation provides contextlite command

πŸ—οΈ Architecture

This npm package provides Node.js bindings for the high-performance ContextLite engine:

  1. Binary Management: Automatically manages ContextLite binary
  2. Easy Integration: Downloads and configures ContextLite for your platform
  3. Server Management: Handles ContextLite server lifecycle
  4. TypeScript API: Provides fully-typed Node.js interface

πŸ“– API Reference

ContextLiteClient

The main interface for interacting with ContextLite from Node.js.

Constructor

interface ClientOptions {
    host?: string;          // Server host (default: 'localhost')
    port?: number;          // Server port (default: 8080)
    autoStart?: boolean;    // Auto-start server if not running (default: true)
    databasePath?: string;  // Optional database file path
    timeout?: number;       // Request timeout in milliseconds (default: 30000)
}

const client = new ContextLiteClient(options);

Methods

  • addDocument(content, documentId?, metadata?) - Add a document
  • query(query, options?) - Search for documents
  • getDocument(documentId) - Retrieve specific document
  • deleteDocument(documentId) - Delete a document
  • getStats() - Get server statistics
  • isServerRunning() - Check if server is responsive
  • close() - Stop managed server and cleanup

Types

interface QueryOptions {
    maxResults?: number;
    minScore?: number;
}

interface QueryResult {
    documents: Array<{
        id: string;
        content: string;
        score: number;
        metadata?: Record<string, any>;
    }>;
    totalResults: number;
    queryTime: number;
}

interface Document {
    id: string;
    content: string;
    metadata?: Record<string, any>;
}

Error Handling

import { 
    ContextLiteClient,
    ContextLiteError,
    BinaryNotFoundError,
    ServerError
} from 'contextlite';

try {
    const client = new ContextLiteClient();
    await client.query("test");
} catch (error) {
    if (error instanceof BinaryNotFoundError) {
        console.error('ContextLite binary not found');
    } else if (error instanceof ServerError) {
        console.error('Server error:', error.message);
    } else if (error instanceof ContextLiteError) {
        console.error('ContextLite error:', error.message);
    }
}

🌐 Examples

βš™οΈ Dependency Note

We currently pin node-fetch to version 2.x to keep the distributed wrapper CommonJS-compatible. Version 3 of node-fetch is pure ESM and causes runtime errors (ERR_REQUIRE_ESM) when required from the transpiled lib/ output that uses CommonJS. A future update will provide dual ESM/CJS builds; at that point this pin can be lifted.

Document Management

import { ContextLiteClient } from 'contextlite';

const client = new ContextLiteClient();

// Add documents with metadata
await client.addDocument(
    "Advanced TypeScript patterns for scalable applications.",
    "ts-patterns-guide",
    {
        category: "programming",
        difficulty: "advanced",
        tags: ["typescript", "patterns", "scalability"]
    }
);

// Query with options
const results = await client.query(
    "typescript patterns",
    { maxResults: 5, minScore: 0.7 }
);

for (const doc of results.documents) {
    console.log(`Document: ${doc.id}`);
    console.log(`Score: ${doc.score.toFixed(3)}`);
    console.log(`Content: ${doc.content.slice(0, 100)}...`);
    console.log(`Metadata:`, doc.metadata);
    console.log('-'.repeat(50));
}

await client.close();

Batch Operations

import { ContextLiteClient } from 'contextlite';

const documents = [
    "React makes building user interfaces simple and declarative.",
    "Vue.js provides an approachable, versatile framework.",
    "Angular offers a comprehensive platform for web applications.",
    "Svelte compiles to vanilla JavaScript for optimal performance."
];

const client = new ContextLiteClient();

// Batch add documents
for (const [index, content] of documents.entries()) {
    await client.addDocument(content, `framework-${index}`);
}

// Search across all documents
const results = await client.query("web framework");

console.log(`Found ${results.documents.length} relevant documents`);
results.documents.forEach(doc => {
    console.log(`β€’ ${doc.content} (Score: ${doc.score.toFixed(3)})`);
});

await client.close();

Custom Configuration

import { ContextLiteClient } from 'contextlite';

// Connect to existing server
const remoteClient = new ContextLiteClient({
    host: 'my-server.com',
    port: 9090,
    autoStart: false  // Don't try to start server
});

// Use custom database location
const localClient = new ContextLiteClient({
    databasePath: '/path/to/my/database.db',
    port: 8081
});

// Custom timeout and options
const client = new ContextLiteClient({
    timeout: 60000,  // 60 second timeout
    autoStart: true
});

Express.js Integration

import express from 'express';
import { ContextLiteClient } from 'contextlite';

const app = express();
const client = new ContextLiteClient({ port: 8081 });

app.use(express.json());

app.post('/documents', async (req, res) => {
    try {
        const { content, metadata } = req.body;
        const result = await client.addDocument(content, undefined, metadata);
        res.json(result);
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});

app.get('/search', async (req, res) => {
    try {
        const { q, max_results, min_score } = req.query;
        const results = await client.query(q as string, {
            maxResults: max_results ? parseInt(max_results as string) : undefined,
            minScore: min_score ? parseFloat(min_score as string) : undefined
        });
        res.json(results);
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});

const server = app.listen(3000, () => {
    console.log('Server running on port 3000');
});

// Cleanup on shutdown
process.on('SIGTERM', async () => {
    await client.close();
    server.close();
});

πŸ› οΈ Development

Local Development

# Clone the repository
git clone https://github.com/Michael-A-Kuykendall/contextlite.git
cd contextlite/npm-wrapper

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm test

# Link for local testing
npm link

# Test global command
contextlite --help

Testing

# Install jest globally if needed
npm install -g jest

# Run tests with coverage
npm test -- --coverage

# Run specific test file
npm test -- binary-manager.test.ts

Building and Publishing

# Build TypeScript to JavaScript
npm run build

# Check package contents
npm pack

# Publish to npm (requires npm login)
npm publish

πŸ”§ Binary Management

The package handles ContextLite setup automatically:

Installation Process

  1. Platform Detection: Detects your system and architecture
  2. Binary Setup: Downloads and configures ContextLite
  3. Ready to Use: Makes ContextLite available for your application

Manual Installation

You can also install ContextLite binary manually:

# Download from GitHub releases
curl -L https://github.com/Michael-A-Kuykendall/contextlite/releases/latest/download/contextlite_linux_amd64 -o contextlite
chmod +x contextlite
sudo mv contextlite /usr/local/bin/

# Or using npm global install
npm install -g contextlite

πŸ“ Requirements

  • Node.js: 14.0.0+
  • Platform: Windows, macOS, Linux (x64/ARM64)
  • Dependencies: node-fetch, tar
  • ContextLite Binary: Auto-downloaded or manually installed

🚨 Troubleshooting

Binary Not Found

# Manually download and install
npm run postinstall

# Or set NODE_ENV to avoid automatic download
NODE_ENV=development npm install

Permission Issues

# On Unix systems, ensure binary is executable
chmod +x /path/to/contextlite

# Check PATH variable
echo $PATH

Port Conflicts

// Use a different port
const client = new ContextLiteClient({ port: 9090 });

// Or check if port is in use
netstat -tlnp | grep :8080

πŸ“„ License

This npm package is released under the MIT License. The ContextLite binary may have different licensing terms.

πŸ”— Links

πŸ’¬ Support

  • GitHub Issues: For bug reports and feature requests
  • Documentation: Comprehensive guides and API reference
  • npm Community: Package-specific discussions

Built with ❀️ by the ContextLite team. Perfect for Node.js developers who need blazing-fast context retrieval.

Details


Assets

  • contextlite-1.1.23.tgz

Download activity

  • Total downloads 0
  • Last 30 days 0
  • Last week 0
  • Today 0