create-nexwire 4.0.0 → 4.1.0

package/README.md

@@ -7,8 +7,9 @@
 <h3 align="center">Stop wiring the stack together. Ship the app.</h3>
 
 <p align="center">
-  <a href="https://niyamulahsan.github.io/nexwire"><img src="https://img.shields.io/badge/docs-3b8eed" alt="Documentation"></a>
+  <a href="https://niyamulahsan.github.io/nexwire"><img src="https://img.shields.io/badge/docs%20%7C%20nexwire-3b8eed" alt="Documentation"></a>
   <a href="https://www.npmjs.com/package/create-nexwire"><img src="https://img.shields.io/npm/v/create-nexwire" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/create-nexwire"><img src="https://img.shields.io/npm/dt/create-nexwire" alt="npm downloads"></a>
   <a href="https://github.com/niyamulahsan/nexwire/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License"></a>
 </p>
 
@@ -48,7 +49,7 @@ Your API is live at `http://localhost:3000`, Scalar docs at `/api-docs`, and the
 
 The scaffold already ships a pre-migrated, pre-seeded SQLite database, so there is no migration step before `maker dev`. If you point `DATABASE_URL` at MySQL or PostgreSQL, run `npm run maker db:migrate -- --seed` once to build and populate that database instead.
 
-Requires **Node.js >= 22.12** or **Bun >= 1.3**.
+Requires **Node.js >= 22** or **Bun >= 1.3**.
 
 ### Current directory
 
@@ -79,7 +80,7 @@ nexwire runs on **Node.js** or **Bun** — pick whichever fits your deployment:
 
 | Runtime     | Minimum version | Notes                                                                 |
 | ----------- | --------------- | --------------------------------------------------------------------- |
-| **Node.js** | `>= 22.12`      | Default. Uses `node` in Dockerfile.                                   |
+| **Node.js** | `>= 22`         | Default. Uses `node` in Dockerfile.                                   |
 | **Bun**     | `>= 1.3`        | Pass `--runtime=bun` to `deploy:init`. Uses `oven/bun` in Dockerfile. |
 
 ## Demo
@@ -92,7 +93,7 @@ Real recordings from a freshly scaffolded project — no mockups, no staging dat
   <img src="https://raw.githubusercontent.com/niyamulahsan/nexwire/main/packages/docs/public/screenshots/dev-mode.gif" alt="nexwire dev mode: API, UI, API docs, queue dashboard and mail UI booting in one command" width="100%">
 </p>
 
-**Real deploy** — the same project running on a live server, with HTTPS, process supervision and zero-downtime restarts:
+**Real deploy** — the same framework running on a live server as a real project, with HTTPS, process supervision, and zero-downtime restarts:
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/niyamulahsan/nexwire/main/packages/docs/public/screenshots/real-deploy.gif" alt="nexwire deployed to a real server with HTTPS and process supervision" width="100%">

package/express/.env

@@ -26,7 +26,7 @@ MAIL_PASSWORD=
 
 # ── Redis ──────────────────────────────────────────
 # Set true to enable cache, session, queue, events, and Queue Dashboard
-REDIS=false
+REDIS=true
 # Shared key prefix for cache, session, queue, events, and dashboards
 REDIS_URL=redis://127.0.0.1:6379
 REDIS_PREFIX=nexwire

package/express/README.md

@@ -7,7 +7,7 @@
 <h3 align="center">Full-stack TypeScript framework for modern web applications</h3>
 
 <p align="center">
-  <a href="https://niyamulahsan.github.io/nexwire"><img src="https://img.shields.io/badge/docs-3b8eed" alt="Documentation"></a>
+  <a href="https://niyamulahsan.github.io/nexwire"><img src="https://img.shields.io/badge/docs%20%7C%20nexwire-3b8eed" alt="Documentation"></a>
   <a href="https://www.npmjs.com/package/create-nexwire"><img src="https://img.shields.io/npm/v/create-nexwire" alt="npm version"></a>
   <a href="https://www.npmjs.com/package/create-nexwire"><img src="https://img.shields.io/npm/dt/create-nexwire" alt="npm downloads"></a>
   <a href="https://github.com/niyamulahsan/nexwire/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License"></a>
