@flink-app/flink 2.0.0-alpha.63 → 2.0.0-alpha.65

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @flink-app/flink
 
+## 2.0.0-alpha.65
+
+## 2.0.0-alpha.64
+
+### Patch Changes
+
+-   95b99ee: Add image and binary Buffer response support
+
+    Handlers can now return a Node.js `Buffer` as `data` when `responseType` is set to an image or binary MIME type. The buffer is sent as raw bytes with the correct `Content-Type` — no JSON wrapping.
+
+    Common image and binary MIME types are now first-class literals in `RouteProps.responseType` with autocomplete support: `"image/png"`, `"image/jpeg"`, `"image/gif"`, `"image/webp"`, `"image/svg+xml"`, `"application/pdf"`, `"application/octet-stream"`.
+
+    Example:
+
+    ```typescript
+    export const Route: RouteProps = {
+        path: "/logo",
+        responseType: "image/png",
+    };
+
+    const handler: GetHandler<Ctx, Buffer> = async () => {
+        const buf = await fs.promises.readFile("./assets/logo.png");
+        return { data: buf };
+    };
+    ```
+
 ## 2.0.0-alpha.63
 
 ### Patch Changes

package/dist/src/FlinkHttpHandler.d.ts

@@ -250,8 +250,21 @@ export interface RouteProps {
      *   return { data: `id,name\n1,Alice` };
      * };
      * ```
+     *
+     * @example
+     * ```typescript
+     * export const Route: RouteProps = {
+     *   path: "/logo",
+     *   responseType: "image/png",
+     * };
+     *
+     * const handler: GetHandler<AppContext, Buffer> = async ({ ctx }) => {
+     *   const imageBuffer = await fs.promises.readFile("./logo.png");
+     *   return { data: imageBuffer };
+     * };
+     * ```
      */
-    responseType?: "html" | "csv" | "text" | "xml" | (string & {});
+    responseType?: "html" | "csv" | "text" | "xml" | "image/png" | "image/jpeg" | "image/gif" | "image/svg+xml" | "image/webp" | "application/pdf" | "application/octet-stream" | (string & {});
     /**
      * Direct JSON Schema for request body validation.
      * When set, bypasses manifest lookup for request schema.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flink-app/flink",
-  "version": "2.0.0-alpha.63",
+  "version": "2.0.0-alpha.65",
   "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.htmlResponse.spec.ts

@@ -129,3 +129,132 @@ describe("HTML response handler (html: true in RouteProps)", () => {
         expect(response.text).toBe("<h1>Hello World</h1>");
     });
 });
+
+describe("Binary Buffer response handler (responseType: image/png)", () => {
+    let app: FlinkApp<TestContext>;
+
+    afterEach(async () => {
+        if (app && app.started) {
+            await app.stop();
+        }
+    });
+
+    it("should return image/png content type for Buffer response", async () => {
+        // Minimal valid 1x1 red PNG (67 bytes)
+        const pngBuffer = Buffer.from(
+            "89504e470d0a1a0a0000000d49484452000000010000000108020000009001" +
+                "2e00000000c4944415478016360f8cfc00000000200016934e360000000049454e44ae426082",
+            "hex"
+        );
+
+        const handler: GetHandler<TestContext, Buffer> = async () => {
+            return { data: pngBuffer };
+        };
+
+        app = new FlinkApp<TestContext>({ name: "test-png-ct", port: 4110 });
+        await app.start();
+
+        app.addHandler({
+            default: handler,
+            Route: { method: HttpMethod.get, path: "/image", responseType: "image/png" },
+        });
+
+        const response = await request(app.expressApp).get("/image");
+
+        expect(response.status).toBe(200);
+        expect(response.headers["content-type"]).toMatch(/image\/png/);
+    });
+
+    it("should return the exact buffer bytes as the response body", async () => {
+        const pngBuffer = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+        const handler: GetHandler<TestContext, Buffer> = async () => {
+            return { data: pngBuffer };
+        };
+
+        app = new FlinkApp<TestContext>({ name: "test-png-body", port: 4111 });
+        await app.start();
+
+        app.addHandler({
+            default: handler,
+            Route: { method: HttpMethod.get, path: "/image", responseType: "image/png" },
+        });
+
+        const response = await request(app.expressApp)
+            .get("/image")
+            .buffer(true)
+            .parse((res: any, callback: any) => {
+                const chunks: Buffer[] = [];
+                res.on("data", (chunk: Buffer) => chunks.push(chunk));
+                res.on("end", () => callback(null, Buffer.concat(chunks)));
+            });
+
+        expect(response.status).toBe(200);
+        expect(Buffer.compare(response.body, pngBuffer)).toBe(0);
+    });
+
+    it("should respect a custom status code for binary responses", async () => {
+        const handler: GetHandler<TestContext, Buffer> = async () => {
+            return { status: 404, data: Buffer.from("not found") };
+        };
+
+        app = new FlinkApp<TestContext>({ name: "test-png-status", port: 4112 });
+        await app.start();
+
+        app.addHandler({
+            default: handler,
+            Route: { method: HttpMethod.get, path: "/image", responseType: "image/png" },
+        });
+
+        const response = await request(app.expressApp).get("/image");
+
+        expect(response.status).toBe(404);
+        expect(response.headers["content-type"]).toMatch(/image\/png/);
+    });
+
+    it("should support image/jpeg content type", async () => {
+        const jpegBuffer = Buffer.from([0xff, 0xd8, 0xff, 0xe0]);
+
+        const handler: GetHandler<TestContext, Buffer> = async () => {
+            return { data: jpegBuffer };
+        };
+
+        app = new FlinkApp<TestContext>({ name: "test-jpeg-ct", port: 4113 });
+        await app.start();
+
+        app.addHandler({
+            default: handler,
+            Route: { method: HttpMethod.get, path: "/photo", responseType: "image/jpeg" },
+        });
+
+        const response = await request(app.expressApp).get("/photo");
+
+        expect(response.status).toBe(200);
+        expect(response.headers["content-type"]).toMatch(/image\/jpeg/);
+    });
+
+    it("should support application/octet-stream for generic binary data", async () => {
+        const binaryData = Buffer.from([0x00, 0x01, 0x02, 0x03, 0xff]);
+
+        const handler: GetHandler<TestContext, Buffer> = async () => {
+            return { data: binaryData };
+        };
+
+        app = new FlinkApp<TestContext>({ name: "test-octet", port: 4114 });
+        await app.start();
+
+        app.addHandler({
+            default: handler,
+            Route: {
+                method: HttpMethod.get,
+                path: "/binary",
+                responseType: "application/octet-stream",
+            },
+        });
+
+        const response = await request(app.expressApp).get("/binary");
+
+        expect(response.status).toBe(200);
+        expect(response.headers["content-type"]).toMatch(/application\/octet-stream/);
+    });
+});

package/src/FlinkHttpHandler.ts

@@ -272,8 +272,33 @@ export interface RouteProps {
      *   return { data: `id,name\n1,Alice` };
      * };
      * ```
+     *
+     * @example
+     * ```typescript
+     * export const Route: RouteProps = {
+     *   path: "/logo",
+     *   responseType: "image/png",
+     * };
+     *
+     * const handler: GetHandler<AppContext, Buffer> = async ({ ctx }) => {
+     *   const imageBuffer = await fs.promises.readFile("./logo.png");
+     *   return { data: imageBuffer };
+     * };
+     * ```
      */
-    responseType?: "html" | "csv" | "text" | "xml" | (string & {});
+    responseType?:
+        | "html"
+        | "csv"
+        | "text"
+        | "xml"
+        | "image/png"
+        | "image/jpeg"
+        | "image/gif"
+        | "image/svg+xml"
+        | "image/webp"
+        | "application/pdf"
+        | "application/octet-stream"
+        | (string & {});
 
     /**
      * Direct JSON Schema for request body validation.