backend-error 1.2.0 → 1.2.2

package/README.md

@@ -72,6 +72,8 @@ const error = new BackendError({
 
 ## ⚙️ Static error helpers
 
+Available helpers (status, showUser, severity):
+
 ```ts
 BackendError.BadRequest("..."); // 400, showUser: true
 BackendError.Unauthorized("..."); // 401, showUser: true
@@ -79,8 +81,34 @@ BackendError.Forbidden("..."); // 403, showUser: true
 BackendError.NotFound("..."); // 404, showUser: true
 BackendError.Conflict("..."); // 409, showUser: true
 BackendError.UnprocessableEntity("..."); // 422, showUser: true
+BackendError.FailedDependency("..."); // 424, showUser: true
 BackendError.Internal("..."); // 500, showUser: false
+BackendError.NotImplemented("..."); // 501, showUser: true
+BackendError.ExternalAPI("..."); // 502, showUser: true
 BackendError.ServiceUnavailable("..."); // 503, showUser: false
+BackendError.GatewayTimeout("..."); // 504, showUser: false
+BackendError.InsufficientStorage("..."); // 507, showUser: false
+```
+
+Notes:
+
+- 4xx helpers generally have `showUser: true` so clients get actionable messages.
+- 5xx helpers are usually `showUser: false` to avoid leaking internals, except `NotImplemented` and `ExternalAPI` which intentionally expose helpful client-facing messages.
+
+### External / upstream errors
+
+Use `ExternalAPI` for failures originating from upstream services (Stripe, bank APIs, HR systems etc). It defaults to HTTP `502 Bad Gateway`, `showUser: true` (so the user gets a helpful message), and `severity: "critical"`.
+
+Example:
+
+```ts
+try {
+  // call an external API
+  await chargeCard();
+} catch (err) {
+  // Indicate the error came from an external API — user can be informed
+  throw BackendError.ExternalAPI("Payment provider unavailable"); // 502, showUser: true
+}
 ```
 
 ---
@@ -109,6 +137,14 @@ app.get("/user/:id", async (req, res) => {
 
 ## 🧩 Types
 
+The package re-exports TypeScript types so you get full typings when consuming the package. Import types like this:
+
+```ts
+import type { BackendErrorOptions, Severity } from "backend-error";
+```
+
+For reference, the exported types look like:
+
 ```ts
 export type Severity = "info" | "warning" | "error" | "critical";
 

package/dist/core/BackendError.d.ts

@@ -1,17 +1,23 @@
-import { BackendErrorOptions, Severity } from "../interfaces/Types";
-export declare class BackendError extends Error {
-    isOperational: boolean;
-    showUser: boolean;
-    severity: Severity;
-    code?: number;
-    data?: any;
-    constructor(options: BackendErrorOptions);
-    static BadRequest(msg: string): BackendError;
-    static Unauthorized(msg: string): BackendError;
-    static Forbidden(msg: string): BackendError;
-    static NotFound(msg: string): BackendError;
-    static Conflict(msg: string): BackendError;
-    static UnprocessableEntity(msg: string): BackendError;
-    static Internal(msg: string): BackendError;
-    static ServiceUnavailable(msg: string): BackendError;
-}
+import { BackendErrorOptions, Severity } from "../interfaces/Types";
+export declare class BackendError extends Error {
+    isOperational: boolean;
+    showUser: boolean;
+    severity: Severity;
+    code?: number;
+    data?: any;
+    constructor(options: BackendErrorOptions);
+    static BadRequest(msg: string): BackendError;
+    static Unauthorized(msg: string): BackendError;
+    static Forbidden(msg: string): BackendError;
+    static NotFound(msg: string): BackendError;
+    static Conflict(msg: string): BackendError;
+    static UnprocessableEntity(msg: string): BackendError;
+    static FailedDependency(msg: string): BackendError;
+    static Internal(msg: string): BackendError;
+    static NotImplemented(msg: string): BackendError;
+    static ExternalAPI(msg: string, code?: number): BackendError;
+    static ServiceUnavailable(msg: string): BackendError;
+    static GatewayTimeout(msg: string): BackendError;
+    static InsufficientStorage(msg: string): BackendError;
+}
+//# sourceMappingURL=BackendError.d.ts.map

package/dist/core/BackendError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BackendError.d.ts","sourceRoot":"","sources":["../../src/core/BackendError.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpE,qBAAa,YAAa,SAAQ,KAAK;IAC9B,aAAa,EAAE,OAAO,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,GAAG,CAAC;gBAEN,OAAO,EAAE,mBAAmB;IAcxC,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM;IAI7B,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM;IAI/B,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,MAAM;IAI5B,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM;IAK3B,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM;IAK3B,MAAM,CAAC,mBAAmB,CAAC,GAAG,EAAE,MAAM;IAItC,MAAM,CAAC,gBAAgB,CAAC,GAAG,EAAE,MAAM;IAKnC,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM;IAI3B,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,MAAM;IAIjC,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,MAAY;IAIlD,MAAM,CAAC,kBAAkB,CAAC,GAAG,EAAE,MAAM;IAIrC,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,MAAM;IAIjC,MAAM,CAAC,mBAAmB,CAAC,GAAG,EAAE,MAAM;CAGvC"}

package/dist/core/BackendError.js

@@ -13,6 +13,7 @@ class BackendError extends Error {
         this.data = options.data;
         Object.setPrototypeOf(this, BackendError.prototype);
     }
+    // Ordered by HTTP status code (ascending)
     static BadRequest(msg) {
         return new BackendError({ message: msg, code: 400, severity: "warning", showUser: true });
     }
@@ -25,21 +26,36 @@ class BackendError extends Error {
     static NotFound(msg) {
         return new BackendError({ message: msg, code: 404, severity: "warning", showUser: true });
     }
+    // 409 Conflict variants
     static Conflict(msg) {
         return new BackendError({ message: msg, code: 409, severity: "warning", showUser: true });
     }
+    // 422 Unprocessable / validation
     static UnprocessableEntity(msg) {
         return new BackendError({ message: msg, code: 422, severity: "warning", showUser: true });
     }
+    static FailedDependency(msg) {
+        return new BackendError({ message: msg, code: 424, severity: "warning", showUser: true });
+    }
+    // 5xx server errors
     static Internal(msg) {
         return new BackendError({ message: msg, code: 500, severity: "critical", showUser: false });
     }
+    static NotImplemented(msg) {
+        return new BackendError({ message: msg, code: 501, severity: "error", showUser: true });
+    }
     static ExternalAPI(msg, code = 502) {
-        return new BackendError({ message: msg, code, severity: "warning", showUser: true });
+        return new BackendError({ message: msg, code, severity: "critical", showUser: true });
     }
     static ServiceUnavailable(msg) {
         return new BackendError({ message: msg, code: 503, severity: "critical", showUser: false });
     }
+    static GatewayTimeout(msg) {
+        return new BackendError({ message: msg, code: 504, severity: "critical", showUser: false });
+    }
+    static InsufficientStorage(msg) {
+        return new BackendError({ message: msg, code: 507, severity: "critical", showUser: false });
+    }
 }
 exports.BackendError = BackendError;
 //# sourceMappingURL=BackendError.js.map

package/dist/core/BackendError.js.map

@@ -1 +1 @@
-{"version":3,"file":"BackendError.js","sourceRoot":"","sources":["../../src/core/BackendError.ts"],"names":[],"mappings":";;;AAEA,MAAa,YAAa,SAAQ,KAAK;IAOrC,YAAY,OAA4B;;QACtC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAE3B,IAAI,CAAC,aAAa,GAAG,MAAA,OAAO,CAAC,aAAa,mCAAI,IAAI,CAAC;QACnD,IAAI,CAAC,QAAQ,GAAG,MAAA,OAAO,CAAC,QAAQ,mCAAI,IAAI,CAAC;QACzC,IAAI,CAAC,QAAQ,GAAG,MAAA,OAAO,CAAC,QAAQ,mCAAI,OAAO,CAAC;QAC5C,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QAEzB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IACtD,CAAC;IAED,MAAM,CAAC,UAAU,CAAC,GAAW;QAC3B,OAAO,IAAI,YAAY,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5F,CAAC;IAED,MAAM,CAAC,YAAY,CAAC,GAAW;QAC7B,OAAO,IAAI,YAAY,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5F,CAAC;IAED,MAAM,CAAC,SAAS,CAAC,GAAW;QAC1B,OAAO,IAAI,YAAY,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5F,CAAC;IAED,MAAM,CAAC,QAAQ,CAAC,GAAW;QACzB,OAAO,IAAI,YAAY,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5F,CAAC;IAED,MAAM,CAAC,QAAQ,CAAC,GAAW;QACzB,OAAO,IAAI,YAAY,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5F,CAAC;IAED,MAAM,CAAC,mBAAmB,CAAC,GAAW;QACpC,OAAO,IAAI,YAAY,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5F,CAAC;IAED,MAAM,CAAC,QAAQ,CAAC,GAAW;QACzB,OAAO,IAAI,YAAY,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;IAC9F,CAAC;IAED,MAAM,CAAC,WAAW,CAAC,GAAW,EAAE,OAAe,GAAG;QAChD,OAAO,IAAI,YAAY,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IACvF,CAAC;IAED,MAAM,CAAC,kBAAkB,CAAC,GAAW;QACnC,OAAO,IAAI,YAAY,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;IAC9F,CAAC;CACF;AAvDD,oCAuDC"}
+{"version":3,"file":"BackendError.js","sourceRoot":"","sources":["../../src/core/BackendError.ts"],"names":[],"mappings":"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"}

package/dist/core/httpErrorFormatter.d.ts

@@ -1,6 +1,7 @@
-export declare function httpErrorFormatter(err: unknown): {
-    status: number;
-    body: Record<string, any>;
-    showUser: boolean;
-    message: string;
-};
+export declare function httpErrorFormatter(err: unknown): {
+    status: number;
+    body: Record<string, any>;
+    showUser: boolean;
+    message: string;
+};
+//# sourceMappingURL=httpErrorFormatter.d.ts.map

package/dist/core/httpErrorFormatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpErrorFormatter.d.ts","sourceRoot":"","sources":["../../src/core/httpErrorFormatter.ts"],"names":[],"mappings":"AAMA,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,CA8CA"}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
-export { BackendError } from "./core/BackendError";
-export { httpErrorFormatter } from "./core/httpErrorFormatter";
-export type { BackendErrorOptions, Severity } from "./interfaces/Types";
+export { BackendError } from "./core/BackendError";
+export { httpErrorFormatter } from "./core/httpErrorFormatter";
+export type { BackendErrorOptions, Severity } from "./interfaces/Types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,YAAY,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/interfaces/Types.d.ts

@@ -1,9 +1,10 @@
-export type Severity = "info" | "warning" | "error" | "critical";
-export interface BackendErrorOptions {
-    message: string;
-    isOperational?: boolean;
-    showUser?: boolean;
-    severity?: Severity;
-    code?: number;
-    data?: any;
-}
+export type Severity = "info" | "warning" | "error" | "critical";
+export interface BackendErrorOptions {
+    message: string;
+    isOperational?: boolean;
+    showUser?: boolean;
+    severity?: Severity;
+    code?: number;
+    data?: any;
+}
+//# sourceMappingURL=Types.d.ts.map

package/dist/interfaces/Types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Types.d.ts","sourceRoot":"","sources":["../../src/interfaces/Types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,CAAC;AAEjE,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,GAAG,CAAC;CACZ"}

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.2.0",
+  "version": "1.2.2",
   "name": "backend-error",
   "license": "MIT",
   "keywords": [