@beignet/core 0.0.2 → 0.0.3

package/src/server/server.ts

@@ -31,6 +31,7 @@ import type {
   HttpResponse,
   HttpResponseLike,
   ResolvedRoute,
+  RouteHook,
   ServerCaughtErrorHook,
   ServerHook,
   ServerUnhandledErrorMapper,
@@ -48,29 +49,65 @@ import {
  * 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;
+  /**
+   * Route-scoped hooks that run after group hooks and before the handler.
+   */
+  hooks?: Hooks;
   /**
    * Handler that implements the contract.
    */
-  handle: Handler<Ctx, ResolveContract<CLike>>;
+  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 are an organization helper only. `defineRoutes(...)` flattens
- * them before server registration.
+ * 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(...)`.
@@ -80,6 +117,10 @@ export type RouteGroup<
    * Human-readable group name.
    */
   name: string;
+  /**
+   * Hooks applied to every route in this group.
+   */
+  hooks?: readonly RouteHook<Ctx, object>[];
   /**
    * Route definitions in this group.
    */
@@ -87,24 +128,45 @@ export type RouteGroup<
 };
 
 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 [];
@@ -122,6 +184,22 @@ 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.
  */
@@ -129,7 +207,7 @@ 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
@@ -637,6 +715,7 @@ function buildHandler<
   contract: C,
   userHandler: Handler<Ctx, C>,
   hooks: ServerHook<Ctx, FinalPorts>[],
+  routeHooks: readonly RouteHook<unknown, object>[] = [],
   optionsOverrides?: {
     skipRoutePreparation?: boolean;
   },
@@ -1208,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 = {
@@ -1328,7 +1440,7 @@ 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
@@ -1382,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(
@@ -1412,6 +1525,7 @@ export async function createServer<
       contract,
       handler,
       hooks,
+      routeHooks,
     );
     registry.push({
       contract,
@@ -1444,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 {
@@ -1518,6 +1636,7 @@ export async function createServer<
       notFoundContract,
       async () => errorResponse(404, "NOT_FOUND", "Not found"),
       hooks,
+      [],
       { skipRoutePreparation: true },
     );
 
@@ -1549,6 +1668,15 @@ export async function createServer<
  * ]);
  * ```
  */
+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>[],
@@ -1557,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);
     }
@@ -1585,26 +1718,61 @@ export function contractsFromRoutes<
  * 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
  * ```ts
- * const todoRoutes = defineRouteGroup<AppContext>({
+ * const todoRoutes = defineRouteGroup<AppContext>()({
  *   name: "todos",
+ *   hooks: [auth.optional()],
  *   routes: [
  *     { 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,
   };
 }

package/src/testing/index.ts

@@ -196,6 +196,17 @@ export class SeedRunError extends Error {
   }
 }
 
+/**
+ * Reset one or more factory sequences to their configured starting values.
+ */
+export function resetFactories(
+  ...factories: readonly Pick<FactoryDef, "resetSequence">[]
+): void {
+  for (const factory of factories) {
+    factory.resetSequence();
+  }
+}
+
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }