create-nexwire 4.2.5 → 4.4.0

package/fastify/src/framework/database/connection.ts

@@ -0,0 +1,223 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { databaseConfig, detectDialectFrom } from "@/config/index.js";
+import { loadAppSchema } from "@/framework/database/app-schema.js";
+
+export type Dialect = "sqlite" | "mysql" | "postgresql";
+
+let databaseInstance: any;
+let pool: any;
+let dialect: Dialect;
+
+async function optionalImport<T = any>(name: string): Promise<T> {
+  return import(name) as Promise<T>;
+}
+
+/**
+ * Why: Resolves the active DB driver from DATABASE_URL.
+ * When: Called during bootstrap and dialect-specific branching.
+ * Where: Used by init/close and schema generation helpers.
+ * How: Checks DATABASE_URL prefix and maps to sqlite/mysql/postgresql.
+ */
+export function detectDialect(): Dialect {
+  return detectDialectFrom(databaseConfig.url);
+}
+
+/**
+ * Why: Creates a singleton Drizzle connection for the current dialect.
+ * When: Called once at app/worker/scheduler startup.
+ * Where: Framework bootstrap entry points.
+ * How: Builds dialect-specific pool/client and stores it in module state.
+ */
+export async function initDatabase() {
+  if (databaseInstance) return databaseInstance;
+
+  dialect = detectDialect();
+  const schema = await loadAppSchema();
+
+  // --- SQLite (libsql) ---
+  if (dialect === "sqlite") {
+    let drizzleSqlite: any;
+    let createClient: any;
+    try {
+      [{ drizzle: drizzleSqlite }, { createClient }] = await Promise.all([
+        optionalImport("drizzle-orm/libsql"),
+        optionalImport("@libsql/client")
+      ]);
+    } catch {
+      throw new Error("Missing sqlite dependencies. Install with: bun add drizzle-orm @libsql/client");
+    }
+
+    // databaseConfig.url is guaranteed to be "file:..."
+    const url = databaseConfig.url;
+
+    // Ensure the directory exists (skip for :memory: or absolute URLs)
+    if (!url.includes(":memory:")) {
+      const rawPath = url.replace(/^file:/i, "");
+      if (!rawPath.startsWith("//")) {
+        const file = path.resolve(process.cwd(), rawPath);
+        await fs.mkdir(path.dirname(file), { recursive: true });
+      }
+    }
+
+    pool = createClient({ url });
+    databaseInstance = drizzleSqlite(pool, { schema });
+    return databaseInstance;
+  }
+
+  // --- MySQL ---
+  if (dialect === "mysql") {
+    let drizzleMysql: any;
+    let mysql: any;
+    try {
+      [{ drizzle: drizzleMysql }, mysql] = await Promise.all([optionalImport("drizzle-orm/mysql2"), optionalImport("mysql2/promise")]);
+    } catch {
+      throw new Error("Missing mysql dependencies. Install with: bun add drizzle-orm mysql2");
+    }
+
+    pool = mysql.createPool({
+      uri: databaseConfig.url,
+      connectionLimit: databaseConfig.pool.max,
+      connectTimeout: databaseConfig.pool.connectTimeout,
+      enableKeepAlive: databaseConfig.pool.keepAlive,
+      ...(databaseConfig.ssl ? { ssl: {} } : {})
+    });
+
+    databaseInstance = drizzleMysql(pool, { schema, mode: "default" });
+    return databaseInstance;
+  }
+
+  // --- PostgreSQL ---
+  let drizzlePg: any;
+  let postgres: any;
+  try {
+    [{ drizzle: drizzlePg }, { default: postgres }] = await Promise.all([
+      optionalImport("drizzle-orm/postgres-js"),
+      optionalImport("postgres")
+    ]);
+  } catch {
+    throw new Error("Missing postgres dependencies. Install with: bun add drizzle-orm postgres");
+  }
+
+  pool = postgres(databaseConfig.url, {
+    max: databaseConfig.pool.max,
+    idle_timeout: Math.floor(databaseConfig.pool.idleTimeout / 1000),
+    connect_timeout: Math.floor(databaseConfig.pool.connectTimeout / 1000),
+    prepare: databaseConfig.prepare,
+    ...(databaseConfig.ssl ? { ssl: "require" as const } : {})
+  });
+
+  databaseInstance = drizzlePg(pool, { schema });
+  return databaseInstance;
+}
+
+/**
+ * Why: Returns initialized Drizzle instance for queries.
+ * When: Used by app code after bootstrap.
+ * Where: Facade `db` proxy and direct internal consumers.
+ * How: Throws if initDatabase has not completed.
+ */
+export function database() {
+  if (!databaseInstance) throw new Error("Database is not initialized");
+  return databaseInstance;
+}
+
+/**
+ * Why: Exposes low-level pool/client for advanced operations.
+ * When: Needed by internals that require native pool behavior.
+ * Where: Scheduler lock and infrastructure helpers.
+ * How: Returns shared pool and guards against uninitialized access.
+ */
+export function databasePool() {
+  if (!pool) throw new Error("Database pool is not initialized");
+  return pool;
+}
+
+/**
+ * Why: Gracefully closes DB resources during shutdown/reset flows.
+ * When: Server stop, worker stop, migration/reset commands.
+ * Where: Runtime lifecycle scripts.
+ * How: Detects dialect, closes pool, and clears singleton state.
+ */
+export async function closeDatabase() {
+  if (!pool) return;
+
+  const activeDialect = databaseDialect();
+
+  try {
+    if (activeDialect === "sqlite") {
+      await pool.close?.();
+    } else if (activeDialect === "mysql") {
+      await pool.end();
+    } else {
+      await pool.end();
+    }
+  } catch (error) {
+    console.error("Error closing database pool:", error);
+  } finally {
+    pool = undefined;
+    databaseInstance = undefined;
+  }
+}
+
+/**
+ * Why: Returns active dialect for conditional SQL/runtime behavior.
+ * When: Dialect-specific features are required.
+ * Where: Locking, schema, and shutdown helpers.
+ * How: Uses initialized dialect or falls back to detection.
+ */
+export function databaseDialect(): Dialect {
+  return dialect || detectDialect();
+}
+
+/**
+ * Why: Normalizes raw query results into a consistent { rows } shape.
+ * When: Drivers differ in what db.execute() returns:
+ *   - postgres-js / libsql return a plain array of rows
+ *   - mysql2 returns a [rows, fields] tuple
+ *   - pg node clients already wrap rows in { rows }
+ * Consumers across modules read `result.rows`.
+ * Where: Applied to every db.execute() call.
+ * How: Wraps arrays of row objects (and the mysql2 tuple) into { rows },
+ * leaves object shapes untouched.
+ */
+function normalizeExecuteResult(result: unknown): unknown {
+  if (Array.isArray(result)) {
+    if (result.length === 2 && Array.isArray(result[1])) {
+      return { rows: result[0], fields: result[1] };
+    }
+    const isRowList = result.length === 0 || result.every((row) => row != null && typeof row === "object" && !Array.isArray(row));
+    if (isRowList) {
+      return { rows: result };
+    }
+  }
+  return result;
+}
+
+/**
+ * Why: Provides ergonomic global query surface without calling database().
+ * When: Used by modules, seeders, and facade consumers.
+ * Where: Exposed via framework facade as `db`.
+ * How: Proxy forwards property access to the initialized Drizzle instance.
+ */
+export const db = new Proxy(
+  {},
+  {
+    get(_target, property) {
+      const instance = database();
+
+      if (property === "execute") {
+        return async (query: unknown, params?: unknown) => {
+          if (!instance.execute) {
+            throw new Error("The current driver does not support raw execute.");
+          }
+          const raw = await instance.execute(query, params);
+          return normalizeExecuteResult(raw);
+        };
+      }
+
+      const value = instance[property as keyof typeof instance];
+      return typeof value === "function" ? value.bind(instance) : value;
+    }
+  }
+) as any;

