@fishka/express 0.9.5

package/dist/esm/http.types.js

@@ -0,0 +1,35 @@
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+export const INTERNAL_ERROR_STATUS = 500;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+export const BAD_REQUEST_STATUS = 400;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+export const UNAUTHORIZED_STATUS = 401;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+export const FORBIDDEN_STATUS = 403;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+export const NOT_FOUND_STATUS = 404;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+export const OK_STATUS = 200;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+export const TOO_MANY_REQUESTS_STATUS = 429;

package/dist/esm/index.js

@@ -0,0 +1,15 @@
+export * from './api.types';
+export * from './auth/auth-strategy';
+export * from './auth/auth.types';
+export * from './auth/auth.utils';
+export * from './auth/bearer-auth-strategy';
+export * from './config';
+export * from './error-handling';
+export * from './http.types';
+export * from './rate-limit/in-memory-rate-limiter';
+export * from './rate-limit/rate-limit.types';
+export * from './route-table';
+export * from './router';
+export * from './thread-local/thread-local-storage';
+export * from './thread-local/thread-local-storage-middleware';
+export * from './utils/express.utils';

package/dist/esm/rate-limit/in-memory-rate-limiter.js

@@ -0,0 +1,88 @@
+import { addRateLimitHeaders, msToSeconds } from './rate-limit';
+const MILLIS_PER_SECOND = 1000;
+/**
+ * In-memory rate limiter using sliding window counter.
+ * Tracks request counts per key with time-based window expiration.
+ */
+class InMemoryRateLimiter {
+    constructor(points, durationSeconds) {
+        this.limits = new Map();
+        this.points = points;
+        this.durationMs = durationSeconds * MILLIS_PER_SECOND;
+    }
+    /**
+     * Try to consume points from the rate limit.
+     * Returns result if successful, throws if limit exceeded.
+     *
+     * @param key - Unique identifier for the client (e.g., IP address)
+     * @returns Rate limit result with remaining points and ms until reset
+     * @throws RateLimitResult if limit exceeded
+     */
+    consume(key) {
+        const now = Date.now();
+        const existing = this.limits.get(key);
+        // Reset expired entry
+        if (existing && now >= existing.resetTime) {
+            this.limits.delete(key);
+        }
+        const current = this.limits.get(key) || { count: 0, resetTime: now + this.durationMs };
+        if (current.count >= this.points) {
+            const msBeforeNext = Math.max(0, current.resetTime - now);
+            throw {
+                remainingPoints: 0,
+                msBeforeNext,
+            };
+        }
+        current.count++;
+        this.limits.set(key, current);
+        const msBeforeNext = Math.max(0, current.resetTime - now);
+        return {
+            remainingPoints: this.points - current.count,
+            msBeforeNext,
+        };
+    }
+}
+/**
+ * Creates a rate limiter middleware using in-memory implementation.
+ *
+ * Separate limiters are used for read (GET) and write (POST/PATCH/PUT/DELETE) requests.
+ *
+ * @param config - Rate limit configuration
+ * @returns Express middleware function
+ */
+export async function createRateLimiterMiddleware(config) {
+    const readLimiter = new InMemoryRateLimiter(config.points.read, config.duration);
+    const writeLimiter = new InMemoryRateLimiter(config.points.write, config.duration);
+    const whitelist = config.rateLimitWhitelist || ['/v1', '/health'];
+    /**
+     * The actual middleware function.
+     */
+    return async (req, res, next) => {
+        // Check if the path is whitelisted
+        if (whitelist.some(path => req.path.includes(path))) {
+            next();
+            return;
+        }
+        const isReadRequest = req.method === 'GET';
+        const limiter = isReadRequest ? readLimiter : writeLimiter;
+        const limitPoints = isReadRequest ? config.points.read : config.points.write;
+        const clientKey = req.ip || 'unknown';
+        try {
+            const result = limiter.consume(clientKey);
+            addRateLimitHeaders(res, result, limitPoints, config.duration);
+            next();
+        }
+        catch (error) {
+            const result = error;
+            addRateLimitHeaders(res, result, limitPoints, config.duration)
+                .header('Retry-After', `${msToSeconds(result.msBeforeNext)}`)
+                .status(429)
+                .send({ error: 'Too Many Requests' });
+        }
+    };
+}
+/**
+ * Export the in-memory limiter class for advanced use cases where
+ * you might want direct control over rate limit management.
+ */
+export { InMemoryRateLimiter };

package/dist/esm/rate-limit/rate-limit.js

