@fragno-dev/core 0.1.7 → 0.1.9

package/dist/api/fragno-response.js

@@ -0,0 +1,73 @@
+//#region src/api/fragno-response.ts
+/**
+* Parse a Response object into a FragnoResponse discriminated union
+*/
+async function parseFragnoResponse(response) {
+	const status = response.status;
+	const headers = response.headers;
+	if ((headers.get("content-type") || "").includes("application/x-ndjson")) return {
+		type: "jsonStream",
+		status,
+		headers,
+		stream: parseNDJSONStream(response)
+	};
+	const text = await response.text();
+	if (!text || text === "null") return {
+		type: "empty",
+		status,
+		headers
+	};
+	const data = JSON.parse(text);
+	if (data && typeof data === "object" && "code" in data) {
+		if ("message" in data) return {
+			type: "error",
+			status,
+			headers,
+			error: {
+				message: data.message,
+				code: data.code
+			}
+		};
+		if ("error" in data) return {
+			type: "error",
+			status,
+			headers,
+			error: {
+				message: data.error,
+				code: data.code
+			}
+		};
+	}
+	return {
+		type: "json",
+		status,
+		headers,
+		data
+	};
+}
+/**
+* Parse an NDJSON stream into an async generator
+*/
+async function* parseNDJSONStream(response) {
+	if (!response.body) return;
+	const reader = response.body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			const lines = buffer.split("\n");
+			buffer = lines.pop() || "";
+			for (const line of lines) if (line.trim()) yield JSON.parse(line);
+		}
+		if (buffer.trim()) yield JSON.parse(buffer);
+	} finally {
+		reader.releaseLock();
+	}
+}
+
+//#endregion
+export { parseFragnoResponse };
+//# sourceMappingURL=fragno-response.js.map

package/dist/api/fragno-response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fragno-response.js","names":[],"sources":["../../src/api/fragno-response.ts"],"sourcesContent":["/**\n * Discriminated union representing all possible Fragno response types\n */\nexport type FragnoResponse<T> =\n  | {\n      type: \"empty\";\n      status: number;\n      headers: Headers;\n    }\n  | {\n      type: \"error\";\n      status: number;\n      headers: Headers;\n      error: { message: string; code: string };\n    }\n  | {\n      type: \"json\";\n      status: number;\n      headers: Headers;\n      data: T;\n    }\n  | {\n      type: \"jsonStream\";\n      status: number;\n      headers: Headers;\n      stream: AsyncGenerator<T extends unknown[] ? T[number] : T>;\n    };\n\n/**\n * Parse a Response object into a FragnoResponse discriminated union\n */\nexport async function parseFragnoResponse<T>(response: Response): Promise<FragnoResponse<T>> {\n  const status = response.status;\n  const headers = response.headers;\n  const contentType = headers.get(\"content-type\") || \"\";\n\n  // Check for streaming response\n  if (contentType.includes(\"application/x-ndjson\")) {\n    return {\n      type: \"jsonStream\",\n      status,\n      headers,\n      stream: parseNDJSONStream<T>(response),\n    };\n  }\n\n  // Parse JSON body\n  const text = await response.text();\n\n  // Empty response\n  if (!text || text === \"null\") {\n    return {\n      type: \"empty\",\n      status,\n      headers,\n    };\n  }\n\n  const data = JSON.parse(text);\n\n  // Error response (has message and code, or error and code)\n  if (data && typeof data === \"object\" && \"code\" in data) {\n    if (\"message\" in data) {\n      return {\n        type: \"error\",\n        status,\n        headers,\n        error: { message: data.message, code: data.code },\n      };\n    }\n    if (\"error\" in data) {\n      return {\n        type: \"error\",\n        status,\n        headers,\n        error: { message: data.error, code: data.code },\n      };\n    }\n  }\n\n  // JSON response\n  return {\n    type: \"json\",\n    status,\n    headers,\n    data: data as T,\n  };\n}\n\n/**\n * Parse an NDJSON stream into an async generator\n */\nasync function* parseNDJSONStream<T>(\n  response: Response,\n): AsyncGenerator<T extends unknown[] ? T[number] : T> {\n  if (!response.body) {\n    return;\n  }\n\n  const reader = response.body.getReader();\n  const decoder = new TextDecoder();\n  let buffer = \"\";\n\n  try {\n    while (true) {\n      const { done, value } = await reader.read();\n\n      if (done) {\n        break;\n      }\n\n      buffer += decoder.decode(value, { stream: true });\n      const lines = buffer.split(\"\\n\");\n\n      // Keep the last incomplete line in the buffer\n      buffer = lines.pop() || \"\";\n\n      for (const line of lines) {\n        if (line.trim()) {\n          yield JSON.parse(line) as T extends unknown[] ? T[number] : T;\n        }\n      }\n    }\n\n    // Process any remaining data in the buffer\n    if (buffer.trim()) {\n      yield JSON.parse(buffer) as T extends unknown[] ? T[number] : T;\n    }\n  } finally {\n    reader.releaseLock();\n  }\n}\n"],"mappings":";;;;AA+BA,eAAsB,oBAAuB,UAAgD;CAC3F,MAAM,SAAS,SAAS;CACxB,MAAM,UAAU,SAAS;AAIzB,MAHoB,QAAQ,IAAI,eAAe,IAAI,IAGnC,SAAS,uBAAuB,CAC9C,QAAO;EACL,MAAM;EACN;EACA;EACA,QAAQ,kBAAqB,SAAS;EACvC;CAIH,MAAM,OAAO,MAAM,SAAS,MAAM;AAGlC,KAAI,CAAC,QAAQ,SAAS,OACpB,QAAO;EACL,MAAM;EACN;EACA;EACD;CAGH,MAAM,OAAO,KAAK,MAAM,KAAK;AAG7B,KAAI,QAAQ,OAAO,SAAS,YAAY,UAAU,MAAM;AACtD,MAAI,aAAa,KACf,QAAO;GACL,MAAM;GACN;GACA;GACA,OAAO;IAAE,SAAS,KAAK;IAAS,MAAM,KAAK;IAAM;GAClD;AAEH,MAAI,WAAW,KACb,QAAO;GACL,MAAM;GACN;GACA;GACA,OAAO;IAAE,SAAS,KAAK;IAAO,MAAM,KAAK;IAAM;GAChD;;AAKL,QAAO;EACL,MAAM;EACN;EACA;EACM;EACP;;;;;AAMH,gBAAgB,kBACd,UACqD;AACrD,KAAI,CAAC,SAAS,KACZ;CAGF,MAAM,SAAS,SAAS,KAAK,WAAW;CACxC,MAAM,UAAU,IAAI,aAAa;CACjC,IAAI,SAAS;AAEb,KAAI;AACF,SAAO,MAAM;GACX,MAAM,EAAE,MAAM,UAAU,MAAM,OAAO,MAAM;AAE3C,OAAI,KACF;AAGF,aAAU,QAAQ,OAAO,OAAO,EAAE,QAAQ,MAAM,CAAC;GACjD,MAAM,QAAQ,OAAO,MAAM,KAAK;AAGhC,YAAS,MAAM,KAAK,IAAI;AAExB,QAAK,MAAM,QAAQ,MACjB,KAAI,KAAK,MAAM,CACb,OAAM,KAAK,MAAM,KAAK;;AAM5B,MAAI,OAAO,MAAM,CACf,OAAM,KAAK,MAAM,OAAO;WAElB;AACR,SAAO,aAAa"}

