create-nexwire 4.2.5 → 4.4.0

package/hono/src/framework/facade.ts

@@ -5,17 +5,44 @@
  * How: Re-exports stable, reusable helpers while hiding setup internals.
  */
 
+// ==========================================
+// 1. External & Core Utilities
+// ==========================================
 export { createRoute, z } from "@hono/zod-openapi";
 export * as lodash from "lodash-es";
 export * as HttpStatusCodes from "stoker/http-status-codes";
 export { jsonContent } from "stoker/openapi/helpers";
+// ==========================================
+// 6. Cache & Session
+// ==========================================
 export { cache } from "@/framework/cache/cache.js";
+// ==========================================
+// 2. Database
+// ==========================================
 export { database, db } from "@/framework/database/connection.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";
+// ==========================================
+// 3. HTTP & Routing
+// ==========================================
+export { loginLimiter } from "@/framework/http/ratelimiter.js";
 export { createRouter, group } 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,
@@ -29,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,
@@ -47,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
+// ==========================================
 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/hono/src/framework/http/logger.ts

@@ -1,81 +1,86 @@
-import type { Context, Next } from "hono";
-import { loggingConfig } from "@/config/index.js";
-import { logger } from "@/framework/support/logger.js";
-
-function ip(c: Context) {
-  return c.req.header("cf-connecting-ip") || c.req.header("x-forwarded-for") || c.req.header("x-real-ip") || null;
-}
-
-function shouldSkipHttpLog(pathname: string) {
-  return pathname.startsWith("/queues");
-}
-
-/**
- * Why: Logs each HTTP request with latency and request metadata.
- * When: Applied globally to app routes.
- * Where: HTTP middleware stack.
- * How: Captures start time, assigns request id, logs after downstream response.
- */
-export async function loggerMiddleware(c: Context, next: Next) {
-  const start = Date.now();
-  const requestId = crypto.randomUUID();
-
-  c.set("requestId", requestId);
-  await next();
-
-  if (!loggingConfig.httpRequests || shouldSkipHttpLog(c.req.path)) {
-    return;
-  }
-
-  logger.info("HTTP Request", {
-    requestId,
-    method: c.req.method,
-    path: c.req.path,
-    url: c.req.url,
-    status: c.res.status,
-    duration_ms: Date.now() - start,
-    ip: ip(c),
-    userAgent: c.req.header("user-agent") || null
-  });
-}
-
-/**
- * Why: Standard 404 handler with structured log context.
- * When: No route matches request path.
- * Where: App notFound handler registration.
- * How: Emits warning log and returns JSON 404 payload.
- */
-export function notFound(c: Context) {
-  logger.warn("404 Not Found", {
-    requestId: c.get("requestId") || null,
-    method: c.req.method,
-    path: c.req.path,
-    url: c.req.url,
-    ip: ip(c),
-    userAgent: c.req.header("user-agent") || null
-  });
-
-  return c.json({ message: "Not Found" }, 404);
-}
-
-/**
- * Why: Centralized unhandled error responder and logger.
- * When: Route/middleware throws uncaught error.
- * Where: App onError handler registration.
- * How: Logs stack + request context and returns status/message JSON.
- */
-export function onError(error: any, c: Context) {
-  logger.error("Unhandled Application Error", {
-    requestId: c.get("requestId") || null,
-    name: error?.name || "Error",
-    message: error?.message,
-    stack: error?.stack,
-    method: c.req.method,
-    path: c.req.path,
-    url: c.req.url,
-    ip: ip(c),
-    userAgent: c.req.header("user-agent") || null
-  });
-
-  return c.json({ message: error?.message || "Internal Server Error" }, error?.status || 500);
-}
+import type { Context, Next } from "hono";
+import { loggingConfig } from "@/config/index.js";
+import { logger } from "@/framework/support/logger.js";
+
+function ip(c: Context) {
+  return c.req.header("cf-connecting-ip") || c.req.header("x-forwarded-for") || c.req.header("x-real-ip") || null;
+}
+
+// Probe endpoints and the queue dashboard are infrastructure traffic, not
+// application requests. Skip them on every engine so the access log stays
+// useful (the dev CLI polls /health while it boots).
+const PROBE_PATHS = new Set(["/health", "/ready", "/live"]);
+
+function shouldSkipHttpLog(pathname: string) {
+  return PROBE_PATHS.has(pathname) || pathname.startsWith("/queues");
+}
+
+/**
+ * Why: Logs each HTTP request with latency and request metadata.
+ * When: Applied globally to app routes.
+ * Where: HTTP middleware stack.
+ * How: Captures start time, assigns request id, logs after downstream response.
+ */
+export async function loggerMiddleware(c: Context, next: Next) {
+  const start = Date.now();
+  const requestId = crypto.randomUUID();
+
+  c.set("requestId", requestId);
+  await next();
+
+  if (!loggingConfig.httpRequests || shouldSkipHttpLog(c.req.path)) {
+    return;
+  }
+
+  logger.info("HTTP Request", {
+    requestId,
+    method: c.req.method,
+    path: c.req.path,
+    url: c.req.url,
+    status: c.res.status,
+    duration_ms: Date.now() - start,
+    ip: ip(c),
+    userAgent: c.req.header("user-agent") || null
+  });
+}
+
+/**
+ * Why: Standard 404 handler with structured log context.
+ * When: No route matches request path.
+ * Where: App notFound handler registration.
+ * How: Emits warning log and returns JSON 404 payload.
+ */
+export function notFound(c: Context) {
+  logger.warn("404 Not Found", {
+    requestId: c.get("requestId") || null,
+    method: c.req.method,
+    path: c.req.path,
+    url: c.req.url,
+    ip: ip(c),
+    userAgent: c.req.header("user-agent") || null
+  });
+
+  return c.json({ message: "Not Found" }, 404);
+}
+
+/**
+ * Why: Centralized unhandled error responder and logger.
+ * When: Route/middleware throws uncaught error.
+ * Where: App onError handler registration.
+ * How: Logs stack + request context and returns status/message JSON.
+ */
+export function onError(error: any, c: Context) {
+  logger.error("Unhandled Application Error", {
+    requestId: c.get("requestId") || null,
+    name: error?.name || "Error",
+    message: error?.message,
+    stack: error?.stack,
+    method: c.req.method,
+    path: c.req.path,
+    url: c.req.url,
+    ip: ip(c),
+    userAgent: c.req.header("user-agent") || null
+  });
+
+  return c.json({ message: error?.message || "Internal Server Error" }, error?.status || 500);
+}

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