package/fastify/src/framework/database/migrate-hooks.ts

@@ -0,0 +1,87 @@
+import { sql } from "drizzle-orm";
+import { closeDatabase, database, databasePool, detectDialect, initDatabase } from "@/framework/database/connection.js";
+import { discoverModuleFiles, importFile } from "@/framework/modules/discover.js";
+
+type HookMap = {
+  __migrationSql: true;
+  postgresql?: string[];
+  mysql?: string[];
+  sqlite?: string[];
+};
+
+function isHookMap(value: unknown): value is HookMap {
+  if (!value || typeof value !== "object") return false;
+  return (value as HookMap).__migrationSql === true;
+}
+
+function collectStatements(exportsObj: Record<string, unknown>, dialect: "postgresql" | "mysql" | "sqlite") {
+  const statements: string[] = [];
+  for (const value of Object.values(exportsObj)) {
+    if (!isHookMap(value)) continue;
+    const sqlList = value[dialect] || [];
+    for (const statement of sqlList) {
+      if (typeof statement === "string" && statement.trim()) statements.push(statement);
+    }
+  }
+  return statements;
+}
+
+async function executeWithPoolFallback(statement: string, dialect: "postgresql" | "mysql" | "sqlite") {
+  const pool = databasePool();
+  if (dialect === "sqlite") {
+    await pool.executeMultiple(statement);
+    return;
+  }
+  if (dialect === "postgresql") {
+    await pool.unsafe(statement);
+    return;
+  }
+  await pool.query(statement);
+}
+
+async function executeStatement(statement: string, dialect: "postgresql" | "mysql" | "sqlite") {
+  const drizzle = database();
+  try {
+    if (dialect === "sqlite") {
+      await drizzle.run(sql.raw(statement));
+    } else {
+      await drizzle.execute(sql.raw(statement));
+    }
+  } catch {
+    await executeWithPoolFallback(statement, dialect);
+  }
+}
+
+export async function runModelMigrationHooks() {
+  const dialect = detectDialect();
+  const files = await discoverModuleFiles("**/database/models/*.{ts,js}");
+
+  await initDatabase();
+  try {
+    let applied = 0;
+    for (const file of files) {
+      const mod = await importFile(file);
+      const statements = collectStatements(mod, dialect);
+      if (!statements.length) continue;
+
+      for (const statement of statements) {
+        await executeStatement(statement, dialect);
+      }
+
+      applied += statements.length;
+    }
+
+    if (applied > 0) {
+      console.log(`Applied ${applied} model migration SQL statement(s) for ${dialect}.`);
+    }
+  } finally {
+    await closeDatabase();
+  }
+}
+
+if (process.argv[1]?.endsWith("migrate-hooks.ts")) {
+  runModelMigrationHooks().catch((error) => {
+    console.error("Failed to run model migration hooks:", error instanceof Error ? error.message : error);
+    process.exit(1);
+  });
+}

