create-nexwire 4.0.0 → 4.1.1

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

@@ -0,0 +1,113 @@
+import type { Request, Response } from "express";
+import { createRoute, group, HttpStatusCodes, jsonContent, z } from "@/framework/facade.js";
+import { authMiddleware } from "@/middlewares/auth-middleware.js";
+import { requireRole } from "@/middlewares/role-middleware.js";
+
+/**
+ * {{module}} routes for {{controller}}.
+ *
+ * Wire each route to a handler:
+ *   import { index, show, store, update, destroy } from "@/modules/{{module}}/controllers/{{controller}}.js";
+ *   export default group().api(indexRoute, index).api(showRoute, show) ...
+ *
+ * Wire each route to its validation schema:
+ *   import {
+ *     Create{{ClassName}}Schema,
+ *     {{ClassName}}IdParamsSchema,
+ *     {{ClassName}}ListResponseSchema,
+ *     {{ClassName}}MessageSchema,
+ *     {{ClassName}}ResponseSchema,
+ *     Update{{ClassName}}Schema
+ *   } from "@/modules/{{module}}/schemas/{{controller}}.js";
+ */
+
+const indexRoute = createRoute({
+  path: "/",
+  method: "get",
+  tags: ["{{ModuleClass}}"],
+  // request: {
+  //   query: {{ClassName}}ListQuerySchema
+  // },
+  responses: {
+    [HttpStatusCodes.OK]: jsonContent(
+      z.object({ message: z.string(), data: z.array(z.object({ id: z.number(), name: z.string() })) }),
+      "{{module}} list"
+    )
+  }
+});
+
+const showRoute = createRoute({
+  path: "/{id}",
+  method: "get",
+  tags: ["{{ModuleClass}}"],
+  // request: {
+  //   params: {{ClassName}}IdParamsSchema
+  // },
+  responses: {
+    [HttpStatusCodes.OK]: jsonContent(
+      z.object({ message: z.string(), data: z.object({ id: z.number(), name: z.string() }) }),
+      "{{module}} item"
+    ),
+    [HttpStatusCodes.NOT_FOUND]: jsonContent(z.object({ message: z.string() }), "Not found")
+  }
+});
+
+const storeRoute = createRoute({
+  path: "/",
+  method: "post",
+  tags: ["{{ModuleClass}}"],
+  // request: {
+  //   body: jsonContent(Create{{ClassName}}Schema, "Create {{module}} payload")
+  // },
+  responses: {
+    [HttpStatusCodes.CREATED]: jsonContent(z.object({ message: z.string() }), "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(z.object({ message: z.string() }), "Updated"),
+    [HttpStatusCodes.NOT_FOUND]: jsonContent(z.object({ message: z.string() }), "Not found")
+  }
+});
+
+const destroyRoute = createRoute({
+  path: "/{id}",
+  method: "delete",
+  tags: ["{{ModuleClass}}"],
+  // request: {
+  //   params: {{ClassName}}IdParamsSchema
+  // },
+  responses: {
+    [HttpStatusCodes.OK]: jsonContent(z.object({ message: z.string() }), "Deleted"),
+    [HttpStatusCodes.NOT_FOUND]: jsonContent(z.object({ message: z.string() }), "Not found")
+  }
+});
+
+export default group()
+  .api(indexRoute, (_req: Request, res: Response) => res.json({ message: "{{module}} list not implemented", data: [] }))
+  .api(showRoute, (_req: Request, res: Response) =>res.json({ message: "{{module}} item not implemented", data: { id: 0, name: "" } }))
+  .api(storeRoute, (_req: Request, res: Response) =>res.status(HttpStatusCodes.CREATED).json({ message: "{{module}} create not implemented" }))
+  .api(updateRoute, (_req: Request, res: Response) => res.json({ message: "{{module}} update not implemented" }))
+  .api(destroyRoute, (_req: Request, res: Response) => res.json({ message: "{{module}} delete not implemented" }));
+
+
+// Gate the whole group (authMiddleware resolves the session once for every route):
+//   export default group(authMiddleware).api(indexRoute, index) ...
+//
+// Or gate a single route by role. requireRole reads the role authMiddleware set,
+// so authMiddleware must run first:
+//   group().api(destroyRoute, [authMiddleware, requireRole("admin")], destroy)
+//
+// Or group all authMiddleware and set single requireRole middleware
+// so authMiddleware must run on all chain and requireRole single on per route:
+//   group(authMiddleware).api(destroyRoute, [requireRole("admin")], destroy)
+//
+// Delete the imports above when you do not need them.

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

@@ -0,0 +1,37 @@
+import type { Request, Response } from "express";
+import { group, HttpStatusCodes } from "@/framework/facade.js";
+import { authMiddleware } from "@/middlewares/auth-middleware.js";
+import { requireRole } from "@/middlewares/role-middleware.js";
+
+/**
+ * {{module}} routes for {{controller}}.
+ *
+ * Wire each handler to a controller:
+ *   import { index, show, store, update, destroy } from "@/modules/{{module}}/controllers/{{controller}}.js";
+ *   export default group().get("/", index).get("/:id", show) ...
+ *
+ * Add validation with the validate() helper:
+ *   import { validate } from "@/framework/facade.js";
+ *   import { {{ClassName}}IdParamsSchema } from "@/modules/{{module}}/schemas/{{controller}}.js";
+ *   const params = await validate({{ClassName}}IdParamsSchema, req.params);
+ */
+
+export default group()
+  .get("/", (_req: Request, res: Response) => res.json({ message: "{{module}} list not implemented", data: [] }))
+  .get("/:id", (_req: Request, res: Response) =>res.json({ message: "{{module}} item not implemented", data: { id: 0, name: "" } }))
+  .post("/", (_req: Request, res: Response) =>res.status(HttpStatusCodes.CREATED).json({ message: "{{module}} create not implemented" }))
+  .put("/:id", (_req: Request, res: Response) => res.json({ message: "{{module}} update not implemented" }))
+  .delete("/:id", (_req: Request, res: Response) => res.json({ message: "{{module}} delete not implemented" }));
+
+// Gate the whole group (authMiddleware resolves the session once for every route):
+//   export default group(authMiddleware).api(indexRoute, index) ...
+//
+// Or gate a single route by role. requireRole reads the role authMiddleware set,
+// so authMiddleware must run first:
+//   group().api(destroyRoute, [authMiddleware, requireRole("admin")], destroy)
+//
+// Or group all authMiddleware and set single requireRole middleware
+// so authMiddleware must run on all chain and requireRole single on per route:
+//   group(authMiddleware).api(destroyRoute, [requireRole("admin")], destroy)
+//
+// Delete the imports above when you do not need them.

package/express/src/framework/maker-cli/stubs/{controller/schema.plain.ts.stub → schema/name.plain.ts.stub}

@@ -1,14 +1,14 @@
-import { z } from "@/framework/facade.js";
-
-export const Create{{ClassName}}Schema = z.object({
-  name: z.string().min(1)
-});
-
-export const Update{{ClassName}}Schema = z.object({
-  name: z.string().min(1)
-});
-
-export const {{ClassName}}IdParamsSchema = z.object({
-  id: z.coerce.number().int().positive()
-});
+import { z } from "@/framework/facade.js";
+
+export const Create{{ClassName}}Schema = z.object({
+  name: z.string().min(1)
+});
+
+export const Update{{ClassName}}Schema = z.object({
+  name: z.string().min(1)
+});
+
+export const {{ClassName}}IdParamsSchema = z.object({
+  id: z.coerce.number().int().positive()
+});
 

package/express/src/framework/maker-cli/stubs/{controller/schema.ts.stub → schema/name.ts.stub}

@@ -1,33 +1,33 @@
-import { z } from "@/framework/facade.js";
-
-export const {{ClassName}}ItemSchema = z.object({
-  id: z.number(),
-  name: z.string()
-});
-
-export const Create{{ClassName}}Schema = z.object({
-  name: z.string().min(1)
-});
-
-export const Update{{ClassName}}Schema = z.object({
-  name: z.string().min(1)
-});
-
-export const {{ClassName}}IdParamsSchema = z.object({
-  id: z.coerce.number().int().positive()
-});
-
-export const {{ClassName}}ListResponseSchema = z.object({
-  message: z.string(),
-  data: z.array({{ClassName}}ItemSchema)
-});
-
-export const {{ClassName}}ResponseSchema = z.object({
-  message: z.string(),
-  data: {{ClassName}}ItemSchema
-});
-
-export const {{ClassName}}MessageSchema = z.object({
-  message: z.string()
-});
+import { z } from "@/framework/facade.js";
+
+export const {{ClassName}}ItemSchema = z.object({
+  id: z.number(),
+  name: z.string()
+});
+
+export const Create{{ClassName}}Schema = z.object({
+  name: z.string().min(1)
+});
+
+export const Update{{ClassName}}Schema = z.object({
+  name: z.string().min(1)
+});
+
+export const {{ClassName}}IdParamsSchema = z.object({
+  id: z.coerce.number().int().positive()
+});
+
+export const {{ClassName}}ListResponseSchema = z.object({
+  message: z.string(),
+  data: z.array({{ClassName}}ItemSchema)
+});
+
+export const {{ClassName}}ResponseSchema = z.object({
+  message: z.string(),
+  data: {{ClassName}}ItemSchema
+});
+
+export const {{ClassName}}MessageSchema = z.object({
+  message: z.string()
+});
 

package/express/src/framework/maker-cli/stubs/service/name.plain.ts.stub

@@ -0,0 +1,67 @@
+import { eq } from "drizzle-orm";
+import { db } from "@/framework/facade.js";
+
+/**
+ * Why: Returns every {{controller}} row for list screens.
+ * When: Called by the controller's index() handler.
+ * Where: GET /{{controller}} route.
+ *
+ * TODO: import your model and query it, for example:
+ *   import { {{tableVariable}} } from "@/modules/{{module}}/database/models/{{controller}}.js";
+ *   return db.select().from({{tableVariable}});
+ */
+export const {{controller}}Service = {  
+  /**
+  * Why: CRUD service for {{controller}}.
+  * When: Consumed directly by the controller as `{{controller}}Service.list()`, etc.
+  * Where: Wired into the module's controller handlers.
+  */
+  list: async () => {
+    void db;
+    return [];
+  },
+
+  /**
+   * Why: Returns one {{controller}} row by primary key.
+   * When: Called by the controller's show/update/destroy handlers.
+   * Where: Reused across GET/PUT/DELETE /{{controller}}/{id} routes.
+   *
+   * TODO: query the model by id and return the row, or null when missing.
+   */
+  findOne: async (_id: number) => {
+    return null;
+  },
+
+  /**
+   * Why: Persists a new {{controller}} row.
+   * When: Called by the controller's store() handler.
+   * Where: POST /{{controller}} route.
+   *
+   * TODO: insert the validated payload and return the created row.
+   */
+  create: async (_data: Record<string, unknown>) => {
+    return null;
+  },
+
+  /**
+   * Why: Applies a partial change to one {{controller}} row.
+   * When: Called by the controller's update() handler.
+   * Where: PUT/PATCH /{{controller}}/{id} route.
+   *
+   * TODO: update by id, refresh updatedAt, and return the row, or null when missing.
+   */
+  update: async (_id: number, _data: Record<string, unknown>) => {
+    return null;
+  },
+
+  /**
+   * Why: Removes one {{controller}} row.
+   * When: Called by the controller's destroy() handler.
+   * Where: DELETE /{{controller}}/{id} route.
+   *
+   * TODO: delete by id and return the removed row, or null when missing.
+   */
+  remove: async (_id: number) => {
+    return null;
+  },
+};

package/express/src/framework/maker-cli/stubs/service/name.ts.stub

@@ -0,0 +1,65 @@
+import { eq } from "drizzle-orm";
+import { db } from "@/framework/facade.js";
+import { {{tableVariable}} } from "@/modules/{{module}}/database/models/{{controller}}.js";
+
+export const {{controller}}Service = {
+  /**
+   * Why: Returns every {{controller}} row for list screens.
+   * When: Called by the controller's index() handler.
+   * Where: GET /{{controller}} route.
+   */
+  list: async () => {
+    return db.select().from({{tableVariable}});
+  },
+
+  /**
+   * Why: Returns one {{controller}} row by primary key.
+   * When: Called by the controller's show/update/destroy handlers.
+   * Where: Reused across GET/PUT/DELETE /{{controller}}/{id} routes.
+   */
+  findOne: async (id: number) => {
+    const [row] = await db
+      .select()
+      .from({{tableVariable}})
+      .where(eq({{tableVariable}}.id, id))
+      .limit(1);
+    return row ?? null;
+  },
+
+  /**
+   * Why: Persists a new {{controller}} row.
+   * When: Called by the controller's store() handler.
+   * Where: POST /{{controller}} route.
+   */
+  create: async (data: Record<string, unknown>) => {
+    const [row] = await db.insert({{tableVariable}}).values(data).returning();
+    return row;
+  },
+
+  /**
+   * Why: Applies a partial change to one {{controller}} row.
+   * When: Called by the controller's update() handler.
+   * Where: PUT/PATCH /{{controller}}/{id} route.
+   */
+  update: async (id: number, data: Record<string, unknown>) => {
+    const [row] = await db
+      .update({{tableVariable}})
+      .set(data)
+      .where(eq({{tableVariable}}.id, id))
+      .returning();
+    return row ?? null;
+  },
+
+  /**
+   * Why: Removes one {{controller}} row.
+   * When: Called by the controller's destroy() handler.
+   * Where: DELETE /{{controller}}/{id} route.
+   */
+  remove: async (id: number) => {
+    const [row] = await db
+      .delete({{tableVariable}})
+      .where(eq({{tableVariable}}.id, id))
+      .returning();
+    return row ?? null;
+  },
+};

package/express/src/framework/maker-cli/stubs/type/name.ts.stub

@@ -0,0 +1,22 @@
+/**
+ * Why: Shared TypeScript types for the {{module}} module.
+ * When: Needed by controllers, services, or helpers that must agree on a shape.
+ * Where: src/modules/{{module}}/types/{{name}}.ts
+ */
+
+/** Why: Base shape for every {{name}} record. When: Used as a constraint or return type. Where: This file. */
+export interface {{Name}}Record {
+  id: number;
+}
+
+/** Why: Result shape for a single-item response. When: Returned by show-style handlers. Where: This file. */
+export interface {{Name}}Result {
+  message: string;
+  data: {{Name}}Record;
+}
+
+/** Why: Result shape for list responses. When: Returned by index-style handlers. Where: This file. */
+export interface {{Name}}ListResult {
+  message: string;
+  data: {{Name}}Record[];
+}

package/express/src/framework/maker-cli/utils/naming.mjs

@@ -1,13 +1,56 @@
-/** Validate that a name value exists and return it trimmed+lowercased. Throws if empty. */
-export function assertName(value, label) {
-  if (!value) {
-    throw new Error(`${label} is required.`);
-  }
-
-  return value.trim().toLowerCase();
-}
-
-/** Convert a kebab-case or snake_case string to PascalCase. */
-export function pascal(input) {
-  return input.replace(/(^\w|[-_]\w)/g, (part) => part.replace(/[-_]/g, "").toUpperCase());
-}
+/**
+ * A name is safe when it can be used as a folder name, a URL segment, a table
+ * name and a TypeScript identifier without further quoting.
+ *
+ * Kebab-case, snake_case and camelCase all pass: `pascal` already folds `-` and
+ * `_`, and names are lowercased before this test. What fails is anything that
+ * would produce uncompilable code - spaces and dots break the generated
+ * `@/modules/...` import, a leading digit breaks the identifier.
+ */
+const NAME_PATTERN = /^[a-z][a-z0-9_-]*$/;
+
+/**
+ * Best-effort readable repair of a rejected name, used only in error text.
+ * Returns "" when no safe suggestion exists (e.g. a leading digit cannot be
+ * reordered without guessing the developer's intent).
+ */
+function suggestName(value) {
+  const cleaned = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/-{2,}/g, "-")
+    .replace(/^[-_]+|[-_]+$/g, "");
+  if (!cleaned || !/^[a-z]/.test(cleaned)) return "";
+  return cleaned;
+}
+
+/**
+ * Validate that a name value exists and is safe to use.
+ * Throws with the exact command to run instead when the value is unusable.
+ */
+export function assertName(value, label) {
+  if (!value) {
+    throw new Error(`${label} is required.`);
+  }
+
+  const name = value.trim().toLowerCase();
+  if (NAME_PATTERN.test(name)) return name;
+
+  const suggestion = suggestName(value);
+  const reason = /^[0-9]/.test(name)
+    ? "must start with a lowercase letter"
+    : "may only contain lowercase letters, numbers, dashes and underscores";
+  throw new Error(`Invalid ${label.toLowerCase()}: "${value}" - a name ${reason}.${suggestion ? ` Use "${suggestion}" instead.` : ""}`);
+}
+
+/** Convert a kebab-case or snake_case string to PascalCase. */
+export function pascal(input) {
+  return input.replace(/(^\w|[-_]\w)/g, (part) => part.replace(/[-_]/g, "").toUpperCase());
+}
+
+/** Convert a kebab-case or snake_case string to camelCase. */
+export function camelCase(input) {
+  const p = pascal(input);
+  return p.charAt(0).toLowerCase() + p.slice(1);
+}

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

