oliang 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thefordz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# oliang
+
+Tiny error-handling core for Express + TypeScript apps ☕
+
+> Looking to start a new project? Use the scaffolder instead:
+>
+> ```bash
+> npm create oliang
+> ```
+
+## Install
+
+```bash
+npm install oliang
+```
+
+## Usage
+
+```ts
+import express from "express";
+import { errorHandler, NotFoundException, HTTPSTATUS } from "oliang";
+
+const app = express();
+
+app.get("/health", (_req, res) => {
+  res.status(HTTPSTATUS.OK).json({ status: "ok" });
+});
+
+app.get("/users/:id", (req, _res) => {
+  throw new NotFoundException(`User ${req.params.id} not found`);
+});
+
+app.use(errorHandler);
+```
+
+## Exports
+
+- `AppError` — base error class carrying `statusCode` and `errorCode`
+- `InternalServerException`, `NotFoundException`, `BadRequestException`, `UnauthorizedException` — ready-made subclasses
+- `ErrorCodes` / `ErrorCodeType` — error code constants
+- `errorHandler` — Express error middleware that maps `AppError` to JSON responses
+- `HTTPSTATUS` / `HttpStatusCodeType` — HTTP status constants
+- `getEnv` — env reader that throws at startup when a required variable is missing

package/dist/app-error.d.ts

@@ -0,0 +1,27 @@
+import { HttpStatusCodeType } from "./http-status.js";
+export declare const ErrorCodes: {
+    readonly ERROR_INTERNAL: "ERROR_INTERNAL";
+    readonly ERROR_BAD_REQUEST: "ERROR_BAD_REQUEST";
+    readonly ERROR_UNAUTHORIZED: "ERROR_UNAUTHORIZED";
+    readonly ERROR_FORBIDDEN: "ERROR_FORBIDDEN";
+    readonly ERROR_NOT_FOUND: "ERROR_NOT_FOUND";
+    readonly ERROR_VALIDATION_ERROR: "ERROR_VALIDATION_ERROR";
+};
+export type ErrorCodeType = keyof typeof ErrorCodes;
+export declare class AppError extends Error {
+    statusCode: HttpStatusCodeType;
+    errorCode: ErrorCodeType;
+    constructor(message: string, statusCode?: HttpStatusCodeType, errorCode?: ErrorCodeType);
+}
+export declare class InternalServerException extends AppError {
+    constructor(message?: string);
+}
+export declare class NotFoundException extends AppError {
+    constructor(message?: string);
+}
+export declare class BadRequestException extends AppError {
+    constructor(message?: string);
+}
+export declare class UnauthorizedException extends AppError {
+    constructor(message?: string);
+}

package/dist/app-error.js

