@plures/praxis 1.1.2 → 1.2.0

package/dist/browser/index.d.ts

@@ -1,36 +1,85 @@
-import { L as LogicEngine, P as PraxisState, a as PraxisEvent, b as PraxisRegistry, R as RuleDescriptor, C as ConstraintDescriptor, c as PraxisFact, d as RuleFn, e as ConstraintFn, f as PraxisModule } from './engine-BjdqxeXG.js';
-export { m as ConstraintId, k as PRAXIS_PROTOCOL_VERSION, g as PraxisDiagnostics, n as PraxisEngineOptions, h as PraxisStepConfig, j as PraxisStepFn, i as PraxisStepResult, l as RuleId, o as createPraxisEngine } from './engine-BjdqxeXG.js';
+import { L as LogicEngine, P as PraxisState, a as PraxisEvent, b as PraxisRegistry, R as RuleDescriptor, C as ConstraintDescriptor, c as PraxisFact, d as RuleFn, e as ConstraintFn, f as PraxisModule } from './reactive-engine.svelte-C9OpcTHf.js';
+export { m as ConstraintId, k as PRAXIS_PROTOCOL_VERSION, g as PraxisDiagnostics, n as PraxisEngineOptions, h as PraxisStepConfig, j as PraxisStepFn, i as PraxisStepResult, p as ReactiveEngineOptions, q as ReactiveLogicEngine, l as RuleId, o as createPraxisEngine, r as createReactiveEngine } from './reactive-engine.svelte-C9OpcTHf.js';
 
 /**
  * Praxis Reactive Logic Engine
  *
- * A Svelte 5 native implementation of the Praxis Logic Engine.
- * Uses Runes ($state, $derived, $effect) for fine-grained reactivity.
+ * A framework-agnostic reactive implementation of the Praxis Logic Engine.
+ * Uses JavaScript Proxies to provide reactivity without Svelte-specific primitives.
+ *
+ * This implementation provides:
+ * - Proxy-based state tracking for automatic reactivity
+ * - Subscription-based change notifications
+ * - Computed/derived values support
+ * - Compatible API with Svelte-based implementation
  */
 interface ReactiveEngineOptions<TContext> {
     initialContext: TContext;
     initialFacts?: any[];
     initialMeta?: Record<string, unknown>;
 }
+/**
+ * Callback type for state change subscribers
+ */
+type StateChangeCallback<TContext> = (state: {
+    context: TContext;
+    facts: any[];
+    meta: Record<string, unknown>;
+}) => void;
+/**
+ * Callback type for unsubscribe function
+ */
+type UnsubscribeFn$1 = () => void;
+/**
+ * Framework-agnostic reactive logic engine using JavaScript Proxies
+ */
 declare class ReactiveLogicEngine<TContext extends object> {
-    state: {
+    private _state;
+    private _subscribers;
+    private _contextProxy;
+    private _factsProxy;
+    private _metaProxy;
+    private _batchDepth;
+    private _pendingNotification;
+    private _proxyCache;
+    private static readonly ARRAY_MUTATORS;
+    constructor(options: ReactiveEngineOptions<TContext>);
+    /**
+     * Create a reactive proxy that notifies subscribers on changes.
+     * Uses a WeakMap cache to avoid creating multiple proxies for the same object.
+     */
+    private _createReactiveProxy;
+    /**
+     * Notify all subscribers of state changes
+     */
+    private _notify;
+    /**
+     * Get the full state object
+     */
+    get state(): {
         context: TContext;
         facts: any[];
         meta: Record<string, unknown>;
     };
-    constructor(options: ReactiveEngineOptions<TContext>);
     /**
-     * Access the reactive context directly.
-     * Consumers can use this in $derived() or $effect().
+     * Access the reactive context.
+     * Changes to this object will trigger subscriber notifications.
      */
     get context(): TContext;
     /**
      * Access the reactive facts list.
+     * Changes to this array will trigger subscriber notifications.
      */
     get facts(): any[];
+    /**
+     * Access the reactive metadata.
+     * Changes to this object will trigger subscriber notifications.
+     */
+    get meta(): Record<string, unknown>;
     /**
      * Apply a mutation to the state.
      * This is the "Action" or "Rule" equivalent.
+     * Mutations are batched - notifications only happen once per apply call.
      *
      * @param mutator A function that receives the state and modifies it.
      */
@@ -40,10 +89,54 @@ declare class ReactiveLogicEngine<TContext extends object> {
         meta: Record<string, unknown>;
     }) => void): void;
     /**
-     * Access the reactive meta.
+     * Subscribe to state changes.
+     * Returns an unsubscribe function.
+     *
+     * @param callback Function to call when state changes
+     * @returns Unsubscribe function
      */