package/dist/api/internal/path.d.ts

@@ -0,0 +1,50 @@
+//#region src/api/internal/path.d.ts
+type SplitPath<T extends string> = T extends `${infer First}/${infer Rest}` ? First extends "" ? SplitPath<Rest> : [First, ...SplitPath<Rest>] : T extends "" ? [] : [T];
+type ExtractParam<T extends string> = T extends `:${infer Name}` ? Name : T extends `**:${infer Name}` ? Name : T extends "**" ? "**" : never;
+type ExtractParamsFromSegments<T extends readonly string[]> = T extends readonly [infer First, ...infer Rest] ? First extends string ? Rest extends readonly string[] ? ExtractParam<First> | ExtractParamsFromSegments<Rest> : ExtractParam<First> : never : never;
+/**
+ * Type helper to extract path parameters from a const string path
+ *
+ * Supports:
+ * - Regular paths: "/path" -> never
+ * - Named parameters: "/path/:name" -> "name"
+ * - Wildcard paths: "/path/foo/**" -> "**"
+ * - Named wildcard paths: "/path/foo/**:name" -> "name"
+ * - String (narrows): string -> never
+ */
+type ExtractPathParams<T extends string, ValueType = string> = ExtractParamsFromSegments<SplitPath<T>> extends never ? Record<string, never> : Record<ExtractParamsFromSegments<SplitPath<T>>, ValueType>;
+/**
+ * Same as @see ExtractPathParams, but returns `Record<string, ValueType>` when a string is
+ * passed in.
+ */
+type ExtractPathParamsOrWiden<T extends string, ValueType = string> = string extends T ? Record<string, ValueType> : ExtractPathParams<T, ValueType>;
+/**
+ * Same as @see ExtractPathParamsOrWiden, but returns `undefined` when no path parameters in the
+ * const.
+ */
+type MaybeExtractPathParamsOrWiden<T extends string, ValueType = string> = HasPathParams<T> extends true ? ExtractPathParamsOrWiden<T, ValueType> : undefined;
+type ExtractPathParamNames<T extends string> = ExtractParamsFromSegments<SplitPath<T>>;
+type HasPathParams<T extends string> = ExtractPathParamNames<T> extends never ? false : true;
+/**
+ * Creates a query parameters type where the specified keys are hints (optional)
+ * and additional string keys are also allowed.
+ *
+ * This allows for flexible query parameter typing where:
+ * - All hinted parameters are optional
+ * - Additional parameters beyond the hints are allowed
+ * - Values can be of any specified type (defaults to string)
+ *
+ * @example
+ * ```ts
+ * type MyQuery = QueryParamsHint<"page" | "limit", string>;
+ * // Allows: { page?: string, limit?: string, [key: string]: string }
+ *
+ * const query1: MyQuery = {}; // Valid - no params required
+ * const query2: MyQuery = { page: "1" }; // Valid - hinted param
+ * const query3: MyQuery = { page: "1", sort: "asc" }; // Valid - additional param
+ * ```
+ */
+type QueryParamsHint<TQueryParameters extends string, ValueType = string> = Partial<Record<TQueryParameters, ValueType>> & Record<string, ValueType | undefined>;
+//#endregion
+export { ExtractPathParams, ExtractPathParamsOrWiden, HasPathParams, MaybeExtractPathParamsOrWiden, QueryParamsHint };
+//# sourceMappingURL=path.d.ts.map

package/dist/api/internal/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","names":[],"sources":["../../../src/api/internal/path.ts"],"sourcesContent":[],"mappings":";KACK,8BAA8B,2CAC/B,mBACE,UAAU,SACT,UAAU,UAAU,SACvB,qBAEG;KAGF,YATS,CAAA,UAAA,MAAA,CAAA,GASwB,CATxB,SAAA,IAAA,KAAA,KAAA,EAAA,GAUV,IAVU,GAWV,CAXU,SAAA,MAAA,KAAA,KAAA,EAAA,GAYR,IAZQ,GAaR,CAbQ,SAAA,IAAA,GAAA,IAAA,GAAA,KAAA;KAkBT,yBAlB8B,CAAA,UAAA,SAAA,MAAA,EAAA,CAAA,GAkB2B,CAlB3B,SAAA,SAAA,CAC/B,KAAA,MAAA,EACY,GAAA,KAAA,KAAA,CAAV,GAoBF,KApBE,SAAA,MAAA,GAqBA,IArBA,SAAA,SAAA,MAAA,EAAA,GAsBE,YAtBF,CAsBe,KAtBf,CAAA,GAsBwB,yBAtBxB,CAsBkD,IAtBlD,CAAA,GAuBE,YAvBF,CAuBe,KAvBf,CAAA,GAAA,KAAA,GAAA,KAAA;;;;;;;AAIE;;;;AAMF,KA2BM,iBA3BN,CAAA,UAAA,MAAA,EAAA,YAAA,MAAA,CAAA,GA4BJ,yBA5BI,CA4BsB,SA5BtB,CA4BgC,CA5BhC,CAAA,CAAA,SAAA,KAAA,GA6BA,MA7BA,CAAA,MAAA,EAAA,KAAA,CAAA,GA8BA,MA9BA,CA8BO,yBA9BP,CA8BiC,SA9BjC,CA8B2C,CA9B3C,CAAA,CAAA,EA8BgD,SA9BhD,CAAA;;;AACC;;AASH,KA0BQ,wBA1BR,CAAA,UAAA,MAAA,EAAA,YAAA,MAAA,CAAA,GAAA,MAAA,SA0BwF,CA1BxF,GA2BA,MA3BA,CAAA,MAAA,EA2Be,SA3Bf,CAAA,GA4BA,iBA5BA,CA4BkB,CA5BlB,EA4BqB,SA5BrB,CAAA;;;;;AAE0B,KAiClB,6BAjCkB,CAAA,UAAA,MAAA,EAAA,YAAA,MAAA,CAAA,GAkC5B,aAlC4B,CAkCd,CAlCc,CAAA,SAAA,IAAA,GAkCI,wBAlCJ,CAkC6B,CAlC7B,EAkCgC,SAlChC,CAAA,GAAA,SAAA;AACT,KAoCT,qBApCS,CAAA,UAAA,MAAA,CAAA,GAoCiC,yBApCjC,CAoC2D,SApC3D,CAoCqE,CApCrE,CAAA,CAAA;AAuBuE,KAqDhF,aArDgF,CAAA,UAAA,MAAA,CAAA,GAqD9C,qBArD8C,CAqDxB,CArDwB,CAAA,SAAA,KAAA,GAAA,KAAA,GAAA,IAAA;;;;;;;AAS5F;;;;;;;AAIA;;;;;AAwCA;AAqBY,KAAA,eAAe,CAAA,yBAAA,MAAA,EAAA,YAAA,MAAA,CAAA,GAAwD,OAAxD,CACzB,MADyB,CAClB,gBADkB,EACA,SADA,CAAA,CAAA,GAGzB,MAHyB,CAAA,MAAA,EAGV,SAHU,GAAA,SAAA,CAAA"}

