@flink-app/flink 0.14.3 → 2.0.0-alpha.48

package/spec/FlinkApp.query.spec.ts

@@ -0,0 +1,107 @@
+import { FlinkApp } from "../src/FlinkApp";
+import { FlinkContext } from "../src/FlinkContext";
+import { GetHandler, HttpMethod } from "../src/FlinkHttpHandler";
+
+const request = require("supertest");
+
+interface TestContext extends FlinkContext {}
+
+describe("Query parameter normalization", () => {
+    let app: FlinkApp<TestContext>;
+
+    afterEach(async () => {
+        if (app && app.started) {
+            await app.stop();
+        }
+    });
+
+    it("should normalize query params to strings", async () => {
+        const handler: GetHandler<TestContext, any> = async ({ req }) => {
+            return { status: 200, data: { query: req.query } };
+        };
+
+        app = new FlinkApp<TestContext>({ name: "test-query-norm", port: 4000 });
+        await app.start();
+
+        app.addHandler({
+            default: handler,
+            Route: { method: HttpMethod.get, path: "/test" },
+        });
+
+        const response = await request(app.expressApp).get("/test?name=John&age=25");
+
+        expect(response.status).toBe(200);
+        expect(response.body.data.query.name).toBe("John");
+        expect(response.body.data.query.age).toBe("25");
+        expect(typeof response.body.data.query.name).toBe("string");
+        expect(typeof response.body.data.query.age).toBe("string");
+    });
+
+    it("should normalize array query params to string arrays", async () => {
+        const handler: GetHandler<TestContext, any> = async ({ req }) => {
+            return { status: 200, data: { query: req.query } };
+        };
+
+        app = new FlinkApp<TestContext>({ name: "test-query-array", port: 4001 });
+        await app.start();
+
+        app.addHandler({
+            default: handler,
+            Route: { method: HttpMethod.get, path: "/test-array" },
+        });
+
+        const response = await request(app.expressApp).get("/test-array?tag=a&tag=b&tag=c");
+
+        expect(response.status).toBe(200);
+        expect(Array.isArray(response.body.data.query.tag)).toBe(true);
+        expect(response.body.data.query.tag).toEqual(["a", "b", "c"]);
+        response.body.data.query.tag.forEach((tag: string) => {
+            expect(typeof tag).toBe("string");
+        });
+    });
+
+    it("should normalize numeric values to strings", async () => {
+        const handler: GetHandler<TestContext, any> = async ({ req }) => {
+            return { status: 200, data: { query: req.query } };
+        };
+
+        app = new FlinkApp<TestContext>({ name: "test-query-numbers", port: 4002 });
+        await app.start();
+
+        app.addHandler({
+            default: handler,
+            Route: { method: HttpMethod.get, path: "/test-numbers" },
+        });
+
+        const response = await request(app.expressApp).get("/test-numbers?count=100&price=99.99");
+
+        expect(response.status).toBe(200);
+        expect(response.body.data.query.count).toBe("100");
+        expect(response.body.data.query.price).toBe("99.99");
+        expect(typeof response.body.data.query.count).toBe("string");
+        expect(typeof response.body.data.query.price).toBe("string");
+    });
+
+    it("should allow handlers to parse strings as needed", async () => {
+        const handler: GetHandler<TestContext, any> = async ({ req }) => {
+            const page = Number(req.query.page) || 1;
+            const active = req.query.active === "true";
+
+            return { status: 200, data: { page, active } };
+        };
+
+        app = new FlinkApp<TestContext>({ name: "test-query-parsing", port: 4003 });
+        await app.start();
+
+        app.addHandler({
+            default: handler,
+            Route: { method: HttpMethod.get, path: "/test-parsing" },
+        });
+
+        const response = await request(app.expressApp).get("/test-parsing?page=2&active=true");
+
+        expect(response.status).toBe(200);
+        expect(response.body.data.page).toBe(2);
+        expect(response.body.data.active).toBe(true);
+    });
+});

package/spec/FlinkApp.validationMode.spec.ts

