@plures/praxis 1.0.2 → 1.1.0

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();
 }
 

package/src/examples/cart/index.ts

@@ -1,6 +1,6 @@
 /**
  * Cart Example
- * 
+ *
  * Demonstrates shopping cart logic with flows and derived state.
  * Shows how to manage complex state with multiple rules and constraints.
  */
@@ -15,7 +15,7 @@ import {
   defineModule,
   findEvent,
   filterFacts,
-} from "../../index.js";
+} from '../../index.js';
 
 // Define the context type
 interface CartContext {
@@ -25,25 +25,26 @@ interface CartContext {
 }
 
 // Define facts
-const ItemAdded = defineFact<"ItemAdded", { productId: string; quantity: number; price: number }>(
-  "ItemAdded"
+const ItemAdded = defineFact<'ItemAdded', { productId: string; quantity: number; price: number }>(
+  'ItemAdded'
 );
-const ItemRemoved = defineFact<"ItemRemoved", { productId: string }>("ItemRemoved");
-const DiscountApplied = defineFact<"DiscountApplied", { percentage: number }>("DiscountApplied");
-const CartCleared = defineFact<"CartCleared", {}>("CartCleared");
+const ItemRemoved = defineFact<'ItemRemoved', { productId: string }>('ItemRemoved');
+const DiscountApplied = defineFact<'DiscountApplied', { percentage: number }>('DiscountApplied');
+const CartCleared = defineFact<'CartCleared', {}>('CartCleared');
 
 // Define events
-const AddToCart = defineEvent<"ADD_TO_CART", { productId: string; quantity: number; price: number }>(
-  "ADD_TO_CART"
-);
-const RemoveFromCart = defineEvent<"REMOVE_FROM_CART", { productId: string }>("REMOVE_FROM_CART");
-const ApplyDiscount = defineEvent<"APPLY_DISCOUNT", { code: string }>("APPLY_DISCOUNT");
-const ClearCart = defineEvent<"CLEAR_CART", {}>("CLEAR_CART");
+const AddToCart = defineEvent<
+  'ADD_TO_CART',
+  { productId: string; quantity: number; price: number }
+>('ADD_TO_CART');
+const RemoveFromCart = defineEvent<'REMOVE_FROM_CART', { productId: string }>('REMOVE_FROM_CART');
+const ApplyDiscount = defineEvent<'APPLY_DISCOUNT', { code: string }>('APPLY_DISCOUNT');
+const ClearCart = defineEvent<'CLEAR_CART', {}>('CLEAR_CART');
 
 // Define rules
 const addToCartRule = defineRule<CartContext>({
-  id: "cart.addItem",
-  description: "Add item to cart",
+  id: 'cart.addItem',
+  description: 'Add item to cart',
   impl: (_state, events) => {
     const addEvents = events.filter(AddToCart.is);
     return addEvents.map((event) =>
@@ -57,8 +58,8 @@ const addToCartRule = defineRule<CartContext>({
 });
 
 const removeFromCartRule = defineRule<CartContext>({
-  id: "cart.removeItem",
-  description: "Remove item from cart",
+  id: 'cart.removeItem',
+  description: 'Remove item from cart',
   impl: (_state, events) => {
     const removeEvent = findEvent(events, RemoveFromCart);
     if (!removeEvent) {
@@ -69,8 +70,8 @@ const removeFromCartRule = defineRule<CartContext>({
 });
 
 const applyDiscountRule = defineRule<CartContext>({
-  id: "cart.applyDiscount",
-  description: "Apply discount code",
+  id: 'cart.applyDiscount',
+  description: 'Apply discount code',
   impl: (state, events) => {
     const discountEvent = findEvent(events, ApplyDiscount);
     if (!discountEvent || state.context.discountApplied) {
@@ -78,7 +79,7 @@ const applyDiscountRule = defineRule<CartContext>({
     }
 
     // Simple discount logic: "SAVE10" = 10% off
-    const percentage = discountEvent.payload.code === "SAVE10" ? 10 : 0;
+    const percentage = discountEvent.payload.code === 'SAVE10' ? 10 : 0;
     if (percentage > 0) {
       return [DiscountApplied.create({ percentage })];
     }
@@ -87,8 +88,8 @@ const applyDiscountRule = defineRule<CartContext>({
 });
 
 const clearCartRule = defineRule<CartContext>({
-  id: "cart.clear",
-  description: "Clear cart",
+  id: 'cart.clear',
+  description: 'Clear cart',
   impl: (_state, events) => {
     const clearEvent = findEvent(events, ClearCart);
     if (!clearEvent) {
@@ -99,8 +100,8 @@ const clearCartRule = defineRule<CartContext>({
 });
 
 const updateCartContextRule = defineRule<CartContext>({
-  id: "cart.updateContext",
-  description: "Update cart context based on facts",
+  id: 'cart.updateContext',
+  description: 'Update cart context based on facts',
   impl: (state, _events) => {
     const addedItems = filterFacts(state.facts, ItemAdded);
     const removedItems = filterFacts(state.facts, ItemRemoved);
@@ -145,10 +146,7 @@ const updateCartContextRule = defineRule<CartContext>({
     }));
 
     // Calculate total
-    let total = state.context.items.reduce(
-      (sum, item) => sum + item.quantity * item.price,
-      0
-    );
+    let total = state.context.items.reduce((sum, item) => sum + item.quantity * item.price, 0);
 
     // Apply discount if any
     if (discountFacts.length > 0) {
@@ -165,8 +163,8 @@ const updateCartContextRule = defineRule<CartContext>({
 
 // Define constraints
 const maxItemsConstraint = defineConstraint<CartContext>({
-  id: "cart.maxItems",
-  description: "Cart cannot exceed 100 items",
+  id: 'cart.maxItems',
+  description: 'Cart cannot exceed 100 items',
   impl: (state) => {
     const totalQuantity = state.context.items.reduce((sum, item) => sum + item.quantity, 0);
     return totalQuantity <= 100 || `Cart has ${totalQuantity} items, maximum is 100`;
@@ -174,10 +172,12 @@ const maxItemsConstraint = defineConstraint<CartContext>({
 });
 
 const maxTotalConstraint = defineConstraint<CartContext>({
-  id: "cart.maxTotal",
-  description: "Cart total cannot exceed $10,000",
+  id: 'cart.maxTotal',
+  description: 'Cart total cannot exceed $10,000',
   impl: (state) => {
-    return state.context.total <= 10000 || `Cart total $${state.context.total} exceeds maximum $10,000`;
+    return (
+      state.context.total <= 10000 || `Cart total $${state.context.total} exceeds maximum $10,000`
+    );
   },
 });
 
@@ -191,7 +191,7 @@ const cartModule = defineModule<CartContext>({
     updateCartContextRule,
   ],
   constraints: [maxItemsConstraint, maxTotalConstraint],
-  meta: { version: "1.0.0" },
+  meta: { version: '1.0.0' },
 });
 
 // Create and configure the engine
@@ -213,41 +213,41 @@ function createCartEngine() {
 
 // Example usage
 function runExample() {
-  console.log("=== Cart Example ===\n");
+  console.log('=== Cart Example ===\n');
 
   const engine = createCartEngine();
 
   // Add items
-  console.log("1. Add items to cart:");
+  console.log('1. Add items to cart:');
   engine.step([
-    AddToCart.create({ productId: "prod-1", quantity: 2, price: 29.99 }),
-    AddToCart.create({ productId: "prod-2", quantity: 1, price: 49.99 }),
+    AddToCart.create({ productId: 'prod-1', quantity: 2, price: 29.99 }),
+    AddToCart.create({ productId: 'prod-2', quantity: 1, price: 49.99 }),
   ]);
-  console.log("   Cart:", engine.getContext());
+  console.log('   Cart:', engine.getContext());
   console.log();
 
   // Apply discount
-  console.log("2. Apply discount code:");
-  engine.step([ApplyDiscount.create({ code: "SAVE10" })]);
-  console.log("   Cart:", engine.getContext());
+  console.log('2. Apply discount code:');
+  engine.step([ApplyDiscount.create({ code: 'SAVE10' })]);
+  console.log('   Cart:', engine.getContext());
   console.log();
 
   // Remove item
-  console.log("3. Remove an item:");
-  engine.step([RemoveFromCart.create({ productId: "prod-1" })]);
-  console.log("   Cart:", engine.getContext());
+  console.log('3. Remove an item:');
+  engine.step([RemoveFromCart.create({ productId: 'prod-1' })]);
+  console.log('   Cart:', engine.getContext());
   console.log();
 
   // Add more items
-  console.log("4. Add more items:");
-  engine.step([AddToCart.create({ productId: "prod-3", quantity: 3, price: 15.99 })]);
-  console.log("   Cart:", engine.getContext());
+  console.log('4. Add more items:');
+  engine.step([AddToCart.create({ productId: 'prod-3', quantity: 3, price: 15.99 })]);
+  console.log('   Cart:', engine.getContext());
   console.log();
 
   // Clear cart
-  console.log("5. Clear cart:");
+  console.log('5. Clear cart:');
   engine.step([ClearCart.create({})]);
-  console.log("   Cart:", engine.getContext());
+  console.log('   Cart:', engine.getContext());
   console.log();
 }