@fragno-dev/core 0.0.1

package/src/api/fragment.ts

@@ -0,0 +1,277 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import { type FragnoRouteConfig, type HTTPMethod } from "./api";
+import { FragnoApiError } from "./error";
+import { getMountRoute } from "./internal/route";
+import { addRoute, createRouter, findRoute } from "rou3";
+import { RequestInputContext } from "./request-input-context";
+import type { ExtractPathParams } from "./internal/path";
+import { RequestOutputContext } from "./request-output-context";
+import {
+  type EmptyObject,
+  type AnyFragnoRouteConfig,
+  type AnyRouteOrFactory,
+  type FlattenRouteFactories,
+  resolveRouteFactories,
+} from "./route";
+import {
+  RequestMiddlewareInputContext,
+  RequestMiddlewareOutputContext,
+  type FragnoMiddlewareCallback,
+} from "./request-middleware";
+
+export interface FragnoPublicConfig {
+  mountRoute?: string;
+}
+
+export interface FragnoPublicClientConfig {
+  mountRoute?: string;
+  baseUrl?: string;
+}
+
+export interface FragnoInstantiatedFragment<
+  TRoutes extends readonly AnyFragnoRouteConfig[] = [],
+  TDeps = EmptyObject,
+  TServices extends Record<string, unknown> = Record<string, unknown>,
+> {
+  config: FragnoFragmentSharedConfig<TRoutes>;
+  deps: TDeps;
+  services: TServices;
+  handler: (req: Request) => Promise<Response>;
+  mountRoute: string;
+  withMiddleware: (
+    handler: FragnoMiddlewareCallback<TRoutes, TDeps, TServices>,
+  ) => FragnoInstantiatedFragment<TRoutes, TDeps, TServices>;
+}
+
+export interface FragnoFragmentSharedConfig<
+  TRoutes extends readonly FragnoRouteConfig<
+    HTTPMethod,
+    string,
+    StandardSchemaV1 | undefined,
+    StandardSchemaV1 | undefined,
+    string,
+    string
+  >[],
+> {
+  name: string;
+  routes: TRoutes;
+}
+
+export type AnyFragnoFragmentSharedConfig = FragnoFragmentSharedConfig<
+  readonly AnyFragnoRouteConfig[]
+>;
+
+interface FragmentDefinition<
+  TConfig,
+  TDeps = EmptyObject,
+  TServices extends Record<string, unknown> = EmptyObject,
+> {
+  name: string;
+  dependencies?: (config: TConfig) => TDeps;
+  services?: (config: TConfig, deps: TDeps) => TServices;
+}
+
+export class FragmentBuilder<
+  TConfig,
+  TDeps = EmptyObject,
+  TServices extends Record<string, unknown> = EmptyObject,
+> {
+  #definition: FragmentDefinition<TConfig, TDeps, TServices>;
+
+  constructor(definition: FragmentDefinition<TConfig, TDeps, TServices>) {
+    this.#definition = definition;
+  }
+
+  get definition() {
+    return this.#definition;
+  }
+
+  withDependencies<TNewDeps>(
+    fn: (config: TConfig) => TNewDeps,
+  ): FragmentBuilder<TConfig, TNewDeps, TServices> {
+    return new FragmentBuilder<TConfig, TNewDeps, TServices>({
+      ...this.#definition,
+      dependencies: fn,
+    } as FragmentDefinition<TConfig, TNewDeps, TServices>);
+  }
+
+  withServices<TNewServices extends Record<string, unknown>>(
+    fn: (config: TConfig, deps: TDeps) => TNewServices,
+  ): FragmentBuilder<TConfig, TDeps, TNewServices> {
+    return new FragmentBuilder<TConfig, TDeps, TNewServices>({
+      ...this.#definition,
+      services: fn,
+    } as FragmentDefinition<TConfig, TDeps, TNewServices>);
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export function defineFragment<TConfig = {}>(name: string): FragmentBuilder<TConfig> {
+  return new FragmentBuilder({
+    name,
+  });
+}
+
+export function createFragment<
+  TConfig,
+  TDeps,
+  TServices extends Record<string, unknown>,
+  const TRoutesOrFactories extends readonly AnyRouteOrFactory[],
+>(
+  fragmentDefinition: FragmentBuilder<TConfig, TDeps, TServices>,
+  config: TConfig,
+  routesOrFactories: TRoutesOrFactories,
+  fragnoConfig: FragnoPublicConfig = {},
+): FragnoInstantiatedFragment<FlattenRouteFactories<TRoutesOrFactories>, TDeps, TServices> {
+  const definition = fragmentDefinition.definition;
+
+  const dependencies = definition.dependencies ? definition.dependencies(config) : ({} as TDeps);
+  const services = definition.services
+    ? definition.services(config, dependencies)
+    : ({} as TServices);
+
+  const context = { config, deps: dependencies, services };
+  const routes = resolveRouteFactories(context, routesOrFactories);
+
+  const mountRoute = getMountRoute({
+    name: definition.name,
+    mountRoute: fragnoConfig.mountRoute,
+  });
+
+  const router =
+    createRouter<
+      FragnoRouteConfig<
+        HTTPMethod,
+        string,
+        StandardSchemaV1 | undefined,
+        StandardSchemaV1 | undefined,
+        string,
+        string
+      >
+    >();
+
+  let middlewareHandler:
+    | FragnoMiddlewareCallback<FlattenRouteFactories<TRoutesOrFactories>, TDeps, TServices>
+    | undefined;
+
+  for (const routeConfig of routes) {
+    addRoute(router, routeConfig.method.toUpperCase(), routeConfig.path, routeConfig);
+  }
+
+  const fragment: FragnoInstantiatedFragment<
+    FlattenRouteFactories<TRoutesOrFactories>,
+    TDeps,
+    TServices
+  > = {
+    mountRoute,
+    config: {
+      name: definition.name,
+      routes,
+    },
+    services,
+    deps: dependencies,
+    withMiddleware: (handler) => {
+      if (middlewareHandler) {
+        throw new Error("Middleware already set");
+      }
+
+      middlewareHandler = handler;
+
+      return fragment;
+    },
+    handler: async (req: Request) => {
+      const url = new URL(req.url);
+      const pathname = url.pathname;
+
+      const matchRoute = pathname.startsWith(mountRoute) ? pathname.slice(mountRoute.length) : null;
+
+      if (matchRoute === null) {
+        return Response.json(
+          {
+            error:
+              `Fragno: Route for '${definition.name}' not found. Is the fragment mounted on the right route? ` +
+              `Expecting: '${mountRoute}'.`,
+            code: "ROUTE_NOT_FOUND",
+          },
+          { status: 404 },
+        );
+      }
+
+      const route = findRoute(router, req.method, matchRoute);
+
+      if (!route) {
+        return Response.json(
+          { error: `Fragno: Route for '${definition.name}' not found`, code: "ROUTE_NOT_FOUND" },
+          { status: 404 },
+        );
+      }
+
+      const { handler, inputSchema, outputSchema, path } = route.data;
+
+      const outputContext = new RequestOutputContext(outputSchema);
+
+      if (middlewareHandler) {
+        const middlewareInputContext = new RequestMiddlewareInputContext(routes, {
+          method: req.method as HTTPMethod,
+          path,
+          pathParams: route.params,
+          searchParams: new URL(req.url).searchParams,
+          body: req.body,
+          request: req,
+        });
+
+        const middlewareOutputContext = new RequestMiddlewareOutputContext(dependencies, services);
+
+        try {
+          const middlewareResult = await middlewareHandler(
+            middlewareInputContext,
+            middlewareOutputContext,
+          );
+          if (middlewareResult !== undefined) {
+            return middlewareResult;
+          }
+        } catch (error) {
+          console.error("Error in middleware", error);
+
+          if (error instanceof FragnoApiError) {
+            // TODO: If a validation error occurs in middleware (when calling `await input.valid()`)
+            //       the processing is short-circuited and a potential `catch` block around the call
+            //       to `input.valid()` in the actual handler will not be executed.
+            return error.toResponse();
+          }
+
+          return Response.json(
+            { error: "Internal server error", code: "INTERNAL_SERVER_ERROR" },
+            { status: 500 },
+          );
+        }
+      }
+
+      const inputContext = await RequestInputContext.fromRequest({
+        request: req,
+        method: req.method,
+        path,
+        pathParams: (route.params ?? {}) as ExtractPathParams<typeof path>,
+        inputSchema,
+      });
+
+      try {
+        const result = await handler(inputContext, outputContext);
+        return result;
+      } catch (error) {
+        console.error("Error in handler", error);
+
+        if (error instanceof FragnoApiError) {
+          return error.toResponse();
+        }
+
+        return Response.json(
+          { error: "Internal server error", code: "INTERNAL_SERVER_ERROR" },
+          { status: 500 },
+        );
+      }
+    },
+  };
+
+  return fragment;
+}

package/src/api/internal/path-runtime.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, test } from "vitest";
+import { buildPath, extractPathParams, matchPathParams } from "./path";
+
+describe("extractPathParams (runtime names)", () => {
+  test("no params", () => {
+    expect(extractPathParams("/static/assets")).toEqual([]);
+    expect(extractPathParams("/")).toEqual([]);
+    expect(extractPathParams("")).toEqual([]);
+  });
+
+  test("named param", () => {
+    expect(extractPathParams("/users/:id")).toEqual(["id"]);
+    expect(extractPathParams(":id")).toEqual(["id"]);
+    expect(extractPathParams("/:id")).toEqual(["id"]);
+  });
+
+  test("empty name param segment is allowed", () => {
+    expect(extractPathParams("/:")).toEqual([""]);
+    expect(extractPathParams("/:/x")).toEqual([""]);
+  });
+
+  test("duplicate identifiers are preserved in order", () => {
+    expect(extractPathParams("/path/:/x/:/")).toEqual(["", ""]);
+    expect(extractPathParams("/path/:var/x/:var")).toEqual(["var", "var"]);
+  });
+
+  test("multiple named params", () => {
+    expect(extractPathParams("/users/:id/posts/:postId")).toEqual(["id", "postId"]);
+  });
+
+  test("wildcards", () => {
+    expect(extractPathParams("/path/foo/**")).toEqual(["**"]);
+    expect(extractPathParams("/path/foo/**:name")).toEqual(["name"]);
+  });
+
+  test("mixed complex", () => {
+    expect(extractPathParams("/api/:version/users/:userId/posts/:postId/**:remaining")).toEqual([
+      "version",
+      "userId",
+      "postId",
+      "remaining",
+    ]);
+  });
+
+  test("consecutive slashes are ignored in names extraction", () => {
+    expect(extractPathParams("//path//:name")).toEqual(["name"]);
+  });
+});
+
+describe("matchPathParams (runtime extraction)", () => {
+  test("literal match with named param", () => {
+    expect(matchPathParams("/users/:id", "/users/123")).toEqual({ id: "123" });
+  });
+
+  test("mismatch returns empty object", () => {
+    expect(matchPathParams("/users/:id", "/posts/123")).toEqual({});
+  });
+
+  test("named wildcard captures remainder", () => {
+    expect(matchPathParams("/files/**:rest", "/files/a/b/c")).toEqual({ rest: "a/b/c" });
+    expect(matchPathParams("/files/**:rest", "/files")).toEqual({ rest: "" });
+  });
+
+  test("anonymous wildcard captures remainder under ** key", () => {
+    expect(matchPathParams("/files/**", "/files/a/b")).toEqual({ "**": "a/b" });
+    expect(matchPathParams("/files/**", "/files")).toEqual({ "**": "" });
+  });
+
+  test("mixed named segment and wildcard remainder", () => {
+    expect(matchPathParams("/api/:version/**:rest", "/api/v1/users/1")).toEqual({
+      version: "v1",
+      rest: "users/1",
+    });
+  });
+
+  test("trailing slashes are ignored", () => {
+    expect(matchPathParams("/users/:id", "/users/123/")).toEqual({ id: "123" });
+  });
+
+  test("pattern longer than path fills empty strings for remaining params", () => {
+    // Remaining ":id" becomes empty string
+    expect(matchPathParams("/users/:id", "/users")).toEqual({ id: "" });
+    // Remaining "**" becomes empty string
+    expect(matchPathParams("/files/**", "/files")).toEqual({ "**": "" });
+  });
+});
+
+describe("buildPath (runtime building)", () => {
+  test("builds literal match with named param", () => {
+    expect(buildPath("/users/:id", { id: "123" })).toEqual("/users/123");
+  });
+
+  test("encodes named params", () => {
+    expect(buildPath("/q/:term", { term: "a b" })).toEqual("/q/a%20b");
+    expect(buildPath("/:name", { name: "ä" })).toEqual("/%C3%A4");
+  });
+
+  test("builds with named wildcard remainder", () => {
+    expect(buildPath("/files/**:rest", { rest: "a/b/c" })).toEqual("/files/a/b/c");
+  });
+
+  test("builds with anonymous wildcard remainder", () => {
+    expect(buildPath("/files/**", { "**": "a/b" })).toEqual("/files/a/b");
+  });
+
+  test("preserves extra slashes from pattern", () => {
+    expect(buildPath("//path//:name//", { name: "x" })).toEqual("//path//x//");
+  });
+
+  test("throws on missing named param", () => {
+    // @ts-expect-error - intentionally passing missing param to test runtime error
+    expect(() => buildPath("/users/:id", {})).toThrowError(/Missing value/);
+  });
+
+  test("throws on missing wildcard values", () => {
+    // @ts-expect-error - intentionally passing missing param to test runtime error
+    expect(() => buildPath("/files/**", {})).toThrowError(/Missing value/);
+    // @ts-expect-error - intentionally passing missing param to test runtime error
+    expect(() => buildPath("/files/**:rest", {})).toThrowError(/Missing value/);
+  });
+});