create-nexwire 4.3.0 → 4.4.0

package/fastify/src/framework/database/seed.ts

@@ -0,0 +1,152 @@
+import { readFile } from "node:fs/promises";
+import { closeDatabase, initDatabase } from "@/framework/database/connection.js";
+import { discoverModuleFiles, importFile } from "@/framework/modules/discover.js";
+
+const NAME_SYMBOL = Symbol.for("drizzle:Name");
+const FK_SYMBOLS = [
+  Symbol.for("drizzle:PgInlineForeignKeys"),
+  Symbol.for("drizzle:MySqlInlineForeignKeys"),
+  Symbol.for("drizzle:SQLiteInlineForeignKeys")
+];
+
+interface SeederEntry {
+  file: string;
+  name: string;
+  execute: () => Promise<void>;
+  tableName?: string;
+  dependsOn: string[];
+}
+
+function getTableDeps(table: any): string[] {
+  for (const sym of FK_SYMBOLS) {
+    const fks = table[sym] as any[] | undefined;
+    if (!fks || fks.length === 0) continue;
+    const deps: string[] = [];
+    for (const fk of fks) {
+      const ref = fk.reference();
+      if (ref?.foreignTable) {
+        const name = ref.foreignTable[NAME_SYMBOL] as string;
+        if (name && !deps.includes(name)) deps.push(name);
+      }
+    }
+    return deps;
+  }
+  return [];
+}
+
+await initDatabase();
+
+try {
+  const moduleArg = process.argv.find((arg) => arg.startsWith("--module="));
+  const moduleName = moduleArg?.split("=")[1]?.trim();
+  const pattern = moduleName ? `${moduleName}/database/seeders/*.{ts,js}` : "**/database/seeders/*.{ts,js}";
+
+  const files = await discoverModuleFiles(pattern);
+  const seeders: SeederEntry[] = [];
+
+  for (const file of files) {
+    try {
+      const source = await readFile(file, "utf8");
+      const isUnfilledStub = !/^\s*export\s/m.test(source);
+      const mod = await importFile(file).catch((err: any) => {
+        console.warn(`[seed:skip] ${file}: ${err?.message || err}`);
+        return null as any;
+      });
+      if (!mod) continue;
+      if (typeof mod.default !== "function") {
+        if (isUnfilledStub) {
+          console.log(`Skipped unfilled seeder ${file} (no exports yet)`);
+          continue;
+        }
+        console.warn(`[seed:skip] ${file}: has no default export function`);
+        continue;
+      }
+      const table: any = mod.table;
+      const entry: SeederEntry = {
+        file,
+        name: file
+          .split(/[\\/]/)
+          .pop()!
+          .replace(/\.(ts|js)$/, ""),
+        execute: () => mod.default(),
+        dependsOn: table ? getTableDeps(table) : []
+      };
+      if (table) {
+        entry.tableName = table[NAME_SYMBOL] as string;
+      }
+      seeders.push(entry);
+    } catch (err: any) {
+      console.warn(`[seed:skip] ${file}: ${err?.message || err}`);
+    }
+  }
+
+  const tableToSeeder = new Map<string, SeederEntry>();
+  for (const s of seeders) {
+    if (s.tableName) tableToSeeder.set(s.tableName, s);
+  }
+
+  const seederByName = new Map<string, SeederEntry>();
+  for (const s of seeders) {
+    seederByName.set(s.name, s);
+  }
+
+  const resolvedDeps = new Map<SeederEntry, SeederEntry[]>();
+  for (const s of seeders) {
+    const deps: SeederEntry[] = [];
+    for (const tableDep of s.dependsOn) {
+      const depSeeder = tableToSeeder.get(tableDep);
+      if (depSeeder && depSeeder !== s) {
+        deps.push(depSeeder);
+      }
+    }
+    resolvedDeps.set(s, deps);
+  }
+
+  const inDegree = new Map<SeederEntry, number>();
+  const adj = new Map<SeederEntry, SeederEntry[]>();
+  for (const s of seeders) {
+    inDegree.set(s, 0);
+    adj.set(s, []);
+  }
+  for (const s of seeders) {
+    for (const dep of resolvedDeps.get(s)!) {
+      adj.get(dep)!.push(s);
+      inDegree.set(s, inDegree.get(s)! + 1);
+    }
+  }
+
+  const queue: SeederEntry[] = [];
+  for (const [s, deg] of inDegree) {
+    if (deg === 0) queue.push(s);
+  }
+
+  const sorted: SeederEntry[] = [];
+  while (queue.length > 0) {
+    const s = queue.shift()!;
+    sorted.push(s);
+    for (const next of adj.get(s)!) {
+      const newDeg = inDegree.get(next)! - 1;
+      inDegree.set(next, newDeg);
+      if (newDeg === 0) queue.push(next);
+    }
+  }
+
+  if (sorted.length !== seeders.length) {
+    const seeded = new Set(sorted.map((s) => s.name));
+    const missing = seeders.filter((s) => !seeded.has(s.name)).map((s) => s.name);
+    console.error(`Circular dependency detected among seeders: ${missing.join(", ")}`);
+    process.exit(1);
+  }
+
+  for (const s of sorted) {
+    try {
+      await s.execute();
+    } catch (err: any) {
+      console.warn(`[seed:skip] ${s.name} failed: ${err?.message || err}`);
+    }
+  }
+
+  console.log(`Executed ${sorted.length} seeder file(s)${moduleName ? ` for module ${moduleName}` : ""}`);
+} finally {
+  await closeDatabase();
+}

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

