@lssm/lib.error 0.0.0-canary-20251120170226

package/README.md

@@ -0,0 +1,47 @@
+# @lssm/lib.error
+
+Standardized error handling primitives for LSSM applications.
+
+## Purpose
+
+To provide a consistent error model across the monorepo, enabling predictable error handling, serialization, and mapping to HTTP status codes and GraphQL errors.
+
+## Installation
+
+```bash
+npm install @lssm/lib.error
+# or
+bun add @lssm/lib.error
+```
+
+## Key Concepts
+
+- **AppError**: Base class for all application errors, carrying a `code` and optional `meta` data.
+- **Error Codes**: Centralized enum/registry of error codes (e.g., `NOT_FOUND`, `UNAUTHORIZED`).
+- **HTTP Mapping**: Utilities to map error codes to HTTP status codes (e.g., `NOT_FOUND` -> 404).
+
+## Exports
+
+- `AppError`: The base error class.
+- `codes`: Error code definitions.
+- `http`: HTTP status code helpers.
+
+## Usage
+
+```ts
+import { AppError, ErrorCode } from '@lssm/lib.error';
+
+// Throwing a known error
+throw new AppError(ErrorCode.NOT_FOUND, 'User not found', { userId: 123 });
+
+// Catching and handling
+try {
+  // ...
+} catch (err) {
+  if (err instanceof AppError) {
+    console.log(err.code); // 'NOT_FOUND'
+    console.log(err.meta); // { userId: 123 }
+  }
+}
+```
+

package/dist/appError.d.ts

@@ -0,0 +1,17 @@
+import { ErrorCode } from "./codes.js";
+
+//#region src/appError.d.ts
+
+/**
+ * Generic application error with code and optional details.
+ */
+declare class AppError extends Error {
+  code: ErrorCode;
+  details?: Record<string, unknown> | undefined;
+  constructor(code: ErrorCode, message: string, details?: Record<string, unknown> | undefined);
+}
+/** Type guard to detect AppError */
+declare function isAppError(err: unknown): err is AppError;
+//#endregion
+export { AppError, isAppError };
+//# sourceMappingURL=appError.d.ts.map

package/dist/appError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appError.d.ts","names":[],"sources":["../src/appError.ts"],"sourcesContent":[],"mappings":";;;;;;AAKA;AAEiB,cAFJ,QAAA,SAAiB,KAAA,CAEb;EAEI,IAAA,EAFJ,SAEI;EAFJ,OAAA,CAAA,EAEI,MAFJ,CAAA,MAAA,EAAA,OAAA,CAAA,GAAA,SAAA;EAEI,WAAA,CAAA,IAAA,EAFJ,SAEI,EAAA,OAAA,EAAA,MAAA,EAAA,OAAA,CAAA,EAAA,MAAA,CAAA,MAAA,EAAA,OAAA,CAAA,GAAA,SAAA;;;AASL,iBAAA,UAAA,CAAiC,GAAQ,EAAA,OAAA,CAAA,EAAA,GAAA,IAAR,QAAQ"}

package/dist/appError.js

@@ -0,0 +1,2 @@
+var e=class extends Error{constructor(e,t,n){super(t),this.code=e,this.details=n,Object.setPrototypeOf(this,new.target.prototype),this.name=`AppError`}};function t(t){return t instanceof e}export{e as AppError,t as isAppError};
+//# sourceMappingURL=appError.js.map

package/dist/appError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appError.js","names":["code: ErrorCode","details?: Record<string, unknown>"],"sources":["../src/appError.ts"],"sourcesContent":["import { ErrorCode } from './codes';\n\n/**\n * Generic application error with code and optional details.\n */\nexport class AppError extends Error {\n  constructor(\n    public code: ErrorCode,\n    message: string,\n    public details?: Record<string, unknown>\n  ) {\n    super(message);\n    Object.setPrototypeOf(this, new.target.prototype);\n    this.name = 'AppError';\n  }\n}\n\n/** Type guard to detect AppError */\nexport function isAppError(err: unknown): err is AppError {\n  return err instanceof AppError;\n}\n"],"mappings":"AAKA,IAAa,EAAb,cAA8B,KAAM,CAClC,YACE,EACA,EACA,EACA,CACA,MAAM,EAAQ,CAJP,KAAA,KAAA,EAEA,KAAA,QAAA,EAGP,OAAO,eAAe,KAAM,IAAI,OAAO,UAAU,CACjD,KAAK,KAAO,aAKhB,SAAgB,EAAW,EAA+B,CACxD,OAAO,aAAe"}

