@fragno-dev/core 0.0.1

package/src/api/request-output-context.ts

@@ -0,0 +1,175 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { ContentlessStatusCode, StatusCode } from "../http/http-status";
+import { ResponseStream } from "./internal/response-stream";
+import type { InferOrUnknown } from "../util/types-util";
+
+export type ResponseData = string | ArrayBuffer | ReadableStream | Uint8Array<ArrayBuffer>;
+
+interface ResponseInit<T extends StatusCode = StatusCode> {
+  headers?: HeadersInit;
+  status?: T;
+  statusText?: string;
+}
+
+/**
+ * Utility function to merge headers from multiple sources.
+ * Later headers override earlier ones.
+ */
+function mergeHeaders(...headerSources: (HeadersInit | undefined)[]): HeadersInit | undefined {
+  const mergedHeaders = new Headers();
+
+  for (const headerSource of headerSources) {
+    if (!headerSource) continue;
+
+    if (headerSource instanceof Headers) {
+      for (const [key, value] of headerSource.entries()) {
+        mergedHeaders.set(key, value);
+      }
+    } else if (Array.isArray(headerSource)) {
+      for (const [key, value] of headerSource) {
+        mergedHeaders.set(key, value);
+      }
+    } else {
+      for (const [key, value] of Object.entries(headerSource)) {
+        mergedHeaders.set(key, value);
+      }
+    }
+  }
+
+  return mergedHeaders;
+}
+
+export abstract class OutputContext<const TOutput, const TErrorCode extends string> {
+  /**
+   * Creates an error response.
+   *
+   * Shortcut for `throw new FragnoApiError(...)`
+   */
+  error(
+    { message, code }: { message: string; code: TErrorCode },
+    initOrStatus?: ResponseInit | StatusCode,
+    headers?: HeadersInit,
+  ): Response {
+    if (typeof initOrStatus === "undefined") {
+      return Response.json({ error: message, code }, { status: 500, headers });
+    }
+
+    if (typeof initOrStatus === "number") {
+      return Response.json({ error: message, code }, { status: initOrStatus, headers });
+    }
+
+    const mergedHeaders = mergeHeaders(initOrStatus.headers, headers);
+    return Response.json(
+      { error: message, code },
+      { status: initOrStatus.status, headers: mergedHeaders },
+    );
+  }
+
+  empty(
+    initOrStatus?: ResponseInit<ContentlessStatusCode> | ContentlessStatusCode,
+    headers?: HeadersInit,
+  ): Response {
+    const defaultHeaders = {};
+
+    if (typeof initOrStatus === "undefined") {
+      const mergedHeaders = mergeHeaders(defaultHeaders, headers);
+      return Response.json(null, {
+        status: 201,
+        headers: mergedHeaders,
+      });
+    }
+
+    if (typeof initOrStatus === "number") {
+      const mergedHeaders = mergeHeaders(defaultHeaders, headers);
+      return Response.json(null, {
+        status: initOrStatus,
+        headers: mergedHeaders,
+      });
+    }
+
+    const mergedHeaders = mergeHeaders(defaultHeaders, initOrStatus.headers, headers);
+    return Response.json(null, {
+      status: initOrStatus.status,
+      headers: mergedHeaders,
+    });
+  }
+
+  json(object: TOutput, initOrStatus?: ResponseInit | StatusCode, headers?: HeadersInit): Response {
+    if (typeof initOrStatus === "undefined") {
+      return Response.json(object, {
+        status: 200,
+        headers,
+      });
+    }
+
+    if (typeof initOrStatus === "number") {
+      return Response.json(object, {
+        status: initOrStatus,
+        headers,
+      });
+    }
+
+    const mergedHeaders = mergeHeaders(initOrStatus.headers, headers);
+    return Response.json(object, {
+      status: initOrStatus.status,
+      headers: mergedHeaders,
+    });
+  }
+
+  jsonStream = (
+    cb: (stream: ResponseStream<TOutput>) => void | Promise<void>,
+    {
+      onError,
+      headers,
+    }: {
+      onError?: (error: Error, stream: ResponseStream<TOutput>) => void | Promise<void>;
+      headers?: HeadersInit;
+    } = {},
+  ): Response => {
+    // Note: this is intentionally an arrow function (=>) to keep `this` context.
+    const defaultHeaders = {
+      "content-type": "application/x-ndjson; charset=utf-8",
+      "transfer-encoding": "chunked",
+      "cache-control": "no-cache",
+    };
+
+    const { readable, writable } = new TransformStream();
+    const stream = new ResponseStream(writable, readable);
+
+    (async () => {
+      try {
+        await cb(stream);
+      } catch (e) {
+        if (e === undefined) {
+          // If reading is canceled without a reason value (e.g. by StreamingApi)
+          // then the .pipeTo() promise will reject with undefined.
+          // In this case, do nothing because the stream is already closed.
+        } else if (e instanceof Error && onError) {
+          await onError(e, stream);
+        } else {
+          console.error(e);
+        }
+      } finally {
+        stream.close();
+      }
+    })();
+
+    return new Response(stream.responseReadable, {
+      status: 200,
+      headers: mergeHeaders(defaultHeaders, headers),
+    });
+  };
+}
+
+export class RequestOutputContext<
+  const TOutputSchema extends StandardSchemaV1 | undefined = undefined,
+  const TErrorCode extends string = string,
+> extends OutputContext<InferOrUnknown<TOutputSchema>, TErrorCode> {
+  // eslint-disable-next-line no-unused-private-class-members
+  #outputSchema?: TOutputSchema;
+
+  constructor(outputSchema?: TOutputSchema) {
+    super();
+    this.#outputSchema = outputSchema;
+  }
+}