@@ -0,0 +1,61 @@
+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/fastify/src/framework/facade.ts

@@ -0,0 +1,96 @@
+/**
+ * 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, 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 { ValidationErrorSchema, 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,
+  AuthProviderUser,
+  AuthUserContact,
+  AuthUserContext,
+  NotifiableTarget,
+  NotificationCreateInput,
+  NotificationListOptions,
+  NotificationPage,
+  NotificationProvider,
+  NotificationRecord
+} from "@/framework/providers/contracts.js";
+export { loadProviders } from "@/framework/providers/loader.js";
+export {
+  clearAuthProvider,
+  clearNotificationProvider,
+  clearProvider,
+  getAuthProvider,
+  getNotificationProvider,
+  getProvider,
+  hasAuthProvider,
+  hasNotificationProvider,
+  hasProvider,
+  listProviders,
+  registerAuthProvider,
+  registerNotificationProvider,
+  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";
+export * as HttpStatusCodes from "@/framework/support/status-codes.js";
+export { fields, upload } from "@/framework/support/upload.js";
+export { urls } from "@/framework/support/url.js";

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

@@ -0,0 +1,176 @@
+import cookie from "@fastify/cookie";
+import cors from "@fastify/cors";
+import rateLimit from "@fastify/rate-limit";
+import Fastify from "fastify";
+import fastifyPlugin from "fastify-plugin";
+import { serializerCompiler, validatorCompiler, type ZodTypeProvider } from "fastify-type-provider-zod";
+import { z } from "zod";
+import { appConfig, cookieConfig, loggingConfig, rateLimitConfig, redisConfig } from "@/config/index.js";
+import { database } from "@/framework/database/connection.js";
+import { corsOrigins } from "@/framework/http/cors.js";
+import { registerErrorHandler, registerRequestLogger } from "@/framework/http/logger.js";
+import { getMetrics, incrementRequestCount } from "@/framework/http/metrics.js";
+import { configureOpenApi } from "@/framework/http/openapi.js";
+import { registerRateLimit } from "@/framework/http/ratelimiter.js";
+import { securityHook } from "@/framework/http/security.js";
+import { hasUiBuild, registerStatic } from "@/framework/http/static.js";
+import { redisClientIfReady } from "@/framework/redis/client.js";
+import { sessionMiddleware } from "@/framework/session/session.js";
+
+const HealthSchema = z.object({
+  message: z.string()
+});
+
+const ReadySchema = z.object({
+  status: z.enum(["ready", "not_ready"]),
+  checks: z.record(z.string(), z.string())
+});
+
+const RootSchema = z.object({
+  name: z.string(),
+  ok: z.boolean()
+});
+
+/**
+ * Why: Wraps the request lifecycle hooks in one plugin so they load after the
+ *      cookie/cors/rate-limit plugins. fastify-plugin breaks encapsulation, so
+ *      the hooks and request decorators still reach every route on the root.
+ * When: App boot, before route registration.
+ * Where: HTTP app setup.
+ * How: Session first (needs parsed cookies), then security, metrics, logging.
+ */
+const infrastructure = fastifyPlugin(async (app) => {
+  app.decorateRequest("auth", null);
+  app.decorateRequest("sessionId", null);
+
+  app.addHook("onRequest", sessionMiddleware);
+  app.addHook("onRequest", securityHook);
+  app.addHook("onRequest", async () => {
+    incrementRequestCount();
+  });
+
+  if (loggingConfig.httpRequests) {
+    registerRequestLogger(app);
+  }
+});
+
+/**
+ * Why: Builds the main HTTP app with plugins, health, and fallbacks.
+ * When: Kernel creates the application server instance.
+ * Where: Framework bootstrap path.
+ * How: Native Fastify plugins and hooks; no Express/Hono compatibility layer.
+ */
+export function createHttpApp() {
+  const app = Fastify({
+    logger: false,
+    // Match Hono and Express: a UUID per request instead of Fastify's `req-1`
+    // counter, so request ids are comparable across engines and log sinks.
+    genReqId: () => crypto.randomUUID()
+  }).withTypeProvider<ZodTypeProvider>();
+
+  app.setValidatorCompiler(validatorCompiler);
+  app.setSerializerCompiler(serializerCompiler);
+
+  // Error handling must exist before child route scopes are created, otherwise
+  // those scopes inherit Fastify's default handler and return 400 for Zod errors.
+  registerErrorHandler(app);
+
+  app.register(cookie, { secret: cookieConfig.secret });
+  app.register(cors, { origin: corsOrigins, credentials: true });
+  registerRateLimit(app);
+
+  app.register(infrastructure);
+
+  if (appConfig.openApiEnabled) {
+    configureOpenApi(app);
+  }
+
+  app.get(
+    "/health",
+    {
+      schema: {
+        tags: ["System"],
+        description: "Application health status",
+        response: { 200: HealthSchema }
+      }
+    },
+    async () => ({ message: "Application is healthy" })
+  );
+
+  app.get(
+    "/ready",
+    {
+      schema: {
+        tags: ["System"],
+        description: "Readiness probe",
+        response: { 200: ReadySchema, 503: ReadySchema }
+      }
+    },
+    async (_request, reply) => {
+      const checks: Record<string, string> = {};
+      let allOk = true;
+      try {
+        database();
+        checks.database = "ok";
+      } catch {
+        checks.database = "error";
+        allOk = false;
+      }
+      if (redisConfig.enabled) {
+        if (redisClientIfReady()) {
+          checks.redis = "ok";
+        } else {
+          checks.redis = "error";
+          allOk = false;
+        }
+      } else {
+        checks.redis = "disabled";
+      }
+      reply.code(allOk ? 200 : 503);
+      return { status: allOk ? "ready" : "not_ready", checks } as const;
+    }
+  );
+
+  app.get(
+    "/live",
+    {
+      schema: {
+        tags: ["System"],
+        description: "Liveness probe",
+        response: { 200: z.object({ status: z.literal("alive") }) }
+      }
+    },
+    async () => ({ status: "alive" as const })
+  );
+
+  app.get("/metrics", async (_request, reply) => {
+    const m = getMetrics();
+    const output = [
+      "# HELP http_requests_total Total HTTP requests",
+      "# TYPE http_requests_total counter",
+      `http_requests_total ${m.requestCount}`,
+      "# HELP http_errors_total Total HTTP errors",
+      "# TYPE http_errors_total counter",
+      `http_errors_total ${m.errorCount}`
+    ].join("\n");
+    reply.type("text/plain").send(output);
+  });
+
+  if (!hasUiBuild()) {
+    app.get(
+      "/",
+      {
+        schema: {
+          tags: ["System"],
+          description: "API identity",
+          response: { 200: RootSchema }
+        }
+      },
+      async () => ({ name: appConfig.name, ok: true })
+    );
+  }
+
+  registerStatic(app);
+
+  return app;
+}

