@plures/praxis 1.0.3 → 1.1.1

package/docs/tutorials/ecommerce-cart.md

@@ -9,6 +9,7 @@ This tutorial walks you through building a shopping cart with a multi-step check
 ## What You'll Build
 
 An e-commerce cart that:
+
 - Manages a product catalog
 - Handles cart operations (add, remove, update quantity)
 - Implements a multi-step checkout flow
@@ -24,7 +25,7 @@ Create the PSF schema for the e-commerce domain:
   "$version": "1.0.0",
   "id": "ecommerce-cart",
   "name": "E-commerce Cart",
-  
+
   "models": [
     {
       "name": "Product",
@@ -121,21 +122,44 @@ interface CartContext {
 }
 
 // Facts
-export const ItemAddedToCart = defineFact<'ItemAddedToCart', { productId: string; quantity: number }>('ItemAddedToCart');
-export const ItemRemovedFromCart = defineFact<'ItemRemovedFromCart', { productId: string }>('ItemRemovedFromCart');
-export const QuantityUpdated = defineFact<'QuantityUpdated', { productId: string; newQuantity: number }>('QuantityUpdated');
+export const ItemAddedToCart = defineFact<
+  'ItemAddedToCart',
+  { productId: string; quantity: number }
+>('ItemAddedToCart');
+export const ItemRemovedFromCart = defineFact<'ItemRemovedFromCart', { productId: string }>(
+  'ItemRemovedFromCart'
+);
+export const QuantityUpdated = defineFact<
+  'QuantityUpdated',
+  { productId: string; newQuantity: number }
+>('QuantityUpdated');
 export const CheckoutStarted = defineFact<'CheckoutStarted', {}>('CheckoutStarted');
-export const ShippingEntered = defineFact<'ShippingEntered', { address: ShippingAddress }>('ShippingEntered');
-export const PaymentProcessed = defineFact<'PaymentProcessed', { success: boolean }>('PaymentProcessed');
-export const OrderPlaced = defineFact<'OrderPlaced', { orderId: string; total: number }>('OrderPlaced');
+export const ShippingEntered = defineFact<'ShippingEntered', { address: ShippingAddress }>(
+  'ShippingEntered'
+);
+export const PaymentProcessed = defineFact<'PaymentProcessed', { success: boolean }>(
+  'PaymentProcessed'
+);
+export const OrderPlaced = defineFact<'OrderPlaced', { orderId: string; total: number }>(
+  'OrderPlaced'
+);
 export const CartCleared = defineFact<'CartCleared', {}>('CartCleared');
 
 // Events
-export const ADD_TO_CART = defineEvent<'ADD_TO_CART', { productId: string; quantity: number }>('ADD_TO_CART');
-export const REMOVE_FROM_CART = defineEvent<'REMOVE_FROM_CART', { productId: string }>('REMOVE_FROM_CART');
-export const UPDATE_QUANTITY = defineEvent<'UPDATE_QUANTITY', { productId: string; quantity: number }>('UPDATE_QUANTITY');
+export const ADD_TO_CART = defineEvent<'ADD_TO_CART', { productId: string; quantity: number }>(
+  'ADD_TO_CART'
+);
+export const REMOVE_FROM_CART = defineEvent<'REMOVE_FROM_CART', { productId: string }>(
+  'REMOVE_FROM_CART'
+);
+export const UPDATE_QUANTITY = defineEvent<
+  'UPDATE_QUANTITY',
+  { productId: string; quantity: number }
+>('UPDATE_QUANTITY');
 export const START_CHECKOUT = defineEvent<'START_CHECKOUT', {}>('START_CHECKOUT');
-export const ENTER_SHIPPING = defineEvent<'ENTER_SHIPPING', { address: ShippingAddress }>('ENTER_SHIPPING');
+export const ENTER_SHIPPING = defineEvent<'ENTER_SHIPPING', { address: ShippingAddress }>(
+  'ENTER_SHIPPING'
+);
 export const ENTER_PAYMENT = defineEvent<'ENTER_PAYMENT', { method: string }>('ENTER_PAYMENT');
 export const CONFIRM_ORDER = defineEvent<'CONFIRM_ORDER', {}>('CONFIRM_ORDER');
 export const GO_BACK = defineEvent<'GO_BACK', {}>('GO_BACK');
@@ -148,20 +172,20 @@ const addToCartRule = defineRule<CartContext>({
   impl: (state, events) => {
     const event = events.find(ADD_TO_CART.is);
     if (!event) return [];
-    
-    const product = state.context.products.find(p => p.id === event.payload.productId);
+
+    const product = state.context.products.find((p) => p.id === event.payload.productId);
     if (!product) {
       state.context.lastError = 'Product not found';
       return [];
     }
-    
+
     if (product.stock < event.payload.quantity) {
       state.context.lastError = 'Not enough stock';
       return [];
     }
-    
+
     // Check if already in cart
-    const existingItem = state.context.cart.find(i => i.productId === event.payload.productId);
+    const existingItem = state.context.cart.find((i) => i.productId === event.payload.productId);
     if (existingItem) {
       existingItem.quantity += event.payload.quantity;
     } else {
@@ -171,9 +195,14 @@ const addToCartRule = defineRule<CartContext>({
         priceAtAdd: product.price,
       });
     }
-    
+
     state.context.lastError = null;
-    return [ItemAddedToCart.create({ productId: event.payload.productId, quantity: event.payload.quantity })];
+    return [
+      ItemAddedToCart.create({
+        productId: event.payload.productId,
+        quantity: event.payload.quantity,
+      }),
+    ];
   },
 });
 
@@ -183,10 +212,10 @@ const removeFromCartRule = defineRule<CartContext>({
   impl: (state, events) => {
     const event = events.find(REMOVE_FROM_CART.is);
     if (!event) return [];
-    
-    state.context.cart = state.context.cart.filter(i => i.productId !== event.payload.productId);
+
+    state.context.cart = state.context.cart.filter((i) => i.productId !== event.payload.productId);
     state.context.lastError = null;
-    
+
     return [ItemRemovedFromCart.create({ productId: event.payload.productId })];
   },
 });
@@ -197,24 +226,31 @@ const updateQuantityRule = defineRule<CartContext>({
   impl: (state, events) => {
     const event = events.find(UPDATE_QUANTITY.is);
     if (!event) return [];
-    
-    const item = state.context.cart.find(i => i.productId === event.payload.productId);
+
+    const item = state.context.cart.find((i) => i.productId === event.payload.productId);
     if (!item) return [];
-    
-    const product = state.context.products.find(p => p.id === event.payload.productId);
+
+    const product = state.context.products.find((p) => p.id === event.payload.productId);
     if (product && event.payload.quantity > product.stock) {
       state.context.lastError = 'Not enough stock';
       return [];
     }
-    
+
     if (event.payload.quantity <= 0) {
-      state.context.cart = state.context.cart.filter(i => i.productId !== event.payload.productId);
+      state.context.cart = state.context.cart.filter(
+        (i) => i.productId !== event.payload.productId
+      );
     } else {
       item.quantity = event.payload.quantity;
     }
-    
+
     state.context.lastError = null;
-    return [QuantityUpdated.create({ productId: event.payload.productId, newQuantity: event.payload.quantity })];
+    return [
+      QuantityUpdated.create({
+        productId: event.payload.productId,
+        newQuantity: event.payload.quantity,
+      }),
+    ];
   },
 });
 
@@ -224,15 +260,15 @@ const startCheckoutRule = defineRule<CartContext>({
   impl: (state, events) => {
     const event = events.find(START_CHECKOUT.is);
     if (!event) return [];
-    
+
     if (state.context.cart.length === 0) {
       state.context.lastError = 'Cart is empty';
       return [];
     }
-    
+
     state.context.checkoutStep = 'shipping';
     state.context.lastError = null;
-    
+
     return [CheckoutStarted.create({})];
   },
 });
@@ -243,11 +279,11 @@ const enterShippingRule = defineRule<CartContext>({
   impl: (state, events) => {
     const event = events.find(ENTER_SHIPPING.is);
     if (!event) return [];
-    
+
     state.context.shippingAddress = event.payload.address;
     state.context.checkoutStep = 'payment';
     state.context.lastError = null;
-    
+
     return [ShippingEntered.create({ address: event.payload.address })];
   },
 });
@@ -258,11 +294,11 @@ const enterPaymentRule = defineRule<CartContext>({
   impl: (state, events) => {
     const event = events.find(ENTER_PAYMENT.is);
     if (!event) return [];
-    
+
     state.context.paymentMethod = event.payload.method;
     state.context.checkoutStep = 'confirmation';
     state.context.lastError = null;
-    
+
     return [];
   },
 });
@@ -273,17 +309,17 @@ const confirmOrderRule = defineRule<CartContext>({
   impl: (state, events) => {
     const event = events.find(CONFIRM_ORDER.is);
     if (!event) return [];
-    
+
     if (!state.context.shippingAddress || !state.context.paymentMethod) {
       state.context.lastError = 'Missing checkout information';
       return [];
     }
-    
+
     // Calculate total
     const total = state.context.cart.reduce((sum, item) => {
-      return sum + (item.priceAtAdd * item.quantity);
+      return sum + item.priceAtAdd * item.quantity;
     }, 0);
-    
+
     // Create order
     const orderId = `order_${Date.now().toString(36)}`;
     const order: Order = {
@@ -294,24 +330,24 @@ const confirmOrderRule = defineRule<CartContext>({
       shippingAddress: state.context.shippingAddress,
       createdAt: new Date(),
     };
-    
+
     state.context.orders.push(order);
-    
+
     // Update stock
     for (const item of state.context.cart) {
-      const product = state.context.products.find(p => p.id === item.productId);
+      const product = state.context.products.find((p) => p.id === item.productId);
       if (product) {
         product.stock -= item.quantity;
       }
     }
-    
+
     // Clear cart and reset checkout
     state.context.cart = [];
     state.context.checkoutStep = 'cart';
     state.context.shippingAddress = null;
     state.context.paymentMethod = null;
     state.context.lastError = null;
-    
+
     return [
       PaymentProcessed.create({ success: true }),
       OrderPlaced.create({ orderId, total }),
@@ -326,14 +362,14 @@ const goBackRule = defineRule<CartContext>({
   impl: (state, events) => {
     const event = events.find(GO_BACK.is);
     if (!event) return [];
-    
+
     const stepOrder: CheckoutStep[] = ['cart', 'shipping', 'payment', 'confirmation'];
     const currentIndex = stepOrder.indexOf(state.context.checkoutStep);
-    
+
     if (currentIndex > 0) {
       state.context.checkoutStep = stepOrder[currentIndex - 1];
     }
-    
+
     return [];
   },
 });
@@ -344,12 +380,12 @@ const clearCartRule = defineRule<CartContext>({
   impl: (state, events) => {
     const event = events.find(CLEAR_CART.is);
     if (!event) return [];
-    
+
     state.context.cart = [];
     state.context.checkoutStep = 'cart';
     state.context.shippingAddress = null;
     state.context.paymentMethod = null;
-    
+
     return [CartCleared.create({})];
   },
 });
@@ -366,7 +402,7 @@ const maxCartItemsConstraint = defineConstraint<CartContext>({
 const maxQuantityConstraint = defineConstraint<CartContext>({
   id: 'cart.maxQuantity',
   description: 'Cannot order more than 10 of each item',
-  check: (state) => state.context.cart.every(item => item.quantity <= 10),
+  check: (state) => state.context.cart.every((item) => item.quantity <= 10),
   errorMessage: 'Cannot order more than 10 of each item',
   severity: 'error',
 });
@@ -376,7 +412,7 @@ const stockConstraint = defineConstraint<CartContext>({
   description: 'Cart items must be in stock',
   check: (state) => {
     for (const item of state.context.cart) {
-      const product = state.context.products.find(p => p.id === item.productId);
+      const product = state.context.products.find((p) => p.id === item.productId);
       if (!product || product.stock < item.quantity) {
         return false;
       }
@@ -404,11 +440,46 @@ registry.registerConstraint(stockConstraint);
 
 // Sample products
 const sampleProducts: Product[] = [
-  { id: 'p1', name: 'Laptop', description: 'High-performance laptop', price: 999.99, stock: 10, imageUrl: '' },
-  { id: 'p2', name: 'Headphones', description: 'Wireless headphones', price: 149.99, stock: 25, imageUrl: '' },
-  { id: 'p3', name: 'Keyboard', description: 'Mechanical keyboard', price: 79.99, stock: 50, imageUrl: '' },
-  { id: 'p4', name: 'Mouse', description: 'Wireless mouse', price: 49.99, stock: 100, imageUrl: '' },
-  { id: 'p5', name: 'Monitor', description: '27" 4K monitor', price: 399.99, stock: 5, imageUrl: '' },
+  {
+    id: 'p1',
+    name: 'Laptop',
+    description: 'High-performance laptop',
+    price: 999.99,
+    stock: 10,
+    imageUrl: '',
+  },
+  {
+    id: 'p2',
+    name: 'Headphones',
+    description: 'Wireless headphones',
+    price: 149.99,
+    stock: 25,
+    imageUrl: '',
+  },
+  {
+    id: 'p3',
+    name: 'Keyboard',
+    description: 'Mechanical keyboard',
+    price: 79.99,
+    stock: 50,
+    imageUrl: '',
+  },
+  {
+    id: 'p4',
+    name: 'Mouse',
+    description: 'Wireless mouse',
+    price: 49.99,
+    stock: 100,
+    imageUrl: '',
+  },
+  {
+    id: 'p5',
+    name: 'Monitor',
+    description: '27" 4K monitor',
+    price: 399.99,
+    stock: 5,
+    imageUrl: '',
+  },
 ];
 
 // Engine factory
@@ -430,7 +501,7 @@ export function createCartEngine() {
 
 // Helper functions
 export function getCartTotal(context: CartContext): number {
-  return context.cart.reduce((sum, item) => sum + (item.priceAtAdd * item.quantity), 0);
+  return context.cart.reduce((sum, item) => sum + item.priceAtAdd * item.quantity, 0);
 }
 
 export function getCartItemCount(context: CartContext): number {
@@ -463,22 +534,24 @@ import {
 
 async function main() {
   console.log('🛒 E-commerce Cart Demo\n');
-  
+
   const engine = createCartEngine();
-  
+
   // Helper to display cart
   function displayCart() {
     const ctx = engine.getContext();
     console.log('\n📦 Cart:');
     console.log('─'.repeat(50));
-    
+
     if (ctx.cart.length === 0) {
       console.log('  (empty)');
     } else {
       ctx.cart.forEach((item, i) => {
-        const product = ctx.products.find(p => p.id === item.productId)!;
+        const product = ctx.products.find((p) => p.id === item.productId)!;
         const subtotal = item.quantity * item.priceAtAdd;
-        console.log(`  ${i + 1}. ${product.name} x${item.quantity} @ $${item.priceAtAdd.toFixed(2)} = $${subtotal.toFixed(2)}`);
+        console.log(
+          `  ${i + 1}. ${product.name} x${item.quantity} @ $${item.priceAtAdd.toFixed(2)} = $${subtotal.toFixed(2)}`
+        );
       });
       console.log('─'.repeat(50));
       console.log(`  Items: ${getCartItemCount(ctx)}`);
@@ -486,65 +559,73 @@ async function main() {
     }
     console.log('');
   }
-  
+
   // Display products
   console.log('📋 Available Products:');
   engine.getContext().products.forEach((p, i) => {
     console.log(`  ${i + 1}. ${p.name} - $${p.price.toFixed(2)} (${p.stock} in stock)`);
   });
-  
+
   displayCart();
-  
+
   // Add items to cart
   console.log('Adding items to cart...');
   engine.dispatch([ADD_TO_CART.create({ productId: 'p1', quantity: 1 })]); // Laptop
   engine.dispatch([ADD_TO_CART.create({ productId: 'p2', quantity: 2 })]); // Headphones x2
   engine.dispatch([ADD_TO_CART.create({ productId: 'p4', quantity: 1 })]); // Mouse
-  
+
   displayCart();
-  
+
   // Update quantity
   console.log('Updating headphones quantity to 3...');
   engine.dispatch([UPDATE_QUANTITY.create({ productId: 'p2', quantity: 3 })]);
-  
+
   displayCart();
-  
+
   // Start checkout
   console.log('Starting checkout...');
   engine.dispatch([START_CHECKOUT.create({})]);
-  console.log(`Checkout step: ${engine.getContext().checkoutStep} (${getCheckoutStepNumber(engine.getContext().checkoutStep)}/4)`);
-  
+  console.log(
+    `Checkout step: ${engine.getContext().checkoutStep} (${getCheckoutStepNumber(engine.getContext().checkoutStep)}/4)`
+  );
+
   // Enter shipping
   console.log('\nEntering shipping information...');
-  engine.dispatch([ENTER_SHIPPING.create({
-    address: {
-      name: 'John Doe',
-      street: '123 Main St',
-      city: 'San Francisco',
-      state: 'CA',
-      zip: '94105',
-      country: 'USA',
-    },
-  })]);
-  console.log(`Checkout step: ${engine.getContext().checkoutStep} (${getCheckoutStepNumber(engine.getContext().checkoutStep)}/4)`);
-  
+  engine.dispatch([
+    ENTER_SHIPPING.create({
+      address: {
+        name: 'John Doe',
+        street: '123 Main St',
+        city: 'San Francisco',
+        state: 'CA',
+        zip: '94105',
+        country: 'USA',
+      },
+    }),
+  ]);
+  console.log(
+    `Checkout step: ${engine.getContext().checkoutStep} (${getCheckoutStepNumber(engine.getContext().checkoutStep)}/4)`
+  );
+
   // Enter payment
   console.log('\nEntering payment method...');
   engine.dispatch([ENTER_PAYMENT.create({ method: 'credit_card' })]);
-  console.log(`Checkout step: ${engine.getContext().checkoutStep} (${getCheckoutStepNumber(engine.getContext().checkoutStep)}/4)`);
-  
+  console.log(
+    `Checkout step: ${engine.getContext().checkoutStep} (${getCheckoutStepNumber(engine.getContext().checkoutStep)}/4)`
+  );
+
   // Confirm order
   console.log('\nConfirming order...');
   const result = engine.step([CONFIRM_ORDER.create({})]);
-  
+
   // Check for order confirmation
-  const orderPlaced = result.state.facts.find(f => f.tag === 'OrderPlaced');
+  const orderPlaced = result.state.facts.find((f) => f.tag === 'OrderPlaced');
   if (orderPlaced) {
     console.log('✅ Order placed successfully!');
     console.log(`   Order ID: ${(orderPlaced.payload as any).orderId}`);
     console.log(`   Total: $${(orderPlaced.payload as any).total.toFixed(2)}`);
   }
-  
+
   // Display orders
   console.log('\n📋 Orders:');
   console.log('─'.repeat(50));
@@ -555,15 +636,15 @@ async function main() {
     console.log(`     Items: ${order.items.length}`);
     console.log(`     Created: ${order.createdAt.toLocaleString()}`);
   });
-  
+
   // Show updated stock
   console.log('\n📦 Updated Stock:');
   engine.getContext().products.forEach((p, i) => {
     console.log(`  ${i + 1}. ${p.name} - ${p.stock} in stock`);
   });
-  
+
   displayCart();
-  
+
   console.log('🎉 Done!');
 }
 
@@ -601,9 +682,10 @@ Enforcing business rules:
 
 ```typescript
 const stockConstraint = defineConstraint({
-  check: (state) => state.context.cart.every(item => 
-    products.find(p => p.id === item.productId)?.stock >= item.quantity
-  ),
+  check: (state) =>
+    state.context.cart.every(
+      (item) => products.find((p) => p.id === item.productId)?.stock >= item.quantity
+    ),
 });
 ```