@ts-kizuna/fastify 1.49.5

package/LICENSE.MD

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Sondre Ørland
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# @ts-kizuna/fastify
+
+`@ts-kizuna/fastify` connects a ts-kizuna API to a Fastify application.
+
+**Requires Fastify >= 5.**
+
+## Installation
+
+```sh
+pnpm add @ts-kizuna/fastify fastify
+```
+
+## Usage
+
+```ts
+import Fastify from 'fastify';
+import { KizunaServer } from '@ts-kizuna/fastify';
+import { contract } from './contract';
+import { router } from './router';
+
+const server = new KizunaServer(contract);
+
+const api = server.api({
+    router,
+});
+
+const app = Fastify();
+await api.mount(app);
+
+app.listen({
+    port: 3000,
+});
+```
+
+## Documentation
+
+[Fastify adapter](https://ts-kizuna.com/docs/adapters/fastify)

package/dist/index.cjs

@@ -0,0 +1,187 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+let fastify_plugin = require("fastify-plugin");
+fastify_plugin = __toESM(fastify_plugin, 1);
+let node_stream = require("node:stream");
+let _ts_kizuna_core_adapter = require("@ts-kizuna/core/adapter");
+//#region src/server.ts
+/**
+* Write a web `Response` to a Fastify reply. Plugins answer in web terms to stay
+* adapter-agnostic, so the translation belongs here.
+*/
+const writeWebResponse = async (response, reply) => {
+	if (!(response instanceof globalThis.Response)) return;
+	reply.hijack();
+	reply.raw.statusCode = response.status;
+	response.headers.forEach((value, name) => reply.raw.setHeader(name, value));
+	if (!response.body) {
+		reply.raw.end();
+		return;
+	}
+	node_stream.Readable.fromWeb(response.body).pipe(reply.raw);
+};
+const adapter = (0, _ts_kizuna_core_adapter.createAdapter)({
+	buildHandlerContext: (adapterRequest, { reply }) => ({
+		request: adapterRequest.request,
+		reply
+	}),
+	respond: (result, { reply, formatError }) => {
+		if (result.kind === "handler-error") throw result.error;
+		if (result.kind === "raw-response") {
+			writeWebResponse(result.response, reply);
+			return;
+		}
+		const rendered = (0, _ts_kizuna_core_adapter.renderJsonResult)(result, formatError, reply.request);
+		for (const [key, value] of Object.entries(rendered.headers)) reply.header(key, value);
+		if (rendered.body === void 0) reply.status(rendered.status).send();
+		else if (rendered.raw) {
+			const body = rendered.body;
+			reply.status(rendered.status).send(typeof body === "string" || Buffer.isBuffer(body) ? body : Buffer.from(body));
+		} else reply.status(rendered.status).send(rendered.body);
+	}
+});
+/**
+* Fastify plugin that mounts a ts-kizuna API.
+*
+* @example
+* const app = Fastify();
+* await api.mount(app);
+*/
+const fastifyKizuna = (0, fastify_plugin.default)(async (app, options) => {
+	const { api } = options;
+	const guards = api[_ts_kizuna_core_adapter.GUARDS_META];
+	const schemes = api[_ts_kizuna_core_adapter.SCHEMES_META];
+	const requestContext = api[_ts_kizuna_core_adapter.REQUEST_CONTEXT_META];
+	const pluginExports = (0, _ts_kizuna_core_adapter.pluginExportsOf)(api);
+	const jobsMeta = api[_ts_kizuna_core_adapter.JOBS_META];
+	const jobRunner = (0, _ts_kizuna_core_adapter.jobRunnerFrom)(jobsMeta);
+	const mountRoute = (routeKey, route, lane, resolvedRouter) => {
+		app.route({
+			method: route.method,
+			url: route.path,
+			preHandler: [async (request) => {
+				request.kizunaRoute = route;
+			}],
+			handler: async (request, reply) => {
+				const adapterRequest = {
+					request,
+					method: request.method,
+					resolution: {
+						kind: "pre-resolved",
+						routeKey,
+						route,
+						params: request.params ?? {}
+					},
+					query: request.query ?? {},
+					headers: request.headers,
+					readBody: () => request.body
+				};
+				await adapter.handle({
+					routes: lane,
+					router: resolvedRouter,
+					request: adapterRequest,
+					responseContext: {
+						reply,
+						formatError: options?.formatError
+					},
+					guards,
+					schemes,
+					requestContext,
+					pluginExports,
+					jobs: jobRunner,
+					responseValidation: options?.responseValidation
+				});
+			}
+		});
+	};
+	const mountLane = (lane, resolvedRouter) => {
+		const declaredRoutes = [...adapter.eachRoute(lane, resolvedRouter)].sort((left, right) => Number(right.route.method === "HEAD") - Number(left.route.method === "HEAD"));
+		for (const { routeKey, route } of declaredRoutes) mountRoute(routeKey, route, lane, resolvedRouter);
+	};
+	mountLane(api.routes, api[_ts_kizuna_core_adapter.ROUTER_META]);
+	mountLane((0, _ts_kizuna_core_adapter.pluginRoutesOf)(api), (0, _ts_kizuna_core_adapter.pluginRouterOf)(api));
+	if (jobsMeta) {
+		const routes = (0, _ts_kizuna_core_adapter.jobRoutes)(jobsMeta);
+		const router = (0, _ts_kizuna_core_adapter.jobRouter)(jobsMeta);
+		for (const [routeKey, route] of Object.entries(routes)) mountRoute(routeKey, route, routes, router);
+	}
+}, { name: "@ts-kizuna/fastify" });
+const createServerSurface = (contract, options) => {
+	(0, _ts_kizuna_core_adapter.warnUnsupportedJobOptions)(contract.jobs, options?.jobTransport);
+	return {
+		guard: (_name, run) => run,
+		requestContext: (_name, run) => run,
+		router: (groupOrRouter, groupRouter) => groupRouter ?? groupOrRouter,
+		jobs: (handlers) => handlers,
+		api: ({ jobs, ...parts }) => {
+			const api = Object.assign((0, _ts_kizuna_core_adapter.assembleApi)(contract, parts), { [_ts_kizuna_core_adapter.JOBS_META]: contract.jobs ? {
+				jobs: contract.jobs,
+				handlers: jobs ?? {},
+				config: contract.jobsConfig,
+				transport: options?.jobTransport,
+				onError: options?.onJobError
+			} : void 0 });
+			const plugin = (0, fastify_plugin.default)(async (app, pluginOptions) => {
+				await fastifyKizuna(app, {
+					...pluginOptions,
+					api
+				});
+			}, { name: "@ts-kizuna/fastify" });
+			return Object.assign(api, {
+				plugin,
+				mount: async (app, mountOptions) => {
+					await app.register(plugin, mountOptions ?? {});
+				}
+			});
+		}
+	};
+};
+/**
+* Turn a contract into a server handle: the serving counterpart to `Kizuna`.
+* Keep the instance and use `server.guard` to define guards, `server.router`
+* to write typed handlers, and `server.api` to assemble them.
+*
+* @example
+* const server = new KizunaServer(contract);
+*
+* const requireUser = server.guard('user', ({ bearer, deny }) => {
+*     const session = bearer && sessions.get(bearer.token);
+*     return session ? { userId: session.userId } : deny(401, 'Unauthorized');
+* });
+*
+* export const api = server.api({
+*     router,
+*     guards: {
+*         user: requireUser,
+*     },
+* });
+*/
+var KizunaServer = class {
+	constructor(contract, options) {
+		Object.assign(this, createServerSurface(contract, options));
+	}
+};
+//#endregion
+exports.KizunaServer = KizunaServer;
+exports.fastifyKizuna = fastifyKizuna;

package/dist/index.d.cts

@@ -0,0 +1,200 @@
+import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest } from "fastify";
+import { ApiWithRouter, ContractPlugins, ErrorFormatter, GUARDS_META, GuardDenial, GuardDeny, GuardParams, GuardRun, HandlersFromAuth, JOBS_META, Jobs, PluginArgs, PluginImplementations, REQUEST_CONTEXT_META, RequestContextRun, RequestContextValues, RouteDefinition, RouteHandler as RouteHandler$1, Router as Router$1, Routes, SCHEMES_META, ServerOptions } from "@ts-kizuna/core/adapter";
+import { z } from "zod";
+import { Contract, CredentialOf, GuardSuccess, JobHandlers, JobsArg, RequestContextHeaderValues, RequestContextSchema, SecurityScheme, TagOptions } from "@ts-kizuna/core";
+
+//#region src/server.d.ts
+type FastifyApi<R extends Routes = Routes> = ApiWithRouter<R> & {
+  readonly [GUARDS_META]?: unknown;
+  readonly [SCHEMES_META]?: unknown;
+  readonly [REQUEST_CONTEXT_META]?: unknown;
+  readonly [JOBS_META]?: unknown;
+  /**
+   * Register every contract route on a Fastify instance. Calls
+   * `app.register` internally, so encapsulation behaves as Fastify expects.
+   */
+  mount: (app: FastifyInstance, options?: FastifyOptions) => Promise<void>;
+  /**
+   * The same routes as a Fastify plugin, for composing inside your own plugin
+   * tree: `app.register(api.plugin, { prefix: '/v1' })`.
+   */
+  plugin: FastifyPluginAsync<FastifyOptions>;
+};
+interface FastifyHandlerContext {
+  request: FastifyRequest;
+  reply: FastifyReply;
+}
+/**
+ * The handler type for a single route, typed against its contract definition.
+ */
+type RouteHandler<R extends RouteDefinition> = RouteHandler$1<R, FastifyHandlerContext>;
+/**
+ * The handler tree for a contract or route group, typed against it. Routes
+ * secured by the contract's `auth` map additionally receive each required
+ * identity's context in their handler args, under `auth`, keyed by the identity's name.
+ */
+type Router<C> = C extends Contract<infer R, infer _Tags, infer _Codes, infer Schemes, infer Auth, infer RequestContext, infer Plugins, infer J> ? HandlersFromAuth<R, FastifyHandlerContext & RequestContextValues<RequestContext> & PluginArgs<Plugins> & JobsArg<J>, Schemes, Auth> : C extends Routes ? Router$1<C, FastifyHandlerContext> : never;
+/**
+ * The handler for each of a contract's scheduled jobs, typed against it. Each
+ * receives only the job's `input`, so the same handler can be run in process.
+ */
+type JobsRouter<C> = C extends Contract<infer _R, infer _Tags, infer _Codes, infer _Schemes, infer _Auth, infer _RequestContext, infer _Plugins, infer J> ? JobHandlers<J> : never;
+/**
+ * The handlers for a group named on the contract, or for a bare route group.
+ * Both forms resolve through one signature: a second candidate of the same
+ * arity costs zero-argument handlers their contextual type.
+ */
+type GroupRouter<Source, GroupOrRoutes> = GroupOrRoutes extends string ? Router<Source>[Extract<GroupOrRoutes, keyof Router<Source>>] : Router<GroupOrRoutes>;
+declare module 'fastify' {
+  interface FastifyRequest {
+    kizunaRoute?: RouteDefinition;
+  }
+}
+type FastifyPreHandler = (request: FastifyRequest, reply: FastifyReply) => void | Promise<void>;
+interface FastifyOptions {
+  /**
+   * Validate handler return values against the routes' response schemas.
+   * Mismatches surface as 500 errors. Intended for development; disable in
+   * production.
+   *
+   * @default false
+   */
+  responseValidation?: boolean;
+  /**
+   * Reshape error (status >= 400) response bytes before they are sent. See
+   * {@link ErrorFormatter}.
+   */
+  formatError?: ErrorFormatter<FastifyRequest>;
+}
+/**
+ * A guard per identity, keyed by name. Each receives the handler context, a
+ * `deny` helper, and the matched route's required scopes, and returns that
+ * identity's {@link GuardSuccess} (its context and access fields) or a `deny(...)`
+ * result. Keying by name lets each guard's return be typed against its own
+ * identity, so access values narrow without an annotation. An
+ * authentication-only identity (no context, no access) returns nothing on
+ * success, or `deny(...)`.
+ */
+type GuardFns<Schemes extends Record<string, SecurityScheme>, Params> = { [Name in keyof Schemes]: (args: FastifyHandlerContext & CredentialOf<Schemes[Name]> & {
+  params: Params;
+  deny: GuardDeny;
+  scopes: string[];
+}) => [keyof GuardSuccess<Schemes[Name]>] extends [never] ? void | GuardDenial | Promise<void | GuardDenial> : GuardSuccess<Schemes[Name]> | GuardDenial | Promise<GuardSuccess<Schemes[Name]> | GuardDenial> };
+/**
+ * One guard per identity declared on the contract.
+ */
+type GuardsForSchemes<Schemes extends Record<string, SecurityScheme>> = { [Name in keyof Schemes]: GuardRun<FastifyHandlerContext> };
+/**
+ * The resolver functions for the request context schemas declared on `kizuna`,
+ * keyed by name. Each runs on every route and returns its schema's value.
+ */
+type RequestResolverFns<RequestContext extends Record<string, RequestContextSchema>> = { [Name in keyof RequestContext]: (args: FastifyHandlerContext & {
+  params: Record<string, string>;
+  headers: RequestContextHeaderValues<RequestContext[Name]>;
+}) => z.output<RequestContext[Name]['context']> | Promise<z.output<RequestContext[Name]['context']>> };
+interface KizunaPluginOptions extends FastifyOptions {
+  /**
+   * The API object built by `server.api`.
+   */
+  api: FastifyApi;
+}
+/**
+ * Fastify plugin that mounts a ts-kizuna API.
+ *
+ * @example
+ * const app = Fastify();
+ * await api.mount(app);
+ */
+declare const fastifyKizuna: (app: FastifyInstance, options: KizunaPluginOptions) => Promise<void>;
+type ServerContract<R extends Routes, Schemes extends Record<string, SecurityScheme>, Auth, RequestContext extends Record<string, RequestContextSchema>, Plugins extends ContractPlugins, J extends Jobs = Jobs> = Contract<R, Record<string, TagOptions>, string, Schemes, Auth, RequestContext, Plugins, J>;
+interface Server<R extends Routes, Schemes extends Record<string, SecurityScheme>, Auth, RequestContext extends Record<string, RequestContextSchema>, Plugins extends ContractPlugins, J extends Jobs = Jobs> {
+  /**
+   * Define a guard for one of the contract's identities. It runs before the
+   * handlers of every route whose `auth` entry requires the identity, and
+   * receives the credential its method extracted (`bearer`, `apiKey`, or
+   * `basic`, `null` when absent). Return the identity's context and access
+   * fields to allow the request, or call `deny(status, detail)`.
+   */
+  guard<const Name extends Extract<keyof Schemes, string>>(name: Name, run: GuardFns<Schemes, GuardParams<R, Auth, Name>>[Name]): GuardRun<FastifyHandlerContext>;
+  /**
+   * Define a request context resolver declared on the contract. It runs on
+   * every route, public ones included, and never denies.
+   */
+  requestContext<const Name extends Extract<keyof RequestContext, string>>(name: Name, run: RequestResolverFns<RequestContext>[Name]): RequestContextRun<FastifyHandlerContext>;
+  /**
+   * Write typed handlers for the contract or one of its route groups.
+   */
+  router: {
+    <const GroupOrRoutes extends Extract<keyof Router<ServerContract<R, Schemes, Auth, RequestContext, Plugins, J>>, string> | Routes>(group: GroupOrRoutes, router: GroupRouter<ServerContract<R, Schemes, Auth, RequestContext, Plugins, J>, GroupOrRoutes>): GroupRouter<ServerContract<R, Schemes, Auth, RequestContext, Plugins, J>, GroupOrRoutes>;
+    (router: Router<ServerContract<R, Schemes, Auth, RequestContext, Plugins, J>>): Router<ServerContract<R, Schemes, Auth, RequestContext, Plugins, J>>;
+  };
+  /**
+   * Write a handler for each of the contract's jobs.
+   *
+   * Pass a `transport` to say where a queued job goes. Without one, `queue`
+   * runs the job in this process and it is lost on a crash.
+   *
+   * @example
+   * export const jobs = server.jobs({
+   *     sendDigests: async () => ({
+   *         status: 200,
+   *         body: {
+   *             sent: await sendPendingDigests(),
+   *         },
+   *     }),
+   * });
+   */
+  jobs(handlers: JobsRouter<ServerContract<R, Schemes, Auth, RequestContext, Plugins, J>>): JobsRouter<ServerContract<R, Schemes, Auth, RequestContext, Plugins, J>>;
+  /**
+   * Assemble the router, guards, and job handlers into the api object.
+   */
+  api(options: {
+    router: Router<ServerContract<R, Schemes, Auth, RequestContext, Plugins, J>>;
+  } & (string extends keyof Schemes ? {
+    guards?: undefined;
+  } : {
+    guards: NoInfer<GuardsForSchemes<Schemes>>;
+  }) & (string extends keyof J ? {
+    jobs?: undefined;
+  } : {
+    jobs: NoInfer<JobsRouter<ServerContract<R, Schemes, Auth, RequestContext, Plugins, J>>>;
+  }) & (string extends keyof RequestContext ? {
+    requestContext?: undefined;
+  } : {
+    requestContext: NoInfer<{ [Name in keyof RequestContext]: RequestContextRun<FastifyHandlerContext> }>;
+  }) & (string extends keyof Plugins ? {
+    plugins?: undefined;
+  } : {
+    plugins: PluginImplementations<Plugins, FastifyHandlerContext>;
+  })): FastifyApi<R>;
+}
+/**
+ * Turn a contract into a server handle: the serving counterpart to `Kizuna`.
+ * Keep the instance and use `server.guard` to define guards, `server.router`
+ * to write typed handlers, and `server.api` to assemble them.
+ *
+ * @example
+ * const server = new KizunaServer(contract);
+ *
+ * const requireUser = server.guard('user', ({ bearer, deny }) => {
+ *     const session = bearer && sessions.get(bearer.token);
+ *     return session ? { userId: session.userId } : deny(401, 'Unauthorized');
+ * });
+ *
+ * export const api = server.api({
+ *     router,
+ *     guards: {
+ *         user: requireUser,
+ *     },
+ * });
+ */
+declare class KizunaServer<const R extends Routes, Schemes extends Record<string, SecurityScheme>, Auth, RequestContext extends Record<string, RequestContextSchema>, Plugins extends ContractPlugins, J extends Jobs = Jobs> implements Server<R, Schemes, Auth, RequestContext, Plugins, J> {
+  readonly guard: Server<R, Schemes, Auth, RequestContext, Plugins, J>['guard'];
+  readonly requestContext: Server<R, Schemes, Auth, RequestContext, Plugins, J>['requestContext'];
+  readonly router: Server<R, Schemes, Auth, RequestContext, Plugins, J>['router'];
+  readonly jobs: Server<R, Schemes, Auth, RequestContext, Plugins, J>['jobs'];
+  readonly api: Server<R, Schemes, Auth, RequestContext, Plugins, J>['api'];
+  constructor(contract: ServerContract<R, Schemes, Auth, RequestContext, Plugins, J>, options?: ServerOptions);
+}
+//#endregion
+export { FastifyApi, FastifyHandlerContext, FastifyOptions, FastifyPreHandler, JobsRouter, KizunaPluginOptions, KizunaServer, RouteHandler, Router, Server, fastifyKizuna };

