@tahminator/sapling 1.5.16 → 1.5.18

package/dist/src/helper/error.d.ts

@@ -0,0 +1,10 @@
+import { HttpStatus } from "../enum";
+/**
+ * Ensure that you define a middleware that can handle this error.
+ *
+ * @see {@link Sapling.loadResponseStatusErrorMiddleware}
+ */
+export declare class ResponseStatusError extends Error {
+    readonly status: HttpStatus;
+    constructor(status: HttpStatus, message?: string);
+}

package/dist/src/helper/error.js

@@ -0,0 +1,19 @@
+import { HttpStatus } from "../enum";
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { Sapling } from "./sapling";
+/**
+ * Ensure that you define a middleware that can handle this error.
+ *
+ * @see {@link Sapling.loadResponseStatusErrorMiddleware}
+ */
+export class ResponseStatusError extends Error {
+    constructor(status, message) {
+        super(message !== null && message !== void 0 ? message : "Something went wrong.");
+        this.status = status;
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = `HttpError(${HttpStatus[status]})`;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, ResponseStatusError);
+        }
+    }
+}

package/dist/src/helper/importer.d.ts

@@ -0,0 +1 @@
+export declare const getControllers: () => any;

package/dist/src/helper/importer.js

@@ -0,0 +1,6 @@
+// WIP
+// @ts-expect-error glob import
+import * as controllers from "**/*.controller.ts";
+export const getControllers = () => {
+    return controllers;
+};

package/dist/src/helper/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./redirect";
+export * from "./response";
+export * from "./error";
+export * from "./sapling";

package/dist/src/helper/index.js

@@ -0,0 +1,4 @@
+export * from "./redirect";
+export * from "./response";
+export * from "./error";
+export * from "./sapling";

package/dist/src/helper/redirect.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Generic HTTP redirect wrapped modeled after Spring's `RedirectView`.
+ *
+ * You can either return `new RedirectView(url)` or `RedirectView.redirect(url)` inside of a controller method.
+ */
+export declare class RedirectView {
+    _url: string;
+    constructor(url: string);
+    getUrl(): string;
+    /**
+     * Instantiate `RedirectView` with the given `url`.
+     */
+    static redirect(url: string): RedirectView;
+}

package/dist/src/helper/redirect.js

@@ -0,0 +1,19 @@
+/**
+ * Generic HTTP redirect wrapped modeled after Spring's `RedirectView`.
+ *
+ * You can either return `new RedirectView(url)` or `RedirectView.redirect(url)` inside of a controller method.
+ */
+export class RedirectView {
+    constructor(url) {
+        this._url = url;
+    }
+    getUrl() {
+        return this._url;
+    }
+    /**
+     * Instantiate `RedirectView` with the given `url`.
+     */
+    static redirect(url) {
+        return new RedirectView(url);
+    }
+}

package/dist/src/helper/response.d.ts

@@ -0,0 +1,68 @@
+import type { HttpHeaders } from "../types";
+/**
+ * Generic HTTP response wrapper modeled after Spring's `ResponseEntity`.
+ *
+ * Provides status code, headers, and an optional typed body.
+ * The body is serialized through `Sapling.serialize`.
+ *
+ * @typeParam T - the type of the response body
+ */
+export declare class ResponseEntity<T> {
+    private readonly _statusCode;
+    private readonly _headers;
+    private readonly _body;
+    constructor(body: T, headers?: HttpHeaders, statusCode?: number);
+    /**
+     * Create a builder with a 200 status code.
+     *
+     * @example```ts
+     * return ResponseEntity.ok().body({ success: true });
+     * ```
+     */
+    static ok(): ResponseEntityBuilder;
+    /**
+     * Create a builder with a custom status code.
+     *
+     * @example```ts
+     * return ResponseEntity.status(HttpStatus.BAD_REQUEST).body({ success: false });
+     * ```
+     *
+     * @see {@link HttpStatus}
+     */
+    static status(statusCode: number): ResponseEntityBuilder;
+    /**
+     * Return status code.
+     */
+    getStatusCode(): number;
+    /**
+     * Return headers.
+     */
+    getHeaders(): HttpHeaders;
+    /**
+     * Return the response body.
+     */
+    getBody(): T;
+}
+/**
+ * Builder for {@link ResponseEntity}.
+ *
+ * Forces the status code to be set first, then headers and body,
+ * ensuring type safety when constructing the response.
+ */
+export declare class ResponseEntityBuilder {
+    private readonly _statusCode;
+    private _headers;
+    constructor(statusCode: number);
+    /**
+     * Set all headers as an object with keys and values.
+     */
+    headers(headers: HttpHeaders): this;
+    /**
+     * Add/override a single key and value to the headers.
+     */
+    setHeader(key: string, value: string): this;
+    /**
+     * Set the response body.
+     */
+    body<T>(body: T): ResponseEntity<T>;
+}

