create-charcole 2.0.4 → 2.1.0

package/template/ts/src/modules/auth/package.json

@@ -0,0 +1,10 @@
+{
+  "dependencies": {
+    "bcryptjs": "^3.0.3",
+    "jsonwebtoken": "^9.0.3"
+  },
+  "devDependencies": {
+    "@types/bcryptjs": "^2.4.6",
+    "@types/jsonwebtoken": "^9.0.10"
+  }
+}

package/template/ts/src/modules/health/controller.ts

@@ -1,8 +1,8 @@
 import { Request, Response } from "express";
 import { z } from "zod";
-import { sendSuccess } from "../../utils/response.js";
-import { asyncHandler } from "../../middlewares/errorHandler.js";
-import { validateRequest } from "../../middlewares/validateRequest.js";
+import { sendSuccess } from "../../utils/response.ts";
+import { asyncHandler } from "../../middlewares/errorHandler.ts";
+import { validateRequest } from "../../middlewares/validateRequest.ts";
 
 const healthCheckSchema = z.object({
   query: z.object({}),

package/template/ts/src/repositories/user.repo.ts

@@ -0,0 +1,33 @@
+import { randomUUID } from "crypto";
+import type { User } from "../modules/auth/auth.schemas.ts";
+
+const users: User[] = [];
+
+type CreateUserData = {
+  email: string;
+  name: string;
+  passwordHash: string;
+};
+
+export const userRepo = {
+  async findByEmail(email: string): Promise<User | undefined> {
+    return users.find((u) => u.email === email);
+  },
+
+  async create(data: CreateUserData): Promise<User> {
+    const user: User = {
+      id: randomUUID(),
+      email: data.email,
+      name: data.name,
+      passwordHash: data.passwordHash,
+      role: "user",
+      provider: "credentials",
+      isEmailVerified: false,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+
+    users.push(user);
+    return user;
+  },
+};

package/template/ts/src/routes/index.ts

@@ -0,0 +1,24 @@
+import { Router } from "express";
+import {
+  getHealth,
+  createItem,
+  createItemSchema,
+} from "../modules/health/controller.ts";
+import { validateRequest } from "../middlewares/validateRequest.ts";
+import protectedRoutes from "./protected.ts";
+import authRoutes from "../modules/auth/auth.routes.ts";
+const router = Router();
+
+// Health check
+router.get("/health", getHealth);
+
+// Example: Create item with validation
+router.post("/items", validateRequest(createItemSchema), createItem);
+
+// 🔐 Auth routes
+router.use("/auth", authRoutes);
+
+// 🔐 Protected routes (REQUIRED BEARER TOKEN FOR THEM)
+router.use("/protected", protectedRoutes);
+
+export default router;

package/template/ts/src/routes/protected.ts

@@ -0,0 +1,13 @@
+import { Router } from "express";
+import { requireAuth } from "../modules/auth/auth.middlewares.ts";
+
+const router = Router();
+
+router.get("/me", requireAuth, (req, res) => {
+  res.json({
+    message: "You are authenticated",
+    user: req.user,
+  });
+});
+
+export default router;

package/template/ts/src/server.ts

@@ -1,5 +1,4 @@
 import "dotenv/config";
-
 import { app } from "./app.js";
 import { env } from "./config/env.js";
 import { logger } from "./utils/logger.js";

package/template/ts/src/utils/logger.ts

@@ -1,4 +1,4 @@
-import { env } from "../config/env.js";
+import { env } from "../config/env.ts";
 
 type LogLevel = "debug" | "info" | "warn" | "error" | "fatal";
 

package/template/ts/tsconfig.json

@@ -2,18 +2,25 @@
   "compilerOptions": {
     "target": "ES2020",
     "module": "ESNext",
-    "rootDir": "src",
-    "outDir": "dist",
+    "moduleResolution": "bundler",
+    "rootDir": "./src",
+    "outDir": "./dist",
     "strict": true,
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,
     "skipLibCheck": true,
-    "moduleResolution": "node",
     "resolveJsonModule": true,
     "allowJs": false,
-    "noEmitOnError": true,
-    "sourceMap": true
+    "noEmitOnError": false,
+    "sourceMap": true,
+    "declaration": false,
+    "allowImportingTsExtensions": true,
+    "noEmit": true
   },
-  "include": ["src/**/*.ts"],
-  "exclude": ["node_modules", "dist"]
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"],
+  "ts-node": {
+    "esm": true,
+    "experimentalSpecifierResolution": "node"
+  }
 }

package/template/js/ARCHITECTURE_DIAGRAMS.md

@@ -1,283 +0,0 @@
-# Error Handling Architecture Diagram
-
-## Complete Error Flow
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│                         HTTP REQUEST                                │
-└──────────────────────────────────────┬──────────────────────────────┘
-                                       │
-                                       ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│                    CORS & BODY PARSING MIDDLEWARE                   │
-└──────────────────────────────────────┬──────────────────────────────┘
-                                       │
-                                       ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│                       REQUEST LOGGER MIDDLEWARE                      │
-│  (Logs: method, path, query, IP, user-agent)                        │
-└──────────────────────────────────────┬──────────────────────────────┘
-                                       │
-                                       ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│                    VALIDATION MIDDLEWARE (optional)                  │
-│                                                                      │
-│  Validates with Zod schema → throws ValidationError if fails       │
-└──────────────────────────────────────┬──────────────────────────────┘
-                                       │
-                                       ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│              ROUTE HANDLER (wrapped with asyncHandler)              │
-│                                                                      │
-│  ┌────────────────────────────────────────────────────────────────┐ │
-│  │ asyncHandler(async (req, res) => {                             │ │
-│  │   // Your handler code                                         │ │
-│  │   const user = await User.findById(req.params.id);            │ │
-│  │                                                                │ │
-│  │   if (!user) {                                                │ │
-│  │     throw new NotFoundError("User", { id: req.params.id });   │ │
-│  │   }                                                            │ │
-│  │                                                                │ │
-│  │   sendSuccess(res, user);                                     │ │
-│  │ })                                                             │ │
-│  └────────────────────────────────────────────────────────────────┘ │
-└────────┬────────────────────────────────────────────────────────────┘
-         │
-         ├──→ Success? ──→ sendSuccess() ──→ [END: Response sent]
-         │
-         └──→ Error thrown ✘ ──→ [Continue below]
-                                 │
-                                 ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│              GLOBAL ERROR HANDLER MIDDLEWARE                         │
-│  (This is where ALL errors flow!)                                   │
-└────┬────────────────────────────────────────────────────────────────┘
-     │
-     ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│                    ERROR NORMALIZATION                               │
-│                                                                      │
-│  if (err instanceof AppError)     → Use as is                       │
-│  if (err instanceof ZodError)     → Convert to ValidationError      │
-│  if (err instanceof TypeError)    → Convert to InternalServerError  │
-│  if (err instanceof ReferenceError)→ Convert to InternalServerError │
-│  if (err instanceof SyntaxError)  → Convert to InternalServerError  │
-│  if (err instanceof RangeError)   → Convert to InternalServerError  │
-│  else                             → Wrap in InternalServerError     │
-└────┬────────────────────────────────────────────────────────────────┘
-     │
-     ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│                    ERROR CLASSIFICATION                              │
-│                                                                      │
-│  ┌─ Operational Error (isOperational: true)                        │
-│  │  ├─ ValidationError (422)                                       │
-│  │  ├─ NotFoundError (404)                                         │
-│  │  ├─ AuthenticationError (401)                                   │
-│  │  ├─ AuthorizationError (403)                                    │
-│  │  ├─ ConflictError (409)                                         │
-│  │  └─ BadRequestError (400)                                       │
-│  │                                                                  │
-│  └─ Programmer Error (isOperational: false)                        │
-│     └─ TypeError, ReferenceError, SyntaxError, etc.                │
-└────┬────────────────────────────────────────────────────────────────┘
-     │
-     ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│                      ERROR LOGGING                                   │
-│                                                                      │
-│  If Operational Error:                                              │
-│  ├─ Log as WARN level                                              │
-│  ├─ Include: code, message, statusCode, method, path, IP           │
-│  └─ NO stack trace (expected error)                                │
-│                                                                      │
-│  If Programmer Error:                                               │
-│  ├─ Log as ERROR level                                             │
-│  ├─ Include: code, message, statusCode, method, path, IP, stack    │
-│  └─ YES full stack trace (for debugging)                           │
-└────┬────────────────────────────────────────────────────────────────┘
-     │
-     ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│                  SEND ERROR RESPONSE                                 │
-│                                                                      │
-│  If Production & Programmer Error:                                  │
-│  ├─ {                                                               │
-│  │   success: false,                                               │
-│  │   message: "Internal server error",                             │
-│  │   code: "INTERNAL_SERVER_ERROR",                                │
-│  │   timestamp: "..."                                              │
-│  │ }                                                                │
-│  │                                                                  │
-│  └─ (Details hidden from client)                                   │
-│                                                                      │
-│  If Development OR Operational Error:                               │
-│  ├─ {                                                               │
-│  │   success: false,                                               │
-│  │   message: "Full error message",                                │
-│  │   code: "ERROR_CODE",                                           │
-│  │   statusCode: 422,                                              │
-│  │   context: { ... },                                             │
-│  │   errors: [ ... ],  // for validation errors                    │
-│  │   timestamp: "..."                                              │
-│  │ }                                                                │
-│  │                                                                  │
-│  └─ (Full details sent)                                            │
-└────┬────────────────────────────────────────────────────────────────┘
-     │
-     ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│                  HTTP RESPONSE SENT TO CLIENT                        │
-│                                                                      │
-│  Status Code: 400, 401, 403, 404, 409, 422, 500, etc.              │
-│  Body: Consistent JSON error format                                 │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-## Error Class Hierarchy
-
-```
-Error (JavaScript)
-  │
-  └── AppError (Base class)
-      │
-      ├── ValidationError         (422 - Input validation failed)
-      ├── BadRequestError         (400 - Malformed request)
-      ├── AuthenticationError     (401 - Auth failed)
-      ├── AuthorizationError      (403 - Permission denied)
-      ├── NotFoundError           (404 - Resource not found)
-      ├── ConflictError           (409 - Duplicate/conflict)
-      └── InternalServerError     (500 - Unexpected error)
-```
-
-## Middleware Stack Order
-
-```
-Express App
-│
-├─ Trust Proxy
-├─ CORS
-├─ JSON Body Parser
-├─ URL Encoded Parser
-├─ Request Timeout Handler
-│
-├─ requestLogger (logs all requests)
-│
-├─ Routes:
-│  │
-│  ├─ validateRequest (optional, per route)
-│  │
-│  └─ Route Handler (MUST wrap with asyncHandler)
-│
-└─ errorHandler (MUST BE LAST)
-   └─ Catches all errors and sends JSON response
-```
-
-## Error Classification Decision Tree
-
-```
-                           Error Thrown
-                                │
-                    ┌───────────┴───────────┐
-                    │                       │
-               Is AppError?            Is ZodError?
-                    │                       │
-                   YES                     YES
-                    │                       │
-            ┌───────▼────────┐      ┌──────▼──────────┐
-            │ Use as is      │      │ Convert to      │
-            │ (already has   │      │ ValidationError │
-            │  isOperational)│      │ (422)           │
-            └─────────────────┘      └─────────────────┘
-                                            │
-                    ┌───────────────────────┴───────────────────────┐
-                    │                                               │
-              Is Operational?                              Is Programmer Error?
-              (isOperational: true)                        (Syntax, Type, Ref, Range)
-                    │                                               │
-                   YES                                             YES
-                    │                                               │
-         ┌──────────▼──────────┐                        ┌──────────▼──────────┐
-         │ Send full error     │                        │ Convert to          │
-         │ details to client   │                        │ InternalServerError │
-         │ with code & context │                        │ (500)               │
-         │                     │                        │ isOperational: false│
-         │ Log as WARN         │                        │                     │
-         │ (no stack)          │                        │ Log as ERROR        │
-         │                     │                        │ WITH FULL STACK     │
-         └─────────────────────┘                        │                     │
-                                                        │ Hide details in     │
-                                                        │ production          │
-                                                        └─────────────────────┘
-```
-
-## Request-to-Response Timeline
-
-```
-TIME  LAYER                  ACTION
-════  ═════════════════════  ════════════════════════════════════════
-
-T0    Network               Request arrives at server
-
-T1    Express Middleware    CORS, Body Parser, Request Logger
-
-T2    Route Handler         validateRequest() - validates input
-
-T3    Route Handler         Handler executes (wrapped with asyncHandler)
-                            ├─ Success: sendSuccess() → Response sent → T6
-                            └─ Error: Thrown → T4
-
-T4    asyncHandler          Catches error, passes to next(error)
-
-T5    Error Handler Mw      Normalizes error
-                            Classifies (operational vs programmer)
-                            Logs error with context
-                            Sanitizes response (production)
-                            Sends JSON response
-
-T6    Network               Response sent to client
-```
-
-## Environment Behavior
-
-```
-┌──────────────────────┐           ┌──────────────────────┐
-│    DEVELOPMENT       │           │    PRODUCTION        │
-│  NODE_ENV=development│           │  NODE_ENV=production │
-└──────────┬───────────┘           └──────────┬───────────┘
-           │                                  │
-           │ Programmer Error:                │ Programmer Error:
-           │ ┌────────────────────────┐       │ ┌────────────────────────┐
-           │ │ {                      │       │ │ {                      │
-           │ │   success: false,      │       │ │   success: false,      │
-           │ │   message: "TypeError: │       │ │   message: "Internal   │
-           │ │   x is undefined",     │       │ │   server error",       │
-           │ │   code: "INTERNAL...", │       │ │   code: "INTERNAL...", │
-           │ │   stack: "TypeError... │       │ │   timestamp: "..."     │
-           │ │   at handler.js:15..." │       │ │ }                      │
-           │ │ }                      │       │ │                        │
-           │ └────────────────────────┘       │ └────────────────────────┘
-           │                                  │
-           │ Operational Error:               │ Operational Error:
-           │ (sent fully in both)             │ (sent fully in both)
-           │ ┌────────────────────────┐       │ ┌────────────────────────┐
-           │ │ {                      │       │ │ {                      │
-           │ │   success: false,      │       │ │   success: false,      │
-           │ │   message: "User not   │       │ │   message: "User not   │
-           │ │   found",              │       │ │   found",              │
-           │ │   code: "NOT_FOUND",   │       │ │   code: "NOT_FOUND",   │
-           │ │   context: {...}       │       │ │   context: {...}       │
-           │ │ }                      │       │ │ }                      │
-           │ └────────────────────────┘       │ └────────────────────────┘
-           │                                  │
-           │ Logging:                         │ Logging:
-           │ Full details + stack             │ Full details + stack
-           │ (for development)                │ (server-side only)
-           │                                  │
-```
-
----
-
-This architecture ensures that **every single error in your application flows through one place, gets properly classified, logged with full context, and returns a consistent JSON response to the client.**
-
-That's production-grade error handling. 🎯