create-nexwire 4.2.5 → 4.4.0

package/express/src/database/migrations/sqlite/meta/0000_snapshot.json

@@ -1,7 +1,7 @@
 {
   "version": "6",
   "dialect": "sqlite",
-  "id": "f0fe475e-8a3e-4c5c-9b5e-9ec41ddfde71",
+  "id": "af502348-be37-45c6-84e4-df4db9f31bfb",
   "prevId": "00000000-0000-0000-0000-000000000000",
   "tables": {
     "roles": {

package/express/src/database/migrations/sqlite/meta/_journal.json

@@ -5,7 +5,7 @@
     {
       "idx": 0,
       "version": "6",
-      "when": 1792936160057,
+      "when": 1793719238470,
       "tag": "0000_init",
       "breakpoints": true
     }

package/express/src/framework/cache/cache.ts

@@ -1,10 +1,18 @@
 import { cacheConfig, redisConfig } from "@/config/index.js";
+import { createCircuitBreaker, isCircuitBreakerError } from "@/framework/circuit-breaker/cb.js";
 import { redisClientIfReady } from "@/framework/redis/client.js";
 
 function cacheKey(key: string) {
   return `${cacheConfig.keyPrefix}:${key}`;
 }
 
+// Initialize the circuit breaker specifically for Cache operations
+const cacheBreaker = createCircuitBreaker({
+  name: "Redis Cache",
+  failureThreshold: 3,
+  resetTimeout: 30000
+});
+
 /**
  * Why: Provides Redis-backed cache helpers with graceful fallback behavior.
  * When: Controllers/jobs need temporary computed data caching.
@@ -20,18 +28,35 @@ export const cache = {
    */
   async get<T>(key: string, fallback: T | null = null) {
     const client = redisClientIfReady();
+    // If the client isn't connected at all, fail fast to fallback
     if (!client) return fallback;
 
-    const value = await client.get(cacheKey(key));
-    return value ? (JSON.parse(value) as T) : fallback;
+    try {
+      return await cacheBreaker.exec(async () => {
+        const value = await client.get(cacheKey(key));
+        return value ? (JSON.parse(value) as T) : fallback;
+      });
+    } catch (error) {
+      // If the circuit is open, or a Redis error occurs, return the fallback safely
+      if (isCircuitBreakerError(error)) return fallback;
+      return fallback;
+    }
   },
 
   async set(key: string, value: unknown, ttl = cacheConfig.ttlSeconds) {
     const client = redisClientIfReady();
     if (!client) return false;
 
-    await client.set(cacheKey(key), JSON.stringify(value), "EX", ttl);
-    return true;
+    try {
+      return await cacheBreaker.exec(async () => {
+        await client.set(cacheKey(key), JSON.stringify(value), "EX", ttl);
+        return true;
+      });
+    } catch (error) {
+      // If the circuit is open, or a Redis error occurs, silently fail
+      if (isCircuitBreakerError(error)) return false;
+      return false;
+    }
   },
 
   /**
@@ -51,8 +76,15 @@ export const cache = {
     const client = redisClientIfReady();
     if (!client) return false;
 
-    await client.del(cacheKey(key));
-    return true;
+    try {
+      return await cacheBreaker.exec(async () => {
+        await client.del(cacheKey(key));
+        return true;
+      });
+    } catch (error) {
+      if (isCircuitBreakerError(error)) return false;
+      return false;
+    }
   },
 
   /**
@@ -66,7 +98,7 @@ export const cache = {
     if (cached !== null) return cached;
 
     const fresh = await callback();
-    await this.put(key, fresh, ttl);
+    await this.set(key, fresh, ttl);
     return fresh;
   },
 
@@ -77,6 +109,6 @@ export const cache = {
    * How: Confirms REDIS flag and ready Redis client instance.
    */
   isAvailable() {
-    return redisConfig.enabled && redisClientIfReady() !== null;
+    return redisConfig.enabled && redisClientIfReady() !== null && cacheBreaker.getState() !== "open";
   }
 };

package/express/src/framework/circuit-breaker/cb.ts

@@ -1,60 +1,88 @@
-export class CircuitBreaker {
-  private state: "closed" | "open" | "half-open" = "closed";
-  private failureCount = 0;
-  private readonly failureThreshold = 3;
-  private readonly resetTimeout = 30000;
-  private lastFailureTime = 0;
-  private successCount = 0;
-  private readonly successThreshold = 1;
-
-  async exec<T>(fn: () => Promise<T>): Promise<T> {
-    if (this.state === "open") {
-      if (Date.now() - this.lastFailureTime >= this.resetTimeout) {
-        this.state = "half-open";
-        this.successCount = 0;
-      } else {
-        throw new Error("Circuit breaker is open");
-      }
-    }
-    try {
-      const result = await fn();
-      this.onSuccess();
-      return result;
-    } catch (error) {
-      this.onFailure();
-      throw error;
-    }
-  }
-
-  getState(): "closed" | "open" | "half-open" {
-    return this.state;
-  }
-
-  onSuccess(): void {
-    if (this.state === "half-open") {
-      this.successCount++;
-      if (this.successCount >= this.successThreshold) {
-        this.reset();
-      }
-    }
-    this.failureCount = 0;
-  }
-
-  onFailure(): void {
-    this.failureCount++;
-    if (this.failureCount >= this.failureThreshold || this.state === "half-open") {
-      this.trip();
-    }
-  }
-
-  trip(): void {
-    this.state = "open";
-    this.lastFailureTime = Date.now();
-  }
-
-  reset(): void {
-    this.state = "closed";
-    this.failureCount = 0;
-    this.successCount = 0;
-  }
-}
+// Factory for the error
+export function createCircuitBreakerError(serviceName: string) {
+  const error = new Error(`Circuit breaker is open for ${serviceName}. Service is temporarily unavailable.`);
+  // Attach a custom property to identify it
+  Object.assign(error, { name: "CircuitBreakerOpenError", isCircuitBreakerError: true });
+  return error;
+}
+
+// Functional Type Guard
+export function isCircuitBreakerError(error: unknown): error is Error {
+  return error instanceof Error && (error as any).isCircuitBreakerError === true;
+}
+
+export interface CircuitBreakerOptions {
+  name?: string;
+  failureThreshold?: number;
+  resetTimeout?: number;
+  successThreshold?: number;
+}
+
+export function createCircuitBreaker({
+  name = "Unknown Service",
+  failureThreshold = 3,
+  resetTimeout = 30000,
+  successThreshold = 1
+}: CircuitBreakerOptions = {}) {
+  let state: "closed" | "open" | "half-open" = "closed";
+  let failureCount = 0;
+  let successCount = 0;
+  let lastFailureTime = 0;
+  let isHalfOpenTestRunning = false;
+
+  function trip() {
+    state = "open";
+    lastFailureTime = Date.now();
+  }
+
+  function reset() {
+    state = "closed";
+    failureCount = 0;
+    successCount = 0;
+  }
+
+  return {
+    async exec<T>(fn: () => Promise<T>): Promise<T> {
+      if (state === "open") {
+        if (Date.now() - lastFailureTime >= resetTimeout) {
+          state = "half-open";
+          successCount = 0;
+          isHalfOpenTestRunning = false;
+        } else {
+          throw createCircuitBreakerError(name);
+        }
+      }
+
+      if (state === "half-open") {
+        if (isHalfOpenTestRunning) {
+          throw createCircuitBreakerError(name);
+        }
+        isHalfOpenTestRunning = true;
+      }
+
+      try {
+        const result = await fn();
+        if (state === "half-open") {
+          successCount++;
+          if (successCount >= successThreshold) reset();
+        }
+        failureCount = 0;
+        return result;
+      } catch (error) {
+        failureCount++;
+        if (failureCount >= failureThreshold || state === "half-open") {
+          trip();
+        }
+        throw error;
+      } finally {
+        if (state === "half-open") isHalfOpenTestRunning = false;
+      }
+    },
+
+    getState() {
+      return state;
+    }
+  };
+}
+
+export type CircuitBreaker = ReturnType<typeof createCircuitBreaker>;

package/express/src/framework/database/connection.ts

@@ -1,6 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { databaseConfig } from "@/config/index.js";
+import { databaseConfig, detectDialectFrom } from "@/config/index.js";
 import { loadAppSchema } from "@/framework/database/app-schema.js";
 
 export type Dialect = "sqlite" | "mysql" | "postgresql";
@@ -20,10 +20,7 @@ async function optionalImport<T = any>(name: string): Promise<T> {
  * How: Checks DATABASE_URL prefix and maps to sqlite/mysql/postgresql.
  */
 export function detectDialect(): Dialect {
-  const url = databaseConfig.url.toLowerCase();
-  if (url.startsWith("mysql")) return "mysql";
-  if (url.startsWith("postgres")) return "postgresql";
-  return "sqlite";
+  return detectDialectFrom(databaseConfig.url);
 }
 
 /**
@@ -36,9 +33,9 @@ export async function initDatabase() {
   if (databaseInstance) return databaseInstance;
 
   dialect = detectDialect();
-
   const schema = await loadAppSchema();
 
+  // --- SQLite (libsql) ---
   if (dialect === "sqlite") {
     let drizzleSqlite: any;
     let createClient: any;
@@ -51,13 +48,24 @@ export async function initDatabase() {
       throw new Error("Missing sqlite dependencies. Install with: bun add drizzle-orm @libsql/client");
     }
 
-    const file = path.resolve(process.cwd(), databaseConfig.url.replace(/^sqlite:/, ""));
-    await fs.mkdir(path.dirname(file), { recursive: true });
-    pool = createClient({ url: `file:${file.replace(/\\/g, "/")}` });
+    // databaseConfig.url is guaranteed to be "file:..."
+    const url = databaseConfig.url;
+
+    // Ensure the directory exists (skip for :memory: or absolute URLs)
+    if (!url.includes(":memory:")) {
+      const rawPath = url.replace(/^file:/i, "");
+      if (!rawPath.startsWith("//")) {
+        const file = path.resolve(process.cwd(), rawPath);
+        await fs.mkdir(path.dirname(file), { recursive: true });
+      }
+    }
+
+    pool = createClient({ url });
     databaseInstance = drizzleSqlite(pool, { schema });
     return databaseInstance;
   }
 
+  // --- MySQL ---
   if (dialect === "mysql") {
     let drizzleMysql: any;
     let mysql: any;
@@ -67,11 +75,19 @@ export async function initDatabase() {
       throw new Error("Missing mysql dependencies. Install with: bun add drizzle-orm mysql2");
     }
 
-    pool = mysql.createPool({ uri: databaseConfig.url, connectionLimit: 10, enableKeepAlive: true });
+    pool = mysql.createPool({
+      uri: databaseConfig.url,
+      connectionLimit: databaseConfig.pool.max,
+      connectTimeout: databaseConfig.pool.connectTimeout,
+      enableKeepAlive: databaseConfig.pool.keepAlive,
+      ...(databaseConfig.ssl ? { ssl: {} } : {})
+    });
+
     databaseInstance = drizzleMysql(pool, { schema, mode: "default" });
     return databaseInstance;
   }
 
+  // --- PostgreSQL ---
   let drizzlePg: any;
   let postgres: any;
   try {
@@ -83,7 +99,14 @@ export async function initDatabase() {
     throw new Error("Missing postgres dependencies. Install with: bun add drizzle-orm postgres");
   }
 
-  pool = postgres(databaseConfig.url);
+  pool = postgres(databaseConfig.url, {
+    max: databaseConfig.pool.max,
+    idle_timeout: Math.floor(databaseConfig.pool.idleTimeout / 1000),
+    connect_timeout: Math.floor(databaseConfig.pool.connectTimeout / 1000),
+    prepare: databaseConfig.prepare,
+    ...(databaseConfig.ssl ? { ssl: "require" as const } : {})
+  });
+
   databaseInstance = drizzlePg(pool, { schema });
   return databaseInstance;
 }
@@ -121,23 +144,20 @@ export async function closeDatabase() {
 
   const activeDialect = databaseDialect();
 
-  if (activeDialect === "sqlite") {
-    pool.close?.();
-    pool = undefined;
-    databaseInstance = undefined;
-    return;
-  }
-
-  if (activeDialect === "mysql") {
-    await pool.end();
+  try {
+    if (activeDialect === "sqlite") {
+      await pool.close?.();
+    } else if (activeDialect === "mysql") {
+      await pool.end();
+    } else {
+      await pool.end();
+    }
+  } catch (error) {
+    console.error("Error closing database pool:", error);
+  } finally {
     pool = undefined;
     databaseInstance = undefined;
-    return;
   }
-
-  await pool.end();
-  pool = undefined;
-  databaseInstance = undefined;
 }
 
 /**
@@ -146,7 +166,7 @@ export async function closeDatabase() {
  * Where: Locking, schema, and shutdown helpers.
  * How: Uses initialized dialect or falls back to detection.
  */
-export function databaseDialect() {
+export function databaseDialect(): Dialect {
   return dialect || detectDialect();
 }
 
@@ -185,12 +205,17 @@ export const db = new Proxy(
   {
     get(_target, property) {
       const instance = database();
+
       if (property === "execute") {
         return async (query: unknown, params?: unknown) => {
-          const raw = instance.execute ? await instance.execute(query, params) : await instance.all(query);
+          if (!instance.execute) {
+            throw new Error("The current driver does not support raw execute.");
+          }
+          const raw = await instance.execute(query, params);
           return normalizeExecuteResult(raw);
         };
       }
+
       const value = instance[property as keyof typeof instance];
       return typeof value === "function" ? value.bind(instance) : value;
     }

package/express/src/framework/events/dispatcher.ts

@@ -1,49 +1,61 @@
-import { queueJob } from "@/framework/queue/queue.js";
-import { type BroadcastOptions, broadcast } from "@/framework/realtime/broadcast.js";
-
-type CommandHandler = (payload: any) => Promise<any>;
-
-const commandHandlers = new Map<string, CommandHandler>();
-
-/**
- * Why: Registers in-memory command handler for synchronous dispatch.
- * When: Module startup files register command handlers.
- * Where: Job/command style module code.
- * How: Stores handler in a process-level map by command name.
- */
-export function command(name: string, handler: CommandHandler) {
-  commandHandlers.set(name, handler);
-}
-
-/**
- * Why: Executes command immediately or queues it for async processing.
- * When: Application logic needs command pattern behavior.
- * Where: Controllers, jobs, and service layers.
- * How: Runs local handler unless async requested; otherwise enqueues.
- */
-export async function dispatchCommand(name: string, payload: any, options: { async?: boolean; queue?: string } = {}) {
-  if (!options.async) {
-    const handler = commandHandlers.get(name);
-    if (handler) return await handler(payload);
-  }
-
-  return await queueJob(name, payload, { queue: options.queue || "default" });
-}
-
-/**
- * Why: Dispatches domain events with optional queueing and websocket fan-out.
- * When: Domain actions need side effects or realtime notifications.
- * Where: Controllers/jobs across modules.
- * How: Broadcasts via Socket.IO and optionally enqueues job.
- */
-export async function dispatchEvent(name: string, payload: any, options: { queue?: boolean | string; broadcast?: BroadcastOptions } = {}) {
-  if (options.broadcast) {
-    broadcast(name, payload, options.broadcast);
-  }
-
-  if (options.queue) {
-    return await queueJob(name, payload, {
-      queue: typeof options.queue === "string" ? options.queue : "default"
-    });
-  }
-}
+import { queueJob } from "@/framework/queue/queue.js";
+import { type BroadcastOptions, broadcast } from "@/framework/realtime/broadcast.js";
+import { logger } from "@/framework/support/logger.js";
+
+type CommandHandler = (payload: any) => Promise<any>;
+
+const commandHandlers = new Map<string, CommandHandler>();
+
+/**
+ * Why: Registers in-memory command handler for synchronous dispatch.
+ * When: Module startup files register command handlers.
+ * Where: Job/command style module code.
+ * How: Stores handler in a process-level map by command name.
+ */
+export function command(name: string, handler: CommandHandler) {
+  commandHandlers.set(name, handler);
+}
+
+/**
+ * Why: Executes command immediately or queues it for async processing.
+ * When: Application logic needs command pattern behavior.
+ * Where: Controllers, jobs, and service layers.
+ * How: Runs local handler unless async requested; otherwise enqueues.
+ */
+export async function dispatchCommand(name: string, payload: any, options: { async?: boolean; queue?: string } = {}) {
+  if (!options.async) {
+    const handler = commandHandlers.get(name);
+    if (handler) return await handler(payload);
+  }
+
+  return await queueJob(name, payload, { queue: options.queue || "default" });
+}
+
+/**
+ * Why: Dispatches domain events with optional queueing and websocket fan-out.
+ * When: Domain actions need side effects or realtime notifications.
+ * Where: Controllers/jobs across modules.
+ * How: Broadcasts via Socket.IO and optionally enqueues job.
+ */
+export async function dispatchEvent(name: string, payload: any, options: { queue?: boolean | string; broadcast?: BroadcastOptions } = {}) {
+  // 1. Handle Broadcast safely
+  if (options.broadcast) {
+    try {
+      // Await the broadcast so the circuit breaker and redis publish complete safely
+      await broadcast(name, payload, options.broadcast);
+    } catch (error) {
+      logger.error(`Failed to broadcast event: ${name}`, { error });
+    }
+  }
+
+  // 2. Handle Queue safely
+  if (options.queue) {
+    try {
+      return await queueJob(name, payload, {
+        queue: typeof options.queue === "string" ? options.queue : "default"
+      });
+    } catch (error) {
+      logger.error(`Failed to queue event: ${name}`, { error });
+    }
+  }
+}

package/express/src/framework/facade.ts

@@ -1,15 +1,48 @@
+/**
+ * Why: Central public API surface for framework consumers.
+ * When: Modules/middlewares need framework utilities.
+ * Where: App-layer imports should target this file.
+ * How: Re-exports stable, reusable helpers while hiding setup internals.
+ */
+
 export * as lodash from "lodash-es";
+// ==========================================
+// 1. External & Core Utilities
+// ==========================================
 export { z } from "zod";
+// ==========================================
+// 6. Cache & Session
+// ==========================================
 export { cache } from "@/framework/cache/cache.js";
+// ==========================================
+// 2. Database
+// ==========================================
 export { database, db } from "@/framework/database/connection.js";
-export type { PaginatedResult } from "@/framework/database/paginate.js";
-export { paginate, paginateModel, paginateQuery, paginateTable } from "@/framework/database/paginate.js";
+export { type PaginatedResult, paginate, paginateModel, paginateQuery, paginateTable } from "@/framework/database/paginate.js";
+// ==========================================
+// 4. Events & Queue
+// ==========================================
 export { command, dispatchCommand, dispatchEvent } from "@/framework/events/dispatcher.js";
 export { registerOpenApiRoute } from "@/framework/http/openapi.js";
 export type { RouteConfig } from "@/framework/http/router.js";
+// ==========================================
+// 3. HTTP & Routing
+// ==========================================
+export { loginLimiter } from "@/framework/http/ratelimiter.js";
 export { createRoute, createRouter, group, jsonContent } from "@/framework/http/router.js";
 export { validate } from "@/framework/http/validation.js";
+export { broadcastChannel } from "@/framework/notification/channels/broadcast.js";
+export { mailChannel } from "@/framework/notification/channels/mail.js";
+export type { NotificationChannel, NotificationOptions } from "@/framework/notification/contracts.js";
+// ==========================================
+// 10. Notification Engine (Delivery Channels)
+// ==========================================
 export { notify } from "@/framework/notification/index.js";
+export { registerChannel } from "@/framework/notification/registry.js";
+// ==========================================
+// 9. Providers (Storage/Auth)
+// ==========================================
+export { resolveAuthProvider, resolveNotificationProvider } from "@/framework/providers/adapter.js";
 export type {
   AuthProvider,
   AuthProviderRefreshToken,
@@ -23,7 +56,6 @@ export type {
   NotificationProvider,
   NotificationRecord
 } from "@/framework/providers/contracts.js";
-export { resolveAuthProvider, resolveNotificationProvider } from "@/framework/providers/adapter.js";
 export { loadProviders } from "@/framework/providers/loader.js";
 export {
   clearAuthProvider,
@@ -41,12 +73,24 @@ export {
   registerProvider
 } from "@/framework/providers/registry.js";
 export { queue, queueJob, shouldQueue } from "@/framework/queue/queue.js";
+// ==========================================
+// 5. Realtime
+// ==========================================
 export { broadcast } from "@/framework/realtime/index.js";
 export { defineSchedule } from "@/framework/scheduler/scheduler.js";
 export { session } from "@/framework/session/session.js";
+// ==========================================
+// 7. Storage & Mail
+// ==========================================
 export { storage } from "@/framework/storage/storage.js";
+// ==========================================
+// 8. Security, Auth & Uploads
+// ==========================================
 export { cookie } from "@/framework/support/cookie.js";
 export { jwt } from "@/framework/support/jwt.js";
+// ==========================================
+// 11. Utilities
+// ==========================================
 export { logger } from "@/framework/support/logger.js";
 export { mail } from "@/framework/support/mail.js";
 export { password } from "@/framework/support/password.js";