karos 1.0.0

package/README.md

@@ -0,0 +1,103 @@
+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.
+
+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 full of conditionals
+    
+*   Teams re-implement the same response boilerplate in every project
+    
+
+There is no shared contract between backend and frontend.
+
+What Karos Enforces
+-------------------
+
+Karos enforces **one response contract** for your entire API.
+
+Success
+-------
+
+Plain textANTLR4BashCC#CSSCoffeeScriptCMakeDartDjangoDockerEJSErlangGitGoGraphQLGroovyHTMLJavaJavaScriptJSONJSXKotlinLaTeXLessLuaMakefileMarkdownMATLABMarkupObjective-CPerlPHPPowerShell.propertiesProtocol BuffersPythonRRubySass (Sass)Sass (Scss)SchemeSQLShellSwiftSVGTSXTypeScriptWebAssemblyYAMLXML`   json{    "success": true,    "data": {}  }   `
+
+Error
+-----
+
+Plain textANTLR4BashCC#CSSCoffeeScriptCMakeDartDjangoDockerEJSErlangGitGoGraphQLGroovyHTMLJavaJavaScriptJSONJSXKotlinLaTeXLessLuaMakefileMarkdownMATLABMarkupObjective-CPerlPHPPowerShell.propertiesProtocol BuffersPythonRRubySass (Sass)Sass (Scss)SchemeSQLShellSwiftSVGTSXTypeScriptWebAssemblyYAMLXML`   json{    "success": false,    "error": {      "code": "NOT_FOUND",      "message": "User not found"    }  }   `
+
+No exceptions. No special cases.
+
+Install + Usage (60 seconds)
+----------------------------
+
+Plain textANTLR4BashCC#CSSCoffeeScriptCMakeDartDjangoDockerEJSErlangGitGoGraphQLGroovyHTMLJavaJavaScriptJSONJSXKotlinLaTeXLessLuaMakefileMarkdownMATLABMarkupObjective-CPerlPHPPowerShell.propertiesProtocol BuffersPythonRRubySass (Sass)Sass (Scss)SchemeSQLShellSwiftSVGTSXTypeScriptWebAssemblyYAMLXML`   bashnpm install karos   `
+
+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
+--------
+
+**ok(res, data, message?, meta?)**Formats a successful response.
+
+Plain textANTLR4BashCC#CSSCoffeeScriptCMakeDartDjangoDockerEJSErlangGitGoGraphQLGroovyHTMLJavaJavaScriptJSONJSXKotlinLaTeXLessLuaMakefileMarkdownMATLABMarkupObjective-CPerlPHPPowerShell.propertiesProtocol BuffersPythonRRubySass (Sass)Sass (Scss)SchemeSQLShellSwiftSVGTSXTypeScriptWebAssemblyYAMLXML`   ok(res, user);  ok(res, user, 'User fetched');   `
+
+**notFoundError(message?)**Prebuilt helpers (autocomplete-safe).
+
+Plain textANTLR4BashCC#CSSCoffeeScriptCMakeDartDjangoDockerEJSErlangGitGoGraphQLGroovyHTMLJavaJavaScriptJSONJSXKotlinLaTeXLessLuaMakefileMarkdownMATLABMarkupObjective-CPerlPHPPowerShell.propertiesProtocol BuffersPythonRRubySass (Sass)Sass (Scss)SchemeSQLShellSwiftSVGTSXTypeScriptWebAssemblyYAMLXML`   notFoundError();                           // 404 "Not found"  validationError('Invalid email');          // 400  unauthorizedError();                       // 401   `
+
+**errorHandler**Express middleware that:
+
+*   Catches all thrown Karos errors
+    
+*   Formats unknown errors as INTERNAL\_ERROR
+    
+*   Preserves correct HTTP status codes
+    
+
+Plain textANTLR4BashCC#CSSCoffeeScriptCMakeDartDjangoDockerEJSErlangGitGoGraphQLGroovyHTMLJavaJavaScriptJSONJSXKotlinLaTeXLessLuaMakefileMarkdownMATLABMarkupObjective-CPerlPHPPowerShell.propertiesProtocol BuffersPythonRRubySass (Sass)Sass (Scss)SchemeSQLShellSwiftSVGTSXTypeScriptWebAssemblyYAMLXML`   app.use(errorHandler);  // Last, after all routes   `
+
+Error Codes (Autocomplete)
+--------------------------
+
+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.
+
+Database Errors (Auto-handled)
+------------------------------
+
+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);  });   `
+
+**Zero try/catch needed.** Middleware formats everything.
+
+What Karos Does NOT Do (By Design)
+----------------------------------
+
+❌ No request validation❌ No authentication helpers❌ No logging❌ No database handling❌ No config files❌ No framework adapters (Fastify, Hono, etc.)
+
+**Pure formatting layer only.** Your business logic stays yours.
+
+TypeScript ✅
+------------
+
+Full types + autocomplete for ErrorCode.NOT\_FOUND, response shapes.
+
+License
+-------
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+import { Response, Request, NextFunction } from 'express';
+
+declare const ErrorCode: {
+    readonly VALIDATION_FAILED: "VALIDATION_FAILED";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly CONFLICT: "CONFLICT";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+};
+type ErrorCodeType = typeof ErrorCode[keyof typeof ErrorCode];
+interface ApiSuccessResponse<T = unknown> {
+    success: true;
+    data: T;
+    message?: string;
+    meta?: Record<string, unknown>;
+}
+interface ApiErrorResponse {
+    success: false;
+    error: {
+        code: ErrorCodeType;
+        message: string;
+        errors?: Record<string, unknown>;
+    };
+}
+
+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 class KarosError extends Error {
+    readonly code: ErrorCodeType;
+    readonly status: number;
+    readonly errors?: Record<string, unknown>;
+    readonly isKarosError = true;
+    constructor(code: ErrorCodeType, message: string, status: number, errors?: Record<string, unknown>);
+}
+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 httpError: (code: ErrorCodeType, message: string, status: number, errors?: Record<string, unknown>) => never;
+
+declare function errorHandler(err: unknown, req: Request, res: Response, next: NextFunction): void;
+
+export { type ApiErrorResponse, type ApiSuccessResponse, ErrorCode, type ErrorCodeType, KarosError, errorHandler, fail, httpError, notFoundError, ok, unauthorizedError, validationError };

package/dist/index.js

@@ -0,0 +1,112 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ErrorCode: () => ErrorCode,
+  KarosError: () => KarosError,
+  errorHandler: () => errorHandler,
+  fail: () => fail,
+  httpError: () => httpError,
+  notFoundError: () => notFoundError,
+  ok: () => ok,
+  unauthorizedError: () => unauthorizedError,
+  validationError: () => validationError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/types.ts
+var ErrorCode = {
+  VALIDATION_FAILED: "VALIDATION_FAILED",
+  UNAUTHORIZED: "UNAUTHORIZED",
+  NOT_FOUND: "NOT_FOUND",
+  FORBIDDEN: "FORBIDDEN",
+  CONFLICT: "CONFLICT",
+  INTERNAL_ERROR: "INTERNAL_ERROR"
+};
+
+// src/responses.ts
+function ok(res, data, message, meta) {
+  const response = {
+    success: true,
+    data,
+    ...message && { message },
+    ...meta && { meta }
+  };
+  res.status(200).json(response);
+}
+function fail(res, code, message, status, errors) {
+  const response = {
+    success: false,
+    error: { code, message, ...errors && { errors } }
+  };
+  res.status(status).json(response);
+}
+
+// src/errors.ts
+var KarosError = class _KarosError extends Error {
+  constructor(code, message, status, errors) {
+    super(message);
+    this.isKarosError = true;
+    this.code = code;
+    this.status = status;
+    this.errors = errors;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _KarosError);
+    }
+  }
+};
+var notFoundError = (message = "Not found", errors) => {
+  throw new KarosError("NOT_FOUND", message, 404, errors);
+};
+var validationError = (message = "Validation failed", errors) => {
+  throw new KarosError("VALIDATION_FAILED", message, 400, errors);
+};
+var unauthorizedError = (message = "Unauthorized", errors) => {
+  throw new KarosError("UNAUTHORIZED", message, 401, errors);
+};
+var httpError = (code, message, status, errors) => {
+  throw new KarosError(code, message, status, errors);
+};
+
+// src/middleware.ts
+function isKarosError(err) {
+  return typeof err === "object" && err !== null && err.isKarosError === true;
+}
+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);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ErrorCode,
+  KarosError,
+  errorHandler,
+  fail,
+  httpError,
+  notFoundError,
+  ok,
+  unauthorizedError,
+  validationError
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "karos",
+  "version": "1.0.0",
+  "description": "Opinionated API response and error handling for Node.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "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",    
+  "license": "MIT",
+  "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",
+    "@types/node": "^25.0.3",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "express": "^4.21.1"
+  }
+}