create-nexwire 4.2.4 → 4.3.0

package/express/src/config/openapi.ts

@@ -8,46 +8,28 @@ import { appConfig } from "./app.js";
  *      and the Scalar docs UI appearance.
  */
 export const openApiConfig = {
-  /** OpenAPI spec version */
   version: "3.0.0",
-
-  /** API title shown in docs and the /doc spec */
   title: `${appConfig.name} API`,
-
-  /** API version shown in docs */
   apiVersion: "1.0.0",
-
-  /** Optional description shown in the /doc spec */
   description: "",
 
   /** Scalar docs UI settings */
   scalar: {
-    /** URL path to the OpenAPI JSON spec */
-    specUrl: "/doc",
-
-    /** URL path to the interactive docs UI */
-    docsPath: "/api-docs",
-
-    /** UI layout: "classic" or "modern" */
-    layout: "classic" as const,
-
+    specUrl: "/doc", // URL path to the OpenAPI JSON spec
+    docsPath: "/api-docs", // URL path to the interactive docs UI
+    layout: "classic" as const, // UI layout: "classic" or "modern"
     /** UI theme: "default", "moon", "purple", "solarized", "bluePlanet", "fastify", "kepler", "mars", "nebula", "none" */
     theme: "moon" as const,
-
-    /** HTML page title for the /api-docs page */
-    pageTitle: `${appConfig.name} API`,
-
+    pageTitle: `${appConfig.name} API`, // HTML page title for the /api-docs page
     /** Favicon file (project-relative) served at /favicon.ico for the /api-docs page */
     favicon: "src/resources/src/assets/images/favicon/favicon.ico",
-
     /** Default HTTP client shown in code examples */
     defaultHttpClient: {
       targetKey: "js" as const,
       clientKey: "fetch" as const
     },
-
-    /** Expand all tags on load */
-    defaultOpenAllTags: true
+    defaultOpenAllTags: true, // Expand all tags on load
+    showDeveloperTools: "never"
   }
 } as const;
 

package/express/src/config/queue.ts

@@ -1,30 +1,30 @@
-import { redisConfig } from "./redis.js";
-
-/**
- * Why: Queue workers, concurrency, and BullMQ key namespaces.
- * When: The queue facade bootstraps workers and the dashboard connects.
- * Where: src/config/queue.ts.
- * How: `queues` lists which queue names get a worker by default (default,
- *      mail, maintenance). `concurrency` caps parallel jobs per worker.
- *      Key prefixes derive from the shared `REDIS_PREFIX`.
- */
-export const queueConfig = {
-  queues: ["default", "mail", "maintenance"],
-  concurrency: 10,
-  /**
-   * autoPruneQueues
-   * Why: Automatically deletes phantom queues (Redis keys for queue names that
-   *      no longer exist in `queues`) when a queue worker boots. Safe because
-   *      only empty, unconfigured queues are removed, and BullMQ recreates a
-   *      queue's keys on demand if code still dispatches to it.
-   * When: Set false to disable automatic pruning and rely on manual
-   *      `queue:clear` instead.
-   */
-  autoPruneQueues: true,
-  prefix: `${redisConfig.prefix}:queue`,
-  durablePrefix: `${redisConfig.prefix}:durable`,
-  queueUi: "/queues",
-  allowedEmails: ""
-};
-
-export type QueueConfig = typeof queueConfig;
+import { redisConfig } from "./redis.js";
+
+/**
+ * Why: Queue workers, concurrency, and BullMQ key namespaces.
+ * When: The queue facade bootstraps workers and the dashboard connects.
+ * Where: src/config/queue.ts.
+ * How: `queues` lists which queue names get a worker by default (default,
+ *      mail, maintenance). `concurrency` caps parallel jobs per worker.
+ *      Key prefixes derive from the shared `REDIS_PREFIX`.
+ */
+export const queueConfig = {
+  queues: ["default", "mail", "maintenance"],
+  concurrency: 10,
+  /**
+   * autoPruneQueues
+   * Why: Automatically deletes phantom queues (Redis keys for queue names that
+   *      no longer exist in `queues`) when a queue worker boots. Safe because
+   *      only empty, unconfigured queues are removed, and BullMQ recreates a
+   *      queue's keys on demand if code still dispatches to it.
+   * When: Set false to disable automatic pruning and rely on manual
+   *      `queue:clear` instead.
+   */
+  autoPruneQueues: true,
+  prefix: `${redisConfig.prefix}:queue`,
+  durablePrefix: `${redisConfig.prefix}:durable`,
+  queueUi: "/queues",
+  allowedEmails: "" // Comma-separated list of email addresses allowed to access the queue UI. Empty means no restriction.
+};
+
+export type QueueConfig = typeof queueConfig;

package/express/src/config/validate.ts