package/fastify/src/framework/database/paginate.ts

@@ -0,0 +1,226 @@
+import { count, getTableColumns, type SQL, sql } from "drizzle-orm";
+import { db } from "@/framework/database/connection.js";
+
+export type PaginatedResult<T> = {
+  current_page: number;
+  data: T[];
+  first_page_url: string | null;
+  from: number | null;
+  last_page: number;
+  last_page_url: string | null;
+  links: Array<{ url: string | null; label: string; page: number | null; active: boolean }>;
+  next_page_url: string | null;
+  path: string;
+  per_page: number;
+  prev_page_url: string | null;
+  to: number | null;
+  total: number;
+};
+
+type PaginateOptions = {
+  page?: number;
+  perPage?: number;
+  maxPerPage?: number;
+  path?: string;
+  where?: SQL<unknown>;
+  orderBy?: unknown[];
+};
+
+type RequestLike = {
+  query: any;
+  path?: string;
+  url?: string;
+};
+
+type PaginateQueryOptions<T> = {
+  page?: number;
+  perPage?: number;
+  maxPerPage?: number;
+  path?: string;
+  total: () => Promise<number>;
+  data: (limit: number, offset: number) => Promise<T[]>;
+};
+
+type PaginateModelOptions<T = any> = {
+  table?: any;
+  query?: { findMany: (args: Record<string, any>) => Promise<T[]> };
+  where?: SQL<unknown>;
+  with?: Record<string, any>;
+  columns?: Record<string, any>;
+  extras?: Record<string, any>;
+  orderBy?: unknown;
+  page?: number;
+  perPage?: number;
+  maxPerPage?: number;
+  path?: string;
+  total?: () => Promise<number>;
+  data?: (params: { limit: number; offset: number }) => Promise<T[]>;
+};
+
+function toPositiveInt(value: unknown, fallback: number) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 1) return fallback;
+  return Math.floor(parsed);
+}
+
+function pageUrl(path: string, page: number, perPage: number) {
+  if (!path) return null;
+  const delimiter = path.includes("?") ? "&" : "?";
+  return `${path}${delimiter}page=${page}&per_page=${perPage}`;
+}
+
+function resolvePath(req: RequestLike, path?: string) {
+  if (path) return path;
+  if (req.path) return req.path;
+  if (!req.url) return "";
+  try {
+    return new URL(req.url, "http://localhost").pathname;
+  } catch {
+    return req.url.split("?")[0];
+  }
+}
+
+export async function paginateQuery<T = any>(options: PaginateQueryOptions<T>): Promise<PaginatedResult<T>> {
+  const maxPerPage = toPositiveInt(options.maxPerPage, 100);
+  const perPage = Math.min(toPositiveInt(options.perPage, 15), maxPerPage);
+  const page = toPositiveInt(options.page, 1);
+
+  const total = Number(await options.total());
+  const lastPage = Math.max(1, Math.ceil(total / perPage));
+  const currentPage = Math.min(page, lastPage);
+  const safeOffset = (currentPage - 1) * perPage;
+  const data = await options.data(perPage, safeOffset);
+
+  const from = total === 0 ? null : safeOffset + 1;
+  const to = total === 0 ? null : safeOffset + data.length;
+  const path = options.path || "";
+  const firstPageUrl = pageUrl(path, 1, perPage);
+  const lastPageUrl = pageUrl(path, lastPage, perPage);
+  const prevPageUrl = currentPage > 1 ? pageUrl(path, currentPage - 1, perPage) : null;
+  const nextPageUrl = currentPage < lastPage ? pageUrl(path, currentPage + 1, perPage) : null;
+
+  const links: Array<{ url: string | null; label: string; page: number | null; active: boolean }> = [
+    {
+      url: prevPageUrl,
+      label: "&laquo; Previous",
+      page: currentPage > 1 ? currentPage - 1 : null,
+      active: false
+    }
+  ];
+
+  for (let p = 1; p <= lastPage; p += 1) {
+    links.push({
+      url: pageUrl(path, p, perPage),
+      label: String(p),
+      page: p,
+      active: p === currentPage
+    });
+  }
+
+  links.push({
+    url: nextPageUrl,
+    label: "Next &raquo;",
+    page: currentPage < lastPage ? currentPage + 1 : null,
+    active: false
+  });
+
+  return {
+    current_page: currentPage,
+    data,
+    first_page_url: firstPageUrl,
+    from,
+    last_page: lastPage,
+    last_page_url: lastPageUrl,
+    links,
+    next_page_url: nextPageUrl,
+    path,
+    per_page: perPage,
+    prev_page_url: prevPageUrl,
+    to,
+    total
+  };
+}
+
+export async function paginate<T = any>(
+  req: RequestLike,
+  query: any,
+  perPage = 15,
+  options: { maxPerPage?: number; path?: string } = {}
+): Promise<PaginatedResult<T>> {
+  const page = Number(req.query.page || 1);
+  const size = req.query.size;
+  const perPageQuery = req.query.per_page;
+  const perPageValue = Number(size || perPageQuery || perPage);
+  const resolvedPath = resolvePath(req, options.path);
+
+  return paginateQuery<T>({
+    page,
+    perPage: perPageValue,
+    maxPerPage: options.maxPerPage,
+    path: resolvedPath,
+    total: async () => {
+      const inner = db.select({ val: sql`1` }).from(query.as("_inner"));
+      const [row] = await db.select({ total: count() }).from(inner);
+      return Number(row?.total ?? 0);
+    },
+    data: (limit, offset) => query.limit(limit).offset(offset)
+  });
+}
+
+export async function paginateModel<T = any>(req: RequestLike, options: PaginateModelOptions<T>): Promise<PaginatedResult<T>> {
+  const page = Number(req.query.page || options.page || 1);
+  const size = req.query.size;
+  const perPageQuery = req.query.per_page;
+  const perPageValue = Number(size || perPageQuery || options.perPage || 15);
+  const resolvedPath = resolvePath(req, options.path);
+
+  return paginateQuery<T>({
+    page,
+    perPage: perPageValue,
+    maxPerPage: options.maxPerPage,
+    path: resolvedPath,
+    total: async () => {
+      if (options.total) return Number(await options.total());
+      if (!options.table) throw new Error("paginateModel requires either table or total callback");
+
+      let totalQuery = db.select({ total: count() }).from(options.table);
+      if (options.where) totalQuery = totalQuery.where(options.where);
+      const [row] = await totalQuery;
+      return Number(row?.total ?? 0);
+    },
+    data: async (limit, offset) => {
+      if (options.data) return options.data({ limit, offset });
+      if (!options.query) throw new Error("paginateModel requires either query or data callback");
+
+      const args: Record<string, any> = { limit, offset };
+      if (options.where) args.where = options.where;
+      if (options.with) args.with = options.with;
+      if (options.columns) args.columns = options.columns;
+      if (options.extras) args.extras = options.extras;
+      if (options.orderBy) args.orderBy = options.orderBy;
+
+      return options.query.findMany(args);
+    }
+  });
+}
+
+export async function paginateTable<T = any>(db: any, table: any, options: PaginateOptions = {}): Promise<PaginatedResult<T>> {
+  return paginateQuery<T>({
+    page: options.page,
+    perPage: options.perPage,
+    maxPerPage: options.maxPerPage,
+    path: options.path,
+    total: async () => {
+      let totalQuery = db.select({ total: count() }).from(table);
+      if (options.where) totalQuery = totalQuery.where(options.where);
+      const totalRow = await totalQuery;
+      return Number(totalRow[0]?.total ?? 0);
+    },
+    data: async (limit, offset) => {
+      let dataQuery = db.select(getTableColumns(table)).from(table);
+      if (options.where) dataQuery = dataQuery.where(options.where);
+      if (options.orderBy?.length) dataQuery = dataQuery.orderBy(...options.orderBy);
+      return dataQuery.limit(limit).offset(offset);
+    }
+  });
+}

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

