create-nexgen 1.0.4

package/template/src/framework/maker-cli/stubs/notification/index.vue.stub

@@ -0,0 +1,211 @@
+<template>
+  <Pagebar title="Notifications" />
+  <Refresh @click="fetchList" />
+
+  <div class="notifications-page">
+    <div class="card">
+      <div class="card-header d-flex align-items-center justify-content-between">
+        <div class="d-flex align-items-center gap-2">
+          <i class="bi bi-bell"></i>
+          <span class="fw-semibold">All Notifications</span>
+          <span v-if="unread > 0" class="badge bg-danger">{{ unread }} unread</span>
+        </div>
+        <div class="d-flex gap-2">
+          <button v-if="unread > 0" class="btn btn-sm btn-outline-primary" @click="markAllRead">
+            <i class="bi bi-check-all"></i> Mark all read
+          </button>
+        </div>
+      </div>
+      <div class="card-body p-0">
+        <div v-if="loading" class="text-center py-5">
+          <div class="spinner-border" role="status"></div>
+        </div>
+        <div v-else-if="items.length === 0" class="text-center text-secondary py-5">
+          <i class="bi bi-bell-slash fs-1 d-block mb-2"></i>
+          No notifications yet
+        </div>
+        <div v-else>
+          <div
+            v-for="item in items"
+            :key="item.id"
+            class="notification-row"
+            :class="{ unread: !item.readAt }">
+            <div class="d-flex align-items-start gap-3 px-3 py-3">
+              <i :class="iconClass(item.type)" class="fs-5 mt-1"></i>
+              <div class="flex-grow-1 min-w-0">
+                <div class="notification-title">{{ item.title }}</div>
+                <div v-if="item.body" class="notification-body mt-1">{{ item.body }}</div>
+                <div class="notification-meta mt-1">
+                  <span class="notification-time">{{ formatDate(item.createdAt) }}</span>
+                </div>
+              </div>
+              <div class="d-flex gap-1 flex-shrink-0">
+                <button
+                  v-if="!item.readAt"
+                  class="btn btn-sm btn-outline-secondary"
+                  title="Mark as read"
+                  @click="markRead(item)">
+                  <i class="bi bi-check"></i>
+                </button>
+                <button
+                  class="btn btn-sm btn-outline-danger"
+                  title="Delete"
+                  @click="remove(item)">
+                  <i class="bi bi-trash"></i>
+                </button>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+      <div v-if="total > perPage" class="card-footer d-flex justify-content-center">
+        <nav>
+          <ul class="pagination pagination-sm mb-0">
+            <li class="page-item" :class="{ disabled: page <= 1 }">
+              <button class="page-link" @click="goPage(page - 1)">Previous</button>
+            </li>
+            <li class="page-item" :class="{ disabled: page >= maxPage }">
+              <button class="page-link" @click="goPage(page + 1)">Next</button>
+            </li>
+          </ul>
+        </nav>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, computed, onMounted, onUnmounted } from "vue";
+import { useHead } from "@vueuse/head";
+import axios from "@/plugins/axios";
+import { pulse } from "@/plugins/pulse";
+import { useAuth } from "@/composables/useAuth";
+import Pagebar from "@/components/Pagebar.vue";
+import Refresh from "@/components/Refresh.vue";
+
+useHead({ title: "Notifications" });
+
+const { user } = useAuth();
+
+const items = ref<any[]>([]);
+const loading = ref(true);
+const page = ref(1);
+const perPage = ref(20);
+const total = ref(0);
+const unread = ref(0);
+
+const maxPage = computed(() => Math.max(1, Math.ceil(total.value / perPage.value)));
+
+function iconClass(type: string) {
+  const map: Record<string, string> = {
+    info: "bi bi-info-circle text-primary",
+    success: "bi bi-check-circle text-success",
+    warning: "bi bi-exclamation-triangle text-warning",
+    error: "bi bi-x-circle text-danger",
+  };
+  return map[type] || "bi bi-bell text-secondary";
+}
+
+function formatDate(dateStr: string) {
+  const d = new Date(dateStr);
+  return d.toLocaleDateString() + " " + d.toLocaleTimeString();
+}
+
+async function fetchList() {
+  loading.value = true;
+  try {
+    const res = await axios.get(`/api/{{module}}?page=${page.value}&perPage=${perPage.value}`);
+    items.value = res.data.data;
+    total.value = res.data.total;
+    unread.value = res.data.unread;
+  } catch {}
+  loading.value = false;
+}
+
+async function markRead(item: any) {
+  try {
+    await axios.patch(`/api/{{module}}/${item.id}/read`);
+    item.readAt = new Date().toISOString();
+    unread.value = Math.max(0, unread.value - 1);
+  } catch {}
+}
+
+async function markAllRead() {
+  try {
+    await axios.patch("/api/{{module}}/read-all");
+    items.value.forEach((n) => (n.readAt = new Date().toISOString()));
+    unread.value = 0;
+  } catch {}
+}
+
+async function remove(item: any) {
+  try {
+    await axios.delete(`/api/{{module}}/${item.id}`);
+    items.value = items.value.filter((n) => n.id !== item.id);
+    if (!item.readAt) unread.value = Math.max(0, unread.value - 1);
+  } catch {}
+}
+
+function goPage(p: number) {
+  page.value = Math.max(1, Math.min(p, maxPage.value));
+  fetchList();
+}
+
+let cleanup: (() => void) | null = null;
+
+onMounted(async () => {
+  await fetchList();
+
+  if (user.value) {
+    const channel = pulse.channel(`user:${user.value.id}`);
+    channel.listen("notification.created", (payload: any) => {
+      items.value.unshift(payload);
+      unread.value++;
+    });
+    cleanup = () => channel.stopListening("notification.created");
+  }
+});
+
+onUnmounted(() => {
+  cleanup?.();
+});
+</script>
+
+<style scoped>
+.notifications-page {
+  padding: 0.5rem;
+}
+
+.notification-row {
+  border-bottom: 1px solid var(--app-border);
+  transition: background 0.15s;
+}
+
+.notification-row:hover {
+  background: var(--app-surface);
+}
+
+.notification-row.unread {
+  background: rgba(var(--bs-primary-rgb), 0.04);
+}
+
+.notification-title {
+  font-weight: 500;
+}
+
+.notification-body {
+  font-size: 0.9rem;
+  color: var(--bs-secondary-color);
+}
+
+.notification-time {
+  font-size: 0.8rem;
+  color: var(--bs-secondary-color);
+}
+
+@media (max-width: 768px) {
+  .notifications-page {
+    padding: 0;
+  }
+}
+</style>