@@ -0,0 +1,39 @@
+import { HTTPSTATUS } from "./http-status.js";
+export const ErrorCodes = {
+    ERROR_INTERNAL: "ERROR_INTERNAL",
+    ERROR_BAD_REQUEST: "ERROR_BAD_REQUEST",
+    ERROR_UNAUTHORIZED: "ERROR_UNAUTHORIZED",
+    ERROR_FORBIDDEN: "ERROR_FORBIDDEN",
+    ERROR_NOT_FOUND: "ERROR_NOT_FOUND",
+    ERROR_VALIDATION_ERROR: "ERROR_VALIDATION_ERROR",
+};
+export class AppError extends Error {
+    statusCode;
+    errorCode;
+    constructor(message, statusCode = HTTPSTATUS.INTERNAL_SERVER_ERROR, errorCode = ErrorCodes.ERROR_INTERNAL) {
+        super(message);
+        this.statusCode = statusCode;
+        this.errorCode = errorCode;
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+export class InternalServerException extends AppError {
+    constructor(message = "Internal Server Error") {
+        super(message, HTTPSTATUS.INTERNAL_SERVER_ERROR, ErrorCodes.ERROR_INTERNAL);
+    }
+}
+export class NotFoundException extends AppError {
+    constructor(message = "Resource Not Found") {
+        super(message, HTTPSTATUS.NOT_FOUND, ErrorCodes.ERROR_NOT_FOUND);
+    }
+}
+export class BadRequestException extends AppError {
+    constructor(message = "Bad Request") {
+        super(message, HTTPSTATUS.BAD_REQUEST, ErrorCodes.ERROR_BAD_REQUEST);
+    }
+}
+export class UnauthorizedException extends AppError {
+    constructor(message = "Unauthorized Access") {
+        super(message, HTTPSTATUS.UNAUTHORIZED, ErrorCodes.ERROR_UNAUTHORIZED);
+    }
+}

package/dist/error-handler.d.ts

@@ -0,0 +1,2 @@
+import { ErrorRequestHandler } from "express";
+export declare const errorHandler: ErrorRequestHandler;

package/dist/error-handler.js

@@ -0,0 +1,20 @@
+import { HTTPSTATUS } from "./http-status.js";
+import { AppError } from "./app-error.js";
+export const errorHandler = (error, req, res, next) => {
+    console.log(`Error occured: ${req.path} ${error}`);
+    if (error instanceof SyntaxError) {
+        return res.status(HTTPSTATUS.BAD_REQUEST).json({
+            message: "Invalid JSON format. Please check your request body.",
+        });
+    }
+    if (error instanceof AppError) {
+        return res.status(error.statusCode).json({
+            message: error.message,
+            errorCode: error.errorCode,
+        });
+    }
+    return res.status(HTTPSTATUS.INTERNAL_SERVER_ERROR).json({
+        message: "Internal Server Error",
+        error: error?.message || "Something went wrong",
+    });
+};

package/dist/get-env.d.ts

@@ -0,0 +1 @@
+export declare const getEnv: (key: string, defaultValue?: string) => string;

package/dist/get-env.js

@@ -0,0 +1,6 @@
+export const getEnv = (key, defaultValue = "") => {
+    const value = process.env[key] ?? defaultValue;
+    if (!value)
+        throw new Error(`Missing env variable:${key}`);
+    return value;
+};

package/dist/http-status.d.ts

@@ -0,0 +1,10 @@
+export declare const HTTPSTATUS: {
+    readonly OK: 200;
+    readonly CREATED: 201;
+    readonly BAD_REQUEST: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly FORBIDDEN: 403;
+    readonly NOT_FOUND: 404;
+    readonly INTERNAL_SERVER_ERROR: 500;
+};
+export type HttpStatusCodeType = (typeof HTTPSTATUS)[keyof typeof HTTPSTATUS];

package/dist/http-status.js

@@ -0,0 +1,9 @@
+export const HTTPSTATUS = {
+    OK: 200,
+    CREATED: 201,
+    BAD_REQUEST: 400,
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    NOT_FOUND: 404,
+    INTERNAL_SERVER_ERROR: 500,
+};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { HTTPSTATUS, type HttpStatusCodeType } from "./http-status.js";
+export { AppError, BadRequestException, ErrorCodes, InternalServerException, NotFoundException, UnauthorizedException, type ErrorCodeType, } from "./app-error.js";
+export { errorHandler } from "./error-handler.js";
+export { getEnv } from "./get-env.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { HTTPSTATUS } from "./http-status.js";
+export { AppError, BadRequestException, ErrorCodes, InternalServerException, NotFoundException, UnauthorizedException, } from "./app-error.js";
+export { errorHandler } from "./error-handler.js";
+export { getEnv } from "./get-env.js";

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "oliang",
+  "version": "0.1.0",
+  "description": "Tiny error-handling core for Express + TypeScript apps. Scaffold a full app with `npm create oliang` ☕",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "express",
+    "typescript",
+    "error-handling",
+    "oliang"
+  ],
+  "author": "thefordz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thefordz/oliang.git",
+    "directory": "packages/oliang"
+  },
+  "peerDependencies": {
+    "express": ">=4"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "typescript": "^5.9.2"
+  }
+}