@@ -0,0 +1,20 @@
+import { detectDialect } from "@/framework/database/connection.js";
+
+/**
+ * Why: Picks dialect-specific model exports from composite schema modules.
+ * When: Building generated schema for active DB dialect.
+ * Where: Maker/database schema generation pipeline.
+ * How: Filters objects containing sqlite/mysql/postgresql keys and selects current dialect.
+ */
+export function normalizeSchemaExports(source: Record<string, any>) {
+  const dialect = detectDialect();
+  const out: Record<string, any> = {};
+
+  for (const [key, value] of Object.entries(source)) {
+    if (value && typeof value === "object" && "sqlite" in value && "mysql" in value && "postgresql" in value) {
+      out[key] = value[dialect];
+    }
+  }
+
+  return out;
+}

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

@@ -0,0 +1,152 @@
+import { readFile } from "node:fs/promises";
+import { closeDatabase, initDatabase } from "@/framework/database/connection.js";
+import { discoverModuleFiles, importFile } from "@/framework/modules/discover.js";
+
+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) {
+    try {
+      const source = await readFile(file, "utf8");
+      const isUnfilledStub = !/^\s*export\s/m.test(source);
+      const mod = await importFile(file).catch((err: any) => {
+        console.warn(`[seed:skip] ${file}: ${err?.message || err}`);
+        return null as any;
+      });
+      if (!mod) continue;
+      if (typeof mod.default !== "function") {
+        if (isUnfilledStub) {
+          console.log(`Skipped unfilled seeder ${file} (no exports yet)`);
+          continue;
+        }
+        console.warn(`[seed:skip] ${file}: has no default export function`);
+        continue;
+      }
+      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);
+    } catch (err: any) {
+      console.warn(`[seed:skip] ${file}: ${err?.message || err}`);
+    }
+  }
+
+  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) {
+    try {
+      await s.execute();
+    } catch (err: any) {
+      console.warn(`[seed:skip] ${s.name} failed: ${err?.message || err}`);
+    }
+  }
+
+  console.log(`Executed ${sorted.length} seeder file(s)${moduleName ? ` for module ${moduleName}` : ""}`);
+} finally {
+  await closeDatabase();
+}