create-nexwire 4.2.1 → 4.2.3

package/hono/src/framework/facade.ts

@@ -1,29 +1,48 @@
-/**
- * Why: Central public API surface for framework consumers.
- * When: Modules/middlewares need framework utilities.
- * Where: App-layer imports should target this file.
- * How: Re-exports stable, reusable helpers while hiding setup internals.
- */
-
-export { createRoute, z } from "@hono/zod-openapi";
-export * as lodash from "lodash-es";
-export * as HttpStatusCodes from "stoker/http-status-codes";
-export { jsonContent } from "stoker/openapi/helpers";
-export { cache } from "@/framework/cache/cache.js";
-export { database, db } from "@/framework/database/connection.js";
-export { type PaginatedResult, paginate, paginateModel, paginateQuery, paginateTable } from "@/framework/database/paginate.js";
-export { command, dispatchCommand, dispatchEvent } from "@/framework/events/dispatcher.js";
-export { createRouter, group } from "@/framework/http/router.js";
-export { validate } from "@/framework/http/validation.js";
-export { notify } from "@/framework/notification/index.js";
-export { queue, queueJob, shouldQueue } from "@/framework/queue/queue.js";
-export { broadcast } from "@/framework/realtime/index.js";
-export { defineSchedule } from "@/framework/scheduler/scheduler.js";
-export { session } from "@/framework/session/session.js";
-export { storage } from "@/framework/storage/storage.js";
-export { cookie } from "@/framework/support/cookie.js";
-export { jwt } from "@/framework/support/jwt.js";
-export { logger } from "@/framework/support/logger.js";
-export { mail } from "@/framework/support/mail.js";
-export { password } from "@/framework/support/password.js";
-export { urls } from "@/framework/support/url.js";
+/**
+ * Why: Central public API surface for framework consumers.
+ * When: Modules/middlewares need framework utilities.
+ * Where: App-layer imports should target this file.
+ * How: Re-exports stable, reusable helpers while hiding setup internals.
+ */
+
+export { createRoute, z } from "@hono/zod-openapi";
+export * as lodash from "lodash-es";
+export * as HttpStatusCodes from "stoker/http-status-codes";
+export { jsonContent } from "stoker/openapi/helpers";
+export { cache } from "@/framework/cache/cache.js";
+export { database, db } from "@/framework/database/connection.js";
+export { type PaginatedResult, paginate, paginateModel, paginateQuery, paginateTable } from "@/framework/database/paginate.js";
+export { command, dispatchCommand, dispatchEvent } from "@/framework/events/dispatcher.js";
+export { createRouter, group } from "@/framework/http/router.js";
+export { validate } from "@/framework/http/validation.js";
+export { notify } from "@/framework/notification/index.js";
+export type {
+  AuthProvider,
+  AuthProviderRefreshToken,
+  AuthProviderUser,
+  AuthUserContact,
+  AuthUserContext
+} from "@/framework/providers/contracts.js";
+export { loadProviders } from "@/framework/providers/loader.js";
+export {
+  clearAuthProvider,
+  clearProvider,
+  getAuthProvider,
+  getProvider,
+  hasAuthProvider,
+  hasProvider,
+  listProviders,
+  registerAuthProvider,
+  registerProvider
+} from "@/framework/providers/registry.js";
+export { queue, queueJob, shouldQueue } from "@/framework/queue/queue.js";
+export { broadcast } from "@/framework/realtime/index.js";
+export { defineSchedule } from "@/framework/scheduler/scheduler.js";
+export { session } from "@/framework/session/session.js";
+export { storage } from "@/framework/storage/storage.js";
+export { cookie } from "@/framework/support/cookie.js";
+export { jwt } from "@/framework/support/jwt.js";
+export { logger } from "@/framework/support/logger.js";
+export { mail } from "@/framework/support/mail.js";
+export { password } from "@/framework/support/password.js";
+export { urls } from "@/framework/support/url.js";

