@claude-flow/memory 3.0.0-alpha.1 → 3.0.0-alpha.10

package/docs/CROSS_PLATFORM.md

@@ -1,505 +0,0 @@
-# Cross-Platform Database Support
-
-## Overview
-
-The `@claude-flow/memory` module provides **universal cross-platform support** through intelligent database provider selection. This ensures your application works seamlessly on Windows, macOS, and Linux without code changes.
-
-## Architecture
-
-```
-┌─────────────────────────────────────────┐
-│      createDatabase() Factory           │
-│    Platform-Aware Auto-Selection        │
-└──────────────┬──────────────────────────┘
-               │
-       ┌───────┴────────┐
-       │                │
-       ▼                ▼
-┌─────────────┐  ┌─────────────┐
-│   Windows   │  │ macOS/Linux │
-│   Detected  │  │   Detected  │
-└──────┬──────┘  └──────┬──────┘
-       │                │
-       ▼                ▼
-┌─────────────┐  ┌─────────────┐
-│   sql.js    │  │better-sqlite│
-│  (WASM)     │  │  (Native)   │
-└──────┬──────┘  └──────┬──────┘
-       │                │
-       └────────┬────────┘
-                │
-                ▼
-         ┌─────────────┐
-         │JSON Fallback│
-         │ (Universal) │
-         └─────────────┘
-```
-
-## Supported Providers
-
-### 1. better-sqlite3 (Native SQLite)
-
-**Best for:** macOS, Linux
-**Performance:** Fastest (native C++ bindings)
-**Features:**
-- WAL mode for concurrent reads
-- ACID transactions
-- Optimal performance
-- Native compilation required
-
-```typescript
-const db = await createDatabase('./data/memory.db', {
-  provider: 'better-sqlite3',
-  walMode: true,
-  optimize: true
-});
-```
-
-### 2. sql.js (WASM SQLite)
-
-**Best for:** Windows, environments without native compilation
-**Performance:** Good (WebAssembly)
-**Features:**
-- Pure JavaScript/WASM (no native compilation)
-- Works everywhere
-- Auto-persistence to disk
-- Slightly slower than native
-
-```typescript
-const db = await createDatabase('./data/memory.db', {
-  provider: 'sql.js',
-  autoPersistInterval: 5000  // Persist every 5 seconds
-});
-```
-
-### 3. JSON (Simple File Storage)
-
-**Best for:** Maximum compatibility, small datasets
-**Performance:** Slower (brute-force search)
-**Features:**
-- Zero dependencies
-- Human-readable storage
-- Works on all platforms
-- Limited scalability
-
-```typescript
-const db = await createDatabase('./data/memory.db', {
-  provider: 'json'
-});
-```
-
-## Platform-Specific Recommendations
-
-### Windows
-
-```typescript
-// Recommended: sql.js (no native compilation issues)
-const db = await createDatabase('./data/memory.db', {
-  provider: 'sql.js',
-  autoPersistInterval: 10000,  // Auto-save every 10s
-  verbose: true
-});
-```
-
-**Why sql.js on Windows?**
-- No Visual Studio build tools required
-- No Python dependency for node-gyp
-- Pure JavaScript/WASM stack
-- Reliable across Windows versions
-
-### macOS
-
-```typescript
-// Recommended: better-sqlite3 (native performance)
-const db = await createDatabase('./data/memory.db', {
-  provider: 'better-sqlite3',
-  walMode: true,    // Enable WAL mode
-  optimize: true    // Performance optimizations
-});
-```
-
-**Why better-sqlite3 on macOS?**
-- Native compilation works reliably
-- Maximum performance
-- WAL mode for concurrent access
-- Apple's SQLite optimizations
-
-### Linux
-
-```typescript
-// Recommended: better-sqlite3 (native performance)
-const db = await createDatabase('./data/memory.db', {
-  provider: 'better-sqlite3',
-  walMode: true,
-  optimize: true
-});
-```
-
-**Why better-sqlite3 on Linux?**
-- Native SQLite library widely available
-- Excellent performance
-- Production-ready
-- Standard on most distributions
-
-## Automatic Provider Selection
-
-The `createDatabase()` function uses intelligent platform detection:
-
-```typescript
-// Auto-select best provider for current platform
-const db = await createDatabase('./data/memory.db');
-```
-
-**Selection Algorithm:**
-
-1. **Detect platform** (Windows, macOS, Linux)
-2. **Try recommended provider** for platform
-3. **Test provider availability** (compilation check)
-4. **Fallback to alternatives** if needed
-5. **Final fallback** to JSON if all fail
-
-```typescript
-// Example: Auto-selection with fallback chain
-Windows:  sql.js → JSON
-macOS:    better-sqlite3 → sql.js → JSON
-Linux:    better-sqlite3 → sql.js → JSON
-```
-
-## Usage Examples
-
-### Example 1: Cross-Platform Application
-
-```typescript
-import { createDatabase, getPlatformInfo } from '@claude-flow/memory';
-
-async function initDatabase() {
-  const platform = getPlatformInfo();
-  console.log(`Running on ${platform.os}`);
-  console.log(`Recommended: ${platform.recommendedProvider}`);
-
-  // Auto-select best provider
-  const db = await createDatabase('./data/app.db', {
-    verbose: true
-  });
-
-  return db;
-}
-```
-
-### Example 2: Windows-Specific Setup
-
-```typescript
-import { createDatabase } from '@claude-flow/memory';
-
-async function windowsSetup() {
-  // Force sql.js for Windows reliability
-  const db = await createDatabase('./data/windows.db', {
-    provider: 'sql.js',
-    autoPersistInterval: 5000,
-    verbose: true
-  });
-
-  // Store data
-  await db.store({
-    id: 'config-1',
-    key: 'app-config',
-    content: JSON.stringify({ theme: 'dark' }),
-    // ... other fields
-  });
-
-  // Changes auto-persist every 5 seconds
-  // Or manually trigger:
-  await db.persist();
-
-  return db;
-}
-```
-
-### Example 3: Unix Performance Optimization
-
-```typescript
-import { createDatabase, getAvailableProviders } from '@claude-flow/memory';
-
-async function unixSetup() {
-  const available = await getAvailableProviders();
-
-  if (available.betterSqlite3) {
-    // Use native SQLite with optimizations
-    const db = await createDatabase('./data/unix.db', {
-      provider: 'better-sqlite3',
-      walMode: true,        // Concurrent reads
-      optimize: true,       // Performance tuning
-      maxEntries: 1000000   // Large dataset support
-    });
-
-    return db;
-  } else {
-    // Fallback to sql.js
-    const db = await createDatabase('./data/unix.db', {
-      provider: 'sql.js'
-    });
-
-    return db;
-  }
-}
-```
-
-### Example 4: Migration Between Providers
-
-```typescript
-import { createDatabase } from '@claude-flow/memory';
-
-async function migrateDatabase() {
-  // Load from JSON
-  const sourceDb = await createDatabase('./old/data.db', {
-    provider: 'json'
-  });
-
-  const entries = await sourceDb.query({
-    type: 'hybrid',
-    limit: 10000
-  });
-
-  await sourceDb.shutdown();
-
-  // Migrate to SQLite
-  const destDb = await createDatabase('./new/data.db', {
-    provider: 'auto'  // Auto-select best for platform
-  });
-
-  await destDb.bulkInsert(entries);
-  console.log(`Migrated ${entries.length} entries`);
-
-  await destDb.shutdown();
-}
-```
-
-## API Reference
-
-### createDatabase()
-
-```typescript
-async function createDatabase(
-  path: string,
-  options?: DatabaseOptions
-): Promise<IMemoryBackend>
-```
-
-**Parameters:**
-- `path` - Database file path (`:memory:` for in-memory)
-- `options.provider` - Provider type (`'auto'`, `'better-sqlite3'`, `'sql.js'`, `'json'`)
-- `options.verbose` - Enable logging
-- `options.walMode` - Enable WAL mode (better-sqlite3 only)
-- `options.optimize` - Enable optimizations
-- `options.autoPersistInterval` - Auto-save interval in ms (sql.js only)
-- `options.wasmPath` - Custom WASM file path (sql.js only)
-
-**Returns:** Initialized `IMemoryBackend` instance
-
-### getPlatformInfo()
-
-```typescript
-function getPlatformInfo(): PlatformInfo
-```
-
-**Returns:**
-```typescript
-{
-  os: string;                        // 'win32', 'darwin', 'linux'
-  isWindows: boolean;
-  isMacOS: boolean;
-  isLinux: boolean;
-  recommendedProvider: DatabaseProvider;
-}
-```
-
-### getAvailableProviders()
-
-```typescript
-async function getAvailableProviders(): Promise<{
-  betterSqlite3: boolean;
-  sqlJs: boolean;
-  json: boolean;
-}>
-```
-
-**Returns:** Which providers are available and working
-
-## Performance Comparison
-
-| Provider | Read Speed | Write Speed | Memory | Compilation |
-|----------|------------|-------------|--------|-------------|
-| better-sqlite3 | ⚡⚡⚡⚡⚡ | ⚡⚡⚡⚡⚡ | Low | Required |
-| sql.js | ⚡⚡⚡⚡ | ⚡⚡⚡⚡ | Medium | None |
-| JSON | ⚡⚡ | ⚡⚡ | Low | None |
-
-## Installation
-
-### All Platforms
-
-```bash
-npm install @claude-flow/memory
-```
-
-Dependencies are installed automatically:
-- `better-sqlite3` (tries to compile, fails gracefully)
-- `sql.js` (pure JavaScript, always works)
-
-### Windows-Specific
-
-If you encounter compilation errors with `better-sqlite3`:
-
-```bash
-# Skip better-sqlite3 compilation
-npm install @claude-flow/memory --no-optional
-
-# The module will automatically use sql.js
-```
-
-### Linux-Specific
-
-Install SQLite development headers:
-
-```bash
-# Debian/Ubuntu
-sudo apt-get install libsqlite3-dev
-
-# RHEL/Fedora
-sudo yum install sqlite-devel
-
-# Then install
-npm install @claude-flow/memory
-```
-
-## Troubleshooting
-
-### Windows: better-sqlite3 Compilation Fails
-
-**Problem:** `node-gyp` errors, missing Visual Studio
-
-**Solution:** Use sql.js provider (automatic fallback)
-
-```typescript
-const db = await createDatabase('./data/memory.db', {
-  provider: 'sql.js'
-});
-```
-
-### macOS: Code Signing Issues
-
-**Problem:** "cannot be opened because the developer cannot be verified"
-
-**Solution:** Allow native module in System Preferences or use sql.js
-
-```bash
-# Allow native module
-xattr -d com.apple.quarantine node_modules/better-sqlite3/build/Release/better_sqlite3.node
-```
-
-### Linux: Missing SQLite Headers
-
-**Problem:** `sqlite3.h not found`
-
-**Solution:** Install development headers
-
-```bash
-sudo apt-get install libsqlite3-dev
-```
-
-## Best Practices
-
-### 1. Use Auto-Selection in Production
-
-```typescript
-// Let the library choose the best provider
-const db = await createDatabase('./data/memory.db');
-```
-
-### 2. Persist Regularly on Windows
-
-```typescript
-// sql.js is in-memory, persist frequently
-const db = await createDatabase('./data/memory.db', {
-  provider: 'sql.js',
-  autoPersistInterval: 5000  // 5 seconds
-});
-```
-
-### 3. Enable WAL Mode on Unix
-
-```typescript
-// Better concurrency on macOS/Linux
-const db = await createDatabase('./data/memory.db', {
-  provider: 'better-sqlite3',
-  walMode: true
-});
-```
-
-### 4. Check Health Regularly
-
-```typescript
-const health = await db.healthCheck();
-if (health.status !== 'healthy') {
-  console.warn('Database issues:', health.issues);
-  console.log('Recommendations:', health.recommendations);
-}
-```
-
-### 5. Handle Shutdown Gracefully
-
-```typescript
-// Always shutdown to persist changes
-process.on('SIGINT', async () => {
-  await db.shutdown();
-  process.exit(0);
-});
-```
-
-## Environment Variables
-
-```bash
-# Force specific provider
-CLAUDE_FLOW_DB_PROVIDER=sql.js
-
-# Enable verbose logging
-CLAUDE_FLOW_DB_VERBOSE=true
-
-# Set auto-persist interval (ms)
-CLAUDE_FLOW_DB_PERSIST_INTERVAL=10000
-```
-
-## Docker Support
-
-```dockerfile
-FROM node:20-alpine
-
-# Install SQLite for better-sqlite3 (optional)
-RUN apk add --no-cache sqlite-dev python3 make g++
-
-WORKDIR /app
-COPY package*.json ./
-RUN npm install
-
-# Will use better-sqlite3 if compilation succeeds,
-# otherwise falls back to sql.js automatically
-```
-
-## Testing
-
-Run cross-platform tests:
-
-```bash
-# Run all tests
-npm test
-
-# Test specific provider
-npm test -- --grep "sql.js"
-npm test -- --grep "better-sqlite3"
-
-# Test on current platform
-npm test -- src/database-provider.test.ts
-```
-
-## License
-
-MIT