@ismaelsoilet/synapsejs 1.1.0

package/src/runtime/client-entry.ts

@@ -0,0 +1,65 @@
+/**
+ * SynapseJS - Client Entry Generator
+ *
+ * Produces the browser entry for one slice. It hydrates the same React component
+ * the server rendered and wires `onSubmitAction` to the slice's RPC endpoint, so
+ * the call site a slice author writes is valid on both sides: a direct call on the
+ * server, a transparent RPC in the browser.
+ *
+ * The entry imports the splitter's client artifact, never the slice itself — that
+ * is what keeps database code out of the browser bundle.
+ */
+
+export interface ClientEntryOptions {
+  componentName: string;
+  /** Relative path (from the entry file) to the splitter's client artifact. */
+  clientModulePath: string;
+  rpcPath: string;
+  rootId?: string;
+  actionPropNames?: string[];
+}
+
+export const CLIENT_ROOT_ID = 'synapse-root';
+export const CLIENT_PROPS_GLOBAL = '__SYNAPSE_PROPS__';
+
+export function clientEntrySource(options: ClientEntryOptions): string {
+  const rootId = options.rootId ?? CLIENT_ROOT_ID;
+  const propNames = options.actionPropNames ?? ['onSubmitAction', 'action'];
+  const actionWires = propNames
+    .map((name) => `      ${name}: (payload: unknown) => rpcCall(${JSON.stringify(options.rpcPath)}, payload)`)
+    .join(',\n');
+
+  return [
+    `// [SYNAPSE-JS GENERATED CLIENT ENTRY] hydrates the slice in the browser`,
+    `import React from 'react';`,
+    `import { hydrateRoot } from 'react-dom/client';`,
+    `import { rpcCall } from 'synapsejs/client';`,
+    `import { ${options.componentName} } from ${JSON.stringify(options.clientModulePath)};`,
+    ``,
+    `export function hydrate() {`,
+    `  const scope = globalThis as unknown as Record<string, unknown>;`,
+    `  const props = (scope[${JSON.stringify(CLIENT_PROPS_GLOBAL)}] ?? {}) as Record<string, unknown>;`,
+    `  const root = document.getElementById(${JSON.stringify(rootId)});`,
+    `  if (root) {`,
+    `    hydrateRoot(`,
+    `      root,`,
+    `      React.createElement(${options.componentName}, {`,
+    `        ...props,`,
+    `${actionWires}`,
+    `      })`,
+    `    );`,
+    `  }`,
+    `}`,
+    ``,
+    `hydrate();`,
+    ``
+  ].join('\n');
+}
+
+/**
+ * Props travel to the browser as JSON inside a script tag, so `<` must be escaped
+ * or a value containing `</script>` would end the tag early.
+ */
+export function serializeClientProps(props: Record<string, unknown>): string {
+  return JSON.stringify(props).replace(/</g, '\\u003c');
+}

package/src/runtime/discovery-rules.ts

@@ -0,0 +1,63 @@
+/**
+ * SynapseJS - Discovery Rules
+ *
+ * What a slice exports, and which suffix means what, is decided here and nowhere
+ * else. The runtime, the splitter and the machine contract all read these
+ * constants, so the contract an agent reads cannot drift from the behavior that
+ * enforces it — and a suffix is never guessed in two places.
+ */
+
+export const ACTION_SUFFIX = 'Action';
+export const JOB_SUFFIX = 'Job';
+export const WEBHOOK_SUFFIX = 'Webhook';
+export const LOADER_SUFFIX = 'Loader';
+export const SCHEMA_SUFFIX = 'Schema';
+export const META_SUFFIX = 'Meta';
+export const SLICE_META_EXPORT = 'sliceMeta';
+export const SLICE_DDL_EXPORT = 'sliceSchema';
+export const SLICE_ORACLE_EXPORT = 'sliceTests';
+
+/** React UI exports. */
+export const COMPONENT_SUFFIXES = ['Trigger', 'View', 'Form', 'Component'] as const;
+
+/** Everything the server side of a slice is built from. */
+export const SERVER_ROOT_SUFFIXES = [ACTION_SUFFIX, JOB_SUFFIX, WEBHOOK_SUFFIX, META_SUFFIX] as const;
+
+/** Test-only exports, dropped from both runtime bundles. */
+export const TEST_ONLY_EXPORTS = [SLICE_ORACLE_EXPORT] as const;
+
+export function hasSuffix(name: string, suffixes: readonly string[]): boolean {
+  return suffixes.some((suffix) => name.endsWith(suffix));
+}
+
+export function isLoader(name: string): boolean {
+  return name.endsWith(LOADER_SUFFIX);
+}
+
+export function isAction(name: string): boolean {
+  return name.endsWith(ACTION_SUFFIX);
+}
+
+export function isJob(name: string): boolean {
+  return name.endsWith(JOB_SUFFIX);
+}
+
+export function isWebhook(name: string): boolean {
+  return name.endsWith(WEBHOOK_SUFFIX);
+}
+
+export function isComponent(name: string): boolean {
+  return hasSuffix(name, COMPONENT_SUFFIXES);
+}
+
+export function isSchema(name: string): boolean {
+  return name.endsWith(SCHEMA_SUFFIX);
+}
+
+export function isMeta(name: string): boolean {
+  return name === SLICE_META_EXPORT || name.endsWith(META_SUFFIX);
+}
+
+export function isTestOnly(name: string): boolean {
+  return hasSuffix(name, TEST_ONLY_EXPORTS);
+}