package/dist/index.d.mts

@@ -0,0 +1,200 @@
+import { ApiWithRouter, ContractPlugins, ErrorFormatter, GUARDS_META, GuardDenial, GuardDeny, GuardParams, GuardRun, HandlersFromAuth, JOBS_META, Jobs, PluginArgs, PluginImplementations, REQUEST_CONTEXT_META, RequestContextRun, RequestContextValues, RouteDefinition, RouteHandler as RouteHandler$1, Router as Router$1, Routes, SCHEMES_META, ServerOptions } from "@ts-kizuna/core/adapter";
+import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest } from "fastify";
+import { z } from "zod";
+import { Contract, CredentialOf, GuardSuccess, JobHandlers, JobsArg, RequestContextHeaderValues, RequestContextSchema, SecurityScheme, TagOptions } from "@ts-kizuna/core";
+
+//#region src/server.d.ts
+type FastifyApi<R extends Routes = Routes> = ApiWithRouter<R> & {
+  readonly [GUARDS_META]?: unknown;
+  readonly [SCHEMES_META]?: unknown;
+  readonly [REQUEST_CONTEXT_META]?: unknown;
+  readonly [JOBS_META]?: unknown;
+  /**
+   * Register every contract route on a Fastify instance. Calls
+   * `app.register` internally, so encapsulation behaves as Fastify expects.
+   */
+  mount: (app: FastifyInstance, options?: FastifyOptions) => Promise<void>;
+  /**
+   * The same routes as a Fastify plugin, for composing inside your own plugin
+   * tree: `app.register(api.plugin, { prefix: '/v1' })`.
+   */
+  plugin: FastifyPluginAsync<FastifyOptions>;
+};
+interface FastifyHandlerContext {
+  request: FastifyRequest;
+  reply: FastifyReply;
+}
+/**
+ * The handler type for a single route, typed against its contract definition.
+ */
+type RouteHandler<R extends RouteDefinition> = RouteHandler$1<R, FastifyHandlerContext>;
+/**
+ * The handler tree for a contract or route group, typed against it. Routes
+ * secured by the contract's `auth` map additionally receive each required
+ * identity's context in their handler args, under `auth`, keyed by the identity's name.
+ */
+type Router<C> = C extends Contract<infer R, infer _Tags, infer _Codes, infer Schemes, infer Auth, infer RequestContext, infer Plugins, infer J> ? HandlersFromAuth<R, FastifyHandlerContext & RequestContextValues<RequestContext> & PluginArgs<Plugins> & JobsArg<J>, Schemes, Auth> : C extends Routes ? Router$1<C, FastifyHandlerContext> : never;
+/**
+ * The handler for each of a contract's scheduled jobs, typed against it. Each
+ * receives only the job's `input`, so the same handler can be run in process.
+ */
+type JobsRouter<C> = C extends Contract<infer _R, infer _Tags, infer _Codes, infer _Schemes, infer _Auth, infer _RequestContext, infer _Plugins, infer J> ? JobHandlers<J> : never;
+/**
+ * The handlers for a group named on the contract, or for a bare route group.
+ * Both forms resolve through one signature: a second candidate of the same
+ * arity costs zero-argument handlers their contextual type.
+ */
+type GroupRouter<Source, GroupOrRoutes> = GroupOrRoutes extends string ? Router<Source>[Extract<GroupOrRoutes, keyof Router<Source>>] : Router<GroupOrRoutes>;
+declare module 'fastify' {
+  interface FastifyRequest {
+    kizunaRoute?: RouteDefinition;
+  }
+}
+type FastifyPreHandler = (request: FastifyRequest, reply: FastifyReply) => void | Promise<void>;
+interface FastifyOptions {
+  /**
+   * Validate handler return values against the routes' response schemas.
+   * Mismatches surface as 500 errors. Intended for development; disable in
+   * production.
+   *
+   * @default false
+   */
+  responseValidation?: boolean;
+  /**
+   * Reshape error (status >= 400) response bytes before they are sent. See
+   * {@link ErrorFormatter}.
+   */
+  formatError?: ErrorFormatter<FastifyRequest>;
+}
+/**
+ * A guard per identity, keyed by name. Each receives the handler context, a
+ * `deny` helper, and the matched route's required scopes, and returns that
+ * identity's {@link GuardSuccess} (its context and access fields) or a `deny(...)`
+ * result. Keying by name lets each guard's return be typed against its own
+ * identity, so access values narrow without an annotation. An
+ * authentication-only identity (no context, no access) returns nothing on
+ * success, or `deny(...)`.
+ */
+type GuardFns<Schemes extends Record<string, SecurityScheme>, Params> = { [Name in keyof Schemes]: (args: FastifyHandlerContext & CredentialOf<Schemes[Name]> & {
+  params: Params;
+  deny: GuardDeny;
+  scopes: string[];
+}) => [keyof GuardSuccess<Schemes[Name]>] extends [never] ? void | GuardDenial | Promise<void | GuardDenial> : GuardSuccess<Schemes[Name]> | GuardDenial | Promise<GuardSuccess<Schemes[Name]> | GuardDenial> };
+/**
+ * One guard per identity declared on the contract.
+ */
+type GuardsForSchemes<Schemes extends Record<string, SecurityScheme>> = { [Name in keyof Schemes]: GuardRun<FastifyHandlerContext> };
+/**
+ * The resolver functions for the request context schemas declared on `kizuna`,
+ * keyed by name. Each runs on every route and returns its schema's value.
+ */
+type RequestResolverFns<RequestContext extends Record<string, RequestContextSchema>> = { [Name in keyof RequestContext]: (args: FastifyHandlerContext & {
+  params: Record<string, string>;
+  headers: RequestContextHeaderValues<RequestContext[Name]>;
+}) => z.output<RequestContext[Name]['context']> | Promise<z.output<RequestContext[Name]['context']>> };
+interface KizunaPluginOptions extends FastifyOptions {
+  /**
+   * The API object built by `server.api`.
+   */
+  api: FastifyApi;
+}
+/**
+ * Fastify plugin that mounts a ts-kizuna API.
+ *
+ * @example
+ * const app = Fastify();
+ * await api.mount(app);
+ */
+declare const fastifyKizuna: (app: FastifyInstance, options: KizunaPluginOptions) => Promise<void>;
+type ServerContract<R extends Routes, Schemes extends Record<string, SecurityScheme>, Auth, RequestContext extends Record<string, RequestContextSchema>, Plugins extends ContractPlugins, J extends Jobs = Jobs> = Contract<R, Record<string, TagOptions>, string, Schemes, Auth, RequestContext, Plugins, J>;
+interface Server<R extends Routes, Schemes extends Record<string, SecurityScheme>, Auth, RequestContext extends Record<string, RequestContextSchema>, Plugins extends ContractPlugins, J extends Jobs = Jobs> {
+  /**
+   * Define a guard for one of the contract's identities. It runs before the
+   * handlers of every route whose `auth` entry requires the identity, and
+   * receives the credential its method extracted (`bearer`, `apiKey`, or
+   * `basic`, `null` when absent). Return the identity's context and access
+   * fields to allow the request, or call `deny(status, detail)`.
+   */
+  guard<const Name extends Extract<keyof Schemes, string>>(name: Name, run: GuardFns<Schemes, GuardParams<R, Auth, Name>>[Name]): GuardRun<FastifyHandlerContext>;
+  /**
+   * Define a request context resolver declared on the contract. It runs on
+   * every route, public ones included, and never denies.
+   */
+  requestContext<const Name extends Extract<keyof RequestContext, string>>(name: Name, run: RequestResolverFns<RequestContext>[Name]): RequestContextRun<FastifyHandlerContext>;
+  /**
+   * Write typed handlers for the contract or one of its route groups.
+   */
+  router: {
+    <const GroupOrRoutes extends Extract<keyof Router<ServerContract<R, Schemes, Auth, RequestContext, Plugins, J>>, string> | Routes>(group: GroupOrRoutes, router: GroupRouter<ServerContract<R, Schemes, Auth, RequestContext, Plugins, J>, GroupOrRoutes>): GroupRouter<ServerContract<R, Schemes, Auth, RequestContext, Plugins, J>, GroupOrRoutes>;
+    (router: Router<ServerContract<R, Schemes, Auth, RequestContext, Plugins, J>>): Router<ServerContract<R, Schemes, Auth, RequestContext, Plugins, J>>;
+  };
+  /**
+   * Write a handler for each of the contract's jobs.
+   *
+   * Pass a `transport` to say where a queued job goes. Without one, `queue`
+   * runs the job in this process and it is lost on a crash.
+   *
+   * @example
+   * export const jobs = server.jobs({
+   *     sendDigests: async () => ({
+   *         status: 200,
+   *         body: {
+   *             sent: await sendPendingDigests(),
+   *         },
+   *     }),
+   * });
+   */
+  jobs(handlers: JobsRouter<ServerContract<R, Schemes, Auth, RequestContext, Plugins, J>>): JobsRouter<ServerContract<R, Schemes, Auth, RequestContext, Plugins, J>>;
+  /**
+   * Assemble the router, guards, and job handlers into the api object.
+   */
+  api(options: {
+    router: Router<ServerContract<R, Schemes, Auth, RequestContext, Plugins, J>>;
+  } & (string extends keyof Schemes ? {
+    guards?: undefined;
+  } : {
+    guards: NoInfer<GuardsForSchemes<Schemes>>;
+  }) & (string extends keyof J ? {
+    jobs?: undefined;
+  } : {
+    jobs: NoInfer<JobsRouter<ServerContract<R, Schemes, Auth, RequestContext, Plugins, J>>>;
+  }) & (string extends keyof RequestContext ? {
+    requestContext?: undefined;
+  } : {
+    requestContext: NoInfer<{ [Name in keyof RequestContext]: RequestContextRun<FastifyHandlerContext> }>;
+  }) & (string extends keyof Plugins ? {
+    plugins?: undefined;
+  } : {
+    plugins: PluginImplementations<Plugins, FastifyHandlerContext>;
+  })): FastifyApi<R>;
+}
+/**
+ * Turn a contract into a server handle: the serving counterpart to `Kizuna`.
+ * Keep the instance and use `server.guard` to define guards, `server.router`
+ * to write typed handlers, and `server.api` to assemble them.
+ *
+ * @example
+ * const server = new KizunaServer(contract);
+ *
+ * const requireUser = server.guard('user', ({ bearer, deny }) => {
+ *     const session = bearer && sessions.get(bearer.token);
+ *     return session ? { userId: session.userId } : deny(401, 'Unauthorized');
+ * });
+ *
+ * export const api = server.api({
+ *     router,
+ *     guards: {
+ *         user: requireUser,
+ *     },
+ * });
+ */
+declare class KizunaServer<const R extends Routes, Schemes extends Record<string, SecurityScheme>, Auth, RequestContext extends Record<string, RequestContextSchema>, Plugins extends ContractPlugins, J extends Jobs = Jobs> implements Server<R, Schemes, Auth, RequestContext, Plugins, J> {
+  readonly guard: Server<R, Schemes, Auth, RequestContext, Plugins, J>['guard'];
+  readonly requestContext: Server<R, Schemes, Auth, RequestContext, Plugins, J>['requestContext'];
+  readonly router: Server<R, Schemes, Auth, RequestContext, Plugins, J>['router'];
+  readonly jobs: Server<R, Schemes, Auth, RequestContext, Plugins, J>['jobs'];
+  readonly api: Server<R, Schemes, Auth, RequestContext, Plugins, J>['api'];
+  constructor(contract: ServerContract<R, Schemes, Auth, RequestContext, Plugins, J>, options?: ServerOptions);
+}
+//#endregion
+export { FastifyApi, FastifyHandlerContext, FastifyOptions, FastifyPreHandler, JobsRouter, KizunaPluginOptions, KizunaServer, RouteHandler, Router, Server, fastifyKizuna };