@@ -0,0 +1,30 @@
+const MILLIS_PER_SECOND = 1000;
+/**
+ * Adds rate limit state headers to the response.
+ * See https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/
+ *
+ * Headers added:
+ * - X-RateLimit-Limit: Server's quota for requests in the time window
+ * - X-RateLimit-Remaining: Remaining quota in the current window
+ * - X-RateLimit-Reset: Time remaining in the current window (in seconds)
+ * - X-RateLimit-Policy: Quota policies associated with the client
+ * @Internal
+ */
+export function addRateLimitHeaders(res, result, limitPoints, duration) {
+    return (res
+        // The server's quota for requests by the client in the time window.
+        .header('X-RateLimit-Limit', `${limitPoints}`)
+        // The remaining quota in the current window.
+        .header('X-RateLimit-Remaining', `${result.remainingPoints}`)
+        // The time remaining in the current window specified in seconds.
+        .header('X-RateLimit-Reset', `${Math.ceil(result.msBeforeNext / MILLIS_PER_SECOND)}`)
+        // Indicates the quota policies currently associated with the client.
+        .header('X-RateLimit-Policy', `${limitPoints};w=${duration};comment="fixed window"`));
+}
+/**
+ * Converts milliseconds to seconds, rounding up.
+ * @Internal
+ */
+export function msToSeconds(ms) {
+    return Math.ceil(ms / MILLIS_PER_SECOND);
+}

package/dist/esm/rate-limit/rate-limit.types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/route-table.js

@@ -0,0 +1,40 @@
+import { mountDelete, mountGet, mountPatch, mountPost, mountPut, } from './router';
+/**
+ * Helper utility for organizing and mounting routes.
+ * Provides a fluent interface for registering multiple handlers.
+ */
+export class RouteTable {
+    constructor(app) {
+        this.app = app;
+    }
+    get(path, endpointOrRun) {
+        const endpoint = typeof endpointOrRun === 'function' ? { run: endpointOrRun } : endpointOrRun;
+        mountGet(this.app, path, endpoint);
+        return this;
+    }
+    post(path, endpoint) {
+        mountPost(this.app, path, endpoint);
+        return this;
+    }
+    patch(path, endpoint) {
+        mountPatch(this.app, path, endpoint);
+        return this;
+    }
+    put(path, endpoint) {
+        mountPut(this.app, path, endpoint);
+        return this;
+    }
+    delete(path, endpointOrRun) {
+        const endpoint = typeof endpointOrRun === 'function' ? { run: endpointOrRun } : endpointOrRun;
+        mountDelete(this.app, path, endpoint);
+        return this;
+    }
+}
+/**
+ * Factory function to create a new route table.
+ * @param app Express application instance
+ * @returns RouteTable instance with fluent API
+ */
+export function createRouteTable(app) {
+    return new RouteTable(app);
+}

package/dist/esm/router.js

