@plures/praxis 1.0.3 → 1.1.0

package/dist/node/integrations/svelte.d.ts

@@ -0,0 +1,309 @@
+import { L as LogicEngine } from '../engine-1iqLe6_P.js';
+import { P as PraxisState, a as PraxisEvent } from '../protocol-Qek7ebBl.js';
+
+/**
+ * Svelte v5 Integration
+ *
+ * Provides reactive bindings for Praxis logic engines in Svelte v5 applications.
+ * Supports both traditional stores and modern Svelte 5 runes ($state, $derived, $effect).
+ *
+ * Features:
+ * - Store-based API for backward compatibility
+ * - Runes-based composables for Svelte 5
+ * - Snapshot support for time-travel debugging
+ * - History state pattern implementation
+ * - Automatic cleanup and subscription management
+ */
+
+/**
+ * Writable store interface (Svelte-compatible)
+ */
+interface Writable<T> {
+    subscribe(run: (value: T) => void): () => void;
+    set(value: T): void;
+    update(updater: (value: T) => T): void;
+}
+/**
+ * Readable store interface (Svelte-compatible)
+ */
+interface Readable<T> {
+    subscribe(run: (value: T) => void): () => void;
+}
+/**
+ * Create a reactive Svelte store from a Praxis engine.
+ *
+ * The store tracks the engine's state and provides methods to dispatch events.
+ *
+ * @example
+ * const engine = createPraxisEngine({ ... });
+ * const store = createPraxisStore(engine);
+ *
+ * // In Svelte component:
+ * $: state = $store;
+ *
+ * // Dispatch events:
+ * store.dispatch([Login.create({ username: "alice", password: "secret" })]);
+ */
+declare function createPraxisStore<TContext = unknown>(engine: LogicEngine<TContext>): Readable<Readonly<PraxisState & {
+    context: TContext;
+}>> & {
+    dispatch: (events: PraxisEvent[]) => void;
+};
+/**
+ * Create a derived store that extracts the context from the engine state.
+ *
+ * @example
+ * const engine = createPraxisEngine({ ... });
+ * const contextStore = createContextStore(engine);
+ *
+ * // In Svelte component:
+ * $: context = $contextStore;
+ */
+declare function createContextStore<TContext = unknown>(engine: LogicEngine<TContext>): Readable<TContext> & {
+    dispatch: (events: PraxisEvent[]) => void;
+};
+/**
+ * Create a derived store that extracts specific data from the context.
+ *
+ * @example
+ * const engine = createPraxisEngine<{ count: number }>({ ... });
+ * const countStore = createDerivedStore(engine, (ctx) => ctx.count);
+ *
+ * // In Svelte component:
+ * $: count = $countStore;
+ */
+declare function createDerivedStore<TContext = unknown, TDerived = unknown>(engine: LogicEngine<TContext>, selector: (context: TContext) => TDerived): Readable<TDerived> & {
+    dispatch: (events: PraxisEvent[]) => void;
+};
+/**
+ * Snapshot of engine state for time-travel debugging
+ */
+interface StateSnapshot<TContext = unknown> {
+    timestamp: number;
+    state: Readonly<PraxisState & {
+        context: TContext;
+    }>;
+    events: PraxisEvent[];
+}
+/**
+ * Options for usePraxisEngine composable
+ */
+interface UsePraxisEngineOptions {
+    /** Enable snapshot history for time-travel debugging */
+    enableHistory?: boolean;
+    /** Maximum number of snapshots to keep */
+    maxHistorySize?: number;
+}
+/**
+ * Result of usePraxisEngine composable with Svelte 5 runes
+ */
+interface PraxisEngineBinding<TContext = unknown> {
+    /** Current state (reactive via $state) */
+    state: Readonly<PraxisState & {
+        context: TContext;
+    }>;
+    /** Current context (reactive via $state) */
+    context: TContext;
+    /** Current facts (reactive via $state) */
+    facts: PraxisState['facts'];
+    /** Dispatch events to the engine */
+    dispatch: (events: PraxisEvent[]) => void;
+    /** History snapshots (if enabled) */
+    snapshots: StateSnapshot<TContext>[];
+    /** Navigate to a specific snapshot index */
+    goToSnapshot: (index: number) => void;
+    /** Undo last action (go back one snapshot) */
+    undo: () => void;
+    /** Redo action (go forward one snapshot) */
+    redo: () => void;
+    /** Check if undo is available */
+    canUndo: boolean;
+    /** Check if redo is available */
+    canRedo: boolean;
+    /** Current position in history */
+    historyIndex: number;
+}
+/**
+ * Create a reactive binding to a Praxis engine with Svelte 5 runes support.
+ *
+ * This composable provides a runes-compatible API for integrating Praxis
+ * with Svelte 5 components. The returned state is reactive and will
+ * automatically update the component when the engine state changes.
+ *
+ * Note: The history/snapshot feature tracks state snapshots but doesn't
+ * restore the engine to previous states. When you navigate history (undo/redo),
+ * you're viewing past snapshots, but new events are still applied to the
+ * current engine state. For true undo/redo, use createHistoryEngine or
+ * implement state restoration in your application logic.
+ *
+ * @example
+ * <script>
+ *   import { usePraxisEngine } from '@plures/praxis/svelte';
+ *   import { createMyEngine } from './my-engine';
+ *
+ *   const engine = createMyEngine();
+ *   const { context, dispatch, undo, canUndo } = usePraxisEngine(engine, {
+ *     enableHistory: true
+ *   });
+ * </script>
+ *
+ * <div>
+ *   <p>Count: {context.count}</p>
+ *   <button onclick={() => dispatch([Increment.create({})])}>+</button>
+ *   <button onclick={() => undo()} disabled={!canUndo}>Undo</button>
+ * </div>
+ *
+ * @param engine The Praxis logic engine
+ * @param options Configuration options
+ * @returns Reactive binding with state, context, and control methods
+ */
+declare function usePraxisEngine<TContext = unknown>(engine: LogicEngine<TContext>, options?: UsePraxisEngineOptions): PraxisEngineBinding<TContext>;
+/**
+ * Create a reactive derived value from engine context with Svelte 5 runes.
+ *
+ * This composable extracts and tracks a specific value from the engine context.
+ * The returned value is reactive and will update when the selected value changes.
+ *
+ * @example
+ * <script>
+ *   import { usePraxisContext } from '@plures/praxis/svelte';
+ *
+ *   const engine = createMyEngine();
+ *   const count = usePraxisContext(engine, (ctx) => ctx.count);
+ * </script>
+ *
+ * <p>Count: {count}</p>
+ *
+ * @param engine The Praxis logic engine
+ * @param selector Function to extract value from context
+ * @returns Reactive derived value
+ */
+declare function usePraxisContext<TContext = unknown, TDerived = unknown>(engine: LogicEngine<TContext>, selector: (context: TContext) => TDerived): TDerived;
+/**
+ * Subscribe to engine state changes with automatic cleanup.
+ *
+ * This composable sets up a subscription to engine state changes and
+ * automatically cleans up when the component is destroyed.
+ *
+ * @example
+ * <script>
+ *   import { usePraxisSubscription } from '@plures/praxis/svelte';
+ *
+ *   const engine = createMyEngine();
+ *
+ *   usePraxisSubscription(engine, (state) => {
+ *     console.log('State changed:', state);
+ *   });
+ * </script>
+ *
+ * @param engine The Praxis logic engine
+ * @param callback Function to call when state changes
+ */
+declare function usePraxisSubscription<TContext = unknown>(engine: LogicEngine<TContext>, callback: (state: Readonly<PraxisState & {
+    context: TContext;
+}>) => void): () => void;
+/**
+ * History state entry for tracking state transitions
+ */
+interface HistoryEntry<TContext = unknown> {
+    /** Unique identifier for this history entry */
+    id: string;
+    /** Timestamp when this state was entered */
+    timestamp: number;
+    /** State snapshot */
+    state: Readonly<PraxisState & {
+        context: TContext;
+    }>;
+    /** Events that led to this state */
+    events: PraxisEvent[];
+    /** Optional label for this history entry */
+    label?: string;
+}
+/**
+ * History state manager for Praxis engines
+ */
+declare class HistoryStateManager<TContext = unknown> {
+    private history;
+    private currentIndex;
+    private readonly maxSize;
+    private idCounter;
+    constructor(maxSize?: number);
+    /**
+     * Record a new history entry
+     */
+    record(state: Readonly<PraxisState & {
+        context: TContext;
+    }>, events: PraxisEvent[], label?: string): void;
+    /**
+     * Navigate to a specific history entry
+     */
+    goTo(index: number): HistoryEntry<TContext> | null;
+    /**
+     * Go back to previous state
+     */
+    back(): HistoryEntry<TContext> | null;
+    /**
+     * Go forward to next state
+     */
+    forward(): HistoryEntry<TContext> | null;
+    /**
+     * Check if can go back
+     */
+    canGoBack(): boolean;
+    /**
+     * Check if can go forward
+     */
+    canGoForward(): boolean;
+    /**
+     * Get current history entry
+     */
+    current(): HistoryEntry<TContext> | null;
+    /**
+     * Get all history entries
+     */
+    getHistory(): ReadonlyArray<HistoryEntry<TContext>>;
+    /**
+     * Get current index in history
+     */
+    getCurrentIndex(): number;
+    /**
+     * Clear all history
+     */
+    clear(): void;
+}
+/**
+ * Create a Praxis engine with history tracking.
+ *
+ * This utility wraps an engine with automatic history recording,
+ * providing undo/redo functionality.
+ *
+ * @example
+ * const engine = createPraxisEngine({ ... });
+ * const { dispatch, undo, redo, canUndo, canRedo } = createHistoryEngine(engine);
+ *
+ * // Use normally
+ * dispatch([Login.create({ username: "alice" })]);
+ *
+ * // Undo the login
+ * undo();
+ *
+ * @param engine The base Praxis engine
+ * @param options History configuration
+ * @returns Enhanced engine with history methods
+ */
+declare function createHistoryEngine<TContext = unknown>(engine: LogicEngine<TContext>, options?: {
+    maxHistorySize?: number;
+    initialLabel?: string;
+}): {
+    engine: LogicEngine<TContext>;
+    dispatch: (events: PraxisEvent[], label?: string) => void;
+    undo: () => boolean;
+    redo: () => boolean;
+    canUndo: () => boolean;
+    canRedo: () => boolean;
+    getHistory: () => ReadonlyArray<HistoryEntry<TContext>>;
+    goToHistory: (index: number) => boolean;
+    clearHistory: () => void;
+};
+
+export { type HistoryEntry, HistoryStateManager, type PraxisEngineBinding, type Readable, type StateSnapshot, type UsePraxisEngineOptions, type Writable, createContextStore, createDerivedStore, createHistoryEngine, createPraxisStore, usePraxisContext, usePraxisEngine, usePraxisSubscription };