package/dist/index.mjs

@@ -0,0 +1,162 @@
+import fastifyPlugin from "fastify-plugin";
+import { Readable } from "node:stream";
+import { GUARDS_META, JOBS_META, REQUEST_CONTEXT_META, ROUTER_META, SCHEMES_META, assembleApi, createAdapter, jobRouter, jobRoutes, jobRunnerFrom, pluginExportsOf, pluginRouterOf, pluginRoutesOf, renderJsonResult, warnUnsupportedJobOptions } from "@ts-kizuna/core/adapter";
+//#region src/server.ts
+/**
+* Write a web `Response` to a Fastify reply. Plugins answer in web terms to stay
+* adapter-agnostic, so the translation belongs here.
+*/
+const writeWebResponse = async (response, reply) => {
+	if (!(response instanceof globalThis.Response)) return;
+	reply.hijack();
+	reply.raw.statusCode = response.status;
+	response.headers.forEach((value, name) => reply.raw.setHeader(name, value));
+	if (!response.body) {
+		reply.raw.end();
+		return;
+	}
+	Readable.fromWeb(response.body).pipe(reply.raw);
+};
+const adapter = createAdapter({
+	buildHandlerContext: (adapterRequest, { reply }) => ({
+		request: adapterRequest.request,
+		reply
+	}),
+	respond: (result, { reply, formatError }) => {
+		if (result.kind === "handler-error") throw result.error;
+		if (result.kind === "raw-response") {
+			writeWebResponse(result.response, reply);
+			return;
+		}
+		const rendered = renderJsonResult(result, formatError, reply.request);
+		for (const [key, value] of Object.entries(rendered.headers)) reply.header(key, value);
+		if (rendered.body === void 0) reply.status(rendered.status).send();
+		else if (rendered.raw) {
+			const body = rendered.body;
+			reply.status(rendered.status).send(typeof body === "string" || Buffer.isBuffer(body) ? body : Buffer.from(body));
+		} else reply.status(rendered.status).send(rendered.body);
+	}
+});
+/**
+* Fastify plugin that mounts a ts-kizuna API.
+*
+* @example
+* const app = Fastify();
+* await api.mount(app);
+*/
+const fastifyKizuna = fastifyPlugin(async (app, options) => {
+	const { api } = options;
+	const guards = api[GUARDS_META];
+	const schemes = api[SCHEMES_META];
+	const requestContext = api[REQUEST_CONTEXT_META];
+	const pluginExports = pluginExportsOf(api);
+	const jobsMeta = api[JOBS_META];
+	const jobRunner = jobRunnerFrom(jobsMeta);
+	const mountRoute = (routeKey, route, lane, resolvedRouter) => {
+		app.route({
+			method: route.method,
+			url: route.path,
+			preHandler: [async (request) => {
+				request.kizunaRoute = route;
+			}],
+			handler: async (request, reply) => {
+				const adapterRequest = {
+					request,
+					method: request.method,
+					resolution: {
+						kind: "pre-resolved",
+						routeKey,
+						route,
+						params: request.params ?? {}
+					},
+					query: request.query ?? {},
+					headers: request.headers,
+					readBody: () => request.body
+				};
+				await adapter.handle({
+					routes: lane,
+					router: resolvedRouter,
+					request: adapterRequest,
+					responseContext: {
+						reply,
+						formatError: options?.formatError
+					},
+					guards,
+					schemes,
+					requestContext,
+					pluginExports,
+					jobs: jobRunner,
+					responseValidation: options?.responseValidation
+				});
+			}
+		});
+	};
+	const mountLane = (lane, resolvedRouter) => {
+		const declaredRoutes = [...adapter.eachRoute(lane, resolvedRouter)].sort((left, right) => Number(right.route.method === "HEAD") - Number(left.route.method === "HEAD"));
+		for (const { routeKey, route } of declaredRoutes) mountRoute(routeKey, route, lane, resolvedRouter);
+	};
+	mountLane(api.routes, api[ROUTER_META]);
+	mountLane(pluginRoutesOf(api), pluginRouterOf(api));
+	if (jobsMeta) {
+		const routes = jobRoutes(jobsMeta);
+		const router = jobRouter(jobsMeta);
+		for (const [routeKey, route] of Object.entries(routes)) mountRoute(routeKey, route, routes, router);
+	}
+}, { name: "@ts-kizuna/fastify" });
+const createServerSurface = (contract, options) => {
+	warnUnsupportedJobOptions(contract.jobs, options?.jobTransport);
+	return {
+		guard: (_name, run) => run,
+		requestContext: (_name, run) => run,
+		router: (groupOrRouter, groupRouter) => groupRouter ?? groupOrRouter,
+		jobs: (handlers) => handlers,
+		api: ({ jobs, ...parts }) => {
+			const api = Object.assign(assembleApi(contract, parts), { [JOBS_META]: contract.jobs ? {
+				jobs: contract.jobs,
+				handlers: jobs ?? {},
+				config: contract.jobsConfig,
+				transport: options?.jobTransport,
+				onError: options?.onJobError
+			} : void 0 });
+			const plugin = fastifyPlugin(async (app, pluginOptions) => {
+				await fastifyKizuna(app, {
+					...pluginOptions,
+					api
+				});
+			}, { name: "@ts-kizuna/fastify" });
+			return Object.assign(api, {
+				plugin,
+				mount: async (app, mountOptions) => {
+					await app.register(plugin, mountOptions ?? {});
+				}
+			});
+		}
+	};
+};
+/**
+* Turn a contract into a server handle: the serving counterpart to `Kizuna`.
+* Keep the instance and use `server.guard` to define guards, `server.router`
+* to write typed handlers, and `server.api` to assemble them.
+*
+* @example
+* const server = new KizunaServer(contract);
+*
+* const requireUser = server.guard('user', ({ bearer, deny }) => {
+*     const session = bearer && sessions.get(bearer.token);
+*     return session ? { userId: session.userId } : deny(401, 'Unauthorized');
+* });
+*
+* export const api = server.api({
+*     router,
+*     guards: {
+*         user: requireUser,
+*     },
+* });
+*/
+var KizunaServer = class {
+	constructor(contract, options) {
+		Object.assign(this, createServerSurface(contract, options));
+	}
+};
+//#endregion
+export { KizunaServer, fastifyKizuna };

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@ts-kizuna/fastify",
+  "version": "1.49.5",
+  "description": "Fastify adapter for ts-kizuna",
+  "keywords": [
+    "ts-kizuna",
+    "typescript",
+    "zod",
+    "openapi",
+    "contract-first",
+    "type-safe",
+    "rest",
+    "api",
+    "fastify",
+    "adapter",
+    "server"
+  ],
+  "license": "MIT",
+  "homepage": "https://ts-kizuna.com/docs/adapters/fastify",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ts-kizuna/kizuna.git",
+    "directory": "packages/fastify"
+  },
+  "bugs": "https://github.com/ts-kizuna/kizuna/issues",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "kizuna": {
+    "entries": {
+      ".": "server"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "fastify-plugin": "^5.1.0"
+  },
+  "peerDependencies": {
+    "fastify": "^5.0.0",
+    "zod": "^4.0.0",
+    "@ts-kizuna/core": "1.49.5"
+  },
+  "devDependencies": {
+    "fastify": "^5.0.0",
+    "tsdown": "^0.21.0",
+    "typescript": "^5.6.3",
+    "zod": "^4.0.0",
+    "@ts-kizuna/core": "1.49.5"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm,cjs --dts --clean --external @ts-kizuna/core --external fastify --external fastify-plugin --external zod",
+    "typecheck": "tsc --noEmit"
+  }
+}