create-nexwire 4.0.0

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

@@ -0,0 +1,139 @@
+import { closeDatabase, initDatabase } from "@/framework/database/connection.js";
+import { discoverModuleFiles, importFile } from "@/framework/modules/discover.js";
+import { readFile } from "node:fs/promises";
+
+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) {
+    const source = await readFile(file, "utf8");
+    const isUnfilledStub = !/^\s*export\s/m.test(source);
+    const mod = await importFile(file);
+    if (typeof mod.default !== "function") {
+      if (isUnfilledStub) {
+        console.log(`Skipped unfilled seeder ${file} (no exports yet)`);
+        continue;
+      }
+      throw new Error(`Seeder file ${file} has no default export function`);
+    }
+    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);
+  }
+
+  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) {
+    await s.execute();
+  }
+
+  console.log(`Executed ${sorted.length} seeder file(s)${moduleName ? ` for module ${moduleName}` : ""}`);
+} finally {
+  await closeDatabase();
+}

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

@@ -0,0 +1,49 @@
+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"
+    });
+  }
+}

package/express/src/framework/facade.ts

@@ -0,0 +1,48 @@
+export * as lodash from "lodash-es";
+export { z } from "zod";
+export { registerOpenApiRoute } from "@/framework/http/openapi.js";
+export type { RouteConfig } from "@/framework/http/router.js";
+export { createRoute, createRouter, group, jsonContent } from "@/framework/http/router.js";
+export { validate } from "@/framework/http/validation.js";
+export const HttpStatusCodes = {
+  CONTINUE: 100,
+  SWITCHING_PROTOCOLS: 101,
+  OK: 200,
+  CREATED: 201,
+  ACCEPTED: 202,
+  NO_CONTENT: 204,
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  METHOD_NOT_ALLOWED: 405,
+  CONFLICT: 409,
+  GONE: 410,
+  PAYLOAD_TOO_LARGE: 413,
+  URI_TOO_LONG: 414,
+  UNSUPPORTED_MEDIA_TYPE: 415,
+  UNPROCESSABLE_ENTITY: 422,
+  TOO_MANY_REQUESTS: 429,
+  INTERNAL_SERVER_ERROR: 500,
+  BAD_GATEWAY: 502,
+  SERVICE_UNAVAILABLE: 503,
+  GATEWAY_TIMEOUT: 504
+} as const;
+export { cache } from "@/framework/cache/cache.js";
+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 { command, dispatchCommand, dispatchEvent } from "@/framework/events/dispatcher.js";
+export { notify } from "@/framework/notification/index.js";
+export { queue, queueJob, shouldQueue } from "@/framework/queue/queue.js";
+export { broadcast } from "@/framework/realtime/index.js";
+export { defineSchedule } from "@/framework/scheduler/scheduler.js";
+export { session } from "@/framework/session/session.js";
+export { storage } from "@/framework/storage/storage.js";
+export { cookie } from "@/framework/support/cookie.js";
+export { jwt } from "@/framework/support/jwt.js";
+export { logger } from "@/framework/support/logger.js";
+export { mail } from "@/framework/support/mail.js";
+export { password } from "@/framework/support/password.js";
+export { fields, upload } from "@/framework/support/upload.js";
+export { urls } from "@/framework/support/url.js";

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