@@ -0,0 +1,155 @@
+import { FlinkApp } from "../src/FlinkApp";
+import { FlinkContext } from "../src/FlinkContext";
+import { Handler, RouteProps, ValidationMode } from "../src/FlinkHttpHandler";
+
+interface TestContext extends FlinkContext {}
+
+// Test schemas
+interface ValidRequest {
+    name: string;
+    age: number;
+}
+
+interface ValidResponse {
+    message: string;
+    status: string;
+}
+
+describe("FlinkApp validation modes", () => {
+    let app: FlinkApp<TestContext>;
+
+    beforeEach(async () => {
+        app = new FlinkApp<TestContext>({
+            name: "validation-test-app",
+            debug: false,
+        });
+    });
+
+    afterEach(async () => {
+        if (app && app.started) {
+            await app.stop();
+        }
+    });
+
+    describe("ValidationMode enum", () => {
+        it("should have all validation mode values", () => {
+            expect(ValidationMode.Validate).toBe("Validate");
+            expect(ValidationMode.SkipValidation).toBe("SkipValidation");
+            expect(ValidationMode.ValidateRequest).toBe("ValidateRequest");
+            expect(ValidationMode.ValidateResponse).toBe("ValidateResponse");
+        });
+    });
+
+    describe("RouteProps validation property", () => {
+        it("should accept validation property with ValidationMode.Validate", () => {
+            const route: RouteProps = {
+                path: "/test",
+                validation: ValidationMode.Validate,
+            };
+
+            expect(route.validation).toBe(ValidationMode.Validate);
+        });
+
+        it("should accept validation property with ValidationMode.SkipValidation", () => {
+            const route: RouteProps = {
+                path: "/test",
+                validation: ValidationMode.SkipValidation,
+            };
+
+            expect(route.validation).toBe(ValidationMode.SkipValidation);
+        });
+
+        it("should accept validation property with ValidationMode.ValidateRequest", () => {
+            const route: RouteProps = {
+                path: "/test",
+                validation: ValidationMode.ValidateRequest,
+            };
+
+            expect(route.validation).toBe(ValidationMode.ValidateRequest);
+        });
+
+        it("should accept validation property with ValidationMode.ValidateResponse", () => {
+            const route: RouteProps = {
+                path: "/test",
+                validation: ValidationMode.ValidateResponse,
+            };
+
+            expect(route.validation).toBe(ValidationMode.ValidateResponse);
+        });
+
+        it("should be optional and default to undefined", () => {
+            const route: RouteProps = {
+                path: "/test",
+            };
+
+            expect(route.validation).toBeUndefined();
+        });
+    });
+
+    describe("Handler type compatibility", () => {
+        it("should allow handlers with validation modes to compile", () => {
+            // This test verifies TypeScript compilation
+
+            const handler: Handler<TestContext, ValidRequest, ValidResponse> = async ({ ctx, req }) => {
+                return {
+                    status: 200,
+                    data: {
+                        message: "success",
+                        status: "ok",
+                    },
+                };
+            };
+
+            expect(handler).toBeDefined();
+            expect(typeof handler).toBe("function");
+        });
+
+        it("should allow route props with different validation modes", () => {
+            const routes: RouteProps[] = [
+                { path: "/test1", validation: ValidationMode.Validate },
+                { path: "/test2", validation: ValidationMode.SkipValidation },
+                { path: "/test3", validation: ValidationMode.ValidateRequest },
+                { path: "/test4", validation: ValidationMode.ValidateResponse },
+                { path: "/test5" }, // No validation specified
+            ];
+
+            expect(routes.length).toBe(5);
+            expect(routes[0].validation).toBe(ValidationMode.Validate);
+            expect(routes[1].validation).toBe(ValidationMode.SkipValidation);
+            expect(routes[2].validation).toBe(ValidationMode.ValidateRequest);
+            expect(routes[3].validation).toBe(ValidationMode.ValidateResponse);
+            expect(routes[4].validation).toBeUndefined();
+        });
+    });
+
+    describe("Backward compatibility", () => {
+        it("should not break existing code without validation property", () => {
+            const route: RouteProps = {
+                path: "/legacy",
+                permissions: ["admin"],
+            };
+
+            // TypeScript should compile this without errors
+            expect(route.path).toBe("/legacy");
+            expect(route.validation).toBeUndefined();
+        });
+
+        it("should allow all existing RouteProps properties with validation", () => {
+            const route: RouteProps = {
+                path: "/test",
+                permissions: ["admin", "user"],
+                skipAutoRegister: true,
+                docs: "Test endpoint",
+                order: -1,
+                validation: ValidationMode.SkipValidation,
+            };
+
+            expect(route.path).toBe("/test");
+            expect(route.permissions).toEqual(["admin", "user"]);
+            expect(route.skipAutoRegister).toBe(true);
+            expect(route.docs).toBe("Test endpoint");
+            expect(route.order).toBe(-1);
+            expect(route.validation).toBe(ValidationMode.SkipValidation);
+        });
+    });
+});

package/spec/StreamingIntegration.spec.ts