@@ -11,6 +11,8 @@ import type { NexwireRouter } from "@/framework/http/router.js";
  * How: Exposes `/doc` spec and `/api-docs` Scalar viewer.
  */
 export function configureOpenApi(app: NexwireRouter) {
+  const { specUrl, docsPath, favicon, ...scalarOptions } = openApiConfig.scalar;
+
   app.doc("/doc", {
     openapi: openApiConfig.version,
     info: {
@@ -20,23 +22,19 @@ export function configureOpenApi(app: NexwireRouter) {
     }
   });
 
-  if (openApiConfig.scalar.favicon) {
+  if (favicon) {
     app.get("/favicon.ico", (c) => {
-      const faviconPath = path.join(process.cwd(), openApiConfig.scalar.favicon);
+      const faviconPath = path.join(process.cwd(), favicon);
       if (!fs.existsSync(faviconPath)) return c.notFound();
       return c.body(fs.readFileSync(faviconPath), 200, { "content-type": "image/x-icon" });
     });
   }
 
   app.get(
-    openApiConfig.scalar.docsPath,
+    docsPath, // Use the destructured path
     Scalar({
-      url: openApiConfig.scalar.specUrl,
-      layout: openApiConfig.scalar.layout,
-      theme: openApiConfig.scalar.theme,
-      pageTitle: openApiConfig.scalar.pageTitle,
-      defaultHttpClient: openApiConfig.scalar.defaultHttpClient,
-      defaultOpenAllTags: openApiConfig.scalar.defaultOpenAllTags
+      url: specUrl, // Use the destructured URL
+      ...scalarOptions // Pass EVERYTHING else automatically!
     })
   );
 }

package/hono/src/framework/maker-cli/runtime/core.mjs

@@ -120,7 +120,7 @@ function serveRedisUnavailablePage(port, endpoint) {
 </html>
 `;
 
-  return new Promise((resolve, reject) => {
+  return new Promise((_resolve, reject) => {
     const server = http.createServer((_req, res) => {
       res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
       res.end(body);
@@ -558,4 +558,3 @@ export async function clearViteCache() {
 
   console.log("Vite cache cleared.");
 }
-

package/hono/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/hono/src/framework/notification/channels/mail.ts

@@ -0,0 +1,42 @@
+import { dispatchEvent } from "@/framework/events/dispatcher.js";
+import type { NotificationChannel } from "@/framework/notification/contracts.js";
+import { resolveAuthProvider } from "@/framework/providers/adapter.js";
+import { redisClientIfReady } from "@/framework/redis/client.js";
+import { mail } from "@/framework/support/mail.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;
+  }
+};

package/hono/src/framework/notification/contracts.ts

@@ -0,0 +1,29 @@
+import type { NotifiableTarget, NotificationRecord } from "@/framework/providers/contracts.js";
+
+export type NotificationTarget = number | string | NotifiableTarget;
+export type NormalizedTarget = { type: string; id: number | string };
+
+export type NotificationOptions = {
+  type?: string;
+  title: string;
+  body?: string;
+  link?: string;
+  data?: Record<string, unknown>;
+
+  // Built-in Channels
+  broadcast?: boolean;
+  mail?: {
+    to?: string;
+    subject?: string;
+    html?: string;
+  };
+
+  // Extensible: Add any custom channel options here (e.g., sms, push, discord)
+  sms?: { to?: string; message?: string };
+  push?: { token?: string; payload?: any };
+};
+
+export interface NotificationChannel {
+  name: string;
+  send(target: NormalizedTarget, notification: NotificationRecord, options: NotificationOptions): Promise<boolean>;
+}

package/hono/src/framework/notification/index.ts

@@ -1,39 +1,12 @@
-import { dispatchEvent } from "@/framework/events/dispatcher.js";
-import { resolveAuthProvider, resolveNotificationProvider } from "@/framework/providers/adapter.js";
-import type { NotifiableTarget, NotificationRecord } from "@/framework/providers/contracts.js";
-import { redisClientIfReady } from "@/framework/redis/client.js";
-import { mail } from "@/framework/support/mail.js";
+import type { NormalizedTarget, NotificationOptions, NotificationTarget } from "@/framework/notification/contracts.js";
+import { getChannels } from "@/framework/notification/registry.js";
+import { resolveNotificationProvider } from "@/framework/providers/adapter.js";
+import type { NotificationRecord } from "@/framework/providers/contracts.js";
 
 let missingProviderWarned = false;
 
-/** A numeric id (default auth), a string id (UUID/ULID), or an explicit target. */
-export type NotificationTarget = number | string | NotifiableTarget;
-
-/** Extra JSON metadata attached to the notification (e.g. entity IDs, links). */
-export type NotificationOptions = {
-  /** Notification category key (default: "info") */
-  type?: string;
-  /** Notification title */
-  title: string;
-  /** Notification body text */
-  body?: string;
-  /** Optional click-through URL */
-  link?: string;
-  /** Arbitrary JSON payload stored in `data` column */
-  data?: Record<string, unknown>;
-  /** Whether to broadcast the notification to the user's socket in realtime */
-  broadcast?: boolean;
-  /** Email delivery options */
-  mail?: {
-    /** Explicit recipient. Skips the auth provider contact lookup. */
-    to?: string;
-    subject?: string;
-    html?: string;
-  };
-};
-
 /** Turn the public target argument into the polymorphic owner pair. */
-function normalizeTarget(target: NotificationTarget): Required<Pick<NotifiableTarget, "id">> & { type: string } {
+function normalizeTarget(target: NotificationTarget): NormalizedTarget {
   if (target !== null && typeof target === "object") {
     return {
       type: String(target.type || "user").trim() || "user",
@@ -44,13 +17,10 @@ function normalizeTarget(target: NotificationTarget): Required<Pick<NotifiableTa
 }
 
 /**
- * Why: Persists a notification through the registered provider.
- * When: A feature wants to record something for a user (or another notifiable).
+ * Why: Persists a notification to the database and triggers all active channels.
+ * When: A feature wants to record something for a user.
  * Where: Application code, through the framework facade.
- * How: The provider owns storage; broadcasting and email stay here so a custom
- *      store cannot silently disable them. A missing provider is reported once
- *      and returns `null` instead of throwing, matching the framework's
- *      "optional module" behaviour.
+ * How: The provider owns database storage. The channels handle delivery (mail, sms, ws).
  */
 export async function notify(target: NotificationTarget, options: NotificationOptions): Promise<NotificationRecord | null> {
   const provider = await resolveNotificationProvider();
@@ -65,6 +35,8 @@ export async function notify(target: NotificationTarget, options: NotificationOp
   }
 
   const normalizedTarget = normalizeTarget(target);
+
+  // 1. Save to Database via the Provider
   const normalized = await provider.create(normalizedTarget, {
     type: options.type,
     title: options.title,
@@ -73,62 +45,15 @@ export async function notify(target: NotificationTarget, options: NotificationOp
     data: options.data ?? null
   });
 
-  if (options.broadcast) {
-    await dispatchEvent("notification.created", normalized, {
-      broadcast: { users: [normalizedTarget.id] }
-    });
-  }
-
-  if (options.mail) {
-    await sendMailChannel(normalizedTarget, normalized, options);
-  }
+  // 2. Dispatch to all registered channels in parallel
+  const channels = getChannels();
+  await Promise.allSettled(
+    channels.map((channel) =>
+      channel.send(normalizedTarget, normalized, options).catch((err) => {
+        console.error(`[notification] Channel ${channel.name} failed:`, err);
+      })
+    )
+  );
 
   return normalized;
 }
-
-/** Deliver an email notification, either queued (if Redis is available) or direct. */
-async function sendMailChannel(
-  target: { type: string; id: number | string },
-  notification: NotificationRecord,
-  options: NotificationOptions
-) {
-  let to: string | null = 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;
-
-  const subject = options.mail?.subject || notification.title;
-  const html = options.mail?.html || defaultMailHtml(notification.title, notification.body);
-
-  if (redisClientIfReady()) {
-    await dispatchEvent(
-      "notification:mail",
-      {
-        to,
-        subject,
-        html
-      },
-      { queue: "mail" }
-    );
-  } else {
-    await mail.sendMail({ to, subject, html });
-  }
-}
-
-/** Generate a basic HTML email body from title and body text. */
-function defaultMailHtml(title: string, body: string | null) {
-  return `<h2>${escapeHtml(title)}</h2>${body ? `<p>${escapeHtml(body)}</p>` : ""}`;
-}
-
-function escapeHtml(str: string) {
-  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-}

package/hono/src/framework/notification/registry.ts

@@ -0,0 +1,15 @@
+import type { NotificationChannel } from "@/framework/notification/contracts.js";
+
+const channels = new Map<string, NotificationChannel>();
+
+export function registerChannel(channel: NotificationChannel) {
+  channels.set(channel.name, channel);
+}
+
+export function getChannels(): NotificationChannel[] {
+  return Array.from(channels.values());
+}
+
+export function clearChannels() {
+  channels.clear();
+}

package/hono/src/framework/providers/adapter.ts

@@ -18,6 +18,7 @@ async function loadDefaultProvider(): Promise<AuthProvider | null> {
   if (defaultProvider) return defaultProvider;
   if (defaultLoadAttempted) return null;
   defaultLoadAttempted = true;
+
   try {
     const userMod = await import("@/modules/auth/database/models/user.js").catch(() => null);
     if (!userMod?.users || !userMod?.refreshTokens) return null;
@@ -25,22 +26,28 @@ async function loadDefaultProvider(): Promise<AuthProvider | null> {
     const users = userMod.users;
     const refreshTokens = userMod.refreshTokens;
 
-    defaultProvider = {
-      async getUserById(id: number | string) {
-        try {
-          const user = await (db.query.users.findFirst as any)?.({
-            where: eq(users.id, id as any),
-            with: { role: true }
-          });
-          if (user) return user;
-        } catch {}
-        try {
-          const rows = await db.select().from(users).where(eq(users.id, id as any));
-          return rows?.[0] ?? null;
-        } catch {
-          return null;
-        }
-      },
+    // Define the core logic as standalone functions to avoid `this` context issues
+    const getUserById = async (id: number | string) => {
+      try {
+        const user = await (db.query.users.findFirst as any)?.({
+          where: eq(users.id, id as any),
+          with: { role: true }
+        });
+        if (user) return user;
+      } catch {}
+      try {
+        const rows = await db
+          .select()
+          .from(users)
+          .where(eq(users.id, id as any));
+        return rows?.[0] ?? null;
+      } catch {
+        return null;
+      }
+    };
+
+    const provider: AuthProvider = {
+      getUserById,
       async findRefreshToken(jti: string) {
         try {
           const token = await (db.query.refreshTokens.findFirst as any)?.({
@@ -89,7 +96,8 @@ async function loadDefaultProvider(): Promise<AuthProvider | null> {
       },
       async getUserContact(userId: number | string) {
         try {
-          const user = await this.getUserById(userId);
+          // Use the standalone function instead of `this.getUserById`
+          const user = await getUserById(userId);
           if (!user) return null;
           return {
             email: user.email ?? null,
@@ -101,6 +109,8 @@ async function loadDefaultProvider(): Promise<AuthProvider | null> {
         }
       }
     };
+
+    defaultProvider = provider;
     return defaultProvider;
   } catch {
     return null;