package/src/api/route.test.ts

@@ -0,0 +1,176 @@
+import { test, expect, expectTypeOf, describe } from "vitest";
+import { defineRoute } from "./route";
+import { z } from "zod";
+
+describe("defineRoute", () => {
+  test("defineRoute no inputSchema", () => {
+    const route = defineRoute({
+      method: "GET",
+      path: "/thing/**:path",
+      handler: async ({ path, pathParams }, { empty }) => {
+        expect(path).toEqual("/thing/**:path");
+        expectTypeOf<typeof path>().toEqualTypeOf<"/thing/**:path">();
+
+        expect(pathParams).toEqual({ path: "test" });
+        expectTypeOf<typeof pathParams>().toEqualTypeOf<{ path: string }>();
+        return empty();
+      },
+    });
+
+    expect(route.method).toBe("GET");
+    expect(route.path).toBe("/thing/**:path");
+    expect(route.handler).toBeDefined();
+  });
+
+  test("defineRoute with inputSchema", () => {
+    const route = defineRoute({
+      method: "GET" as const,
+      path: "/thing/**:path" as const,
+      inputSchema: z.object({
+        path: z.string(),
+      }),
+      handler: async ({ path, pathParams, input }, { empty }) => {
+        expect(path).toEqual("/thing/**:path");
+        expectTypeOf<typeof path>().toEqualTypeOf<"/thing/**:path">();
+
+        expect(pathParams).toEqual({ path: "test" });
+        expectTypeOf<typeof pathParams>().toEqualTypeOf<{ path: string }>();
+
+        expect(input).toBeTruthy();
+        if (input) {
+          expectTypeOf<typeof input.schema>().toEqualTypeOf<z.ZodObject<{ path: z.ZodString }>>();
+          expectTypeOf<typeof input.valid>().toEqualTypeOf<() => Promise<{ path: string }>>();
+
+          const _valid = await input.valid();
+          expectTypeOf<typeof _valid>().toEqualTypeOf<{ path: string }>();
+        }
+        return empty();
+      },
+    });
+
+    expect(route.method).toBe("GET");
+    expect(route.path).toBe("/thing/**:path");
+    expect(route.inputSchema).toBeDefined();
+    expect(route.handler).toBeDefined();
+  });
+
+  test("HTTPMethod DELETE without inputSchema or outputSchema", () => {
+    const route = defineRoute({
+      method: "DELETE",
+      path: "/thing",
+      handler: async ({ input }, { empty, json }) => {
+        // FIXME: Would be nicer if input was not on the object at all
+        expect(input).toBeUndefined();
+        expectTypeOf<typeof input>().toEqualTypeOf<undefined>();
+
+        // FIXME: Would be nicer if parameter of json was never, or not have json as field at all.
+        expect(json).toBeDefined();
+        expectTypeOf<Parameters<typeof json>[0]>().toEqualTypeOf<unknown>();
+
+        return empty();
+      },
+    });
+
+    expect(route.method).toBe("DELETE");
+    expect(route.path).toBe("/thing");
+    expect(route.handler).toBeDefined();
+  });
+
+  test("defineRoute with outputSchema", () => {
+    const route = defineRoute({
+      method: "GET",
+      path: "/users",
+      outputSchema: z.array(z.object({ id: z.number(), name: z.string() })),
+      handler: async (_ctx, { json }) => {
+        return json([{ id: 1, name: "John" }]);
+      },
+    });
+
+    expect(route.method).toBe("GET");
+    expect(route.path).toBe("/users");
+    expect(route.outputSchema).toBeDefined();
+    expect(route.handler).toBeDefined();
+  });
+
+  test("defineRoute with both inputSchema and outputSchema", () => {
+    const route = defineRoute({
+      method: "POST",
+      path: "/users",
+      inputSchema: z.object({ name: z.string(), email: z.string() }),
+      outputSchema: z.object({ id: z.number(), name: z.string(), email: z.string() }),
+      handler: async ({ input }, { json }) => {
+        expect(input).toBeTruthy();
+        if (input) {
+          const data = await input.valid();
+          return json({ id: 1, name: data.name, email: data.email });
+        }
+        return json({ id: 1, name: "", email: "" });
+      },
+    });
+
+    expect(route.method).toBe("POST");
+    expect(route.path).toBe("/users");
+    expect(route.inputSchema).toBeDefined();
+    expect(route.outputSchema).toBeDefined();
+    expect(route.handler).toBeDefined();
+  });
+
+  test("defineRoute with path parameters", () => {
+    const route = defineRoute({
+      method: "GET",
+      path: "/users/:id",
+      outputSchema: z.object({ id: z.number(), name: z.string() }),
+      handler: async ({ pathParams }, { json }) => {
+        expectTypeOf<typeof pathParams>().toEqualTypeOf<{ id: string }>();
+        return json({ id: Number(pathParams.id), name: "John" });
+      },
+    });
+
+    expect(route.method).toBe("GET");
+    expect(route.path).toBe("/users/:id");
+    expect(route.outputSchema).toBeDefined();
+    expect(route.handler).toBeDefined();
+  });
+
+  test("defineRoute with multiple path parameters", () => {
+    const route = defineRoute({
+      method: "GET",
+      path: "/organizations/:orgId/users/:userId",
+      outputSchema: z.object({ orgId: z.number(), userId: z.number() }),
+      handler: async ({ pathParams }, { json }) => {
+        expectTypeOf<typeof pathParams>().toEqualTypeOf<{ orgId: string; userId: string }>();
+        return json({ orgId: Number(pathParams.orgId), userId: Number(pathParams.userId) });
+      },
+    });
+
+    expect(route.method).toBe("GET");
+    expect(route.path).toBe("/organizations/:orgId/users/:userId");
+    expect(route.outputSchema).toBeDefined();
+    expect(route.handler).toBeDefined();
+  });
+
+  test("defineRoute returns the same config object", () => {
+    const config = {
+      method: "GET" as const,
+      path: "/test" as const,
+      handler: async (_ctx: unknown, { empty }: { empty: () => Response }) => empty(),
+    };
+
+    const route = defineRoute(config);
+    expect(route).toBe(config);
+  });
+
+  test("defineRoute with ValidPath type checking", () => {
+    // Valid path
+    const validRoute = defineRoute({
+      method: "GET",
+      path: "/api/users",
+      handler: async (_ctx, { empty }) => empty(),
+    });
+
+    expectTypeOf(validRoute.path).toEqualTypeOf<"/api/users">();
+
+    // TODO: Once ValidPath is integrated with defineRoute, add tests for invalid paths
+    // Currently defineRoute doesn't enforce ValidPath constraints
+  });
+});

