create-nexwire 4.2.5 → 4.4.0

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

@@ -0,0 +1,324 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "af502348-be37-45c6-84e4-df4db9f31bfb",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "tables": {
+    "roles": {
+      "name": "roles",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "roles_name_unique": {
+          "name": "roles_name_unique",
+          "columns": [
+            "name"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "email_verification_tokens": {
+      "name": "email_verification_tokens",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "email": {
+          "name": "email",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "token": {
+          "name": "token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "password_reset_tokens": {
+      "name": "password_reset_tokens",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "email": {
+          "name": "email",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "token": {
+          "name": "token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "refresh_tokens": {
+      "name": "refresh_tokens",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "jti": {
+          "name": "jti",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "revoked": {
+          "name": "revoked",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false,
+          "default": false
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "refresh_tokens_jti_unique": {
+          "name": "refresh_tokens_jti_unique",
+          "columns": [
+            "jti"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {
+        "refresh_tokens_user_id_users_id_fk": {
+          "name": "refresh_tokens_user_id_users_id_fk",
+          "tableFrom": "refresh_tokens",
+          "tableTo": "users",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "users": {
+      "name": "users",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "email": {
+          "name": "email",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "password": {
+          "name": "password",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "role_id": {
+          "name": "role_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "email_verified_at": {
+          "name": "email_verified_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "users_email_unique": {
+          "name": "users_email_unique",
+          "columns": [
+            "email"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {
+        "users_role_id_roles_id_fk": {
+          "name": "users_role_id_roles_id_fk",
+          "tableFrom": "users",
+          "tableTo": "roles",
+          "columnsFrom": [
+            "role_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

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

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1793719238470,
+      "tag": "0000_init",
+      "breakpoints": true
+    }
+  ]
+}

package/fastify/src/database/schema.ts

@@ -0,0 +1,2 @@
+export * from "../modules/auth/database/models/role.js";
+export * from "../modules/auth/database/models/user.js";

package/fastify/src/env.ts

@@ -0,0 +1,76 @@
+import { config } from "dotenv";
+import { expand } from "dotenv-expand";
+import { z } from "zod";
+
+expand(config({ override: true }));
+
+const envSchema = z
+  .object({
+    APP_NAME: z.string().default("nexwire"),
+    APP_ENV: z.enum(["development", "production", "test"]).default("development"),
+    APP_PORT: z.coerce.number().default(3000),
+    APP_URL: z.string().trim().min(1, "APP_URL is required in .env"),
+    UI: z
+      .string()
+      .default("true")
+      .transform((value) => value.trim().toLowerCase() !== "false" && value.trim() !== "0"),
+    FRONTEND_URL: z
+      .string()
+      .optional()
+      .transform((value) => value?.trim() || undefined),
+    DATABASE_URL: z.string().default("sqlite:./src/storage/database/nexwire.sqlite"),
+    REDIS: z
+      .string()
+      .default("false")
+      .transform((value) => value.trim().toLowerCase() !== "false" && value.trim() !== "0"),
+    REDIS_URL: z.string().default("redis://127.0.0.1:6379"),
+    REDIS_PREFIX: z
+      .string()
+      .default("nexwire")
+      .transform((value) => value.trim()),
+    JWT_ACCESS_SECRET: z.string(),
+    JWT_REFRESH_SECRET: z.string(),
+    COOKIE_SECRET: z.string(),
+    STORAGE_ACCESS_KEY_ID: z
+      .string()
+      .optional()
+      .transform((value) => value?.trim() || undefined),
+    STORAGE_SECRET_ACCESS_KEY: z
+      .string()
+      .optional()
+      .transform((value) => value?.trim() || undefined),
+    MAIL_USERNAME: z.string().default(""),
+    MAIL_PASSWORD: z.string().default(""),
+    OPEN_API: z
+      .string()
+      .default("true")
+      .transform((value) => value.trim().toLowerCase() !== "false" && value.trim() !== "0"),
+    SOCKET: z
+      .string()
+      .default("false")
+      .transform((value) => value.trim().toLowerCase() !== "false" && value.trim() !== "0"),
+    SECURITY_HEADERS: z
+      .string()
+      .default("true")
+      .transform((value) => value.trim().toLowerCase() !== "false" && value.trim() !== "0")
+  })
+  .superRefine((data, ctx) => {
+    for (const key of ["JWT_ACCESS_SECRET", "JWT_REFRESH_SECRET", "COOKIE_SECRET"] as const) {
+      if (!data[key]) {
+        ctx.addIssue({
+          code: "custom",
+          path: [key],
+          message: `${key} is required`
+        });
+      }
+    }
+  });
+
+const parsedEnv = envSchema.parse(process.env);
+
+export const env = {
+  ...parsedEnv,
+  FRONTEND_URL: parsedEnv.FRONTEND_URL
+};
+
+export type Env = typeof env;

package/fastify/src/framework/cache/cache.ts

@@ -0,0 +1,114 @@
+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.
+ * 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 the client isn't connected at all, fail fast to fallback
+    if (!client) return 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;
+
+    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;
+    }
+  },
+
+  /**
+   * @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;
+
+    try {
+      return await cacheBreaker.exec(async () => {
+        await client.del(cacheKey(key));
+        return true;
+      });
+    } catch (error) {
+      if (isCircuitBreakerError(error)) return false;
+      return false;
+    }
+  },
+
+  /**
+   * 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.set(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 && cacheBreaker.getState() !== "open";
+  }
+};

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

@@ -0,0 +1,88 @@
+// 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>;

package/fastify/src/framework/database/app-schema.ts

@@ -0,0 +1,37 @@
+import { discoverModuleFiles, importFile } from "@/framework/modules/discover.js";
+
+/**
+ * Why: Builds the Drizzle schema from the modules that actually exist.
+ * When: The database connection is initialised.
+ * Where: Framework database connection.
+ * How: Discovers `src/modules/**\/database/models/*` and merges their exports.
+ *      The generated barrel at `src/database/schema.ts` is only used by
+ *      drizzle-kit, so deleting or replacing a module never leaves the
+ *      framework importing a file that is no longer there.
+ */
+let cachedSchema: Record<string, unknown> | null = null;
+
+export async function loadAppSchema(): Promise<Record<string, unknown>> {
+  if (cachedSchema) return cachedSchema;
+
+  const schema: Record<string, unknown> = {};
+  const files = await discoverModuleFiles("**/database/models/*.{ts,js}");
+
+  for (const file of files) {
+    try {
+      const models = await importFile(file);
+      Object.assign(schema, models);
+    } catch {
+      // A model file that fails to load is skipped: the rest of the schema
+      // still works, and the framework keeps booting.
+    }
+  }
+
+  cachedSchema = schema;
+  return schema;
+}
+
+/** Clears the cached schema. Mainly useful in tests. */
+export function clearAppSchema(): void {
+  cachedSchema = null;
+}