package/dist/api/internal/path.js

@@ -0,0 +1,76 @@
+//#region src/api/internal/path.ts
+/**
+* Extract parameter names from a path pattern at runtime.
+* Examples:
+* - "/users/:id" => ["id"]
+* - "/files/**" => ["**"]
+* - "/files/**:rest" => ["rest"]
+*/
+function extractPathParams(pathPattern) {
+	const segments = pathPattern.split("/").filter((s) => s.length > 0);
+	const names = [];
+	for (const segment of segments) {
+		if (segment.startsWith(":")) {
+			names.push(segment.slice(1));
+			continue;
+		}
+		if (segment === "**") {
+			names.push("**");
+			continue;
+		}
+		if (segment.startsWith("**:")) {
+			names.push(segment.slice(3));
+			continue;
+		}
+	}
+	return names;
+}
+/**
+* Build a concrete path by replacing placeholders in a path pattern with values.
+*
+* Supports the same placeholder syntax as the matcher:
+* - Named parameter ":name" is URL-encoded as a single segment
+* - Anonymous wildcard "**" inserts the remainder as-is (slashes preserved)
+* - Named wildcard "**:name" inserts the remainder from the named key
+*
+* Examples:
+* - buildPath("/users/:id", { id: "123" }) => "/users/123"
+* - buildPath("/files/**", { "**": "a/b" }) => "/files/a/b"
+* - buildPath("/files/**:rest", { rest: "a/b" }) => "/files/a/b"
+*/
+function buildPath(pathPattern, params) {
+	const patternSegments = pathPattern.split("/");
+	const builtSegments = [];
+	for (const segment of patternSegments) {
+		if (segment.length === 0) {
+			builtSegments.push("");
+			continue;
+		}
+		if (segment.startsWith(":")) {
+			const name = segment.slice(1);
+			const value = params[name];
+			if (value === void 0) throw new Error(`Missing value for path parameter :${name}`);
+			builtSegments.push(encodeURIComponent(value));
+			continue;
+		}
+		if (segment === "**") {
+			const value = params["**"];
+			if (value === void 0) throw new Error("Missing value for path wildcard **");
+			builtSegments.push(value);
+			continue;
+		}
+		if (segment.startsWith("**:")) {
+			const name = segment.slice(3);
+			const value = params[name];
+			if (value === void 0) throw new Error(`Missing value for path wildcard **:${name}`);
+			builtSegments.push(value);
+			continue;
+		}
+		builtSegments.push(segment);
+	}
+	return builtSegments.join("/");
+}
+
+//#endregion
+export { buildPath, extractPathParams };
+//# sourceMappingURL=path.js.map