@@ -0,0 +1,107 @@
+import cookieParser from "cookie-parser";
+import express from "express";
+import { z } from "zod";
+import { appConfig, cookieConfig, loggingConfig, redisConfig } from "@/config/index.js";
+import { database } from "@/framework/database/connection.js";
+import { corsMiddleware } from "@/framework/http/cors.js";
+import { loggerMiddleware } from "@/framework/http/logger.js";
+import { getMetrics, incrementRequestCount } from "@/framework/http/metrics.js";
+import { configureOpenApi, registerOpenApiRoute } from "@/framework/http/openapi.js";
+import { rateLimiterMiddleware } from "@/framework/http/ratelimiter.js";
+import { createRoute, jsonContent } from "@/framework/http/router.js";
+import { securityMiddleware } from "@/framework/http/security.js";
+import { hasUiBuild, storageStaticMiddleware } from "@/framework/http/static.js";
+import { redisClientIfReady } from "@/framework/redis/client.js";
+import { sessionMiddleware } from "@/framework/session/session.js";
+
+export function createHttpApp() {
+  const app = express();
+
+  app.disable("x-powered-by");
+  app.use(express.json());
+  app.use(express.urlencoded({ extended: true }));
+  app.use(cookieParser(cookieConfig.secret));
+  app.use(corsMiddleware);
+  app.use(sessionMiddleware);
+  app.use(securityMiddleware);
+
+  app.use((_req, _res, next) => {
+    incrementRequestCount();
+    next();
+  });
+
+  app.get("/ready", (_req, res) => {
+    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";
+    }
+    const status = allOk ? 200 : 503;
+    res.status(status).json({ status: allOk ? "ready" : "not_ready", checks });
+  });
+
+  app.get("/live", (_req, res) => {
+    res.json({ status: "alive" });
+  });
+
+  app.get("/metrics", (_req, res) => {
+    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");
+    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")
+        }
+      })
+    );
+  }
+
+  app.get("/health", (_req, res) => {
+    res.json({ message: "Application is healthy" });
+  });
+
+  if (!hasUiBuild()) {
+    app.get("/", (_req, res) => {
+      res.json({ name: appConfig.name, ok: true });
+    });
+  }
+
+  app.use("/storage", storageStaticMiddleware);
+
+  return app;
+}

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

@@ -0,0 +1,7 @@
+import cors from "cors";
+import { corsConfig } from "@/config/index.js";
+
+export const corsMiddleware = cors({
+  origin: corsConfig.origin === "*" ? true : corsConfig.origin,
+  credentials: corsConfig.origin === "*"
+});

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

@@ -0,0 +1,69 @@
+import type { ErrorRequestHandler, RequestHandler } from "express";
+import createError from "http-errors";
+import { logger } from "@/framework/support/logger.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 || "");
+}
+
+export const loggerMiddleware: RequestHandler = (req, res, next) => {
+  const startedAt = Date.now();
+  const requestId = crypto.randomUUID();
+
+  res.locals.requestId = requestId;
+  res.setHeader("X-Request-ID", requestId);
+
+  res.on("finish", () => {
+    const pathname = (req.url ?? "").split("?")[0];
+    if (pathname === "/health" || pathname.startsWith("/queues")) return;
+
+    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();
+};
+
+export const notFound: RequestHandler = (req, _res, next) => {
+  next(createError(404, `Route not found: ${req.method} ${req.originalUrl}`));
+};
+
+export const onError: ErrorRequestHandler = (error, _req, res, _next) => {
+  const status = typeof error?.status === "number" ? error.status : 500;
+
+  if (error?.success === false && error?.error?.issues) {
+    logger.warn("Request validation failed", {
+      status,
+      issues: error.error.issues
+    });
+    res.status(status).json({
+      success: false,
+      error: {
+        name: error.error.name ?? "ZodError",
+        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 } : {})
+  });
+};

package/express/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
+  };
+}

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

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import path from "node:path";
+import { extendZodWithOpenApi, OpenAPIRegistry, OpenApiGeneratorV3 } from "@asteasolutions/zod-to-openapi";
+import { apiReference } from "@scalar/express-api-reference";
+import type { Express } from "express";
+import { z } from "zod";
+import { openApiConfig } from "@/config/index.js";
+import type { RouteConfig } from "@/framework/http/router.js";
+
+extendZodWithOpenApi(z);
+
+const registry = new OpenAPIRegistry();
+
+export function registerOpenApiRoute(route: RouteConfig) {
+  registry.registerPath(route as any);
+}
+
+export function createOpenApiDocument() {
+  const generator = new OpenApiGeneratorV3(registry.definitions);
+  return generator.generateDocument({
+    openapi: openApiConfig.version,
+    info: {
+      title: openApiConfig.title,
+      version: openApiConfig.apiVersion,
+      ...(openApiConfig.description ? { description: openApiConfig.description } : {})
+    }
+  });
+}
+
+export function configureOpenApi(app: Express) {
+  app.get(openApiConfig.scalar.specUrl, (_req, res) => {
+    res.json(createOpenApiDocument());
+  });
+
+  if (openApiConfig.scalar.favicon) {
+    app.get("/favicon.ico", (_req, res) => {
+      const faviconPath = path.join(process.cwd(), openApiConfig.scalar.favicon);
+      if (!fs.existsSync(faviconPath)) return res.status(404).end();
+      res.type("image/x-icon").sendFile(faviconPath);
+    });
+  }
+
+  app.get(
+    openApiConfig.scalar.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)
+  );
+}

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