@@ -1,40 +1,50 @@
-import { databaseConfig } from "./database.js";
-import { mailConfig } from "./mail.js";
-import { redisConfig } from "./redis.js";
-import { storageConfig } from "./storage.js";
-
-/**
- * Why: Validates that resolved configs are internally consistent at startup.
- * When: Called before any framework subsystem initializes.
- * Where: kernel.ts, before storage.init() and initRedis().
- * How: Checks cross-config dependencies and throws clear errors for inconsistencies.
- */
-export function validateConfig(): void {
-  if (!databaseConfig.url) {
-    throw new Error("DATABASE_URL is required but is empty");
-  }
-
-  if (storageConfig.driver === "s3") {
-    if (!storageConfig.bucket) {
-      throw new Error("STORAGE_BUCKET is required when storage driver is s3");
-    }
-    if (!storageConfig.accessKeyId || !storageConfig.secretAccessKey) {
-      throw new Error("STORAGE_ACCESS_KEY_ID and STORAGE_SECRET_ACCESS_KEY are required when storage driver is s3");
-    }
-  }
-
-  if (redisConfig.enabled) {
-    try {
-      const url = new URL(redisConfig.url);
-      if (!url.hostname || url.port === "") {
-        throw new Error(`REDIS_URL is invalid: "${redisConfig.url}" — must include host and port`);
-      }
-    } catch (error) {
-      throw new Error(`REDIS_URL is invalid: "${redisConfig.url}" — ${error instanceof Error ? error.message : error}`);
-    }
-  }
-
-  if (!mailConfig.failSilent && !mailConfig.username) {
-    throw new Error("MAIL_USERNAME is required when MAIL_FAIL_SILENT is false");
-  }
-}
+import { databaseConfig } from "./database.js";
+import { mailConfig } from "./mail.js";
+import { redisConfig } from "./redis.js";
+import { storageConfig } from "./storage.js";
+
+/**
+ * Why: Validates that resolved configs are internally consistent at startup.
+ * When: Called before any framework subsystem initializes.
+ * Where: kernel.ts, before storage.init() and initRedis().
+ * How: Checks cross-config dependencies and throws clear errors for inconsistencies.
+ */
+export function validateConfig(): void {
+  if (!databaseConfig.url) {
+    throw new Error("DATABASE_URL is required but is empty");
+  }
+
+  if (storageConfig.driver === "s3") {
+    if (!storageConfig.bucket) {
+      throw new Error("STORAGE_BUCKET is required when storage driver is s3");
+    }
+    if (!storageConfig.accessKeyId || !storageConfig.secretAccessKey) {
+      throw new Error("STORAGE_ACCESS_KEY_ID and STORAGE_SECRET_ACCESS_KEY are required when storage driver is s3");
+    }
+  }
+
+  if (redisConfig.enabled) {
+    try {
+      const url = new URL(redisConfig.url);
+
+      // Ensure it starts with redis:// or rediss://
+      if (url.protocol !== "redis:" && url.protocol !== "rediss:") {
+        throw new Error("URL must start with redis:// or rediss://");
+      }
+
+      // Hostname is mandatory (e.g., localhost, 127.0.0.1, redis-container)
+      if (!url.hostname) {
+        throw new Error("URL must include a valid hostname");
+      }
+
+      // Note: We do NOT check if the port is empty.
+      // ioredis automatically defaults to 6379 if no port is provided.
+    } catch (error) {
+      throw new Error(`REDIS_URL is invalid: "${redisConfig.url}" — ${error instanceof Error ? error.message : error}`);
+    }
+  }
+
+  if (!mailConfig.failSilent && !mailConfig.username) {
+    throw new Error("MAIL_USERNAME is required when MAIL_FAIL_SILENT is false");
+  }
+}

package/express/src/database/migrations/sqlite/0000_init.sql