-    get meta(): Record<string, unknown>;
+    subscribe(callback: StateChangeCallback<TContext>): UnsubscribeFn$1;
+    /**
+     * Create a derived/computed value from the state.
+     * The selector function will be called whenever the state changes.
+     *
+     * @param selector Function to extract derived value from state
+     * @returns Object with subscribe method for reactive updates
+     */
+    $derived<TDerived>(selector: (state: {
+        context: TContext;
+        facts: any[];
+        meta: Record<string, unknown>;
+    }) => TDerived): {
+        subscribe: (callback: (value: TDerived) => void) => UnsubscribeFn$1;
+    };
 }
+/**
+ * Create a new reactive logic engine instance.
+ *
+ * @param options Configuration options for the reactive engine
+ * @returns A new ReactiveLogicEngine instance
+ *
+ * @example
+ * ```typescript
+ * const engine = createReactiveEngine({
+ *   initialContext: { count: 0 },
+ *   initialFacts: [],
+ *   initialMeta: {}
+ * });
+ *
+ * // Subscribe to changes
+ * engine.subscribe((state) => {
+ *   console.log('State changed:', state);
+ * });
+ *
+ * // Mutate state (will trigger subscribers)
+ * engine.apply((state) => {
+ *   state.context.count++;
+ * });
+ * ```
+ */
+declare function createReactiveEngine<TContext extends object>(options: ReactiveEngineOptions<TContext>): ReactiveLogicEngine<TContext>;
 
 /**
  * Actors System
@@ -915,6 +1008,73 @@ declare class InMemoryPraxisDB implements PraxisDB {
  * ```
  */
 declare function createInMemoryDB(): InMemoryPraxisDB;
+/**
+ * PluresDB instance type - represents either PluresNode or SQLiteCompatibleAPI
+ */
+type PluresDBInstance = {
+    get(key: string): Promise<any>;
+    put(key: string, value: any): Promise<void>;
+};
+/**
+ * Configuration options for PluresDBPraxisAdapter
+ */
+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.
+ */
+declare class PluresDBPraxisAdapter implements PraxisDB {
+    private db;
+    private watchers;
+    private pollIntervals;
+    private lastValues;
+    private pollInterval;
+    constructor(config: PluresDBAdapterConfig | PluresDBInstance);
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T): Promise<void>;
+    watch<T>(key: string, callback: (val: T) => void): UnsubscribeFn;
+    /**
+     * Clean up all resources
+     */
+    dispose(): void;
+}
+/**
+ * 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
+ * });
+ * ```
+ */
+declare function createPluresDB(config: PluresDBAdapterConfig | PluresDBInstance): PluresDBPraxisAdapter;
 
 /**
  * PraxisDB Store
@@ -3001,4 +3161,133 @@ declare function attachTauriToEngine<TContext>(engine: LogicEngine<TContext>, ad
  */
 declare function generateTauriConfig(config: TauriAppConfig): Record<string, unknown>;
 
