@ismaelsoilet/synapsejs 1.1.0

package/src/compiler/standalone-builder.ts

@@ -0,0 +1,117 @@
+/**
+ * SynapseJS - Standalone Production Build Generator
+ *
+ * Produces an ultra-optimized, self-contained deployment package under `.synapse/standalone/`
+ * containing pre-compiled client bundles, server-side slice execution runtime,
+ * static assets, and minimal production package.json for zero-dependency container deployment.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { Err, Ok, type Result } from '../core/machine-types';
+import { type BuildReportEntry, buildAllClientBundles } from './client-bundler';
+import { resolveSlicesDir, type SlicesDirError } from './slice-discovery';
+
+export interface StandaloneBuildResult {
+  status: 'PASS' | 'FAIL';
+  outDir: string;
+  clientBundlesCount: number;
+  totalBytes: number;
+  serverEntry: string;
+  entries: BuildReportEntry[];
+}
+
+export async function buildStandalone(
+  appRoot: string
+): Promise<Result<StandaloneBuildResult, SlicesDirError | { code: string; message: string }>> {
+  const resolution = resolveSlicesDir(appRoot);
+  if (!resolution.ok) {
+    return Err(resolution.error);
+  }
+
+  // 1. Pre-build all client bundles and manifest
+  const clientBuild = await buildAllClientBundles(appRoot);
+  if (!clientBuild.ok) {
+    return Err(clientBuild.error);
+  }
+
+  const standaloneDir = path.join(appRoot, '.synapse', 'standalone');
+  fs.rmSync(standaloneDir, { recursive: true, force: true });
+  fs.mkdirSync(standaloneDir, { recursive: true });
+
+  // 2. Copy pre-built client bundles
+  const clientSrc = path.join(appRoot, '.synapse', 'client');
+  const clientDest = path.join(standaloneDir, '.synapse', 'client');
+  if (fs.existsSync(clientSrc)) {
+    fs.cpSync(clientSrc, clientDest, { recursive: true });
+  }
+
+  // 3. Copy public/ if present
+  const publicSrc = path.join(appRoot, 'public');
+  const publicDest = path.join(standaloneDir, 'public');
+  if (fs.existsSync(publicSrc)) {
+    fs.cpSync(publicSrc, publicDest, { recursive: true });
+  }
+
+  // 4. Copy slices for server-side SSR and actions
+  const slicesSrc = resolution.value.slicesDir;
+  const relSlices = path.relative(appRoot, slicesSrc);
+  const slicesDest = path.join(standaloneDir, relSlices);
+  fs.mkdirSync(path.dirname(slicesDest), { recursive: true });
+  fs.cpSync(slicesSrc, slicesDest, { recursive: true });
+
+  // 5. Copy package.json & tsconfig.json if present
+  const pkgSrc = path.join(appRoot, 'package.json');
+  if (fs.existsSync(pkgSrc)) {
+    fs.copyFileSync(pkgSrc, path.join(standaloneDir, 'package.json'));
+  }
+
+  const tsconfigSrc = path.join(appRoot, 'tsconfig.json');
+  if (fs.existsSync(tsconfigSrc)) {
+    fs.copyFileSync(tsconfigSrc, path.join(standaloneDir, 'tsconfig.json'));
+  }
+
+  // 6. Write standalone server bootstrap
+  const serverEntryCode = `/**
+ * SynapseJS Standalone Production Server
+ */
+import { SynapseServer } from 'synapsejs';
+
+const port = process.env.PORT ? parseInt(process.env.PORT, 10) : 3000;
+const server = new SynapseServer(import.meta.dir, port);
+
+console.log(\`⚡ [SynapseJS Standalone] Iniciando servidor de produção na porta \${port}...\`);
+await server.discoverSlices();
+await server.start();
+`;
+
+  const serverEntryPath = path.join(standaloneDir, 'server.ts');
+  fs.writeFileSync(serverEntryPath, serverEntryCode, 'utf-8');
+
+  // Compute stats
+  let totalBytes = 0;
+  function computeDirSize(dir: string) {
+    if (!fs.existsSync(dir)) return;
+    const items = fs.readdirSync(dir, { withFileTypes: true });
+    for (const item of items) {
+      const full = path.join(dir, item.name);
+      if (item.isDirectory()) {
+        computeDirSize(full);
+      } else if (item.isFile()) {
+        totalBytes += fs.statSync(full).size;
+      }
+    }
+  }
+  computeDirSize(standaloneDir);
+
+  const passedEntries = clientBuild.value.entries.filter((e) => e.status === 'PASS');
+
+  return Ok({
+    status: 'PASS',
+    outDir: standaloneDir,
+    clientBundlesCount: passedEntries.length,
+    totalBytes,
+    serverEntry: serverEntryPath,
+    entries: clientBuild.value.entries
+  });
+}