@@ -1,48 +1,48 @@
-CREATE TABLE `roles` (
-	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
-	`name` text NOT NULL,
-	`created_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL,
-	`updated_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL
-);
---> statement-breakpoint
-CREATE UNIQUE INDEX `roles_name_unique` ON `roles` (`name`);--> statement-breakpoint
-CREATE TABLE `email_verification_tokens` (
-	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
-	`email` text NOT NULL,
-	`token` text NOT NULL,
-	`expires_at` integer NOT NULL,
-	`created_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL
-);
---> statement-breakpoint
-CREATE TABLE `password_reset_tokens` (
-	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
-	`email` text NOT NULL,
-	`token` text NOT NULL,
-	`expires_at` integer NOT NULL,
-	`created_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL
-);
---> statement-breakpoint
-CREATE TABLE `refresh_tokens` (
-	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
-	`user_id` integer,
-	`jti` text NOT NULL,
-	`revoked` integer DEFAULT false,
-	`expires_at` integer NOT NULL,
-	`created_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL,
-	FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON UPDATE cascade ON DELETE set null
-);
---> statement-breakpoint
-CREATE UNIQUE INDEX `refresh_tokens_jti_unique` ON `refresh_tokens` (`jti`);--> statement-breakpoint
-CREATE TABLE `users` (
-	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
-	`name` text NOT NULL,
-	`email` text NOT NULL,
-	`password` text NOT NULL,
-	`role_id` integer,
-	`email_verified_at` integer,
-	`created_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL,
-	`updated_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL,
-	FOREIGN KEY (`role_id`) REFERENCES `roles`(`id`) ON UPDATE cascade ON DELETE set null
-);
---> statement-breakpoint
+CREATE TABLE `roles` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`name` text NOT NULL,
+	`created_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL,
+	`updated_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `roles_name_unique` ON `roles` (`name`);--> statement-breakpoint
+CREATE TABLE `email_verification_tokens` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`email` text NOT NULL,
+	`token` text NOT NULL,
+	`expires_at` integer NOT NULL,
+	`created_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `password_reset_tokens` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`email` text NOT NULL,
+	`token` text NOT NULL,
+	`expires_at` integer NOT NULL,
+	`created_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `refresh_tokens` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`user_id` integer,
+	`jti` text NOT NULL,
+	`revoked` integer DEFAULT false,
+	`expires_at` integer NOT NULL,
+	`created_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL,
+	FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON UPDATE cascade ON DELETE set null
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `refresh_tokens_jti_unique` ON `refresh_tokens` (`jti`);--> statement-breakpoint
+CREATE TABLE `users` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`name` text NOT NULL,
+	`email` text NOT NULL,
+	`password` text NOT NULL,
+	`role_id` integer,
+	`email_verified_at` integer,
+	`created_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL,
+	`updated_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL,
+	FOREIGN KEY (`role_id`) REFERENCES `roles`(`id`) ON UPDATE cascade ON DELETE set null
+);
+--> statement-breakpoint
 CREATE UNIQUE INDEX `users_email_unique` ON `users` (`email`);

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

