karos 1.0.3 → 1.0.4

package/dist/index.d.ts

@@ -1,12 +1,14 @@
-import { Response, Request, NextFunction } from 'express';
+import { Response as Response$1, Request, NextFunction } from 'express';
 
 declare const ErrorCode: {
     readonly VALIDATION_FAILED: "VALIDATION_FAILED";
+    readonly BAD_REQUEST: "BAD_REQUEST";
     readonly UNAUTHORIZED: "UNAUTHORIZED";
-    readonly NOT_FOUND: "NOT_FOUND";
     readonly FORBIDDEN: "FORBIDDEN";
+    readonly NOT_FOUND: "NOT_FOUND";
     readonly CONFLICT: "CONFLICT";
     readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
 };
 type ErrorCodeType = typeof ErrorCode[keyof typeof ErrorCode];
 interface ApiSuccessResponse<T = unknown> {
@@ -24,8 +26,8 @@ interface ApiErrorResponse {
     };
 }
 
-declare function ok<T = unknown>(res: Response, data: T, message?: string, meta?: Record<string, unknown>): void;
-declare function fail(res: Response, code: ErrorCodeType, message: string, status: number, errors?: Record<string, unknown>): void;
+declare function ok<T = unknown>(res: Response$1, data: T, message?: string, meta?: Record<string, unknown>): void;
+declare function fail(res: Response$1, code: ErrorCodeType, message: string, status: number, errors?: Record<string, unknown>): void;
 
 declare class KarosError extends Error {
     readonly code: ErrorCodeType;
@@ -33,12 +35,51 @@ declare class KarosError extends Error {
     readonly errors?: Record<string, unknown>;
     readonly isKarosError = true;
     constructor(code: ErrorCodeType, message: string, status: number, errors?: Record<string, unknown>);
+    toJSON(): {
+        success: boolean;
+        error: {
+            code: ErrorCodeType;
+            message: string;
+            details: Record<string, unknown> | undefined;
+        };
+    };
 }
 declare const notFoundError: (message?: string, errors?: Record<string, unknown>) => never;
 declare const validationError: (message?: string, errors?: Record<string, unknown>) => never;
 declare const unauthorizedError: (message?: string, errors?: Record<string, unknown>) => never;
+declare const forbiddenError: (message?: string, errors?: Record<string, unknown>) => never;
+declare const conflictError: (message?: string, errors?: Record<string, unknown>) => never;
+declare const internalError: (message?: string, errors?: Record<string, unknown>) => never;
 declare const httpError: (code: ErrorCodeType, message: string, status: number, errors?: Record<string, unknown>) => never;
 
-declare function errorHandler(err: unknown, req: Request, res: Response, next: NextFunction): void;
+declare function errorHandler(err: unknown, req: Request, res: Response$1, next: NextFunction): void;
+
+/**
+ * Next.js / Web Standard Helper
+ * Returns a standardized SUCCESS Response object.
+ */
+declare function nextOk<T = unknown>(data: T, message?: string, status?: number, meta?: Record<string, unknown>): Response;
+/**
+ * Next.js / Web Standard Helper
+ * Returns a standardized ERROR Response object.
+ */
+declare function nextFail(code: ErrorCodeType, message: string, status: number, errors?: Record<string, unknown>): Response;
+/**
+ * Global Error Handler for Next.js App Router.
+ * Automatically detects:
+ * 1. KarosErrors (thrown manually)
+ * 2. Database Errors (Prisma, Mongo)
+ * 3. Unknown crashes (returns 500)
+ *
+ * Usage:
+ * try { ... } catch (err) { return handleNextError(err); }
+ */
+declare function handleNextError(err: any): Response;
+
+/**
+ * Examines an error object and determines if it is a known database error.
+ * Supports: Prisma, Mongoose, MongoDB driver
+ */
+declare function resolveDbError(err: any): KarosError | null;
 
-export { type ApiErrorResponse, type ApiSuccessResponse, ErrorCode, type ErrorCodeType, KarosError, errorHandler, fail, httpError, notFoundError, ok, unauthorizedError, validationError };
+export { type ApiErrorResponse, type ApiSuccessResponse, ErrorCode, type ErrorCodeType, KarosError, conflictError, errorHandler, fail, forbiddenError, handleNextError, httpError, internalError, nextFail, nextOk, notFoundError, ok, resolveDbError, unauthorizedError, validationError };

package/dist/index.js

@@ -22,11 +22,18 @@ var index_exports = {};
 __export(index_exports, {
   ErrorCode: () => ErrorCode,
   KarosError: () => KarosError,
+  conflictError: () => conflictError,
   errorHandler: () => errorHandler,
   fail: () => fail,
+  forbiddenError: () => forbiddenError,
+  handleNextError: () => handleNextError,
   httpError: () => httpError,
+  internalError: () => internalError,
+  nextFail: () => nextFail,
+  nextOk: () => nextOk,
   notFoundError: () => notFoundError,
   ok: () => ok,
+  resolveDbError: () => resolveDbError,
   unauthorizedError: () => unauthorizedError,
   validationError: () => validationError
 });
@@ -35,11 +42,21 @@ module.exports = __toCommonJS(index_exports);
 // src/types.ts
 var ErrorCode = {
   VALIDATION_FAILED: "VALIDATION_FAILED",
+  // 400
+  BAD_REQUEST: "BAD_REQUEST",
+  // 400 (Generic)
   UNAUTHORIZED: "UNAUTHORIZED",
-  NOT_FOUND: "NOT_FOUND",
+  // 401
   FORBIDDEN: "FORBIDDEN",
+  // 403
+  NOT_FOUND: "NOT_FOUND",
+  // 404
   CONFLICT: "CONFLICT",
-  INTERNAL_ERROR: "INTERNAL_ERROR"
+  // 409
+  INTERNAL_ERROR: "INTERNAL_ERROR",
+  // 500
+  SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE"
+  // 503 (Optional, good for external API failures)
 };
 
 // src/responses.ts
@@ -68,10 +85,24 @@ var KarosError = class _KarosError extends Error {
     this.code = code;
     this.status = status;
     this.errors = errors;
+    Object.setPrototypeOf(this, _KarosError.prototype);
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, _KarosError);
     }
   }