package/src/runtime/event-hub.ts

@@ -0,0 +1,97 @@
+/**
+ * SynapseJS - Reactive Event Hub & Server-Sent Events (SSE) Engine
+ *
+ * Lightweight, in-memory pub/sub broker for reactive slice subscriptions.
+ * Zero external dependencies, thread-safe within the Bun process, and designed
+ * for real-time reactivity without stateful WebSocket overhead.
+ */
+
+export type EventListener = (data: unknown) => void;
+export type UnsubscribeFn = () => void;
+
+export class EventHub {
+  private topics: Map<string, Set<EventListener>> = new Map();
+
+  /**
+   * Subscribes a listener to a specific topic.
+   * Returns an unsubscribe function.
+   */
+  subscribe(topic: string, listener: EventListener): UnsubscribeFn {
+    let listeners = this.topics.get(topic);
+    if (!listeners) {
+      listeners = new Set();
+      this.topics.set(topic, listeners);
+    }
+
+    listeners.add(listener);
+
+    return () => {
+      listeners?.delete(listener);
+      if (listeners && listeners.size === 0) {
+        this.topics.delete(topic);
+      }
+    };
+  }
+
+  /**
+   * Publishes an event payload to all listeners registered for the topic.
+   * Returns the number of listeners that received the event.
+   */
+  publish(topic: string, data: unknown): number {
+    const listeners = this.topics.get(topic);
+    if (!listeners || listeners.size === 0) {
+      return 0;
+    }
+
+    let notified = 0;
+    for (const listener of listeners) {
+      try {
+        listener(data);
+        notified++;
+      } catch (err) {
+        console.error(`[EventHub] Erro no listener do tópico "${topic}":`, err);
+      }
+    }
+
+    return notified;
+  }
+
+  /**
+   * Returns the count of active listeners on a given topic.
+   */
+  listenerCount(topic: string): number {
+    return this.topics.get(topic)?.size ?? 0;
+  }
+
+  /**
+   * Returns all active topics currently subscribed to.
+   */
+  activeTopics(): string[] {
+    return Array.from(this.topics.keys());
+  }
+
+  /**
+   * Clears listeners for a given topic, or all topics if none specified.
+   */
+  clear(topic?: string): void {
+    if (topic) {
+      this.topics.delete(topic);
+    } else {
+      this.topics.clear();
+    }
+  }
+}
+
+let globalEventHub: EventHub | null = null;
+
+export function getEventHub(): EventHub {
+  if (!globalEventHub) {
+    globalEventHub = new EventHub();
+  }
+  return globalEventHub;
+}
+
+export function resetEventHub(): void {
+  globalEventHub?.clear();
+  globalEventHub = null;
+}

package/src/runtime/postgres-event-hub.ts

@@ -0,0 +1,148 @@
+/**
+ * SynapseJS - Distributed PostgreSQL EventHub
+ *
+ * Implements a distributed pub/sub broker across multiple server instances
+ * using PostgreSQL LISTEN/NOTIFY with:
+ * 1. Dedicated persistent connection for LISTEN (max: 1) to avoid transaction pooler starvation.
+ * 2. Automatic payload chunking / offloading to `_synapse_event_payloads` for messages > 7.5KB (RFC 8KB pg_notify limit).
+ * 3. Transparent local delivery and non-blocking background broadcast.
+ */
+
+import postgres from 'postgres';
+import { EventHub } from './event-hub';
+
+export interface PostgresEventHubOptions {
+  connectionUri: string;
+  channelName?: string;
+  onNotice?: (notice: postgres.Notice) => void;
+}
+
+export class PostgresEventHub extends EventHub {
+  public readonly instanceId = crypto.randomUUID();
+  private connectionUri: string;
+  private channelName: string;
+  private listenerClient: postgres.Sql | null = null;
+  private publisherClient: postgres.Sql | null = null;
+  private isInitialized = false;
+  private isClosed = false;
+
+  constructor(options: PostgresEventHubOptions) {
+    super();
+    this.connectionUri = options.connectionUri;
+    this.channelName = options.channelName || 'synapse_events';
+  }
+
+  /**
+   * Initializes persistent dedicated connection for LISTEN and publisher pool.
+   */
+  async init(): Promise<void> {
+    if (this.isInitialized || this.isClosed) return;
+
+    // 1. Dedicated persistent listener connection (max: 1, idle_timeout: 0)
+    this.listenerClient = postgres(this.connectionUri, {
+      max: 1,
+      idle_timeout: 0,
+      onnotice: () => {}
+    });
+
+    // 2. Publisher pool
+    this.publisherClient = postgres(this.connectionUri, {
+      max: 5,
+      idle_timeout: 30,
+      onnotice: () => {}
+    });
+
+    // 3. Ensure large payload table exists
+    await this.publisherClient.unsafe(`
+      CREATE TABLE IF NOT EXISTS _synapse_event_payloads (
+        id TEXT PRIMARY KEY,
+        payload TEXT NOT NULL,
+        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+      );
+    `);
+
+    // 4. Start listening on channel
+    await this.listenerClient.listen(this.channelName, async (rawPayload: string) => {
+      try {
+        const envelope = JSON.parse(rawPayload);
+
+        // Deduplicate: ignore events published by this exact process instance
+        if (envelope.o === this.instanceId) {
+          return;
+        }
+
+        let eventData: unknown;
+
+        if (envelope.ref && this.publisherClient) {
+          // Offloaded large payload (>7.5KB)
+          const rows = await this.publisherClient.unsafe('SELECT payload FROM _synapse_event_payloads WHERE id = $1', [
+            envelope.ref
+          ]);
+          if (rows.length > 0) {
+            eventData = JSON.parse(rows[0].payload);
+          }
+        } else {
+          eventData = envelope.d;
+        }
+
+        // Deliver to in-process subscribers
+        super.publish(envelope.t, eventData);
+      } catch (err) {
+        console.error('[PostgresEventHub] Erro ao processar mensagem LISTEN:', err);
+      }
+    });
+
+    this.isInitialized = true;
+  }
+
+  /**
+   * Publishes event locally and broadcasts via PostgreSQL LISTEN/NOTIFY.
+   */
+  override publish(topic: string, data: unknown): number {
+    const localNotified = super.publish(topic, data);
+
+    if (this.publisherClient && !this.isClosed) {
+      const client = this.publisherClient;
+      const serialized = JSON.stringify(data);
+
+      if (serialized.length > 7500) {
+        const refId = crypto.randomUUID();
+        client
+          .unsafe('INSERT INTO _synapse_event_payloads (id, payload) VALUES ($1, $2)', [refId, serialized])
+          .then(() => {
+            // Opportunistic TTL cleanup for records older than 5 minutes
+            client
+              .unsafe("DELETE FROM _synapse_event_payloads WHERE created_at < NOW() - INTERVAL '5 minutes'")
+              .catch(() => {});
+
+            return client.notify(this.channelName, JSON.stringify({ t: topic, ref: refId, o: this.instanceId }));
+          })
+          .catch((err) => {
+            console.error('[PostgresEventHub] Erro ao persistir payload offloaded:', err);
+          });
+      } else {
+        client.notify(this.channelName, JSON.stringify({ t: topic, d: data, o: this.instanceId })).catch((err) => {
+          console.error('[PostgresEventHub] Erro no pg_notify:', err);
+        });
+      }
+    }
+
+    return localNotified;
+  }
+
+  /**
+   * Gracefully ends connections and frees resources.
+   */
+  async close(): Promise<void> {
+    this.isClosed = true;
+    if (this.listenerClient) {
+      await this.listenerClient.end();
+      this.listenerClient = null;
+    }
+    if (this.publisherClient) {
+      await this.publisherClient.end();
+      this.publisherClient = null;
+    }
+    this.clear();
+  }
+}

package/src/runtime/queue-engine.ts

