edgevector/README.md

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.

[![npm version](https://badge.fury.io/js/edgevector-sdk.svg)](https://badge.fury.io/js/edgevector-sdk)
[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)

## 🚀 Quick Start

### Installation

```bash
npm install edgevector-sdk
```

### Basic Usage

```typescript
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: 'alice@example.com' });

// 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

```typescript
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

```typescript
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

```typescript
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

```typescript
// 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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
// 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

```typescript
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);
  }
}
```

## 🔗 Links

- [Documentation](https://edgevector.com/docs)
- [API Reference](https://edgevector.com/docs/api)
- [Examples](https://github.com/edgevector/examples)
- [Discord Community](https://discord.gg/edgevector)

## 📝 License

MIT © [EdgeVector Team](https://edgevector.com)

---

## 🤝 Support

- 📧 Email: [support@edgevector.com](mailto:support@edgevector.com)
- 💬 Discord: [Join our community](https://discord.gg/edgevector)
- 📖 Docs: [edgevector.com/docs](https://edgevector.com/docs)
- 🐛 Issues: [GitHub Issues](https://github.com/edgevector/sdk/issues)