package/dist/api/internal/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","names":["names: string[]","builtSegments: string[]"],"sources":["../../../src/api/internal/path.ts"],"sourcesContent":["// Helper type to split a string by '/'\ntype SplitPath<T extends string> = T extends `${infer First}/${infer Rest}`\n  ? First extends \"\"\n    ? SplitPath<Rest>\n    : [First, ...SplitPath<Rest>]\n  : T extends \"\"\n    ? []\n    : [T];\n\n// Helper type to extract parameter name from a single segment\ntype ExtractParam<T extends string> = T extends `:${infer Name}`\n  ? Name\n  : T extends `**:${infer Name}`\n    ? Name\n    : T extends \"**\"\n      ? \"**\"\n      : never;\n\n// Helper type to extract all parameter names from path segments\ntype ExtractParamsFromSegments<T extends readonly string[]> = T extends readonly [\n  infer First,\n  ...infer Rest,\n]\n  ? First extends string\n    ? Rest extends readonly string[]\n      ? ExtractParam<First> | ExtractParamsFromSegments<Rest>\n      : ExtractParam<First>\n    : never\n  : never;\n\n/**\n * Type helper to extract path parameters from a const string path\n *\n * Supports:\n * - Regular paths: \"/path\" -> never\n * - Named parameters: \"/path/:name\" -> \"name\"\n * - Wildcard paths: \"/path/foo/**\" -> \"**\"\n * - Named wildcard paths: \"/path/foo/**:name\" -> \"name\"\n * - String (narrows): string -> never\n */\nexport type ExtractPathParams<T extends string, ValueType = string> =\n  ExtractParamsFromSegments<SplitPath<T>> extends never\n    ? Record<string, never>\n    : Record<ExtractParamsFromSegments<SplitPath<T>>, ValueType>;\n\n/**\n * Same as @see ExtractPathParams, but returns `Record<string, ValueType>` when a string is\n * passed in.\n */\nexport type ExtractPathParamsOrWiden<T extends string, ValueType = string> = string extends T\n  ? Record<string, ValueType>\n  : ExtractPathParams<T, ValueType>;\n\n// TODO: MaybeExtractPathParamsOrWiden<string> --> undefined, should that be Record<string, string>?\n/**\n * Same as @see ExtractPathParamsOrWiden, but returns `undefined` when no path parameters in the\n * const.\n */\nexport type MaybeExtractPathParamsOrWiden<T extends string, ValueType = string> =\n  HasPathParams<T> extends true ? ExtractPathParamsOrWiden<T, ValueType> : undefined;\n\n// Alternative version that returns the parameter names as a union type\nexport type ExtractPathParamNames<T extends string> = ExtractParamsFromSegments<SplitPath<T>>;\n\n// Helper type to extract parameter names as an ordered tuple from path segments\ntype ExtractParamNamesAsTuple<T extends readonly string[]> = T extends readonly [\n  infer First,\n  ...infer Rest,\n]\n  ? First extends string\n    ? Rest extends readonly string[]\n      ? ExtractParam<First> extends never\n        ? ExtractParamNamesAsTuple<Rest>\n        : [ExtractParam<First>, ...ExtractParamNamesAsTuple<Rest>]\n      : ExtractParam<First> extends never\n        ? []\n        : [ExtractParam<First>]\n    : []\n  : [];\n\n// Type to convert ExtractPathParamNames result to a string tuple with the same number of elements\nexport type ExtractPathParamNamesAsTuple<T extends string> = ExtractParamNamesAsTuple<SplitPath<T>>;\n\n// Helper type to create labeled tuple from parameter names\ntype CreateLabeledTuple<T extends readonly string[], ElementType = string> = T extends readonly [\n  infer First,\n  ...infer Rest,\n]\n  ? First extends string\n    ? Rest extends readonly string[]\n      ? [{ [K in First]: ElementType }[First], ...CreateLabeledTuple<Rest, ElementType>]\n      : [{ [K in First]: ElementType }[First]]\n    : []\n  : [];\n\n// Type to convert path parameters to a labeled tuple\nexport type ExtractPathParamsAsLabeledTuple<\n  T extends string,\n  ElementType = string,\n> = CreateLabeledTuple<ExtractParamNamesAsTuple<SplitPath<T>>, ElementType>;\n\n// Type to check if a path has parameters\nexport type HasPathParams<T extends string> = ExtractPathParamNames<T> extends never ? false : true;\n\n/**\n * Creates a query parameters type where the specified keys are hints (optional)\n * and additional string keys are also allowed.\n *\n * This allows for flexible query parameter typing where:\n * - All hinted parameters are optional\n * - Additional parameters beyond the hints are allowed\n * - Values can be of any specified type (defaults to string)\n *\n * @example\n * ```ts\n * type MyQuery = QueryParamsHint<\"page\" | \"limit\", string>;\n * // Allows: { page?: string, limit?: string, [key: string]: string }\n *\n * const query1: MyQuery = {}; // Valid - no params required\n * const query2: MyQuery = { page: \"1\" }; // Valid - hinted param\n * const query3: MyQuery = { page: \"1\", sort: \"asc\" }; // Valid - additional param\n * ```\n */\nexport type QueryParamsHint<TQueryParameters extends string, ValueType = string> = Partial<\n  Record<TQueryParameters, ValueType>\n> &\n  Record<string, ValueType | undefined>;\n\n// Runtime utilities\n\n/**\n * Extract parameter names from a path pattern at runtime.\n * Examples:\n * - \"/users/:id\" => [\"id\"]\n * - \"/files/**\" => [\"**\"]\n * - \"/files/**:rest\" => [\"rest\"]\n */\nexport function extractPathParams<TPath extends string>(\n  pathPattern: TPath,\n): ExtractPathParamNames<TPath>[] {\n  const segments = pathPattern.split(\"/\").filter((s) => s.length > 0);\n  const names: string[] = [];\n\n  for (const segment of segments) {\n    if (segment.startsWith(\":\")) {\n      names.push(segment.slice(1));\n      continue;\n    }\n\n    if (segment === \"**\") {\n      names.push(\"**\");\n      continue;\n    }\n\n    if (segment.startsWith(\"**:\")) {\n      names.push(segment.slice(3));\n      continue;\n    }\n  }\n\n  return names as ExtractPathParamNames<TPath>[];\n}\n\n/**\n * Match an actual path against a path pattern and return extracted params.\n *\n * Notes and limitations:\n * - Named segment \":name\" captures a single path segment.\n * - Wildcard \"**\" or \"**:name\" greedily captures the remainder of the path and\n *   should be placed at the end of the pattern.\n * - If the path does not match the pattern, an empty object is returned.\n */\nexport function matchPathParams<TPath extends string>(\n  pathPattern: TPath,\n  actualPath: string,\n): ExtractPathParams<TPath> {\n  const patternSegments = pathPattern.split(\"/\").filter((s) => s.length > 0);\n  const actualSegments = actualPath.split(\"/\").filter((s) => s.length > 0);\n\n  const params: Record<string, string> = {};\n\n  let i = 0;\n  let j = 0;\n\n  while (i < patternSegments.length && j < actualSegments.length) {\n    const patternSegment = patternSegments[i];\n    const actualSegment = actualSegments[j];\n\n    if (patternSegment.startsWith(\":\")) {\n      const name = patternSegment.slice(1);\n      params[name] = decodeURIComponent(actualSegment);\n      i += 1;\n      j += 1;\n      continue;\n    }\n\n    if (patternSegment === \"**\") {\n      const remainder = actualSegments.slice(j).join(\"/\");\n      params[\"**\"] = remainder ? decodeURIComponent(remainder) : \"\";\n      // Wildcard consumes the rest; pattern should end here\n      i = patternSegments.length;\n      j = actualSegments.length;\n      break;\n    }\n\n    if (patternSegment.startsWith(\"**:\")) {\n      const name = patternSegment.slice(3);\n      const remainder = actualSegments.slice(j).join(\"/\");\n      params[name] = remainder ? decodeURIComponent(remainder) : \"\";\n      // Wildcard consumes the rest; pattern should end here\n      i = patternSegments.length;\n      j = actualSegments.length;\n      break;\n    }\n\n    // Literal segment must match exactly\n    if (patternSegment === actualSegment) {\n      i += 1;\n      j += 1;\n      continue;\n    }\n\n    // Mismatch\n    return {} as ExtractPathParams<TPath>;\n  }\n\n  // If there are remaining pattern segments\n  while (i < patternSegments.length) {\n    const remaining = patternSegments[i];\n    if (remaining === \"**\") {\n      params[\"**\"] = \"\";\n      i += 1;\n      continue;\n    }\n    if (remaining.startsWith(\":\")) {\n      const name = remaining.slice(1);\n      params[name] = \"\";\n      i += 1;\n      continue;\n    }\n    if (remaining.startsWith(\"**:\")) {\n      const name = remaining.slice(3);\n      params[name] = \"\";\n      i += 1;\n      continue;\n    }\n    // Non-parameter remaining segment without corresponding actual segment → mismatch\n    return {} as ExtractPathParams<TPath>;\n  }\n\n  // If there are remaining actual segments without pattern to match → mismatch\n  if (j < actualSegments.length) {\n    return {} as ExtractPathParams<TPath>;\n  }\n\n  return params as ExtractPathParams<TPath>;\n}\n\n/**\n * Build a concrete path by replacing placeholders in a path pattern with values.\n *\n * Supports the same placeholder syntax as the matcher:\n * - Named parameter \":name\" is URL-encoded as a single segment\n * - Anonymous wildcard \"**\" inserts the remainder as-is (slashes preserved)\n * - Named wildcard \"**:name\" inserts the remainder from the named key\n *\n * Examples:\n * - buildPath(\"/users/:id\", { id: \"123\" }) => \"/users/123\"\n * - buildPath(\"/files/**\", { \"**\": \"a/b\" }) => \"/files/a/b\"\n * - buildPath(\"/files/**:rest\", { rest: \"a/b\" }) => \"/files/a/b\"\n */\nexport function buildPath<TPath extends string>(\n  pathPattern: TPath,\n  params: ExtractPathParams<TPath>,\n): string {\n  const patternSegments = pathPattern.split(\"/\");\n\n  const builtSegments: string[] = [];\n\n  for (const segment of patternSegments) {\n    if (segment.length === 0) {\n      // Preserve leading/trailing/duplicate slashes\n      builtSegments.push(\"\");\n      continue;\n    }\n\n    if (segment.startsWith(\":\")) {\n      const name = segment.slice(1);\n      const value = (params as Record<string, string | undefined>)[name];\n      if (value === undefined) {\n        throw new Error(`Missing value for path parameter :${name}`);\n      }\n      builtSegments.push(encodeURIComponent(value));\n      continue;\n    }\n\n    if (segment === \"**\") {\n      const value = (params as Record<string, string | undefined>)[\"**\"];\n      if (value === undefined) {\n        throw new Error(\"Missing value for path wildcard **\");\n      }\n      builtSegments.push(value);\n      continue;\n    }\n\n    if (segment.startsWith(\"**:\")) {\n      const name = segment.slice(3);\n      const value = (params as Record<string, string | undefined>)[name];\n      if (value === undefined) {\n        throw new Error(`Missing value for path wildcard **:${name}`);\n      }\n      builtSegments.push(value);\n      continue;\n    }\n\n    // Literal segment\n    builtSegments.push(segment);\n  }\n\n  // Join with '/'. Empty segments preserve leading/trailing slashes\n  return builtSegments.join(\"/\");\n}\n"],"mappings":";;;;;;;;AAyIA,SAAgB,kBACd,aACgC;CAChC,MAAM,WAAW,YAAY,MAAM,IAAI,CAAC,QAAQ,MAAM,EAAE,SAAS,EAAE;CACnE,MAAMA,QAAkB,EAAE;AAE1B,MAAK,MAAM,WAAW,UAAU;AAC9B,MAAI,QAAQ,WAAW,IAAI,EAAE;AAC3B,SAAM,KAAK,QAAQ,MAAM,EAAE,CAAC;AAC5B;;AAGF,MAAI,YAAY,MAAM;AACpB,SAAM,KAAK,KAAK;AAChB;;AAGF,MAAI,QAAQ,WAAW,MAAM,EAAE;AAC7B,SAAM,KAAK,QAAQ,MAAM,EAAE,CAAC;AAC5B;;;AAIJ,QAAO;;;;;;;;;;;;;;;AA+GT,SAAgB,UACd,aACA,QACQ;CACR,MAAM,kBAAkB,YAAY,MAAM,IAAI;CAE9C,MAAMC,gBAA0B,EAAE;AAElC,MAAK,MAAM,WAAW,iBAAiB;AACrC,MAAI,QAAQ,WAAW,GAAG;AAExB,iBAAc,KAAK,GAAG;AACtB;;AAGF,MAAI,QAAQ,WAAW,IAAI,EAAE;GAC3B,MAAM,OAAO,QAAQ,MAAM,EAAE;GAC7B,MAAM,QAAS,OAA8C;AAC7D,OAAI,UAAU,OACZ,OAAM,IAAI,MAAM,qCAAqC,OAAO;AAE9D,iBAAc,KAAK,mBAAmB,MAAM,CAAC;AAC7C;;AAGF,MAAI,YAAY,MAAM;GACpB,MAAM,QAAS,OAA8C;AAC7D,OAAI,UAAU,OACZ,OAAM,IAAI,MAAM,qCAAqC;AAEvD,iBAAc,KAAK,MAAM;AACzB;;AAGF,MAAI,QAAQ,WAAW,MAAM,EAAE;GAC7B,MAAM,OAAO,QAAQ,MAAM,EAAE;GAC7B,MAAM,QAAS,OAA8C;AAC7D,OAAI,UAAU,OACZ,OAAM,IAAI,MAAM,sCAAsC,OAAO;AAE/D,iBAAc,KAAK,MAAM;AACzB;;AAIF,gBAAc,KAAK,QAAQ;;AAI7B,QAAO,cAAc,KAAK,IAAI"}