@@ -0,0 +1,255 @@
+/**
+ * SynapseJS - Isolated SQLite Queue Engine for Background Jobs
+ *
+ * Persists and coordinates background jobs inside an isolated SQLite database (.synapse/queue.sqlite),
+ * providing atomic claiming (WAL + RETURNING), exponential backoff retries, and dead-letter handling.
+ */
+
+import { Database } from 'bun:sqlite';
+import * as fs from 'fs';
+import * as path from 'path';
+import {
+  AnonymousSession,
+  createActionContext,
+  createDefaultLogger,
+  type DatabaseClient,
+  type JobDefinition,
+  type JobEnqueueOptions,
+  type SessionContext,
+  type StructuredLogger
+} from '../core';
+
+export interface JobRecord {
+  id: string;
+  name: string;
+  payload: string;
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  priority: number;
+  attempts: number;
+  max_attempts: number;
+  backoff_seconds: number;
+  run_at: number;
+  created_at: number;
+  updated_at: number;
+  last_error: string | null;
+}
+
+export interface QueueEngineOptions {
+  /** Path to SQLite database file or ':memory:' */
+  dbPath?: string;
+  logger?: StructuredLogger;
+}
+
+export class QueueEngine {
+  private db: Database;
+  private registry: Map<string, JobDefinition<unknown>> = new Map();
+  private logger: StructuredLogger;
+
+  constructor(options: QueueEngineOptions = {}) {
+    this.logger = options.logger || createDefaultLogger('QueueEngine');
+    const dbPath = options.dbPath || path.join(process.cwd(), '.synapse/queue.sqlite');
+
+    if (dbPath !== ':memory:') {
+      const dir = path.dirname(dbPath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+    }
+
+    this.db = new Database(dbPath);
+    this.db.run('PRAGMA journal_mode = WAL;');
+    this.db.run('PRAGMA busy_timeout = 5000;');
+    this.initSchema();
+  }
+
+  get database(): Database {
+    return this.db;
+  }
+
+  private initSchema(): void {
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS _synapse_jobs (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        payload TEXT NOT NULL,
+        status TEXT NOT NULL,
+        priority INTEGER NOT NULL DEFAULT 0,
+        attempts INTEGER NOT NULL DEFAULT 0,
+        max_attempts INTEGER NOT NULL DEFAULT 3,
+        backoff_seconds INTEGER NOT NULL DEFAULT 5,
+        run_at INTEGER NOT NULL,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        last_error TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_synapse_jobs_pending 
+      ON _synapse_jobs (status, run_at, priority DESC);
+    `);
+  }
+
+  /**
+   * Registers a job definition to be processed by this queue engine.
+   */
+  registerJob<T>(job: JobDefinition<T>): void {
+    this.registry.set(job.name, job as JobDefinition<unknown>);
+  }
+
+  /**
+   * Enqueues a job for background processing.
+   */
+  async enqueue<TPayload>(
+    jobOrName: { name: string; retryLimit?: number; backoffSeconds?: number } | string,
+    payload: TPayload,
+    options?: JobEnqueueOptions
+  ): Promise<string> {
+    const id = `job_${crypto.randomUUID().replace(/-/g, '')}`;
+    const name = typeof jobOrName === 'string' ? jobOrName : jobOrName.name;
+    const maxAttempts = typeof jobOrName === 'object' && jobOrName.retryLimit ? jobOrName.retryLimit : 3;
+    const backoffSeconds = typeof jobOrName === 'object' && jobOrName.backoffSeconds ? jobOrName.backoffSeconds : 5;
+    const priority = options?.priority ?? 0;
+    const delaySeconds = options?.delaySeconds ?? 0;
+    const now = Date.now();
+    const runAt = now + delaySeconds * 1000;
+    const payloadStr = JSON.stringify(payload);
+
+    const stmt = this.db.prepare(`
+      INSERT INTO _synapse_jobs (
+        id, name, payload, status, priority, attempts, max_attempts, backoff_seconds, run_at, created_at, updated_at
+      ) VALUES (?1, ?2, ?3, 'pending', ?4, 0, ?5, ?6, ?7, ?8, ?8)
+    `);
+
+    stmt.run(id, name, payloadStr, priority, maxAttempts, backoffSeconds, runAt, now);
+    return id;
+  }
+
+  /**
+   * Atomically claims the next pending job eligible for execution.
+   */
+  claimNextJob(): JobRecord | null {
+    const now = Date.now();
+    const stmt = this.db.prepare(`
+      UPDATE _synapse_jobs
+      SET status = 'running', updated_at = ?1
+      WHERE id = (
+        SELECT id FROM _synapse_jobs
+        WHERE status = 'pending' AND run_at <= ?1
+        ORDER BY priority DESC, run_at ASC, created_at ASC
+        LIMIT 1
+      )
+      RETURNING *;
+    `);
+
+    const row = stmt.get(now) as JobRecord | undefined;
+    return row || null;
+  }
+
+  /**
+   * Processes a single claimed job. Returns true if a job was found and processed, false if queue was empty.
+   */
+  async processNextJob(deps: {
+    db: DatabaseClient;
+    session?: SessionContext;
+    services?: Record<string, unknown>;
+    logger?: StructuredLogger;
+  }): Promise<boolean> {
+    const job = this.claimNextJob();
+    if (!job) {
+      return false;
+    }
+
+    const jobDef = this.registry.get(job.name);
+    const attempts = job.attempts + 1;
+    const now = Date.now();
+
+    if (!jobDef) {
+      const errorMsg = `Nenhum manipulador registrado para o job: ${job.name}`;
+      this.logger.error(errorMsg);
+      const updateStmt = this.db.prepare(`
+        UPDATE _synapse_jobs
+        SET status = 'failed', attempts = ?1, updated_at = ?2, last_error = ?3
+        WHERE id = ?4
+      `);
+      updateStmt.run(attempts, now, errorMsg, job.id);
+      return true;
+    }
+
+    let parsedPayload: unknown;
+    try {
+      parsedPayload = JSON.parse(job.payload);
+    } catch (parseErr: unknown) {
+      const errorMsg = `Falha ao desserializar payload JSON do job: ${String(parseErr)}`;
+      const updateStmt = this.db.prepare(`
+        UPDATE _synapse_jobs
+        SET status = 'failed', attempts = ?1, updated_at = ?2, last_error = ?3
+        WHERE id = ?4
+      `);
+      updateStmt.run(attempts, now, errorMsg, job.id);
+      return true;
+    }
+
+    const actionCtx = createActionContext({
+      db: deps.db,
+      session: deps.session || AnonymousSession(),
+      services: deps.services || {},
+      logger: deps.logger || this.logger,
+      enqueue: this.enqueue.bind(this)
+    });
+
+    try {
+      await jobDef.handler(parsedPayload, actionCtx);
+      const completeStmt = this.db.prepare(`
+        UPDATE _synapse_jobs
+        SET status = 'completed', attempts = ?1, updated_at = ?2, last_error = NULL
+        WHERE id = ?3
+      `);
+      completeStmt.run(attempts, now, job.id);
+      return true;
+    } catch (handlerErr: unknown) {
+      const errorMsg = handlerErr instanceof Error ? handlerErr.message : String(handlerErr);
+      this.logger.warn(`Job ${job.name} (${job.id}) falhou na tentativa ${attempts}/${job.max_attempts}: ${errorMsg}`);
+
+      if (attempts < job.max_attempts) {
+        // Exponential backoff: backoff_seconds * 2^(attempts-1)
+        const backoffMs = job.backoff_seconds * 1000 * 2 ** (attempts - 1);
+        const nextRunAt = now + backoffMs;
+        const retryStmt = this.db.prepare(`
+          UPDATE _synapse_jobs
+          SET status = 'pending', attempts = ?1, run_at = ?2, updated_at = ?3, last_error = ?4
+          WHERE id = ?5
+        `);
+        retryStmt.run(attempts, nextRunAt, now, errorMsg, job.id);
+      } else {
+        const failStmt = this.db.prepare(`
+          UPDATE _synapse_jobs
+          SET status = 'failed', attempts = ?1, updated_at = ?2, last_error = ?3
+          WHERE id = ?4
+        `);
+        failStmt.run(attempts, now, errorMsg, job.id);
+      }
+      return true;
+    }
+  }
+
+  /**
+   * Returns a snapshot of job counts by status.
+   */
+  getStats(): { pending: number; running: number; completed: number; failed: number } {
+    const rows = this.db
+      .prepare(`
+      SELECT status, COUNT(*) as count FROM _synapse_jobs GROUP BY status
+    `)
+      .all() as Array<{ status: string; count: number }>;
+
+    const stats = { pending: 0, running: 0, completed: 0, failed: 0 };
+    for (const row of rows) {
+      if (row.status in stats) {
+        stats[row.status as keyof typeof stats] = row.count;
+      }
+    }
+    return stats;
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}