package/template/src/framework/maker-cli/stubs/notification/job.ts.stub

@@ -0,0 +1,12 @@
+import { mail } from "@/framework/support/mail.js";
+import { logger } from "@/framework/support/logger.js";
+import { shouldQueue } from "@/framework/queue/queue.js";
+
+shouldQueue("{{module}}:mail", "mail", async (job) => {
+  const { to, subject, html } = job.data;
+
+  await mail.sendMail({ to, subject, html });
+  logger.info("Notification mail sent", { to, subject });
+
+  return { ok: true };
+});

package/template/src/framework/maker-cli/stubs/notification/route.api.ts.stub

@@ -0,0 +1,49 @@
+import { createRoute, createRouter, HttpStatusCodes, jsonContent, z } from "@/framework/facade.js";
+import { authMiddleware } from "@/middlewares/auth-middleware.js";
+import { list, unreadCount, markRead, markAllRead, remove } from "../controllers/{{module}}.controller.js";
+import { PaginatedNotificationsSchema, UnreadCountSchema } from "../controllers/{{module}}.schema.js";
+
+const listRoute = createRoute({
+  path: "/",
+  method: "get",
+  tags: ["Notifications"],
+  responses: { [HttpStatusCodes.OK]: jsonContent(PaginatedNotificationsSchema, "Paginated notifications") },
+});
+
+const unreadCountRoute = createRoute({
+  path: "/unread-count",
+  method: "get",
+  tags: ["Notifications"],
+  responses: { [HttpStatusCodes.OK]: jsonContent(UnreadCountSchema, "Unread count") },
+});
+
+const markReadRoute = createRoute({
+  path: "/{id}/read",
+  method: "patch",
+  tags: ["Notifications"],
+  request: { params: z.object({ id: z.coerce.number() }) },
+  responses: { [HttpStatusCodes.OK]: jsonContent(z.object({ ok: z.boolean() }), "Marked as read") },
+});
+
+const markAllReadRoute = createRoute({
+  path: "/read-all",
+  method: "patch",
+  tags: ["Notifications"],
+  responses: { [HttpStatusCodes.OK]: jsonContent(z.object({ ok: z.boolean() }), "All marked as read") },
+});
+
+const deleteRoute = createRoute({
+  path: "/{id}",
+  method: "delete",
+  tags: ["Notifications"],
+  request: { params: z.object({ id: z.coerce.number() }) },
+  responses: { [HttpStatusCodes.OK]: jsonContent(z.object({ ok: z.boolean() }), "Deleted") },
+});
+
+export default createRouter()
+  .group(authMiddleware)
+  .api(listRoute, list)
+  .api(unreadCountRoute, unreadCount)
+  .api(markReadRoute, markRead)
+  .api(markAllReadRoute, markAllRead)
+  .api(deleteRoute, remove);

