@beignet/core 0.0.1 → 0.0.3

package/src/server/server.ts

@@ -31,6 +31,7 @@ import type {
   HttpResponse,
   HttpResponseLike,
   ResolvedRoute,
+  RouteHook,
   ServerCaughtErrorHook,
   ServerHook,
   ServerUnhandledErrorMapper,
@@ -42,44 +43,130 @@ import {
 } from "./providers";
 
 /**
- * Route definition
+ * Route registration for one contract.
+ *
+ * Route definitions connect a contract to the handler that implements it. Most
+ * apps keep these in `features/<feature>/routes.ts` and compose them with
+ * `defineRoutes(...)`.
  */
-export type RouteDef<Ctx, CLike extends ContractLike = ContractLike> = {
+export type RouteDef<
+  Ctx,
+  CLike extends ContractLike = ContractLike,
+  Hooks extends readonly RouteHook<Ctx, object>[] = readonly RouteHook<
+    Ctx,
+    object
+  >[],
+> = {
+  /**
+   * Contract builder or plain contract config for this route.
+   */
   contract: CLike;
-  handle: Handler<Ctx, ResolveContract<CLike>>;
+  /**
+   * Route-scoped hooks that run after group hooks and before the handler.
+   */
+  hooks?: Hooks;
+  /**
+   * Handler that implements the contract.
+   */
+  handle: Handler<Ctx & AddedCtxFromHooks<Hooks>, ResolveContract<CLike>>;
 };
 
+type AddedCtxFromHook<Hook> =
+  Hook extends RouteHook<infer _Ctx, infer AddedCtx> ? AddedCtx : unknown;
+
+type UnionToIntersection<Union> = (
+  Union extends unknown
+    ? (value: Union) => void
+    : never
+) extends (value: infer Intersection) => void
+  ? Intersection
+  : never;
+
+type AddedCtxFromHooks<Hooks extends readonly unknown[]> =
+  Hooks extends readonly []
+    ? unknown
+    : UnionToIntersection<AddedCtxFromHook<Hooks[number]>>;
+
+// biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at collection boundaries
+type AnyRouteDef = RouteDef<any, any>;
+
+// biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at collection boundaries
+type PlainRouteDef<Ctx> = RouteDef<Ctx, any, readonly []>;
+
+// biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at collection boundaries
+type AnyContractRouteDef<Ctx> = RouteDef<Ctx, any>;
+
 const ROUTE_GROUP_KIND = "beignet.route-group";
 
+/**
+ * Named collection of related route registrations.
+ *
+ * Route groups colocate feature routes and can apply scoped route hooks to
+ * every route in the group. `defineRoutes(...)` flattens them before server
+ * registration while preserving those hooks.
+ */
 export type RouteGroup<
   Ctx,
-  // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
-  Routes extends readonly RouteDef<Ctx, any>[] = readonly RouteDef<Ctx, any>[],
+  Routes extends readonly AnyRouteDef[] = readonly AnyRouteDef[],
 > = {
+  /**
+   * Internal marker used by `defineRoutes(...)`.
+   */
   kind: typeof ROUTE_GROUP_KIND;
+  /**
+   * Human-readable group name.
+   */
   name: string;
+  /**
+   * Hooks applied to every route in this group.
+   */
+  hooks?: readonly RouteHook<Ctx, object>[];
+  /**
+   * Route definitions in this group.
+   */
   routes: Routes;
 };
 
 type RouteInput<Ctx> =
-  // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
-  | RouteDef<Ctx, any>
-  // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
-  | RouteGroup<Ctx, readonly RouteDef<Ctx, any>[]>;
+  | AnyContractRouteDef<Ctx>
+  | AnyRouteDef
+  | RouteGroup<Ctx, readonly AnyRouteDef[]>;
+
+type ContextualRouteInput<Ctx> =
+  | PlainRouteDef<Ctx>
+  | RouteGroup<Ctx, readonly AnyRouteDef[]>;
+
+type RouteGroupBuilder<Ctx> = {
+  <
+    const GroupHooks extends readonly RouteHook<Ctx, object>[] = readonly [],
+    const R extends readonly PlainRouteDef<
+      Ctx & AddedCtxFromHooks<GroupHooks>
+    >[] = readonly PlainRouteDef<Ctx & AddedCtxFromHooks<GroupHooks>>[],
+  >(group: {
+    name: string;
+    hooks?: GroupHooks;
+    routes: R;
+  }): RouteGroup<Ctx, R>;
+  <
+    const GroupHooks extends readonly RouteHook<Ctx, object>[] = readonly [],
+    const R extends readonly AnyRouteDef[] = readonly AnyRouteDef[],
+  >(group: {
+    name: string;
+    hooks?: GroupHooks;
+    routes: R;
+  }): RouteGroup<Ctx, R>;
+};
 
 type RoutesFromInput<Input> =
-  // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
-  Input extends RouteGroup<any, infer Routes>
+  Input extends RouteGroup<infer _Ctx, infer Routes>
     ? Routes
-    : // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
-      Input extends RouteDef<any, any>
+    : Input extends AnyRouteDef
       ? readonly [Input]
       : readonly [];
 
 type FlattenRouteInputs<Inputs extends readonly unknown[]> =
   number extends Inputs["length"]
-    ? // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
-      readonly RouteDef<any, any>[]
+    ? readonly AnyRouteDef[]
     : Inputs extends readonly [infer First, ...infer Rest]
       ? readonly [...RoutesFromInput<First>, ...FlattenRouteInputs<Rest>]
       : readonly [];
@@ -97,11 +184,30 @@ type ContractsFromRouteList<
     : never;
 };
 
+/**
+ * Define one route registration with hook-aware handler typing.
+ *
+ * Direct route objects are still supported. Use this helper when route-scoped
+ * hooks enrich `ctx` for a single handler and you want TypeScript to infer the
+ * added fields.
+ */
+export function defineRoute<Ctx>() {
+  return <
+    CLike extends ContractLike,
+    const Hooks extends readonly RouteHook<Ctx, object>[] = readonly [],
+  >(
+    route: RouteDef<Ctx, CLike, Hooks>,
+  ): RouteDef<Ctx, CLike, Hooks> => route;
+}
+
+/**
+ * Options for creating a Beignet server instance.
+ */
 export type CreateServerOptions<
   Ctx,
   Ports extends AnyPorts,
   // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
-  Routes extends readonly RouteDef<Ctx, any>[] = readonly RouteDef<Ctx, any>[],
+  Routes extends readonly RouteDef<any, any>[] = readonly RouteDef<any, any>[],
   Providers extends readonly ServiceProvider<
     unknown,
     // biome-ignore lint/suspicious/noExplicitAny: provider config types are erased at this level
@@ -109,21 +215,53 @@ export type CreateServerOptions<
     AnyPorts
   >[] = readonly [],
 > = {
+  /**
+   * App-owned ports available to context creation, hooks, and handlers.
+   */
   ports: Ports;
+  /**
+   * Providers installed during server startup.
+   *
+   * Provider ports are merged into `ports` before request handling and are
+   * stopped in reverse setup order when `server.stop()` runs.
+   */
   providers?: Providers;
 
-  // config sources
+  /**
+   * Runtime env used by providers. Defaults to `process.env`.
+   */
   providerEnv?: Record<string, string | undefined>;
+  /**
+   * Provider config overrides keyed by provider name.
+   */
   providerConfig?: Record<string, unknown>;
 
+  /**
+   * Create request context after a route is matched.
+   *
+   * The `ports` argument includes app ports plus ports provided during server
+   * startup.
+   */
   createContext: (args: {
     req: HttpRequestLike;
     ports: Ports & ProvidedPortsOfList<Providers>;
     contract?: HttpContractConfig;
   }) => Ctx | Promise<Ctx>;
+  /**
+   * Server hooks that wrap every registered route.
+   */
   hooks?: ServerHook<Ctx, Ports & ProvidedPortsOfList<Providers>>[];
+  /**
+   * Route list to register up front.
+   */
   routes?: Routes;
+  /**
+   * Global caught-error observer.
+   */
   onCaughtError?: ServerCaughtErrorHook<Ctx>;
+  /**
+   * Global mapper for unexpected errors not handled by app error catalogs.
+   */
   mapUnhandledError?: ServerUnhandledErrorMapper<Ctx>;
 };
 
@@ -133,13 +271,31 @@ interface RouteBuilder<Ctx, C extends HttpContractConfig> {
   ) => (req: HttpRequestLike) => Promise<HttpResponse>;
 }
 
