create-nexwire 4.3.0 → 4.4.0

package/fastify/src/framework/providers/contracts.ts

@@ -0,0 +1,126 @@
+/**
+ * Why: Defines the shapes a pluggable provider has to satisfy.
+ * When: A developer replaces a framework default (auth, notifications, payments later).
+ * Where: Imported through the framework facade, never from framework internals.
+ * How: Interfaces stay deliberately loose so custom user shapes pass through.
+ */
+
+/** Registry key of the built-in auth provider contract. */
+export const AUTH_PROVIDER_KEY = "auth";
+
+/** Registry key of the built-in notification storage provider. */
+export const NOTIFICATION_PROVIDER_KEY = "notification";
+
+/**
+ * Registry key for any provider implementation.
+ *
+ * `string & {}` keeps the literal keys above discoverable by editors while
+ * still accepting any custom key, so a project can register its own contracts
+ * (payments, otp, storage, ...) without the framework having to know them.
+ */
+export type ProviderKey = typeof AUTH_PROVIDER_KEY | typeof NOTIFICATION_PROVIDER_KEY | (string & {});
+
+export interface AuthProviderUser {
+  id: number | string;
+  email?: string | null;
+  [key: string]: any;
+}
+
+export interface AuthProviderRefreshToken {
+  id: number | string;
+  jti: string;
+  revoked?: boolean | null;
+  expiresAt?: Date | string | null;
+  userId?: number | string | null;
+  [key: string]: any;
+}
+
+export interface AuthUserContext {
+  id: number | string;
+  email?: string | null;
+  roleId?: number | null;
+  role?: string | null;
+  [key: string]: any;
+}
+
+export interface AuthUserContact {
+  email?: string | null;
+  name?: string | null;
+  phone?: string | null;
+}
+
+export interface AuthProvider {
+  getUserById(id: number | string): Promise<AuthProviderUser | null>;
+  findRefreshToken(jti: string): Promise<AuthProviderRefreshToken | null>;
+  revokeRefreshToken?(tokenId: number | string): Promise<void>;
+  deleteRefreshToken?(tokenId: number | string): Promise<void>;
+  getAuthContext?(user: AuthProviderUser, payload?: any): Promise<AuthUserContext | any>;
+  getUserContact?(userId: number | string): Promise<AuthUserContact | null>;
+}
+
+/**
+ * Who a notification belongs to. `id` accepts a numeric auth id and a string
+ * id (UUID, ULID, ...) so replacing auth does not force a notification change.
+ * The provider always stores the id as text.
+ */
+export interface NotifiableTarget {
+  /** Notifiable class. Defaults to "user". */
+  type?: string;
+  id: number | string;
+}
+
+/** Payload accepted by `NotificationProvider.create()`. */
+export interface NotificationCreateInput {
+  type?: string;
+  title: string;
+  body?: string | null;
+  link?: string | null;
+  data?: Record<string, unknown> | null;
+}
+
+/** Normalized notification returned by every provider operation. */
+export interface NotificationRecord {
+  id: string;
+  notifiableType: string;
+  notifiableId: string;
+  type: string;
+  title: string;
+  body: string | null;
+  data: Record<string, unknown> | null;
+  link: string | null;
+  readAt: string | null;
+  createdAt: string;
+}
+
+export interface NotificationListOptions {
+  page?: number;
+  perPage?: number;
+}
+
+export interface NotificationPage {
+  data: NotificationRecord[];
+  total: number;
+  unread: number;
+  page: number;
+  perPage: number;
+}
+
+/**
+ * Why: Keeps notification storage replaceable without touching `notify()` or
+ *      the generated HTTP routes.
+ * When: The default `src/modules/notification` store is replaced by a custom
+ *       implementation (a different table, another service, ...).
+ * Where: Registered through `registerNotificationProvider()`.
+ * How: The framework only reads through this contract; mail and realtime
+ *      delivery stay in the runtime so a storage swap cannot disable them.
+ */
+export interface NotificationProvider {
+  create(target: NotifiableTarget, input: NotificationCreateInput): Promise<NotificationRecord>;
+  list(target: NotifiableTarget, options?: NotificationListOptions): Promise<NotificationPage>;
+  unreadCount(target: NotifiableTarget): Promise<number>;
+  markRead(target: NotifiableTarget, id: number | string): Promise<boolean>;
+  markAllRead(target: NotifiableTarget): Promise<number>;
+  remove(target: NotifiableTarget, id: number | string): Promise<boolean>;
+  /** Optional bulk cleanup when a notifiable target is deleted. */
+  deleteForTarget?(target: NotifiableTarget): Promise<number>;
+}