@@ -1,54 +1,57 @@
-import fs from "node:fs";
-import path from "node:path";
-import { pathToFileURL } from "node:url";
-import { glob } from "glob";
-
-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);
-}
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { glob } from "glob";
+
+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 the module name from an absolute discovered file path.
+ * When: Mounting route prefixes and grouping module assets.
+ * Where: Route registration logic.
+ * How: Strips the artifact folder (e.g. `routes/`), keeping any panel segment so
+ * `admin/post/routes/index.ts` resolves to `admin/post` rather than `admin`.
+ * Returns POSIX separators because the result is used as a URL prefix.
+ */
+export function moduleNameFromPath(filePath: string) {
+  const relative = path.relative(modulesPath, filePath);
+  return path.dirname(path.dirname(relative)).split(path.sep).join("/");
+}
+
+/**
+ * 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/express/src/framework/notification/index.ts

@@ -3,7 +3,7 @@ import { db } from "@/framework/database/connection.js";
 import { dispatchEvent } from "@/framework/events/dispatcher.js";
 import { redisClientIfReady } from "@/framework/redis/client.js";
 import { mail } from "@/framework/support/mail.js";
-import { notifications } from "@/modules/auth/database/models/notifications.js";
+import { notifications } from "@/modules/auth/database/models/notification.js";
 import { users } from "@/modules/auth/database/models/user.js";
 
 /** Extra JSON metadata attached to the notification (e.g. entity IDs, links). */