package/fastify/src/framework/http/cors.ts

@@ -0,0 +1,13 @@
+import { corsConfig } from "@/config/index.js";
+import { parseCsvOrFallback } from "@/framework/support/lifecycle.js";
+
+const allowed = parseCsvOrFallback(corsConfig.origin, []);
+
+/**
+ * Why: Applies credential-aware CORS policy.
+ * When: Global HTTP request processing.
+ * Where: App plugin stack.
+ * How: `true` reflects the request origin in wildcard mode; otherwise only
+ *      origins from the configured allowlist receive CORS headers.
+ */
+export const corsOrigins = corsConfig.origin === "*" ? true : allowed;

package/fastify/src/framework/http/fastify.d.ts

@@ -0,0 +1,13 @@
+import "fastify";
+import type { UploadedFile } from "@/framework/support/upload.js";
+
+declare module "fastify" {
+  interface FastifyRequest {
+    auth: any;
+    sessionId: string | null;
+    /** Single-file upload, populated by `upload({ field })`. */
+    upload?: UploadedFile;
+    /** Multiple uploads or labeled fields, populated by `upload`/`fields`. */
+    uploads?: UploadedFile[] | Record<string, UploadedFile[]>;
+  }
+}

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

@@ -0,0 +1,110 @@
+import type { FastifyError, FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+import { hasZodFastifySchemaValidationErrors, isResponseSerializationError } from "fastify-type-provider-zod";
+import { openApiConfig } from "@/config/index.js";
+import { logger } from "@/framework/support/logger.js";
+
+function requestIp(request: FastifyRequest) {
+  const forwarded = request.headers["x-forwarded-for"];
+  return String(request.headers["cf-connecting-ip"] || forwarded || request.headers["x-real-ip"] || request.ip || "");
+}
+
+// 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") ||
+    pathname === "/favicon.ico" ||
+    pathname === openApiConfig.scalar.specUrl ||
+    pathname === openApiConfig.scalar.docsPath ||
+    pathname.startsWith(`${openApiConfig.scalar.docsPath}/`)
+  );
+}
+
+/**
+ * Why: Logs each HTTP request with latency and request metadata.
+ * When: Applied globally to app routes.
+ * Where: HTTP request lifecycle.
+ * How: An onResponse hook reads Fastify's built-in elapsed time, so no
+ *      per-request start timestamp has to be stored.
+ */
+export function registerRequestLogger(app: FastifyInstance) {
+  app.addHook("onRequest", async (request, reply) => {
+    reply.header("X-Request-ID", request.id);
+  });
+
+  app.addHook("onResponse", async (request, reply) => {
+    const pathname = (request.url || "").split("?")[0];
+    if (shouldSkipHttpLog(pathname)) return;
+
+    logger.info("HTTP Request", {
+      requestId: request.id,
+      method: request.method,
+      path: pathname,
+      url: request.url,
+      status: reply.statusCode,
+      duration_ms: Math.round(reply.elapsedTime),
+      ip: requestIp(request),
+      userAgent: request.headers["user-agent"] || null
+    });
+  });
+}
+
+function zodIssues(error: FastifyError) {
+  return (error.validation ?? []).map((issue) => ({
+    path: issue.instancePath.split("/").filter(Boolean),
+    message: issue.message,
+    code: issue.keyword
+  }));
+}
+
+/**
+ * Why: Normalizes every error into the same JSON contract as Hono and Express.
+ * When: Any route or hook throws.
+ * Where: App error boundary.
+ * How: Zod failures become 422 with `{ success:false, error:{ name, issues } }`;
+ *      response serialization failures stay 500; everything else uses statusCode.
+ */
+export function registerErrorHandler(app: FastifyInstance) {
+  app.setErrorHandler((error: FastifyError, request: FastifyRequest, reply: FastifyReply) => {
+    if (hasZodFastifySchemaValidationErrors(error)) {
+      const issues = zodIssues(error);
+      logger.warn("Request validation failed", { status: 422, issues });
+      return reply.code(422).send({
+        success: false,
+        error: { name: "ZodError", issues }
+      });
+    }
+
+    if (isResponseSerializationError(error)) {
+      request.log.error({ err: error }, "Response serialization failed");
+      logger.error("Response serialization failed", { err: error });
+      return reply.code(500).send({ message: "Internal server error" });
+    }
+
+    const status =
+      typeof error.statusCode === "number" ? error.statusCode : typeof (error as any).status === "number" ? (error as any).status : 500;
+
+    const applicationError = error as any;
+    if (applicationError.success === false && applicationError.error?.issues) {
+      logger.warn("Request validation failed", { status, issues: applicationError.error.issues });
+      return reply.code(status).send({
+        success: false,
+        error: {
+          name: applicationError.error.name ?? "ZodError",
+          issues: applicationError.error.issues
+        }
+      });
+    }
+
+    const message = status === 500 ? "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 });
+
+    return reply.code(status).send({ message, ...(stack ? { stack } : {}) });
+  });
+}

package/fastify/src/framework/http/metrics.ts

@@ -0,0 +1,22 @@
+let requestCount = 0;
+let errorCount = 0;
+
+export function incrementRequestCount() {
+  requestCount++;
+}
+
+export function incrementErrorCount() {
+  errorCount++;
+}
+
+export function resetMetrics() {
+  requestCount = 0;
+  errorCount = 0;
+}
+
+export function getMetrics() {
+  return {
+    requestCount,
+    errorCount
+  };
+}