@fairfox/polly 0.10.0 → 0.11.0

package/README.md

@@ -343,6 +343,192 @@ test('user profile updates', async ({ page, extensionId }) => {
 })
 ```
 
+### Full-Stack SPAs with Elysia (Bun)
+
+Polly provides first-class support for building full-stack web applications with Elysia and Bun, treating your SPA as a distributed system.
+
+**Why?** Modern SPAs are distributed systems facing classic distributed computing problems: network unreliability, eventual consistency, offline behavior, cache invalidation, and the CAP theorem. The Elysia integration makes these concerns explicit and verifiable.
+
+#### Server: Add Polly Middleware
+
+```typescript
+// server/index.ts
+import { Elysia, t } from 'elysia'
+import { polly } from '@fairfox/polly/elysia'
+import { $syncedState, $serverState } from '@fairfox/polly'
+
+const app = new Elysia()
+  .use(polly({
+    // Define shared state
+    state: {
+      client: {
+        todos: $syncedState('todos', []),
+        user: $syncedState('user', null),
+      },
+      server: {
+        db: $serverState('db', database),
+      },
+    },
+
+    // Define client-side effects (what happens after server operations)
+    effects: {
+      'POST /todos': {
+        client: ({ result, state }) => {
+          // Update client state with new todo
+          state.client.todos.value = [...state.client.todos.value, result]
+        },
+        broadcast: true,  // Notify all connected clients
+      },
+      'PATCH /todos/:id': {
+        client: ({ result, state }) => {
+          // Update specific todo in client state
+          state.client.todos.value = state.client.todos.value.map(t =>
+            t.id === result.id ? result : t
+          )
+        },
+        broadcast: true,
+      },
+      'DELETE /todos/:id': {
+        client: ({ params, state }) => {
+          // Remove todo from client state
+          state.client.todos.value = state.client.todos.value.filter(
+            t => t.id !== Number(params.id)
+          )
+        },
+        broadcast: true,
+      },
+    },
+
+    // Define authorization rules
+    authorization: {
+      'POST /todos': ({ state }) => state.client.user.value !== null,
+      'PATCH /todos/:id': ({ state }) => state.client.user.value !== null,
+      'DELETE /todos/:id': ({ state }) => state.client.user.value !== null,
+    },
+
+    // Configure offline behavior
+    offline: {
+      'POST /todos': {
+        queue: true,  // Queue when offline
+        optimistic: (body) => ({
+          id: -Date.now(),  // Temporary ID
+          text: body.text,
+          completed: false,
+        }),
+      },
+    },
+
+    // Enable TLA+ generation for verification
+    tlaGeneration: true,
+  }))
+
+  // Write normal Elysia routes (no Polly annotations!)
+  .post('/todos', async ({ body, pollyState }) => {
+    const todo = await pollyState.server.db.value.todos.create(body)
+    return todo
+  }, {
+    body: t.Object({ text: t.String() })
+  })
+
+  .listen(3000)
+```
+
+#### Client: Use Eden with Polly Wrapper
+
+```typescript
+// client/api.ts
+import { createPollyClient } from '@fairfox/polly/client'
+import { $syncedState } from '@fairfox/polly'
+import type { app } from '../server'  // Import server type!
+
+// Define client state
+export const clientState = {
+  todos: $syncedState('todos', []),
+  user: $syncedState('user', null),
+}
+
+// Create type-safe API client (types inferred from server!)
+export const api = createPollyClient<typeof app>('http://localhost:3000', {
+  state: clientState,
+  websocket: true,  // Enable real-time updates
+})
+```
+
+```typescript
+// client/components/TodoList.tsx
+import { useSignal } from '@preact/signals'
+import { api, clientState } from '../api'
+
+export function TodoList() {
+  const newTodo = useSignal('')
+
+  async function handleAdd() {
+    // Automatically handles:
+    // - Optimistic update if offline
+    // - Queue for retry
+    // - Execute client effect on success
+    // - Broadcast to other clients
+    await api.todos.post({ text: newTodo.value })
+    newTodo.value = ''
+  }
+
+  return (
+    <div>
+      {/* Connection status */}
+      <div>Status: {api.$polly.state.isOnline.value ? '🟢 Online' : '🔴 Offline'}</div>
+
+      {/* Queued requests indicator */}
+      {api.$polly.state.queuedRequests.value.length > 0 && (
+        <div>{api.$polly.state.queuedRequests.value.length} requests queued</div>
+      )}
+
+      {/* Todo list (automatically updates from state) */}
+      <ul>
+        {clientState.todos.value.map(todo => (
+          <li key={todo.id}>
+            <input
+              type="checkbox"
+              checked={todo.completed}
+              onChange={() => api.todos[todo.id].patch({ completed: !todo.completed })}
+            />
+            <span>{todo.text}</span>
+            <button onClick={() => api.todos[todo.id].delete()}>Delete</button>
+          </li>
+        ))}
+      </ul>
+
+      {/* Add new todo */}
+      <input
+        value={newTodo.value}
+        onInput={(e) => newTodo.value = e.currentTarget.value}
+        placeholder="What needs to be done?"
+      />
+      <button onClick={handleAdd}>Add</button>
+    </div>
+  )
+}
+```
+
+#### Key Benefits
+
+1. **Zero Type Duplication** - Eden infers client types from Elysia routes automatically
+2. **Distributed Systems Semantics** - Explicit offline, authorization, and effects configuration
+3. **Production-Ready** - Middleware is pass-through in production (minimal overhead)
+4. **Real-Time Updates** - WebSocket broadcast keeps all clients in sync
+5. **Formal Verification** - Generate TLA+ specs from middleware config to verify distributed properties
+
+#### Production vs Development
+
+**Development Mode:**
+- Middleware adds metadata to responses for hot-reload and debugging
+- Client effects serialized from server for live updates
+- TLA+ generation enabled for verification
+
+**Production Mode:**
+- Middleware is minimal (authorization + broadcast only)
+- Client effects are bundled at build time
+- Zero serialization overhead
+
 ## Core Concepts
 
 ### State Primitives

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

@@ -5435,40 +5435,116 @@ class HandlerExtractor {
   project;
   typeGuardCache;
   relationshipExtractor;
+  analyzedFiles;
+  packageRoot;
   constructor(tsConfigPath) {
     this.project = new Project3({
       tsConfigFilePath: tsConfigPath
     });
     this.typeGuardCache = new WeakMap;
     this.relationshipExtractor = new RelationshipExtractor;
+    this.analyzedFiles = new Set;
+    this.packageRoot = this.findPackageRoot(tsConfigPath);
+  }
+  findPackageRoot(tsConfigPath) {
+    let dir = tsConfigPath.substring(0, tsConfigPath.lastIndexOf("/"));
+    while (dir.length > 1) {
+      try {
+        const packageJsonPath = `${dir}/package.json`;
+        const file = Bun.file(packageJsonPath);
+        if (file.size > 0) {
+          return dir;
+        }
+      } catch {}
+      const parentDir = dir.substring(0, dir.lastIndexOf("/"));
+      if (parentDir === dir)
+        break;
+      dir = parentDir;
+    }
+    return tsConfigPath.substring(0, tsConfigPath.lastIndexOf("/"));
   }
   extractHandlers() {
     const handlers = [];
     const messageTypes = new Set;
     const invalidMessageTypes = new Set;
     const stateConstraints = [];
-    const sourceFiles = this.project.getSourceFiles();
-    this.debugLogSourceFiles(sourceFiles);
-    for (const sourceFile of sourceFiles) {
-      const fileHandlers = this.extractFromFile(sourceFile);
-      handlers.push(...fileHandlers);
-      this.categorizeHandlerMessageTypes(fileHandlers, messageTypes, invalidMessageTypes);
-      const fileConstraints = this.extractStateConstraintsFromFile(sourceFile);
-      stateConstraints.push(...fileConstraints);
+    const allSourceFiles = this.project.getSourceFiles();
+    const entryPoints = allSourceFiles.filter((f) => this.isWithinPackage(f.getFilePath()));
+    this.debugLogSourceFiles(allSourceFiles, entryPoints);
+    for (const entryPoint of entryPoints) {
+      this.analyzeFileAndImports(entryPoint, handlers, messageTypes, invalidMessageTypes, stateConstraints);
     }
     this.debugLogExtractionResults(handlers.length, invalidMessageTypes.size);
+    this.debugLogAnalysisStats(allSourceFiles.length, entryPoints.length);
     return {
       handlers,
       messageTypes,
       stateConstraints
     };
   }
-  debugLogSourceFiles(sourceFiles) {
+  analyzeFileAndImports(sourceFile, handlers, messageTypes, invalidMessageTypes, stateConstraints) {
+    const filePath = sourceFile.getFilePath();
+    if (this.analyzedFiles.has(filePath)) {
+      return;
+    }
+    this.analyzedFiles.add(filePath);
+    if (process.env["POLLY_DEBUG"]) {
+      console.log(`[DEBUG] Analyzing: ${filePath}`);
+    }
+    const fileHandlers = this.extractFromFile(sourceFile);
+    handlers.push(...fileHandlers);
+    this.categorizeHandlerMessageTypes(fileHandlers, messageTypes, invalidMessageTypes);
+    const fileConstraints = this.extractStateConstraintsFromFile(sourceFile);
+    stateConstraints.push(...fileConstraints);
+    const importDeclarations = sourceFile.getImportDeclarations();
+    for (const importDecl of importDeclarations) {
+      const importedFile = importDecl.getModuleSpecifierSourceFile();
+      if (importedFile) {
+        const importedPath = importedFile.getFilePath();
+        if (!this.isWithinPackage(importedPath)) {
+          if (process.env["POLLY_DEBUG"]) {
+            console.log(`[DEBUG] Skipping external import: ${importedPath}`);
+          }
+          continue;
+        }
+        this.analyzeFileAndImports(importedFile, handlers, messageTypes, invalidMessageTypes, stateConstraints);
+      } else if (process.env["POLLY_DEBUG"]) {
+        const specifier = importDecl.getModuleSpecifierValue();
+        if (!specifier.startsWith("node:") && !this.isNodeModuleImport(specifier)) {
+          console.log(`[DEBUG] Could not resolve import: ${specifier} in ${filePath}`);
+        }
+      }
+    }
+  }
+  isWithinPackage(filePath) {
+    if (!filePath.startsWith(this.packageRoot)) {
+      return false;
+    }
+    if (filePath.includes("/node_modules/")) {
+      return false;
+    }
+    return true;
+  }
+  isNodeModuleImport(specifier) {
+    return !specifier.startsWith(".") && !specifier.startsWith("/");
+  }
+  debugLogAnalysisStats(totalSourceFiles, entryPointCount) {
+    if (!process.env["POLLY_DEBUG"])
+      return;
+    console.log(`[DEBUG] Analysis Statistics:`);
+    console.log(`[DEBUG]   Package root: ${this.packageRoot}`);
+    console.log(`[DEBUG]   Source files from tsconfig: ${totalSourceFiles}`);
+    console.log(`[DEBUG]   Entry points (in package): ${entryPointCount}`);
+    console.log(`[DEBUG]   Files analyzed (including imports): ${this.analyzedFiles.size}`);
+    console.log(`[DEBUG]   Additional files discovered: ${this.analyzedFiles.size - entryPointCount}`);
+  }
+  debugLogSourceFiles(allSourceFiles, entryPoints) {
     if (!process.env["POLLY_DEBUG"])
       return;
-    console.log(`[DEBUG] Loaded ${sourceFiles.length} source files`);
-    if (sourceFiles.length <= 20) {
-      for (const sf of sourceFiles) {
+    console.log(`[DEBUG] Loaded ${allSourceFiles.length} source files from tsconfig`);
+    console.log(`[DEBUG] Filtered to ${entryPoints.length} entry points within package`);
+    if (entryPoints.length <= 20) {
+      for (const sf of entryPoints) {
         console.log(`[DEBUG]   - ${sf.getFilePath()}`);
       }
     }
@@ -8810,6 +8886,7 @@ ${generateVerificationSection(context)}
 - **Performance**: How to optimize verification speed and state space exploration
 - **Debugging**: Interpreting counterexamples and fixing violations
 - **Configuration**: Understanding maxInFlight, bounds, and other verification parameters
+- **Elysia Integration**: Using Polly with Elysia/Bun servers for full-stack distributed systems verification
 
 # Important Notes
 
@@ -8822,6 +8899,149 @@ ${generateVerificationSection(context)}
   - Example: \`$constraints("loggedIn", { USER_LOGOUT: { requires: "state.loggedIn === true" } })\`
   - This eliminates duplication and creates a single source of truth for state invariants
   - Parser extracts constraints and adds them to all relevant message handlers automatically
+  - **File Organization**: Constraints can be organized in separate files (e.g., specs/constraints.ts)
+  - **Transitive Discovery**: The analyzer uses transitive import following to discover constraints
+  - Files outside src/ are automatically found if imported from handler files
+  - This enables clean separation of verification code from runtime code
+
+# Elysia/Bun Integration
+
+Polly now provides first-class support for Elysia (Bun-first web framework) with Eden type-safe client generation:
+
+## Server-Side Middleware (\`@fairfox/polly/elysia\`)
+
+The \`polly()\` middleware adds distributed systems semantics to Elysia apps:
+
+**Key Features:**
+- **State Management**: Define client and server state signals
+- **Client Effects**: Specify what should happen on the client after server operations
+- **Authorization**: Route-level authorization rules
+- **Offline Behavior**: Configure optimistic updates and queueing
+- **WebSocket Broadcast**: Real-time updates to connected clients
+- **TLA+ Generation**: Automatic formal specification generation from routes + config
+
+**Example:**
+\`\`\`typescript
+import { Elysia, t } from 'elysia';
+import { polly } from '@fairfox/polly/elysia';
+import { $syncedState, $serverState } from '@fairfox/polly';
+
+const app = new Elysia()
+  .use(polly({
+    state: {
+      client: {
+        todos: $syncedState('todos', []),
+        user: $syncedState('user', null),
+      },
+      server: {
+        db: $serverState('db', db),
+      },
+    },
+    effects: {
+      'POST /todos': {
+        client: ({ result, state }) => {
+          state.client.todos.value = [...state.client.todos.value, result];
+        },
+        broadcast: true,  // Send to all connected clients
+      },
+    },
+    authorization: {
+      'POST /todos': ({ state }) => state.client.user.value !== null,
+    },
+    offline: {
+      'POST /todos': {
+        queue: true,
+        optimistic: (body) => ({ id: -Date.now(), ...body }),
+      },
+    },
+  }))
+  .post('/todos', handler, { body: t.Object({ text: t.String() }) });
+\`\`\`
+
+**Route Pattern Matching:**
+- Exact: \`'POST /todos'\`
+- Params: \`'GET /todos/:id'\`
+- Wildcard: \`'/todos/*'\`
+
+**Production Behavior:**
+- In development: Adds metadata to responses for hot-reload and debugging
+- In production: Pass-through (minimal overhead) - client effects are bundled at build time
+- Authorization and broadcasts work in both modes
+
+## Client-Side Wrapper (\`@fairfox/polly/client\`)
+
+Enhances Eden treaty client with Polly features:
+
+**Example:**
+\`\`\`typescript
+import { createPollyClient } from '@fairfox/polly/client';
+import { $syncedState } from '@fairfox/polly';
+import type { app } from './server';
+
+const clientState = {
+  todos: $syncedState('todos', []),
+  user: $syncedState('user', null),
+};
+
+export const api = createPollyClient<typeof app>('http://localhost:3000', {
+  state: clientState,
+  websocket: true,  // Enable real-time updates
+});
+
+// Use it (types are automatically inferred from server!)
+await api.todos.post({ text: 'Buy milk' });
+
+// Access Polly features
+console.log(api.$polly.state.isOnline.value);        // true/false
+console.log(api.$polly.state.queuedRequests.value);  // Queued requests
+api.$polly.sync();  // Manually sync queued requests
+\`\`\`
+
+**Key Features:**
+- Offline queueing with automatic retry
+- WebSocket connection for real-time updates
+- Lamport clock synchronization
+- Type inference from server via Eden
+
+## Why This Matters for Distributed Systems
+
+SPAs/PWAs are distributed systems facing classic problems:
+- **CAP theorem**: Must choose consistency vs availability during partitions
+- **Network unreliability**: The first fallacy of distributed computing
+- **Cache invalidation**: "One of the two hard things in computer science"
+- **Eventual consistency**: State sync across client/server
+- **Conflict resolution**: When multiple devices edit offline
+
+The Elysia integration addresses this by:
+1. Making distributed concerns explicit (offline, authorization, effects)
+2. Leveraging Eden for zero-duplication type safety
+3. Supporting verification via TLA+ generation from middleware config
+4. Providing WebSocket broadcast for real-time consistency
+
+## Architecture Pattern
+
+\`\`\`
+Browser (Client)
+  ├── Eden Treaty Client (types from Elysia)
+  ├── Polly Wrapper (offline, sync, WebSocket)
+  └── Client State ($syncedState)
+        │
+        │ HTTP / WebSocket
+        │
+Server (Elysia + Bun)
+  ├── Elysia Routes (normal routes)
+  ├── Polly Middleware (effects, auth, broadcast)
+  └── Server State ($serverState)
+\`\`\`
+
+## Best Practices
+
+1. **Separate Elysia is the contract** - Don't define types twice. Elysia routes define the API, Eden generates client types.
+2. **Effects describe client behavior** - Keep effects pure and deterministic.
+3. **Authorization at route level** - Centralize security rules in middleware config.
+4. **Queue selectively** - Only queue idempotent operations when offline.
+5. **Broadcast with filters** - Use broadcastFilter to target specific clients.
+6. **Generate TLA+ for verification** - Enable tlaGeneration in dev to verify distributed properties.
 
 Begin by understanding their question and providing a clear, precise answer based on their project context.`;
 }
@@ -8968,6 +9188,10 @@ to reduce verification time while maintaining or improving verification precisio
 and available in the current version of Polly. You can recommend any of these optimizations with
 confidence that they will work when users apply them to their configuration.
 
+**Code Organization**: The analyzer uses transitive import following to discover all reachable code.
+Constraints and type guards can be organized in separate files (e.g., specs/constraints.ts) and will
+be automatically discovered via imports. Files outside src/ are fully supported.
+
 # Communication Style
 
 - Direct and precise - no fluff
@@ -9284,4 +9508,4 @@ Goodbye!`);
 }
 main();
 
-//# debugId=8BD8EAFF3D45D43B64756E2164756E21
+//# debugId=CDFF2E3A99C1DA5C64756E2164756E21