create-charcole 1.1.0 → 2.0.1

package/template/ts/src/utils/AppError.ts

@@ -0,0 +1,220 @@
+/**
+ * Shared types
+ */
+
+export type ErrorContext = Record<string, unknown>;
+
+export interface AppErrorOptions {
+  isOperational?: boolean;
+  code?: string | null;
+  context?: ErrorContext | null;
+  cause?: Error | null;
+}
+
+/**
+ * Operational Error Class
+ *
+ * Use for expected errors that can be handled gracefully
+ */
+export class AppError extends Error {
+  public readonly statusCode: number;
+  public readonly isOperational: boolean;
+  public readonly code: string | null;
+  public readonly context: ErrorContext;
+  public readonly cause: Error | null;
+  public readonly timestamp: string;
+
+  constructor(
+    message: string,
+    statusCode = 500,
+    {
+      isOperational = true,
+      code = null,
+      context = null,
+      cause = null,
+    }: AppErrorOptions = {},
+  ) {
+    super(message);
+
+    this.name = "AppError";
+    this.statusCode = statusCode;
+    this.isOperational = isOperational;
+    this.code = code;
+    this.context = context ?? {};
+    this.cause = cause;
+    this.timestamp = new Date().toISOString();
+
+    // Preserve stack trace
+    Error.captureStackTrace(this, this.constructor);
+  }
+
+  /**
+   * Convert to JSON response format
+   */
+  toJSON(): {
+    success: false;
+    message: string;
+    code: string | null;
+    statusCode: number;
+    context?: ErrorContext;
+    timestamp: string;
+  } {
+    return {
+      success: false,
+      message: this.message,
+      code: this.code,
+      statusCode: this.statusCode,
+      ...(Object.keys(this.context).length > 0 && { context: this.context }),
+      timestamp: this.timestamp,
+    };
+  }
+
+  /**
+   * Get full error details for logging
+   */
+  getFullDetails(): {
+    message: string;
+    statusCode: number;
+    code: string | null;
+    isOperational: boolean;
+    context: ErrorContext;
+    cause: string | null;
+    stack?: string;
+    timestamp: string;
+  } {
+    return {
+      message: this.message,
+      statusCode: this.statusCode,
+      code: this.code,
+      isOperational: this.isOperational,
+      context: this.context,
+      cause: this.cause?.message ?? null,
+      stack: this.stack,
+      timestamp: this.timestamp,
+    };
+  }
+}
+
+/**
+ * Validation Error
+ */
+export class ValidationError extends AppError {
+  public readonly errors: unknown[];
+
+  constructor(
+    message: string,
+    errors: unknown[] = [],
+    context: ErrorContext | null = null,
+  ) {
+    super(message, 422, {
+      isOperational: true,
+      code: "VALIDATION_ERROR",
+      context,
+    });
+
+    this.name = "ValidationError";
+    this.errors = errors;
+  }
+
+  override toJSON() {
+    return {
+      ...super.toJSON(),
+      errors: this.errors,
+    };
+  }
+}
+
+/**
+ * Authentication Error
+ */
+export class AuthenticationError extends AppError {
+  constructor(message = "Unauthorized", context: ErrorContext | null = null) {
+    super(message, 401, {
+      isOperational: true,
+      code: "AUTHENTICATION_ERROR",
+      context,
+    });
+
+    this.name = "AuthenticationError";
+  }
+}
+
+/**
+ * Authorization Error
+ */
+export class AuthorizationError extends AppError {
+  constructor(message = "Forbidden", context: ErrorContext | null = null) {
+    super(message, 403, {
+      isOperational: true,
+      code: "AUTHORIZATION_ERROR",
+      context,
+    });
+
+    this.name = "AuthorizationError";
+  }
+}
+
+/**
+ * Not Found Error
+ */
+export class NotFoundError extends AppError {
+  constructor(resource = "Resource", context: ErrorContext | null = null) {
+    super(`${resource} not found`, 404, {
+      isOperational: true,
+      code: "NOT_FOUND",
+      context,
+    });
+
+    this.name = "NotFoundError";
+  }
+}
+
+/**
+ * Conflict Error
+ */
+export class ConflictError extends AppError {
+  constructor(message: string, context: ErrorContext | null = null) {
+    super(message, 409, {
+      isOperational: true,
+      code: "CONFLICT",
+      context,
+    });
+
+    this.name = "ConflictError";
+  }
+}
+
+/**
+ * Bad Request Error
+ */
+export class BadRequestError extends AppError {
+  constructor(message: string, context: ErrorContext | null = null) {
+    super(message, 400, {
+      isOperational: true,
+      code: "BAD_REQUEST",
+      context,
+    });
+
+    this.name = "BadRequestError";
+  }
+}
+
+/**
+ * Internal Server Error
+ */
+export class InternalServerError extends AppError {
+  constructor(
+    message = "Internal server error",
+    cause: Error | null = null,
+    context: ErrorContext | null = null,
+  ) {
+    super(message, 500, {
+      isOperational: false,
+      code: "INTERNAL_SERVER_ERROR",
+      cause,
+      context,
+    });
+
+    this.name = "InternalServerError";
+  }
+}

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

