@claude-flow/memory 3.0.0-alpha.1

package/docs/CROSS_PLATFORM.md

@@ -0,0 +1,505 @@
+# 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