@fishka/express 0.9.5

package/README.md

@@ -0,0 +1,137 @@
+# Express API
+
+Type-safe Express.js routing with clean, minimal API.
+
+## Installation
+
+```bash
+npm install @fishka/express
+```
+
+## Quick Start
+
+```typescript
+import express from 'express';
+import { createRouteTable } from '@fishka/express';
+
+const app = express();
+app.use(express.json());
+
+const routes = createRouteTable(app);
+
+// GET /users/:id - using function shorthand
+routes.get<{ id: string; name: string }>('users/:id', async ctx => ({
+  id: ctx.params.get('id'),
+  name: 'John',
+}));
+
+// GET /users - using full endpoint object
+routes.get<Array<{ id: string; name: string }>>('users', async () => [
+  { id: '1', name: 'John' },
+  { id: '2', name: 'Jane' },
+]);
+
+// POST /users
+routes.post<{ name: string }, { id: string }>('users', {
+  $body: { name: v => assertString(v, '400: name required') },
+  run: async ctx => ({ id: '1' }),
+});
+
+// DELETE /users/:id - using function shorthand
+routes.delete('users/:id', async () => {
+  // Delete user logic
+});
+
+app.listen(3000);
+```
+
+## URL Parameters
+
+Global validation can be enforced for specific URL parameters (e.g., `:id`, `:orgId`) across all routes.
+
+```typescript
+import { registerUrlParameter } from '@fishka/express';
+import { assertString } from '@fishka/assertions';
+
+// Register parameters with optional validation
+registerUrlParameter('orgId', {
+  validator: (val) => {
+    assertString(val);
+    if (!val.startsWith('org-')) throw new Error('400: Invalid Organization ID');
+  }
+});
+
+// Now /orgs/:orgId will automatically validate that orgId starts with 'org-'
+```
+
+## Authentication
+
+```typescript
+import { createAuthMiddleware, BasicAuthStrategy, getAuthUser } from '@fishka/express';
+
+const auth = new BasicAuthStrategy(async (user, pass) =>
+  user === 'admin' && pass === 'secret' ? { id: '1', role: 'admin' } : null,
+);
+
+routes.get('profile', {
+  middlewares: [createAuthMiddleware(auth)],
+  run: async ctx => {
+    const user = getAuthUser(ctx);
+    return { id: user.id };
+  },
+});
+```
+
+## Rate Limiting
+
+```typescript
+import { createRateLimiterMiddleware } from '@fishka/express';
+
+app.use(
+  await createRateLimiterMiddleware({
+    points: { read: 100, write: 50 },
+    duration: 60,
+  }),
+);
+```
+
+## Complete Example
+
+Here is a full initialization including TLS context, global validation, and proper error handling.
+
+```typescript
+import express from 'express';
+import { 
+  createRouteTable, 
+  createTlsMiddleware, 
+  catchAllMiddleware,
+  registerUrlParameter 
+} from '@fishka/express';
+import { assertString } from '@fishka/assertions';
+
+const app = express();
+
+// 1. Basic express middleware
+app.use(express.json());
+
+// 2. Initialize TLS context (Request IDs, etc.)
+app.use(createTlsMiddleware());
+
+// 3. Register global URL parameters
+registerUrlParameter('id', {
+  validator: (val) => assertString(val)
+});
+
+// 4. Define routes
+const routes = createRouteTable(app);
+routes.get('health', async () => ({ status: 'UP' }));
+
+// 5. Global error handler (Must be after route definitions)
+app.use(catchAllMiddleware);
+
+app.listen(3000);
+```
+
+## License
+
+MIT

package/dist/cjs/api.types.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.URL_PARAMETER_INFO = exports.HttpError = void 0;
+exports.response = response;
+exports.registerUrlParameter = registerUrlParameter;
+exports.assertUrlParameter = assertUrlParameter;
+const assertions_1 = require("@fishka/assertions");
+class HttpError extends Error {
+    constructor(status, message, details) {
+        super(message);
+        this.status = status;
+        this.details = details;
+        // Restore prototype chain for instanceof checks
+        Object.setPrototypeOf(this, HttpError.prototype);
+    }
+}
+exports.HttpError = HttpError;
+/** Converts an API response value into a standardized ApiResponse structure. */
+function response(result) {
+    return { result };
+}
+/**
+ * Default documentation and validation for URL parameters.
+ * @Internal
+ */
+exports.URL_PARAMETER_INFO = {};
+/** Registers a new URL parameter. */
+function registerUrlParameter(name, info) {
+    exports.URL_PARAMETER_INFO[name] = info;
+}
+/**
+ * Asserts that the value is a registered URL parameter name.
+ * @Internal
+ */
+function assertUrlParameter(name) {
+    (0, assertions_1.assertString)(name, 'Url parameter name must be a string');
+    (0, assertions_1.assertTruthy)(exports.URL_PARAMETER_INFO[name], `Invalid URL parameter: '${name}'. Please register it using 'registerUrlParameter('${name}', ...)'`);
+}

