@fairfox/polly 0.11.0 → 0.12.0

package/dist/src/client/wrapper.d.ts

@@ -0,0 +1,54 @@
+import { type Signal } from "@preact/signals-core";
+/**
+ * Polly client options
+ */
+export interface PollyClientOptions {
+    /**
+     * Client state signals that should be synced
+     */
+    state?: Record<string, Signal<unknown>>;
+    /**
+     * Callback when online/offline status changes
+     */
+    onOfflineChange?: (isOnline: boolean) => void;
+    /**
+     * Enable WebSocket for real-time updates (default: true in dev, false in prod)
+     */
+    websocket?: boolean;
+    /**
+     * WebSocket path (default: '/polly/ws')
+     */
+    websocketPath?: string;
+}
+/**
+ * Create a Polly-enhanced Eden client
+ *
+ * In DEV mode:
+ * - Processes server metadata for hot reloading
+ * - Executes client effects from server
+ * - Handles offline queueing
+ * - Connects WebSocket for real-time updates
+ *
+ * In PROD mode:
+ * - Minimal wrapper (client effects are bundled)
+ * - Optional WebSocket for real-time features
+ * - Offline queueing still works
+ *
+ * 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,
+ * });
+ * ```
+ */
+export declare function createPollyClient<T extends Record<string, unknown>>(url: string, options?: PollyClientOptions): any;

package/dist/src/core/clock.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Lamport Clock Implementation
+ *
+ * Provides logical timestamps for distributed systems to establish
+ * causal ordering of events across different contexts (client/server).
+ *
+ * Key properties:
+ * - Each event increments the local clock
+ * - When receiving a message, clock = max(local, received) + 1
+ * - If A happens before B, then timestamp(A) < timestamp(B)
+ *
+ * References:
+ * - Lamport, L. (1978). "Time, Clocks, and the Ordering of Events in a Distributed System"
+ * - https://lamport.azurewebsites.net/pubs/time-clocks.pdf
+ */
+/**
+ * Lamport clock state
+ */
+export interface LamportClock {
+    tick: number;
+    contextId: string;
+}
+/**
+ * Lamport clock with operations
+ */
+export interface LamportClockOps {
+    /**
+     * Get current clock value
+     */
+    now(): LamportClock;
+    /**
+     * Increment the clock (before sending a message or performing an action)
+     */
+    tick(): number;
+    /**
+     * Update clock when receiving a message
+     * Sets clock to max(local, received) + 1
+     */
+    update(receivedClock: LamportClock): void;
+}
+/**
+ * Create a Lamport clock for a specific context
+ *
+ * @param contextId - Unique identifier for this context (e.g., "client", "server", "worker-1")
+ * @returns Clock operations
+ *
+ * @example
+ * ```typescript
+ * const serverClock = createLamportClock("server");
+ *
+ * // Before sending a message
+ * serverClock.tick();
+ * const timestamp = serverClock.now();
+ * send({ data: "...", clock: timestamp });
+ *
+ * // When receiving a message
+ * onReceive((message) => {
+ *   serverClock.update(message.clock);
+ *   // Process message with updated clock
+ * });
+ * ```
+ */
+export declare function createLamportClock(contextId: string): LamportClockOps;

package/dist/src/elysia/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Polly Elysia Middleware
+ *
+ * Adds distributed systems semantics to Elysia apps:
+ * - State management (client + server)
+ * - Authorization
+ * - Offline behavior
+ * - WebSocket broadcast for real-time updates
+ * - TLA+ generation for verification
+ *
+ * Example:
+ * ```typescript
+ * import { Elysia } 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', []),
+ *       },
+ *       server: {
+ *         db: $serverState('db', db),
+ *       },
+ *     },
+ *     effects: {
+ *       'POST /todos': {
+ *         client: ({ result, state }) => {
+ *           state.client.todos.value = [...state.client.todos.value, result];
+ *         },
+ *         broadcast: true,
+ *       },
+ *     },
+ *     authorization: {
+ *       'POST /todos': ({ state }) => state.client.user.value !== null,
+ *     },
+ *   }))
+ *   .post('/todos', handler, { body: t.Object({ text: t.String() }) });
+ * ```
+ */
+export { polly } from "./plugin";
+export type { AuthorizationContext, AuthorizationHandler, ClientEffectConfig, EffectContext, OfflineConfig, PollyConfig, PollyResponseMetadata, PollyStateConfig, RoutePattern, } from "./types";