package/fastify/src/framework/providers/loader.ts

@@ -0,0 +1,105 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { glob } from "glob";
+import { discoverModuleFiles } from "@/framework/modules/discover.js";
+import { logger } from "@/framework/support/logger.js";
+
+/**
+ * Why: Finds the app-level provider folder for the running code.
+ * When: Providers are loaded at boot.
+ * Where: Provider loader.
+ * How: Mirrors the module discovery rule — `src/providers` in development,
+ *      `dist/src/providers` when the compiled server is the entrypoint.
+ */
+function resolveProvidersPath() {
+  const cwd = process.cwd();
+  const srcProviders = path.resolve(cwd, "src/providers");
+  const distProviders = path.resolve(cwd, "dist/src/providers");
+  const entry = String(process.argv[1] || "");
+  const runningDist = /[\\/]dist[\\/]/.test(entry);
+
+  if (runningDist && fs.existsSync(distProviders)) return distProviders;
+  return srcProviders;
+}
+
+export const providersPath = resolveProvidersPath();
+
+let loadPromise: Promise<number> | null = null;
+let loading = false;
+
+/**
+ * Why: Collects every provider file that should run at boot.
+ * When: The loader runs.
+ * Where: Provider loader.
+ * How: Globs `src/providers/**` for app-wide providers, and
+ *      `src/modules/**\/providers.ts` plus `src/modules/**\/providers/*.ts` for
+ *      module-scoped ones. Tests and declaration files are ignored.
+ */
+async function collectProviderFiles(): Promise<string[]> {
+  const files: string[] = [];
+
+  if (fs.existsSync(providersPath)) {
+    const appFiles = await glob("**/*.{ts,js,mjs}", {
+      cwd: providersPath,
+      absolute: true,
+      nodir: true,
+      ignore: ["**/__tests__/**", "**/*.d.ts", "**/*.test.*", "**/*.spec.*"],
+      windowsPathsNoEscape: true
+    });
+    files.push(...appFiles);
+  }
+
+  try {
+    // A module plugs its own implementation in either from a single file
+    // (providers.ts) or from a folder (providers/*.ts). Both are imported.
+    const moduleFiles = await discoverModuleFiles("**/providers.{ts,js}");
+    const moduleProviderFiles = await discoverModuleFiles("**/providers/*.{ts,js}");
+    files.push(...moduleFiles, ...moduleProviderFiles);
+  } catch {}
+
+  return [...new Set(files)].sort();
+}
+
+/**
+ * Why: Imports each discovered provider file so its registration runs.
+ * When: The loader runs.
+ * Where: Provider loader.
+ * How: Imports in sorted order; a broken file is logged and skipped instead of
+ *      taking the whole application down.
+ */
+async function loadProviderFiles(): Promise<number> {
+  const files = await collectProviderFiles();
+
+  for (const file of files) {
+    try {
+      await import(pathToFileURL(file).href);
+    } catch (error) {
+      logger.warn("Provider file failed to load", {
+        file,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+
+  return files.length;
+}
+
+/**
+ * Why: Runs the application's provider files exactly once.
+ * When: The kernel boots, and on the first provider lookup.
+ * Where: Kernel startup and the auth provider adapter.
+ * How: Caches the promise so repeated lookups cost nothing. A provider file
+ *      that itself asks for a provider during load gets an immediate answer
+ *      instead of deadlocking on its own load.
+ */
+export async function loadProviders(): Promise<number> {
+  if (loading) return 0;
+  if (!loadPromise) {
+    loading = true;
+    loadPromise = loadProviderFiles().finally(() => {
+      loading = false;
+    });
+  }
+  return loadPromise;
+}

package/fastify/src/framework/providers/registry.ts

@@ -0,0 +1,88 @@
+import {
+  AUTH_PROVIDER_KEY,
+  type AuthProvider,
+  NOTIFICATION_PROVIDER_KEY,
+  type NotificationProvider,
+  type ProviderKey
+} from "./contracts.js";
+
+/**
+ * Why: Holds the app-wide provider implementations in one place.
+ * When: A provider file in `src/providers/` (or a module's `providers.ts`)
+ *       registers its implementation at boot.
+ * Where: Read by the framework through `resolve*Provider()` helpers.
+ * How: A plain key/value map. No container, no decorators, no auto-wiring.
+ */
+const registry = new Map<string, unknown>();
+
+/**
+ * Why: Registers a provider implementation under a key.
+ * When: A provider file runs at boot and claims a contract.
+ * Where: Application code, through the framework facade.
+ * How: Stores the implementation and returns it so it can be inlined.
+ */
+export function registerProvider<T>(key: ProviderKey, implementation: T): T {
+  registry.set(key, implementation);
+  return implementation;
+}
+
+/** Returns the registered implementation for a key, or null when absent. */
+export function getProvider<T = unknown>(key: ProviderKey): T | null {
+  const found = registry.get(key);
+  return (found as T) ?? null;
+}
+
+/** Reports whether a provider is registered for a key. */
+export function hasProvider(key: ProviderKey): boolean {
+  return registry.has(key);
+}
+
+/** Removes a registered provider. Mainly useful in tests. */
+export function clearProvider(key: ProviderKey): void {
+  registry.delete(key);
+}
+
+/** Lists every registered provider key, sorted for stable output. */
+export function listProviders(): string[] {
+  return [...registry.keys()].sort();
+}
+
+/** Registers the auth provider that the framework's auth middleware uses. */
+export function registerAuthProvider(provider: AuthProvider): AuthProvider {
+  return registerProvider(AUTH_PROVIDER_KEY, provider);
+}
+
+/** Returns the registered auth provider, or null when none was registered. */
+export function getAuthProvider(): AuthProvider | null {
+  return getProvider<AuthProvider>(AUTH_PROVIDER_KEY);
+}
+
+/** Reports whether a custom auth provider is registered. */
+export function hasAuthProvider(): boolean {
+  return hasProvider(AUTH_PROVIDER_KEY);
+}
+
+/** Removes the registered auth provider. Mainly useful in tests. */
+export function clearAuthProvider(): void {
+  clearProvider(AUTH_PROVIDER_KEY);
+}
+
+/** Registers the storage provider `notify()` and `/api/notification/*` use. */
+export function registerNotificationProvider(provider: NotificationProvider): NotificationProvider {
+  return registerProvider(NOTIFICATION_PROVIDER_KEY, provider);
+}
+
+/** Returns the registered notification provider, or null when none was registered. */
+export function getNotificationProvider(): NotificationProvider | null {
+  return getProvider<NotificationProvider>(NOTIFICATION_PROVIDER_KEY);
+}
+
+/** Reports whether a notification provider is registered. */
+export function hasNotificationProvider(): boolean {
+  return hasProvider(NOTIFICATION_PROVIDER_KEY);
+}
+
+/** Removes the registered notification provider. Mainly useful in tests. */
+export function clearNotificationProvider(): void {
+  clearProvider(NOTIFICATION_PROVIDER_KEY);
+}

package/fastify/src/framework/queue/clear.ts

@@ -0,0 +1,22 @@
+import { clearQueue } from "@/framework/queue/queue.js";
+import { closeRedis, initRedis, redisError, redisReady } from "@/framework/redis/client.js";
+import { logger } from "@/framework/support/logger.js";
+
+/**
+ * Why: Clears Redis queue keys used by BullMQ runtime.
+ * When: CLI executes `queue:clear` maintenance command.
+ * Where: Framework queue maintenance script.
+ * How: Initializes Redis, skips safely if unavailable, then deletes prefixed keys.
+ */
+await initRedis();
+if (!redisReady()) {
+  logger.warn("Queue clear skipped because Redis is unavailable", {
+    error: redisError()
+  });
+  process.exit(0);
+}
+
+await clearQueue();
+console.log("Queue cleared");
+await closeRedis();
+process.exit(0);