@flink-app/flink 0.14.0 → 0.14.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @flink-app/flink
 
+## 0.14.2
+
+### Patch Changes
+
+-   6d39832: Add optional onError callback to FlinkApp for custom error handling. The callback receives a properly typed FlinkResponse<FlinkError> and rich request context (including request object, HTTP method, path, and request ID) when handler execution throws an error. Supports both synchronous and asynchronous callbacks, with automatic error handling to prevent callback failures from affecting the error response flow. Enables custom logging or monitoring without modifying the response flow.
+
+## 0.14.1
+
+### Patch Changes
+
+-   fix: restore compatibility between core framework and plugins after 0.14.0 release
+
 ## 0.14.0
 
 ### Minor Changes

package/dist/src/FlinkApp.d.ts

@@ -5,10 +5,12 @@ import { Db, MongoClient } from "mongodb";
 import { ToadScheduler } from "toad-scheduler";
 import { FlinkAuthPlugin } from "./auth/FlinkAuthPlugin";
 import { FlinkContext } from "./FlinkContext";
-import { HandlerFile, HttpMethod, QueryParamMetadata, RouteProps } from "./FlinkHttpHandler";
+import { FlinkError } from "./FlinkErrors";
+import { FlinkRequest, HandlerFile, HttpMethod, QueryParamMetadata, RouteProps } from "./FlinkHttpHandler";
 import { FlinkJobFile } from "./FlinkJob";
 import { FlinkPlugin } from "./FlinkPlugin";
 import { FlinkRepo } from "./FlinkRepo";
+import { FlinkResponse } from "./FlinkResponse";
 export type JSONSchema = JSONSchema7;
 /**
  * Re-export express factory function so sub packages
@@ -136,6 +138,50 @@ export interface FlinkOptions {
          */
         format?: string;
     };
