karos 1.0.1 → 1.0.4

package/README.md

@@ -1,103 +1,167 @@
-karos
-=====
+# Karos
 
 **Opinionated, minimal API response & error standardization for Express.**
 
-Karos enforces predictable JSON response shapes and centralized error handling in Node.js APIs — without adding business logic, configuration, or framework lock-in.
+Karos enforces a single, predictable JSON response contract across your entire Node.js API — without adding business logic, configuration, or framework lock-in.
 
-The Problem
------------
+---
+
+## 🚫 The Problem
 
 In most Express backends:
+- ❌ Every route formats responses differently
+- ❌ Errors are sometimes strings, sometimes objects
+- ❌ Status codes are inconsistent
+- ❌ Frontend logic becomes fragile and conditional-heavy
+- ❌ Teams rewrite the same response boilerplate in every project
+
+**There is no enforced backend–frontend contract.**
+
+## ✅ The Solution
+
+Karos fixes exactly this problem — nothing more, nothing less. It enforces **one response contract** for your entire API.
+
+### Success Response
+```json
+{
+  "success": true,
+  "data": {
+    "id": 123,
+    "name": "Alice"
+  }
+}
+```
+
+### Error Response
+```json
+{
+  "success": false,
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "User not found"
+  }
+}
+```
 
-*   Every route formats responses differently
-    
-*   Errors are sometimes strings, sometimes objects
-    
-*   Status codes are inconsistent
-    
-*   Frontend logic becomes fragile and full of conditionals
-    
-*   Teams re-implement the same response boilerplate in every project
-    
+No exceptions. No special cases.
 
-There is no shared contract between backend and frontend.
+---
 
-What Karos Enforces
--------------------
+## 📦 Installation
 
-Karos enforces **one response contract** for your entire API.
+```bash
+npm install karos
+```
 
-Success
--------
+---
 
-Plain textANTLR4BashCC#CSSCoffeeScriptCMakeDartDjangoDockerEJSErlangGitGoGraphQLGroovyHTMLJavaJavaScriptJSONJSXKotlinLaTeXLessLuaMakefileMarkdownMATLABMarkupObjective-CPerlPHPPowerShell.propertiesProtocol BuffersPythonRRubySass (Sass)Sass (Scss)SchemeSQLShellSwiftSVGTSXTypeScriptWebAssemblyYAMLXML`   json{    "success": true,    "data": {}  }   `
+## 🚀 Quick Start (60 seconds)
 
-Error
------
+Karos replaces manual `try/catch` blocks and inconsistent response formatting.
 
-Plain textANTLR4BashCC#CSSCoffeeScriptCMakeDartDjangoDockerEJSErlangGitGoGraphQLGroovyHTMLJavaJavaScriptJSONJSXKotlinLaTeXLessLuaMakefileMarkdownMATLABMarkupObjective-CPerlPHPPowerShell.propertiesProtocol BuffersPythonRRubySass (Sass)Sass (Scss)SchemeSQLShellSwiftSVGTSXTypeScriptWebAssemblyYAMLXML`   json{    "success": false,    "error": {      "code": "NOT_FOUND",      "message": "User not found"    }  }   `
+### 1. Basic Setup
 
-No exceptions. No special cases.
+```js
+const express = require('express');
+const { ok, notFoundError, errorHandler } = require('karos');
+
+const app = express();
+app.use(express.json());
+
+// --- Your Routes ---
+
+app.get('/users/:id', async (req, res) => {
+  const user = await db.findUser(req.params.id);
+
+  if (!user) {
+    // Throws automatically -> Middleware catches it
+    notFoundError('User not found');
+  }
+
+  // Returns standardized 200 OK
+  ok(res, user);
+});
+
+// --- ONE middleware catches everything ---
+// Must be placed after all routes
+app.use(errorHandler);
 
-Install + Usage (60 seconds)
-----------------------------
+app.listen(3000, () => console.log('Server running on port 3000'));
+```
 
-Plain textANTLR4BashCC#CSSCoffeeScriptCMakeDartDjangoDockerEJSErlangGitGoGraphQLGroovyHTMLJavaJavaScriptJSONJSXKotlinLaTeXLessLuaMakefileMarkdownMATLABMarkupObjective-CPerlPHPPowerShell.propertiesProtocol BuffersPythonRRubySass (Sass)Sass (Scss)SchemeSQLShellSwiftSVGTSXTypeScriptWebAssemblyYAMLXML`   bashnpm install karos   `
+**Zero try/catch needed.** If your DB crashes, Karos catches it and returns a clean 500 `INTERNAL_ERROR`.
 