@@ -1,7 +1,7 @@
 {
   "version": "6",
   "dialect": "sqlite",
-  "id": "f0fe475e-8a3e-4c5c-9b5e-9ec41ddfde71",
+  "id": "af502348-be37-45c6-84e4-df4db9f31bfb",
   "prevId": "00000000-0000-0000-0000-000000000000",
   "tables": {
     "roles": {

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

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

package/express/src/database/schema.ts

@@ -1,2 +1,2 @@
-export * from "../modules/auth/database/models/role.js";
-export * from "../modules/auth/database/models/user.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,10 +1,18 @@
 import { cacheConfig, redisConfig } from "@/config/index.js";
+import { createCircuitBreaker, isCircuitBreakerError } from "@/framework/circuit-breaker/cb.js";
 import { redisClientIfReady } from "@/framework/redis/client.js";
 
 function cacheKey(key: string) {
   return `${cacheConfig.keyPrefix}:${key}`;
 }
 
+// Initialize the circuit breaker specifically for Cache operations
+const cacheBreaker = createCircuitBreaker({
+  name: "Redis Cache",
+  failureThreshold: 3,
+  resetTimeout: 30000
+});
+
 /**
  * Why: Provides Redis-backed cache helpers with graceful fallback behavior.
  * When: Controllers/jobs need temporary computed data caching.
@@ -20,18 +28,35 @@ export const cache = {
    */
   async get<T>(key: string, fallback: T | null = null) {
     const client = redisClientIfReady();
+    // If the client isn't connected at all, fail fast to fallback
     if (!client) return fallback;
 
-    const value = await client.get(cacheKey(key));
-    return value ? (JSON.parse(value) as T) : fallback;
+    try {
+      return await cacheBreaker.exec(async () => {
+        const value = await client.get(cacheKey(key));
+        return value ? (JSON.parse(value) as T) : fallback;
+      });
+    } catch (error) {
+      // If the circuit is open, or a Redis error occurs, return the fallback safely
+      if (isCircuitBreakerError(error)) return fallback;
+      return 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;
+    try {
+      return await cacheBreaker.exec(async () => {
+        await client.set(cacheKey(key), JSON.stringify(value), "EX", ttl);
+        return true;
+      });
+    } catch (error) {
+      // If the circuit is open, or a Redis error occurs, silently fail
+      if (isCircuitBreakerError(error)) return false;
+      return false;
+    }
   },
 
   /**
@@ -51,8 +76,15 @@ export const cache = {
     const client = redisClientIfReady();
     if (!client) return false;
 
-    await client.del(cacheKey(key));
-    return true;
+    try {
+      return await cacheBreaker.exec(async () => {
+        await client.del(cacheKey(key));
+        return true;
+      });
+    } catch (error) {
+      if (isCircuitBreakerError(error)) return false;
+      return false;
+    }
   },
 
   /**
@@ -66,7 +98,7 @@ export const cache = {
     if (cached !== null) return cached;
 
     const fresh = await callback();
-    await this.put(key, fresh, ttl);
+    await this.set(key, fresh, ttl);
     return fresh;
   },
 
@@ -77,6 +109,6 @@ export const cache = {
    * How: Confirms REDIS flag and ready Redis client instance.
    */
   isAvailable() {
-    return redisConfig.enabled && redisClientIfReady() !== null;
+    return redisConfig.enabled && redisClientIfReady() !== null && cacheBreaker.getState() !== "open";
   }
 };

package/express/src/framework/circuit-breaker/cb.ts

@@ -1,60 +1,88 @@
-export class CircuitBreaker {
-  private state: "closed" | "open" | "half-open" = "closed";
-  private failureCount = 0;
-  private readonly failureThreshold = 3;
-  private readonly resetTimeout = 30000;
-  private lastFailureTime = 0;
-  private successCount = 0;
-  private readonly successThreshold = 1;
-
-  async exec<T>(fn: () => Promise<T>): Promise<T> {
-    if (this.state === "open") {
-      if (Date.now() - this.lastFailureTime >= this.resetTimeout) {
-        this.state = "half-open";
-        this.successCount = 0;
-      } else {
-        throw new Error("Circuit breaker is open");
-      }
-    }
-    try {
-      const result = await fn();
-      this.onSuccess();
-      return result;
-    } catch (error) {
-      this.onFailure();
-      throw error;
-    }
-  }
-
-  getState(): "closed" | "open" | "half-open" {
-    return this.state;
-  }
-
-  onSuccess(): void {
-    if (this.state === "half-open") {
-      this.successCount++;
-      if (this.successCount >= this.successThreshold) {
-        this.reset();
-      }
-    }
-    this.failureCount = 0;
-  }
-
-  onFailure(): void {
-    this.failureCount++;
-    if (this.failureCount >= this.failureThreshold || this.state === "half-open") {
-      this.trip();
-    }
-  }
-
-  trip(): void {
-    this.state = "open";
-    this.lastFailureTime = Date.now();
-  }
-
-  reset(): void {
-    this.state = "closed";
-    this.failureCount = 0;
-    this.successCount = 0;
-  }
-}
+// Factory for the error
+export function createCircuitBreakerError(serviceName: string) {
+  const error = new Error(`Circuit breaker is open for ${serviceName}. Service is temporarily unavailable.`);
+  // Attach a custom property to identify it
+  Object.assign(error, { name: "CircuitBreakerOpenError", isCircuitBreakerError: true });
+  return error;
+}
+
+// Functional Type Guard
+export function isCircuitBreakerError(error: unknown): error is Error {
+  return error instanceof Error && (error as any).isCircuitBreakerError === true;
+}
+
+export interface CircuitBreakerOptions {
+  name?: string;
+  failureThreshold?: number;
+  resetTimeout?: number;
+  successThreshold?: number;
+}
+
+export function createCircuitBreaker({
+  name = "Unknown Service",
+  failureThreshold = 3,
+  resetTimeout = 30000,
+  successThreshold = 1
+}: CircuitBreakerOptions = {}) {
+  let state: "closed" | "open" | "half-open" = "closed";
+  let failureCount = 0;
+  let successCount = 0;
+  let lastFailureTime = 0;
+  let isHalfOpenTestRunning = false;
+
+  function trip() {
+    state = "open";
+    lastFailureTime = Date.now();
+  }
+
+  function reset() {
+    state = "closed";
+    failureCount = 0;
+    successCount = 0;
+  }
+
+  return {
+    async exec<T>(fn: () => Promise<T>): Promise<T> {
+      if (state === "open") {
+        if (Date.now() - lastFailureTime >= resetTimeout) {
+          state = "half-open";
+          successCount = 0;
+          isHalfOpenTestRunning = false;
+        } else {
+          throw createCircuitBreakerError(name);
+        }
+      }
+
+      if (state === "half-open") {
+        if (isHalfOpenTestRunning) {
+          throw createCircuitBreakerError(name);
+        }
+        isHalfOpenTestRunning = true;
+      }
+
+      try {
+        const result = await fn();
+        if (state === "half-open") {
+          successCount++;
+          if (successCount >= successThreshold) reset();
+        }
+        failureCount = 0;
+        return result;
+      } catch (error) {
+        failureCount++;
+        if (failureCount >= failureThreshold || state === "half-open") {
+          trip();
+        }
+        throw error;
+      } finally {
+        if (state === "half-open") isHalfOpenTestRunning = false;
+      }
+    },
+
+    getState() {
+      return state;
+    }
+  };
+}
+
+export type CircuitBreaker = ReturnType<typeof createCircuitBreaker>;