package/src/core/action-context.ts

@@ -0,0 +1,152 @@
+/**
+ * SynapseJS - Unified Action Context & Service Extensibility
+ *
+ * Provides a rich, extensible execution context for slices without breaking Locality of Behavior.
+ * Combines database access, authenticated session, multi-tenancy, service locator,
+ * structured logging, and background job dispatch.
+ */
+
+import { getEventHub } from '../runtime/event-hub';
+import type { DatabaseClient, QueryOptions, WhereCondition } from './database-client';
+import type { SessionContext } from './session-context';
+import { getStorage, type StorageClient } from './storage';
+
+export interface StructuredLogger {
+  info(message: string, context?: Record<string, unknown>): void;
+  warn(message: string, context?: Record<string, unknown>): void;
+  error(message: string, error?: unknown, context?: Record<string, unknown>): void;
+  debug(message: string, context?: Record<string, unknown>): void;
+}
+
+export interface JobEnqueueOptions {
+  delaySeconds?: number;
+  priority?: number;
+}
+
+export type EnqueueFn = <TPayload>(
+  jobOrName: { name: string } | string,
+  payload: TPayload,
+  options?: JobEnqueueOptions
+) => Promise<string>;
+
+export type BroadcastFn = (topic: string, data: unknown) => number;
+
+export interface ActionContext<TServices = Record<string, unknown>> extends DatabaseClient {
+  /** Underlying Database Client */
+  readonly db: DatabaseClient;
+
+  /** Authenticated or anonymous session context */
+  readonly session: SessionContext;
+
+  /** Multi-tenant identifier (if resolved from subdomain/header/token) */
+  readonly tenantId?: string;
+
+  /** Registered enterprise/SaaS services (e.g. mailer, stripe, s3) */
+  readonly services: TServices;
+
+  /** Structured logger */
+  readonly logger: StructuredLogger;
+
+  /** Enqueues a background job for asynchronous processing */
+  readonly enqueue: EnqueueFn;
+
+  /** Unified object storage client */
+  readonly storage: StorageClient;
+
+  /** Broadcasts a real-time event to SSE subscribers */
+  readonly broadcast: BroadcastFn;
+
+  /** Lazy adapter for Kysely (if configured or requested) */
+  readonly kysely?: unknown;
+}
+
+export function createDefaultLogger(sliceName?: string): StructuredLogger {
+  const prefix = sliceName ? `[${sliceName}]` : '[SynapseJS]';
+  return {
+    info: (msg, ctx) => console.log(`${prefix} INFO: ${msg}`, ctx ? JSON.stringify(ctx) : ''),
+    warn: (msg, ctx) => console.warn(`${prefix} WARN: ${msg}`, ctx ? JSON.stringify(ctx) : ''),
+    error: (msg, err, ctx) => console.error(`${prefix} ERROR: ${msg}`, err, ctx ? JSON.stringify(ctx) : ''),
+    debug: (msg, ctx) => {
+      if (process.env.DEBUG) {
+        console.debug(`${prefix} DEBUG: ${msg}`, ctx ? JSON.stringify(ctx) : '');
+      }
+    }
+  };
+}
+
+export interface ActionContextOptions<TServices = Record<string, unknown>> {
+  db: DatabaseClient;
+  session: SessionContext;
+  tenantId?: string;
+  services?: TServices;
+  logger?: StructuredLogger;
+  enqueue?: EnqueueFn;
+  storage?: StorageClient;
+  broadcast?: BroadcastFn;
+  kysely?: unknown;
+}
+
+/**
+ * Creates an ActionContext that is also a fully functional DatabaseClient,
+ * providing 100% backward and forward compatibility.
+ */
+export function createActionContext<TServices = Record<string, unknown>>(
+  options: ActionContextOptions<TServices>
+): ActionContext<TServices> {
+  const {
+    db,
+    session,
+    tenantId = session.tenantId,
+    services = {} as TServices,
+    logger = createDefaultLogger(),
+    enqueue = async () => 'job_noop',
+    storage = getStorage(),
+    broadcast = (topic: string, data: unknown) => getEventHub().publish(topic, data),
+    kysely
+  } = options;
+
+  const context: ActionContext<TServices> = {
+    // ActionContext properties
+    db,
+    session,
+    tenantId,
+    services,
+    logger,
+    enqueue,
+    storage,
+    broadcast,
+    kysely,
+
+    // DatabaseClient proxy methods
+    query: <T = unknown>(sql: string, params?: unknown[]) => db.query<T>(sql, params),
+    queryOne: <T = unknown>(sql: string, params?: unknown[]) => db.queryOne<T>(sql, params),
+    sql: <T = unknown>(strings: TemplateStringsArray, ...values: unknown[]) => db.sql<T>(strings, ...values),
+    sqlOne: <T = unknown>(strings: TemplateStringsArray, ...values: unknown[]) => db.sqlOne<T>(strings, ...values),
+    findMany: <T = unknown>(table: string, options?: QueryOptions) => db.findMany<T>(table, options),
+    findOne: <T = unknown>(table: string, options?: QueryOptions) => db.findOne<T>(table, options),
+    insert: <T = unknown>(table: string, data: Record<string, unknown>) => db.insert<T>(table, data),
+    update: <T = unknown>(table: string, data: Record<string, unknown>, where: WhereCondition) =>
+      db.update<T>(table, data, where),
+    delete: (table: string, where: WhereCondition) => db.delete(table, where),
+    transaction: async <T>(operation: (tx: DatabaseClient) => Promise<T>): Promise<T> => {
+      return db.transaction(async (txDb) => {
+        // Create transactional ActionContext preserving services and context
+        const txContext = createActionContext({
+          db: txDb,
+          session,
+          tenantId,
+          services,
+          logger,
+          enqueue,
+          storage,
+          broadcast,
+          kysely: txDb
+        });
+        return operation(txContext);
+      });
+    },
+    close: () => db.close?.()
+  };
+
+  return context;
+}

package/src/core/config.ts

@@ -0,0 +1,77 @@
+/**
+ * SynapseJS - Enterprise & SaaS Configuration Contract
+ *
+ * Provides a declarative configuration entry point via `synapse.config.ts`.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface SynapsePlugin {
+  name: string;
+  // biome-ignore lint/suspicious/noExplicitAny: generic boundary for framework server
+  onBootstrap?: (server: any) => Promise<void> | void;
+  onRequest?: (req: Request) => Promise<Response | null | void> | Response | null | void;
+  onResponse?: (res: Response, req: Request) => Promise<Response> | Response;
+  // biome-ignore lint/suspicious/noExplicitAny: generic boundary for database client
+  onMigrate?: (db: any) => Promise<void> | void;
+}
+
+export interface SynapseConfig<TServices = Record<string, unknown>> {
+  /**
+   * Enterprise & SaaS service registry (e.g. mailer, stripe, storage, ai).
+   * Can be an object or an async factory returning the services.
+   */
+  services?: TServices | (() => Promise<TServices>) | (() => TServices);
+
+  /**
+   * Multi-tenancy configuration.
+   */
+  multitenancy?: {
+    strategy?: 'subdomain' | 'header' | 'cookie';
+    headerName?: string;
+  };
+
+  /**
+   * Background queue settings.
+   */
+  queue?: {
+    driver?: 'sqlite' | 'memory' | 'redis';
+    dbPath?: string;
+    concurrency?: number;
+  };
+
+  /**
+   * Infrastructure lifecycle plugins (onBootstrap, onRequest, onResponse, onMigrate).
+   */
+  plugins?: SynapsePlugin[];
+}
+
+export function defineConfig<TServices = Record<string, unknown>>(
+  config: SynapseConfig<TServices>
+): SynapseConfig<TServices> {
+  return config;
+}
+
+const CONFIG_FILENAMES = ['synapse.config.ts', 'synapse.config.js', 'synapse.config.mjs'];
+
+/**
+ * Discovers and loads `synapse.config.(ts|js|mjs)` from the application root.
+ */
+export async function loadSynapseConfig(appDir: string): Promise<SynapseConfig> {
+  for (const filename of CONFIG_FILENAMES) {
+    const candidate = path.join(appDir, filename);
+    if (fs.existsSync(candidate)) {
+      try {
+        const mod = await import(candidate);
+        const config = mod.default || mod;
+        return typeof config === 'function' ? await config() : config;
+      } catch (err: unknown) {
+        const errMessage = err instanceof Error ? err.message : String(err);
+        console.warn(`[SynapseConfig] Aviso ao carregar ${filename}: ${errMessage}`);
+      }
+    }
+  }
+
+  return {};
+}