@@ -0,0 +1,138 @@
+import { FlinkAgent, StreamChunk } from "../src/ai/FlinkAgent";
+import { FlinkContext } from "../src/FlinkContext";
+import { LLMAdapter, LLMStreamChunk } from "../src/ai/LLMAdapter";
+
+describe("Streaming Integration", () => {
+  let mockCtx: FlinkContext;
+
+  beforeEach(() => {
+    mockCtx = {
+      repos: {},
+      plugins: {},
+    };
+  });
+
+  class StreamingTestAgent extends FlinkAgent<FlinkContext> {
+    description = "Test agent for streaming";
+    instructions = "You are a test agent";
+    tools = [];
+
+    async query(message: string) {
+      const response = this.execute({ message });
+      return response;
+    }
+
+    setContext(ctx: FlinkContext) {
+      (this as any).ctx = ctx;
+    }
+
+    setMockLLMAdapter(adapter: LLMAdapter) {
+      this.__init(new Map([["default", adapter]]), {});
+    }
+  }
+
+  it("should stream text deltas in real-time", async () => {
+    const agent = new StreamingTestAgent();
+    agent.setContext(mockCtx);
+
+    // Mock LLM that streams chunks
+    const mockAdapter: LLMAdapter = {
+      stream: async function* () {
+        yield { type: "text", delta: "Hello " } as LLMStreamChunk;
+        yield { type: "text", delta: "world " } as LLMStreamChunk;
+        yield { type: "text", delta: "from agent" } as LLMStreamChunk;
+        yield { type: "usage", usage: { inputTokens: 10, outputTokens: 5 } } as LLMStreamChunk;
+        yield { type: "done", stopReason: "end_turn" } as LLMStreamChunk;
+      },
+    };
+
+    agent.setMockLLMAdapter(mockAdapter);
+
+    const response = agent.query("Hello");
+
+    const textChunks: string[] = [];
+    for await (const text of (await response).textStream) {
+      textChunks.push(text);
+    }
+
+    expect(textChunks.length).toBe(3);
+    expect(textChunks.join("")).toBe("Hello world from agent");
+  });
+
+  it("should emit text_delta events during streaming", async () => {
+    const agent = new StreamingTestAgent();
+    agent.setContext(mockCtx);
+
+    const mockAdapter: LLMAdapter = {
+      stream: async function* () {
+        yield { type: "text", delta: "Pro" } as LLMStreamChunk;
+        yield { type: "text", delta: "gressive " } as LLMStreamChunk;
+        yield { type: "text", delta: "text" } as LLMStreamChunk;
+        yield { type: "usage", usage: { inputTokens: 10, outputTokens: 5 } } as LLMStreamChunk;
+        yield { type: "done", stopReason: "end_turn" } as LLMStreamChunk;
+      },
+    };
+
+    agent.setMockLLMAdapter(mockAdapter);
+
+    const response = agent.query("Hello");
+
+    const events: StreamChunk[] = [];
+    for await (const chunk of (await response).fullStream) {
+      events.push(chunk);
+    }
+
+    const textDeltas = events.filter((e) => e.type === "text_delta");
+    expect(textDeltas.length).toBe(3);
+    expect((textDeltas[0] as any).delta).toBe("Pro");
+    expect((textDeltas[1] as any).delta).toBe("gressive ");
+    expect((textDeltas[2] as any).delta).toBe("text");
+  });
+
+  it("should allow consuming result after streaming completes", async () => {
+    const agent = new StreamingTestAgent();
+    agent.setContext(mockCtx);
+
+    const mockAdapter: LLMAdapter = {
+      stream: async function* () {
+        yield { type: "text", delta: "Complete " } as LLMStreamChunk;
+        yield { type: "text", delta: "response" } as LLMStreamChunk;
+        yield { type: "usage", usage: { inputTokens: 10, outputTokens: 5 } } as LLMStreamChunk;
+        yield { type: "done", stopReason: "end_turn" } as LLMStreamChunk;
+      },
+    };
+
+    agent.setMockLLMAdapter(mockAdapter);
+
+    const response = agent.query("Hello");
+
+    // Consume stream first
+    const textChunks: string[] = [];
+    for await (const text of (await response).textStream) {
+      textChunks.push(text);
+    }
+
+    // Then await result
+    const result = await (await response).result;
+
+    expect(result.message).toContain("Complete response");
+    expect(textChunks.join("")).toBe("Complete response");
+  });
+
+  it("should handle streaming errors gracefully", async () => {
+    const agent = new StreamingTestAgent();
+    agent.setContext(mockCtx);
+
+    const mockAdapter: LLMAdapter = {
+      stream: async function* () {
+        throw new Error("Streaming failed");
+      },
+    };
+
+    agent.setMockLLMAdapter(mockAdapter);
+
+    const response = agent.query("Hello");
+
+    await expectAsync((await response).result).toBeRejectedWithError("Streaming failed");
+  });
+});