package/hono/src/framework/kernel.ts

@@ -1,48 +1,50 @@
-import { appConfig } from "@/config/index.js";
-import { validateConfig } from "@/config/validate.js";
-import { initDatabase } from "@/framework/database/connection.js";
-import { createHttpApp } from "@/framework/http/app.js";
-import { ensurePublicDir, hasUiBuild, uiIndexMiddleware, uiStaticMiddleware } from "@/framework/http/static.js";
-import { registerModuleRoutes } from "@/framework/modules/routes.js";
-import { bootQueueJobs } from "@/framework/queue/queue.js";
-import { setupQueueDashboard } from "@/framework/queue/ui.js";
-import { initRedis } from "@/framework/redis/client.js";
-import { storage } from "@/framework/storage/storage.js";
-
-/**
- * Why: Assembles app kernel and boots all framework dependencies.
- * When: HTTP server startup.
- * Where: Called by server runtime entrypoint.
- * How: Initializes storage/db/redis/queues/events/routes and optional UI.
- */
-export async function createKernel() {
-  validateConfig();
-
-  await storage.init();
-
-  await initRedis();
-
-  const app = createHttpApp();
-
-  await initDatabase();
-  await bootQueueJobs();
-  await registerModuleRoutes(app);
-
-  const queueDashboard = await setupQueueDashboard();
-  if (typeof queueDashboard.route === "function") {
-    queueDashboard.route(app);
-  } else {
-    app.route(queueDashboard.basePath, queueDashboard.route);
-  }
-
-  if (appConfig.uiEnabled) {
-    ensurePublicDir();
-  }
-
-  if (appConfig.uiEnabled && hasUiBuild()) {
-    app.use("/*", uiStaticMiddleware);
-    app.get("/*", uiIndexMiddleware);
-  }
-
-  return { app, bullBoard: queueDashboard };
-}
+import { appConfig } from "@/config/index.js";
+import { validateConfig } from "@/config/validate.js";
+import { initDatabase } from "@/framework/database/connection.js";
+import { createHttpApp } from "@/framework/http/app.js";
+import { ensurePublicDir, hasUiBuild, uiIndexMiddleware, uiStaticMiddleware } from "@/framework/http/static.js";
+import { registerModuleRoutes } from "@/framework/modules/routes.js";
+import { loadProviders } from "@/framework/providers/loader.js";
+import { bootQueueJobs } from "@/framework/queue/queue.js";
+import { setupQueueDashboard } from "@/framework/queue/ui.js";
+import { initRedis } from "@/framework/redis/client.js";
+import { storage } from "@/framework/storage/storage.js";
+
+/**
+ * Why: Assembles app kernel and boots all framework dependencies.
+ * When: HTTP server startup.
+ * Where: Called by server runtime entrypoint.
+ * How: Initializes storage/db/redis/queues/events/routes and optional UI.
+ */
+export async function createKernel() {
+  validateConfig();
+
+  await storage.init();
+
+  await initRedis();
+
+  const app = createHttpApp();
+
+  await initDatabase();
+  await loadProviders();
+  await bootQueueJobs();
+  await registerModuleRoutes(app);
+
+  const queueDashboard = await setupQueueDashboard();
+  if (typeof queueDashboard.route === "function") {
+    queueDashboard.route(app);
+  } else {
+    app.route(queueDashboard.basePath, queueDashboard.route);
+  }
+
+  if (appConfig.uiEnabled) {
+    ensurePublicDir();
+  }
+
+  if (appConfig.uiEnabled && hasUiBuild()) {
+    app.use("/*", uiStaticMiddleware);
+    app.get("/*", uiIndexMiddleware);
+  }
+
+  return { app, bullBoard: queueDashboard };
+}

package/hono/src/framework/maker-cli/index.mjs