package/dist/api/internal/response-stream.d.ts

@@ -0,0 +1,43 @@
+//#region src/api/internal/response-stream.d.ts
+/**
+ * @module
+ * Stream utility.
+ *
+ * Modified from honojs/hono
+ * Original source: https://github.com/honojs/hono/blob/0e3db674ad3f40be215a55a18062dd8e387ce525/src/utils/stream.ts
+ * License: MIT
+ * Date obtained: August 28 2025
+ * Copyright (c) 2021-present Yusuke Wada and Hono contributors
+ */
+type Error<Message extends string> = {
+  __errorMessage: Message;
+};
+declare class ResponseStream<TArray> {
+  #private;
+  /**
+   * Whether the stream has been aborted.
+   */
+  get aborted(): boolean;
+  /**
+   * Whether the stream has been closed normally.
+   */
+  get closed(): boolean;
+  /**
+   * The readable stream that the response is piped to.
+   */
+  get responseReadable(): ReadableStream;
+  constructor(writable: WritableStream, readable: ReadableStream);
+  writeRaw(input: Uint8Array | string): Promise<void>;
+  write(input: TArray extends (infer U)[] ? U : Error<"To use a streaming response, outputSchema must be an array.">): Promise<void>;
+  sleep(ms: number): Promise<unknown>;
+  close(): Promise<void>;
+  onAbort(listener: () => void | Promise<void>): void;
+  /**
+   * Abort the stream.
+   * You can call this method when stream is aborted by external event.
+   */
+  abort(): void;
+}
+//#endregion
+export { ResponseStream };
+//# sourceMappingURL=response-stream.d.ts.map

package/dist/api/internal/response-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-stream.d.ts","names":[],"sources":["../../../src/api/internal/response-stream.ts"],"sourcesContent":[],"mappings":";;;AAaA;;;;;;;;KAFK,KAyEG,CAAA,gBAAA,MAAA,CAAA,GAAA;EACH,cAAA,EA1EkD,OA0ElD;CAIgB;AAIR,cAhFA,cAgFA,CAAA,MAAA,CAAA,CAAA;EAUoB,CAAA,OAAA;EAAO;;;;;;;;;;;0BAhEd;wBAIF,0BAA0B;kBA2B1B,sBAAsB;eAYnC,6BACH,IACA,uEACH;qBAIgB;WAIR;iCAUoB"}

package/dist/api/internal/response-stream.js

@@ -0,0 +1,81 @@
+//#region src/api/internal/response-stream.ts
+var ResponseStream = class {
+	#writer;
+	#encoder;
+	#abortSubscribers = [];
+	#responseReadable;
+	#aborted = false;
+	#closed = false;
+	/**
+	* Whether the stream has been aborted.
+	*/
+	get aborted() {
+		return this.#aborted;
+	}
+	/**
+	* Whether the stream has been closed normally.
+	*/
+	get closed() {
+		return this.#closed;
+	}
+	/**
+	* The readable stream that the response is piped to.
+	*/
+	get responseReadable() {
+		return this.#responseReadable;
+	}
+	constructor(writable, readable) {
+		this.#writer = writable.getWriter();
+		this.#encoder = new TextEncoder();
+		const reader = readable.getReader();
+		this.#abortSubscribers.push(async () => {
+			await reader.cancel();
+		});
+		this.#responseReadable = new ReadableStream({
+			async pull(controller) {
+				const { done, value } = await reader.read();
+				if (done) controller.close();
+				else controller.enqueue(value);
+			},
+			cancel: () => {
+				this.abort();
+			}
+		});
+	}
+	async writeRaw(input) {
+		try {
+			if (typeof input === "string") input = this.#encoder.encode(input);
+			await this.#writer.write(input);
+		} catch {}
+	}
+	write(input) {
+		return this.writeRaw(JSON.stringify(input) + "\n");
+	}
+	sleep(ms) {
+		return new Promise((res) => setTimeout(res, ms));
+	}
+	async close() {
+		try {
+			await this.#writer.close();
+		} catch {} finally {
+			this.#closed = true;
+		}
+	}
+	onAbort(listener) {
+		this.#abortSubscribers.push(listener);
+	}
+	/**
+	* Abort the stream.
+	* You can call this method when stream is aborted by external event.
+	*/
+	abort() {
+		if (!this.aborted) {
+			this.#aborted = true;
+			this.#abortSubscribers.forEach((subscriber) => subscriber());
+		}
+	}
+};
+
+//#endregion
+export { ResponseStream };
+//# sourceMappingURL=response-stream.js.map