@@ -0,0 +1,203 @@
+import { assertTruthy, callValueAssertion, getMessageFromError, validateObject, } from '@fishka/assertions';
+import * as url from 'url';
+import { HttpError, URL_PARAMETER_INFO } from './api.types';
+import { BAD_REQUEST_STATUS, OK_STATUS } from './http.types';
+import { catchRouteErrors } from './error-handling';
+import { getRequestLocalStorage } from './thread-local/thread-local-storage';
+import { wrapAsApiResponse } from './utils/conversion.utils';
+// ============================================================================
+// Internal implementation details
+// ============================================================================
+/**
+ * Registers a GET route.
+ */
+export const mountGet = (app, path, endpoint) => mount(app, { method: 'get', route: endpoint, path });
+/**
+ * Registers a POST route.
+ */
+export const mountPost = (app, path, endpoint) => mount(app, { method: 'post', route: endpoint, path });
+/**
+ * Registers a PATCH route.
+ */
+export const mountPatch = (app, path, endpoint) => mount(app, { method: 'patch', route: endpoint, path });
+/**
+ * Registers a PUT route.
+ */
+export const mountPut = (app, path, endpoint) => mount(app, { method: 'put', route: endpoint, path });
+/**
+ * Registers a DELETE route.
+ */
+export const mountDelete = (app, path, endpoint) => mount(app, { method: 'delete', route: endpoint, path });
+/**
+ * Mounts a route with the given method, endpoint, and path.
+ */
+export function mount(app, { method, route, path }) {
+    const fullPath = `/${path}`;
+    const handler = createRouteHandler(method, route);
+    app[method](fullPath, catchRouteErrors(handler));
+}
+/**
+ * @Internal
+ * Creates a route handler from an endpoint definition.
+ */
+function createRouteHandler(method, endpoint) {
+    return async (req, res, _next) => {
+        let result;
+        switch (method) {
+            case 'post':
+            case 'put':
+            case 'patch':
+                result = await executeBodyEndpoint(endpoint, req, res);
+                break;
+            case 'delete':
+                result = await executeDeleteEndpoint(endpoint, req, res);
+                break;
+            case 'get':
+                result = await executeGetEndpoint(endpoint, req, res);
+                break;
+        }
+        const response = wrapAsApiResponse(result);
+        const tls = getRequestLocalStorage();
+        if (tls?.requestId) {
+            response.requestId = tls.requestId;
+        }
+        response.status = response.status || OK_STATUS;
+        res.status(response.status);
+        res.send(response);
+    };
+}
+/**
+ * @Internal
+ * Validates request parameters using custom validators.
+ */
+function validateUrlParameters(req, { $path, $query, }) {
+    try {
+        for (const key in req.params) {
+            const value = req.params[key];
+            // Run Global Validation if registered.
+            const globalValidator = URL_PARAMETER_INFO[key]?.validator;
+            if (globalValidator) {
+                callValueAssertion(value, globalValidator, `${BAD_REQUEST_STATUS}`);
+            }
+            // Run Local Validation.
+            const validator = $path?.[key];
+            if (validator) {
+                callValueAssertion(value, validator, `${BAD_REQUEST_STATUS}`);
+            }
+        }
+        const parsedUrl = url.parse(req.url, true);
+        for (const key in parsedUrl.query) {
+            const value = parsedUrl.query[key];
+            //  Global Validation if registered (also applies to query params if names match).
+            const globalValidator = URL_PARAMETER_INFO[key]?.validator;
+            if (globalValidator) {
+                // Query params can be string | string[] | undefined. Global validators usually expect string.
+                // We only validate if it's a single value or handle array in validator.
+                // For simplicity, we pass value as is (unknown) to assertion.
+                callValueAssertion(value, globalValidator, `${BAD_REQUEST_STATUS}`);
+            }
+            const validator = $query?.[key];
+            if (validator) {
+                callValueAssertion(value, validator, `${BAD_REQUEST_STATUS}`);
+            }
+        }
+    }
+    catch (error) {
+        throw new HttpError(BAD_REQUEST_STATUS, getMessageFromError(error));
+    }
+}
+/**
+ * @Internal
+ * Runs GET handler with optional middleware.
+ */
+async function executeGetEndpoint(route, req, res) {
+    const requestContext = newRequestContext(undefined, req, res);
+    validateUrlParameters(req, { $path: route.$path, $query: route.$query });
+    return await executeWithMiddleware(() => route.run(requestContext), route.middlewares || [], requestContext);
+}
+/**
+ * @Internal
+ * Runs DELETE handler with optional middleware.
+ */
+async function executeDeleteEndpoint(route, req, res) {
+    const requestContext = newRequestContext(undefined, req, res);
+    validateUrlParameters(req, { $path: route.$path, $query: route.$query });
+    await executeWithMiddleware(() => route.run(requestContext), route.middlewares || [], requestContext);
+    return undefined;
+}
+/**
+ * @Internal
+ * Runs POST/PUT/PATCH handler with optional middleware.
+ */
+async function executeBodyEndpoint(route, req, res) {
+    const validator = route.$body;
+    const apiRequest = req.body;
+    try {
+        // Handle validation based on whether validator is an object or function
+        if (typeof validator === 'function') {
+            // It's a ValueAssertion (function)
+            callValueAssertion(apiRequest, validator, `${BAD_REQUEST_STATUS}: request body`);
+        }
+        else {
+            // It's an ObjectAssertion - use validateObject
+            // We strictly assume it is an object because of the type definition (function | object)
+            const objectValidator = validator;
+            const isEmptyValidator = Object.keys(objectValidator).length === 0;
+            const error = validateObject(apiRequest, objectValidator, `${BAD_REQUEST_STATUS}: request body`, {
+                failOnUnknownFields: !isEmptyValidator,
+            });
+            assertTruthy(!error, error);
+        }
+    }
+    catch (error) {
+        if (error instanceof HttpError)
+            throw error;
+        throw new HttpError(BAD_REQUEST_STATUS, getMessageFromError(error));
+    }
+    const requestContext = newRequestContext(apiRequest, req, res);
+    validateUrlParameters(req, { $path: route.$path, $query: route.$query });
+    requestContext.body = req.body;
+    return await executeWithMiddleware(() => route.run(requestContext), (route.middlewares || []), requestContext);
+}
+/**
+ * @Internal
+ * Executes handler with middleware chain.
+ */
+async function executeWithMiddleware(run, middlewares, context) {
+    const current = async (index) => {
+        if (index >= middlewares.length) {
+            const result = await run();
+            return wrapAsApiResponse(result);
+        }
+        const middleware = middlewares[index];
+        return (await middleware(() => current(index + 1), context));
+    };
+    return await current(0);
+}
+/**
+ * @Internal
+ * Creates a new RequestContext instance.
+ */
+function newRequestContext(requestBody, req, res) {
+    return {
+        body: requestBody,
+        req,
+        res,
+        params: {
+            get: (key) => {
+                const value = req.params[key];
+                assertTruthy(value, `Path parameter '${key}' not found`);
+                return value;
+            },
+            tryGet: (key) => req.params[key],
+        },
+        query: {
+            get: (key) => {
+                const parsedUrl = url.parse(req.url, true);
+                const value = parsedUrl.query[key];
+                return Array.isArray(value) ? value[0] : value;
+            },
+        },
+        state: new Map(),
+    };
+}

