@plures/praxis 0.2.0 → 1.0.0

package/dist/src/integrations/pluresdb.js

@@ -0,0 +1,117 @@
+/**
+ * PluresDB Integration
+ *
+ * Integration with pluresdb - reactive graph datastore and event source/sink.
+ * This module provides adapters for:
+ * - Storing Praxis state in pluresdb
+ * - Sourcing events from pluresdb
+ * - Sinking events to pluresdb
+ * - Reactive queries and subscriptions
+ */
+import { createPraxisDBStore } from "../core/pluresdb/store.js";
+// Re-export core pluresdb types and implementations
+// Note: Using explicit exports to avoid circular dependency issues
+export { InMemoryPraxisDB, createInMemoryDB } from "../core/pluresdb/adapter.js";
+export { PraxisDBStore, createPraxisDBStore, PRAXIS_PATHS, getFactPath, getEventPath, generateId } from "../core/pluresdb/store.js";
+export { PraxisSchemaRegistry, createSchemaRegistry, registerSchema, getSchemaPath } from "../core/pluresdb/schema-registry.js";
+export { PluresDBGenerator, createPluresDBGenerator } from "../core/pluresdb/generator.js";
+/**
+ * Create a PluresDB adapter with full implementation
+ *
+ * @example
+ * ```typescript
+ * const db = createInMemoryDB();
+ * const registry = new PraxisRegistry();
+ * const adapter = createPluresDBAdapter({ db, registry });
+ *
+ * const engine = createPraxisEngine({ initialContext: {}, registry });
+ * adapter.attachEngine(engine);
+ *
+ * await adapter.persistFacts([{ tag: "UserLoggedIn", payload: { userId: "alice" } }]);
+ * ```
+ */
+export function createPluresDBAdapter(options) {
+    const store = createPraxisDBStore(options.db, options.registry, options.initialContext);
+    const subscriptions = [];
+    return {
+        async persistEvents(events) {
+            await store.appendEvents(events);
+        },
+        async persistFacts(facts) {
+            await store.storeFacts(facts);
+        },
+        async loadEvents(query) {
+            if (!query?.tag) {
+                return [];
+            }
+            const entries = await store.getEvents(query.tag, {
+                since: query.since,
+                limit: query.limit,
+            });
+            return entries.map(e => e.event);
+        },
+        subscribeToEvents(callback, query) {
+            if (!query?.tag) {
+                return () => { };
+            }
+            // Watch for new facts that might be derived from events
+            const unsubscribe = store.watchFacts(query.tag, (facts) => {
+                // Convert facts to events for the callback
+                const events = facts.map(f => ({
+                    tag: f.tag,
+                    payload: f.payload,
+                }));
+                callback(events);
+            });
+            subscriptions.push(unsubscribe);
+            return unsubscribe;
+        },
+        attachEngine(engine) {
+            // Sync context from engine to store
+            store.updateContext(engine.getContext());
+        },
+        dispose() {
+            for (const unsub of subscriptions) {
+                unsub();
+            }
+            subscriptions.length = 0;
+            store.dispose();
+        },
+    };
+}
+/**
+ * Attach a PraxisDBStore to a LogicEngine
+ *
+ * This function creates a bidirectional connection between the store and engine:
+ * - Events processed by the engine are persisted to the store
+ * - Facts from the store are synchronized to the engine
+ *
+ * @param store The PraxisDBStore instance
+ * @param engine The LogicEngine instance
+ * @returns Cleanup function to detach the store
+ *
+ * @example
+ * ```typescript
+ * const db = createInMemoryDB();
+ * const registry = new PraxisRegistry();
+ * const store = createPraxisDBStore(db, registry);
+ * const engine = createPraxisEngine({ initialContext: {}, registry });
+ *
+ * const detach = attachToEngine(store, engine);
+ *
+ * // Events are now automatically persisted
+ * engine.step([{ tag: "LOGIN", payload: { username: "alice" } }]);
+ *
+ * // Cleanup
+ * detach();
+ * ```
+ */
+export function attachToEngine(store, engine) {
+    // Sync context from engine to store
+    store.updateContext(engine.getContext());
+    // Return cleanup function
+    return () => {
+        store.dispose();
+    };
+}
+//# sourceMappingURL=pluresdb.js.map

package/dist/src/integrations/pluresdb.js.map

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

package/dist/src/integrations/state-docs.d.ts

