@fairfox/polly 0.13.2 → 0.14.1

package/dist/tools/analysis/src/extract/handlers.d.ts

@@ -92,13 +92,24 @@ export declare class HandlerExtractor {
      */
     private extractSimpleOrElementAccessAssignment;
     /**
-     * Extract property access assignment (state.field = value)
+     * Extract property access assignment (state.field = value or someState.value.field = value)
      */
     private extractPropertyAccessAssignment;
+    /**
+     * Extract assignments from object literal properties
+     * Used for: someState.value = { field1: value1, field2: value2 }
+     */
+    private extractObjectLiteralAssignments;
     /**
      * Extract element access assignment (state.items[index] = value)
      */
     private extractElementAccessAssignment;
+    /**
+     * Check if field path is a state mutation pattern and extract field name
+     * Supports: state.field, someState.value.field
+     * Returns: field name or null if not a state pattern
+     */
+    private extractFieldFromStatePath;
     /**
      * Extract compound assignments (+=, -=, *=, /=, %=)
      */

package/dist/tools/teach/src/cli.js

@@ -5747,6 +5747,39 @@ class HandlerExtractor {
       if (value !== undefined) {
         assignments.push({ field, value });
       }
+      return;
+    }
+    const valueMatch = fieldPath.match(/\.value\.(.+)$/);
+    if (valueMatch && valueMatch[1]) {
+      const field = valueMatch[1];
+      const value = this.extractValue(right);
+      if (value !== undefined) {
+        assignments.push({ field, value });
+      }
+      return;
+    }
+    if (fieldPath.endsWith(".value") && Node4.isObjectLiteralExpression(right)) {
+      this.extractObjectLiteralAssignments(right, assignments);
+    }
+  }
+  extractObjectLiteralAssignments(objectLiteral, assignments) {
+    if (!Node4.isObjectLiteralExpression(objectLiteral))
+      return;
+    for (const prop of objectLiteral.getProperties()) {
+      if (Node4.isPropertyAssignment(prop)) {
+        const name = prop.getName();
+        const initializer = prop.getInitializer();
+        if (!name || !initializer)
+          continue;
+        const value = this.extractValue(initializer);
+        if (value !== undefined) {
+          assignments.push({ field: name, value });
+        }
+      }
+      if (Node4.isShorthandPropertyAssignment(prop)) {
+        const name = prop.getName();
+        assignments.push({ field: name, value: "@" });
+      }
     }
   }
   extractElementAccessAssignment(left, right, assignments) {
@@ -5756,9 +5789,9 @@ class HandlerExtractor {
     if (!Node4.isPropertyAccessExpression(expr))
       return;
     const fieldPath = this.getPropertyPath(expr);
-    if (!fieldPath.startsWith("state."))
+    const field = this.extractFieldFromStatePath(fieldPath);
+    if (!field)
       return;
-    const field = fieldPath.substring(6);
     const indexExpr = left.getArgumentExpression();
     const index = indexExpr ? indexExpr.getText() : "0";
     const value = this.extractValue(right);
@@ -5770,6 +5803,16 @@ class HandlerExtractor {
       });
     }
   }