package/dist/api/internal/response-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-stream.js","names":["#aborted","#closed","#responseReadable","#writer","#encoder","#abortSubscribers"],"sources":["../../../src/api/internal/response-stream.ts"],"sourcesContent":["/**\n * @module\n * Stream utility.\n *\n * Modified from honojs/hono\n * Original source: https://github.com/honojs/hono/blob/0e3db674ad3f40be215a55a18062dd8e387ce525/src/utils/stream.ts\n * License: MIT\n * Date obtained: August 28 2025\n * Copyright (c) 2021-present Yusuke Wada and Hono contributors\n */\n\ntype Error<Message extends string> = { __errorMessage: Message };\n\nexport class ResponseStream<TArray> {\n  #writer: WritableStreamDefaultWriter<Uint8Array>;\n  #encoder: TextEncoder;\n  #abortSubscribers: (() => void | Promise<void>)[] = [];\n  #responseReadable: ReadableStream;\n\n  #aborted: boolean = false;\n  #closed: boolean = false;\n\n  /**\n   * Whether the stream has been aborted.\n   */\n  get aborted(): boolean {\n    return this.#aborted;\n  }\n\n  /**\n   * Whether the stream has been closed normally.\n   */\n  get closed(): boolean {\n    return this.#closed;\n  }\n\n  /**\n   * The readable stream that the response is piped to.\n   */\n  get responseReadable(): ReadableStream {\n    return this.#responseReadable;\n  }\n\n  constructor(writable: WritableStream, readable: ReadableStream) {\n    this.#writer = writable.getWriter();\n    this.#encoder = new TextEncoder();\n    const reader = readable.getReader();\n\n    // in case the user disconnects, let the reader know to cancel\n    // this in-turn results in responseReadable being closed\n    // and writeSSE method no longer blocks indefinitely\n    this.#abortSubscribers.push(async () => {\n      await reader.cancel();\n    });\n\n    this.#responseReadable = new ReadableStream({\n      async pull(controller) {\n        const { done, value } = await reader.read();\n        if (done) {\n          controller.close();\n        } else {\n          controller.enqueue(value);\n        }\n      },\n      cancel: () => {\n        this.abort();\n      },\n    });\n  }\n\n  async writeRaw(input: Uint8Array | string): Promise<void> {\n    try {\n      if (typeof input === \"string\") {\n        input = this.#encoder.encode(input);\n      }\n      await this.#writer.write(input);\n    } catch {\n      // Do nothing.\n    }\n  }\n\n  write(\n    input: TArray extends (infer U)[]\n      ? U\n      : Error<\"To use a streaming response, outputSchema must be an array.\">,\n  ): Promise<void> {\n    return this.writeRaw(JSON.stringify(input) + \"\\n\");\n  }\n\n  sleep(ms: number): Promise<unknown> {\n    return new Promise((res) => setTimeout(res, ms));\n  }\n\n  async close() {\n    try {\n      await this.#writer.close();\n    } catch {\n      // Do nothing. If you want to handle errors, create a stream by yourself.\n    } finally {\n      this.#closed = true;\n    }\n  }\n\n  onAbort(listener: () => void | Promise<void>) {\n    this.#abortSubscribers.push(listener);\n  }\n\n  /**\n   * Abort the stream.\n   * You can call this method when stream is aborted by external event.\n   */\n  abort() {\n    if (!this.aborted) {\n      this.#aborted = true;\n      this.#abortSubscribers.forEach((subscriber) => subscriber());\n    }\n  }\n}\n"],"mappings":";AAaA,IAAa,iBAAb,MAAoC;CAClC;CACA;CACA,oBAAoD,EAAE;CACtD;CAEA,WAAoB;CACpB,UAAmB;;;;CAKnB,IAAI,UAAmB;AACrB,SAAO,MAAKA;;;;;CAMd,IAAI,SAAkB;AACpB,SAAO,MAAKC;;;;;CAMd,IAAI,mBAAmC;AACrC,SAAO,MAAKC;;CAGd,YAAY,UAA0B,UAA0B;AAC9D,QAAKC,SAAU,SAAS,WAAW;AACnC,QAAKC,UAAW,IAAI,aAAa;EACjC,MAAM,SAAS,SAAS,WAAW;AAKnC,QAAKC,iBAAkB,KAAK,YAAY;AACtC,SAAM,OAAO,QAAQ;IACrB;AAEF,QAAKH,mBAAoB,IAAI,eAAe;GAC1C,MAAM,KAAK,YAAY;IACrB,MAAM,EAAE,MAAM,UAAU,MAAM,OAAO,MAAM;AAC3C,QAAI,KACF,YAAW,OAAO;QAElB,YAAW,QAAQ,MAAM;;GAG7B,cAAc;AACZ,SAAK,OAAO;;GAEf,CAAC;;CAGJ,MAAM,SAAS,OAA2C;AACxD,MAAI;AACF,OAAI,OAAO,UAAU,SACnB,SAAQ,MAAKE,QAAS,OAAO,MAAM;AAErC,SAAM,MAAKD,OAAQ,MAAM,MAAM;UACzB;;CAKV,MACE,OAGe;AACf,SAAO,KAAK,SAAS,KAAK,UAAU,MAAM,GAAG,KAAK;;CAGpD,MAAM,IAA8B;AAClC,SAAO,IAAI,SAAS,QAAQ,WAAW,KAAK,GAAG,CAAC;;CAGlD,MAAM,QAAQ;AACZ,MAAI;AACF,SAAM,MAAKA,OAAQ,OAAO;UACpB,WAEE;AACR,SAAKF,SAAU;;;CAInB,QAAQ,UAAsC;AAC5C,QAAKI,iBAAkB,KAAK,SAAS;;;;;;CAOvC,QAAQ;AACN,MAAI,CAAC,KAAK,SAAS;AACjB,SAAKL,UAAW;AAChB,SAAKK,iBAAkB,SAAS,eAAe,YAAY,CAAC"}

package/dist/api/internal/route.js

@@ -0,0 +1,10 @@
+//#region src/api/internal/route.ts
+function getMountRoute(opts) {
+	const mountRoute = opts.mountRoute ?? `/api/${opts.name}`;
+	if (mountRoute.endsWith("/")) return mountRoute.slice(0, -1);
+	return mountRoute;
+}
+
+//#endregion
+export { getMountRoute };
+//# sourceMappingURL=route.js.map