@@ -0,0 +1,16 @@
+import { rateLimit } from "express-rate-limit";
+import { rateLimitConfig } from "@/config/index.js";
+
+export const rateLimiterMiddleware = rateLimit({
+  windowMs: rateLimitConfig.windowMs,
+  limit: rateLimitConfig.maxRequests,
+  standardHeaders: "draft-7",
+  legacyHeaders: true
+});
+
+export const loginLimiter = rateLimit({
+  windowMs: rateLimitConfig.windowMs,
+  limit: rateLimitConfig.loginMaxRequests,
+  standardHeaders: "draft-7",
+  legacyHeaders: true
+});

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

@@ -0,0 +1,178 @@
+import type { Router as ExpressRouter, RequestHandler } from "express";
+import express from "express";
+import type { z } from "zod";
+import { registerOpenApiRoute } from "@/framework/http/openapi.js";
+import { validate } from "@/framework/http/validation.js";
+
+export type HttpMethod = "get" | "post" | "put" | "patch" | "delete" | "options" | "head" | "trace";
+
+export type RouteConfig = {
+  path: string;
+  method: HttpMethod;
+  tags?: string[];
+  summary?: string;
+  description?: string;
+  request?: {
+    params?: z.ZodTypeAny;
+    query?: z.ZodTypeAny;
+    headers?: z.ZodTypeAny;
+    cookies?: z.ZodTypeAny;
+    body?: { content: { "application/json": { schema: z.ZodTypeAny } }; description?: string };
+  };
+  responses: Record<number | string, { description?: string; content?: { "application/json": { schema: z.ZodTypeAny } } }>;
+};
+
+export type NexwireRouter = Omit<ExpressRouter, "route"> & {
+  group: (...middlewares: RequestHandler[]) => NexwireRouter;
+  api: (route: RouteConfig, handlerOrMiddlewares: RequestHandler[] | RequestHandler, handler?: RequestHandler) => NexwireRouter;
+  route: {
+    (prefix: string, child: NexwireRouter): NexwireRouter;
+    (prefix: string): any;
+  };
+};
+
+export function createRoute<T extends RouteConfig>(config: T): T {
+  return config;
+}
+
+export const jsonContent = <T extends z.ZodTypeAny>(schema: T, description: string) => ({
+  content: {
+    "application/json": {
+      schema
+    }
+  },
+  description
+});
+
+type RouterState = {
+  routes: RouteConfig[];
+  children: Array<{ prefix: string; router: NexwireRouter }>;
+};
+
+const states = new WeakMap<object, RouterState>();
+
+function stateOf(router: object) {
+  let state = states.get(router);
+  if (!state) {
+    state = { routes: [], children: [] };
+    states.set(router, state);
+  }
+  return state;
+}
+
+function joinPaths(prefix: string, path: string) {
+  if (!prefix || prefix === "/") return path || "/";
+  if (!path || path === "/") return prefix;
+  return `${prefix.replace(/\/$/, "")}/${path.replace(/^\//, "")}`;
+}
+
+function expressPath(path: string) {
+  return path
+    .replace(/\{\*([^}]+)\}/g, "/*$1")
+    .replace(/\{([^}]+)\}/g, ":$1")
+    .replace(/\/{2,}/g, "/");
+}
+
+function setRequestPart(target: any, key: string, value: unknown) {
+  Object.defineProperty(target, key, {
+    value,
+    writable: true,
+    configurable: true,
+    enumerable: true
+  });
+}
+
+function validationMiddleware(route: RouteConfig): RequestHandler {
+  return async (req, _res, next) => {
+    try {
+      if (req.params) {
+        for (const key of Object.keys(req.params)) {
+          if (Array.isArray(req.params[key])) {
+            req.params[key] = (req.params[key] as string[]).join('/');
+          }
+        }
+      }
+      if (route.request?.params) {
+        setRequestPart(req, "params", await validate(route.request.params, req.params));
+      }
+      if (route.request?.query) {
+        setRequestPart(req, "query", await validate(route.request.query, req.query));
+      }
+      if (route.request?.headers) {
+        await validate(route.request.headers, req.headers);
+      }
+      if (route.request?.cookies) {
+        await validate(route.request.cookies, req.cookies);
+      }
+      if (route.request?.body) {
+        const bodySchema = route.request.body.content?.["application/json"]?.schema;
+        if (bodySchema) {
+          setRequestPart(req, "body", await validate(bodySchema, req.body));
+        }
+      }
+      next();
+    } catch (error) {
+      next(error);
+    }
+  };
+}
+
+function collectRoutes(router: object, prefix = ""): RouteConfig[] {
+  const state = states.get(router);
+  if (!state) return [];
+
+  const routes: RouteConfig[] = [];
+  for (const child of state.children) {
+    routes.push(...collectRoutes(child.router, joinPaths(prefix, child.prefix)));
+  }
+  for (const route of state.routes) {
+    routes.push({ ...route, path: joinPaths(prefix, route.path) });
+  }
+  return routes;
+}
+
+export function registerRouterOpenApi(router: object, prefix = "") {
+  for (const route of collectRoutes(router, prefix)) {
+    registerOpenApiRoute(route);
+  }
+}
+
+export function createRouter(): NexwireRouter {
+  const router = express.Router() as unknown as NexwireRouter;
+  const nativeRoute = router.route.bind(router);
+  states.set(router, { routes: [], children: [] });
+
+  router.group = function (...middlewares: RequestHandler[]) {
+    if (middlewares.length) router.use(...middlewares);
+    return this;
+  };
+
+  router.api = function (route: RouteConfig, handlerOrMiddlewares: RequestHandler[] | RequestHandler, handler?: RequestHandler) {
+    const middlewares = Array.isArray(handlerOrMiddlewares) ? handlerOrMiddlewares : [];
+    const finalHandler = Array.isArray(handlerOrMiddlewares) ? handler : handlerOrMiddlewares;
+
+    if (typeof finalHandler !== "function") {
+      throw new Error("api(route, middlewares, handler) requires a handler function");
+    }
+
+    (router as any)[route.method](expressPath(route.path), validationMiddleware(route), ...middlewares, finalHandler);
+    stateOf(router).routes.push(route);
+    return this;
+  };
+
+  router.route = function (prefix: string, child?: NexwireRouter) {
+    if (child === undefined) {
+      return nativeRoute(prefix) as any;
+    }
+
+    router.use(prefix, child as any);
+    stateOf(router).children.push({ prefix, router: child });
+    return this;
+  };
+
+  return router;
+}
+
+export function group(...middlewares: RequestHandler[]) {
+  return createRouter().group(...middlewares);
+}