@@ -59,8 +59,8 @@ Works with any package manager: `pnpm`, `yarn`, or `bun`.
 
 All examples use `npm` as the default. nexwire works with any major package manager:
 
-| Manager  | Create project                     | Run commands          |
-| -------- | ---------------------------------- | --------------------- |
+| Manager  | Create project                      | Run commands          |
+| -------- | ----------------------------------- | --------------------- |
 | **npm**  | `npm create nexwire@latest my-app`  | `npm run maker <cmd>` |
 | **pnpm** | `pnpm create nexwire@latest my-app` | `pnpm maker <cmd>`    |
 | **yarn** | `yarn create nexwire@latest my-app` | `yarn maker <cmd>`    |
@@ -73,7 +73,7 @@ nexwire runs on **Node.js** or **Bun** — pick whichever fits your deployment:
 
 | Runtime     | Minimum version | Notes                                                                 |
 | ----------- | --------------- | --------------------------------------------------------------------- |
-| **Node.js** | `>= 22.12`     | Default. Uses `node` in Dockerfile.                                   |
+| **Node.js** | `>= 22.12`      | Default. Uses `node` in Dockerfile.                                   |
 | **Bun**     | `>= 1.3`        | Pass `--runtime=bun` to `deploy:init`. Uses `oven/bun` in Dockerfile. |
 
 ## Features
@@ -114,14 +114,20 @@ Every feature is a self-contained module under `src/modules/<name>/`:
 
 ```
 src/modules/posts/
+├── __tests__/         # Unit tests
 ├── console/           # CLI commands & scheduled tasks
-├── controllers/       # Request handlers + Zod schemas
+├── controllers/       # Request handlers
 ├── database/
 │   ├── models/        # Drizzle table definitions
-│   └── seeders/       # Test data generators
+│   └── seeders/       # Test data
+├── helpers/           # Pure functions — no I/O
 ├── jobs/              # BullMQ queue handlers
+├── middlewares/       # Module-local middleware
 ├── routes/            # HTTP route definitions (auto-discovered)
-└── __test__/          # Unit test
+├── schemas/           # Zod validation schemas
+├── services/          # Business logic — DB, files, network
+├── types/             # Shared TypeScript types
+└── facade.ts          # Public API for other modules
 ```
 
 Modules are **auto-discovered** — no manual registration. Create one with:

package/express/package.json

@@ -100,9 +100,9 @@
     "vitest": "^4.1.10"
   },
   "engines": {
-    "node": ">=22.12.0",
+    "node": ">=22",
     "bun": ">=1.3",
     "pnpm": ">=11",
     "yarn": ">=4"
   }
-}
+}

package/express/src/config/session.ts