+  // ✅ New Helper: Converts error to standardized JSON format
+  // This will be reused by both Express Middleware and Next.js helpers
+  toJSON() {
+    return {
+      success: false,
+      error: {
+        code: this.code,
+        message: this.message,
+        details: this.errors || void 0
+        // Only show if exists
+      }
+    };
+  }
 };
 var notFoundError = (message = "Not found", errors) => {
   throw new KarosError("NOT_FOUND", message, 404, errors);
@@ -82,10 +113,46 @@ var validationError = (message = "Validation failed", errors) => {
 var unauthorizedError = (message = "Unauthorized", errors) => {
   throw new KarosError("UNAUTHORIZED", message, 401, errors);
 };
+var forbiddenError = (message = "Forbidden", errors) => {
+  throw new KarosError("FORBIDDEN", message, 403, errors);
+};
+var conflictError = (message = "Conflict", errors) => {
+  throw new KarosError("CONFLICT", message, 409, errors);
+};
+var internalError = (message = "Internal Server Error", errors) => {
+  throw new KarosError("INTERNAL_ERROR", message, 500, errors);
+};
 var httpError = (code, message, status, errors) => {
   throw new KarosError(code, message, status, errors);
 };
 
+// src/db-handler.ts
+function resolveDbError(err) {
+  if (!err) return null;
+  if (err.code === "P2002") {
+    const target = err.meta?.target ? ` (${err.meta.target})` : "";
+    return new KarosError(
+      ErrorCode.CONFLICT,
+      `Duplicate entry: Resource already exists${target}`,
+      409
+    );
+  }
+  if (err.code === "P2025") {
+    return new KarosError(ErrorCode.NOT_FOUND, "Record not found", 404);
+  }
+  if (err.code === 11e3 || err.errorResponse && err.errorResponse.code === 11e3) {
+    return new KarosError(ErrorCode.CONFLICT, "Duplicate entry: Resource already exists", 409);
+  }
+  if (err.name === "ValidationError") {
+    const details = {};
+    for (const field in err.errors) {
+      details[field] = err.errors[field].message;
+    }
+    return new KarosError(ErrorCode.VALIDATION_FAILED, "Database validation failed", 400, details);
+  }
+  return null;
+}
+
 // src/middleware.ts
 function isKarosError(err) {
   return typeof err === "object" && err !== null && err.isKarosError === true;
@@ -94,19 +161,71 @@ function errorHandler(err, req, res, next) {
   if (res.headersSent) return next(err);
   if (isKarosError(err)) {
     fail(res, err.code, err.message, err.status, err.errors);
-  } else {
-    fail(res, ErrorCode.INTERNAL_ERROR, "Internal server error", 500);
+    return;
+  }
+  const dbError = resolveDbError(err);
+  if (dbError) {
+    fail(res, dbError.code, dbError.message, dbError.status, dbError.errors);
+    return;
+  }
+  console.error("[Karos] Unexpected Error:", err);
+  fail(res, ErrorCode.INTERNAL_ERROR, "Internal server error", 500);
+}
+
+// src/next.ts
+function nextOk(data, message, status = 200, meta) {
+  const body = {
+    success: true,
+    data,
+    ...message && { message },
+    ...meta && { meta }
+  };
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+function nextFail(code, message, status, errors) {
+  const body = {
+    success: false,
+    error: {
+      code,
+      message,
+      ...errors && { errors }
+    }
+  };
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+function handleNextError(err) {
+  if (err && err.isKarosError) {
+    return nextFail(err.code, err.message, err.status, err.errors);
+  }
+  const dbErr = resolveDbError(err);
+  if (dbErr) {
+    return nextFail(dbErr.code, dbErr.message, dbErr.status, dbErr.errors);
   }
+  console.error("[Karos Next] Unexpected Error:", err);
+  return nextFail(ErrorCode.INTERNAL_ERROR, "Internal Server Error", 500);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ErrorCode,
   KarosError,
+  conflictError,
   errorHandler,
   fail,
+  forbiddenError,
+  handleNextError,
   httpError,
+  internalError,
+  nextFail,
+  nextOk,
   notFoundError,
   ok,
+  resolveDbError,
   unauthorizedError,
   validationError
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karos",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Opinionated API response and error handling for Node.js",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,7 +17,10 @@
     "express",
     "error-handling",
     "node",
-    "backend"
+    "backend",
+    "nextjs",
+    "node",
+    "error-structure"
   ],
   "author": "Krishna Shrivastava",
   "license": "MIT",