package/dist/api/internal/route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.js","names":[],"sources":["../../../src/api/internal/route.ts"],"sourcesContent":["export function getMountRoute(opts: { mountRoute?: string; name: string }) {\n  const mountRoute = opts.mountRoute ?? `/api/${opts.name}`;\n\n  if (mountRoute.endsWith(\"/\")) {\n    return mountRoute.slice(0, -1);\n  }\n\n  return mountRoute;\n}\n"],"mappings":";AAAA,SAAgB,cAAc,MAA6C;CACzE,MAAM,aAAa,KAAK,cAAc,QAAQ,KAAK;AAEnD,KAAI,WAAW,SAAS,IAAI,CAC1B,QAAO,WAAW,MAAM,GAAG,GAAG;AAGhC,QAAO"}

package/dist/api/mutable-request-state.d.ts

@@ -0,0 +1,82 @@
+import { RequestBodyType } from "./request-input-context.js";
+
+//#region src/api/mutable-request-state.d.ts
+
+/**
+ * Holds mutable request state that can be modified by middleware and consumed by handlers.
+ *
+ * This class provides a structural way for middleware to modify request data:
+ * - Path parameters can be modified
+ * - Query/search parameters can be modified
+ * - Request body can be overridden
+ * - Request headers can be modified
+ *
+ * @example
+ * ```typescript
+ * // In middleware
+ * const state = new MutableRequestState({
+ *   pathParams: { id: "123" },
+ *   searchParams: new URLSearchParams("?role=user"),
+ *   body: { name: "John" },
+ *   headers: new Headers()
+ * });
+ *
+ * // Modify query parameters
+ * state.searchParams.set("role", "admin");
+ *
+ * // Override body
+ * state.setBody({ name: "Jane" });
+ *
+ * // Modify headers
+ * state.headers.set("X-Custom", "value");
+ * ```
+ */
+declare class MutableRequestState {
+  #private;
+  constructor(config: {
+    pathParams: Record<string, string>;
+    searchParams: URLSearchParams;
+    body: RequestBodyType;
+    headers: Headers;
+  });
+  /**
+   * Path parameters extracted from the route.
+   * Can be modified directly (e.g., `state.pathParams.id = "456"`).
+   */
+  get pathParams(): Record<string, string>;
+  /**
+   * URLSearchParams for query parameters.
+   * Can be modified using URLSearchParams API (e.g., `state.searchParams.set("key", "value")`).
+   */
+  get searchParams(): URLSearchParams;
+  /**
+   * Request headers.
+   * Can be modified using Headers API (e.g., `state.headers.set("X-Custom", "value")`).
+   */
+  get headers(): Headers;
+  /**
+   * Get the current body value.
+   * Returns the override if set, otherwise the initial body.
+   */
+  get body(): RequestBodyType;
+  /**
+   * Override the request body.
+   * This allows middleware to replace the body that will be seen by the handler.
+   *
+   * @param body - The new body value
+   *
+   * @example
+   * ```typescript
+   * // In middleware
+   * state.setBody({ modifiedField: "new value" });
+   * ```
+   */
+  setBody(body: RequestBodyType): void;
+  /**
+   * Check if the body has been overridden by middleware.
+   */
+  get hasBodyOverride(): boolean;
+}
+//#endregion
+export { MutableRequestState };
+//# sourceMappingURL=mutable-request-state.d.ts.map

package/dist/api/mutable-request-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutable-request-state.d.ts","names":[],"sources":["../../src/api/mutable-request-state.ts"],"sourcesContent":[],"mappings":";;;;;;AA+BA;;;;;;;;;;;;;;;;;;;;;;;;;;;cAAa,mBAAA;;;gBASG;kBACE;UACR;aACG;;;;;;oBAaO;;;;;sBAQE;;;;;iBAQL;;;;;cAQH;;;;;;;;;;;;;gBAgBE"}

package/dist/api/mutable-request-state.js

@@ -0,0 +1,97 @@
+//#region src/api/mutable-request-state.ts
+/**
+* Holds mutable request state that can be modified by middleware and consumed by handlers.
+*
+* This class provides a structural way for middleware to modify request data:
+* - Path parameters can be modified
+* - Query/search parameters can be modified
+* - Request body can be overridden
+* - Request headers can be modified
+*
+* @example
+* ```typescript
+* // In middleware
+* const state = new MutableRequestState({
+*   pathParams: { id: "123" },
+*   searchParams: new URLSearchParams("?role=user"),
+*   body: { name: "John" },
+*   headers: new Headers()
+* });
+*
+* // Modify query parameters
+* state.searchParams.set("role", "admin");
+*
+* // Override body
+* state.setBody({ name: "Jane" });
+*
+* // Modify headers
+* state.headers.set("X-Custom", "value");
+* ```
+*/
+var MutableRequestState = class {
+	#pathParams;
+	#searchParams;
+	#headers;
+	#initialBody;
+	#bodyOverride;
+	constructor(config) {
+		this.#pathParams = config.pathParams;
+		this.#searchParams = config.searchParams;
+		this.#headers = config.headers;
+		this.#initialBody = config.body;
+		this.#bodyOverride = void 0;
+	}
+	/**
+	* Path parameters extracted from the route.
+	* Can be modified directly (e.g., `state.pathParams.id = "456"`).
+	*/
+	get pathParams() {
+		return this.#pathParams;
+	}
+	/**
+	* URLSearchParams for query parameters.
+	* Can be modified using URLSearchParams API (e.g., `state.searchParams.set("key", "value")`).
+	*/
+	get searchParams() {
+		return this.#searchParams;
+	}
+	/**
+	* Request headers.
+	* Can be modified using Headers API (e.g., `state.headers.set("X-Custom", "value")`).
+	*/
+	get headers() {
+		return this.#headers;
+	}
+	/**
+	* Get the current body value.
+	* Returns the override if set, otherwise the initial body.
+	*/
+	get body() {
+		return this.#bodyOverride !== void 0 ? this.#bodyOverride : this.#initialBody;
+	}
+	/**
+	* Override the request body.
+	* This allows middleware to replace the body that will be seen by the handler.
+	*
+	* @param body - The new body value
+	*
+	* @example
+	* ```typescript
+	* // In middleware
+	* state.setBody({ modifiedField: "new value" });
+	* ```
+	*/
+	setBody(body) {
+		this.#bodyOverride = body;
+	}
+	/**
+	* Check if the body has been overridden by middleware.
+	*/
+	get hasBodyOverride() {
+		return this.#bodyOverride !== void 0;
+	}
+};
+
+//#endregion
+export { MutableRequestState };
+//# sourceMappingURL=mutable-request-state.js.map

package/dist/api/mutable-request-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutable-request-state.js","names":["#pathParams","#searchParams","#headers","#initialBody","#bodyOverride"],"sources":["../../src/api/mutable-request-state.ts"],"sourcesContent":["import type { RequestBodyType } from \"./request-input-context\";\n\n/**\n * Holds mutable request state that can be modified by middleware and consumed by handlers.\n *\n * This class provides a structural way for middleware to modify request data:\n * - Path parameters can be modified\n * - Query/search parameters can be modified\n * - Request body can be overridden\n * - Request headers can be modified\n *\n * @example\n * ```typescript\n * // In middleware\n * const state = new MutableRequestState({\n *   pathParams: { id: \"123\" },\n *   searchParams: new URLSearchParams(\"?role=user\"),\n *   body: { name: \"John\" },\n *   headers: new Headers()\n * });\n *\n * // Modify query parameters\n * state.searchParams.set(\"role\", \"admin\");\n *\n * // Override body\n * state.setBody({ name: \"Jane\" });\n *\n * // Modify headers\n * state.headers.set(\"X-Custom\", \"value\");\n * ```\n */\nexport class MutableRequestState {\n  readonly #pathParams: Record<string, string>;\n  readonly #searchParams: URLSearchParams;\n  readonly #headers: Headers;\n  // oxlint-disable-next-line no-unused-private-class-members False Positive?\n  readonly #initialBody: RequestBodyType;\n  #bodyOverride: RequestBodyType | undefined;\n\n  constructor(config: {\n    pathParams: Record<string, string>;\n    searchParams: URLSearchParams;\n    body: RequestBodyType;\n    headers: Headers;\n  }) {\n    this.#pathParams = config.pathParams;\n    this.#searchParams = config.searchParams;\n    this.#headers = config.headers;\n    this.#initialBody = config.body;\n    this.#bodyOverride = undefined;\n  }\n\n  /**\n   * Path parameters extracted from the route.\n   * Can be modified directly (e.g., `state.pathParams.id = \"456\"`).\n   */\n  get pathParams(): Record<string, string> {\n    return this.#pathParams;\n  }\n\n  /**\n   * URLSearchParams for query parameters.\n   * Can be modified using URLSearchParams API (e.g., `state.searchParams.set(\"key\", \"value\")`).\n   */\n  get searchParams(): URLSearchParams {\n    return this.#searchParams;\n  }\n\n  /**\n   * Request headers.\n   * Can be modified using Headers API (e.g., `state.headers.set(\"X-Custom\", \"value\")`).\n   */\n  get headers(): Headers {\n    return this.#headers;\n  }\n\n  /**\n   * Get the current body value.\n   * Returns the override if set, otherwise the initial body.\n   */\n  get body(): RequestBodyType {\n    return this.#bodyOverride !== undefined ? this.#bodyOverride : this.#initialBody;\n  }\n\n  /**\n   * Override the request body.\n   * This allows middleware to replace the body that will be seen by the handler.\n   *\n   * @param body - The new body value\n   *\n   * @example\n   * ```typescript\n   * // In middleware\n   * state.setBody({ modifiedField: \"new value\" });\n   * ```\n   */\n  setBody(body: RequestBodyType): void {\n    this.#bodyOverride = body;\n  }\n\n  /**\n   * Check if the body has been overridden by middleware.\n   */\n  get hasBodyOverride(): boolean {\n    return this.#bodyOverride !== undefined;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,IAAa,sBAAb,MAAiC;CAC/B,CAASA;CACT,CAASC;CACT,CAASC;CAET,CAASC;CACT;CAEA,YAAY,QAKT;AACD,QAAKH,aAAc,OAAO;AAC1B,QAAKC,eAAgB,OAAO;AAC5B,QAAKC,UAAW,OAAO;AACvB,QAAKC,cAAe,OAAO;AAC3B,QAAKC,eAAgB;;;;;;CAOvB,IAAI,aAAqC;AACvC,SAAO,MAAKJ;;;;;;CAOd,IAAI,eAAgC;AAClC,SAAO,MAAKC;;;;;;CAOd,IAAI,UAAmB;AACrB,SAAO,MAAKC;;;;;;CAOd,IAAI,OAAwB;AAC1B,SAAO,MAAKE,iBAAkB,SAAY,MAAKA,eAAgB,MAAKD;;;;;;;;;;;;;;CAetE,QAAQ,MAA6B;AACnC,QAAKC,eAAgB;;;;;CAMvB,IAAI,kBAA2B;AAC7B,SAAO,MAAKA,iBAAkB"}

package/dist/api/request-context-storage.d.ts

@@ -0,0 +1,42 @@
+//#region src/api/request-context-storage.d.ts
+/**
+ * Typed wrapper around AsyncLocalStorage for managing per-request data storage.
+ * Each fragment instance has its own storage to ensure proper isolation.
+ *
+ * TRequestStorage represents the type of data stored per-request (e.g., { userId: string, requestId: number })
+ *
+ * Note: The data stored should be an object that can be mutated during the request lifecycle.
+ * For example, you can store { uow: UnitOfWork } and modify properties on that object.
+ *
+ * @internal - Used by @fragno-dev/db, not part of public API
+ */
+declare class RequestContextStorage<TRequestStorage> {
+  #private;
+  constructor();
+  /**
+   * Run a callback with the given data available via getStore().
+   * This establishes the async context for the duration of the callback.
+   */
+  run<T>(data: TRequestStorage, callback: () => T): T;
+  run<T>(data: TRequestStorage, callback: () => Promise<T>): Promise<T>;
+  /**
+   * Get the current stored data from AsyncLocalStorage.
+   * @throws an error if called outside of a run() callback.
+   *
+   * Note: The returned object can be mutated. Changes will be visible to all code
+   * running within the same async context.
+   */
+  getStore(): TRequestStorage;
+  /**
+   * Enter a new async context with fresh storage.
+   * This is typically called at the start of a request handler.
+   *
+   * @param initializer Function that returns the initial storage data
+   * @param callback The request handler to execute with the storage
+   */
+  runWithInitializer<T>(initializer: () => TRequestStorage, callback: () => T): T;
+  runWithInitializer<T>(initializer: () => TRequestStorage, callback: () => Promise<T>): Promise<T>;
+}
+//#endregion
+export { RequestContextStorage };
+//# sourceMappingURL=request-context-storage.d.ts.map

package/dist/api/request-context-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context-storage.d.ts","names":[],"sources":["../../src/api/request-context-storage.ts"],"sourcesContent":[],"mappings":";;AAaA;;;;;;;;;;AAyC2C,cAzC9B,qBAyC8B,CAAA,eAAA,CAAA,CAAA;EAAiC,CAAA,OAAA;EAAI,WAAA,CAAA;EACrC;;;;EAA8C,GAAA,CAAA,CAAA,CAAA,CAAA,IAAA,EA/B1E,eA+B0E,EAAA,QAAA,EAAA,GAAA,GA/BzC,CA+ByC,CAAA,EA/BrC,CA+BqC;EAAO,GAAA,CAAA,CAAA,CAAA,CAAA,IAAA,EA9BjF,eA8BiF,EAAA,QAAA,EAAA,GAAA,GA9BhD,OA8BgD,CA9BxC,CA8BwC,CAAA,CAAA,EA9BnC,OA8BmC,CA9B3B,CA8B2B,CAAA;;;;;;;;cAlBlF;;;;;;;;2CAiB6B,iCAAiC,IAAI;2CACrC,iCAAiC,QAAQ,KAAK,QAAQ"}