@plures/praxis 1.0.3 → 1.1.1

package/src/core/schema/types.ts

@@ -1,6 +1,6 @@
 /**
  * Praxis Schema System
- * 
+ *
  * Declarative schema definitions for generating models, components, logic, and documentation.
  */
 
@@ -494,7 +494,7 @@ export function validateSchema(schema: PraxisSchema): ValidationResult {
           message: 'Node type is required',
         });
       }
-      
+
       // Validate terminal node specific props
       if (node.type === 'terminal' && node.props) {
         const props = node.props as Partial<TerminalNodeProps>;
@@ -527,18 +527,54 @@ function isValidIdentifier(str: string): boolean {
   // JavaScript identifier must start with letter, $, or _
   // and can contain letters, digits, $, or _
   const identifierRegex = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
-  
+
   // Also check that it's not a reserved keyword
   const reservedKeywords = [
-    'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger',
-    'default', 'delete', 'do', 'else', 'export', 'extends', 'finally',
-    'for', 'function', 'if', 'import', 'in', 'instanceof', 'new',
-    'return', 'super', 'switch', 'this', 'throw', 'try', 'typeof',
-    'var', 'void', 'while', 'with', 'yield', 'let', 'static',
-    'enum', 'await', 'implements', 'interface', 'package', 'private',
-    'protected', 'public',
+    'break',
+    'case',
+    'catch',
+    'class',
+    'const',
+    'continue',
+    'debugger',
+    'default',
+    'delete',
+    'do',
+    'else',
+    'export',
+    'extends',
+    'finally',
+    'for',
+    'function',
+    'if',
+    'import',
+    'in',
+    'instanceof',
+    'new',
+    'return',
+    'super',
+    'switch',
+    'this',
+    'throw',
+    'try',
+    'typeof',
+    'var',
+    'void',
+    'while',
+    'with',
+    'yield',
+    'let',
+    'static',
+    'enum',
+    'await',
+    'implements',
+    'interface',
+    'package',
+    'private',
+    'protected',
+    'public',
   ];
-  
+
   return identifierRegex.test(str) && !reservedKeywords.includes(str);
 }
 

package/src/dsl/index.ts

@@ -1,18 +1,18 @@
 /**
  * DSL Helpers
- * 
+ *
  * Ergonomic TypeScript helpers for defining facts, events, rules, constraints, and flows.
  * These produce both strongly-typed APIs and serializable descriptors.
  */
 
-import type { PraxisEvent, PraxisFact } from "../core/protocol.js";
+import type { PraxisEvent, PraxisFact } from '../core/protocol.js';
 import type {
   RuleDescriptor,
   ConstraintDescriptor,
   PraxisModule,
   RuleFn,
   ConstraintFn,
-} from "../core/rules.js";
+} from '../core/rules.js';
 
 /**
  * Strongly typed fact definition
@@ -25,7 +25,7 @@ export interface FactDefinition<TTag extends string, TPayload> {
 
 /**
  * Define a typed fact
- * 
+ *
  * @example
  * const UserLoggedIn = defineFact<"UserLoggedIn", { userId: string }>("UserLoggedIn");
  * const fact = UserLoggedIn.create({ userId: "123" });
@@ -58,7 +58,7 @@ export interface EventDefinition<TTag extends string, TPayload> {
 
 /**
  * Define a typed event
- * 
+ *
  * @example
  * const Login = defineEvent<"LOGIN", { username: string; password: string }>("LOGIN");
  * const event = Login.create({ username: "alice", password: "secret" });
@@ -89,7 +89,7 @@ export interface DefineRuleOptions<TContext = unknown> {
 
 /**
  * Define a rule
- * 
+ *
  * @example
  * const loginRule = defineRule({
  *   id: "auth.login",
@@ -126,7 +126,7 @@ export interface DefineConstraintOptions<TContext = unknown> {
 
 /**
  * Define a constraint
- * 
+ *
  * @example
  * const maxCartItems = defineConstraint({
  *   id: "cart.maxItems",
@@ -159,7 +159,7 @@ export interface DefineModuleOptions<TContext = unknown> {
 
 /**
  * Define a module (bundle of rules and constraints)
- * 
+ *
  * @example
  * const authModule = defineModule({
  *   rules: [loginRule, logoutRule],

package/src/dsl.ts

@@ -9,26 +9,23 @@ import type { PraxisState, PraxisEvent, Effect } from './types.js';
 /**
  * A condition function that checks if a rule should fire.
  */