package/dist/src/elysia/index.js

@@ -0,0 +1,241 @@
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/elysia/plugin.ts
+import { Elysia } from "elysia";
+
+// src/core/clock.ts
+function createLamportClock(contextId) {
+  let tick = 0;
+  return {
+    now() {
+      return { tick, contextId };
+    },
+    tick() {
+      tick += 1;
+      return tick;
+    },
+    update(receivedClock) {
+      tick = Math.max(tick, receivedClock.tick) + 1;
+    }
+  };
+}
+
+// src/utils/function-serialization.ts
+import serialize from "serialize-javascript";
+var isDev = true;
+function serializeFunction(fn) {
+  if (!isDev) {
+    return "";
+  }
+  return serialize(fn, { space: 0 });
+}
+function deserializeFunction(serialized) {
+  if (!isDev) {
+    throw new Error("[Polly] deserializeFunction should not be called in production. " + "Client effects should be imported from your bundle.");
+  }
+  if (!serialized) {
+    throw new Error("[Polly] Cannot deserialize empty function");
+  }
+  return eval(`(${serialized})`);
+}
+
+// src/elysia/plugin.ts
+function matchRoute(pattern, method, path) {
+  const hasMethod = pattern.includes(" ");
+  const patternMethod = hasMethod ? pattern.split(" ")[0] : null;
+  const patternPath = hasMethod ? pattern.split(" ")[1] : pattern;
+  if (patternMethod && patternMethod !== method) {
+    return false;
+  }
+  const patternSegments = patternPath.split("/").filter(Boolean);
+  const pathSegments = path.split("/").filter(Boolean);
+  if (patternSegments.length !== pathSegments.length && !patternPath.includes("*")) {
+    return false;
+  }
+  for (let i = 0;i < patternSegments.length; i++) {
+    const patternSeg = patternSegments[i];
+    const pathSeg = pathSegments[i];
+    if (patternSeg === "*")
+      return true;
+    if (patternSeg.startsWith(":"))
+      continue;
+    if (patternSeg !== pathSeg)
+      return false;
+  }
+  return true;
+}
+function findMatchingConfig(configs, method, path) {
+  if (!configs)
+    return;
+  for (const [pattern, config] of Object.entries(configs)) {
+    if (matchRoute(pattern, method, path)) {
+      return config;
+    }
+  }
+  return;
+}
+
+class BroadcastManager {
+  connections = new Map;
+  register(clientId, ws) {
+    this.connections.set(clientId, ws);
+  }
+  unregister(clientId) {
+    this.connections.delete(clientId);
+  }
+  broadcast(message, filter) {
+    const payload = JSON.stringify(message);
+    for (const [clientId, ws] of this.connections.entries()) {
+      if (filter && !filter(clientId))
+        continue;
+      if (ws.readyState === 1) {
+        ws.send(payload);
+      }
+    }
+  }
+}
+function polly(config = {}) {
+  const isDev2 = true;
+  const clock = createLamportClock("server");
+  const broadcaster = new BroadcastManager;
+  const clientStateByConnection = new Map;
+  const app = new Elysia({ name: "polly" }).decorate("pollyState", {
+    client: config.state?.client || {},
+    server: config.state?.server || {}
+  }).decorate("pollyClock", clock).decorate("pollyBroadcast", broadcaster).ws(config.websocketPath || "/polly/ws", {
+    open(ws) {
+      const clientId = ws.data.headers?.["x-client-id"] || crypto.randomUUID();
+      broadcaster.register(clientId, ws.raw);
+      ws.send(JSON.stringify({
+        type: "state-sync",
+        state: config.state?.client || {},
+        clock: clock.now()
+      }));
+    },
+    close(ws) {
+      const clientId = ws.data.headers?.["x-client-id"];
+      if (clientId) {
+        broadcaster.unregister(clientId);
+        clientStateByConnection.delete(clientId);
+      }
+    },
+    message(ws, message) {
+      const data = JSON.parse(message);
+      if (data.type === "state-update") {
+        const clientId = ws.data.headers?.["x-client-id"];
+        if (clientId) {
+          clientStateByConnection.set(clientId, data.state);
+        }
+      }
+    }
+  }).onBeforeHandle(async ({ request, pollyState, body, params }) => {
+    const method = request.method;
+    const path = new URL(request.url).pathname;
+    const authHandler = findMatchingConfig(config.authorization, method, path);
+    if (authHandler) {
+      const allowed = await authHandler({
+        state: pollyState,
+        body,
+        params,
+        headers: Object.fromEntries(request.headers.entries())
+      });
+      if (!allowed) {
+        return new Response("Unauthorized", { status: 403 });
+      }
+    }
+  }).onAfterHandle(async ({ request, response, _pollyState, pollyClock, pollyBroadcast, _body, _params }) => {
+    const method = request.method;
+    const path = new URL(request.url).pathname;
+    const effectConfig = findMatchingConfig(config.effects, method, path);
+    pollyClock.tick();
+    if (effectConfig?.broadcast) {
+      const broadcastMessage = {
+        type: "effect",
+        path,
+        method,
+        result: response,
+        clock: pollyClock.now()
+      };
+      if (effectConfig.broadcastFilter) {
+        pollyBroadcast.broadcast(broadcastMessage, (clientId) => {
+          const clientState = clientStateByConnection.get(clientId) || {};
+          return effectConfig.broadcastFilter?.(clientState) ?? false;
+        });
+      } else {
+        pollyBroadcast.broadcast(broadcastMessage);
+      }
+    }
+    if (!isDev2) {
+      return response;
+    }
+    const offlineConfig = findMatchingConfig(config.offline, method, path);
+    const metadata = {
+      clientEffect: effectConfig ? {
+        handler: serializeFunction(effectConfig.client),
+        broadcast: effectConfig.broadcast || false
+      } : undefined,
+      offline: offlineConfig,
+      clock: pollyClock.now()
+    };
+    return new Response(JSON.stringify(response), {
+      headers: {
+        "Content-Type": "application/json",
+        "X-Polly-Metadata": JSON.stringify(metadata)
+      }
+    });
+  });
+  return app;
+}
+export {
+  polly
+};
+
+//# debugId=8AEBFE7CEBB3C9C364756E2164756E21