@@ -1,4 +1,4 @@
-import { cookieConfig } from "./index.js";
+import { cookieConfig } from "./cookie.js";
 import { redisConfig } from "./redis.js";
 
 /**

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

@@ -1,7 +1,7 @@
 {
   "version": "6",
   "dialect": "sqlite",
-  "id": "e998e08f-4fb2-46ee-baa2-e2480d4b685a",
+  "id": "54057efa-2d33-41f3-aa7a-1f1a3e89a382",
   "prevId": "00000000-0000-0000-0000-000000000000",
   "tables": {
     "notifications": {

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

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

package/express/src/database/schema.ts

@@ -1,3 +1,3 @@
-export * from "../modules/auth/database/models/notifications.js";
-export * from "../modules/auth/database/models/role.js";
-export * from "../modules/auth/database/models/user.js";
+export * from "../modules/auth/database/models/notification.js";
+export * from "../modules/auth/database/models/role.js";
+export * from "../modules/auth/database/models/user.js";

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

@@ -1,81 +1,82 @@
-import { cacheConfig, redisConfig } from "@/config/index.js";
-import { redisClientIfReady } from "@/framework/redis/client.js";
-
-function cacheKey(key: string) {
-  return `${cacheConfig.keyPrefix}:${key}`;
-}
-
-/**
- * Why: Provides Redis-backed cache helpers with graceful fallback behavior.
- * When: Controllers/jobs need temporary computed data caching.
- * Where: Application module code via facade.
- * How: Uses namespaced Redis keys and JSON serialization.
- */
-export const cache = {
-  /**
-   * Why: Reads cached JSON value by key.
-   * When: A feature wants fast lookup before recomputing.
-   * Where: Controllers/jobs/services using shared cache.
-   * How: Fetches namespaced Redis key and parses JSON.
-   */
-  async get<T>(key: string, fallback: T | null = null) {
-    const client = redisClientIfReady();
-    if (!client) return fallback;
-
-    const value = await client.get(cacheKey(key));
-    return value ? (JSON.parse(value) as T) : fallback;
-  },
-
-  /**
-   * Why: Stores value in cache with TTL.
-   * When: Data should be reused for a limited period.
-   * Where: Application code caching expensive results.
-   * How: Serializes value and writes with Redis EX seconds.
-   */
-  async put(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;
-  },
-
-  /**
-   * Why: Deletes a cached value by key.
-   * When: Cached data becomes stale or must be invalidated.
-   * Where: Write/update flows that change source data.
-   * How: Removes namespaced Redis cache key.
-   */
-  async forget(key: string) {
-    const client = redisClientIfReady();
-    if (!client) return false;
-
-    await client.del(cacheKey(key));
-    return true;
-  },
-
-  /**
-   * Why: Returns cached value or computes/stores a fresh one.
-   * When: A feature needs cache-aside behavior.
-   * Where: Read paths with potentially expensive callbacks.
-   * How: Attempts get first, then executes callback and put.
-   */
-  async remember<T>(key: string, ttl: number, callback: () => Promise<T>) {
-    const cached = await cache.get<T>(key);
-    if (cached !== null) return cached;
-
-    const fresh = await callback();
-    await this.put(key, fresh, ttl);
-    return fresh;
-  },
-
-  /**
-   * Why: Indicates whether Redis cache backend is currently usable.
-   * When: Runtime checks need to branch on cache availability.
-   * Where: Health/status endpoints and conditional flows.
-   * How: Confirms REDIS flag and ready Redis client instance.
-   */
-  isAvailable() {
-    return redisConfig.enabled && redisClientIfReady() !== null;
-  }
-};
+import { cacheConfig, redisConfig } from "@/config/index.js";
+import { redisClientIfReady } from "@/framework/redis/client.js";
+
+function cacheKey(key: string) {
+  return `${cacheConfig.keyPrefix}:${key}`;
+}
+
+/**
+ * Why: Provides Redis-backed cache helpers with graceful fallback behavior.
+ * When: Controllers/jobs need temporary computed data caching.
+ * Where: Application module code via facade.
+ * How: Uses namespaced Redis keys and JSON serialization.
+ */
+export const cache = {
+  /**
+   * Why: Reads cached JSON value by key.
+   * When: A feature wants fast lookup before recomputing.
+   * Where: Controllers/jobs/services using shared cache.
+   * How: Fetches namespaced Redis key and parses JSON.
+   */
+  async get<T>(key: string, fallback: T | null = null) {
+    const client = redisClientIfReady();
+    if (!client) return fallback;
+
+    const value = await client.get(cacheKey(key));
+    return value ? (JSON.parse(value) as T) : 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;
+  },
+
+  /**
+   * @deprecated Use set() instead.
+   */
+  async put(key: string, value: unknown, ttl = cacheConfig.ttlSeconds) {
+    return this.set(key, value, ttl);
+  },
+
+  /**
+   * Why: Deletes a cached value by key.
+   * When: Cached data becomes stale or must be invalidated.
+   * Where: Write/update flows that change source data.
+   * How: Removes namespaced Redis cache key.
+   */
+  async forget(key: string) {
+    const client = redisClientIfReady();
+    if (!client) return false;
+
+    await client.del(cacheKey(key));
+    return true;
+  },
+
+  /**
+   * Why: Returns cached value or computes/stores a fresh one.
+   * When: A feature needs cache-aside behavior.
+   * Where: Read paths with potentially expensive callbacks.
+   * How: Attempts get first, then executes callback and put.
+   */
+  async remember<T>(key: string, ttl: number, callback: () => Promise<T>) {
+    const cached = await cache.get<T>(key);
+    if (cached !== null) return cached;
+
+    const fresh = await callback();
+    await this.put(key, fresh, ttl);
+    return fresh;
+  },
+
+  /**
+   * Why: Indicates whether Redis cache backend is currently usable.
+   * When: Runtime checks need to branch on cache availability.
+   * Where: Health/status endpoints and conditional flows.
+   * How: Confirms REDIS flag and ready Redis client instance.
+   */
+  isAvailable() {
+    return redisConfig.enabled && redisClientIfReady() !== null;
+  }
+};

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