-export { type ActivityState, type Actor, ActorManager, type CanvasDocument, type CanvasEdge, type CanvasEdgeStyle, type CanvasEditorConfig, type CanvasNode, type CanvasNodeStyle, type ComponentDefinition, ConstraintDescriptor, ConstraintFn, type ConstraintNode, type ConstraintSchema, type DefineConstraintOptions, type DefineModuleOptions, type DefineRuleOptions, type EventDefinition$1 as EventDefinition, type EventStreamEntry, type FactDefinition$1 as FactDefinition, type GeneratedDoc, type GeneratedPluresDBFile, type GraphEdge, type GuardianError, type GuardianResult, type GuardianWarning, InMemoryPraxisDB, type LifecycleState, type LoaderOptions, type LoaderResult, type LogicDefinition, LogicEngine, type ModelDefinition, type NodeBindings, type NodeDefinition, type OrchestrationDefinition, PRAXIS_PATHS, type PluresDBAdapter, type PluresDBAdapterOptions, PluresDBGenerator, type PluresDBGeneratorOptions, type PraxisDB, PraxisDBStore, type PraxisDBStoreOptions, PraxisEvent, PraxisFact, PraxisModule, PraxisRegistry, type PraxisSchema, PraxisSchemaRegistry, PraxisState, type ReactiveEngineOptions, ReactiveLogicEngine, type RegistryGraph, RegistryIntrospector, type RegistrySchema, type RegistryStats, RuleDescriptor, RuleFn, type RuleNode, type RuleSchema, type StateDoc, type StateDocsConfig, StateDocsGenerator, type StateMachineDoc, type StoredSchema, type TauriAppConfig, type TauriBridge, type TauriCommand, type TauriEvent, type TauriFS, type TauriFileEntry, type TauriMenuItem, type TauriNotification, type TauriNotificationOptions, type TauriPlugin, type TauriPraxisAdapter, type TauriSecurityConfig, type TauriTray, type TauriUpdateConfig, type TauriUpdateInfo, type TauriWindowConfig, type TerminalNodeProps, type TransitionDoc, type UnsubscribeFn, type UnumAdapter, type UnumAdapterConfig, type UnumChannel, type UnumIdentity, type UnumMessage, type UnumStore, type ValidationError, type ValidationResult, attachTauriToEngine, attachToEngine, attachUnumToEngine, canvasToMermaid, canvasToSchema, canvasToYaml, createCanvasEditor, createInMemoryDB, createIntrospector, createMockTauriBridge, createPluresDBAdapter, createPluresDBGenerator, createPraxisDBStore, createSchema, createSchemaRegistry, createSchemaTemplate, createStateDocsGenerator, createTauriPraxisAdapter, createTimerActor, createUnumAdapter, defineConstraint, defineEvent, defineFact, defineModule, defineRule, filterEvents, filterFacts, findEvent, findFact, generateDocs, generateId, generateTauriConfig, getEventPath, getFactPath, getSchemaPath, loadSchemaFromJson, loadSchemaFromYaml, registerSchema, schemaToCanvas, validateForGeneration, validateSchema, validateWithGuardian };
+/**
+ * Unified Integration Helpers
+ *
+ * Convenience functions for setting up Praxis with all ecosystem integrations
+ * (PluresDB, Unum, State-Docs, CodeCanvas) in a single call.
+ */
+
+/**
+ * Configuration for unified Praxis application
+ */
+interface UnifiedAppConfig<TContext = unknown> {
+    /** Praxis registry with rules and constraints */
+    registry: PraxisRegistry<TContext>;
+    /** Initial context for the engine */
+    initialContext: TContext;
+    /** PluresDB instance (if not provided, creates in-memory DB) */
+    db?: PraxisDB;
+    /** Enable Unum for distributed communication */
+    enableUnum?: boolean;
+    /** Unum identity configuration (without id and createdAt which are auto-generated) */
+    unumIdentity?: Omit<UnumIdentity, 'id' | 'createdAt'>;
+    /** Enable State-Docs documentation generation */
+    enableDocs?: boolean;
+    /** State-Docs configuration */
+    docsConfig?: {
+        projectTitle: string;
+        target?: string;
+    };
+    /** Praxis schema for CodeCanvas integration */
+    schema?: PraxisSchema;
+}
+/**
+ * Unified application instance with all integrations
+ */
+interface UnifiedApp<TContext = unknown> {
+    /** Praxis logic engine */
+    engine: LogicEngine<TContext>;
+    /** PluresDB adapter for persistence */
+    pluresdb: PluresDBAdapter<TContext>;
+    /** Unum adapter for distributed communication (if enabled) */
+    unum?: UnumAdapter;
+    /** Default Unum channel (if Unum enabled) */
+    channel?: UnumChannel;
+    /** State-Docs generator (if enabled) */
+    docs?: StateDocsGenerator;
+    /** CodeCanvas document (if schema provided) */
+    canvas?: CanvasDocument;
+    /** Generate documentation from current state */
+    generateDocs?: () => GeneratedDoc[];
+    /** Cleanup function to dispose all integrations */
+    dispose: () => void;
+}
+/**
+ * Create a unified Praxis application with all integrations
+ *
+ * This is a convenience function that sets up:
+ * - Praxis logic engine
+ * - PluresDB for persistence (auto-attaches to engine)
+ * - Unum for distributed communication (optional)
+ * - State-Docs for documentation generation (optional)
+ * - CodeCanvas for visual schema editing (optional)
+ *
+ * @example
+ * ```typescript
+ * import { createUnifiedApp } from '@plures/praxis';
+ *
+ * const app = await createUnifiedApp({
+ *   registry: myRegistry,
+ *   initialContext: { count: 0 },
+ *   enableUnum: true,
+ *   unumIdentity: { name: 'node-1' },
+ *   enableDocs: true,
+ *   docsConfig: { projectTitle: 'My App' },
+ *   schema: mySchema,
+ * });
+ *
+ * // Use the engine
+ * app.engine.step([myEvent]);
+ *
+ * // Broadcast to other nodes
+ * if (app.channel) {
+ *   await app.unum?.broadcastEvent(app.channel.id, myEvent);
+ * }
+ *
+ * // Generate documentation
+ * const docs = app.generateDocs?.();
+ *
+ * // Cleanup
+ * app.dispose();
+ * ```
+ */
+declare function createUnifiedApp<TContext = unknown>(config: UnifiedAppConfig<TContext>): Promise<UnifiedApp<TContext>>;
+/**
+ * Attach all available integrations to an existing Praxis engine
+ *
+ * This is useful when you already have an engine and want to add integrations.
+ *
+ * @example
+ * ```typescript
+ * import { createPraxisEngine, attachAllIntegrations } from '@plures/praxis';
+ *
+ * const engine = createPraxisEngine({ initialContext: {}, registry });
+ *
+ * const integrations = await attachAllIntegrations(engine, registry, {
+ *   enableUnum: true,
+ *   enableDocs: true,
+ * });
+ *
+ * // Later cleanup
+ * integrations.dispose();
+ * ```
+ */
+declare function attachAllIntegrations<TContext = unknown>(engine: LogicEngine<TContext>, registry: PraxisRegistry<TContext>, options?: {
+    db?: PraxisDB;
+    enableUnum?: boolean;
+    unumIdentity?: Omit<UnumIdentity, 'id' | 'createdAt'>;
+    enableDocs?: boolean;
+    docsConfig?: {
+        projectTitle: string;
+        target?: string;
+    };
+}): Promise<{
+    pluresdb: PluresDBAdapter<TContext>;
+    unum?: UnumAdapter;
+    channel?: UnumChannel;
+    docs?: StateDocsGenerator;
+    dispose: () => void;
+}>;
+
+export { type ActivityState, type Actor, ActorManager, type CanvasDocument, type CanvasEdge, type CanvasEdgeStyle, type CanvasEditorConfig, type CanvasNode, type CanvasNodeStyle, type ComponentDefinition, ConstraintDescriptor, ConstraintFn, type ConstraintNode, type ConstraintSchema, type DefineConstraintOptions, type DefineModuleOptions, type DefineRuleOptions, type EventDefinition$1 as EventDefinition, type EventStreamEntry, type FactDefinition$1 as FactDefinition, ReactiveLogicEngine as FrameworkAgnosticReactiveEngine, type ReactiveEngineOptions as FrameworkAgnosticReactiveEngineOptions, type GeneratedDoc, type GeneratedPluresDBFile, type GraphEdge, type GuardianError, type GuardianResult, type GuardianWarning, InMemoryPraxisDB, type LifecycleState, type LoaderOptions, type LoaderResult, type LogicDefinition, LogicEngine, type ModelDefinition, type NodeBindings, type NodeDefinition, type OrchestrationDefinition, PRAXIS_PATHS, type PluresDBAdapter, type PluresDBAdapterConfig, type PluresDBAdapterOptions, PluresDBGenerator, type PluresDBGeneratorOptions, type PluresDBInstance, PluresDBPraxisAdapter, type PraxisDB, PraxisDBStore, type PraxisDBStoreOptions, PraxisEvent, PraxisFact, PraxisModule, PraxisRegistry, type PraxisSchema, PraxisSchemaRegistry, PraxisState, type RegistryGraph, RegistryIntrospector, type RegistrySchema, type RegistryStats, RuleDescriptor, RuleFn, type RuleNode, type RuleSchema, type StateChangeCallback, type StateDoc, type StateDocsConfig, StateDocsGenerator, type StateMachineDoc, type StoredSchema, type TauriAppConfig, type TauriBridge, type TauriCommand, type TauriEvent, type TauriFS, type TauriFileEntry, type TauriMenuItem, type TauriNotification, type TauriNotificationOptions, type TauriPlugin, type TauriPraxisAdapter, type TauriSecurityConfig, type TauriTray, type TauriUpdateConfig, type TauriUpdateInfo, type TauriWindowConfig, type TerminalNodeProps, type TransitionDoc, type UnifiedApp, type UnifiedAppConfig, type UnsubscribeFn, type UnumAdapter, type UnumAdapterConfig, type UnumChannel, type UnumIdentity, type UnumMessage, type UnumStore, type ValidationError, type ValidationResult, attachAllIntegrations, attachTauriToEngine, attachToEngine, attachUnumToEngine, canvasToMermaid, canvasToSchema, canvasToYaml, createCanvasEditor, createReactiveEngine as createFrameworkAgnosticReactiveEngine, createInMemoryDB, createIntrospector, createMockTauriBridge, createPluresDB, createPluresDBAdapter, createPluresDBGenerator, createPraxisDBStore, createSchema, createSchemaRegistry, createSchemaTemplate, createStateDocsGenerator, createTauriPraxisAdapter, createTimerActor, createUnifiedApp, createUnumAdapter, defineConstraint, defineEvent, defineFact, defineModule, defineRule, filterEvents, filterFacts, findEvent, findFact, generateDocs, generateId, generateTauriConfig, getEventPath, getFactPath, getSchemaPath, loadSchemaFromJson, loadSchemaFromYaml, registerSchema, schemaToCanvas, validateForGeneration, validateSchema, validateWithGuardian };