package/template/src/framework/maker-cli/stubs/notification/schema.ts.stub

@@ -0,0 +1,25 @@
+import { z } from "@hono/zod-openapi";
+
+export const NotificationSchema = z.object({
+  id: z.number(),
+  userId: z.number(),
+  type: z.string(),
+  title: z.string(),
+  body: z.string().nullable(),
+  data: z.any().nullable(),
+  link: z.string().nullable(),
+  readAt: z.string().nullable(),
+  createdAt: z.string(),
+});
+
+export const UnreadCountSchema = z.object({
+  count: z.number(),
+});
+
+export const PaginatedNotificationsSchema = z.object({
+  data: z.array(NotificationSchema),
+  total: z.number(),
+  unread: z.number(),
+  page: z.number(),
+  perPage: z.number(),
+});

package/template/src/framework/maker-cli/stubs/route/api.ts.stub

@@ -0,0 +1,79 @@
+import { createRoute, group, HttpStatusCodes, jsonContent } from "@/framework/facade.js";
+import { requireRole } from "@/middlewares/role-middleware.js";
+import { index, show, store, update, destroy } from "@/modules/{{module}}/controllers/{{controller}}.controller.js";
+import {
+  Create{{ClassName}}Schema,
+  Update{{ClassName}}Schema,
+  {{ClassName}}IdParamsSchema,
+  {{ClassName}}ListResponseSchema,
+  {{ClassName}}MessageSchema,
+  {{ClassName}}ResponseSchema
+} from "@/modules/{{module}}/controllers/{{controller}}.schema.js";
+
+const indexRoute = createRoute({
+  path: "/",
+  method: "get",
+  tags: ["{{ModuleClass}}"],
+  responses: {
+    [HttpStatusCodes.OK]: jsonContent({{ClassName}}ListResponseSchema, "{{module}} list")
+  }
+});
+
+const showRoute = createRoute({
+  path: "/{id}",
+  method: "get",
+  tags: ["{{ModuleClass}}"],
+  request: {
+    params: {{ClassName}}IdParamsSchema
+  },
+  responses: {
+    [HttpStatusCodes.OK]: jsonContent({{ClassName}}ResponseSchema, "{{module}} item"),
+    [HttpStatusCodes.NOT_FOUND]: jsonContent({{ClassName}}MessageSchema, "Not found")
+  }
+});
+
+const storeRoute = createRoute({
+  path: "/",
+  method: "post",
+  tags: ["{{ModuleClass}}"],
+  request: {
+    body: jsonContent(Create{{ClassName}}Schema, "Create {{module}} payload")
+  },
+  responses: {
+    [HttpStatusCodes.CREATED]: jsonContent({{ClassName}}MessageSchema, "Created")
+  }
+});
+
+const updateRoute = createRoute({
+  path: "/{id}",
+  method: "put",
+  tags: ["{{ModuleClass}}"],
+  request: {
+    params: {{ClassName}}IdParamsSchema,
+    body: jsonContent(Update{{ClassName}}Schema, "Update {{module}} payload")
+  },
+  responses: {
+    [HttpStatusCodes.OK]: jsonContent({{ClassName}}MessageSchema, "Updated"),
+    [HttpStatusCodes.NOT_FOUND]: jsonContent({{ClassName}}MessageSchema, "Not found")
+  }
+});
+
+const destroyRoute = createRoute({
+  path: "/{id}",
+  method: "delete",
+  tags: ["{{ModuleClass}}"],
+  request: {
+    params: {{ClassName}}IdParamsSchema
+  },
+  responses: {
+    [HttpStatusCodes.OK]: jsonContent({{ClassName}}MessageSchema, "Deleted"),
+    [HttpStatusCodes.NOT_FOUND]: jsonContent({{ClassName}}MessageSchema, "Not found")
+  }
+});
+
+export default group()
+  .api(indexRoute, index)
+  .api(showRoute, show)
+  .api(storeRoute, store)
+  .api(updateRoute, update)
+  .api(destroyRoute, destroy);