@@ -5,6 +5,7 @@ import { config } from "dotenv";
 import { registerDbCommands } from "./db/index.mjs";
 import { registerMiddlewareCommands } from "./middleware/index.mjs";
 import { registerModuleCommands } from "./module/index.mjs";
+import { registerProviderCommands } from "./provider/index.mjs";
 import { registerRuntimeCommands } from "./runtime/index.mjs";
 import { configureGroupedHelp, makerCommandPrefix, showHelp } from "./utils/help.mjs";
 import { registerProjectCommands } from "./utils/project-commands.mjs";
@@ -42,6 +43,7 @@ try {
 
   registerMiddlewareCommands(program, args);
   registerModuleCommands(program, args);
+  registerProviderCommands(program, args);
   registerDeployCommands(program, args);
   registerDbCommands(program, args);
   registerRuntimeCommands(program, args);

package/hono/src/framework/maker-cli/module/core.mjs

@@ -45,6 +45,11 @@ const STUBS = {
   facade: {
     named: "facade/name.ts.stub"
   },
+  provider: {
+    named: "provider/name.ts.stub",
+    module: "provider/module.ts.stub",
+    moduleBarrel: "provider/module-barrel.ts.stub"
+  },
   helper: {
     named: "helper/name.ts.stub"
   },
@@ -736,6 +741,31 @@ export async function makeLocalMiddleware(rawModule, rawNameOrFlag, extraFlags =
   await writeFileSafe(path.join(root, `middlewares/${name}.ts`), content, flags, "Middleware file");
 }
 
+/**
+ * Generate a provider file for an existing module.
+ *
+ * The file lands in the module's providers/ folder, which the framework
+ * imports at boot just like src/providers/. That is what lets a module offer
+ * an implementation to the whole application without the application knowing
+ * anything about the module's internals.
+ */
+export async function makeModuleProvider(rawModule, rawNameOrFlag, extraFlags = []) {
+  const { moduleName, leaf } = resolveModuleRef(rawModule, rawNameOrFlag, extraFlags);
+  const { name, flags } = parseNameArg(rawNameOrFlag, extraFlags, "Provider name", leaf);
+  const root = await assertModuleExists(moduleName);
+  const filePath = path.join(root, `providers/${name}.ts`);
+  if (hasFlag(flags, "--dry-run")) {
+    console.log(`Would create provider file: ${path.relative(process.cwd(), filePath)}`);
+    return;
+  }
+  const content = await stub(STUBS.provider.module, {
+    module: moduleName,
+    name,
+    camel: camelCase(name)
+  });
+  await writeFileSafe(filePath, content, flags, "Provider file");
+}
+
 /** Generate a types file for an existing module. */
 export async function makeType(rawModule, rawNameOrFlag, extraFlags = []) {
   const { moduleName, leaf } = resolveModuleRef(rawModule, rawNameOrFlag, extraFlags);

package/hono/src/framework/maker-cli/module/index.mjs

@@ -12,6 +12,7 @@ import {
   makeLocalMiddleware,
   makeModel,
   makeModule,
+  makeModuleProvider,
   makeModules,
   makeNotificationModule,
   makeRoute,
@@ -28,7 +29,7 @@ import {
 export function registerModuleCommands(program, rawArgs) {
   program
     .command("module:make <names...>")
-    .description("Create one or more modules with facade, schema, service, controller, route, model, and seeder folders")
+    .description("Create one or more modules with facade, providers, schema, service, controller, route, model, and seeder folders")
     .option("--path <panel>", "Nest the module(s) under a panel folder (e.g. --path=admin)")
     .option("--force", "Overwrite the files of modules that already exist")
     .allowUnknownOption(true)
@@ -128,6 +129,14 @@ export function registerModuleCommands(program, rawArgs) {
     .option("--path <panel>", "Address a module inside a panel folder (e.g. --path=admin)")
     .allowUnknownOption(true)
     .action(async (moduleName, name) => makeLocalMiddleware(moduleName, name, rawArgs.slice(name ? 3 : 2)));
+  program
+    .command("module:make-provider <module> [name]")
+    .description("Generate a provider file in the module's providers folder")
+    .option("--force", "Overwrite existing provider file")
+    .option("--dry-run", "Print what would be created without executing")
+    .option("--path <panel>", "Address a module inside a panel folder (e.g. --path=admin)")
+    .allowUnknownOption(true)
+    .action(async (moduleName, name) => makeModuleProvider(moduleName, name, rawArgs.slice(name ? 3 : 2)));
   program
     .command("module:make-type <module> [name]")
     .description("Generate a types file for an existing module")

package/hono/src/framework/maker-cli/provider/core.mjs

@@ -0,0 +1,49 @@
+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, "");
+}
+
+/**
+ * Why: Generates the app-wide provider file.
+ * When: A developer wants to plug an implementation into the whole app.
+ * Where: src/providers/<name>.ts - imported automatically at boot.
+ * How: Writes the stub and prints how to reach the provider from anywhere.
+ */
+export async function makeProvider(rawName, flags = []) {
+  const name = assertName(rawName, "Provider 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/providers", `${name}.ts`);
+  if (dryRun) {
+    console.log(`Would create provider file: ${path.relative(process.cwd(), filePath)}`);
+    return;
+  }
+
+  let exists = false;
+  try {
+    await fs.access(filePath);
+    exists = true;
+  } catch {}
+  if (exists && !force) {
+    throw new Error(`Provider already exists: ${path.relative(process.cwd(), filePath)}. Re-run with --force to overwrite.`);
+  }
+
+  const content = await stub("provider/name.ts.stub", { name, camel });
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, content);
+  console.log(`Provider ready: ${path.relative(process.cwd(), filePath)}`);
+  console.log(`It is imported at boot. Reach it with: getProvider("${name}")`);
+}

package/hono/src/framework/maker-cli/provider/index.mjs

@@ -0,0 +1,12 @@
+import { makeProvider } from "./core.mjs";
+
+/** Register provider:* subcommands on the CLI program. */
+export function registerProviderCommands(program, rawArgs) {
+  program
+    .command("provider:make <name>")
+    .description("Generate a provider file in src/providers")
+    .option("--force", "Overwrite existing provider file")
+    .option("--dry-run", "Print what would be created without executing")
+    .allowUnknownOption(true)
+    .action(async (name) => makeProvider(name, rawArgs.filter((arg) => arg.startsWith("--"))));
+}

package/hono/src/framework/maker-cli/stubs/notification/controller.ts.stub

@@ -1,86 +1,86 @@
-import type { Handler } from "hono";
-import { and, count, desc, eq, sql } from "drizzle-orm";
-import { db } from "@/framework/facade.js";
-import { notifications } from "@/modules/auth/database/models/notifications.js";
-
-export const list: Handler = async (c: any) => {
-  const userId = c.get("auth").id;
-  const page = Math.max(1, Number(c.req.query("page")) || 1);
-  const perPage = Math.min(50, Math.max(1, Number(c.req.query("perPage")) || 20));
-
-  const unread = await db.select({ count: count() }).from(notifications)
-    .where(and(eq(notifications.userId, userId), sql`${notifications.readAt} IS NULL`));
-
-  const total = await db.select({ count: count() }).from(notifications)
-    .where(eq(notifications.userId, userId));
-
-  const rows = await db.select().from(notifications)
-    .where(eq(notifications.userId, userId))
-    .orderBy(desc(notifications.createdAt))
-    .limit(perPage).offset((page - 1) * perPage);
-
-  return c.json({
-    data: rows.map(normalize),
-    total: total[0].count,
-    unread: unread[0].count,
-    page,
-    perPage,
-  });
-};
-
-export const unreadCount: Handler = async (c: any) => {
-  const userId = c.get("auth").id;
-  const rows = await db.select({ count: count() }).from(notifications)
-    .where(and(eq(notifications.userId, userId), sql`${notifications.readAt} IS NULL`));
-  return c.json({ count: rows[0].count });
-};
-
-export const markRead: Handler = async (c: any) => {
-  const userId = c.get("auth").id;
-  const id = Number(c.req.param("id"));
-
-  await db.update(notifications)
-    .set({ readAt: sql`now()` })
-    .where(and(eq(notifications.id, id), eq(notifications.userId, userId)));
-
-  return c.json({ ok: true });
-};
-
-export const markAllRead: Handler = async (c: any) => {
-  const userId = c.get("auth").id;
-
-  await db.update(notifications)
-    .set({ readAt: sql`now()` })
-    .where(and(eq(notifications.userId, userId), sql`${notifications.readAt} IS NULL`));
-
-  return c.json({ ok: true });
-};
-
-export const remove: Handler = async (c: any) => {
-  const userId = c.get("auth").id;
-  const id = Number(c.req.param("id"));
-
-  await db.delete(notifications)
-    .where(and(eq(notifications.id, id), eq(notifications.userId, userId)));
-
-  return c.json({ ok: true });
-};
-
-function normalize(row: typeof notifications.$inferSelect) {
-  let parsed: unknown = null;
-  if (row.data) {
-    try { parsed = JSON.parse(row.data); } catch {}
-  }
-  return {
-    id: row.id,
-    userId: row.userId,
-    type: row.type,
-    title: row.title,
-    body: row.body,
-    data: parsed,
-    link: row.link,
-    readAt: row.readAt?.toISOString() || null,
-    createdAt: row.createdAt.toISOString(),
-  };
-}
+import type { Handler } from "hono";
+import { and, count, desc, eq, sql } from "drizzle-orm";
+import { db } from "@/framework/facade.js";
+import { notifications } from "@/modules/auth/database/models/notification.js";
+
+export const list: Handler = async (c: any) => {
+  const userId = c.get("auth").id;
+  const page = Math.max(1, Number(c.req.query("page")) || 1);
+  const perPage = Math.min(50, Math.max(1, Number(c.req.query("perPage")) || 20));
+
+  const unread = await db.select({ count: count() }).from(notifications)
+    .where(and(eq(notifications.userId, userId), sql`${notifications.readAt} IS NULL`));
+
+  const total = await db.select({ count: count() }).from(notifications)
+    .where(eq(notifications.userId, userId));
+
+  const rows = await db.select().from(notifications)
+    .where(eq(notifications.userId, userId))
+    .orderBy(desc(notifications.createdAt))
+    .limit(perPage).offset((page - 1) * perPage);
+
+  return c.json({
+    data: rows.map(normalize),
+    total: total[0].count,
+    unread: unread[0].count,
+    page,
+    perPage,
+  });
+};
+
+export const unreadCount: Handler = async (c: any) => {
+  const userId = c.get("auth").id;
+  const rows = await db.select({ count: count() }).from(notifications)
+    .where(and(eq(notifications.userId, userId), sql`${notifications.readAt} IS NULL`));
+  return c.json({ count: rows[0].count });
+};
+
+export const markRead: Handler = async (c: any) => {
+  const userId = c.get("auth").id;
+  const id = Number(c.req.param("id"));
+
+  await db.update(notifications)
+    .set({ readAt: sql`now()` })
+    .where(and(eq(notifications.id, id), eq(notifications.userId, userId)));
+
+  return c.json({ ok: true });
+};
+
+export const markAllRead: Handler = async (c: any) => {
+  const userId = c.get("auth").id;
+
+  await db.update(notifications)
+    .set({ readAt: sql`now()` })
+    .where(and(eq(notifications.userId, userId), sql`${notifications.readAt} IS NULL`));
+
+  return c.json({ ok: true });
+};
+
+export const remove: Handler = async (c: any) => {
+  const userId = c.get("auth").id;
+  const id = Number(c.req.param("id"));
+
+  await db.delete(notifications)
+    .where(and(eq(notifications.id, id), eq(notifications.userId, userId)));
+
+  return c.json({ ok: true });
+};
+
+function normalize(row: typeof notifications.$inferSelect) {
+  let parsed: unknown = null;
+  if (row.data) {
+    try { parsed = JSON.parse(row.data); } catch {}
+  }
+  return {
+    id: row.id,
+    userId: row.userId,
+    type: row.type,
+    title: row.title,
+    body: row.body,
+    data: parsed,
+    link: row.link,
+    readAt: row.readAt?.toISOString() || null,
+    createdAt: row.createdAt.toISOString(),
+  };
+}
 

package/hono/src/framework/maker-cli/stubs/provider/module-barrel.ts.stub

@@ -0,0 +1,19 @@
+/**
+ * Providers for the {{module}} module.
+ *
+ * This file is imported automatically at boot, so whatever it registers is
+ * available to the whole application. Use this to plug implementations (e.g.
+ * auth, payments) into the app - not to export the module's API to other
+ * modules (that is what facade.ts is for):
+ *
+ *   import { registerProvider } from "@/framework/facade.js";
+ *
+ *   registerProvider("{{module}}", { ... });
+ *
+ * A module with more than one provider keeps them in providers/*.ts instead -
+ * those files are imported at boot too.
+ *
+ * Rule: a module never imports another module's provider implementation.
+ */
+
+export {};

package/hono/src/framework/maker-cli/stubs/provider/module.ts.stub

@@ -0,0 +1,21 @@
+import { registerProvider } from "@/framework/facade.js";
+
+/**
+ * Why: Plugs the {{name}} implementation into the application.
+ * When: Imported automatically at boot from each module's providers folder.
+ * Where: src/modules/{{module}}/providers/{{name}}.ts
+ *
+ * Reach it from anywhere in the app:
+ *
+ *   import { getProvider } from "@/framework/facade.js";
+ *   const {{camel}} = getProvider<typeof {{camel}}Provider>("{{name}}");
+ *
+ * Rule: a provider never imports another module's provider implementation.
+ */
+export const {{camel}}Provider = {
+  async handle(input: unknown) {
+    return input;
+  }
+};
+
+registerProvider("{{name}}", {{camel}}Provider);

package/hono/src/framework/maker-cli/stubs/provider/name.ts.stub

@@ -0,0 +1,21 @@
+import { registerProvider } from "@/framework/facade.js";
+
+/**
+ * Why: Plugs the {{name}} implementation into the application.
+ * When: Imported automatically at boot from src/providers/.
+ * Where: src/providers/{{name}}.ts
+ *
+ * Reach it from anywhere in the app:
+ *
+ *   import { getProvider } from "@/framework/facade.js";
+ *   const {{camel}} = getProvider<typeof {{camel}}Provider>("{{name}}");
+ *
+ * Rule: a provider never imports another provider's implementation.
+ */
+export const {{camel}}Provider = {
+  async handle(input: unknown) {
+    return input;
+  }
+};
+
+registerProvider("{{name}}", {{camel}}Provider);

package/hono/src/framework/maker-cli/utils/help.mjs

@@ -89,7 +89,11 @@ const COMMAND_GROUPS = [
     // `module:make-middleware` writes inside one module and applies only to it.
     // In the same section the two look interchangeable, which is exactly the
     // mistake a developer is about to make.
-    commands: ["middleware:make"]
+    //
+    // `provider:make` follows the same split: it writes to src/providers and
+    // applies to the whole app, `module:make-provider` writes inside one
+    // module and applies only to it.
+    commands: ["middleware:make", "provider:make"]
   },
   {
     title: "Generators - modules",
@@ -107,6 +111,7 @@ const COMMAND_GROUPS = [
       "module:make-test",
       "module:make-helper",
       "module:make-middleware",
+      "module:make-provider",
       "module:make-type"
     ]
   },