@plures/praxis 0.2.0

package/dist/integrations/pluresdb.js

@@ -0,0 +1,46 @@
+/**
+ * PluresDB Integration (Placeholder)
+ *
+ * Future integration with pluresdb - reactive graph datastore and event source/sink.
+ * This module will provide adapters for:
+ * - Storing Praxis state in pluresdb
+ * - Sourcing events from pluresdb
+ * - Sinking events to pluresdb
+ * - Reactive queries and subscriptions
+ */
+/**
+ * Create a pluresdb adapter (placeholder implementation)
+ *
+ * @example
+ * // Future usage:
+ * const adapter = createPluresDBAdapter({
+ *   connection: pluresdbClient,
+ *   collection: "myapp-events"
+ * });
+ * adapter.attachEngine(engine);
+ */
+export function createPluresDBAdapter(_options) {
+    return {
+        async persistEvents(_events) {
+            // TODO: Implement pluresdb event persistence
+            throw new Error("PluresDB integration not yet implemented");
+        },
+        async persistFacts(_facts) {
+            // TODO: Implement pluresdb fact persistence
+            throw new Error("PluresDB integration not yet implemented");
+        },
+        async loadEvents(_query) {
+            // TODO: Implement pluresdb event loading
+            throw new Error("PluresDB integration not yet implemented");
+        },
+        subscribeToEvents(_callback, _query) {
+            // TODO: Implement pluresdb event subscription
+            throw new Error("PluresDB integration not yet implemented");
+        },
+        attachEngine(_engine) {
+            // TODO: Implement engine attachment
+            throw new Error("PluresDB integration not yet implemented");
+        },
+    };
+}
+//# sourceMappingURL=pluresdb.js.map

package/dist/integrations/pluresdb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluresdb.js","sourceRoot":"","sources":["../../src/integrations/pluresdb.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA4CH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CACnC,QAAiB;IAEjB,OAAO;QACL,KAAK,CAAC,aAAa,CAAC,OAAsB;YACxC,6CAA6C;YAC7C,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAC9D,CAAC;QACD,KAAK,CAAC,YAAY,CAAC,MAAoB;YACrC,4CAA4C;YAC5C,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAC9D,CAAC;QACD,KAAK,CAAC,UAAU,CAAC,MAAgB;YAC/B,yCAAyC;YACzC,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAC9D,CAAC;QACD,iBAAiB,CACf,SAA0C,EAC1C,MAAgB;YAEhB,8CAA8C;YAC9C,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAC9D,CAAC;QACD,YAAY,CAAC,OAA8B;YACzC,oCAAoC;YACpC,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAC9D,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/integrations/svelte.d.ts

@@ -0,0 +1,306 @@
+/**
+ * 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
+ */
+import type { LogicEngine } from "../core/engine.js";
+import type { PraxisEvent, PraxisState } from "../core/protocol.js";
+/**
+ * Writable store interface (Svelte-compatible)
+ */
+export interface Writable<T> {
+    subscribe(run: (value: T) => void): () => void;
+    set(value: T): void;
+    update(updater: (value: T) => T): void;
+}
+/**
+ * Readable store interface (Svelte-compatible)
+ */
+export 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" })]);
+ */
+export 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;
+ */
+export 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;
+ */
+export 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
+ */
+export interface StateSnapshot<TContext = unknown> {
+    timestamp: number;
+    state: Readonly<PraxisState & {
+        context: TContext;
+    }>;
+    events: PraxisEvent[];
+}
+/**
+ * Options for usePraxisEngine composable
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export declare function usePraxisSubscription<TContext = unknown>(engine: LogicEngine<TContext>, callback: (state: Readonly<PraxisState & {
+    context: TContext;
+}>) => void): () => void;
+/**
+ * History state entry for tracking state transitions
+ */
+export 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
+ */
+export 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
+ */
+export 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;
+};
+//# sourceMappingURL=svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"svelte.d.ts","sourceRoot":"","sources":["../../src/integrations/svelte.ts"],"names":[],"mappings":"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"}