package/dist/codes.d.ts

@@ -0,0 +1,19 @@
+//#region src/codes.d.ts
+/**
+ * Centralised error codes used across services.
+ * Extend this enum to add more domain-specific codes.
+ */
+declare enum ErrorCode {
+  UNAUTHENTICATED = "UNAUTHENTICATED",
+  FORBIDDEN = "FORBIDDEN",
+  NOT_FOUND = "NOT_FOUND",
+  INVALID_INPUT = "INVALID_INPUT",
+  CONFLICT = "CONFLICT",
+  RATE_LIMITED = "RATE_LIMITED",
+  SERVER_ERROR = "SERVER_ERROR",
+  POLICY_DENIED = "POLICY_DENIED",
+}
+declare function isKnownErrorCode(code: string): code is ErrorCode;
+//#endregion
+export { ErrorCode, isKnownErrorCode };
+//# sourceMappingURL=codes.d.ts.map

package/dist/codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.d.ts","names":[],"sources":["../src/codes.ts"],"sourcesContent":[],"mappings":";;AAIA;AAYA;;aAZY,SAAA;;;;;;;;;;iBAYI,gBAAA,wBAAwC"}

package/dist/codes.js

@@ -0,0 +1,2 @@
+let e=function(e){return e.UNAUTHENTICATED=`UNAUTHENTICATED`,e.FORBIDDEN=`FORBIDDEN`,e.NOT_FOUND=`NOT_FOUND`,e.INVALID_INPUT=`INVALID_INPUT`,e.CONFLICT=`CONFLICT`,e.RATE_LIMITED=`RATE_LIMITED`,e.SERVER_ERROR=`SERVER_ERROR`,e.POLICY_DENIED=`POLICY_DENIED`,e}({});function t(t){return Object.values(e).includes(t)}export{e as ErrorCode,t as isKnownErrorCode};
+//# sourceMappingURL=codes.js.map