package/template/src/framework/maker-cli/stubs/route/plain.ts.stub

@@ -0,0 +1,10 @@
+import { group } from "@/framework/facade.js";
+import { requireRole } from "@/middlewares/role-middleware.js";
+import { index, show, store, update, destroy } from "@/modules/{{module}}/controllers/{{controller}}.controller.js";
+
+export default group()
+  .get("/", index)
+  .get("/:id", show)
+  .post("/", store)
+  .put("/:id", update)
+  .delete("/:id", destroy);

package/template/src/framework/maker-cli/stubs/schedule/name.ts.stub

@@ -0,0 +1,35 @@
+import { DateTime } from "luxon";
+import { defineSchedule, dispatchEvent } from "@/framework/facade.js";
+
+/**
+ * name: Unique schedule id used as the distributed lock key.
+ * expression: Cron expression that controls when the task runs.
+ * timezone: IANA timezone for cron evaluation (example: "UTC").
+ * runOnInit: Runs once immediately when scheduler starts.
+ * enabled: Enables or disables this schedule without deleting code.
+ * ttlMs: Lock TTL in milliseconds to avoid duplicate execution.
+ */
+defineSchedule({
+  name: "{{module}}:{{name}}",
+  expression: "0 * * * * *",
+  // timezone: "UTC",
+  // runOnInit: false,
+  // enabled: true,
+  // ttlMs: 120000,
+  handler: async () => {
+    /**
+     * dispatchEvent name: Event id to publish to listeners.
+     * payload: Data sent to queue/broadcast consumers.
+     * queue: Optional queue target for async event consumers.
+     * broadcast: Optional realtime fanout (all/users/roles/rooms).
+     */
+    // await dispatchEvent("{{module}}.{{name}}", {
+    //   origin: "scheduler",
+    //   createdAt: DateTime.now()
+    // }, {
+    //   queue: "default"
+    // });
+
+    DateTime.now().toISO();
+  }
+});

package/template/src/framework/maker-cli/stubs/seeder/name.ts.stub

@@ -0,0 +1,17 @@
+import { db } from "@/framework/facade.js";
+import { {{tableVariable}} } from "@/modules/{{module}}/database/models/{{name}}.js";
+
+export default async function {{ClassName}}Seeder() {
+  const rows = [
+    // Add your seed data here
+    // Example:
+    // { name: "{{ClassName}} 1", description: "This is the first {{name}}" },
+    // { name: "{{ClassName}} 2", description: "This is the second {{name}}" }
+  ];
+
+  for (const row of rows) {
+    await db.insert({{tableVariable}}).values(row);
+  }
+
+  console.log("{{ClassName}} seeder completed");
+}

package/template/src/framework/modules/discover.ts

@@ -0,0 +1,54 @@
+import { glob } from "glob";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+function resolveModulesPath() {
+  const cwd = process.cwd();
+  const srcModules = path.resolve(cwd, "src/modules");
+  const distModules = path.resolve(cwd, "dist/src/modules");
+  const entry = String(process.argv[1] || "");
+  const runningDist = /[\\/]dist[\\/]/.test(entry);
+
+  if (runningDist && fs.existsSync(distModules)) return distModules;
+  return srcModules;
+}
+
+export const modulesPath = resolveModulesPath();
+
+/**
+ * Why: Finds module files by glob from active src/dist modules path.
+ * When: Framework needs module routes/jobs/seeders/schedules discovery.
+ * Where: Route registrar, queue boot, scheduler boot, seeding.
+ * How: Runs glob with absolute paths and stable sorting.
+ */
+export async function discoverModuleFiles(pattern: string) {
+  const files = await glob(pattern, {
+    cwd: modulesPath,
+    absolute: true,
+    nodir: true,
+    windowsPathsNoEscape: true
+  });
+
+  return files.sort();
+}
+
+/**
+ * Why: Derives module folder name from absolute discovered file path.
+ * When: Mounting route prefixes and grouping module assets.
+ * Where: Route registration logic.
+ * How: Computes relative path and returns first segment.
+ */
+export function moduleNameFromPath(filePath: string) {
+  return path.relative(modulesPath, filePath).split(path.sep)[0];
+}
+
+/**
+ * Why: Dynamically imports a discovered module file.
+ * When: Bootstrapping pluggable module artifacts.
+ * Where: Discovery consumers across framework.
+ * How: Converts file path to file URL and imports it.
+ */
+export async function importFile(filePath: string) {
+  return await import(pathToFileURL(filePath).href);
+}