package/dist/src/helper/response.js

@@ -0,0 +1,90 @@
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { HttpStatus } from "../enum";
+/**
+ * Generic HTTP response wrapper modeled after Spring's `ResponseEntity`.
+ *
+ * Provides status code, headers, and an optional typed body.
+ * The body is serialized through `Sapling.serialize`.
+ *
+ * @typeParam T - the type of the response body
+ */
+export class ResponseEntity {
+    constructor(body, headers = {}, statusCode = 200) {
+        this._headers = {};
+        this._body = body;
+        this._headers = headers;
+        this._statusCode = statusCode;
+    }
+    /**
+     * Create a builder with a 200 status code.
+     *
+     * @example```ts
+     * return ResponseEntity.ok().body({ success: true });
+     * ```
+     */
+    static ok() {
+        return new ResponseEntityBuilder(200);
+    }
+    /**
+     * Create a builder with a custom status code.
+     *
+     * @example```ts
+     * return ResponseEntity.status(HttpStatus.BAD_REQUEST).body({ success: false });
+     * ```
+     *
+     * @see {@link HttpStatus}
+     */
+    static status(statusCode) {
+        return new ResponseEntityBuilder(statusCode);
+    }
+    /**
+     * Return status code.
+     */
+    getStatusCode() {
+        return this._statusCode;
+    }
+    /**
+     * Return headers.
+     */
+    getHeaders() {
+        return this._headers;
+    }
+    /**
+     * Return the response body.
+     */
+    getBody() {
+        return this._body;
+    }
+}
+/**
+ * Builder for {@link ResponseEntity}.
+ *
+ * Forces the status code to be set first, then headers and body,
+ * ensuring type safety when constructing the response.
+ */
+export class ResponseEntityBuilder {
+    constructor(statusCode) {
+        this._headers = {};
+        this._statusCode = statusCode;
+    }
+    /**
+     * Set all headers as an object with keys and values.
+     */
+    headers(headers) {
+        this._headers = headers;
+        return this;
+    }
+    /**
+     * Add/override a single key and value to the headers.
+     */
+    setHeader(key, value) {
+        this._headers[key] = value;
+        return this;
+    }
+    /**
+     * Set the response body.
+     */
+    body(body) {
+        return new ResponseEntity(body, this._headers, this._statusCode);
+    }
+}

package/dist/src/helper/sapling.d.ts

@@ -0,0 +1,101 @@
+import type { Router } from "express";
+import e from "express";
+import type { Class, ExpressMiddlewareFn } from "../types";
+import { ResponseStatusError } from "./error";
+/**
+ * Collection of utility functions which are essential for Sapling to function.
+ */
+export declare class Sapling {
+    /**
+     * If you would prefer to manually resolve your controllers instead, call resolve
+     * on the controller class.
+     *
+     * @example```ts
+     * import { Sapling } from "@tahminator/sapling";
+     * import TestController from "./path/to/test.controller";
+     *
+     * const app = express();
+     *
+     * const router = Sapling.resolve(TestController);
+     * app.use(router);
+     * ```
+     */
+    static resolve<TClass>(this: void, clazz: Class<TClass>): Router;
+    /**
+     * Register this function as a middleware in order to utilize Sapling's `deserialize` function.
+     *
+     * @example```ts
+     * import { Sapling } from "@tahminator/sapling";
+     * import express from "express";
+     *
+     * const app = express();
+     *
+     * app.use(Sapling.json());
+     * ```
+     */
+    static json(this: void): ExpressMiddlewareFn;
+    /**
+     * Register your application with all the necessary middlewares and logics for Sapling to function.
+     *
+     * @example```ts
+     * import { Sapling } from "@tahminator/sapling";
+     * import express from "express";
+     *
+     * const app = express();
+     *
+     * app.registerApp(app);
+     * ```
+     */
+    static registerApp(app: e.Express): void;
+    /**
+     * Register a middleware that will handle {@link ResponseStatusError}.
+     *
+     * This middleware will chain to the next middleware if it does not catch {@link ResponseStatusError}.
+     * You may still define middleware to handle all other errors in a separate `app.use` call.
+     *
+     * @example
+     * ```ts
+     * import express from "express";
+     * import { Sapling } from "@tahminator/sapling";
+     *
+     * const app = express();
+     *
+     * Sapling.loadResponseStatusErrorMiddleware(app, (err, req, res, next) => {
+     *   // `err` is guaranteed to be of type ResponseStatusError
+     *   res.status(err.status).json({
+     *     success: false,
+     *     message: err.message,
+     *   });
+     * });
+     * ```
+     */
+    static loadResponseStatusErrorMiddleware(this: void, app: e.Express, fn: (err: ResponseStatusError, request: e.Request, response: e.Response, next: e.NextFunction) => void): void;
+    /**
+     * Serialize a value into a JSON string.
+     *
+     * This function is used in {@link ResponseEntity} to serialize the `body`.
+     *
+     * Use `setSerializeFn` to override underlying implementation.
+     *
+     * @defaultValue `JSON.stringify`
+     */
+    static serialize(this: void, value: any): string;
+    /**
+     * Replace the function used for `serialize`.
+     */
+    static setSerializeFn(this: void, fn: (value: any) => string): void;
+    /**
+     * De-serialize a JSON string back to a JavaScript object.
+     *
+     * This function is used to de-serialize a string into a `body`.
+     *
+     * Use `setDeserializeFn` to override underlying implementation.
+     *
+     * @defaultValue `JSON.parse`
+     */
+    static deserialize<T = any>(this: void, value: string): T;
+    /**
+     * Replace the function used for `deserialize`
+     */
+    static setDeserializeFn(this: void, fn: (value: string) => any): void;
+}