-export type Condition<
-  S extends PraxisState = PraxisState,
-  E extends PraxisEvent = PraxisEvent
-> = (state: S, event: E) => boolean;
+export type Condition<S extends PraxisState = PraxisState, E extends PraxisEvent = PraxisEvent> = (
+  state: S,
+  event: E
+) => boolean;
 
 /**
  * An action function that produces effects when a rule fires.
  */
-export type Action<
-  S extends PraxisState = PraxisState,
-  E extends PraxisEvent = PraxisEvent
-> = (state: S, event: E) => Effect[];
+export type Action<S extends PraxisState = PraxisState, E extends PraxisEvent = PraxisEvent> = (
+  state: S,
+  event: E
+) => Effect[];
 
 /**
  * A rule that fires when its condition is met.
  */
-export interface Rule<
-  S extends PraxisState = PraxisState,
-  E extends PraxisEvent = PraxisEvent
-> {
+export interface Rule<S extends PraxisState = PraxisState, E extends PraxisEvent = PraxisEvent> {
   /** Unique identifier for the rule */
   id: string;
   /** Human-readable description of what the rule does */
@@ -69,10 +66,7 @@ export interface ConstraintViolation {
 /**
  * DSL builder for creating rules with a fluent interface.
  */
-export class RuleBuilder<
-  S extends PraxisState = PraxisState,
-  E extends PraxisEvent = PraxisEvent
-> {
+export class RuleBuilder<S extends PraxisState = PraxisState, E extends PraxisEvent = PraxisEvent> {
   private rule: Partial<Rule<S, E>> = {};
 
   /**
@@ -201,7 +195,7 @@ export class ConstraintBuilder<S extends PraxisState = PraxisState> {
  */
 export function rule<
   S extends PraxisState = PraxisState,
-  E extends PraxisEvent = PraxisEvent
+  E extends PraxisEvent = PraxisEvent,
 >(): RuleBuilder<S, E> {
   return new RuleBuilder<S, E>();
 }

package/src/examples/advanced-todo/README.md

@@ -5,6 +5,7 @@ A comprehensive example demonstrating Praxis's Svelte 5 integration with history
 ## Features
 
 ### Core Functionality
+
 - ✅ Add, complete, and remove todos
 - ✅ Filter by all, active, or completed
 - ✅ Complete all todos at once
@@ -12,6 +13,7 @@ A comprehensive example demonstrating Praxis's Svelte 5 integration with history
 - ✅ Real-time statistics
 
 ### Advanced Features
+
 - 🔄 **Undo/Redo**: Full history tracking with keyboard shortcuts
 - 🕰️ **Time-Travel Debugging**: Navigate through state snapshots
 - ⚡ **Svelte 5 Runes**: Modern reactive API
@@ -21,12 +23,14 @@ A comprehensive example demonstrating Praxis's Svelte 5 integration with history
 ## Architecture
 
 ### State Management
+
 - **Engine**: Praxis logic engine managing todo state
 - **Rules**: Pure functions handling events
 - **Facts**: Immutable history of what happened
 - **Context**: Current application state
 
 ### Svelte Integration
+
 - **usePraxisEngine**: Main composable with history support
 - **Reactive Derivations**: Computed values with `$:` syntax
 - **Event Dispatching**: Type-safe event handling
@@ -71,7 +75,7 @@ export function createTodoEngine() {
   const registry = new PraxisRegistry<TodoContext>();
   registry.registerRule(addTodoRule);
   // ... register more rules
-  
+
   return createPraxisEngine({
     initialContext: { todos: [], filter: 'all', nextId: 1 },
     registry,
@@ -127,6 +131,7 @@ node dist/examples/advanced-todo/index.js
 ```
 
 Output:
+
 ```
 === Advanced Todo Example ===
 
@@ -157,11 +162,13 @@ Output:
 To use the Svelte component in your app:
 
 1. Install dependencies:
+
 ```bash
 npm install @plures/praxis svelte@^5.0.0
 ```
 
 2. Import and use the component:
+
 ```svelte
 <script>
   import TodoApp from '@plures/praxis/examples/advanced-todo/App.svelte';
@@ -179,7 +186,7 @@ Or create your own component using the engine:
 
   const engine = createTodoEngine();
   const { context, dispatch } = usePraxisEngine(engine);
-  
+
   let text = '';
 </script>
 
@@ -226,9 +233,15 @@ const addTodoRule = defineRule({
     // - Testable
     const event = findEvent(events, AddTodo);
     if (!event) return [];
-    
-    state.context.todos.push({ /* ... */ });
-    return [TodoAdded.create({ /* ... */ })];
+
+    state.context.todos.push({
+      /* ... */
+    });
+    return [
+      TodoAdded.create({
+        /* ... */
+      }),
+    ];
   },
 });
 ```
@@ -240,8 +253,8 @@ const addTodoRule = defineRule({
 const facts = engine.getFacts();
 
 // Find specific facts
-const added = facts.filter(f => f.tag === 'TodoAdded');
-const toggled = facts.filter(f => f.tag === 'TodoToggled');
+const added = facts.filter((f) => f.tag === 'TodoAdded');
+const toggled = facts.filter((f) => f.tag === 'TodoToggled');
 
 // Facts enable:
 // - Audit trails
@@ -270,10 +283,10 @@ const { undo, redo, snapshots, goToSnapshot } = usePraxisEngine(engine, {
 });
 
 // Navigate history
-undo();                    // Go back
-redo();                    // Go forward
-goToSnapshot(5);           // Jump to specific snapshot
-console.log(snapshots);    // View all snapshots
+undo(); // Go back
+redo(); // Go forward
+goToSnapshot(5); // Jump to specific snapshot
+console.log(snapshots); // View all snapshots
 ```
 
 ## Testing
@@ -287,7 +300,7 @@ describe('Todo Engine', () => {
   it('should add todos', () => {
     const engine = createTodoEngine();
     engine.step([AddTodo.create({ text: 'Test todo' })]);
-    
+
     const context = engine.getContext();
     expect(context.todos.length).toBe(1);
     expect(context.todos[0].text).toBe('Test todo');
@@ -296,10 +309,10 @@ describe('Todo Engine', () => {
   it('should toggle todos', () => {
     const engine = createTodoEngine();
     engine.step([AddTodo.create({ text: 'Test' })]);
-    
+
     const context = engine.getContext();
     const todoId = context.todos[0].id;
-    
+
     engine.step([ToggleTodo.create({ id: todoId })]);
     expect(engine.getContext().todos[0].completed).toBe(true);
   });
@@ -309,55 +322,60 @@ describe('Todo Engine', () => {
 ## Performance Tips
 
 1. **Batch Events**: Dispatch multiple events at once
+
    ```typescript
-   dispatch([
-     AddTodo.create({ text: 'Todo 1' }),
-     AddTodo.create({ text: 'Todo 2' }),
-     AddTodo.create({ text: 'Todo 3' }),
-   ], 'Batch Add');
+   dispatch(
+     [
+       AddTodo.create({ text: 'Todo 1' }),
+       AddTodo.create({ text: 'Todo 2' }),
+       AddTodo.create({ text: 'Todo 3' }),
+     ],
+     'Batch Add'
+   );
    ```
 
 2. **Limit History**: Adjust history size based on needs
+
    ```typescript
    usePraxisEngine(engine, { maxHistorySize: 20 });
    ```
 
 3. **Selective Subscriptions**: Use derived stores for specific values
    ```typescript
-   const count = createDerivedStore(engine, ctx => ctx.todos.length);
+   const count = createDerivedStore(engine, (ctx) => ctx.todos.length);
    ```
 
 ## Comparison with Other Libraries
 
 ### vs. Redux + Redux Toolkit
 
-| Feature | Redux + RTK | Praxis |
-|---------|-------------|--------|
-| State Updates | Reducers | Rules |
-| Side Effects | Thunks/Sagas | Actors |
-| Time-Travel | DevTools | Built-in |
-| TypeScript | Good | Excellent |
-| Learning Curve | Medium | Low |
+| Feature        | Redux + RTK  | Praxis    |
+| -------------- | ------------ | --------- |
+| State Updates  | Reducers     | Rules     |
+| Side Effects   | Thunks/Sagas | Actors    |
+| Time-Travel    | DevTools     | Built-in  |
+| TypeScript     | Good         | Excellent |
+| Learning Curve | Medium       | Low       |
 
 ### vs. XState
 
-| Feature | XState | Praxis |
-|---------|--------|--------|
-| State Machines | Native | Engine-based |
+| Feature            | XState         | Praxis                |
+| ------------------ | -------------- | --------------------- |
+| State Machines     | Native         | Engine-based          |
 | Svelte Integration | @xstate/svelte | @plures/praxis/svelte |
-| History States | Built-in | Pattern-based |
-| Visual Tools | Stately | State-Docs (planned) |
-| Learning Curve | High | Medium |
+| History States     | Built-in       | Pattern-based         |
+| Visual Tools       | Stately        | State-Docs (planned)  |
+| Learning Curve     | High           | Medium                |
 
 ### vs. Svelte Stores
 
-| Feature | Svelte Stores | Praxis |
-|---------|---------------|--------|
-| Simplicity | Very High | High |
-| Structure | Manual | Built-in |
-| Time-Travel | Manual | Built-in |
-| Rules/Logic | Manual | Built-in |
-| TypeScript | Good | Excellent |
+| Feature     | Svelte Stores | Praxis    |
+| ----------- | ------------- | --------- |
+| Simplicity  | Very High     | High      |
+| Structure   | Manual        | Built-in  |
+| Time-Travel | Manual        | Built-in  |
+| Rules/Logic | Manual        | Built-in  |
+| TypeScript  | Good          | Excellent |
 
 ## Next Steps
 

package/src/examples/advanced-todo/index.ts

@@ -1,6 +1,6 @@
 /**
  * Advanced Svelte 5 Integration Example
- * 
+ *
  * Demonstrates the new Svelte 5 runes support with history state pattern.
  * This example shows a todo app with undo/redo and time-travel debugging.
  */
@@ -254,8 +254,8 @@ function runExample() {
 
   // Change filter
   console.log('3. Filtering to active todos:');
-  engine.step([SetFilter.create({ filter: 'active' })])
-  
+  engine.step([SetFilter.create({ filter: 'active' })]);
+
   const context3 = engine.getContext();
   const filtered = getFilteredTodos(context3.todos, context3.filter);
   console.log(`   Filter: ${context3.filter}`);

package/src/examples/auth-basic/index.ts

@@ -1,6 +1,6 @@
 /**
  * Auth Basic Example
- * 
+ *
  * Demonstrates basic authentication logic with login/logout using Praxis.
  * Shows how to define facts, events, rules, and constraints.
  */
@@ -14,7 +14,7 @@ import {
   defineConstraint,
   findEvent,
   filterFacts,
-} from "../../index.js";
+} from '../../index.js';
 
 // Define the context type
 interface AuthContext {
@@ -23,21 +23,21 @@ interface AuthContext {
 }
 
 // Define facts
-const UserLoggedIn = defineFact<"UserLoggedIn", { userId: string; timestamp: number }>(
-  "UserLoggedIn"
+const UserLoggedIn = defineFact<'UserLoggedIn', { userId: string; timestamp: number }>(
+  'UserLoggedIn'
 );
-const UserLoggedOut = defineFact<"UserLoggedOut", { userId: string; timestamp: number }>(
-  "UserLoggedOut"
+const UserLoggedOut = defineFact<'UserLoggedOut', { userId: string; timestamp: number }>(
+  'UserLoggedOut'
 );
 
 // Define events
-const Login = defineEvent<"LOGIN", { username: string; password: string }>("LOGIN");
-const Logout = defineEvent<"LOGOUT", {}>("LOGOUT");
+const Login = defineEvent<'LOGIN', { username: string; password: string }>('LOGIN');
+const Logout = defineEvent<'LOGOUT', {}>('LOGOUT');
 
 // Define rules
 const loginRule = defineRule<AuthContext>({
-  id: "auth.login",
-  description: "Process login event and create UserLoggedIn fact",
+  id: 'auth.login',
+  description: 'Process login event and create UserLoggedIn fact',
   impl: (_state, events) => {
     const loginEvent = findEvent(events, Login);
     if (!loginEvent) {
@@ -51,8 +51,8 @@ const loginRule = defineRule<AuthContext>({
 });
 
 const logoutRule = defineRule<AuthContext>({
-  id: "auth.logout",
-  description: "Process logout event and create UserLoggedOut fact",
+  id: 'auth.logout',
+  description: 'Process logout event and create UserLoggedOut fact',
   impl: (state, events) => {
     const logoutEvent = findEvent(events, Logout);
     if (!logoutEvent || !state.context.currentUser) {
@@ -69,8 +69,8 @@ const logoutRule = defineRule<AuthContext>({
 });
 
 const updateContextRule = defineRule<AuthContext>({
-  id: "auth.updateContext",
-  description: "Update context based on login/logout facts",
+  id: 'auth.updateContext',
+  description: 'Update context based on login/logout facts',
   impl: (state, _events) => {
     // This rule updates context based on facts (side effect on context)
     const loginFacts = filterFacts(state.facts, UserLoggedIn);
@@ -95,8 +95,8 @@ const updateContextRule = defineRule<AuthContext>({
 
 // Define constraints
 const singleSessionConstraint = defineConstraint<AuthContext>({
-  id: "auth.singleSession",
-  description: "Only one user can be logged in at a time",
+  id: 'auth.singleSession',
+  description: 'Only one user can be logged in at a time',
   impl: (state) => {
     const loginFacts = filterFacts(state.facts, UserLoggedIn);
     const logoutFacts = filterFacts(state.facts, UserLoggedOut);
@@ -127,31 +127,31 @@ function createAuthEngine() {
 
 // Example usage
 function runExample() {
-  console.log("=== Auth Basic Example ===\n");
+  console.log('=== Auth Basic Example ===\n');
 
   const engine = createAuthEngine();
 
   // Login
-  console.log("1. User logs in:");
-  let result = engine.step([Login.create({ username: "alice", password: "secret123" })]);
-  console.log("   Context:", engine.getContext());
-  console.log("   Facts:", result.state.facts);
-  console.log("   Diagnostics:", result.diagnostics);
+  console.log('1. User logs in:');
+  let result = engine.step([Login.create({ username: 'alice', password: 'secret123' })]);
+  console.log('   Context:', engine.getContext());
+  console.log('   Facts:', result.state.facts);
+  console.log('   Diagnostics:', result.diagnostics);
   console.log();
 
   // Try to login again (should violate constraint)
-  console.log("2. Another user tries to log in:");
-  result = engine.step([Login.create({ username: "bob", password: "secret456" })]);
-  console.log("   Context:", engine.getContext());
-  console.log("   Diagnostics:", result.diagnostics);
+  console.log('2. Another user tries to log in:');
+  result = engine.step([Login.create({ username: 'bob', password: 'secret456' })]);
+  console.log('   Context:', engine.getContext());
+  console.log('   Diagnostics:', result.diagnostics);
   console.log();
 
   // Logout
-  console.log("3. User logs out:");
+  console.log('3. User logs out:');
   result = engine.step([Logout.create({})]);
-  console.log("   Context:", engine.getContext());
-  console.log("   Facts (last 3):", result.state.facts.slice(-3));
-  console.log("   Diagnostics:", result.diagnostics);
+  console.log('   Context:', engine.getContext());
+  console.log('   Facts (last 3):', result.state.facts.slice(-3));
+  console.log('   Diagnostics:', result.diagnostics);
   console.log();
 }