-Plain textANTLR4BashCC#CSSCoffeeScriptCMakeDartDjangoDockerEJSErlangGitGoGraphQLGroovyHTMLJavaJavaScriptJSONJSXKotlinLaTeXLessLuaMakefileMarkdownMATLABMarkupObjective-CPerlPHPPowerShell.propertiesProtocol BuffersPythonRRubySass (Sass)Sass (Scss)SchemeSQLShellSwiftSVGTSXTypeScriptWebAssemblyYAMLXML`   const express = require('express');  const { ok, notFoundError, errorHandler } = require('karos');  const app = express();  app.use(express.json());  // Your routes here...  app.get('/users/:id', async (req, res) => {    const user = await db.findUser(req.params.id);    if (!user) {      notFoundError('User not found');  // Throws → middleware catches    }    ok(res, user);  });  // ONE middleware catches everything  app.use(errorHandler);  app.listen(3000);   `
+---
 
-No try/catch. No per-route error formatting. One consistent API surface.
+## 📚 Core API
 
-Core API
---------
+### `ok(res, data, message?, meta?)`
 
-**ok(res, data, message?, meta?)**Formats a successful response.
+Formats a successful response.
 
-Plain textANTLR4BashCC#CSSCoffeeScriptCMakeDartDjangoDockerEJSErlangGitGoGraphQLGroovyHTMLJavaJavaScriptJSONJSXKotlinLaTeXLessLuaMakefileMarkdownMATLABMarkupObjective-CPerlPHPPowerShell.propertiesProtocol BuffersPythonRRubySass (Sass)Sass (Scss)SchemeSQLShellSwiftSVGTSXTypeScriptWebAssemblyYAMLXML`   ok(res, user);  ok(res, user, 'User fetched');   `
+| Param | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `res` | `Response` | **Yes** | Express Response object |
+| `data` | `any` | **Yes** | The payload (object, array, string) |
+| `message` | `string` | No | Optional success message |
+| `meta` | `object` | No | Optional metadata (e.g., pagination info) |
 
-**notFoundError(message?)**Prebuilt helpers (autocomplete-safe).
+**Example:**
+```js
+ok(res, user);
+ok(res, user, 'User fetched successfully');
+```
 
-Plain textANTLR4BashCC#CSSCoffeeScriptCMakeDartDjangoDockerEJSErlangGitGoGraphQLGroovyHTMLJavaJavaScriptJSONJSXKotlinLaTeXLessLuaMakefileMarkdownMATLABMarkupObjective-CPerlPHPPowerShell.propertiesProtocol BuffersPythonRRubySass (Sass)Sass (Scss)SchemeSQLShellSwiftSVGTSXTypeScriptWebAssemblyYAMLXML`   notFoundError();                           // 404 "Not found"  validationError('Invalid email');          // 400  unauthorizedError();                       // 401   `
+---
 
-**errorHandler**Express middleware that:
+### Error Helpers
 
-*   Catches all thrown Karos errors
-    
-*   Formats unknown errors as INTERNAL\_ERROR
-    
-*   Preserves correct HTTP status codes
-    
+Prebuilt helpers that throw standardized errors. These stop execution immediately, so you don't need `return`.
 
-Plain textANTLR4BashCC#CSSCoffeeScriptCMakeDartDjangoDockerEJSErlangGitGoGraphQLGroovyHTMLJavaJavaScriptJSONJSXKotlinLaTeXLessLuaMakefileMarkdownMATLABMarkupObjective-CPerlPHPPowerShell.propertiesProtocol BuffersPythonRRubySass (Sass)Sass (Scss)SchemeSQLShellSwiftSVGTSXTypeScriptWebAssemblyYAMLXML`   app.use(errorHandler);  // Last, after all routes   `
+| Helper Function | HTTP Status | Error Code |
+| :--- | :--- | :--- |
+| `notFoundError(msg)` | **404** | `NOT_FOUND` |
+| `validationError(msg)` | **400** | `VALIDATION_FAILED` |
+| `unauthorizedError(msg)` | **401** | `UNAUTHORIZED` |
+| `forbiddenError(msg)` | **403** | `FORBIDDEN` |
+| `conflictError(msg)` | **409** | `CONFLICT` |
+| `internalError(msg)` | **500** | `INTERNAL_ERROR` |
 
-Error Codes (Autocomplete)
---------------------------
+**Example:**
+```js
+if (emailInvalid) validationError('Invalid email format');
+if (!isAdmin) forbiddenError('Admin access required');
+```
 
-Plain textANTLR4BashCC#CSSCoffeeScriptCMakeDartDjangoDockerEJSErlangGitGoGraphQLGroovyHTMLJavaJavaScriptJSONJSXKotlinLaTeXLessLuaMakefileMarkdownMATLABMarkupObjective-CPerlPHPPowerShell.propertiesProtocol BuffersPythonRRubySass (Sass)Sass (Scss)SchemeSQLShellSwiftSVGTSXTypeScriptWebAssemblyYAMLXML`   ErrorCode.NOT_FOUND          // 404  ErrorCode.VALIDATION_FAILED  // 400    ErrorCode.UNAUTHORIZED       // 401  ErrorCode.FORBIDDEN          // 403  ErrorCode.CONFLICT           // 409  ErrorCode.INTERNAL_ERROR     // 500   `
+---
 
-You control: message, status, structured details.Karos only enforces the response shape.
+### `errorHandler`
 
-Database Errors (Auto-handled)
-------------------------------
+Express middleware that:
+1. Catches all thrown Karos errors.
+2. Catches unexpected crashes (DB down, undefined variables).
+3. Formats unknown errors as `INTERNAL_ERROR` (500).
 
-Plain textANTLR4BashCC#CSSCoffeeScriptCMakeDartDjangoDockerEJSErlangGitGoGraphQLGroovyHTMLJavaJavaScriptJSONJSXKotlinLaTeXLessLuaMakefileMarkdownMATLABMarkupObjective-CPerlPHPPowerShell.propertiesProtocol BuffersPythonRRubySass (Sass)Sass (Scss)SchemeSQLShellSwiftSVGTSXTypeScriptWebAssemblyYAMLXML`   app.get('/orders', async (req, res) => {    const orders = await prisma.order.findMany();  // Crashes? → 500    ok(res, orders);  });   `
+```js
+// Add this as the very last middleware in your app
+app.use(errorHandler);
+```
 
-**Zero try/catch needed.** Middleware formats everything.
+---
 
-What Karos Does NOT Do (By Design)
-----------------------------------
+## TypeScript Support
 
-❌ No request validation❌ No authentication helpers❌ No logging❌ No database handling❌ No config files❌ No framework adapters (Fastify, Hono, etc.)
+Karos is written in TypeScript and includes full type definitions out of the box.
 
-**Pure formatting layer only.** Your business logic stays yours.
+- ✅ Full type safety
+- ✅ Autocomplete-safe error codes
 
-TypeScript ✅
-------------
+```ts
+import { ok, ErrorCode } from 'karos';
+```
 
-Full types + autocomplete for ErrorCode.NOT\_FOUND, response shapes.
+---
 
-License
--------
+## License
 
-MIT
+MIT

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,20 +1,31 @@
 {
   "name": "karos",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "description": "Opinionated API response and error handling for Node.js",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsup src/index.ts --format cjs --dts",
     "dev": "tsup src/index.ts --format cjs --watch --dts",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
-  "keywords": ["api", "express", "error-handling", "node", "backend"],
-  "author": "Krishna Shrivastava",    
+  "keywords": [
+    "api",
+    "express",
+    "error-handling",
+    "node",
+    "backend",
+    "nextjs",
+    "node",
+    "error-structure"
+  ],
+  "author": "Krishna Shrivastava",
   "license": "MIT",
-  "repository": "https://github.com/Krishna-Shrivastava-1/Karos",  
-  "bugs": "https://github.com/Krishna-Shrivastava-1/Karos/issues", 
+  "repository": "https://github.com/Krishna-Shrivastava-1/Karos",
+  "bugs": "https://github.com/Krishna-Shrivastava-1/Karos/issues",
   "type": "commonjs",
   "devDependencies": {
     "@types/express": "^5.0.6",