+  extractFieldFromStatePath(fieldPath) {
+    if (fieldPath.startsWith("state.")) {
+      return fieldPath.substring(6);
+    }
+    const valueMatch = fieldPath.match(/\.value\.(.+)$/);
+    if (valueMatch && valueMatch[1]) {
+      return valueMatch[1];
+    }
+    return null;
+  }
   extractCompoundAssignment(node, assignments) {
     if (!Node4.isBinaryExpression(node))
       return;
@@ -5778,8 +5821,8 @@ class HandlerExtractor {
     const right = node.getRight();
     if (Node4.isPropertyAccessExpression(left)) {
       const fieldPath = this.getPropertyPath(left);
-      if (fieldPath.startsWith("state.")) {
-        const field = fieldPath.substring(6);
+      const field = this.extractFieldFromStatePath(fieldPath);
+      if (field) {
         const rightValue = right.getText();
         const tlaOp = operator.slice(0, -1);
         assignments.push({
@@ -5813,8 +5856,8 @@ class HandlerExtractor {
     if (!Node4.isPropertyAccessExpression(operand))
       return;
     const fieldPath = this.getPropertyPath(operand);
-    if (fieldPath.startsWith("state.")) {
-      const field = fieldPath.substring(6);
+    const field = this.extractFieldFromStatePath(fieldPath);
+    if (field) {
       const value = operatorText === "++" ? "@ + 1" : "@ - 1";
       assignments.push({ field, value });
     }
@@ -5829,8 +5872,8 @@ class HandlerExtractor {
     const object = expr.getExpression();
     if (Node4.isPropertyAccessExpression(object)) {
       const fieldPath = this.getPropertyPath(object);
-      if (fieldPath.startsWith("state.")) {
-        const field = fieldPath.substring(6);
+      const field = this.extractFieldFromStatePath(fieldPath);
+      if (field) {
         const args = node.getArguments().map((arg) => arg.getText());
         const tlaValue = this.translateArrayMethod(methodName, args, fieldPath);
         if (tlaValue) {
@@ -6470,8 +6513,8 @@ class HandlerExtractor {
     if (!Node4.isPropertyAccessExpression(left) && !Node4.isElementAccessExpression(left))
       return;
     const fieldPath = Node4.isPropertyAccessExpression(left) ? this.getPropertyPath(left) : this.getPropertyPath(left.getExpression());
-    if (fieldPath.startsWith("state.")) {
-      const field = fieldPath.substring(6);
+    const field = this.extractFieldFromStatePath(fieldPath);
+    if (field) {
       const line = node.getStartLineNumber();
       const afterAwait = node.getStart() > firstAwaitPos;
       mutations.push({ field, line, afterAwait });
@@ -6488,10 +6531,8 @@ class HandlerExtractor {
     if (!Node4.isPropertyAccessExpression(object))
       return;
     const fieldPath = this.getPropertyPath(object);
-    if (!fieldPath.startsWith("state."))
-      return;
-    if (["push", "pop", "shift", "unshift", "splice"].includes(methodName)) {
-      const field = fieldPath.substring(6);
+    const field = this.extractFieldFromStatePath(fieldPath);
+    if (field && ["push", "pop", "shift", "unshift", "splice"].includes(methodName)) {
       const line = node.getStartLineNumber();
       const afterAwait = node.getStart() > firstAwaitPos;
       mutations.push({ field, line, afterAwait });
@@ -9061,6 +9102,32 @@ ${generateVerificationSection(context)}
   - Files outside src/ are automatically found if imported from handler files
   - This enables clean separation of verification code from runtime code
 
+# Verification Parameters Explained
+
+When explaining verification configuration, help users understand what each parameter controls:
+
+**maxDepth**: Maximum number of **sequential** message deliveries to check
+- Depth 4 = check sequences up to 4 messages delivered one after another
+- Depth 8 = check sequences up to 8 messages delivered one after another
+- Question to ask: "What's the longest sequence of messages that could expose a bug in my app?"
+- Most authentication/state machine bugs appear in shallow sequences (depth 2-4)
+
+**maxInFlight**: Maximum number of **concurrent** messages in the system at once
+- 2 = check scenarios with up to 2 messages pending simultaneously
+- 3 = check scenarios with up to 3 messages pending simultaneously
+- Question: "How many concurrent messages can actually happen in my app?"
+- Consider different bounds per message type (auth should be 1, queries could be higher)
+
+**maxTabs**: Number of concurrent contexts (tabs, workers, etc.)
+- Question: "How many concurrent contexts do I need to verify for race conditions?"
+- Most single-tab apps only need 1; multi-tab/worker apps need 2+
+
+**Practical Guidance**:
+- Start conservative: maxDepth: 3-4, maxInFlight: 2, maxTabs: 1
+- Use timeouts (5-10 minutes) to prevent runaway verification
+- Don't arbitrarily exclude message types to speed up verification - tune the bounds instead
+- If verification takes hours, bounds are likely too high for regular development workflows
+
 # Elysia/Bun Integration
 
 Polly now provides first-class support for Elysia (Bun-first web framework) with Eden type-safe client generation:
@@ -9109,6 +9176,8 @@ const app = new Elysia()
       'POST /todos': {
         queue: true,
         optimistic: (body) => ({ id: -Date.now(), ...body }),
+        merge: 'replace',  // 'replace' | custom merge function
+        conflictResolution: 'last-write-wins',  // 'last-write-wins' | 'server-wins' | custom function
       },
     },
   }))
@@ -9125,6 +9194,30 @@ const app = new Elysia()
 - In production: Pass-through (minimal overhead) - client effects are bundled at build time
 - Authorization and broadcasts work in both modes
 
+**Offline Behavior Configuration:**
+
+The \`offline\` config enables Progressive Web App capabilities:
+
+\`\`\`typescript
+offline: {
+  'POST /todos': {
+    queue: true,                          // Queue request when offline
+    optimistic: (body) => TResult,        // Immediate UI update with predicted result
+    merge: 'replace' | mergeFn,           // How to merge optimistic with server result
+    conflictResolution: 'last-write-wins' | 'server-wins' | resolveFn,
+  },
+}
+\`\`\`
+
+**Merge Strategies:**
+- \`'replace'\`: Replace optimistic result with server result (default)
+- \`(optimistic, server) => TResult\`: Custom merge logic
+
+**Conflict Resolution** (when multiple devices edit offline):
+- \`'last-write-wins'\`: Lamport clock determines winner
+- \`'server-wins'\`: Server state always takes precedence
+- \`(client, server) => TResult\`: Custom conflict resolution
+
 ## Client-Side Wrapper (\`@fairfox/polly/client\`)
 
 Enhances Eden treaty client with Polly features:
@@ -9503,6 +9596,32 @@ ${generateProjectSection(context, contexts2, allHandlers, messageFlows)}
 
 ${generateVerificationSection(context)}
 
+# Understanding Verification Parameters
+
+Before suggesting optimizations, understand what each parameter actually controls:
+
+**maxDepth**: Maximum number of **sequential** message deliveries to check
+- Depth 4 = check sequences up to 4 messages delivered one after another
+- Depth 8 = check sequences up to 8 messages delivered one after another
+- Question to ask: "What's the longest sequence of messages that could expose a bug in my app?"
+- Most authentication/state machine bugs appear in shallow sequences (depth 2-4)
+
+**maxInFlight**: Maximum number of **concurrent** messages in the system at once
+- 2 = check scenarios with up to 2 messages pending simultaneously
+- 3 = check scenarios with up to 3 messages pending simultaneously
+- Question: "How many concurrent messages can actually happen in my app?"
+- Consider different bounds per message type (auth should be 1, queries could be higher)
+
+**maxTabs**: Number of concurrent contexts (tabs, workers, etc.)
+- Question: "How many concurrent contexts do I need to verify for race conditions?"
+- Most single-tab apps only need 1; multi-tab/worker apps need 2+
+
+**Practical Approach**:
+- Start conservative: maxDepth: 3-4, maxInFlight: 2, maxTabs: 1
+- Use timeouts (5-10 minutes) to prevent runaway verification
+- Don't arbitrarily exclude message types - tune the bounds instead
+- If verification takes hours, bounds are likely too high for regular development
+
 # Your Expertise: Optimization Tiers
 
 ## Tier 1: Safe Optimizations (ZERO precision loss)
@@ -9806,4 +9925,4 @@ Goodbye!`);
 }
 main();
 
-//# debugId=53EFCFE442D6558B64756E2164756E21
+//# debugId=0C5B6EFE146F7BE464756E2164756E21