package/src/api/route.ts

@@ -0,0 +1,152 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { FragnoRouteConfig, HTTPMethod } from "./api";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyFragnoRouteConfig = FragnoRouteConfig<HTTPMethod, string, any, any, any, any>;
+
+export interface RouteFactoryContext<TConfig, TDeps, TServices> {
+  config: TConfig;
+  deps: TDeps;
+  services: TServices;
+}
+
+export type RouteFactory<
+  TConfig,
+  TDeps,
+  TServices,
+  TRoutes extends readonly FragnoRouteConfig<
+    HTTPMethod,
+    string,
+    StandardSchemaV1 | undefined,
+    StandardSchemaV1 | undefined,
+    string,
+    string
+  >[],
+> = (context: RouteFactoryContext<TConfig, TDeps, TServices>) => TRoutes;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyRouteOrFactory = AnyFragnoRouteConfig | RouteFactory<any, any, any, any>;
+
+export type FlattenRouteFactories<T extends readonly AnyRouteOrFactory[]> = T extends readonly [
+  infer First,
+  ...infer Rest extends readonly AnyRouteOrFactory[],
+]
+  ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    First extends RouteFactory<any, any, any, infer TRoutes>
+    ? [...TRoutes, ...FlattenRouteFactories<Rest>]
+    : [First, ...FlattenRouteFactories<Rest>]
+  : [];
+
+// Helper to resolve route factories into routes
+export function resolveRouteFactories<
+  TConfig,
+  TDeps,
+  TServices,
+  const TRoutesOrFactories extends readonly AnyRouteOrFactory[],
+>(
+  context: RouteFactoryContext<TConfig, TDeps, TServices>,
+  routesOrFactories: TRoutesOrFactories,
+): FlattenRouteFactories<TRoutesOrFactories> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const routes: any[] = [];
+
+  for (const item of routesOrFactories) {
+    if (typeof item === "function") {
+      // It's a route factory
+      const factoryRoutes = item(context);
+      routes.push(...factoryRoutes);
+    } else {
+      // It's a direct route
+      routes.push(item);
+    }
+  }
+
+  return routes as FlattenRouteFactories<TRoutesOrFactories>;
+}
+
+// TODO(Wilco): Do these overloads actually do anything?
+// TODO(Wilco): ValidPath<T> should be added back in here.
+
+// Overload for routes without inputSchema
+export function defineRoute<
+  const TMethod extends HTTPMethod,
+  const TPath extends string,
+  const TOutputSchema extends StandardSchemaV1 | undefined,
+  const TErrorCode extends string = string,
+  const TQueryParameters extends string = string,
+>(
+  config: FragnoRouteConfig<
+    TMethod,
+    TPath,
+    undefined,
+    TOutputSchema,
+    TErrorCode,
+    TQueryParameters
+  > & { inputSchema?: undefined },
+): FragnoRouteConfig<TMethod, TPath, undefined, TOutputSchema, TErrorCode, TQueryParameters>;
+
+// Overload for routes with inputSchema
+export function defineRoute<
+  const TMethod extends HTTPMethod,
+  const TPath extends string,
+  const TInputSchema extends StandardSchemaV1,
+  const TOutputSchema extends StandardSchemaV1 | undefined,
+  const TErrorCode extends string = string,
+  const TQueryParameters extends string = string,
+>(
+  config: FragnoRouteConfig<
+    TMethod,
+    TPath,
+    TInputSchema,
+    TOutputSchema,
+    TErrorCode,
+    TQueryParameters
+  > & { inputSchema: TInputSchema },
+): FragnoRouteConfig<TMethod, TPath, TInputSchema, TOutputSchema, TErrorCode, TQueryParameters>;
+
+// implementation
+export function defineRoute<
+  const TMethod extends HTTPMethod,
+  const TPath extends string,
+  const TInputSchema extends StandardSchemaV1 | undefined,
+  const TOutputSchema extends StandardSchemaV1 | undefined,
+  const TErrorCode extends string = string,
+  const TQueryParameters extends string = string,
+>(
+  config: FragnoRouteConfig<
+    TMethod,
+    TPath,
+    TInputSchema,
+    TOutputSchema,
+    TErrorCode,
+    TQueryParameters
+  >,
+): FragnoRouteConfig<TMethod, TPath, TInputSchema, TOutputSchema, TErrorCode, TQueryParameters> {
+  return config;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export type EmptyObject = {}; //Record<string, never>;
+
+export function defineRoutes<
+  TConfig = EmptyObject,
+  TDeps = EmptyObject,
+  TServices = EmptyObject,
+>() {
+  return {
+    create: <
+      const TRoutes extends readonly FragnoRouteConfig<
+        HTTPMethod,
+        string,
+        StandardSchemaV1 | undefined,
+        StandardSchemaV1 | undefined,
+        string,
+        string
+      >[],
+    >(
+      fn: (context: RouteFactoryContext<TConfig, TDeps, TServices>) => TRoutes,
+    ): RouteFactory<TConfig, TDeps, TServices, TRoutes> => {
+      return fn;
+    },
+  };
+}