package/dist/esm/thread-local/thread-local-storage-middleware.js

@@ -0,0 +1,24 @@
+import { randomUUID } from 'crypto';
+import { getExpressApiConfig } from '../config';
+import { runWithRequestTlsData } from './thread-local-storage';
+/**
+ * Creates middleware that initializes thread-local storage for each request.
+ * Automatically generates a unique request ID and makes it available throughout
+ * the request lifecycle.
+ *
+ * @returns Express middleware function
+ */
+export function createTlsMiddleware() {
+    return async (req, _res, next) => {
+        const config = getExpressApiConfig();
+        const headerId = config.trustRequestIdHeader ? req.headers['x-request-id'] : undefined;
+        const existingId = req.requestId || headerId;
+        const requestId = typeof existingId === 'string' ? existingId : randomUUID();
+        // Run the next handler within the TLS context
+        await runWithRequestTlsData({
+            requestId,
+        }, async () => {
+            next();
+        });
+    };
+}

package/dist/esm/thread-local/thread-local-storage.js

@@ -0,0 +1,27 @@
+import { AsyncLocalStorage } from 'async_hooks';
+/**
+ * AsyncLocalStorage instance for managing per-request context.
+ * This ensures that each async operation associated with a request
+ * can access the request-specific data even across async boundaries.
+ * @Internal
+ */
+const asyncLocalStorage = new AsyncLocalStorage();
+/**
+ * Gets all thread-local data for the current request context.
+ * Returns undefined if called outside an async context managed by API.
+ * @Internal
+ */
+export function getRequestLocalStorage() {
+    return asyncLocalStorage.getStore();
+}
+/**
+ * Executes a callback within a request context with the given thread-local data.
+ * Used by middleware to set up the context for handlers.
+ * @Internal
+ * @param data - Thread-local data to establish
+ * @param callback - Function to execute within the context
+ * @returns Result of the callback
+ */
+export async function runWithRequestTlsData(data, callback) {
+    return asyncLocalStorage.run(data, callback);
+}

package/dist/esm/utils/conversion.utils.js

@@ -0,0 +1,22 @@
+/**
+ * Converts JS timestamp or date to ISO 8601 format (without milliseconds).
+ * Example: "2012-07-20T01:19:13Z".
+ * @Internal
+ */
+export function toApiDateString(value) {
+    const resultWithMillis = (typeof value === 'number' ? new Date(value) : value).toISOString();
+    return `${resultWithMillis.substring(0, resultWithMillis.length - 5)}Z`;
+}
+/**
+ * Wraps the response into the correct API form.
+ * Add necessary fields, like 'requestId'.
+ * If the response is already in the correct form, returns it as-is.
+ * @Internal
+ */
+export function wrapAsApiResponse(apiResponseOrResultValue) {
+    let apiResponse = apiResponseOrResultValue;
+    apiResponse = apiResponse?.result
+        ? apiResponse // The value is in the correct 'ApiResponse' form: just return it.
+        : { result: apiResponseOrResultValue }; // Wrap the raw value into the correct ApiResponse form.
+    return apiResponse;
+}

package/dist/esm/utils/express.utils.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@fishka/express",
+  "version": "0.9.5",
+  "description": "Express.js extension with built-in validation, and type safety",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "private": false,
+  "license": "MIT",
+  "sideEffects": false,
+  "scripts": {
+    "prebuild": "npm run clean",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build": "npm run build:esm && npm run build:cjs",
+    "clean": "rimraf ./dist",
+    "format": "prettier --write \"./**/*.{ts,js,md,json}\"",
+    "lint": "eslint .",
+    "test": "jest",
+    "typecheck": "tsc --noEmit",
+    "release": "npm run lint && npm run test && npm run build && npm publish"
+  },
+  "keywords": [
+    "express",
+    "expressjs",
+    "typescript",
+    "rest-api",
+    "rest"
+  ],
+  "dependencies": {
+    "@fishka/assertions": "^1.0.0",
+    "express": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.19.27",
+    "@typescript-eslint/eslint-plugin": "^8.51.0",
+    "@typescript-eslint/parser": "^8.51.0",
+    "eslint": "^9.39.2",
+    "eslint-plugin-unused-imports": "^4.3.0",
+    "jest": "^30.2.0",
+    "prettier": "^3.7.4",
+    "prettier-plugin-organize-imports": "^4.3.0",
+    "rimraf": "^6.1.2",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.9.3"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://gitea.com/fishka/express.git"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "npm": ">=9.0.0"
+  }
+}