+    /**
+     * Optional callback invoked when an error occurs in a handler.
+     * The error response and request context are passed for custom
+     * error logging or monitoring. This is a side-effect only and
+     * will not modify the response flow.
+     *
+     * Supports both synchronous and asynchronous callbacks. Any errors
+     * thrown or rejected by the callback will be caught and logged
+     * without affecting the error response to the client.
+     *
+     * @param error - The error response with status and error details
+     * @param context - Request context including method, path, and request ID
+     *
+     * @example
+     * ```ts
+     * // Synchronous callback
+     * onError: (error, context) => {
+     *   if (error.status >= 500) {
+     *     logger.error('Server error occurred', {
+     *       status: error.status,
+     *       code: error.error?.code,
+     *       route: `${context.method} ${context.path}`,
+     *       reqId: context.reqId
+     *     });
+     *   }
+     * }
+     *
+     * // Asynchronous callback
+     * onError: async (error, context) => {
+     *   if (error.status >= 500) {
+     *     await monitoringService.reportError({
+     *       error,
+     *       context
+     *     });
+     *   }
+     * }
+     * ```
+     */
+    onError?: (error: FlinkResponse<FlinkError>, context: {
+        req: FlinkRequest;
+        method: HttpMethod;
+        path: string;
+        reqId: string;
+    }) => void | Promise<void>;
 }
 export interface HandlerConfig {
     schema?: {
@@ -178,6 +224,7 @@ export declare class FlinkApp<C extends FlinkContext> {
     private schedulingOptions?;
     private disableHttpServer;
     private expressServer;
+    private onError?;
     private repos;
     /**
      * Internal cache used to track registered handlers and potentially any overlapping routes

package/dist/src/FlinkApp.js

@@ -122,6 +122,7 @@ var FlinkApp = /** @class */ (function () {
         this.schedulingOptions = opts.scheduling;
         this.disableHttpServer = !!opts.disableHttpServer;
         this.accessLog = __assign({ enabled: true, format: "dev" }, opts.accessLog);
+        this.onError = opts.onError;
     }
     Object.defineProperty(FlinkApp.prototype, "ctx", {
         get: function () {
@@ -341,7 +342,7 @@ var FlinkApp = /** @class */ (function () {
                 validateRes_1 = ajv.compile(schema.resSchema);
             }
             this.expressApp[method](routeProps.path, function (req, res) { return __awaiter(_this, void 0, void 0, function () {
-                var valid, formattedErrors, data, handlerRes, err_1, valid, formattedErrors;
+                var valid, formattedErrors, data, handlerRes, err_1, errorResponse, result, valid, formattedErrors;
                 return __generator(this, function (_a) {
                     switch (_a.label) {
                         case 0:
@@ -391,21 +392,45 @@ var FlinkApp = /** @class */ (function () {
                             return [3 /*break*/, 6];
                         case 5:
                             err_1 = _a.sent();
+                            errorResponse = void 0;
                             // duck typing to check if it is a FlinkError
                             if (typeof err_1.status === "number" && err_1.status >= 400 && err_1.status < 600 && err_1.error) {
-                                return [2 /*return*/, res.status(err_1.status).json({
-                                        status: err_1.status,
-                                        error: {
-                                            id: err_1.error.id || (0, uuid_1.v4)(),
-                                            title: err_1.error.title || "Unhandled error: ".concat(err_1.error.code || err_1.status),
-                                            detail: err_1.error.detail,
-                                            code: err_1.error.code,
-                                        },
-                                    })];
+                                errorResponse = {
+                                    status: err_1.status,
+                                    error: {
+                                        id: err_1.error.id || (0, uuid_1.v4)(),
+                                        title: err_1.error.title || "Unhandled error: ".concat(err_1.error.code || err_1.status),
+                                        detail: err_1.error.detail,
+                                        code: err_1.error.code,
+                                    },
+                                };
                             }
-                            FlinkLog_1.log.warn("Handler '".concat(methodAndRoute_1, "' threw unhandled exception ").concat(err_1));
-                            console.error(err_1);
-                            return [2 /*return*/, res.status(500).json((0, FlinkErrors_1.internalServerError)(err_1))];
+                            else {
+                                FlinkLog_1.log.warn("Handler '".concat(methodAndRoute_1, "' threw unhandled exception ").concat(err_1));
+                                console.error(err_1);
+                                errorResponse = (0, FlinkErrors_1.internalServerError)(err_1);
+                            }
+                            // Invoke onError callback if provided
+                            if (this.onError) {
+                                try {
+                                    result = this.onError(errorResponse, {
+                                        req: req,
+                                        method: method,
+                                        path: routeProps.path,
+                                        reqId: req.reqId,
+                                    });
+                                    // Handle async callbacks - don't wait for them
+                                    if (result instanceof Promise) {
+                                        result.catch(function (callbackErr) {
+                                            FlinkLog_1.log.error("onError callback rejected with: ".concat(callbackErr));
+                                        });
+                                    }
+                                }
+                                catch (callbackErr) {
+                                    FlinkLog_1.log.error("onError callback threw an exception: ".concat(callbackErr));
+                                }
+                            }
+                            return [2 /*return*/, res.status(errorResponse.status || 500).json(errorResponse)];
                         case 6:
                             if (validateRes_1 && !(0, utils_1.isError)(handlerRes)) {
                                 valid = validateRes_1(JSON.parse(JSON.stringify(handlerRes.data)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flink-app/flink",
-  "version": "0.14.0",
+  "version": "0.14.2",
   "description": "Typescript only framework for creating REST-like APIs on top of Express and mongodb",
   "types": "dist/src/index.d.ts",
   "main": "dist/src/index.js",

package/spec/FlinkApp.onError.spec.ts

@@ -0,0 +1,80 @@
+import { FlinkApp } from "../src/FlinkApp";
+import { FlinkContext } from "../src/FlinkContext";
+import { FlinkResponse } from "../src/FlinkResponse";
+import { FlinkError } from "../src/FlinkErrors";
+import { badRequest, internalServerError, notFound } from "../src/FlinkErrors";
+import { HttpMethod } from "../src/FlinkHttpHandler";
+
+interface TestContext extends FlinkContext {}
+
+describe("FlinkApp onError callback", () => {
+    let app: FlinkApp<TestContext>;
+    let capturedError: FlinkResponse<FlinkError> | null;
+    let capturedContext: any;
+
+    beforeEach(() => {
+        capturedError = null;
+        capturedContext = null;
+    });
+
+    afterEach(async () => {
+        if (app && app.started) {
+            await app.stop();
+        }
+    });
+
+    it("should be configurable in FlinkOptions", () => {
+        const callback = (error: FlinkResponse<FlinkError>, context: any) => {
+            capturedError = error;
+            capturedContext = context;
+        };
+
+        app = new FlinkApp<TestContext>({
+            name: "test-app",
+            disableHttpServer: true,
+            onError: callback,
+        });
+
+        expect(app).toBeDefined();
+    });
+
+    it("should have proper type signature for onError callback", () => {
+        // This test verifies TypeScript compilation
+        // The callback should accept FlinkResponse<FlinkError> and context object
+
+        const syncCallback = (error: FlinkResponse<FlinkError>, context: { req: any; method: HttpMethod; path: string; reqId: string }) => {
+            console.log(error.status, context.reqId);
+        };
+
+        const asyncCallback = async (error: FlinkResponse<FlinkError>, context: { req: any; method: HttpMethod; path: string; reqId: string }) => {
+            await Promise.resolve();
+            console.log(error.status, context.reqId);
+        };
+
+        const app1 = new FlinkApp<TestContext>({
+            name: "test-app-1",
+            disableHttpServer: true,
+            onError: syncCallback,
+        });
+
+        const app2 = new FlinkApp<TestContext>({
+            name: "test-app-2",
+            disableHttpServer: true,
+            onError: asyncCallback,
+        });
+
+        expect(app1).toBeDefined();
+        expect(app2).toBeDefined();
+    });
+
+    it("should be optional in FlinkOptions", async () => {
+        app = new FlinkApp<TestContext>({
+            name: "test-app",
+            disableHttpServer: true,
+            // No onError callback
+        });
+
+        await app.start();
+        expect(app.started).toBe(true);
+    });
+});

package/src/FlinkApp.ts

@@ -11,7 +11,7 @@ import { AsyncTask, CronJob, SimpleIntervalJob, ToadScheduler } from "toad-sched
 import { v4 } from "uuid";
 import { FlinkAuthPlugin } from "./auth/FlinkAuthPlugin";
 import { FlinkContext } from "./FlinkContext";
-import { internalServerError, notFound, unauthorized } from "./FlinkErrors";
+import { FlinkError, internalServerError, notFound, unauthorized } from "./FlinkErrors";
 import { FlinkRequest, Handler, HandlerFile, HttpMethod, QueryParamMetadata, RouteProps } from "./FlinkHttpHandler";
 import { FlinkJobFile } from "./FlinkJob";
 import { log } from "./FlinkLog";
@@ -197,6 +197,54 @@ export interface FlinkOptions {
          */
         format?: string;
     };
+
+    /**
+     * Optional callback invoked when an error occurs in a handler.
+     * The error response and request context are passed for custom
+     * error logging or monitoring. This is a side-effect only and
+     * will not modify the response flow.
+     *
+     * Supports both synchronous and asynchronous callbacks. Any errors
+     * thrown or rejected by the callback will be caught and logged
+     * without affecting the error response to the client.
+     *
+     * @param error - The error response with status and error details
+     * @param context - Request context including method, path, and request ID
+     *
+     * @example
+     * ```ts
+     * // Synchronous callback
+     * onError: (error, context) => {
+     *   if (error.status >= 500) {
+     *     logger.error('Server error occurred', {
+     *       status: error.status,
+     *       code: error.error?.code,
+     *       route: `${context.method} ${context.path}`,
+     *       reqId: context.reqId
+     *     });
+     *   }
+     * }
+     *
+     * // Asynchronous callback
+     * onError: async (error, context) => {
+     *   if (error.status >= 500) {
+     *     await monitoringService.reportError({
+     *       error,
+     *       context
+     *     });
+     *   }
+     * }
+     * ```
+     */
+    onError?: (
+        error: FlinkResponse<FlinkError>,
+        context: {
+            req: FlinkRequest;
+            method: HttpMethod;
+            path: string;
+            reqId: string;
+        }
+    ) => void | Promise<void>;
 }
 
 export interface HandlerConfig {
@@ -242,6 +290,7 @@ export class FlinkApp<C extends FlinkContext> {
     private schedulingOptions?: FlinkOptions["scheduling"];
     private disableHttpServer = false;
     private expressServer: any; // for simplicity, we don't want to import types from express/node here
+    private onError?: FlinkOptions["onError"];
 
     private repos: { [x: string]: FlinkRepo<C, any> } = {};
 
@@ -272,6 +321,7 @@ export class FlinkApp<C extends FlinkContext> {
         this.schedulingOptions = opts.scheduling;
         this.disableHttpServer = !!opts.disableHttpServer;
         this.accessLog = { enabled: true, format: "dev", ...opts.accessLog };
+        this.onError = opts.onError;
     }
 
     get ctx() {
@@ -540,9 +590,11 @@ export class FlinkApp<C extends FlinkContext> {
                         origin: routeProps.origin,
                     });
                 } catch (err: any) {
+                    let errorResponse: FlinkResponse<FlinkError>;
+
                     // duck typing to check if it is a FlinkError
                     if (typeof err.status === "number" && err.status >= 400 && err.status < 600 && err.error) {
-                        return res.status(err.status).json({
+                        errorResponse = {
                             status: err.status,
                             error: {
                                 id: err.error.id || v4(),
@@ -550,12 +602,35 @@ export class FlinkApp<C extends FlinkContext> {
                                 detail: err.error.detail,
                                 code: err.error.code,
                             },
-                        });
+                        };
+                    } else {
+                        log.warn(`Handler '${methodAndRoute}' threw unhandled exception ${err}`);
+                        console.error(err);
+                        errorResponse = internalServerError(err as any);
                     }
 
-                    log.warn(`Handler '${methodAndRoute}' threw unhandled exception ${err}`);
-                    console.error(err);
-                    return res.status(500).json(internalServerError(err as any));
+                    // Invoke onError callback if provided
+                    if (this.onError) {
+                        try {
+                            const result = this.onError(errorResponse, {
+                                req: req as FlinkRequest,
+                                method: method!,
+                                path: routeProps.path,
+                                reqId: req.reqId,
+                            });
+
+                            // Handle async callbacks - don't wait for them
+                            if (result instanceof Promise) {
+                                result.catch((callbackErr) => {
+                                    log.error(`onError callback rejected with: ${callbackErr}`);
+                                });
+                            }
+                        } catch (callbackErr) {
+                            log.error(`onError callback threw an exception: ${callbackErr}`);
+                        }
+                    }
+
+                    return res.status(errorResponse.status || 500).json(errorResponse);
                 }
 
                 if (validateRes && !isError(handlerRes)) {