package/src/core/database-client.ts

@@ -0,0 +1,246 @@
+/**
+ * SynapseJS - Database Context & Query Builder Abstraction
+ *
+ * Provides a clean, type-safe persistence contract without reflection-based ORM bloat.
+ * Compatible with raw parameterized SQL, Kysely, and Drizzle query builders.
+ */
+
+export interface QueryResult<T = unknown> {
+  rows: T[];
+  rowCount: number;
+}
+
+export function compileTaggedSql(
+  strings: TemplateStringsArray,
+  ...values: unknown[]
+): { text: string; params: unknown[] } {
+  let text = '';
+  const params: unknown[] = [];
+
+  for (let i = 0; i < strings.length; i++) {
+    text += strings[i];
+    if (i < values.length) {
+      params.push(values[i]);
+      text += `$${params.length}`;
+    }
+  }
+
+  return { text, params };
+}
+
+import {
+  compileDelete,
+  compileInsert,
+  compileSelect,
+  compileUpdate,
+  type JoinClause,
+  nestJoinedRow,
+  type QueryOptions,
+  type WhereCondition,
+  type WhereOperator
+} from './query-builder';
+
+export {
+  compileDelete,
+  compileInsert,
+  compileSelect,
+  compileUpdate,
+  type JoinClause,
+  nestJoinedRow,
+  type QueryOptions,
+  type WhereCondition,
+  type WhereOperator
+};
+
+export interface DatabaseClient {
+  /**
+   * Execute parameterized SQL query with explicit generic return type.
+   */
+  query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
+
+  /**
+   * Execute single-row query, returning null if not found.
+   */
+  queryOne<T = unknown>(sql: string, params?: unknown[]): Promise<T | null>;
+
+  /**
+   * Execute Tagged Template Literal SQL query with auto-parameterization.
+   */
+  sql<T = unknown>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
+
+  /**
+   * Execute Tagged Template Literal SQL query returning first row or null.
+   */
+  sqlOne<T = unknown>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T | null>;
+
+  /**
+   * Declarative type-safe SELECT with parameterized filters, ordering and pagination.
+   */
+  findMany<T = unknown>(table: string, options?: QueryOptions): Promise<T[]>;
+
+  /**
+   * Declarative type-safe single-row SELECT, returning null if not found.
+   */
+  findOne<T = unknown>(table: string, options?: QueryOptions): Promise<T | null>;
+
+  /**
+   * Declarative type-safe INSERT returning the created row.
+   */
+  insert<T = unknown>(table: string, data: Record<string, unknown>): Promise<T>;
+
+  /**
+   * Declarative type-safe UPDATE with WHERE condition, returning modified rows.
+   */
+  update<T = unknown>(table: string, data: Record<string, unknown>, where: WhereCondition): Promise<T[]>;
+
+  /**
+   * Declarative type-safe DELETE with WHERE condition, returning number of affected rows.
+   */
+  delete(table: string, where: WhereCondition): Promise<number>;
+
+  /**
+   * Execute command inside a database transaction boundary.
+   */
+  transaction<T>(operation: (tx: DatabaseClient) => Promise<T>): Promise<T>;
+
+  /**
+   * Closes active connections or statement pools.
+   */
+  close?(): void | Promise<void>;
+}
+
+/**
+ * In-memory Mock Database Client for deterministic testing and PBT (Fast-Check).
+ */
+export class MockDatabaseClient implements DatabaseClient {
+  private tables: Map<string, Array<Record<string, unknown>>> = new Map();
+  private queryHandlers: Array<{
+    match: RegExp | string;
+    handler: (params: unknown[]) => unknown[];
+  }> = [];
+
+  /** Every statement the client was asked to execute, in order. */
+  readonly calls: Array<{ sql: string; params: unknown[] }> = [];
+
+  constructor(initialData?: Record<string, Array<Record<string, unknown>>>) {
+    if (initialData) {
+      for (const [table, rows] of Object.entries(initialData)) {
+        this.tables.set(table, [...rows]);
+      }
+    }
+  }
+
+  onQuery(pattern: RegExp | string, handler: (params: unknown[]) => unknown[]): this {
+    this.queryHandlers.push({ match: pattern, handler });
+    return this;
+  }
+
+  async query<T = unknown>(sql: string, params: unknown[] = []): Promise<T[]> {
+    this.calls.push({ sql, params });
+
+    for (const { match, handler } of this.queryHandlers) {
+      const isMatch = typeof match === 'string' ? sql.includes(match) : match.test(sql);
+      if (isMatch) {
+        return handler(params) as T[];
+      }
+    }
+
+    // Default mock response: check if table matches initialData for SELECT queries
+    if (/^\s*SELECT\b/i.test(sql)) {
+      for (const [table, rows] of this.tables.entries()) {
+        if (sql.includes(table)) {
+          return [...rows] as unknown as T[];
+        }
+      }
+    }
+
+    // Default mock response: empty set
+    return [] as T[];
+  }
+
+  async queryOne<T = unknown>(sql: string, params: unknown[] = []): Promise<T | null> {
+    const results = await this.query<T>(sql, params);
+    return results.length > 0 ? results[0] : null;
+  }
+
+  async sql<T = unknown>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]> {
+    const { text, params } = compileTaggedSql(strings, ...values);
+    return this.query<T>(text, params);
+  }
+
+  async sqlOne<T = unknown>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T | null> {
+    const { text, params } = compileTaggedSql(strings, ...values);
+    return this.queryOne<T>(text, params);
+  }
+
+  async findMany<T = unknown>(table: string, options?: QueryOptions): Promise<T[]> {
+    const { sql, params } = compileSelect(table, options);
+    const results = await this.query<Record<string, unknown>>(sql, params);
+    let rows: Array<Record<string, unknown>> = results;
+
+    if (rows.length === 0) {
+      const inMemory = this.tables.get(table);
+      if (inMemory) {
+        rows = inMemory;
+      }
+    }
+
+    if (options?.join && options.join.length > 0) {
+      return rows.map((r) => nestJoinedRow<T>(r, options.join));
+    }
+    return rows as unknown as T[];
+  }
+
+  async findOne<T = unknown>(table: string, options?: QueryOptions): Promise<T | null> {
+    const opts = { ...options, limit: 1 };
+    const { sql, params } = compileSelect(table, opts);
+    const result = await this.queryOne<Record<string, unknown>>(sql, params);
+    let row: Record<string, unknown> | null = result;
+
+    if (row === null) {
+      const inMemory = this.tables.get(table);
+      if (inMemory && inMemory.length > 0) {
+        row = inMemory[0];
+      }
+    }
+
+    if (!row) return null;
+    if (options?.join && options.join.length > 0) {
+      return nestJoinedRow<T>(row, options.join);
+    }
+    return row as unknown as T;
+  }
+
+  async insert<T = unknown>(table: string, data: Record<string, unknown>): Promise<T> {
+    const { sql, params } = compileInsert(table, data);
+    const results = await this.query<T>(sql, params);
+    if (results.length > 0) {
+      return results[0];
+    }
+
+    const tableRows = this.tables.get(table) || [];
+    const created = { ...data };
+    tableRows.push(created);
+    this.tables.set(table, tableRows);
+    return created as T;
+  }
+
+  async update<T = unknown>(table: string, data: Record<string, unknown>, where: WhereCondition): Promise<T[]> {
+    const { sql, params } = compileUpdate(table, data, where);
+    const results = await this.query<T>(sql, params);
+    if (results.length > 0) return results;
+    return [data as T];
+  }
+
+  async delete(table: string, where: WhereCondition): Promise<number> {
+    const { sql, params } = compileDelete(table, where);
+    const results = await this.query(sql, params);
+    return results.length > 0 ? results.length : 1;
+  }
+
+  async transaction<T>(operation: (tx: DatabaseClient) => Promise<T>): Promise<T> {
+    return operation(this);
+  }
+
+  close(): void {}
+}