package/template/src/framework/modules/routes.ts

@@ -0,0 +1,26 @@
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import {
+  discoverModuleFiles,
+  importFile,
+  moduleNameFromPath
+} from "@/framework/modules/discover.js";
+
+/**
+ * Why: Auto-registers module route files under `/api/<module>`.
+ * When: HTTP app bootstraps module routing.
+ * Where: Kernel startup.
+ * How: Discovers route files, imports defaults, mounts by module name.
+ */
+export async function registerModuleRoutes(app: OpenAPIHono) {
+  const files = await discoverModuleFiles("**/routes/*.{ts,js}");
+
+  for (const file of files) {
+    const route = await importFile(file);
+
+    if (route.default) {
+      app.route(`/api/${moduleNameFromPath(file)}`, route.default);
+    }
+  }
+
+  return files.length;
+}

package/template/src/framework/notification/index.ts

@@ -0,0 +1,109 @@
+import { eq } from "drizzle-orm";
+import { db } from "@/framework/database/connection.js";
+import { dispatchEvent } from "@/framework/events/dispatcher.js";
+import { mail } from "@/framework/support/mail.js";
+import { redisClientIfReady } from "@/framework/redis/client.js";
+import { notifications } from "@/modules/auth/database/models/notifications.js";
+import { users } from "@/modules/auth/database/models/user.js";
+
+/** Extra JSON metadata attached to the notification (e.g. entity IDs, links). */
+export type NotificationOptions = {
+  /** Notification category key (default: "info") */
+  type?: string;
+  /** Notification title */
+  title: string;
+  /** Notification body text */
+  body?: string;
+  /** Optional click-through URL */
+  link?: string;
+  /** Arbitrary JSON payload stored in `data` column */
+  data?: Record<string, unknown>;
+  /** Whether to broadcast the notification to the user's socket in realtime */
+  broadcast?: boolean;
+  /** Email delivery options */
+  mail?: {
+    subject?: string;
+    html?: string;
+  };
+};
+
+/** Create a notification and persist it to the database. Optionally broadcast via Socket.IO and/or send by email. */
+export async function notify(userId: number, options: NotificationOptions) {
+  const insertResult = await db.insert(notifications).values({
+    userId,
+    type: options.type || "info",
+    title: options.title,
+    body: options.body || null,
+    link: options.link || null,
+    data: options.data ? JSON.stringify(options.data) : null,
+  });
+
+  const insertedId = Number((insertResult as any)[0]?.insertId ?? (insertResult as any).insertId);
+  if (!insertedId) throw new Error("Failed to create notification");
+
+  const [row] = await db.select().from(notifications).where(eq(notifications.id, insertedId));
+  const normalized = normalize(row);
+
+  if (options.broadcast) {
+    await dispatchEvent("notification.created", normalized, {
+      broadcast: { users: [userId] }
+    });
+  }
+
+  if (options.mail) {
+    await sendMailChannel(userId, normalized, options);
+  }
+
+  return normalized;
+}
+
+/** Deliver an email notification, either queued (if Redis is available) or direct. */
+async function sendMailChannel(
+  userId: number,
+  notification: { id: number; title: string; body: string | null; },
+  options: NotificationOptions
+) {
+  const [user] = await db.select({ email: users.email, name: users.name })
+    .from(users).where(eq(users.id, userId));
+
+  if (!user?.email) return;
+
+  const subject = options.mail?.subject || notification.title;
+  const html = options.mail?.html || defaultMailHtml(notification.title, notification.body);
+
+  if (redisClientIfReady()) {
+    await dispatchEvent("notification:mail", {
+      to: user.email, subject, html,
+    }, { queue: "mail" });
+  } else {
+    await mail.sendMail({ to: user.email, subject, html });
+  }
+}
+
+/** Generate a basic HTML email body from title and body text. */
+function defaultMailHtml(title: string, body: string | null) {
+  return `<h2>${escapeHtml(title)}</h2>${body ? `<p>${escapeHtml(body)}</p>` : ""}`;
+}
+
+function escapeHtml(str: string) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/** Convert a DB row into the normalized response shape, parsing the `data` JSON column. */
+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/template/src/framework/queue/clear.ts

@@ -0,0 +1,20 @@
+import { initRedis, redisError, redisReady } from "@/framework/redis/client.js";
+import { logger } from "@/framework/support/logger.js";
+import { clearQueue } from "@/framework/queue/queue.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");