bonescript-compiler 0.2.1 → 0.4.0

package/src/emit_events.ts

@@ -1,307 +1,377 @@
-/**
- * BoneScript Durable Event System Emitter
- *
- * Generates two event delivery modes:
- *   in_process  — default dev mode, in-memory bus (existing behavior)
- *   durable     — Postgres-backed transactional outbox
- *
- * Durable mode guarantees:
- *   at_least_once  — retry until acknowledged
- *   exactly_once   — deduplicated via event_id table
- */
-
-import * as IR from "./ir";
-
-// ─── Outbox SQL Schema ────────────────────────────────────────────────────────
-
-export function emitOutboxSchema(): string {
-  return `-- BoneScript: Transactional Outbox Schema
--- Generated by BoneScript compiler. DO NOT EDIT.
-
-CREATE TABLE IF NOT EXISTS event_outbox (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  event_type VARCHAR NOT NULL,
-  payload JSONB NOT NULL,
-  source VARCHAR NOT NULL,
-  correlation_id UUID,
-  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-  scheduled_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-  delivered_at TIMESTAMPTZ,
-  attempts INT NOT NULL DEFAULT 0,
-  last_error TEXT,
-  status VARCHAR NOT NULL DEFAULT 'pending'
-    CHECK (status IN ('pending', 'delivered', 'failed', 'dead_letter'))
-);
-
-CREATE INDEX IF NOT EXISTS idx_event_outbox_status ON event_outbox (status, scheduled_at)
-  WHERE status = 'pending';
-
-CREATE INDEX IF NOT EXISTS idx_event_outbox_created ON event_outbox (created_at);
-
--- Deduplication table for exactly_once delivery
-CREATE TABLE IF NOT EXISTS event_processed (
-  event_id UUID PRIMARY KEY,
-  event_type VARCHAR NOT NULL,
-  processed_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-
-CREATE INDEX IF NOT EXISTS idx_event_processed_type ON event_processed (event_type, processed_at);
-`;
-}
-
-// ─── Durable Event Bus ────────────────────────────────────────────────────────
-
-export function emitDurableEventBus(system: IR.IRSystem): string {
-  const exactlyOnceEvents = system.events
-    .filter(e => e.delivery === "exactly_once")
-    .map(e => `"${e.name}"`);
-
-  const atLeastOnceEvents = system.events
-    .filter(e => e.delivery === "at_least_once")
-    .map(e => `"${e.name}"`);
-
-  return `// Generated by BoneScript compiler. DO NOT EDIT.
-// Durable event bus with transactional outbox pattern.
-// Set EVENT_MODE=durable in .env to enable.
-
-import { Pool, PoolClient } from "pg";
-import { v4 as uuid } from "uuid";
-import { pool } from "./db";
-import { logger } from "./logger";
-import { counter } from "./metrics";
-
-export type EventDeliveryMode = "in_process" | "durable";
-
-const MODE: EventDeliveryMode =
-  (process.env.EVENT_MODE as EventDeliveryMode) || "in_process";
-
-// Events requiring exactly_once delivery (deduplicated)
-const EXACTLY_ONCE_EVENTS = new Set([${exactlyOnceEvents.join(", ")}]);
-
-// Events requiring at_least_once delivery (retried until ack)
-const AT_LEAST_ONCE_EVENTS = new Set([${atLeastOnceEvents.join(", ")}]);
-
-export interface EventMetadata {
-  source: string;
-  timestamp: Date;
-  correlation_id: string;
-  causation_id: string;
-}
-
-export interface SystemEvent {
-  type: string;
-  payload: Record<string, unknown>;
-  metadata: EventMetadata;
-}
-
-type Handler = (event: SystemEvent) => Promise<void>;
-
-// ─── In-Process Bus ──────────────────────────────────────────────────────────
-
-class InProcessBus {
-  private handlers: Map<string, Handler[]> = new Map();
-
-  subscribe(type: string, handler: Handler): void {
-    const existing = this.handlers.get(type) || [];
-    existing.push(handler);
-    this.handlers.set(type, existing);
-  }
-
-  async publish(type: string, payload: Record<string, unknown>, source: string, correlationId?: string): Promise<void> {
-    const event: SystemEvent = {
-      type,
-      payload,
-      metadata: {
-        source,
-        timestamp: new Date(),
-        correlation_id: correlationId || uuid(),
-        causation_id: uuid(),
-      },
-    };
-    counter("event.published", { type, mode: "in_process" });
-    const handlers = this.handlers.get(type) || [];
-    for (const handler of handlers) {
-      try {
-        await handler(event);
-        counter("event.delivered", { type, mode: "in_process" });
-      } catch (e: any) {
-        counter("event.delivery_failed", { type, mode: "in_process" });
-        logger.error("event_handler_failed", { event: type, metadata: { error: e.message } });
-      }
-    }
-  }
-}
-
-// ─── Durable Bus (Transactional Outbox) ──────────────────────────────────────
-
-class DurableBus {
-  private handlers: Map<string, Handler[]> = new Map();
-
-  subscribe(type: string, handler: Handler): void {
-    const existing = this.handlers.get(type) || [];
-    existing.push(handler);
-    this.handlers.set(type, existing);
-  }
-
-  // Write event to outbox within the current transaction (or a new one)
-  async publish(
-    type: string,
-    payload: Record<string, unknown>,
-    source: string,
-    correlationId?: string,
-    client?: PoolClient
-  ): Promise<void> {
-    const eventId = uuid();
-    const corrId = correlationId || uuid();
-    const sql = \`
-      INSERT INTO event_outbox (id, event_type, payload, source, correlation_id)
-      VALUES ($1, $2, $3, $4, $5)
-    \`;
-    const params = [eventId, type, JSON.stringify({ ...payload, _event_id: eventId }), source, corrId];
-
-    if (client) {
-      // Write within caller's transaction — atomicity guaranteed
-      await client.query(sql, params);
-    } else {
-      await pool.query(sql, params);
-    }
-    counter("event.outboxed", { type });
-  }
-
-  // Called by the background worker
-  async flush(): Promise<void> {
-    const client = await pool.connect();
-    try {
-      await client.query("BEGIN");
-
-      // Fetch pending events (lock rows to prevent concurrent processing)
-      const { rows } = await client.query(\`
-        SELECT id, event_type, payload, source, correlation_id, attempts
-        FROM event_outbox
-        WHERE status = 'pending' AND scheduled_at <= NOW()
-        ORDER BY scheduled_at ASC
-        LIMIT 50
-        FOR UPDATE SKIP LOCKED
-      \`);
-
-      for (const row of rows) {
-        try {
-          // exactly_once: check deduplication table
-          if (EXACTLY_ONCE_EVENTS.has(row.event_type)) {
-            const { rows: dup } = await client.query(
-              "SELECT 1 FROM event_processed WHERE event_id = $1",
-              [row.payload._event_id || row.id]
-            );
-            if (dup.length > 0) {
-              await client.query(
-                "UPDATE event_outbox SET status = 'delivered', delivered_at = NOW() WHERE id = $1",
-                [row.id]
-              );
-              continue;
-            }
-          }
-
-          const event: SystemEvent = {
-            type: row.event_type,
-            payload: row.payload,
-            metadata: {
-              source: row.source,
-              timestamp: new Date(),
-              correlation_id: row.correlation_id,
-              causation_id: uuid(),
-            },
-          };
-
-          const handlers = this.handlers.get(row.event_type) || [];
-          for (const handler of handlers) {
-            await handler(event);
-          }
-
-          // Mark delivered
-          await client.query(
-            "UPDATE event_outbox SET status = 'delivered', delivered_at = NOW(), attempts = attempts + 1 WHERE id = $1",
-            [row.id]
-          );
-
-          // Record for exactly_once deduplication
-          if (EXACTLY_ONCE_EVENTS.has(row.event_type)) {
-            await client.query(
-              "INSERT INTO event_processed (event_id, event_type) VALUES ($1, $2) ON CONFLICT DO NOTHING",
-              [row.payload._event_id || row.id, row.event_type]
-            );
-          }
-
-          counter("event.delivered", { type: row.event_type, mode: "durable" });
-        } catch (e: any) {
-          const maxAttempts = AT_LEAST_ONCE_EVENTS.has(row.event_type) ? 10 : 3;
-          const newAttempts = row.attempts + 1;
-          const status = newAttempts >= maxAttempts ? "dead_letter" : "pending";
-          const backoffMs = Math.min(1000 * Math.pow(2, newAttempts), 300000);
-          await client.query(
-            \`UPDATE event_outbox
-             SET attempts = $1, last_error = $2, status = $3,
-                 scheduled_at = NOW() + ($4 || ' milliseconds')::interval
-             WHERE id = $5\`,
-            [newAttempts, e.message, status, backoffMs, row.id]
-          );
-          counter("event.delivery_failed", { type: row.event_type, mode: "durable" });
-          logger.error("event_delivery_failed", { event: row.event_type, metadata: { error: e.message, attempts: newAttempts } });
-        }
-      }
-
-      await client.query("COMMIT");
-    } catch (e) {
-      await client.query("ROLLBACK");
-      throw e;
-    } finally {
-      client.release();
-    }
-  }
-
-  // Start background worker
-  startWorker(intervalMs: number = 1000): NodeJS.Timeout {
-    logger.info("event_worker_started", { event: "startup", metadata: { interval_ms: intervalMs } });
-    return setInterval(async () => {
-      try {
-        await this.flush();
-      } catch (e: any) {
-        logger.error("event_worker_error", { event: "flush_failed", metadata: { error: e.message } });
-      }
-    }, intervalMs);
-  }
-}
-
-// ─── Unified Interface ────────────────────────────────────────────────────────
-
-const inProcess = new InProcessBus();
-const durable = new DurableBus();
-
-export const eventBus = {
-  subscribe(type: string, handler: Handler): void {
-    inProcess.subscribe(type, handler);
-    durable.subscribe(type, handler);
-  },
-
-  async publish(
-    type: string,
-    payload: Record<string, unknown>,
-    source: string,
-    correlationId?: string,
-    client?: PoolClient
-  ): Promise<void> {
-    if (MODE === "durable") {
-      await durable.publish(type, payload, source, correlationId, client);
-    } else {
-      await inProcess.publish(type, payload, source, correlationId);
-    }
-  },
-
-  startWorker(intervalMs?: number): NodeJS.Timeout | null {
-    if (MODE === "durable") {
-      return durable.startWorker(intervalMs);
-    }
-    return null;
-  },
-};
-`;
-}
+/**
+ * BoneScript Durable Event System Emitter
+ *
+ * Generates two event delivery modes:
+ *   in_process  — default dev mode, in-memory bus (existing behavior)
+ *   durable     — Postgres-backed transactional outbox
+ *
+ * Durable mode guarantees:
+ *   at_least_once  — retry until acknowledged
+ *   exactly_once   — deduplicated via event_id table
+ */
+
+import * as IR from "./ir";
+
+// ─── Outbox SQL Schema ────────────────────────────────────────────────────────
+
+export function emitOutboxSchema(): string {
+  return `-- BoneScript: Transactional Outbox Schema
+-- Generated by BoneScript compiler. DO NOT EDIT.
+
+CREATE TABLE IF NOT EXISTS event_outbox (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  event_type VARCHAR NOT NULL,
+  payload JSONB NOT NULL,
+  source VARCHAR NOT NULL,
+  correlation_id UUID,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  scheduled_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  delivered_at TIMESTAMPTZ,
+  attempts INT NOT NULL DEFAULT 0,
+  last_error TEXT,
+  status VARCHAR NOT NULL DEFAULT 'pending'
+    CHECK (status IN ('pending', 'delivered', 'failed', 'dead_letter'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_event_outbox_status ON event_outbox (status, scheduled_at)
+  WHERE status = 'pending';
+
+CREATE INDEX IF NOT EXISTS idx_event_outbox_created ON event_outbox (created_at);
+
+-- Deduplication table for exactly_once delivery
+CREATE TABLE IF NOT EXISTS event_processed (
+  event_id UUID PRIMARY KEY,
+  event_type VARCHAR NOT NULL,
+  processed_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_event_processed_type ON event_processed (event_type, processed_at);
+`;
+}
+
+// ─── Durable Event Bus ────────────────────────────────────────────────────────
+
+export function emitDurableEventBus(system: IR.IRSystem): string {
+  const exactlyOnceEvents = system.events
+    .filter(e => e.delivery === "exactly_once")
+    .map(e => `"${e.name}"`);
+
+  const atLeastOnceEvents = system.events
+    .filter(e => e.delivery === "at_least_once")
+    .map(e => `"${e.name}"`);
+
+  return `// Generated by BoneScript compiler. DO NOT EDIT.
+// Durable event bus with transactional outbox pattern.
+// Set EVENT_MODE=durable in .env to enable.
+
+import { Pool, PoolClient } from "pg";
+import { v4 as uuid } from "uuid";
+import { pool } from "./db";
+import { logger } from "./logger";
+import { counter } from "./metrics";
+
+export type EventDeliveryMode = "in_process" | "durable";
+
+const MODE: EventDeliveryMode =
+  (process.env.EVENT_MODE as EventDeliveryMode) || "in_process";
+
+// Events requiring exactly_once delivery (deduplicated)
+const EXACTLY_ONCE_EVENTS = new Set([${exactlyOnceEvents.join(", ")}]);
+
+// Events requiring at_least_once delivery (retried until ack)
+const AT_LEAST_ONCE_EVENTS = new Set([${atLeastOnceEvents.join(", ")}]);
+
+export interface EventMetadata {
+  source: string;
+  timestamp: Date;
+  correlation_id: string;
+  causation_id: string;
+}
+
+export interface SystemEvent {
+  type: string;
+  payload: Record<string, unknown>;
+  metadata: EventMetadata;
+}
+
+type Handler = (event: SystemEvent) => Promise<void>;
+
+// ─── In-Process Bus ──────────────────────────────────────────────────────────
+
+class InProcessBus {
+  private handlers: Map<string, Handler[]> = new Map();
+
+  subscribe(type: string, handler: Handler): void {
+    const existing = this.handlers.get(type) || [];
+    existing.push(handler);
+    this.handlers.set(type, existing);
+  }
+
+  async publish(type: string, payload: Record<string, unknown>, source: string, correlationId?: string): Promise<void> {
+    const event: SystemEvent = {
+      type,
+      payload,
+      metadata: {
+        source,
+        timestamp: new Date(),
+        correlation_id: correlationId || uuid(),
+        causation_id: uuid(),
+      },
+    };
+    counter("event.published", { type, mode: "in_process" });
+    const handlers = this.handlers.get(type) || [];
+    for (const handler of handlers) {
+      try {
+        await handler(event);
+        counter("event.delivered", { type, mode: "in_process" });
+      } catch (e: any) {
+        counter("event.delivery_failed", { type, mode: "in_process" });
+        logger.error("event_handler_failed", { event: type, metadata: { error: e.message } });
+      }
+    }
+  }
+}
+
+// ─── Durable Bus (Transactional Outbox) ──────────────────────────────────────
+
+class DurableBus {
+  private handlers: Map<string, Handler[]> = new Map();
+
+  subscribe(type: string, handler: Handler): void {
+    const existing = this.handlers.get(type) || [];
+    existing.push(handler);
+    this.handlers.set(type, existing);
+  }
+
+  // Write event to outbox within the current transaction (or a new one)
+  async publish(
+    type: string,
+    payload: Record<string, unknown>,
+    source: string,
+    correlationId?: string,
+    client?: PoolClient
+  ): Promise<void> {
+    const eventId = uuid();
+    const corrId = correlationId || uuid();
+    const sql = \`
+      INSERT INTO event_outbox (id, event_type, payload, source, correlation_id)
+      VALUES ($1, $2, $3, $4, $5)
+    \`;
+    const params = [eventId, type, JSON.stringify({ ...payload, _event_id: eventId }), source, corrId];
+
+    if (client) {
+      // Write within caller's transaction — atomicity guaranteed
+      await client.query(sql, params);
+    } else {
+      await pool.query(sql, params);
+    }
+    counter("event.outboxed", { type });
+  }
+
+  // Called by the background worker
+  async flush(): Promise<void> {
+    const client = await pool.connect();
+    try {
+      await client.query("BEGIN");
+
+      // Fetch pending events (lock rows to prevent concurrent processing)
+      const { rows } = await client.query(\`
+        SELECT id, event_type, payload, source, correlation_id, attempts
+        FROM event_outbox
+        WHERE status = 'pending' AND scheduled_at <= NOW()
+        ORDER BY scheduled_at ASC
+        LIMIT 50
+        FOR UPDATE SKIP LOCKED
+      \`);
+
+      for (const row of rows) {
+        try {
+          // exactly_once: check deduplication table
+          if (EXACTLY_ONCE_EVENTS.has(row.event_type)) {
+            const { rows: dup } = await client.query(
+              "SELECT 1 FROM event_processed WHERE event_id = $1",
+              [row.payload._event_id || row.id]
+            );
+            if (dup.length > 0) {
+              await client.query(
+                "UPDATE event_outbox SET status = 'delivered', delivered_at = NOW() WHERE id = $1",
+                [row.id]
+              );
+              continue;
+            }
+          }
+
+          const event: SystemEvent = {
+            type: row.event_type,
+            payload: row.payload,
+            metadata: {
+              source: row.source,
+              timestamp: new Date(),
+              correlation_id: row.correlation_id,
+              causation_id: uuid(),
+            },
+          };
+
+          const handlers = this.handlers.get(row.event_type) || [];
+          for (const handler of handlers) {
+            await handler(event);
+          }
+
+          // Mark delivered
+          await client.query(
+            "UPDATE event_outbox SET status = 'delivered', delivered_at = NOW(), attempts = attempts + 1 WHERE id = $1",
+            [row.id]
+          );
+
+          // Record for exactly_once deduplication
+          if (EXACTLY_ONCE_EVENTS.has(row.event_type)) {
+            await client.query(
+              "INSERT INTO event_processed (event_id, event_type) VALUES ($1, $2) ON CONFLICT DO NOTHING",
+              [row.payload._event_id || row.id, row.event_type]
+            );
+          }
+
+          counter("event.delivered", { type: row.event_type, mode: "durable" });
+        } catch (e: any) {
+          const maxAttempts = AT_LEAST_ONCE_EVENTS.has(row.event_type) ? 10 : 3;
+          const newAttempts = row.attempts + 1;
+          const status = newAttempts >= maxAttempts ? "dead_letter" : "pending";
+          const backoffMs = Math.min(1000 * Math.pow(2, newAttempts), 300000);
+          await client.query(
+            \`UPDATE event_outbox
+             SET attempts = $1, last_error = $2, status = $3,
+                 scheduled_at = NOW() + ($4 || ' milliseconds')::interval
+             WHERE id = $5\`,
+            [newAttempts, e.message, status, backoffMs, row.id]
+          );
+          counter("event.delivery_failed", { type: row.event_type, mode: "durable" });
+          logger.error("event_delivery_failed", { event: row.event_type, metadata: { error: e.message, attempts: newAttempts } });
+        }
+      }
+
+      await client.query("COMMIT");
+    } catch (e) {
+      await client.query("ROLLBACK");
+      throw e;
+    } finally {
+      client.release();
+    }
+  }
+
+  // Start background worker
+  startWorker(intervalMs: number = 1000): NodeJS.Timeout {
+    logger.info("event_worker_started", { event: "startup", metadata: { interval_ms: intervalMs } });
+    return setInterval(async () => {
+      try {
+        await this.flush();
+      } catch (e: any) {
+        logger.error("event_worker_error", { event: "flush_failed", metadata: { error: e.message } });
+      }
+    }, intervalMs);
+  }
+}
+
+// ─── Unified Interface ────────────────────────────────────────────────────────
+
+const inProcess = new InProcessBus();
+const durable = new DurableBus();
+
+export const eventBus = {
+  subscribe(type: string, handler: Handler): void {
+    inProcess.subscribe(type, handler);
+    durable.subscribe(type, handler);
+  },
+
+  async publish(
+    type: string,
+    payload: Record<string, unknown>,
+    source: string,
+    correlationId?: string,
+    client?: PoolClient
+  ): Promise<void> {
+    if (MODE === "durable") {
+      await durable.publish(type, payload, source, correlationId, client);
+    } else {
+      await inProcess.publish(type, payload, source, correlationId);
+    }
+  },
+
+  startWorker(intervalMs?: number): NodeJS.Timeout | null {
+    if (MODE === "durable") {
+      return durable.startWorker(intervalMs);
+    }
+    return null;
+  },
+};
+`;
+}
+
+// ─── Typed Event Publishers ───────────────────────────────────────────────────
+// Generates per-event emitXxx() typed publisher functions as specified in
+// spec/09_CODEGEN.md §5.4. These wrap eventBus.publish with a typed payload
+// interface so callers get compile-time safety instead of raw Record<string,unknown>.
+
+const TS_TYPE_MAP: Record<string, string> = {
+  string: "string", uint: "number", int: "number", float: "number",
+  bool: "boolean", timestamp: "Date", uuid: "string", bytes: "Buffer", json: "unknown",
+};
+
+function toTsType(irType: string): string {
+  if (TS_TYPE_MAP[irType]) return TS_TYPE_MAP[irType];
+  const listMatch = irType.match(/^list<(.+)>$/);
+  if (listMatch) return `${toTsType(listMatch[1])}[]`;
+  const setMatch = irType.match(/^set<(.+)>$/);
+  if (setMatch) return `${toTsType(setMatch[1])}[]`;
+  const optMatch = irType.match(/^optional<(.+)>$/);
+  if (optMatch) return `${toTsType(optMatch[1])} | null`;
+  return irType;
+}
+
+export function emitTypedEventPublishers(system: IR.IRSystem): string {
+  if (system.events.length === 0) return "";
+
+  const lines: string[] = [];
+  lines.push(`// Generated by BoneScript compiler. DO NOT EDIT.`);
+  lines.push(`// Typed event publisher functions — one per declared event.`);
+  lines.push(`// Import these instead of calling eventBus.publish() directly.`);
+  lines.push(``);
+  lines.push(`import { eventBus } from "./events";`);
+  lines.push(`import type { PoolClient } from "pg";`);
+  lines.push(``);
+
+  for (const ev of system.events) {
+    const ifaceName = `${ev.name}Payload`;
+
+    // Payload interface
+    lines.push(`export interface ${ifaceName} {`);
+    for (const field of ev.payload) {
+      const nullable = field.nullable ? " | null" : "";
+      lines.push(`  ${field.name}: ${toTsType(field.type)}${nullable};`);
+    }
+    lines.push(`}`);
+    lines.push(``);
+
+    // Publisher function
+    const sourceId = ev.source && ev.source !== "unknown" ? ev.source : system.name;
+    lines.push(`/**`);
+    lines.push(` * Publish a ${ev.name} event.`);
+    lines.push(` * Delivery: ${ev.delivery}${ev.ttl_ms ? ` | TTL: ${ev.ttl_ms}ms` : ""}`);
+    lines.push(` */`);
+    lines.push(`export async function emit${ev.name}(`);
+    lines.push(`  payload: ${ifaceName},`);
+    lines.push(`  correlationId?: string,`);
+    lines.push(`  client?: PoolClient,`);
+    lines.push(`): Promise<void> {`);
+    lines.push(`  await eventBus.publish(`);
+    lines.push(`    "${ev.name}",`);
+    lines.push(`    payload as unknown as Record<string, unknown>,`);
+    lines.push(`    "${sourceId}",`);
+    lines.push(`    correlationId,`);
+    lines.push(`    client,`);
+    lines.push(`  );`);
+    lines.push(`}`);
+    lines.push(``);
+  }
+
+  return lines.join("\n");
+}