package/src/core/database-factory.ts

@@ -0,0 +1,46 @@
+/**
+ * SynapseJS - Universal Database Factory
+ *
+ * Auto-detects the database engine from DATABASE_URL:
+ * - If postgres:// or postgresql:// -> Instantiates PostgresDatabaseClient
+ * - Otherwise -> Instantiates embedded SqliteDatabaseClient
+ */
+
+import * as path from 'path';
+import type { DatabaseClient } from './database-client';
+import { PostgresDatabaseClient } from './postgres-client';
+import { SqliteDatabaseClient } from './sqlite-client';
+
+let cachedInstance: DatabaseClient | null = null;
+
+export function getDatabase(connectionUri?: string): DatabaseClient {
+  if (cachedInstance) {
+    return cachedInstance;
+  }
+
+  const uri = connectionUri || process.env.DATABASE_URL;
+
+  if (uri && (uri.startsWith('postgres://') || uri.startsWith('postgresql://'))) {
+    cachedInstance = new PostgresDatabaseClient(uri);
+    return cachedInstance;
+  }
+
+  // A configured engine that is neither supported nor a file path must not be
+  // silently downgraded to embedded SQLite: that would make a Postgres parity
+  // check pass against the wrong engine.
+  if (uri && /^[a-z][a-z0-9+.-]*:\/\//i.test(uri)) {
+    throw new Error(
+      `DATABASE_URL '${uri}' usa um esquema não suportado. Use postgres://, postgresql:// ou um caminho de arquivo SQLite.`
+    );
+  }
+
+  // Fallback to embedded SQLite
+  const dbPath = uri || path.join(process.cwd(), '.synapse/synapse.sqlite');
+  cachedInstance = new SqliteDatabaseClient(dbPath);
+
+  return cachedInstance;
+}
+
+export function resetDatabaseInstance(): void {
+  cachedInstance = null;
+}