@@ -0,0 +1,73 @@
+import { env } from "../config/env.js";
+
+const COLORS = {
+  reset: "\x1b[0m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+  green: "\x1b[32m",
+  blue: "\x1b[36m",
+  gray: "\x1b[90m",
+  magenta: "\x1b[35m",
+};
+
+const LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+const getCurrentLogLevel = () => LOG_LEVELS[env.LOG_LEVEL] || LOG_LEVELS.info;
+
+const formatLog = (level, message, data) => {
+  const timestamp = new Date().toISOString();
+  const dataStr = data ? ` ${JSON.stringify(data)}` : "";
+  return `[${timestamp}] ${level}:${dataStr ? " " + message + dataStr : " " + message}`;
+};
+
+const formatStack = (stack) => {
+  if (!stack) return "";
+  return `\n${stack}`;
+};
+
+export const logger = {
+  debug: (message, data) => {
+    if (getCurrentLogLevel() <= LOG_LEVELS.debug) {
+      console.log(
+        `${COLORS.gray}${formatLog("DEBUG", message, data)}${COLORS.reset}`,
+      );
+    }
+  },
+
+  info: (message, data) => {
+    if (getCurrentLogLevel() <= LOG_LEVELS.info) {
+      console.log(
+        `${COLORS.blue}${formatLog("INFO", message, data)}${COLORS.reset}`,
+      );
+    }
+  },
+
+  warn: (message, data) => {
+    if (getCurrentLogLevel() <= LOG_LEVELS.warn) {
+      console.warn(
+        `${COLORS.yellow}${formatLog("WARN", message, data)}${COLORS.reset}`,
+      );
+    }
+  },
+
+  error: (message, data, stack) => {
+    if (getCurrentLogLevel() <= LOG_LEVELS.error) {
+      const stackTrace = formatStack(stack);
+      console.error(
+        `${COLORS.red}${formatLog("ERROR", message, data)}${stackTrace}${COLORS.reset}`,
+      );
+    }
+  },
+
+  fatal: (message, data, stack) => {
+    const stackTrace = formatStack(stack);
+    console.error(
+      `${COLORS.red}${COLORS.magenta}${formatLog("FATAL", message, data)}${stackTrace}${COLORS.reset}`,
+    );
+  },
+};

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

@@ -0,0 +1,55 @@
+import { env } from "../config/env.js";
+
+type LogLevel = "debug" | "info" | "warn" | "error" | "fatal";
+
+const COLORS = {
+  reset: "\x1b[0m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+  green: "\x1b[32m",
+  blue: "\x1b[36m",
+  gray: "\x1b[90m",
+  magenta: "\x1b[35m",
+} as const;
+
+const LOG_LEVELS: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  fatal: 4,
+};
+
+const getCurrentLogLevel = (): number =>
+  LOG_LEVELS[env.LOG_LEVEL as LogLevel] ?? LOG_LEVELS.info;
+
+const formatLog = (
+  level: LogLevel,
+  message: string,
+  data?: unknown,
+): string => {
+  const timestamp = new Date().toISOString();
+  const dataStr = data ? ` ${JSON.stringify(data)}` : "";
+  return `[${timestamp}] ${level.toUpperCase()}: ${message}${dataStr}`;
+};
+
+const formatStack = (stack?: string): string => (stack ? `\n${stack}` : "");
+
+const log =
+  (level: LogLevel, color: string, consoleFn: (...args: unknown[]) => void) =>
+  (message: string, data?: unknown, stack?: string): void => {
+    if (getCurrentLogLevel() <= LOG_LEVELS[level]) {
+      const stackTrace = formatStack(stack);
+      consoleFn(
+        `${color}${formatLog(level, message, data)}${stackTrace}${COLORS.reset}`,
+      );
+    }
+  };
+
+export const logger = {
+  debug: log("debug", COLORS.gray, console.log),
+  info: log("info", COLORS.blue, console.log),
+  warn: log("warn", COLORS.yellow, console.warn),
+  error: log("error", COLORS.red, console.error),
+  fatal: log("fatal", `${COLORS.red}${COLORS.magenta}`, console.error),
+};

package/template/ts/src/utils/response.js

@@ -0,0 +1,51 @@
+/**
+ * Send success response
+ *
+ * @param {Response} res - Express response object
+ * @param {*} data - Response data
+ * @param {number} statusCode - HTTP status code (default: 200)
+ * @param {string} message - Success message (default: 'Success')
+ */
+export const sendSuccess = (
+  res,
+  data,
+  statusCode = 200,
+  message = "Success",
+) => {
+  return res.status(statusCode).json({
+    success: true,
+    message,
+    data,
+    timestamp: new Date().toISOString(),
+  });
+};
+
+/**
+ * Send error response (DEPRECATED - use AppError instead)
+ * This is kept for backward compatibility
+ */
+export const sendError = (res, message, statusCode = 500, errors = null) => {
+  return res.status(statusCode).json({
+    success: false,
+    message,
+    ...(errors && { errors }),
+    timestamp: new Date().toISOString(),
+  });
+};
+
+/**
+ * Send validation error response (DEPRECATED - use ValidationError instead)
+ * This is kept for backward compatibility
+ */
+export const sendValidationError = (res, errors, statusCode = 422) => {
+  return res.status(statusCode).json({
+    success: false,
+    message: "Validation failed",
+    errors: errors.map((err) => ({
+      field: err.path.join("."),
+      message: err.message,
+      code: err.code,
+    })),
+    timestamp: new Date().toISOString(),
+  });
+};

package/template/ts/src/utils/response.ts

@@ -0,0 +1,100 @@
+import type { Response } from "express";
+
+/**
+ * Standard success response shape
+ */
+export type SuccessResponse<T> = {
+  success: true;
+  message: string;
+  data: T;
+  timestamp: string;
+};
+
+/**
+ * Send success response
+ */
+export const sendSuccess = <T>(
+  res: Response,
+  data: T,
+  statusCode = 200,
+  message = "Success",
+): Response<SuccessResponse<T>> => {
+  return res.status(statusCode).json({
+    success: true,
+    message,
+    data,
+    timestamp: new Date().toISOString(),
+  });
+};
+
+/**
+ * Error response shape (legacy)
+ */
+type ErrorResponse = {
+  success: false;
+  message: string;
+  errors?: unknown;
+  timestamp: string;
+};
+
+/**
+ * Send error response (DEPRECATED — use AppError instead)
+ * Kept for backward compatibility
+ */
+export const sendError = (
+  res: Response,
+  message: string,
+  statusCode = 500,
+  errors: unknown = null,
+): Response<ErrorResponse> => {
+  return res.status(statusCode).json({
+    success: false,
+    message,
+    ...(errors !== null && { errors }),
+    timestamp: new Date().toISOString(),
+  });
+};
+
+/**
+ * Validation error item (Zod / Joi–style compatible)
+ */
+type ValidationIssue = {
+  path: (string | number)[];
+  message: string;
+  code?: string;
+};
+
+/**
+ * Validation error response shape
+ */
+type ValidationErrorResponse = {
+  success: false;
+  message: string;
+  errors: {
+    field: string;
+    message: string;
+    code?: string;
+  }[];
+  timestamp: string;
+};
+
+/**
+ * Send validation error response (DEPRECATED — use ValidationError instead)
+ * Kept for backward compatibility
+ */
+export const sendValidationError = (
+  res: Response,
+  errors: ValidationIssue[],
+  statusCode = 422,
+): Response<ValidationErrorResponse> => {
+  return res.status(statusCode).json({
+    success: false,
+    message: "Validation failed",
+    errors: errors.map((err) => ({
+      field: err.path.join("."),
+      message: err.message,
+      code: err.code,
+    })),
+    timestamp: new Date().toISOString(),
+  });
+};

package/template/ts/test-api.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+import http from "http";
+
+const tests = [
+  {
+    name: "Test 1: GET / (root)",
+    method: "GET",
+    path: "/",
+    body: null,
+  },
+  {
+    name: "Test 2: GET /api/health",
+    method: "GET",
+    path: "/api/health",
+    body: null,
+  },
+  {
+    name: "Test 3: POST /api/items (valid)",
+    method: "POST",
+    path: "/api/items",
+    body: JSON.stringify({ name: "Test Item", description: "A test item" }),
+  },
+  {
+    name: "Test 4: POST /api/items (invalid - missing name)",
+    method: "POST",
+    path: "/api/items",
+    body: JSON.stringify({ description: "No name" }),
+  },
+  {
+    name: "Test 5: GET /api/nonexistent (404)",
+    method: "GET",
+    path: "/api/nonexistent",
+    body: null,
+  },
+];
+
+const runTest = (test) => {
+  return new Promise((resolve) => {
+    const options = {
+      hostname: "localhost",
+      port: 3000,
+      path: test.path,
+      method: test.method,
+      headers: {
+        "Content-Type": "application/json",
+      },
+    };
+
+    const req = http.request(options, (res) => {
+      let data = "";
+
+      res.on("data", (chunk) => {
+        data += chunk;
+      });
+
+      res.on("end", () => {
+        try {
+          const json = JSON.parse(data);
+          console.log(`\n✅ ${test.name}`);
+          console.log(`   Status: ${res.statusCode}`);
+          console.log(`   Response:`, JSON.stringify(json, null, 2));
+        } catch (error) {
+          console.log(`\n✅ ${test.name}`);
+          console.log(`   Status: ${res.statusCode}`);
+          console.log(`   Response:`, data);
+        }
+        resolve();
+      });
+    });
+
+    req.on("error", (error) => {
+      console.error(`\n❌ ${test.name}`);
+      console.error(`   Error: ${error.message}`);
+      resolve();
+    });
+
+    if (test.body) {
+      req.write(test.body);
+    }
+    req.end();
+  });
+};
+
+const runTests = async () => {
+  console.log("🚀 Testing Charcole API Error Handling\n");
+  console.log("=".repeat(60));
+
+  for (const test of tests) {
+    await runTest(test);
+    await new Promise((r) => setTimeout(r, 200));
+  }
+
+  console.log("\n" + "=".repeat(60));
+  console.log("\n✅ All tests completed!");
+  process.exit(0);
+};
+
+// Wait for server to be ready
+setTimeout(runTests, 1000);

package/template/ts/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "rootDir": "src",
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "allowJs": false,
+    "noEmitOnError": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}