@plures/praxis 1.1.2 → 1.1.3

package/src/core/pluresdb/README.md

@@ -0,0 +1,156 @@
+# PluresDB Integration
+
+This module provides integration between Praxis and PluresDB for local-first, reactive data storage.
+
+## Overview
+
+Praxis supports PluresDB through a simple adapter interface (`PraxisDB`) that can be backed by:
+
+1. **In-memory storage** (for development/testing) - `InMemoryPraxisDB`
+2. **Official PluresDB** (for production) - `PluresDBPraxisAdapter`
+
+## Using the Official PluresDB
+
+The official PluresDB package from NPM provides a complete local-first database with P2P sync, CRDT conflict resolution, and more.
+
+### Installation
+
+PluresDB is included as a dependency in Praxis:
+
+```bash
+npm install @plures/praxis
+# PluresDB is automatically installed as a dependency
+```
+
+### Basic Usage
+
+```typescript
+import { PluresNode } from 'pluresdb';
+import { createPluresDB, createPraxisDBStore } from '@plures/praxis';
+import { PraxisRegistry } from '@plures/praxis';
+
+// Initialize PluresDB
+const pluresdb = new PluresNode({
+  config: {
+    port: 34567,
+    host: 'localhost',
+    dataDir: './data',
+  },
+  autoStart: true,
+});
+
+// Wrap it with the Praxis adapter
+const db = createPluresDB(pluresdb);
+
+// Use with Praxis store
+const registry = new PraxisRegistry();
+const store = createPraxisDBStore(db, registry);
+
+// Now you can use the store with Praxis engine
+```
+
+### Using with In-Memory Storage (Development)
+
+For testing and development, use the in-memory implementation:
+
+```typescript
+import { createInMemoryDB, createPraxisDBStore } from '@plures/praxis';
+import { PraxisRegistry } from '@plures/praxis';
+
+// Create in-memory database
+const db = createInMemoryDB();
+
+// Use with Praxis store
+const registry = new PraxisRegistry();
+const store = createPraxisDBStore(db, registry);
+```
+
+## API Reference
+
+### PraxisDB Interface
+
+All database adapters implement this interface:
+
+```typescript
+interface PraxisDB {
+  // Get a value by key
+  get<T>(key: string): Promise<T | undefined>;
+  
+  // Set a value by key
+  set<T>(key: string, value: T): Promise<void>;
+  
+  // Watch a key for changes
+  watch<T>(key: string, callback: (val: T) => void): UnsubscribeFn;
+}
+```
+
+### createPluresDB(db)
+
+Creates a Praxis adapter for the official PluresDB package.
+
+**Parameters:**
+- `db`: PluresDB instance (PluresNode or SQLiteCompatibleAPI)
+
+**Returns:** `PluresDBPraxisAdapter` instance
+
+### createInMemoryDB()
+
+Creates an in-memory database for testing/development.
+
+**Returns:** `InMemoryPraxisDB` instance
+
+## Features
+
+### Event Sourcing
+
+Store facts and events in PluresDB:
+
+```typescript
+import { createPraxisEngine, createPluresDBAdapter } from '@plures/praxis';
+
+const adapter = createPluresDBAdapter({ db, registry });
+const engine = createPraxisEngine({ initialContext: {}, registry });
+adapter.attachEngine(engine);
+
+// Events are now persisted to PluresDB
+```
+
+### Reactive Queries
+
+Watch for changes in the database:
+
+```typescript
+const unsubscribe = db.watch('user:123', (user) => {
+  console.log('User updated:', user);
+});
+
+// Later: unsubscribe
+unsubscribe();
+```
+
+## PluresDB Features
+
+The official PluresDB package provides:
+
+- **P2P Graph Database**: Distributed, peer-to-peer data storage
+- **SQLite Compatibility**: 95% SQLite API compatibility
+- **CRDT Conflict Resolution**: Automatic conflict resolution
+- **Vector Search**: Built-in vector embeddings and similarity search
+- **Local-First**: Offline-first data storage with sync when online
+- **Cross-Device Sync**: Automatic synchronization across devices
+
+For more information, see the [PluresDB documentation](https://github.com/plures/pluresdb).
+
+## Migration
+
+If you're using the in-memory implementation and want to migrate to PluresDB:
+
+1. Install PluresDB (already included as dependency)
+2. Replace `createInMemoryDB()` with `createPluresDB(pluresdb)`
+3. The API remains the same - no other code changes needed!
+
+## Notes
+
+- The `PluresDBPraxisAdapter` uses polling to watch for changes (since PluresDB doesn't natively support reactive queries in the current API)
+- For production use, consider the polling interval and adjust if needed
+- The adapter automatically handles cleanup of polling intervals when watchers are removed

package/src/core/pluresdb/adapter.ts

@@ -115,3 +115,168 @@ export class InMemoryPraxisDB implements PraxisDB {
 export function createInMemoryDB(): InMemoryPraxisDB {
   return new InMemoryPraxisDB();
 }
+
+/**
+ * PluresDB instance type - represents either PluresNode or SQLiteCompatibleAPI
+ */
+export type PluresDBInstance = {
+  get(key: string): Promise<any>;
+  put(key: string, value: any): Promise<void>;
+};
+
+/**
+ * Configuration options for PluresDBPraxisAdapter
+ */
+export interface PluresDBAdapterConfig {
+  /** PluresDB instance */
+  db: PluresDBInstance;
+  /** Polling interval in milliseconds for watch functionality (default: 1000ms) */
+  pollInterval?: number;
+}
+
+/**
+ * PluresDB-backed implementation of PraxisDB
+ *
+ * Wraps the official PluresDB package from NPM to provide
+ * the PraxisDB interface for production use.
+ */
+export class PluresDBPraxisAdapter implements PraxisDB {
+  private db: PluresDBInstance;
+  private watchers = new Map<string, Set<(val: unknown) => void>>();
+  private pollIntervals = new Map<string, NodeJS.Timeout>();
+  private lastValues = new Map<string, unknown>();
+  private pollInterval: number;
+
+  constructor(config: PluresDBAdapterConfig | PluresDBInstance) {
+    // Support both old API (direct db instance) and new config API
+    if ('get' in config && 'put' in config) {
+      this.db = config;
+      this.pollInterval = 1000;
+    } else {
+      this.db = config.db;
+      this.pollInterval = config.pollInterval ?? 1000;
+    }
+  }
+
+  async get<T>(key: string): Promise<T | undefined> {
+    try {
+      const value = await this.db.get(key);
+      return value as T | undefined;
+    } catch (error) {
+      // PluresDB returns undefined/null for missing keys
+      return undefined;
+    }
+  }
+
+  async set<T>(key: string, value: T): Promise<void> {
+    await this.db.put(key, value);
+
+    // Update last known value
+    this.lastValues.set(key, value);
+
+    // Notify watchers
+    const keyWatchers = this.watchers.get(key);
+    if (keyWatchers) {
+      for (const callback of keyWatchers) {
+        callback(value);
+      }
+    }
+  }
+
+  watch<T>(key: string, callback: (val: T) => void): UnsubscribeFn {
+    if (!this.watchers.has(key)) {
+      this.watchers.set(key, new Set());
+    }
+
+    const watchers = this.watchers.get(key)!;
+    const wrappedCallback = (val: unknown) => callback(val as T);
+    watchers.add(wrappedCallback);
+
+    // Set up polling for this key if not already set up
+    if (!this.pollIntervals.has(key)) {
+      const interval = setInterval(async () => {
+        try {
+          const value = await this.db.get(key);
+          const lastValue = this.lastValues.get(key);
+          
+          // Only notify if value has actually changed
+          if (JSON.stringify(value) !== JSON.stringify(lastValue)) {
+            this.lastValues.set(key, value);
+            const currentWatchers = this.watchers.get(key);
+            if (currentWatchers) {
+              for (const cb of currentWatchers) {
+                cb(value);
+              }
+            }
+          }
+        } catch (error) {
+          // Ignore errors in polling
+        }
+      }, this.pollInterval);
+
+      this.pollIntervals.set(key, interval);
+    }
+
+    // Return unsubscribe function
+    return () => {
+      watchers.delete(wrappedCallback);
+      if (watchers.size === 0) {
+        this.watchers.delete(key);
+        // Clean up polling interval
+        const interval = this.pollIntervals.get(key);
+        if (interval) {
+          clearInterval(interval);
+          this.pollIntervals.delete(key);
+        }
+        // Clean up last value cache
+        this.lastValues.delete(key);
+      }
+    };
+  }
+
+  /**
+   * Clean up all resources
+   */
+  dispose(): void {
+    // Clear all polling intervals
+    for (const interval of this.pollIntervals.values()) {
+      clearInterval(interval);
+    }
+    this.pollIntervals.clear();
+    this.watchers.clear();
+    this.lastValues.clear();
+  }
+}
+
+/**
+ * Create a PluresDB-backed PraxisDB instance
+ *
+ * Wraps the official PluresDB package from NPM.
+ *
+ * @param config PluresDB instance or configuration object
+ * @returns PluresDBPraxisAdapter instance
+ *
+ * @example
+ * ```typescript
+ * import { PluresNode } from 'pluresdb';
+ * import { createPluresDB } from '@plures/praxis';
+ *
+ * const pluresdb = new PluresNode({ autoStart: true });
+ * const db = createPluresDB(pluresdb);
+ *
+ * await db.set('user:1', { name: 'Alice' });
+ * const user = await db.get('user:1');
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom polling interval
+ * const db = createPluresDB({
+ *   db: pluresdb,
+ *   pollInterval: 500, // Poll every 500ms
+ * });
+ * ```
+ */
+export function createPluresDB(config: PluresDBAdapterConfig | PluresDBInstance): PluresDBPraxisAdapter {
+  return new PluresDBPraxisAdapter(config);
+}

package/src/core/pluresdb/index.ts

@@ -5,9 +5,9 @@
  * It provides the core adapter layer, store, and schema registry.
  */
 
-// Adapter - Core interface and in-memory implementation
-export type { PraxisDB, UnsubscribeFn } from './adapter.js';
-export { InMemoryPraxisDB, createInMemoryDB } from './adapter.js';
+// Adapter - Core interface and implementations (in-memory + PluresDB)
+export type { PraxisDB, UnsubscribeFn, PluresDBInstance, PluresDBAdapterConfig } from './adapter.js';
+export { InMemoryPraxisDB, createInMemoryDB, PluresDBPraxisAdapter, createPluresDB } from './adapter.js';
 
 // Store - Manages facts, events, and reactive updates
 export type { EventStreamEntry, PraxisDBStoreOptions, RuleErrorHandler } from './store.js';

package/src/core/reactive-engine.svelte.ts

@@ -1,39 +1,60 @@
 /**
- * Praxis Reactive Logic Engine
+ * Praxis Reactive Logic Engine - Svelte 5 Implementation
  * 
- * A Svelte 5 native implementation of the Praxis Logic Engine.
- * Uses Runes ($state, $derived, $effect) for fine-grained reactivity.
+ * This version uses Svelte 5 runes ($state) for built-in reactivity.
+ * The state object is automatically reactive when used in Svelte components.
  */
 
+import { PraxisRegistry } from '../core/rules.js';
+import type { PraxisEvent } from '../core/protocol.js';
+import { LogicEngine, createPraxisEngine } from '../core/engine.js';
+
 export interface ReactiveEngineOptions<TContext> {
     initialContext: TContext;
     initialFacts?: any[];
     initialMeta?: Record<string, unknown>;
+    registry?: PraxisRegistry<TContext>;
 }
 
+/**
+ * Reactive Logic Engine using Svelte 5 runes.
+ * Combines the standard LogicEngine with reactive state management.
+ */
 export class ReactiveLogicEngine<TContext extends object> {
-    // The single source of truth, reactive by default
-    // We use $state.raw for things that shouldn't be deeply reactive if needed,
-    // but for context we usually want deep reactivity.
-    state: { context: TContext; facts: any[]; meta: Record<string, unknown> } = $state<{
-        context: TContext;
-        facts: any[];
-        meta: Record<string, unknown>;
-    }>({
+    // Use Svelte's $state rune for automatic reactivity
+    state = $state({
         context: {} as TContext,
-        facts: [],
-        meta: {}
+        facts: [] as any[],
+        meta: {} as Record<string, unknown>
     });
 
+    // Internal engine for logic processing
+    private _engine: LogicEngine<TContext>;
+
     constructor(options: ReactiveEngineOptions<TContext>) {
+        // Initialize reactive state
         this.state.context = options.initialContext;
         this.state.facts = options.initialFacts ?? [];
         this.state.meta = options.initialMeta ?? {};
+
+        // Create internal engine if registry is provided
+        if (options.registry) {
+            this._engine = createPraxisEngine({
+                initialContext: options.initialContext,
+                registry: options.registry,
+            });
+        } else {
+            // Create a basic engine without registry
+            this._engine = createPraxisEngine({
+                initialContext: options.initialContext,
+                registry: new PraxisRegistry<TContext>(),
+            });
+        }
     }
 
     /**
-     * Access the reactive context directly.
-     * Consumers can use this in $derived() or $effect().
+     * Access the reactive context.
+     * In Svelte 5 components, changes to this object will automatically trigger updates.
      */
     get context(): TContext {
         return this.state.context;
@@ -46,9 +67,16 @@ export class ReactiveLogicEngine<TContext extends object> {
         return this.state.facts;
     }
 
+    /**
+     * Access the reactive metadata.
+     */
+    get meta(): Record<string, unknown> {
+        return this.state.meta;
+    }
+
     /**
      * Apply a mutation to the state.
-     * This is the "Action" or "Rule" equivalent.
+     * Changes will automatically trigger Svelte reactivity.
      * 
      * @param mutator A function that receives the state and modifies it.
      */
@@ -57,9 +85,50 @@ export class ReactiveLogicEngine<TContext extends object> {
     }
 
     /**
-     * Access the reactive meta.
+     * Process events through the logic engine and update reactive state.
+     * 
+     * @param events Events to process
      */
-    get meta(): Record<string, unknown> {
-        return this.state.meta;
+    step(events: PraxisEvent[]): void {
+        const result = this._engine.step(events);
+        
+        // Update reactive state with engine results
+        this.state.context = result.state.context as TContext;
+        this.state.facts = result.state.facts;
+        this.state.meta = result.state.meta ?? {};
     }
 }
+
+/**
+ * Create a reactive logic engine with Svelte 5 runes.
+ * 
+ * @param options Configuration options
+ * @returns A reactive logic engine instance
+ * 
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { createReactiveEngine } from '@plures/praxis/svelte';
+ * 
+ *   const engine = createReactiveEngine({
+ *     initialContext: { count: 0 },
+ *     registry
+ *   });
+ * 
+ *   // Use $derived for computed values
+ *   const count = $derived(engine.context.count);
+ *   const doubled = $derived(engine.context.count * 2);
+ * 
+ *   function increment() {
+ *     engine.step([Increment.create({ amount: 1 })]);
+ *   }
+ * </script>
+ * 
+ * <button on:click={increment}>Count: {count}, Doubled: {doubled}</button>
+ * ```
+ */
+export function createReactiveEngine<TContext extends object>(
+    options: ReactiveEngineOptions<TContext>
+): ReactiveLogicEngine<TContext> {
+    return new ReactiveLogicEngine(options);
+}