+/**
+ * Runtime server object returned by `createServer(...)`.
+ */
 export interface ServerInstance<Ctx, Ports extends AnyPorts = AnyPorts> {
+  /**
+   * Catch-all request handler for platform adapters.
+   */
   api: (req: HttpRequestLike) => Promise<HttpResponse>;
+  /**
+   * Register and build a single route handler imperatively.
+   */
   route: <CLike extends ContractLike>(
     contractLike: CLike,
   ) => RouteBuilder<Ctx, ResolveContract<CLike>>;
+  /**
+   * Contract configs registered through the `routes` option.
+   */
   contracts: readonly HttpContractConfig[];
+  /**
+   * Stop installed providers in reverse setup order.
+   */
   stop: () => Promise<void>;
+  /**
+   * Final app ports after provider setup.
+   */
   ports: Ports;
 }
 
@@ -559,6 +715,7 @@ function buildHandler<
   contract: C,
   userHandler: Handler<Ctx, C>,
   hooks: ServerHook<Ctx, FinalPorts>[],
+  routeHooks: readonly RouteHook<unknown, object>[] = [],
   optionsOverrides?: {
     skipRoutePreparation?: boolean;
   },
@@ -1130,6 +1287,39 @@ function buildHandler<
                 }
               }
 
+              if (!result) {
+                for (const hook of routeHooks) {
+                  try {
+                    const additions = await hook.resolve({
+                      req,
+                      ctx: currentCtx,
+                      contract,
+                      path,
+                      query,
+                      headers,
+                      body,
+                    });
+                    if (additions && typeof additions === "object") {
+                      currentCtx = {
+                        ...(currentCtx as object),
+                        ...additions,
+                      } as Ctx;
+                    }
+                  } catch (error) {
+                    result = await resolveErrorResult(
+                      error,
+                      currentCtx,
+                      pathValue,
+                      queryValue,
+                      headersValue,
+                      bodyValue,
+                      { owner: "framework" },
+                    );
+                    break;
+                  }
+                }
+              }
+
               if (!result) {
                 try {
                   result = {
@@ -1234,11 +1424,23 @@ function buildHandler<
   };
 }
 
+/**
+ * Create a Beignet server instance.
+ *
+ * The server owns route registration, provider setup/startup, request
+ * validation, hook execution, response validation, and framework error mapping.
+ * Use adapter packages such as `@beignet/next` to expose `server.api` to a
+ * specific runtime.
+ *
+ * @param options - Ports, providers, routes, hooks, context factory, and error
+ * mapping hooks for the server.
+ * @returns A started server instance with final ports and a catch-all handler.
+ */
 export async function createServer<
   Ctx,
   Ports extends AnyPorts,
   // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
-  Routes extends readonly RouteDef<Ctx, any>[] = readonly RouteDef<Ctx, any>[],
+  Routes extends readonly RouteDef<any, any>[] = readonly RouteDef<any, any>[],
   Providers extends readonly ServiceProvider<
     unknown,
     // biome-ignore lint/suspicious/noExplicitAny: provider config types are erased at this level
@@ -1292,6 +1494,7 @@ export async function createServer<
   const registerRoute = <C extends HttpContractConfig>(
     contract: C,
     handler: Handler<Ctx, C>,
+    routeHooks: readonly RouteHook<unknown, object>[] = [],
   ): void => {
     if (contract.body && !methodSupportsRequestBody(contract.method)) {
       throw new Error(
@@ -1322,6 +1525,7 @@ export async function createServer<
       contract,
       handler,
       hooks,
+      routeHooks,
     );
     registry.push({
       contract,
@@ -1354,7 +1558,11 @@ export async function createServer<
     try {
       for (const route of options.routes) {
         const contract = resolveContract(route.contract);
-        registerRoute(contract, route.handle);
+        registerRoute(
+          contract,
+          route.handle as Handler<Ctx, typeof contract>,
+          route.hooks as readonly RouteHook<unknown, object>[] | undefined,
+        );
       }
     } catch (error) {
       try {
@@ -1428,6 +1636,7 @@ export async function createServer<
       notFoundContract,
       async () => errorResponse(404, "NOT_FOUND", "Not found"),
       hooks,
+      [],
       { skipRoutePreparation: true },
     );
 
@@ -1447,14 +1656,27 @@ export async function createServer<
 }
 
 /**
- * Helper function to define routes with proper type inference.
- * Eliminates the need for type assertions when passing routes to createServer.
+ * Define and flatten route registrations with strong type inference.
+ *
+ * Pass route definitions and route groups here before `createServer(...)`.
+ * Group entries are flattened so downstream tooling receives one route list.
  *
  * @example
+ * ```ts
  * const routes = defineRoutes<AppContext>([
- *   { contract: myContract, handle: async ({ query }) => { ... } }
+ *   { contract: listPosts, handle: async ({ ctx }) => ctx.posts.list() },
  * ]);
+ * ```
  */
+export function defineRoutes<
+  Ctx,
+  const R extends
+    readonly ContextualRouteInput<Ctx>[] = readonly ContextualRouteInput<Ctx>[],
+>(routes: R): FlattenRouteInputs<R>;
+export function defineRoutes<
+  Ctx,
+  const R extends readonly RouteInput<Ctx>[] = readonly RouteInput<Ctx>[],
+>(routes: R): FlattenRouteInputs<R>;
 export function defineRoutes<
   Ctx,
   const R extends readonly RouteInput<Ctx>[] = readonly RouteInput<Ctx>[],
@@ -1463,7 +1685,12 @@ export function defineRoutes<
 
   for (const route of routes) {
     if (isRouteGroup(route)) {
-      flattened.push(...route.routes);
+      for (const groupRoute of route.routes) {
+        flattened.push({
+          ...groupRoute,
+          hooks: [...(route.hooks ?? []), ...(groupRoute.hooks ?? [])],
+        });
+      }
     } else {
       flattened.push(route);
     }
@@ -1473,8 +1700,10 @@ export function defineRoutes<
 }
 
 /**
- * Extract contract configs from a route list. Use this to drive OpenAPI from
- * the same route registration list that createServer receives.
+ * Extract contract configs from a route list.
+ *
+ * Use this to drive clients, OpenAPI, and docs from the same route list passed
+ * to `createServer(...)`.
  */
 export function contractsFromRoutes<
   // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
@@ -1486,27 +1715,64 @@ export function contractsFromRoutes<
 }
 
 /**
- * Helper function to group related route registrations.
+ * Define a named group of related route registrations.
  *
  * Route groups are flattened by defineRoutes, so createServer still receives
- * a regular route list while app code can keep feature route wiring colocated.
+ * a regular route list while app code can keep feature route wiring and scoped
+ * hooks colocated.
  *
  * @example
- * const todoRoutes = defineRouteGroup<AppContext>({
+ * ```ts
+ * const todoRoutes = defineRouteGroup<AppContext>()({
  *   name: "todos",
+ *   hooks: [auth.optional()],
  *   routes: [
- *     { contract: listTodos, handle: async ({ ctx }) => { ... } }
+ *     { contract: listTodos, handle: async ({ ctx }) => ctx.todos.list() },
  *   ]
  * });
+ * ```
  */
+export function defineRouteGroup<Ctx>(): RouteGroupBuilder<Ctx>;
 export function defineRouteGroup<
   Ctx,
   // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
   const R extends readonly RouteDef<Ctx, any>[] = readonly RouteDef<Ctx, any>[],
->(group: { name: string; routes: R }): RouteGroup<Ctx, R> {
+>(group: {
+  name: string;
+  hooks?: readonly RouteHook<Ctx, object>[];
+  routes: R;
+}): RouteGroup<Ctx, R>;
+export function defineRouteGroup<
+  Ctx,
+  // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
+  const R extends readonly RouteDef<any, any>[] = readonly RouteDef<any, any>[],
+>(group?: {
+  name: string;
+  hooks?: readonly RouteHook<Ctx, object>[];
+  routes: R;
+}): RouteGroup<Ctx, R> | RouteGroupBuilder<Ctx> {
+  const createGroup = <
+    const GroupHooks extends readonly RouteHook<Ctx, object>[] = readonly [],
+    const GroupRoutes extends readonly AnyRouteDef[] = readonly AnyRouteDef[],
+  >(input: {
+    name: string;
+    hooks?: GroupHooks;
+    routes: GroupRoutes;
+  }): RouteGroup<Ctx, GroupRoutes> => ({
+    kind: ROUTE_GROUP_KIND,
+    name: input.name,
+    hooks: input.hooks,
+    routes: input.routes,
+  });
+
+  if (!group) {
+    return createGroup;
+  }
+
   return {
     kind: ROUTE_GROUP_KIND,
     name: group.name,
+    hooks: group.hooks,
     routes: group.routes,
   };
 }