package/dist/node/integrations/svelte.js

@@ -0,0 +1,300 @@
+import "../chunk-QGM4M3NI.js";
+
+// src/integrations/svelte.ts
+function createPraxisStore(engine) {
+  let currentState = engine.getState();
+  const subscribers = /* @__PURE__ */ new Set();
+  const notify = () => {
+    currentState = engine.getState();
+    subscribers.forEach((sub) => sub(currentState));
+  };
+  return {
+    subscribe(run) {
+      subscribers.add(run);
+      run(currentState);
+      return () => {
+        subscribers.delete(run);
+      };
+    },
+    dispatch(events) {
+      engine.step(events);
+      notify();
+    }
+  };
+}
+function createContextStore(engine) {
+  let currentContext = engine.getContext();
+  const subscribers = /* @__PURE__ */ new Set();
+  const notify = () => {
+    currentContext = engine.getContext();
+    subscribers.forEach((sub) => sub(currentContext));
+  };
+  return {
+    subscribe(run) {
+      subscribers.add(run);
+      run(currentContext);
+      return () => {
+        subscribers.delete(run);
+      };
+    },
+    dispatch(events) {
+      engine.step(events);
+      notify();
+    }
+  };
+}
+function createDerivedStore(engine, selector) {
+  let currentValue = selector(engine.getContext());
+  const subscribers = /* @__PURE__ */ new Set();
+  const notify = () => {
+    const newValue = selector(engine.getContext());
+    if (newValue !== currentValue) {
+      currentValue = newValue;
+      subscribers.forEach((sub) => sub(currentValue));
+    }
+  };
+  return {
+    subscribe(run) {
+      subscribers.add(run);
+      run(currentValue);
+      return () => {
+        subscribers.delete(run);
+      };
+    },
+    dispatch(events) {
+      engine.step(events);
+      notify();
+    }
+  };
+}
+function usePraxisEngine(engine, options = {}) {
+  const { enableHistory = false, maxHistorySize = 50 } = options;
+  let currentState = engine.getState();
+  let snapshots = [];
+  let historyIndex = -1;
+  if (enableHistory) {
+    snapshots.push({
+      timestamp: Date.now(),
+      state: currentState,
+      events: []
+    });
+    historyIndex = 0;
+  }
+  const dispatch = (events) => {
+    if (enableHistory && historyIndex < snapshots.length - 1) {
+      snapshots = snapshots.slice(0, historyIndex + 1);
+    }
+    engine.step(events);
+    currentState = engine.getState();
+    if (enableHistory) {
+      snapshots.push({
+        timestamp: Date.now(),
+        state: currentState,
+        events
+      });
+      if (snapshots.length > maxHistorySize) {
+        snapshots.shift();
+      } else {
+        historyIndex++;
+      }
+    }
+  };
+  const goToSnapshot = (index) => {
+    if (!enableHistory) {
+      console.warn("History is not enabled for this engine");
+      return;
+    }
+    if (index < 0 || index >= snapshots.length) {
+      console.warn(`Invalid snapshot index: ${index}`);
+      return;
+    }
+    historyIndex = index;
+    currentState = snapshots[index].state;
+  };
+  const undo = () => {
+    if (historyIndex > 0) {
+      goToSnapshot(historyIndex - 1);
+    }
+  };
+  const redo = () => {
+    if (historyIndex < snapshots.length - 1) {
+      goToSnapshot(historyIndex + 1);
+    }
+  };
+  return {
+    get state() {
+      return currentState;
+    },
+    get context() {
+      return currentState.context;
+    },
+    get facts() {
+      return currentState.facts;
+    },
+    dispatch,
+    get snapshots() {
+      return snapshots;
+    },
+    goToSnapshot,
+    undo,
+    redo,
+    get canUndo() {
+      return enableHistory && historyIndex > 0;
+    },
+    get canRedo() {
+      return enableHistory && historyIndex < snapshots.length - 1;
+    },
+    get historyIndex() {
+      return historyIndex;
+    }
+  };
+}
+function usePraxisContext(engine, selector) {
+  let currentValue = selector(engine.getContext());
+  return currentValue;
+}
+function usePraxisSubscription(engine, callback) {
+  const store = createPraxisStore(engine);
+  const unsubscribe = store.subscribe(callback);
+  return unsubscribe;
+}
+var HistoryStateManager = class {
+  history = [];
+  currentIndex = -1;
+  maxSize;
+  idCounter = 0;
+  constructor(maxSize = 50) {
+    this.maxSize = maxSize;
+  }
+  /**
+   * Record a new history entry
+   */
+  record(state, events, label) {
+    if (this.currentIndex < this.history.length - 1) {
+      this.history = this.history.slice(0, this.currentIndex + 1);
+    }
+    this.history.push({
+      id: `history-${++this.idCounter}`,
+      timestamp: Date.now(),
+      state,
+      events,
+      label
+    });
+    if (this.history.length > this.maxSize) {
+      this.history.shift();
+    } else {
+      this.currentIndex++;
+    }
+  }
+  /**
+   * Navigate to a specific history entry
+   */
+  goTo(index) {
+    if (index < 0 || index >= this.history.length) {
+      return null;
+    }
+    this.currentIndex = index;
+    return this.history[index];
+  }
+  /**
+   * Go back to previous state
+   */
+  back() {
+    if (!this.canGoBack()) {
+      return null;
+    }
+    return this.goTo(this.currentIndex - 1);
+  }
+  /**
+   * Go forward to next state
+   */
+  forward() {
+    if (!this.canGoForward()) {
+      return null;
+    }
+    return this.goTo(this.currentIndex + 1);
+  }
+  /**
+   * Check if can go back
+   */
+  canGoBack() {
+    return this.currentIndex > 0;
+  }
+  /**
+   * Check if can go forward
+   */
+  canGoForward() {
+    return this.currentIndex < this.history.length - 1;
+  }
+  /**
+   * Get current history entry
+   */
+  current() {
+    if (this.currentIndex < 0 || this.currentIndex >= this.history.length) {
+      return null;
+    }
+    return this.history[this.currentIndex];
+  }
+  /**
+   * Get all history entries
+   */
+  getHistory() {
+    return [...this.history];
+  }
+  /**
+   * Get current index in history
+   */
+  getCurrentIndex() {
+    return this.currentIndex;
+  }
+  /**
+   * Clear all history
+   */
+  clear() {
+    this.history = [];
+    this.currentIndex = -1;
+  }
+};
+function createHistoryEngine(engine, options = {}) {
+  const history = new HistoryStateManager(options.maxHistorySize);
+  history.record(engine.getState(), [], options.initialLabel || "Initial");
+  const dispatch = (events, label) => {
+    engine.step(events);
+    history.record(engine.getState(), events, label);
+  };
+  const undo = () => {
+    const entry = history.back();
+    if (entry) {
+      return true;
+    }
+    return false;
+  };
+  const redo = () => {
+    const entry = history.forward();
+    if (entry) {
+      return true;
+    }
+    return false;
+  };
+  return {
+    engine,
+    dispatch,
+    undo,
+    redo,
+    canUndo: () => history.canGoBack(),
+    canRedo: () => history.canGoForward(),
+    getHistory: () => history.getHistory(),
+    goToHistory: (index) => history.goTo(index) !== null,
+    clearHistory: () => history.clear()
+  };
+}
+export {
+  HistoryStateManager,
+  createContextStore,
+  createDerivedStore,
+  createHistoryEngine,
+  createPraxisStore,
+  usePraxisContext,
+  usePraxisEngine,
+  usePraxisSubscription
+};