create-nexwire 4.2.4 → 4.3.0

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,47 @@
+/**
+ * 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 { 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 +55,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 +72,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";

package/express/src/framework/http/app.ts

@@ -30,6 +30,30 @@ export function createHttpApp() {
     next();
   });
 
+  if (appConfig.openApiEnabled) {
+    configureOpenApi(app);
+    registerOpenApiRoute(
+      createRoute({
+        path: "/health",
+        method: "get",
+        tags: ["System"],
+        responses: {
+          200: jsonContent(z.object({ message: z.string() }), "Application health status")
+        }
+      })
+    );
+
+    app.get("/health", (_req, res) => {
+      res.json({ message: "Application is healthy" });
+    });
+  }
+
+  if (loggingConfig.httpRequests) {
+    app.use(loggerMiddleware);
+  }
+
+  app.use(rateLimiterMiddleware);
+
   app.get("/ready", (_req, res) => {
     const checks: Record<string, string> = {};
     let allOk = true;
@@ -71,30 +95,12 @@ export function createHttpApp() {
     res.type("text/plain").status(200).send(output);
   });
 
-  if (loggingConfig.httpRequests) {
-    app.use(loggerMiddleware);
-  }
-
-  app.use(rateLimiterMiddleware);
-
-  if (appConfig.openApiEnabled) {
-    configureOpenApi(app);
-    registerOpenApiRoute(
-      createRoute({
-        path: "/health",
-        method: "get",
-        tags: ["System"],
-        responses: {
-          200: jsonContent(z.object({ message: z.string() }), "Application health status")
-        }
-      })
-    );
+  if (!appConfig.openApiEnabled) {
+    app.get("/health", (_req, res) => {
+      res.json({ message: "Application is healthy" });
+    });
   }
 
-  app.get("/health", (_req, res) => {
-    res.json({ message: "Application is healthy" });
-  });
-
   if (!hasUiBuild()) {
     app.get("/", (_req, res) => {
       res.json({ name: appConfig.name, ok: true });

package/express/src/framework/http/logger.ts

@@ -1,12 +1,19 @@
 import type { ErrorRequestHandler, RequestHandler } from "express";
 import createError from "http-errors";
 import { logger } from "@/framework/support/logger.js";
+import { openApiConfig } from "@/config/index.js";
 
 function requestIp(req: Parameters<RequestHandler>[0]) {
   const forwarded = req.headers["x-forwarded-for"];
   return String(req.headers["cf-connecting-ip"] || forwarded || req.headers["x-real-ip"] || req.socket.remoteAddress || "");
 }
 
+// এই ফাংশনটি Express-এর জন্য তৈরি করা হয়েছে, তাই এটি কিছু অতিরিক্ত পাথও বাদ দেয় যা Hono-তে প্রযোজ্য নয়।
+function shouldSkipHttpLog(pathname: string) {
+  // /queues, /queues/..., /favicon.ico বাদ দিন
+  return pathname.startsWith("/queues") || pathname === "/favicon.ico" || pathname === openApiConfig.scalar.specUrl || pathname === openApiConfig.scalar.docsPath;
+}
+
 export const loggerMiddleware: RequestHandler = (req, res, next) => {
   const startedAt = Date.now();
   const requestId = crypto.randomUUID();
@@ -15,19 +22,22 @@ export const loggerMiddleware: RequestHandler = (req, res, next) => {
   res.setHeader("X-Request-ID", requestId);
 
   res.on("finish", () => {
-    const pathname = (req.url ?? "").split("?")[0];
-    if (pathname === "/health" || pathname.startsWith("/queues")) return;
+    // req.originalUrl ব্যবহার করুন, কারণ req.url রাউটারের ভেতরে বদলে যায়
+    const pathname = (req.originalUrl || req.url || "").split("?")[0];
 
-    logger.info("HTTP Request", {
-      requestId,
-      method: req.method,
-      path: pathname,
-      url: req.originalUrl,
-      status: res.statusCode,
-      duration_ms: Date.now() - startedAt,
-      ip: requestIp(req),
-      userAgent: req.headers["user-agent"] || null
-    });
+    // shouldSkipHttpLog চেক করুন
+    if (!shouldSkipHttpLog(pathname)) {
+      logger.info("HTTP Request", {
+        requestId,
+        method: req.method,
+        path: pathname,
+        url: req.originalUrl,
+        status: res.statusCode,
+        duration_ms: Date.now() - startedAt,
+        ip: requestIp(req),
+        userAgent: req.headers["user-agent"] || null
+      });
+    }
   });
 
   next();
@@ -45,6 +55,7 @@ export const onError: ErrorRequestHandler = (error, _req, res, _next) => {
       status,
       issues: error.error.issues
     });
+
     res.status(status).json({
       success: false,
       error: {
@@ -52,18 +63,18 @@ export const onError: ErrorRequestHandler = (error, _req, res, _next) => {
         issues: error.error.issues
       }
     });
+
     return;
   }
 
   const message = status === 500 && !error?.expose ? "Internal server error" : (error?.message ?? "Internal server error");
   const stack = process.env.NODE_ENV === "production" ? undefined : error?.stack;
+
   logger.error("Request failed", {
     status,
     message,
     stack: error?.stack
   });
-  res.status(status).json({
-    message,
-    ...(stack ? { stack } : {})
-  });
+
+  res.status(status).json({ message, ...(stack ? { stack } : {}) });
 };

package/express/src/framework/http/openapi.ts

@@ -28,27 +28,25 @@ export function createOpenApiDocument() {
 }
 
 export function configureOpenApi(app: Express) {
-  app.get(openApiConfig.scalar.specUrl, (_req, res) => {
+  const { specUrl, docsPath, favicon, ...scalarOptions } = openApiConfig.scalar;
+
+  app.get(specUrl, (_req, res) => {
     res.json(createOpenApiDocument());
   });
 
-  if (openApiConfig.scalar.favicon) {
+  if (favicon) {
     app.get("/favicon.ico", (_req, res) => {
-      const faviconPath = path.join(process.cwd(), openApiConfig.scalar.favicon);
+      const faviconPath = path.join(process.cwd(), favicon);
       if (!fs.existsSync(faviconPath)) return res.status(404).end();
       res.type("image/x-icon").sendFile(faviconPath);
     });
   }
 
   app.get(
-    openApiConfig.scalar.docsPath,
+    docsPath,
     apiReference({
-      url: openApiConfig.scalar.specUrl,
-      layout: openApiConfig.scalar.layout,
-      theme: openApiConfig.scalar.theme,
-      pageTitle: openApiConfig.scalar.pageTitle,
-      defaultHttpClient: openApiConfig.scalar.defaultHttpClient,
-      defaultOpenAllTags: openApiConfig.scalar.defaultOpenAllTags
-    } as any)
+      url: specUrl, // Map specUrl to url
+      ...scalarOptions // Pass EVERYTHING else automatically!
+    } as any) // The `as any` might still be needed if Express types are slightly behind
   );
 }

package/express/src/framework/modules/routes.ts

@@ -1,21 +1,26 @@
-import type { Express } from "express";
-import { registerRouterOpenApi } from "@/framework/http/router.js";
-import { discoverModuleFiles, importFile, moduleNameFromPath } from "@/framework/modules/discover.js";
-
-export async function registerModuleRoutes(app: Express) {
-  const files = await discoverModuleFiles("**/routes/*.{ts,js}");
-
-  for (const file of files) {
-    const route = await importFile(file);
-
-    if (!route.default) {
-      throw new Error(`Route file ${file} has no default export`);
-    }
-
-    const prefix = `/api/${moduleNameFromPath(file)}`;
-    registerRouterOpenApi(route.default, prefix);
-    app.use(prefix, route.default);
-  }
-
-  return files.length;
-}
+import type { Express } from "express";
+import { registerRouterOpenApi } from "@/framework/http/router.js";
+import { discoverModuleFiles, importFile, moduleNameFromPath } from "@/framework/modules/discover.js";
+
+export async function registerModuleRoutes(app: Express) {
+  const files = await discoverModuleFiles("**/routes/*.{ts,js}");
+
+  for (const file of files) {
+    const route = await importFile(file);
+
+    if (!route.default) {
+      throw new Error(`Route file ${file} has no default export`);
+    }
+
+    // Optional Guard: Ensure it's an Express Router
+    if (typeof route.default !== "function" || !route.default.stack) {
+      throw new Error(`Route file ${file} must export an express.Router() instance as default`);
+    }
+
+    const prefix = `/api/${moduleNameFromPath(file)}`;
+    registerRouterOpenApi(route.default, prefix);
+    app.use(prefix, route.default);
+  }
+
+  return files.length;
+}

package/express/src/framework/notification/channels/broadcast.ts

@@ -0,0 +1,15 @@
+import { dispatchEvent } from "@/framework/events/dispatcher.js";
+import type { NotificationChannel } from "@/framework/notification/contracts.js";
+
+export const broadcastChannel: NotificationChannel = {
+  name: "broadcast",
+  async send(target, notification, options) {
+    if (!options.broadcast) return false;
+
+    await dispatchEvent("notification.created", notification, {
+      broadcast: { users: [target.id] }
+    });
+
+    return true;
+  }
+};

package/express/src/framework/notification/channels/mail.ts

@@ -0,0 +1,40 @@
+import { mail } from "@/framework/support/mail.js";
+import { resolveAuthProvider } from "@/framework/providers/adapter.js";
+import { redisClientIfReady } from "@/framework/redis/client.js";
+import { dispatchEvent } from "@/framework/events/dispatcher.js";
+import type { NotificationChannel } from "@/framework/notification/contracts.js";
+
+function escapeHtml(str: string) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+export const mailChannel: NotificationChannel = {
+  name: "mail",
+  async send(target, notification, options) {
+    if (!options.mail) return false;
+
+    let to = options.mail.to || null;
+    if (!to) {
+      try {
+        const provider = await resolveAuthProvider();
+        if (provider?.getUserContact) {
+          const contact = await provider.getUserContact(target.id);
+          if (contact?.email) to = contact.email as string;
+        }
+      } catch { }
+    }
+
+    if (!to) return false;
+
+    const subject = options.mail.subject || notification.title;
+    const html = options.mail.html || `<h2>${escapeHtml(notification.title)}</h2>${notification.body ? `<p>${escapeHtml(notification.body)}</p>` : ""}`;
+
+    if (redisClientIfReady()) {
+      await dispatchEvent("notification:mail", { to, subject, html }, { queue: "mail" });
+    } else {
+      await mail.sendMail({ to, subject, html });
+    }
+
+    return true;
+  }
+};