package/dist/cjs/auth/auth-strategy.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BasicAuthStrategy = void 0;
+const api_types_1 = require("../api.types");
+const http_types_1 = require("../http.types");
+/**
+ * Basic authentication strategy using username/password validation.
+ * Parses HTTP Basic Authorization header and validates credentials.
+ *
+ * Example usage:
+ * ```
+ * const strategy = new BasicAuthStrategy(
+ *   async (username, password) => {
+ *     const user = await db.users.findByUsername(username);
+ *     if (user && await bcrypt.compare(password, user.hash)) {
+ *       return user;
+ *     }
+ *     return null;
+ *   }
+ * );
+ * ```
+ */
+class BasicAuthStrategy {
+    constructor(verifyFn) {
+        this.verifyFn = verifyFn;
+    }
+    /**
+     * Extracts username and password from Basic auth header.
+     * Expected format: "Basic base64(username:password)"
+     * Returns undefined if header is missing or not Basic.
+     */
+    extractCredentials(req) {
+        const authHeaderValue = req.header('Authorization');
+        if (!authHeaderValue || !authHeaderValue.startsWith('Basic ')) {
+            return undefined;
+        }
+        try {
+            const decoded = Buffer.from(authHeaderValue.substring(6), 'base64').toString('utf-8');
+            const [username, password] = decoded.split(':');
+            // If format is "Basic base64(:)", it might mean empty username/password which is technically valid syntax but usually useless.
+            // However, split might return undefined for password if ":" is missing.
+            if (!username || password === undefined) {
+                return undefined;
+            }
+            return { username, password };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Validates the extracted credentials using the provided validation function.
+     */
+    async validateCredentials({ username, password }) {
+        const user = await this.verifyFn(username, password);
+        if (!user) {
+            throw new api_types_1.HttpError(http_types_1.UNAUTHORIZED_STATUS, 'Invalid username or password');
+        }
+        return user;
+    }
+}
+exports.BasicAuthStrategy = BasicAuthStrategy;

package/dist/cjs/auth/auth.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/auth/auth.utils.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAuthMiddleware = createAuthMiddleware;
+exports.getAuthUser = getAuthUser;
+exports.tryGetAuthUser = tryGetAuthUser;
+const api_types_1 = require("../api.types");
+const http_types_1 = require("../http.types");
+/**
+ * Creates a middleware that enforces authentication using the provided strategy.
+ * The authenticated user is stored in the context under the 'authUser' key.
+ *
+ * @template User - Type of the authenticated user
+ * @param strategy - Authentication strategy to use
+ * @param onSuccess - Optional callback to process authenticated user
+ * @returns a middleware that enforces authentication
+ */
+function createAuthMiddleware(strategy, onSuccess) {
+    return async (handler, context) => {
+        // Extract credentials from request
+        const credentials = strategy.extractCredentials(context.req);
+        // If no credentials found (and strategy returned undefined), we must deny access here.
+        // In a composite strategy scenario, we might want to try the next strategy, but this helper is for a single strategy enforcement.
+        if (!credentials) {
+            throw new api_types_1.HttpError(http_types_1.UNAUTHORIZED_STATUS, 'No credentials provided or invalid format');
+        }
+        // Validate credentials and get authenticated user
+        const user = await strategy.validateCredentials(credentials);
+        // Store authenticated user in state for the handler to access
+        context.authUser = user;
+        // Optional: Call success callback
+        if (onSuccess) {
+            onSuccess(user, context);
+        }
+        // Execute the actual handler
+        return handler();
+    };
+}
+/**
+ * Extracts the authenticated user from the request context.
+ * Throws if the user is not present (i.e., authentication was not performed).
+ *
+ * @template User - Type of the authenticated user
+ * @param context - Request context
+ * @returns The authenticated user
+ * @throws Error if user is not found in context
+ */
+function getAuthUser(context) {
+    const user = context.authUser;
+    if (!user) {
+        throw new api_types_1.HttpError(http_types_1.UNAUTHORIZED_STATUS, 'User not found in context. Did you add auth middleware?');
+    }
+    return user;
+}
+/**
+ * Safely extracts the authenticated user from the request context.
+ * Returns undefined if the user is not present.
+ *
+ * @template User - Type of the authenticated user
+ * @param context - Request context
+ * @returns The authenticated user, or undefined if not found
+ */
+function tryGetAuthUser(context) {
+    return context.authUser;
+}

package/dist/cjs/auth/bearer-auth-strategy.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BearerAuthStrategy = void 0;
+const api_types_1 = require("../api.types");
+const http_types_1 = require("../http.types");
+/**
+ * Bearer authentication strategy (commonly used for JWTs).
+ * Extracts the token from the 'Authorization: Bearer <token>' header.
+ *
+ * The validation logic is delegated to the `verifyFn`, which can:
+ * - Validate a JWT signature locally.
+ * - Call an external API/website to verify the token (Introspection/UserInfo).
+ *
+ * Example usage:
+ * ```ts
+ * const strategy = new BearerAuthStrategy(async (token) => {
+ *   // Call external website to validate
+ *   const response = await fetch('https://auth.example.com/verify', {
+ *     headers: { Authorization: `Bearer ${token}` }
+ *   });
+ *   if (!response.ok) return null;
+ *   return await response.json();
+ * });
+ * ```
+ */
+class BearerAuthStrategy {
+    /**
+     * @param verifyFn Function to validate the token. Returns the user if valid, or null if invalid.
+     */
+    constructor(verifyFn) {
+        this.verifyFn = verifyFn;
+    }
+    /**
+     * Extracts the Bearer token from the Authorization header.
+     * Returns undefined if the header is missing or not a Bearer token.
+     */
+    extractCredentials(req) {
+        const authHeader = req.header('Authorization');
+        if (!authHeader || !authHeader.startsWith('Bearer ')) {
+            return undefined;
+        }
+        const token = authHeader.substring(7).trim();
+        if (!token) {
+            return undefined;
+        }
+        return token;
+    }
+    /**
+     * Validates the extracted token using the provided verification function.
+     */
+    async validateCredentials(token) {
+        const user = await this.verifyFn(token);
+        if (!user) {
+            throw new api_types_1.HttpError(http_types_1.UNAUTHORIZED_STATUS, 'Invalid token');
+        }
+        return user;
+    }
+}
+exports.BearerAuthStrategy = BearerAuthStrategy;

package/dist/cjs/config.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureExpressApi = configureExpressApi;
+exports.getExpressApiConfig = getExpressApiConfig;
+exports.resetExpressApiConfig = resetExpressApiConfig;
+const defaultConfig = {
+    trustRequestIdHeader: true,
+};
+let currentConfig = { ...defaultConfig };
+/**
+ * Configure global @fishka/express settings.
+ * @param config Partial configuration to merge with current settings
+ */
+function configureExpressApi(config) {
+    currentConfig = { ...currentConfig, ...config };
+}
+/**
+ * Get current Express API configuration.
+ */
+function getExpressApiConfig() {
+    return currentConfig;
+}
+/**
+ * Reset API configuration to defaults.
+ * Useful for testing.
+ */
+function resetExpressApiConfig() {
+    currentConfig = { ...defaultConfig };
+}

package/dist/cjs/error-handling.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.catchRouteErrors = catchRouteErrors;
+exports.catchAllMiddleware = catchAllMiddleware;
+const assertions_1 = require("@fishka/assertions");
+const api_types_1 = require("./api.types");
+const http_types_1 = require("./http.types");
+const thread_local_storage_1 = require("./thread-local/thread-local-storage");
+const conversion_utils_1 = require("./utils/conversion.utils");
+function buildApiResponse(error) {
+    const tls = (0, thread_local_storage_1.getRequestLocalStorage)();
+    const requestId = tls?.requestId;
+    let response;
+    if (error instanceof api_types_1.HttpError) {
+        response = {
+            ...(0, conversion_utils_1.wrapAsApiResponse)(undefined),
+            error: error.message,
+            status: error.status,
+            details: error.details,
+        };
+    }
+    else {
+        const errorMessage = (0, assertions_1.getMessageFromError)(error, '');
+        response = {
+            ...(0, conversion_utils_1.wrapAsApiResponse)(undefined),
+            error: errorMessage && errorMessage.length > 0 ? errorMessage : 'Internal error',
+            status: http_types_1.INTERNAL_ERROR_STATUS,
+        };
+    }
+    if (requestId) {
+        response.requestId = requestId;
+    }
+    return response;
+}
+/** Catches all kinds of unprocessed exceptions thrown from a single route. */
+function catchRouteErrors(fn) {
+    return async (req, res, next) => {
+        try {
+            await fn(req, res, next);
+        }
+        catch (error) {
+            const apiResponse = buildApiResponse(error);
+            if (apiResponse.status >= http_types_1.INTERNAL_ERROR_STATUS) {
+                console.error(`catchRouteErrors: ${req.path}`, error);
+            }
+            else {
+                console.log(`catchRouteErrors: ${req.path}`, error);
+            }
+            res.status(apiResponse.status);
+            res.send(apiResponse);
+        }
+    };
+}
+/**
+ * Catches all errors in Express.js and is installed as global middleware.
+ * Note that individual routes are wrapped with 'catchRouteErrors' middleware.
+ */
+async function catchAllMiddleware(error, _, res, next) {
+    if (!error) {
+        next();
+        return;
+    }
+    // Report as critical. This kind of error should never happen.
+    console.error('catchAllMiddleware:', (0, assertions_1.getMessageFromError)(error));
+    const apiResponse = error instanceof SyntaxError // JSON body parsing error.
+        ? buildApiResponse(`${http_types_1.BAD_REQUEST_STATUS}: Failed to parse request: ${error.message}`)
+        : buildApiResponse(error);
+    res.status(apiResponse.status);
+    res.send(apiResponse);
+}

package/dist/cjs/http.types.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOO_MANY_REQUESTS_STATUS = exports.OK_STATUS = exports.NOT_FOUND_STATUS = exports.FORBIDDEN_STATUS = exports.UNAUTHORIZED_STATUS = exports.BAD_REQUEST_STATUS = exports.INTERNAL_ERROR_STATUS = void 0;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+exports.INTERNAL_ERROR_STATUS = 500;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+exports.BAD_REQUEST_STATUS = 400;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+exports.UNAUTHORIZED_STATUS = 401;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+exports.FORBIDDEN_STATUS = 403;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+exports.NOT_FOUND_STATUS = 404;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+exports.OK_STATUS = 200;
+/**
+ * Common HTTP status codes as numbers.
+ * @Internal
+ */
+exports.TOO_MANY_REQUESTS_STATUS = 429;

package/dist/cjs/index.js

@@ -0,0 +1,31 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./api.types"), exports);
+__exportStar(require("./auth/auth-strategy"), exports);
+__exportStar(require("./auth/auth.types"), exports);
+__exportStar(require("./auth/auth.utils"), exports);
+__exportStar(require("./auth/bearer-auth-strategy"), exports);
+__exportStar(require("./config"), exports);
+__exportStar(require("./error-handling"), exports);
+__exportStar(require("./http.types"), exports);
+__exportStar(require("./rate-limit/in-memory-rate-limiter"), exports);
+__exportStar(require("./rate-limit/rate-limit.types"), exports);
+__exportStar(require("./route-table"), exports);
+__exportStar(require("./router"), exports);
+__exportStar(require("./thread-local/thread-local-storage"), exports);
+__exportStar(require("./thread-local/thread-local-storage-middleware"), exports);
+__exportStar(require("./utils/express.utils"), exports);

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

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryRateLimiter = void 0;
+exports.createRateLimiterMiddleware = createRateLimiterMiddleware;
+const rate_limit_1 = require("./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,
+        };
+    }
+}
+exports.InMemoryRateLimiter = InMemoryRateLimiter;
+/**
+ * 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
+ */
+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);
+            (0, rate_limit_1.addRateLimitHeaders)(res, result, limitPoints, config.duration);
+            next();
+        }
+        catch (error) {
+            const result = error;
+            (0, rate_limit_1.addRateLimitHeaders)(res, result, limitPoints, config.duration)
+                .header('Retry-After', `${(0, rate_limit_1.msToSeconds)(result.msBeforeNext)}`)
+                .status(429)
+                .send({ error: 'Too Many Requests' });
+        }
+    };
+}

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

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addRateLimitHeaders = addRateLimitHeaders;
+exports.msToSeconds = msToSeconds;
+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
+ */
+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
+ */
+function msToSeconds(ms) {
+    return Math.ceil(ms / MILLIS_PER_SECOND);
+}

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

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });