@flink-app/flink 0.14.1 → 0.14.3

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @flink-app/flink
 
+## 0.14.3
+
+### Patch Changes
+
+-   52eba74: Fix Query type constraint to allow user-defined interfaces without explicit index signatures. The Query type now uses explicit index signature syntax, making it easier for developers to define query parameter interfaces for their handlers without TypeScript compilation errors.
+-   b37faa5: Improve schema validation error messages to show specific additional property names. When validation fails due to additional properties, the error now displays which properties are not allowed instead of a generic message.
+
+## 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

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:
@@ -363,7 +364,7 @@ var FlinkApp = /** @class */ (function () {
                                             error: {
                                                 id: (0, uuid_1.v4)(),
                                                 title: "Bad request",
-                                                detail: "Schema did not validate ".concat(JSON.stringify(validateReq_1.errors)),
+                                                detail: formattedErrors,
                                             },
                                         })];
                                 }
@@ -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)));
@@ -417,7 +442,7 @@ var FlinkApp = /** @class */ (function () {
                                             error: {
                                                 id: (0, uuid_1.v4)(),
                                                 title: "Bad response",
-                                                detail: "Schema did not validate ".concat(JSON.stringify(validateRes_1.errors)),
+                                                detail: formattedErrors,
                                             },
                                         })];
                                 }

package/dist/src/FlinkHttpHandler.d.ts

@@ -15,8 +15,13 @@ type Params = Request["params"];
  * Query type for request query parameters.
  * Does currently not allow nested objects, although
  * underlying express Request does allow it.
+ *
+ * Uses index signature to allow both Record types and interface types
+ * to be assignable to Query without requiring explicit index signatures.
  */
-type Query = Record<string, string | string[] | undefined>;
+type Query = {
+    [x: string]: string | string[] | undefined;
+};
 /**
  * Flink request extends express Request but adds reqId and user object.
  */

package/dist/src/utils.js

@@ -223,6 +223,9 @@ function formatValidationErrors(errors, data, maxDataLength) {
             else if (error.keyword === "type") {
                 formatted.push("  - Invalid type at ".concat(error.schemaPath, ": expected ").concat(error.params.type, ", got ").concat(typeof dataAtPath));
             }
+            else if (error.keyword === "additionalProperties") {
+                formatted.push("  - Additional property not allowed: ".concat(error.params.additionalProperty));
+            }
             else if (error.keyword === "anyOf" || error.keyword === "oneOf") {
                 formatted.push("  - ".concat(error.message));
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flink-app/flink",
-  "version": "0.14.1",
+  "version": "0.14.3",
   "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/spec/utils.spec.ts

@@ -148,6 +148,33 @@ describe("Utils", () => {
             expect(formatted).toContain('Missing required property: email');
             expect(formatted).toContain('Missing required property: age');
         });
+
+        it("should show specific additional property names", () => {
+            const errors = [
+                {
+                    instancePath: "",
+                    schemaPath: "#/additionalProperties",
+                    keyword: "additionalProperties",
+                    params: { additionalProperty: "extraField1" },
+                    message: "must NOT have additional properties",
+                },
+                {
+                    instancePath: "",
+                    schemaPath: "#/additionalProperties",
+                    keyword: "additionalProperties",
+                    params: { additionalProperty: "extraField2" },
+                    message: "must NOT have additional properties",
+                },
+            ];
+            const data = { name: "John", age: 30, extraField1: "value1", extraField2: "value2" };
+
+            const formatted = formatValidationErrors(errors, data);
+
+            // This formatted output is used in HTTP error responses (400/500) in the error.detail field
+            expect(formatted).toContain('Path: /');
+            expect(formatted).toContain('Additional property not allowed: extraField1');
+            expect(formatted).toContain('Additional property not allowed: extraField2');
+        });
     });
 });
 

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() {
@@ -512,7 +562,7 @@ export class FlinkApp<C extends FlinkContext> {
                             error: {
                                 id: v4(),
                                 title: "Bad request",
-                                detail: `Schema did not validate ${JSON.stringify(validateReq.errors)}`,
+                                detail: formattedErrors,
                             },
                         });
                     }
@@ -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)) {
@@ -570,7 +645,7 @@ export class FlinkApp<C extends FlinkContext> {
                             error: {
                                 id: v4(),
                                 title: "Bad response",
-                                detail: `Schema did not validate ${JSON.stringify(validateRes.errors)}`,
+                                detail: formattedErrors,
                             },
                         });
                     }

package/src/FlinkHttpHandler.ts

@@ -18,8 +18,13 @@ type Params = Request["params"];
  * Query type for request query parameters.
  * Does currently not allow nested objects, although
  * underlying express Request does allow it.
+ *
+ * Uses index signature to allow both Record types and interface types
+ * to be assignable to Query without requiring explicit index signatures.
  */
-type Query = Record<string, string | string[] | undefined>;
+type Query = {
+    [x: string]: string | string[] | undefined;
+};
 
 /**
  * Flink request extends express Request but adds reqId and user object.

package/src/utils.ts

@@ -165,6 +165,8 @@ export function formatValidationErrors(errors: any[] | null | undefined, data: a
                 formatted.push(`  - Missing required property: ${error.params.missingProperty}`);
             } else if (error.keyword === "type") {
                 formatted.push(`  - Invalid type at ${error.schemaPath}: expected ${error.params.type}, got ${typeof dataAtPath}`);
+            } else if (error.keyword === "additionalProperties") {
+                formatted.push(`  - Additional property not allowed: ${error.params.additionalProperty}`);
             } else if (error.keyword === "anyOf" || error.keyword === "oneOf") {
                 formatted.push(`  - ${error.message}`);
             } else {