package/dist/codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.js","names":[],"sources":["../src/codes.ts"],"sourcesContent":["/**\n * Centralised error codes used across services.\n * Extend this enum to add more domain-specific codes.\n */\nexport enum ErrorCode {\n  UNAUTHENTICATED = 'UNAUTHENTICATED',\n  FORBIDDEN = 'FORBIDDEN',\n  NOT_FOUND = 'NOT_FOUND',\n  INVALID_INPUT = 'INVALID_INPUT',\n  CONFLICT = 'CONFLICT',\n  RATE_LIMITED = 'RATE_LIMITED',\n  SERVER_ERROR = 'SERVER_ERROR',\n  POLICY_DENIED = 'POLICY_DENIED',\n  // add more codes here\n}\n\nexport function isKnownErrorCode(code: string): code is ErrorCode {\n  return Object.values(ErrorCode).includes(code as ErrorCode);\n}\n"],"mappings":"AAIA,IAAY,EAAA,SAAA,EAAL,OACL,GAAA,gBAAA,kBACA,EAAA,UAAA,YACA,EAAA,UAAA,YACA,EAAA,cAAA,gBACA,EAAA,SAAA,WACA,EAAA,aAAA,eACA,EAAA,aAAA,eACA,EAAA,cAAA,uBAIF,SAAgB,EAAiB,EAAiC,CAChE,OAAO,OAAO,OAAO,EAAU,CAAC,SAAS,EAAkB"}

package/dist/http.d.ts

@@ -0,0 +1,11 @@
+import { ErrorCode } from "./codes.js";
+
+//#region src/http.d.ts
+
+/**
+ * Map known error codes to HTTP status codes.
+ */
+declare function httpStatus(code: ErrorCode): number;
+//#endregion
+export { httpStatus };
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","names":[],"sources":["../src/http.ts"],"sourcesContent":[],"mappings":";;;;;;AAMA;iBAAgB,UAAA,OAAiB"}

package/dist/http.js

@@ -0,0 +1,2 @@
+import{ErrorCode as e}from"./codes.js";function t(t){switch(t){case e.UNAUTHENTICATED:return 401;case e.FORBIDDEN:case e.POLICY_DENIED:return 403;case e.NOT_FOUND:return 404;case e.INVALID_INPUT:return 400;case e.CONFLICT:return 409;case e.RATE_LIMITED:return 429;default:return 500}}export{t as httpStatus};
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","names":[],"sources":["../src/http.ts"],"sourcesContent":["import { isAppError } from './appError';\nimport { ErrorCode } from './codes';\n\n/**\n * Map known error codes to HTTP status codes.\n */\nexport function httpStatus(code: ErrorCode): number {\n  switch (code) {\n    case ErrorCode.UNAUTHENTICATED:\n      return 401;\n    case ErrorCode.FORBIDDEN:\n    case ErrorCode.POLICY_DENIED:\n      return 403;\n    case ErrorCode.NOT_FOUND:\n      return 404;\n    case ErrorCode.INVALID_INPUT:\n      return 400;\n    case ErrorCode.CONFLICT:\n      return 409;\n    case ErrorCode.RATE_LIMITED:\n      return 429;\n    default:\n      return 500;\n  }\n}\n\n/**\n * Convert AppError or unknown error into a Problem JSON response body and status code.\n */\n// export function toHttpResponse(err: unknown): { status: number; body: any } {\n//   if (isAppError(err)) {\n//     const status = httpStatus(err.code);\n//     return {\n//       status,\n//       body: {\n//         type: `https://api.chaman.dev/errors/${err.code.toLowerCase()}`,\n//         title: err.message,\n//         detail: err.details ?? null,\n//         status,\n//       },\n//     };\n//   }\n//   // Unknown error: hide internal details\n//   return {\n//     status: 500,\n//     body: {\n//       type: 'https://api.chaman.dev/errors/server_error',\n//       title: 'Unexpected Error',\n//       detail: null,\n//       status: 500,\n//     },\n//   };\n// }\n"],"mappings":"uCAMA,SAAgB,EAAW,EAAyB,CAClD,OAAQ,EAAR,CACE,KAAK,EAAU,gBACb,MAAO,KACT,KAAK,EAAU,UACf,KAAK,EAAU,cACb,MAAO,KACT,KAAK,EAAU,UACb,MAAO,KACT,KAAK,EAAU,cACb,MAAO,KACT,KAAK,EAAU,SACb,MAAO,KACT,KAAK,EAAU,aACb,MAAO,KACT,QACE,MAAO"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { ErrorCode, isKnownErrorCode } from "./codes.js";
+import { AppError, isAppError } from "./appError.js";
+import { httpStatus } from "./http.js";
+export { AppError, ErrorCode, httpStatus, isAppError, isKnownErrorCode };

package/dist/index.js

@@ -0,0 +1 @@
+import{ErrorCode as e,isKnownErrorCode as t}from"./codes.js";import{AppError as n,isAppError as r}from"./appError.js";import{httpStatus as i}from"./http.js";export{n as AppError,e as ErrorCode,i as httpStatus,r as isAppError,t as isKnownErrorCode};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@lssm/lib.error",
+  "version": "0.0.0-canary-20251120170226",
+  "scripts": {
+    "build": "bun build:bundle && bun build:types",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src"
+  },
+  "devDependencies": {
+    "@lssm/tool.typescript": "0.0.0-canary-20251120170226",
+    "tsdown": "^0.15.9",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "elysia": "^1.4.11",
+    "express": "^5.1.0",
+    "next": "15.5.6"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./appError": "./dist/appError.js",
+    "./codes": "./dist/codes.js",
+    "./http": "./dist/http.js",
+    "./*": "./*"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.js",
+      "./appError": "./dist/appError.js",
+      "./codes": "./dist/codes.js",
+      "./http": "./dist/http.js",
+      "./*": "./*"
+    }
+  }
+}