edgevector-sdk

v1.0.0

Published

8 months ago

Official TypeScript/JavaScript SDK for EdgeVector - Edge-native multi-paradigm database with AI-first features

EdgeVector SDK

The official TypeScript/JavaScript SDK for EdgeVector - the edge-native multi-paradigm database with AI-first features.

🚀 Quick Start

Installation

npm install edgevector-sdk

Basic Usage

import { EdgeVector } from 'edgevector-sdk';

const client = new EdgeVector({
  apiKey: 'your-api-key',
  endpoint: 'https://edgevector-db.finhub.workers.dev'
});

// Document operations
const users = client.collection('users');
await users.insertOne({ name: 'Alice', email: '[email protected]' });

// Vector search
const results = await users.vectorSearch({
  text: 'experienced developer',
  limit: 10
});

// Time series
await client.timeseries('metrics').write({
  metric: 'page_views',
  value: 42,
  timestamp: Date.now()
});

📚 Features

🔍 Multi-Paradigm Database

Document Storage: MongoDB-compatible operations
Vector Search: AI-powered semantic search
Time Series: High-performance metrics storage
SQL Queries: Traditional relational operations

🌍 Edge-Native

Global Distribution: Sub-10ms latency worldwide
Auto-scaling: Handles millions of operations
Real-time: WebSocket and SSE support
Edge Runtime: Optimized for Cloudflare Workers, Vercel Edge

🤖 AI-First

Built-in Embeddings: Text-to-vector conversion
Hybrid Search: Combine vector similarity with filters
Model Flexibility: Support for multiple embedding models
RAG Ready: Perfect for AI applications

📖 Documentation

Document Operations

const collection = client.collection('posts');

// Insert documents
await collection.insertOne({ title: 'Hello', content: 'World' });
await collection.insertMany([
  { title: 'Post 1', tags: ['tech'] },
  { title: 'Post 2', tags: ['ai'] }
]);

// Query documents
const posts = await collection.find({ tags: 'tech' });
const post = await collection.findOne({ title: 'Hello' });

// Update documents
await collection.updateOne(
  { title: 'Hello' },
  { $set: { content: 'Updated!' } }
);

// Delete documents
await collection.deleteOne({ title: 'Hello' });

Vector Search

const vectors = collection.vectors();

// Generate embedding and search
await vectors.similaritySearch('machine learning', { limit: 5 });

// Search with custom vector
await vectors.search([0.1, 0.2, 0.3, ...], {
  filter: { category: 'ai' },
  threshold: 0.8
});

// Hybrid search (vector + metadata)
await collection.hybridSearch({
  text: 'neural networks',
  filter: { published: true },
  limit: 10
});

Time Series

const ts = client.timeseries('metrics');

// Write data points
await ts.write([
  { metric: 'cpu_usage', value: 65.5, tags: { server: 'web-01' } },
  { metric: 'memory', value: 4096, tags: { server: 'web-01' } }
]);

// Query with aggregation
const data = await ts.query({
  metric: 'cpu_usage',
  start: '1h',
  aggregation: 'avg',
  groupBy: ['server']
});

// Anomaly detection
const anomalies = await ts.detectAnomalies('response_time', {
  sensitivity: 0.8
});

Real-time Subscriptions

// Watch collection changes
const unsubscribe = await collection.watch(
  { status: 'active' },
  (change) => {
    console.log('Document changed:', change);
  }
);

// Stream multiple collections
const stream = await client.stream({
  collections: ['users', 'posts'],
  operations: ['insert', 'update']
});

stream.addEventListener('message', (event) => {
  console.log('Real-time update:', JSON.parse(event.data));
});

⚛️ React Integration

import { useCollection, useVectorSearch, useHealth } from 'edgevector-sdk/react';

function App() {
  // Hook for collection operations
  const { data, loading, insertOne } = useCollection('posts');
  
  // Hook for vector search
  const { results, searchByText } = useVectorSearch('posts');
  
  // Hook for health monitoring
  const { health } = useHealth();

  return (
    <div>
      <div>Status: {health?.status}</div>
      <button onClick={() => insertOne({ title: 'New Post' })}>
        Add Post
      </button>
      <button onClick={() => searchByText('machine learning')}>
        Search
      </button>
    </div>
  );
}

🌍 Edge Runtime Support

Cloudflare Workers

import { EdgeVectorEdge } from 'edgevector-sdk/edge';

export default {
  async fetch(request, env, ctx) {
    const client = EdgeVectorEdge.fromWorker(request, env, ctx);
    
    const data = await client.collection('data').find({});
    return client.createResponse(data);
  }
};

Vercel Edge Functions

import { EdgeVectorEdge } from 'edgevector-sdk/edge';

export const config = { runtime: 'edge' };

export default function handler(req: Request) {
  const client = EdgeVectorEdge.fromVercel(req);
  
  // Your edge logic here
  return client.createResponse({ success: true });
}

Next.js Edge API Routes

import { EdgeVectorEdge } from 'edgevector-sdk/edge';
import { NextRequest } from 'next/server';

export const runtime = 'edge';

export async function GET(request: NextRequest) {
  const client = EdgeVectorEdge.fromNextJS(request);
  
  const results = await client.collection('products').find({});
  return client.createResponse(results);
}

🔧 Configuration

const client = new EdgeVector({
  apiKey: 'your-api-key',
  endpoint: 'https://your-endpoint.com',
  timeout: 30000,
  retries: 3,
  cache: true,
  compression: true,
  region: 'us-west',
  headers: {
    'X-App-Name': 'my-app'
  }
});

🧪 Testing

// Quick start helper for development
import { quickStart } from 'edgevector-sdk';

const client = quickStart(process.env.EDGEVECTOR_API_KEY, 'my-app');

// Health check
const health = await client.health();
console.log('Database status:', health.status);

📊 Error Handling

try {
  await collection.insertOne(document);
} catch (error) {
  if (error.message.includes('DUPLICATE_KEY')) {
    console.log('Document already exists');
  } else if (error.message.includes('RATE_LIMIT')) {
    console.log('Rate limited, retry after:', error.retryAfter);
  } else {
    console.error('Unexpected error:', error);
  }
}