package/dist/src/helper/sapling.js

@@ -0,0 +1,153 @@
+import e from "express";
+import { _ControllerRegistry } from "../annotation/controller";
+import { ResponseStatusError } from "./error";
+const settings = {
+    serialize: JSON.stringify,
+    deserialize: JSON.parse,
+};
+/**
+ * Collection of utility functions which are essential for Sapling to function.
+ */
+export class Sapling {
+    /**
+     * If you would prefer to manually resolve your controllers instead, call resolve
+     * on the controller class.
+     *
+     * @example```ts
+     * import { Sapling } from "@tahminator/sapling";
+     * import TestController from "./path/to/test.controller";
+     *
+     * const app = express();
+     *
+     * const router = Sapling.resolve(TestController);
+     * app.use(router);
+     * ```
+     */
+    static resolve(clazz) {
+        const router = _ControllerRegistry.get(clazz);
+        if (!router) {
+            throw new Error("Controller cannot be found");
+        }
+        return router;
+    }
+    /**
+     * Register this function as a middleware in order to utilize Sapling's `deserialize` function.
+     *
+     * @example```ts
+     * import { Sapling } from "@tahminator/sapling";
+     * import express from "express";
+     *
+     * const app = express();
+     *
+     * app.use(Sapling.json());
+     * ```
+     */
+    static json() {
+        return (request, _response, next) => {
+            try {
+                if (!request.body) {
+                    return next();
+                }
+                if (request.headers["content-type"] !== "application/json") {
+                    return next();
+                }
+                if (typeof request.body === "string") {
+                    request.body = Sapling.deserialize(request.body);
+                }
+                else if (typeof request.body === "object") {
+                    // override `express.json()` middleware, if ran, and use Sapling's `deserialize` instead.
+                    const raw = JSON.stringify(request.body);
+                    request.body = Sapling.deserialize(raw);
+                }
+                next();
+            }
+            catch (err) {
+                next(err);
+            }
+        };
+    }
+    /**
+     * Register your application with all the necessary middlewares and logics for Sapling to function.
+     *
+     * @example```ts
+     * import { Sapling } from "@tahminator/sapling";
+     * import express from "express";
+     *
+     * const app = express();
+     *
+     * app.registerApp(app);
+     * ```
+     */
+    static registerApp(app) {
+        app.use(e.text({ type: "application/json" }));
+        app.use(Sapling.json());
+    }
+    /**
+     * Register a middleware that will handle {@link ResponseStatusError}.
+     *
+     * This middleware will chain to the next middleware if it does not catch {@link ResponseStatusError}.
+     * You may still define middleware to handle all other errors in a separate `app.use` call.
+     *
+     * @example
+     * ```ts
+     * import express from "express";
+     * import { Sapling } from "@tahminator/sapling";
+     *
+     * const app = express();
+     *
+     * Sapling.loadResponseStatusErrorMiddleware(app, (err, req, res, next) => {
+     *   // `err` is guaranteed to be of type ResponseStatusError
+     *   res.status(err.status).json({
+     *     success: false,
+     *     message: err.message,
+     *   });
+     * });
+     * ```
+     */
+    static loadResponseStatusErrorMiddleware(app, fn) {
+        app.use(((err, req, res, next) => {
+            if (err instanceof ResponseStatusError) {
+                fn(err, req, res, next);
+            }
+            else {
+                next(err);
+            }
+        }));
+    }
+    /**
+     * Serialize a value into a JSON string.
+     *
+     * This function is used in {@link ResponseEntity} to serialize the `body`.
+     *
+     * Use `setSerializeFn` to override underlying implementation.
+     *
+     * @defaultValue `JSON.stringify`
+     */
+    static serialize(value) {
+        return settings.serialize(value);
+    }
+    /**
+     * Replace the function used for `serialize`.
+     */
+    static setSerializeFn(fn) {
+        settings.serialize = fn;
+    }
+    /**
+     * De-serialize a JSON string back to a JavaScript object.
+     *
+     * This function is used to de-serialize a string into a `body`.
+     *
+     * Use `setDeserializeFn` to override underlying implementation.
+     *
+     * @defaultValue `JSON.parse`
+     */
+    static deserialize(value) {
+        return settings.deserialize(value);
+    }
+    /**
+     * Replace the function used for `deserialize`
+     */
+    static setDeserializeFn(fn) {
+        settings.deserialize = fn;
+    }
+}

package/dist/src/html/404.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Default Express.js 404 error page, as a string.
+ */
+export declare const Html404ErrorPage: (error: string) => string;

package/dist/src/html/404.js

@@ -0,0 +1,15 @@
+/**
+ * Default Express.js 404 error page, as a string.
+ */
+export const Html404ErrorPage = (error) => `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Error</title>
+</head>
+<body>
+<pre>${error}</pre>
+</body>
+</html>
+`;

package/dist/src/html/index.d.ts

@@ -0,0 +1 @@
+export * from "./404";

package/dist/src/html/index.js

@@ -0,0 +1 @@
+export * from "./404";

package/dist/src/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./html";
+export * from "./annotation";
+export * from "./helper";
+export * from "./enum";
+export * from "./types";

package/dist/src/index.js

@@ -0,0 +1,5 @@
+export * from "./html";
+export * from "./annotation";
+export * from "./helper";
+export * from "./enum";
+export * from "./types";

package/dist/src/types.d.ts

@@ -0,0 +1,21 @@
+import type { NextFunction, Request, Response } from "express";
+export type ExpressRouterMethodKey = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS" | "HEAD" | "USE";
+export type ExpressRouterMethods = Lowercase<ExpressRouterMethodKey>;
+export declare const methodResolve: Record<ExpressRouterMethodKey, ExpressRouterMethods>;
+export type RouteDefinition = {
+    /**
+     * Express.js HTTP method.
+     */
+    method: ExpressRouterMethodKey;
+    /**
+     * The path to define the route on. Can be a string or RegExp.
+     */
+    path: string | RegExp;
+    /**
+     * The name of the function the `@Route` annotation was applied on.
+     */
+    fnName: string;
+};
+export type Class<T> = new (...args: any[]) => T;
+export type HttpHeaders = Record<string, string>;
+export type ExpressMiddlewareFn = ($1: Request, $2: Response, $3: NextFunction) => void;

package/dist/src/types.js

@@ -0,0 +1,11 @@
+// all exported types
+export const methodResolve = {
+    GET: "get",
+    PUT: "put",
+    POST: "post",
+    DELETE: "delete",
+    OPTIONS: "options",
+    PATCH: "patch",
+    HEAD: "head",
+    USE: "use",
+};

package/dist/vite.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vite").UserConfig;
+export default _default;

package/dist/vite.config.js

@@ -0,0 +1,17 @@
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference
+/// <reference types="vitest/config" />
+import tsconfigPaths from "vite-tsconfig-paths";
+import { defineConfig } from "vitest/config";
+// https://vite.dev/config/
+export default defineConfig({
+    plugins: [tsconfigPaths()],
+    test: {
+        globals: true,
+        environment: "jsdom",
+        coverage: {
+            enabled: true,
+            provider: "istanbul",
+            reporter: ["lcov"],
+        },
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tahminator/sapling",
-  "version": "1.5.16",
+  "version": "1.5.18",
   "author": "Tahmid Ahmed",
   "description": "A library to help you write cleaner Express.js code",
   "repository": {
@@ -18,7 +18,7 @@
     "prettier": "NODE_OPTIONS=\"--experimental-strip-types\" prettier --check .",
     "prettier:fix": "NODE_OPTIONS=\"--experimental-strip-types\" prettier --write .",
     "typecheck": "tsc -b --noEmit",
-    "build": "rm -rf dist && tsc"
+    "build": "rm -rf dist && tsc --project tsconfig.app.json"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",