@@ -0,0 +1,191 @@
+/**
+ * State-Docs Integration
+ *
+ * Integration with plures/state-docs - FSM documentation generator for XState projects.
+ * Generates Markdown and Mermaid documentation from Praxis state machines and logic.
+ *
+ * Features:
+ * - Auto-generate documentation from Praxis schemas
+ * - Markdown output with Mermaid diagrams
+ * - State machine visualization
+ * - Transition documentation
+ * - Integration with Praxis logic engine
+ *
+ * @see https://github.com/plures/state-docs
+ */
+import type { PraxisSchema } from "../core/schema/types.js";
+import type { PraxisModule } from "../core/rules.js";
+/**
+ * State-Docs configuration
+ */
+export interface StateDocsConfig {
+    /** Project title */
+    projectTitle: string;
+    /** Source directory containing schemas */
+    source?: string;
+    /** Target directory for generated docs */
+    target?: string;
+    /** File patterns to include */
+    globs?: string[];
+    /** Visualization settings */
+    visualization?: {
+        /** Output format */
+        format?: 'mermaid' | 'dot';
+        /** Export as PNG */
+        exportPng?: boolean;
+        /** Diagram theme */
+        theme?: 'default' | 'dark' | 'forest' | 'neutral';
+    };
+    /** Template settings */
+    template?: {
+        /** Include table of contents */
+        toc?: boolean;
+        /** Include timestamp */
+        timestamp?: boolean;
+        /** Custom header content */
+        header?: string;
+        /** Custom footer content */
+        footer?: string;
+    };
+}
+/**
+ * Generated documentation file
+ */
+export interface GeneratedDoc {
+    /** File path */
+    path: string;
+    /** File content */
+    content: string;
+    /** File type */
+    type: 'markdown' | 'mermaid' | 'dot' | 'json';
+}
+/**
+ * State machine representation for documentation
+ */
+export interface StateMachineDoc {
+    /** Machine identifier */
+    id: string;
+    /** Machine name */
+    name: string;
+    /** Machine description */
+    description?: string;
+    /** Initial state */
+    initial?: string;
+    /** All states */
+    states: StateDoc[];
+    /** All transitions */
+    transitions: TransitionDoc[];
+    /** Context type description */
+    context?: string;
+    /** Events that this machine handles */
+    events?: string[];
+}
+/**
+ * State documentation
+ */
+export interface StateDoc {
+    /** State identifier */
+    id: string;
+    /** State name */
+    name: string;
+    /** State description */
+    description?: string;
+    /** Is this an initial state */
+    initial?: boolean;
+    /** Is this a final state */
+    final?: boolean;
+    /** Entry actions */
+    onEntry?: string[];
+    /** Exit actions */
+    onExit?: string[];
+    /** State tags */
+    tags?: string[];
+}
+/**
+ * Transition documentation
+ */
+export interface TransitionDoc {
+    /** Source state */
+    from: string;
+    /** Target state */
+    to: string;
+    /** Event that triggers the transition */
+    event: string;
+    /** Transition guard condition */
+    guard?: string;
+    /** Actions executed during transition */
+    actions?: string[];
+    /** Transition description */
+    description?: string;
+}
+/**
+ * Documentation generator for Praxis schemas
+ */
+export declare class StateDocsGenerator {
+    private config;
+    constructor(config: StateDocsConfig);
+    /**
+     * Generate documentation from a Praxis schema
+     */
+    generateFromSchema(schema: PraxisSchema): GeneratedDoc[];
+    /**
+     * Generate documentation from a Praxis registry
+     */
+    generateFromModule<TContext>(module: PraxisModule<TContext>): GeneratedDoc[];
+    /**
+     * Generate the main schema README
+     */
+    private generateSchemaReadme;
+    /**
+     * Generate models documentation
+     */
+    private generateModelsDoc;
+    /**
+     * Generate components documentation
+     */
+    private generateComponentsDoc;
+    /**
+     * Generate logic documentation
+     */
+    private generateLogicDoc;
+    /**
+     * Generate Mermaid diagram for logic
+     */
+    private generateLogicDiagram;
+    /**
+     * Generate rules documentation
+     */
+    private generateRulesDoc;
+    /**
+     * Generate constraints documentation
+     */
+    private generateConstraintsDoc;
+    /**
+     * Generate state diagram from registry
+     */
+    private generateRegistryDiagram;
+}
+/**
+ * Create a State-Docs generator instance
+ *
+ * @example
+ * ```typescript
+ * import { createStateDocsGenerator } from '@plures/praxis/integrations/state-docs';
+ *
+ * const generator = createStateDocsGenerator({
+ *   projectTitle: 'My Project',
+ *   target: './docs/api',
+ * });
+ *
+ * const docs = generator.generateFromSchema(mySchema);
+ * for (const doc of docs) {
+ *   await writeFile(doc.path, doc.content);
+ * }
+ * ```
+ */
+export declare function createStateDocsGenerator(config: StateDocsConfig): StateDocsGenerator;
+/**
+ * Generate documentation from a schema (convenience function)
+ */
+export declare function generateDocs(schema: PraxisSchema, config: StateDocsConfig): GeneratedDoc[];
+//# sourceMappingURL=state-docs.d.ts.map

package/dist/src/integrations/state-docs.d.ts.map

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