package/dist/src/elysia/index.js.map

@@ -0,0 +1,12 @@
+{
+  "version": 3,
+  "sources": ["../src/elysia/plugin.ts", "../src/core/clock.ts", "../src/utils/function-serialization.ts"],
+  "sourcesContent": [
+    "// @ts-nocheck - Optional peer dependencies (elysia, @elysiajs/eden)\nimport type { Signal } from \"@preact/signals-core\";\nimport { Elysia } from \"elysia\";\nimport { createLamportClock } from \"../core/clock\";\nimport { serializeFunction } from \"../utils/function-serialization\";\nimport type { PollyConfig, PollyResponseMetadata } from \"./types\";\n\n/**\n * Broadcast message sent to connected clients\n */\ninterface BroadcastMessage {\n  type: \"effect\";\n  path: string;\n  method: string;\n  result: unknown;\n  clock: { tick: number; contextId: string };\n}\n\n/**\n * Minimal WebSocket interface for broadcasting\n */\ninterface MinimalWebSocket {\n  readyState: number;\n  send(data: string): void;\n}\n\n/**\n * Route pattern matcher\n * Supports:\n * - Exact match: 'POST /todos'\n * - Param match: 'GET /todos/:id'\n * - Wildcard: '/todos/*'\n */\nfunction matchRoute(pattern: string, method: string, path: string): boolean {\n  // Split pattern into method + path or just path\n  const hasMethod = pattern.includes(\" \");\n  const patternMethod = hasMethod ? pattern.split(\" \")[0] : null;\n  const patternPath = hasMethod ? pattern.split(\" \")[1] : pattern;\n\n  // Check method\n  if (patternMethod && patternMethod !== method) {\n    return false;\n  }\n\n  // Check path\n  const patternSegments = patternPath.split(\"/\").filter(Boolean);\n  const pathSegments = path.split(\"/\").filter(Boolean);\n\n  if (patternSegments.length !== pathSegments.length && !patternPath.includes(\"*\")) {\n    return false;\n  }\n\n  for (let i = 0; i < patternSegments.length; i++) {\n    const patternSeg = patternSegments[i];\n    const pathSeg = pathSegments[i];\n\n    if (patternSeg === \"*\") return true;\n    if (patternSeg.startsWith(\":\")) continue; // Param match\n    if (patternSeg !== pathSeg) return false;\n  }\n\n  return true;\n}\n\n/**\n * Find matching config for a route\n */\nfunction findMatchingConfig<T>(\n  configs: Record<string, T> | undefined,\n  method: string,\n  path: string\n): T | undefined {\n  if (!configs) return undefined;\n\n  for (const [pattern, config] of Object.entries(configs)) {\n    if (matchRoute(pattern, method, path)) {\n      return config;\n    }\n  }\n\n  return undefined;\n}\n\n/**\n * WebSocket broadcast manager\n */\nclass BroadcastManager {\n  private connections = new Map<string, MinimalWebSocket>();\n\n  register(clientId: string, ws: MinimalWebSocket) {\n    this.connections.set(clientId, ws);\n  }\n\n  unregister(clientId: string) {\n    this.connections.delete(clientId);\n  }\n\n  broadcast(message: BroadcastMessage, filter?: (clientId: string) => boolean) {\n    const payload = JSON.stringify(message);\n\n    for (const [clientId, ws] of this.connections.entries()) {\n      if (filter && !filter(clientId)) continue;\n      if (ws.readyState === 1) {\n        // WebSocket.OPEN = 1\n        ws.send(payload);\n      }\n    }\n  }\n}\n\n/**\n * Main Polly Elysia plugin\n */\nexport function polly(config: PollyConfig = {}) {\n  const isDev = process.env.NODE_ENV !== \"production\";\n  const clock = createLamportClock(\"server\");\n  const broadcaster = new BroadcastManager();\n  const clientStateByConnection = new Map<string, Record<string, Signal<unknown>>>();\n\n  const app = new Elysia({ name: \"polly\" })\n    // Add state to context\n    .decorate(\"pollyState\", {\n      client: config.state?.client || {},\n      server: config.state?.server || {},\n    })\n    .decorate(\"pollyClock\", clock)\n    .decorate(\"pollyBroadcast\", broadcaster)\n\n    // WebSocket endpoint for real-time updates\n    .ws(config.websocketPath || \"/polly/ws\", {\n      // @ts-expect-error - Elysia WebSocket types from optional peer dependency\n      open(ws) {\n        const clientId = ws.data.headers?.[\"x-client-id\"] || crypto.randomUUID();\n        broadcaster.register(clientId, ws.raw);\n\n        // Send initial state sync\n        ws.send(\n          JSON.stringify({\n            type: \"state-sync\",\n            state: config.state?.client || {},\n            clock: clock.now(),\n          })\n        );\n      },\n      // @ts-expect-error - Elysia WebSocket types from optional peer dependency\n      close(ws) {\n        const clientId = ws.data.headers?.[\"x-client-id\"];\n        if (clientId) {\n          broadcaster.unregister(clientId);\n          clientStateByConnection.delete(clientId);\n        }\n      },\n      // @ts-expect-error - Elysia WebSocket types from optional peer dependency\n      message(ws, message) {\n        // Handle client state updates\n        const data = JSON.parse(message as string);\n\n        if (data.type === \"state-update\") {\n          const clientId = ws.data.headers?.[\"x-client-id\"];\n          if (clientId) {\n            clientStateByConnection.set(clientId, data.state);\n          }\n        }\n      },\n    })\n\n    // Authorization hook (runs before handler)\n    // @ts-expect-error - Elysia context types from optional peer dependency\n    .onBeforeHandle(async ({ request, pollyState, body, params }) => {\n      const method = request.method;\n      const path = new URL(request.url).pathname;\n\n      const authHandler = findMatchingConfig(config.authorization, method, path);\n\n      if (authHandler) {\n        const allowed = await authHandler({\n          state: pollyState,\n          body,\n          params,\n          headers: Object.fromEntries(request.headers.entries()),\n        });\n\n        if (!allowed) {\n          return new Response(\"Unauthorized\", { status: 403 });\n        }\n      }\n    })\n\n    // Response hook (runs after handler)\n    // @ts-expect-error - Elysia context types from optional peer dependency\n    .onAfterHandle(\n      async ({ request, response, _pollyState, pollyClock, pollyBroadcast, _body, _params }) => {\n        const method = request.method;\n        const path = new URL(request.url).pathname;\n\n        // Find matching effect config\n        const effectConfig = findMatchingConfig(config.effects, method, path);\n\n        // Tick clock\n        pollyClock.tick();\n\n        // If broadcast enabled, send to all connected clients\n        // This works in both dev and prod for real-time updates\n        if (effectConfig?.broadcast) {\n          const broadcastMessage = {\n            type: \"effect\",\n            path,\n            method,\n            result: response,\n            clock: pollyClock.now(),\n          };\n\n          if (effectConfig.broadcastFilter) {\n            pollyBroadcast.broadcast(broadcastMessage, (clientId) => {\n              const clientState = clientStateByConnection.get(clientId) || {};\n              return effectConfig.broadcastFilter?.(clientState) ?? false;\n            });\n          } else {\n            pollyBroadcast.broadcast(broadcastMessage);\n          }\n        }\n\n        // In production, skip expensive metadata operations\n        if (!isDev) {\n          return response;\n        }\n\n        // DEV ONLY: Add Polly metadata to response for debugging/hot-reload\n        const offlineConfig = findMatchingConfig(config.offline, method, path);\n        const metadata: PollyResponseMetadata = {\n          clientEffect: effectConfig\n            ? {\n                handler: serializeFunction(effectConfig.client),\n                broadcast: effectConfig.broadcast || false,\n              }\n            : undefined,\n          offline: offlineConfig,\n          clock: pollyClock.now(),\n        };\n\n        // Attach metadata as header\n        return new Response(JSON.stringify(response), {\n          headers: {\n            \"Content-Type\": \"application/json\",\n            \"X-Polly-Metadata\": JSON.stringify(metadata),\n          },\n        });\n      }\n    );\n\n  return app;\n}\n",
+    "/**\n * Lamport Clock Implementation\n *\n * Provides logical timestamps for distributed systems to establish\n * causal ordering of events across different contexts (client/server).\n *\n * Key properties:\n * - Each event increments the local clock\n * - When receiving a message, clock = max(local, received) + 1\n * - If A happens before B, then timestamp(A) < timestamp(B)\n *\n * References:\n * - Lamport, L. (1978). \"Time, Clocks, and the Ordering of Events in a Distributed System\"\n * - https://lamport.azurewebsites.net/pubs/time-clocks.pdf\n */\n\n/**\n * Lamport clock state\n */\nexport interface LamportClock {\n  tick: number;\n  contextId: string;\n}\n\n/**\n * Lamport clock with operations\n */\nexport interface LamportClockOps {\n  /**\n   * Get current clock value\n   */\n  now(): LamportClock;\n\n  /**\n   * Increment the clock (before sending a message or performing an action)\n   */\n  tick(): number;\n\n  /**\n   * Update clock when receiving a message\n   * Sets clock to max(local, received) + 1\n   */\n  update(receivedClock: LamportClock): void;\n}\n\n/**\n * Create a Lamport clock for a specific context\n *\n * @param contextId - Unique identifier for this context (e.g., \"client\", \"server\", \"worker-1\")\n * @returns Clock operations\n *\n * @example\n * ```typescript\n * const serverClock = createLamportClock(\"server\");\n *\n * // Before sending a message\n * serverClock.tick();\n * const timestamp = serverClock.now();\n * send({ data: \"...\", clock: timestamp });\n *\n * // When receiving a message\n * onReceive((message) => {\n *   serverClock.update(message.clock);\n *   // Process message with updated clock\n * });\n * ```\n */\nexport function createLamportClock(contextId: string): LamportClockOps {\n  let tick = 0;\n\n  return {\n    now(): LamportClock {\n      return { tick, contextId };\n    },\n\n    tick(): number {\n      tick += 1;\n      return tick;\n    },\n\n    update(receivedClock: LamportClock): void {\n      tick = Math.max(tick, receivedClock.tick) + 1;\n    },\n  };\n}\n",
+    "import serialize from \"serialize-javascript\";\n\n/**\n * Check if we're in development mode\n */\nconst isDev = process.env.NODE_ENV !== \"production\";\n\n/**\n * Serialize a function to send to client\n *\n * DEV ONLY: Used for hot reloading and debugging\n * PROD: No-op - client effects are baked into bundle at build time\n */\n// biome-ignore lint/complexity/noBannedTypes: Generic function serialization requires Function type\nexport function serializeFunction(fn: Function): string {\n  if (!isDev) {\n    // In production, return empty string - this won't be used\n    return \"\";\n  }\n\n  return serialize(fn, { space: 0 });\n}\n\n/**\n * Deserialize a function received from server\n *\n * DEV ONLY: Eval serialized function source\n * PROD: Should never be called - effects come from bundle\n */\n// biome-ignore lint/complexity/noBannedTypes: Generic function deserialization requires Function type\nexport function deserializeFunction(serialized: string): Function {\n  if (!isDev) {\n    throw new Error(\n      \"[Polly] deserializeFunction should not be called in production. \" +\n        \"Client effects should be imported from your bundle.\"\n    );\n  }\n\n  if (!serialized) {\n    throw new Error(\"[Polly] Cannot deserialize empty function\");\n  }\n\n  // biome-ignore lint/security/noGlobalEval: Required for dev-mode function deserialization\n  return eval(`(${serialized})`);\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "8AEBFE7CEBB3C9C364756E2164756E21",
+  "names": []
+}

package/dist/src/elysia/plugin.d.ts

@@ -0,0 +1,5 @@
+import type { PollyConfig } from "./types";
+/**
+ * Main Polly Elysia plugin
+ */
+export declare function polly(config?: PollyConfig): any;

package/dist/src/elysia/tla-generator.d.ts

@@ -0,0 +1,16 @@
+import type { PollyConfig } from "./types";
+/**
+ * Generate TLA+ specification from Elysia app + Polly config
+ *
+ * This generates a formal model that can be checked with TLC (TLA+ model checker)
+ * to verify distributed systems properties like:
+ * - Eventually consistent state
+ * - Authorization enforcement
+ * - No lost updates
+ * - Causal ordering of events
+ */
+export declare function generateTLASpec(moduleName: string, config: PollyConfig): string;
+/**
+ * Export TLA+ spec to file
+ */
+export declare function exportTLASpec(moduleName: string, config: PollyConfig, outputPath: string): Promise<void>;

package/dist/src/elysia/types.d.ts

@@ -0,0 +1,137 @@
+import type { Signal } from "@preact/signals-core";
+/**
+ * Route pattern matching configuration
+ * Examples: 'POST /todos', 'GET /todos/:id', '/todos/*'
+ */
+export type RoutePattern = `${string} ${string}` | string;
+/**
+ * State configuration for client and server
+ */
+export interface PollyStateConfig {
+    client?: Record<string, Signal<unknown>>;
+    server?: Record<string, Signal<unknown>>;
+}
+/**
+ * Effect handler context
+ */
+export interface EffectContext<TResult = unknown, TBody = unknown> {
+    result: TResult;
+    body: TBody;
+    state: {
+        client: Record<string, Signal<unknown>>;
+        server: Record<string, Signal<unknown>>;
+    };
+    params: Record<string, string>;
+    clock: {
+        tick: number;
+        contextId: string;
+    };
+}
+/**
+ * Client effect configuration for a route
+ */
+export interface ClientEffectConfig {
+    /**
+     * Client-side effect to run after successful response
+     */
+    client: (ctx: EffectContext) => void | Promise<void>;
+    /**
+     * Whether to broadcast this update to all connected clients
+     */
+    broadcast?: boolean;
+    /**
+     * Broadcast filter - only send to clients matching this condition
+     */
+    broadcastFilter?: (clientState: Record<string, Signal<unknown>>) => boolean;
+}
+/**
+ * Authorization handler context
+ */
+export interface AuthorizationContext {
+    state: {
+        client: Record<string, Signal<unknown>>;
+        server: Record<string, Signal<unknown>>;
+    };
+    body?: unknown;
+    params?: Record<string, string>;
+    headers: Record<string, string>;
+}
+/**
+ * Authorization handler - return true to allow, false to deny
+ */
+export type AuthorizationHandler = (ctx: AuthorizationContext) => boolean | Promise<boolean>;
+/**
+ * Offline behavior configuration for a route
+ */
+export interface OfflineConfig<TBody = unknown, TResult = unknown> {
+    /**
+     * Whether to queue this request when offline
+     */
+    queue: boolean;
+    /**
+     * Optimistic update - what to show the user immediately
+     */
+    optimistic?: (body: TBody) => TResult;
+    /**
+     * Merge strategy when online again
+     * - 'replace': Replace optimistic with server result
+     * - 'merge': Custom merge function
+     */
+    merge?: "replace" | ((optimistic: TResult, server: TResult) => TResult);
+    /**
+     * Conflict resolution if multiple devices edited offline
+     */
+    conflictResolution?: "last-write-wins" | "server-wins" | ((client: TResult, server: TResult) => TResult);
+}
+/**
+ * Complete Polly middleware configuration
+ */
+export interface PollyConfig {
+    /**
+     * State signals (client and server)
+     */
+    state?: PollyStateConfig;
+    /**
+     * Client effects mapped to route patterns
+     */
+    effects?: Record<RoutePattern, ClientEffectConfig>;
+    /**
+     * Authorization rules mapped to route patterns
+     */
+    authorization?: Record<RoutePattern, AuthorizationHandler>;
+    /**
+     * Offline behavior mapped to route patterns
+     */
+    offline?: Record<RoutePattern, OfflineConfig>;
+    /**
+     * WebSocket path for real-time updates (default: '/polly/ws')
+     */
+    websocketPath?: string;
+    /**
+     * Enable TLA+ generation (default: false)
+     */
+    tlaGeneration?: boolean;
+}
+/**
+ * Metadata added to responses for client wrapper
+ */
+export interface PollyResponseMetadata {
+    /**
+     * Client effect to execute
+     */
+    clientEffect?: {
+        handler: string;
+        broadcast: boolean;
+    };
+    /**
+     * Offline configuration for this route
+     */
+    offline?: OfflineConfig;
+    /**
+     * Lamport clock info
+     */
+    clock: {
+        tick: number;
+        contextId: string;
+    };
+}

package/dist/src/utils/function-serialization.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Serialize a function to send to client
+ *
+ * DEV ONLY: Used for hot reloading and debugging
+ * PROD: No-op - client effects are baked into bundle at build time
+ */
+export declare function serializeFunction(fn: Function): string;
+/**
+ * Deserialize a function received from server
+ *
+ * DEV ONLY: Eval serialized function source
+ * PROD: Should never be called - effects come from bundle
+ */
+export declare function deserializeFunction(serialized: string): Function;

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

@@ -0,0 +1,37 @@
+import type { ADRCollection } from "../types/adr";
+export declare class ADRExtractor {
+    private projectRoot;
+    constructor(projectRoot: string);
+    /**
+     * Extract ADRs from docs/adr directory
+     */
+    extract(): ADRCollection;
+    /**
+     * Find ADR directory
+     */
+    private findADRDirectory;
+    /**
+     * Parse ADR from markdown file
+     */
+    private parseADR;
+    /**
+     * Extract status from content
+     */
+    private extractStatus;
+    /**
+     * Extract date from content
+     */
+    private extractDate;
+    /**
+     * Extract section content
+     */
+    private extractSection;
+    /**
+     * Extract links to other ADRs
+     */
+    private extractLinks;
+}
+/**
+ * Extract ADRs from project
+ */
+export declare function extractADRs(projectRoot: string): ADRCollection;