@@ -1,6 +1,6 @@
+import { readFile } from "node:fs/promises";
 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 = [

package/express/src/framework/facade.ts

@@ -4,30 +4,7 @@ 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 * as HttpStatusCodes from "@/framework/support/status-codes.js";
 export { cache } from "@/framework/cache/cache.js";
 export { database, db } from "@/framework/database/connection.js";
 export type { PaginatedResult } from "@/framework/database/paginate.js";

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

@@ -35,20 +35,20 @@ export function createHttpApp() {
     let allOk = true;
     try {
       database();
-      checks["database"] = "ok";
+      checks.database = "ok";
     } catch {
-      checks["database"] = "error";
+      checks.database = "error";
       allOk = false;
     }
     if (redisConfig.enabled) {
       if (redisClientIfReady()) {
-        checks["redis"] = "ok";
+        checks.redis = "ok";
       } else {
-        checks["redis"] = "error";
+        checks.redis = "error";
         allOk = false;
       }
     } else {
-      checks["redis"] = "disabled";
+      checks.redis = "disabled";
     }
     const status = allOk ? 200 : 503;
     res.status(status).json({ status: allOk ? "ready" : "not_ready", checks });

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

@@ -5,7 +5,7 @@ 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";
+import type { RouteConfig } from "@/framework/http/types.js";
 
 extendZodWithOpenApi(z);
 

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

@@ -2,25 +2,10 @@ 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 type { HttpMethod, RouteConfig } from "@/framework/http/types.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 { HttpMethod, RouteConfig };
 
 export type NexwireRouter = Omit<ExpressRouter, "route"> & {
   group: (...middlewares: RequestHandler[]) => NexwireRouter;
@@ -35,7 +20,7 @@ export function createRoute<T extends RouteConfig>(config: T): T {
   return config;
 }
 
-export const jsonContent = <T extends z.ZodTypeAny>(schema: T, description: string) => ({
+export const jsonContent = <T extends z.ZodType>(schema: T, description: string) => ({
   content: {
     "application/json": {
       schema

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

@@ -0,0 +1,19 @@
+import type { z } from "zod";
+
+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.ZodType;
+    query?: z.ZodType;
+    headers?: z.ZodType;
+    cookies?: z.ZodType;
+    body?: { content: { "application/json": { schema: z.ZodType } }; description?: string };
+  };
+  responses: Record<number | string, { description?: string; content?: { "application/json": { schema: z.ZodType } } }>;
+};

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

@@ -1,18 +1,18 @@
-import createError from "http-errors";
-import type { z } from "zod";
-
-export async function validate<T extends z.ZodTypeAny>(schema: T, data: unknown): Promise<z.infer<T>> {
-  const result = await schema.safeParseAsync(data);
-
-  if (!result.success) {
-    throw createError(422, "Validation failed", {
-      success: false,
-      error: {
-        name: result.error.name,
-        issues: result.error.issues
-      }
-    } as never);
-  }
-
-  return result.data;
-}
+import createError from "http-errors";
+import type { z } from "zod";
+
+export async function validate<T extends z.ZodType>(schema: T, data: unknown): Promise<z.infer<T>> {
+  const result = await schema.safeParseAsync(data);
+
+  if (!result.success) {
+    throw createError(422, "Validation failed", {
+      success: false,
+      error: {
+        name: result.error.name,
+        issues: result.error.issues
+      }
+    } as never);
+  }
+
+  return result.data;
+}

package/express/src/framework/maker-cli/middleware/core.mjs

@@ -1,47 +1,41 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { hasFlag } from "../utils/flags.mjs";
-import { assertName, pascal } from "../utils/naming.mjs";
-
-const stubsRoot = path.resolve(import.meta.dirname, "../stubs");
-
-/** Read a stub file and replace {{key}} placeholders, removing unfilled ones. */
-async function stub(name, values = {}) {
-  let content = await fs.readFile(path.join(stubsRoot, name), "utf8");
-  for (const [key, value] of Object.entries(values)) {
-    content = content.replaceAll(`{{${key}}}`, String(value));
-  }
-  return content.replace(/\{\{[A-Z0-9_]+\}\}/g, "");
-}
-
-/** Convert a name to camelCase (e.g. "rate-limit" -> "rateLimit"). */
-function camelCase(input) {
-  const p = pascal(input);
-  return p.charAt(0).toLowerCase() + p.slice(1);
-}
-
-/** Generate a middleware file in src/middlewares. */
-export async function makeMiddleware(rawName, flags = []) {
-  const name = assertName(rawName, "Middleware name");
-  const camel = camelCase(name);
-  const dryRun = hasFlag(flags, "--dry-run");
-  const force = hasFlag(flags, "--force") || hasFlag(flags, "--yes");
-
-  const filePath = path.resolve(process.cwd(), "src/middlewares", `${name}-middleware.ts`);
-  if (dryRun) return;
-
-  let exists = false;
-  try {
-    await fs.access(filePath);
-    exists = true;
-  } catch {}
-  if (exists && !force) {
-    throw new Error(`Middleware already exists: ${path.relative(process.cwd(), filePath)}. Re-run with --force to overwrite.`);
-  }
-
-  const content = await stub("middleware/name.ts.stub", { name, camel });
-  await fs.mkdir(path.dirname(filePath), { recursive: true });
-  await fs.writeFile(filePath, content);
-  console.log(`Middleware ready: ${path.relative(process.cwd(), filePath)}`);
-  console.log(`Apply it to a route group: group(${camel}Middleware)`);
-}
+import fs from "node:fs/promises";
+import path from "node:path";
+import { hasFlag } from "../utils/flags.mjs";
+import { assertName, camelCase } from "../utils/naming.mjs";
+
+const stubsRoot = path.resolve(import.meta.dirname, "../stubs");
+
+/** Read a stub file and replace {{key}} placeholders, removing unfilled ones. */
+async function stub(name, values = {}) {
+  let content = await fs.readFile(path.join(stubsRoot, name), "utf8");
+  for (const [key, value] of Object.entries(values)) {
+    content = content.replaceAll(`{{${key}}}`, String(value));
+  }
+  return content.replace(/\{\{[A-Z0-9_]+\}\}/g, "");
+}
+
+/** Generate a middleware file in src/middlewares. */
+export async function makeMiddleware(rawName, flags = []) {
+  const name = assertName(rawName, "Middleware name");
+  const camel = camelCase(name);
+  const dryRun = hasFlag(flags, "--dry-run");
+  const force = hasFlag(flags, "--force") || hasFlag(flags, "--yes");
+
+  const filePath = path.resolve(process.cwd(), "src/middlewares", `${name}-middleware.ts`);
+  if (dryRun) return;
+
+  let exists = false;
+  try {
+    await fs.access(filePath);
+    exists = true;
+  } catch {}
+  if (exists && !force) {
+    throw new Error(`Middleware already exists: ${path.relative(process.cwd(), filePath)}. Re-run with --force to overwrite.`);
+  }
+
+  const content = await stub("middleware/name.ts.stub", { name, camel });
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, content);
+  console.log(`Middleware ready: ${path.relative(process.cwd(), filePath)}`);
+  console.log(`Apply it to a route group: group(${camel}Middleware)`);
+}