@fragno-dev/core 0.0.1

package/dist/route-Bp6eByhz.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-Bp6eByhz.js","names":["#path","#method","#pathParams","#searchParams","#body","#inputSchema","#shouldValidateInput","#validateInput","#aborted","#closed","#responseReadable","#writer","#encoder","#abortSubscribers","mergedHeaders","#outputSchema","routes: any[]"],"sources":["../src/api/internal/route.ts","../src/api/request-input-context.ts","../src/api/internal/response-stream.ts","../src/api/request-output-context.ts","../src/api/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","import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { ExtractPathParams } from \"./internal/path\";\nimport { FragnoApiValidationError, type HTTPMethod } from \"./api\";\n\nexport type RequestBodyType =\n  | unknown // JSON\n  | FormData\n  | Blob\n  | null\n  | undefined;\n\nexport class RequestInputContext<\n  TPath extends string = string,\n  TInputSchema extends StandardSchemaV1 | undefined = undefined,\n> {\n  readonly #path: TPath;\n  readonly #method: string;\n  readonly #pathParams: ExtractPathParams<TPath>;\n  readonly #searchParams: URLSearchParams;\n  readonly #body: RequestBodyType;\n  readonly #inputSchema: TInputSchema | undefined;\n  readonly #shouldValidateInput: boolean;\n\n  constructor(config: {\n    path: TPath;\n    method: string;\n    pathParams: ExtractPathParams<TPath>;\n    searchParams: URLSearchParams;\n    body: RequestBodyType;\n\n    request?: Request;\n    inputSchema?: TInputSchema;\n    shouldValidateInput?: boolean;\n  }) {\n    this.#path = config.path;\n    this.#method = config.method;\n    this.#pathParams = config.pathParams;\n    this.#searchParams = config.searchParams;\n    this.#body = config.body;\n    this.#inputSchema = config.inputSchema;\n    this.#shouldValidateInput = config.shouldValidateInput ?? true;\n  }\n\n  /**\n   * Create a RequestContext from a Request object for server-side handling\n   */\n  static async fromRequest<\n    TPath extends string,\n    TInputSchema extends StandardSchemaV1 | undefined = undefined,\n  >(config: {\n    request: Request;\n    method: string;\n    path: TPath;\n    pathParams: ExtractPathParams<TPath>;\n    inputSchema?: TInputSchema;\n    shouldValidateInput?: boolean;\n  }): Promise<RequestInputContext<TPath, TInputSchema>> {\n    const url = new URL(config.request.url);\n\n    // Clone the request to avoid consuming the body stream\n    // TODO: Probably we should just cache the result instead\n    const request = config.request.clone();\n\n    // TODO: Support other body types other than json\n    const json = request.body instanceof ReadableStream ? await request.json() : undefined;\n\n    return new RequestInputContext({\n      method: config.method,\n      path: config.path,\n      pathParams: config.pathParams,\n      searchParams: url.searchParams,\n      body: json,\n      inputSchema: config.inputSchema,\n      shouldValidateInput: config.shouldValidateInput,\n    });\n  }\n\n  /**\n   * Create a RequestContext for server-side rendering contexts (no Request object)\n   */\n  static fromSSRContext<\n    TPath extends string,\n    TInputSchema extends StandardSchemaV1 | undefined = undefined,\n  >(\n    config:\n      | {\n          method: \"GET\";\n          path: TPath;\n          pathParams: ExtractPathParams<TPath>;\n          searchParams?: URLSearchParams;\n        }\n      | {\n          method: Exclude<HTTPMethod, \"GET\">;\n          path: TPath;\n          pathParams: ExtractPathParams<TPath>;\n          searchParams?: URLSearchParams;\n          body: RequestBodyType;\n          inputSchema?: TInputSchema;\n        },\n  ): RequestInputContext<TPath, TInputSchema> {\n    return new RequestInputContext({\n      method: config.method,\n      path: config.path,\n      pathParams: config.pathParams,\n      searchParams: config.searchParams ?? new URLSearchParams(),\n      body: \"body\" in config ? config.body : undefined,\n      inputSchema: \"inputSchema\" in config ? config.inputSchema : undefined,\n      shouldValidateInput: false, // No input validation in SSR context\n    });\n  }\n\n  // TODO(Wilco): We should support reading/modifying headers here.\n  /**\n   * The HTTP method as string (e.g., `GET`, `POST`)\n   */\n  get method(): string {\n    return this.#method;\n  }\n  /**\n   * The matched route path (e.g., `/users/:id`)\n   * @remarks `string`\n   */\n  get path(): TPath {\n    return this.#path;\n  }\n  /**\n   * Extracted path parameters as object (e.g., `{ id: '123' }`)\n   * @remarks `Record<string, string>`\n   */\n  get pathParams(): ExtractPathParams<TPath> {\n    return this.#pathParams;\n  }\n  /**\n   * [URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) object for query parameters\n   * @remarks `URLSearchParams`\n   */\n  get query(): URLSearchParams {\n    return this.#searchParams;\n  }\n  // TODO: Should probably remove this\n  /**\n   * @internal\n   */\n  get rawBody(): RequestBodyType {\n    return this.#body;\n  }\n  /**\n   * Input validation context (only if inputSchema is defined)\n   * @remarks `InputContext`\n   */\n  get input(): TInputSchema extends undefined\n    ? undefined\n    : {\n        schema: TInputSchema;\n        valid: () => Promise<\n          TInputSchema extends StandardSchemaV1\n            ? StandardSchemaV1.InferOutput<TInputSchema>\n            : unknown\n        >;\n      } {\n    if (!this.#inputSchema) {\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      return undefined as any;\n    }\n\n    return {\n      schema: this.#inputSchema,\n      valid: async () => {\n        if (!this.#shouldValidateInput) {\n          // In SSR context, return the body directly without validation\n          return this.#body;\n        }\n\n        return this.#validateInput();\n      },\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    } as any;\n  }\n\n  async #validateInput(): Promise<\n    TInputSchema extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<TInputSchema> : never\n  > {\n    if (!this.#inputSchema) {\n      throw new Error(\"No input schema defined for this route\");\n    }\n\n    if (this.#body instanceof FormData || this.#body instanceof Blob) {\n      throw new Error(\"Schema validation is only supported for JSON data, not FormData or Blob\");\n    }\n\n    const result = await this.#inputSchema[\"~standard\"].validate(this.#body);\n\n    if (result.issues) {\n      throw new FragnoApiValidationError(\"Validation failed\", result.issues);\n    }\n\n    return result.value as TInputSchema extends StandardSchemaV1\n      ? StandardSchemaV1.InferOutput<TInputSchema>\n      : never;\n  }\n}\n","/**\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","import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { ContentlessStatusCode, StatusCode } from \"../http/http-status\";\nimport { ResponseStream } from \"./internal/response-stream\";\nimport type { InferOrUnknown } from \"../util/types-util\";\n\nexport type ResponseData = string | ArrayBuffer | ReadableStream | Uint8Array<ArrayBuffer>;\n\ninterface ResponseInit<T extends StatusCode = StatusCode> {\n  headers?: HeadersInit;\n  status?: T;\n  statusText?: string;\n}\n\n/**\n * Utility function to merge headers from multiple sources.\n * Later headers override earlier ones.\n */\nfunction mergeHeaders(...headerSources: (HeadersInit | undefined)[]): HeadersInit | undefined {\n  const mergedHeaders = new Headers();\n\n  for (const headerSource of headerSources) {\n    if (!headerSource) continue;\n\n    if (headerSource instanceof Headers) {\n      for (const [key, value] of headerSource.entries()) {\n        mergedHeaders.set(key, value);\n      }\n    } else if (Array.isArray(headerSource)) {\n      for (const [key, value] of headerSource) {\n        mergedHeaders.set(key, value);\n      }\n    } else {\n      for (const [key, value] of Object.entries(headerSource)) {\n        mergedHeaders.set(key, value);\n      }\n    }\n  }\n\n  return mergedHeaders;\n}\n\nexport abstract class OutputContext<const TOutput, const TErrorCode extends string> {\n  /**\n   * Creates an error response.\n   *\n   * Shortcut for `throw new FragnoApiError(...)`\n   */\n  error(\n    { message, code }: { message: string; code: TErrorCode },\n    initOrStatus?: ResponseInit | StatusCode,\n    headers?: HeadersInit,\n  ): Response {\n    if (typeof initOrStatus === \"undefined\") {\n      return Response.json({ error: message, code }, { status: 500, headers });\n    }\n\n    if (typeof initOrStatus === \"number\") {\n      return Response.json({ error: message, code }, { status: initOrStatus, headers });\n    }\n\n    const mergedHeaders = mergeHeaders(initOrStatus.headers, headers);\n    return Response.json(\n      { error: message, code },\n      { status: initOrStatus.status, headers: mergedHeaders },\n    );\n  }\n\n  empty(\n    initOrStatus?: ResponseInit<ContentlessStatusCode> | ContentlessStatusCode,\n    headers?: HeadersInit,\n  ): Response {\n    const defaultHeaders = {};\n\n    if (typeof initOrStatus === \"undefined\") {\n      const mergedHeaders = mergeHeaders(defaultHeaders, headers);\n      return Response.json(null, {\n        status: 201,\n        headers: mergedHeaders,\n      });\n    }\n\n    if (typeof initOrStatus === \"number\") {\n      const mergedHeaders = mergeHeaders(defaultHeaders, headers);\n      return Response.json(null, {\n        status: initOrStatus,\n        headers: mergedHeaders,\n      });\n    }\n\n    const mergedHeaders = mergeHeaders(defaultHeaders, initOrStatus.headers, headers);\n    return Response.json(null, {\n      status: initOrStatus.status,\n      headers: mergedHeaders,\n    });\n  }\n\n  json(object: TOutput, initOrStatus?: ResponseInit | StatusCode, headers?: HeadersInit): Response {\n    if (typeof initOrStatus === \"undefined\") {\n      return Response.json(object, {\n        status: 200,\n        headers,\n      });\n    }\n\n    if (typeof initOrStatus === \"number\") {\n      return Response.json(object, {\n        status: initOrStatus,\n        headers,\n      });\n    }\n\n    const mergedHeaders = mergeHeaders(initOrStatus.headers, headers);\n    return Response.json(object, {\n      status: initOrStatus.status,\n      headers: mergedHeaders,\n    });\n  }\n\n  jsonStream = (\n    cb: (stream: ResponseStream<TOutput>) => void | Promise<void>,\n    {\n      onError,\n      headers,\n    }: {\n      onError?: (error: Error, stream: ResponseStream<TOutput>) => void | Promise<void>;\n      headers?: HeadersInit;\n    } = {},\n  ): Response => {\n    // Note: this is intentionally an arrow function (=>) to keep `this` context.\n    const defaultHeaders = {\n      \"content-type\": \"application/x-ndjson; charset=utf-8\",\n      \"transfer-encoding\": \"chunked\",\n      \"cache-control\": \"no-cache\",\n    };\n\n    const { readable, writable } = new TransformStream();\n    const stream = new ResponseStream(writable, readable);\n\n    (async () => {\n      try {\n        await cb(stream);\n      } catch (e) {\n        if (e === undefined) {\n          // If reading is canceled without a reason value (e.g. by StreamingApi)\n          // then the .pipeTo() promise will reject with undefined.\n          // In this case, do nothing because the stream is already closed.\n        } else if (e instanceof Error && onError) {\n          await onError(e, stream);\n        } else {\n          console.error(e);\n        }\n      } finally {\n        stream.close();\n      }\n    })();\n\n    return new Response(stream.responseReadable, {\n      status: 200,\n      headers: mergeHeaders(defaultHeaders, headers),\n    });\n  };\n}\n\nexport class RequestOutputContext<\n  const TOutputSchema extends StandardSchemaV1 | undefined = undefined,\n  const TErrorCode extends string = string,\n> extends OutputContext<InferOrUnknown<TOutputSchema>, TErrorCode> {\n  // eslint-disable-next-line no-unused-private-class-members\n  #outputSchema?: TOutputSchema;\n\n  constructor(outputSchema?: TOutputSchema) {\n    super();\n    this.#outputSchema = outputSchema;\n  }\n}\n","import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { FragnoRouteConfig, HTTPMethod } from \"./api\";\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type AnyFragnoRouteConfig = FragnoRouteConfig<HTTPMethod, string, any, any, any, any>;\n\nexport interface RouteFactoryContext<TConfig, TDeps, TServices> {\n  config: TConfig;\n  deps: TDeps;\n  services: TServices;\n}\n\nexport type RouteFactory<\n  TConfig,\n  TDeps,\n  TServices,\n  TRoutes extends readonly FragnoRouteConfig<\n    HTTPMethod,\n    string,\n    StandardSchemaV1 | undefined,\n    StandardSchemaV1 | undefined,\n    string,\n    string\n  >[],\n> = (context: RouteFactoryContext<TConfig, TDeps, TServices>) => TRoutes;\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type AnyRouteOrFactory = AnyFragnoRouteConfig | RouteFactory<any, any, any, any>;\n\nexport type FlattenRouteFactories<T extends readonly AnyRouteOrFactory[]> = T extends readonly [\n  infer First,\n  ...infer Rest extends readonly AnyRouteOrFactory[],\n]\n  ? // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    First extends RouteFactory<any, any, any, infer TRoutes>\n    ? [...TRoutes, ...FlattenRouteFactories<Rest>]\n    : [First, ...FlattenRouteFactories<Rest>]\n  : [];\n\n// Helper to resolve route factories into routes\nexport function resolveRouteFactories<\n  TConfig,\n  TDeps,\n  TServices,\n  const TRoutesOrFactories extends readonly AnyRouteOrFactory[],\n>(\n  context: RouteFactoryContext<TConfig, TDeps, TServices>,\n  routesOrFactories: TRoutesOrFactories,\n): FlattenRouteFactories<TRoutesOrFactories> {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const routes: any[] = [];\n\n  for (const item of routesOrFactories) {\n    if (typeof item === \"function\") {\n      // It's a route factory\n      const factoryRoutes = item(context);\n      routes.push(...factoryRoutes);\n    } else {\n      // It's a direct route\n      routes.push(item);\n    }\n  }\n\n  return routes as FlattenRouteFactories<TRoutesOrFactories>;\n}\n\n// TODO(Wilco): Do these overloads actually do anything?\n// TODO(Wilco): ValidPath<T> should be added back in here.\n\n// Overload for routes without inputSchema\nexport function defineRoute<\n  const TMethod extends HTTPMethod,\n  const TPath extends string,\n  const TOutputSchema extends StandardSchemaV1 | undefined,\n  const TErrorCode extends string = string,\n  const TQueryParameters extends string = string,\n>(\n  config: FragnoRouteConfig<\n    TMethod,\n    TPath,\n    undefined,\n    TOutputSchema,\n    TErrorCode,\n    TQueryParameters\n  > & { inputSchema?: undefined },\n): FragnoRouteConfig<TMethod, TPath, undefined, TOutputSchema, TErrorCode, TQueryParameters>;\n\n// Overload for routes with inputSchema\nexport function defineRoute<\n  const TMethod extends HTTPMethod,\n  const TPath extends string,\n  const TInputSchema extends StandardSchemaV1,\n  const TOutputSchema extends StandardSchemaV1 | undefined,\n  const TErrorCode extends string = string,\n  const TQueryParameters extends string = string,\n>(\n  config: FragnoRouteConfig<\n    TMethod,\n    TPath,\n    TInputSchema,\n    TOutputSchema,\n    TErrorCode,\n    TQueryParameters\n  > & { inputSchema: TInputSchema },\n): FragnoRouteConfig<TMethod, TPath, TInputSchema, TOutputSchema, TErrorCode, TQueryParameters>;\n\n// implementation\nexport function defineRoute<\n  const TMethod extends HTTPMethod,\n  const TPath extends string,\n  const TInputSchema extends StandardSchemaV1 | undefined,\n  const TOutputSchema extends StandardSchemaV1 | undefined,\n  const TErrorCode extends string = string,\n  const TQueryParameters extends string = string,\n>(\n  config: FragnoRouteConfig<\n    TMethod,\n    TPath,\n    TInputSchema,\n    TOutputSchema,\n    TErrorCode,\n    TQueryParameters\n  >,\n): FragnoRouteConfig<TMethod, TPath, TInputSchema, TOutputSchema, TErrorCode, TQueryParameters> {\n  return config;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-empty-object-type\nexport type EmptyObject = {}; //Record<string, never>;\n\nexport function defineRoutes<\n  TConfig = EmptyObject,\n  TDeps = EmptyObject,\n  TServices = EmptyObject,\n>() {\n  return {\n    create: <\n      const TRoutes extends readonly FragnoRouteConfig<\n        HTTPMethod,\n        string,\n        StandardSchemaV1 | undefined,\n        StandardSchemaV1 | undefined,\n        string,\n        string\n      >[],\n    >(\n      fn: (context: RouteFactoryContext<TConfig, TDeps, TServices>) => TRoutes,\n    ): RouteFactory<TConfig, TDeps, TServices, TRoutes> => {\n      return fn;\n    },\n  };\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;;;;;ACIT,IAAa,sBAAb,MAAa,oBAGX;CACA,CAASA;CACT,CAASC;CACT,CAASC;CACT,CAASC;CACT,CAASC;CACT,CAASC;CACT,CAASC;CAET,YAAY,QAUT;AACD,QAAKN,OAAQ,OAAO;AACpB,QAAKC,SAAU,OAAO;AACtB,QAAKC,aAAc,OAAO;AAC1B,QAAKC,eAAgB,OAAO;AAC5B,QAAKC,OAAQ,OAAO;AACpB,QAAKC,cAAe,OAAO;AAC3B,QAAKC,sBAAuB,OAAO,uBAAuB;;;;;CAM5D,aAAa,YAGX,QAOoD;EACpD,MAAM,MAAM,IAAI,IAAI,OAAO,QAAQ,IAAI;EAIvC,MAAM,UAAU,OAAO,QAAQ,OAAO;EAGtC,MAAM,OAAO,QAAQ,gBAAgB,iBAAiB,MAAM,QAAQ,MAAM,GAAG;AAE7E,SAAO,IAAI,oBAAoB;GAC7B,QAAQ,OAAO;GACf,MAAM,OAAO;GACb,YAAY,OAAO;GACnB,cAAc,IAAI;GAClB,MAAM;GACN,aAAa,OAAO;GACpB,qBAAqB,OAAO;GAC7B,CAAC;;;;;CAMJ,OAAO,eAIL,QAe0C;AAC1C,SAAO,IAAI,oBAAoB;GAC7B,QAAQ,OAAO;GACf,MAAM,OAAO;GACb,YAAY,OAAO;GACnB,cAAc,OAAO,gBAAgB,IAAI,iBAAiB;GAC1D,MAAM,UAAU,SAAS,OAAO,OAAO;GACvC,aAAa,iBAAiB,SAAS,OAAO,cAAc;GAC5D,qBAAqB;GACtB,CAAC;;;;;CAOJ,IAAI,SAAiB;AACnB,SAAO,MAAKL;;;;;;CAMd,IAAI,OAAc;AAChB,SAAO,MAAKD;;;;;;CAMd,IAAI,aAAuC;AACzC,SAAO,MAAKE;;;;;;CAMd,IAAI,QAAyB;AAC3B,SAAO,MAAKC;;;;;CAMd,IAAI,UAA2B;AAC7B,SAAO,MAAKC;;;;;;CAMd,IAAI,QASE;AACJ,MAAI,CAAC,MAAKC,YAER;AAGF,SAAO;GACL,QAAQ,MAAKA;GACb,OAAO,YAAY;AACjB,QAAI,CAAC,MAAKC,oBAER,QAAO,MAAKF;AAGd,WAAO,MAAKG,eAAgB;;GAG/B;;CAGH,OAAMA,gBAEJ;AACA,MAAI,CAAC,MAAKF,YACR,OAAM,IAAI,MAAM,yCAAyC;AAG3D,MAAI,MAAKD,gBAAiB,YAAY,MAAKA,gBAAiB,KAC1D,OAAM,IAAI,MAAM,0EAA0E;EAG5F,MAAM,SAAS,MAAM,MAAKC,YAAa,aAAa,SAAS,MAAKD,KAAM;AAExE,MAAI,OAAO,OACT,OAAM,IAAI,yBAAyB,qBAAqB,OAAO,OAAO;AAGxE,SAAO,OAAO;;;;;;ACvLlB,IAAa,iBAAb,MAAoC;CAClC;CACA;CACA,oBAAoD,EAAE;CACtD;CAEA,WAAoB;CACpB,UAAmB;;;;CAKnB,IAAI,UAAmB;AACrB,SAAO,MAAKI;;;;;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;;;;;;;;;;;ACjGlE,SAAS,aAAa,GAAG,eAAqE;CAC5F,MAAM,gBAAgB,IAAI,SAAS;AAEnC,MAAK,MAAM,gBAAgB,eAAe;AACxC,MAAI,CAAC,aAAc;AAEnB,MAAI,wBAAwB,QAC1B,MAAK,MAAM,CAAC,KAAK,UAAU,aAAa,SAAS,CAC/C,eAAc,IAAI,KAAK,MAAM;WAEtB,MAAM,QAAQ,aAAa,CACpC,MAAK,MAAM,CAAC,KAAK,UAAU,aACzB,eAAc,IAAI,KAAK,MAAM;MAG/B,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,aAAa,CACrD,eAAc,IAAI,KAAK,MAAM;;AAKnC,QAAO;;AAGT,IAAsB,gBAAtB,MAAoF;;;;;;CAMlF,MACE,EAAE,SAAS,QACX,cACA,SACU;AACV,MAAI,OAAO,iBAAiB,YAC1B,QAAO,SAAS,KAAK;GAAE,OAAO;GAAS;GAAM,EAAE;GAAE,QAAQ;GAAK;GAAS,CAAC;AAG1E,MAAI,OAAO,iBAAiB,SAC1B,QAAO,SAAS,KAAK;GAAE,OAAO;GAAS;GAAM,EAAE;GAAE,QAAQ;GAAc;GAAS,CAAC;EAGnF,MAAM,gBAAgB,aAAa,aAAa,SAAS,QAAQ;AACjE,SAAO,SAAS,KACd;GAAE,OAAO;GAAS;GAAM,EACxB;GAAE,QAAQ,aAAa;GAAQ,SAAS;GAAe,CACxD;;CAGH,MACE,cACA,SACU;EACV,MAAM,iBAAiB,EAAE;AAEzB,MAAI,OAAO,iBAAiB,aAAa;GACvC,MAAMC,kBAAgB,aAAa,gBAAgB,QAAQ;AAC3D,UAAO,SAAS,KAAK,MAAM;IACzB,QAAQ;IACR,SAASA;IACV,CAAC;;AAGJ,MAAI,OAAO,iBAAiB,UAAU;GACpC,MAAMA,kBAAgB,aAAa,gBAAgB,QAAQ;AAC3D,UAAO,SAAS,KAAK,MAAM;IACzB,QAAQ;IACR,SAASA;IACV,CAAC;;EAGJ,MAAM,gBAAgB,aAAa,gBAAgB,aAAa,SAAS,QAAQ;AACjF,SAAO,SAAS,KAAK,MAAM;GACzB,QAAQ,aAAa;GACrB,SAAS;GACV,CAAC;;CAGJ,KAAK,QAAiB,cAA0C,SAAiC;AAC/F,MAAI,OAAO,iBAAiB,YAC1B,QAAO,SAAS,KAAK,QAAQ;GAC3B,QAAQ;GACR;GACD,CAAC;AAGJ,MAAI,OAAO,iBAAiB,SAC1B,QAAO,SAAS,KAAK,QAAQ;GAC3B,QAAQ;GACR;GACD,CAAC;EAGJ,MAAM,gBAAgB,aAAa,aAAa,SAAS,QAAQ;AACjE,SAAO,SAAS,KAAK,QAAQ;GAC3B,QAAQ,aAAa;GACrB,SAAS;GACV,CAAC;;CAGJ,cACE,IACA,EACE,SACA,YAIE,EAAE,KACO;EAEb,MAAM,iBAAiB;GACrB,gBAAgB;GAChB,qBAAqB;GACrB,iBAAiB;GAClB;EAED,MAAM,EAAE,UAAU,aAAa,IAAI,iBAAiB;EACpD,MAAM,SAAS,IAAI,eAAe,UAAU,SAAS;AAErD,GAAC,YAAY;AACX,OAAI;AACF,UAAM,GAAG,OAAO;YACT,GAAG;AACV,QAAI,MAAM,QAAW,YAIV,aAAa,SAAS,QAC/B,OAAM,QAAQ,GAAG,OAAO;QAExB,SAAQ,MAAM,EAAE;aAEV;AACR,WAAO,OAAO;;MAEd;AAEJ,SAAO,IAAI,SAAS,OAAO,kBAAkB;GAC3C,QAAQ;GACR,SAAS,aAAa,gBAAgB,QAAQ;GAC/C,CAAC;;;AAIN,IAAa,uBAAb,cAGU,cAAyD;CAEjE;CAEA,YAAY,cAA8B;AACxC,SAAO;AACP,QAAKC,eAAgB;;;;;;ACpIzB,SAAgB,sBAMd,SACA,mBAC2C;CAE3C,MAAMC,SAAgB,EAAE;AAExB,MAAK,MAAM,QAAQ,kBACjB,KAAI,OAAO,SAAS,YAAY;EAE9B,MAAM,gBAAgB,KAAK,QAAQ;AACnC,SAAO,KAAK,GAAG,cAAc;OAG7B,QAAO,KAAK,KAAK;AAIrB,QAAO;;AA4CT,SAAgB,YAQd,QAQ8F;AAC9F,QAAO;;AAMT,SAAgB,eAIZ;AACF,QAAO,EACL,SAUE,OACqD;AACrD,SAAO;IAEV"}

package/dist/ssr-tJHqcNSw.js

@@ -0,0 +1,48 @@
+import { allTasks } from "nanostores";
+
+//#region src/util/ssr.ts
+let stores = [];
+const SSR_ENABLED = false;
+function getStores() {
+	return stores;
+}
+function addStore(store) {
+	stores.push(store);
+}
+function cleanStores() {
+	stores = [];
+}
+let clientInitialData;
+function hydrateFromWindow() {
+	if (typeof window !== "undefined" && window.__FRAGNO_INITIAL_DATA__) {
+		clientInitialData = new Map(window.__FRAGNO_INITIAL_DATA__);
+		delete window.__FRAGNO_INITIAL_DATA__;
+		console.warn("hydrateFromWindow", { clientInitialData: Array.from(clientInitialData.entries()) });
+	}
+}
+function getInitialData(key) {
+	if (clientInitialData?.has(key)) {
+		const data = clientInitialData.get(key);
+		clientInitialData.delete(key);
+		return data;
+	}
+}
+function listenToStores() {
+	for (const store of getStores()) store.listen(() => {});
+}
+async function getFinalStoreValues() {
+	listenToStores();
+	await allTasks();
+	const stores$1 = getStores();
+	const storesInitialValue = /* @__PURE__ */ new Map();
+	for (const store of stores$1) {
+		const value = store.get();
+		if (!value || !store.key || value.loading) continue;
+		storesInitialValue.set(store.key, value.data);
+	}
+	return storesInitialValue;
+}
+
+//#endregion
+export { SSR_ENABLED, addStore, cleanStores, getFinalStoreValues, getInitialData, hydrateFromWindow };
+//# sourceMappingURL=ssr-tJHqcNSw.js.map

package/dist/ssr-tJHqcNSw.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssr-tJHqcNSw.js","names":["stores: FetcherStore[]","clientInitialData: Map<string, unknown> | undefined","stores"],"sources":["../src/util/ssr.ts"],"sourcesContent":["import { allTasks } from \"nanostores\";\nimport type { FetcherStore } from \"@nanostores/query\";\n\nlet stores: FetcherStore[] = [];\n\nexport const SSR_ENABLED = false;\n\nexport function getStores() {\n  return stores;\n}\n\nexport function addStore(store: FetcherStore) {\n  stores.push(store);\n}\n\nexport function cleanStores() {\n  stores = [];\n}\n\n// Client side\ndeclare global {\n  interface Window {\n    __FRAGNO_INITIAL_DATA__?: [string, unknown][];\n  }\n}\n\nlet clientInitialData: Map<string, unknown> | undefined;\n\nexport function hydrateFromWindow() {\n  if (typeof window !== \"undefined\" && window.__FRAGNO_INITIAL_DATA__) {\n    clientInitialData = new Map(window.__FRAGNO_INITIAL_DATA__);\n    delete window.__FRAGNO_INITIAL_DATA__;\n    console.warn(\"hydrateFromWindow\", {\n      clientInitialData: Array.from(clientInitialData.entries()),\n    });\n  }\n}\n\nexport function getInitialData(key: string): unknown | undefined {\n  if (clientInitialData?.has(key)) {\n    const data = clientInitialData.get(key);\n    clientInitialData.delete(key);\n    return data;\n  }\n  return undefined;\n}\n\nfunction listenToStores(): void {\n  for (const store of getStores()) {\n    // By calling `listen`, we trigger the fetcher function of the store.\n    // This will start the data fetching process on the server.\n    // We don't need to do anything with the return value of `listen`, as we\n    // are only interested in starting the data fetching.\n    store.listen(() => {});\n  }\n}\n\n// Server side\nexport async function getFinalStoreValues(): Promise<Map<string, unknown>> {\n  listenToStores();\n  await allTasks();\n\n  const stores = getStores();\n  const storesInitialValue = new Map<string, unknown>();\n\n  for (const store of stores) {\n    const value = store.get();\n    if (!value || !store.key || value.loading) {\n      continue;\n    }\n    storesInitialValue.set(store.key, value.data);\n  }\n\n  return storesInitialValue;\n}\n"],"mappings":";;;AAGA,IAAIA,SAAyB,EAAE;AAE/B,MAAa,cAAc;AAE3B,SAAgB,YAAY;AAC1B,QAAO;;AAGT,SAAgB,SAAS,OAAqB;AAC5C,QAAO,KAAK,MAAM;;AAGpB,SAAgB,cAAc;AAC5B,UAAS,EAAE;;AAUb,IAAIC;AAEJ,SAAgB,oBAAoB;AAClC,KAAI,OAAO,WAAW,eAAe,OAAO,yBAAyB;AACnE,sBAAoB,IAAI,IAAI,OAAO,wBAAwB;AAC3D,SAAO,OAAO;AACd,UAAQ,KAAK,qBAAqB,EAChC,mBAAmB,MAAM,KAAK,kBAAkB,SAAS,CAAC,EAC3D,CAAC;;;AAIN,SAAgB,eAAe,KAAkC;AAC/D,KAAI,mBAAmB,IAAI,IAAI,EAAE;EAC/B,MAAM,OAAO,kBAAkB,IAAI,IAAI;AACvC,oBAAkB,OAAO,IAAI;AAC7B,SAAO;;;AAKX,SAAS,iBAAuB;AAC9B,MAAK,MAAM,SAAS,WAAW,CAK7B,OAAM,aAAa,GAAG;;AAK1B,eAAsB,sBAAqD;AACzE,iBAAgB;AAChB,OAAM,UAAU;CAEhB,MAAMC,WAAS,WAAW;CAC1B,MAAM,qCAAqB,IAAI,KAAsB;AAErD,MAAK,MAAM,SAASA,UAAQ;EAC1B,MAAM,QAAQ,MAAM,KAAK;AACzB,MAAI,CAAC,SAAS,CAAC,MAAM,OAAO,MAAM,QAChC;AAEF,qBAAmB,IAAI,MAAM,KAAK,MAAM,KAAK;;AAG/C,QAAO"}

package/package.json

@@ -0,0 +1,127 @@
+{
+  "name": "@fragno-dev/core",
+  "version": "0.0.1",
+  "exports": {
+    ".": {
+      "bun": "./src/mod.ts",
+      "development": "./src/mod.ts",
+      "types": "./dist/mod.d.ts",
+      "default": "./dist/mod.js"
+    },
+    "./api": {
+      "bun": "./src/api/api.ts",
+      "development": "./src/api/api.ts",
+      "types": "./dist/api/api.d.ts",
+      "default": "./dist/api/api.js"
+    },
+    "./client": {
+      "bun": "./src/client/client.ts",
+      "development": "./src/client/client.ts",
+      "types": "./dist/client/client.d.ts",
+      "default": "./dist/client/client.js"
+    },
+    "./react": {
+      "bun": "./src/client/react.tsx",
+      "development": "./src/client/react.ts",
+      "types": "./dist/client/react.d.ts",
+      "default": "./dist/client/react.js"
+    },
+    "./vanilla": {
+      "bun": "./src/client/vanilla.ts",
+      "development": "./src/client/vanilla.ts",
+      "types": "./dist/client/vanilla.d.ts",
+      "default": "./dist/client/vanilla.js"
+    },
+    "./vue": {
+      "bun": "./src/client/vue.ts",
+      "development": "./src/client/vue.ts",
+      "types": "./dist/client/vue.d.ts",
+      "default": "./dist/client/vue.js"
+    },
+    "./svelte": {
+      "bun": "./src/client/client.svelte.ts",
+      "development": "./src/client/client.svelte.ts",
+      "types": "./dist/client/client.svelte.d.ts",
+      "default": "./dist/client/client.svelte.js"
+    },
+    "./astro": {
+      "bun": "./src/integrations/astro.ts",
+      "development": "./src/integrations/astro.ts",
+      "types": "./dist/integrations/astro.d.ts",
+      "default": "./dist/integrations/astro.js"
+    },
+    "./next-js": {
+      "bun": "./src/integrations/next-js.ts",
+      "development": "./src/integrations/next-js.ts",
+      "types": "./dist/integrations/next-js.d.ts",
+      "default": "./dist/integrations/next-js.js"
+    },
+    "./react-ssr": {
+      "bun": "./src/integrations/react-ssr.ts",
+      "development": "./src/integrations/react-ssr.ts",
+      "types": "./dist/integrations/react-ssr.d.ts",
+      "default": "./dist/integrations/react-ssr.js"
+    },
+    "./svelte-kit": {
+      "bun": "./src/integrations/svelte-kit.ts",
+      "development": "./src/integrations/svelte-kit.ts",
+      "types": "./dist/integrations/svelte-kit.d.ts",
+      "default": "./dist/integrations/svelte-kit.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/mod.js",
+  "module": "./dist/mod.js",
+  "types": "./dist/mod.d.ts",
+  "scripts": {
+    "build": "tsdown",
+    "build:watch": "tsdown --watch",
+    "types:check": "tsc --noEmit"
+  },
+  "type": "module",
+  "dependencies": {
+    "@nanostores/query": "^0.3.4",
+    "@standard-schema/spec": "^1.0.0",
+    "nanostores": "^1.0.1",
+    "rou3": "^0.7.3"
+  },
+  "devDependencies": {
+    "@fragno-private/typescript-config": "0.0.1",
+    "@sveltejs/vite-plugin-svelte": "^6.2.0",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/svelte": "^5.2.8",
+    "@testing-library/vue": "^8.1.0",
+    "@types/node": "^22",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "happy-dom": "^18.0.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "svelte": "^5.1.0",
+    "vue": "^3",
+    "zod": "^4.0.5"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "vue": "^3",
+    "svelte": "^5"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rejot-dev/fragno.git",
+    "directory": "packages/fragno"
+  },
+  "homepage": "https://fragno.dev",
+  "license": "MIT"
+}

package/src/api/api.test.ts

@@ -0,0 +1,140 @@
+import { test, expect, expectTypeOf, describe } from "vitest";
+import { addRoute, type ValidPath } from "./api";
+import { z } from "zod";
+
+describe("addRoute", () => {
+  test("addRoute no inputSchema", () => {
+    addRoute({
+      method: "GET",
+      path: "/thing/**:path",
+      handler: async ({ path, pathParams }, { empty }) => {
+        expect(path).toEqual("/thing/**:path");
+        expectTypeOf<typeof path>().toEqualTypeOf<"/thing/**:path">();
+
+        expect(pathParams).toEqual({ path: "test" });
+        expectTypeOf<typeof pathParams>().toEqualTypeOf<{ path: string }>();
+        return empty();
+      },
+    });
+  });
+
+  test("addRoute with inputSchema", () => {
+    addRoute({
+      method: "GET" as const,
+      path: "/thing/**:path" as const,
+      inputSchema: z.object({
+        path: z.string(),
+      }),
+      handler: async ({ path, pathParams, input }, { empty }) => {
+        expect(path).toEqual("/thing/**:path");
+        expectTypeOf<typeof path>().toEqualTypeOf<"/thing/**:path">();
+
+        expect(pathParams).toEqual({ path: "test" });
+        expectTypeOf<typeof pathParams>().toEqualTypeOf<{ path: string }>();
+
+        expect(input).toBeTruthy();
+        if (input) {
+          expectTypeOf<typeof input.schema>().toEqualTypeOf<z.ZodObject<{ path: z.ZodString }>>();
+          expectTypeOf<typeof input.valid>().toEqualTypeOf<() => Promise<{ path: string }>>();
+
+          const _valid = await input.valid();
+          expectTypeOf<typeof _valid>().toEqualTypeOf<{ path: string }>();
+        }
+        return empty();
+      },
+    });
+  });
+
+  test("HTTPMethod DELETE without inputSchema or outputSchema", () => {
+    addRoute({
+      method: "DELETE",
+      path: "/thing",
+      handler: async ({ input }, { empty, json }) => {
+        // FIXME: Would be nicer if input was not on the object at all
+        expect(input).toBeUndefined();
+        expectTypeOf<typeof input>().toEqualTypeOf<undefined>();
+
+        // FIXME: Would be nicer if parameter of json was never, or not have json as field at all.
+        expect(json).toBeDefined();
+        expectTypeOf<Parameters<typeof json>[0]>().toEqualTypeOf<unknown>();
+
+        return empty();
+      },
+    });
+  });
+});
+
+describe("ValidPath", () => {
+  test("accepts valid paths", () => {
+    // Valid paths that start with "/", are not just "/", and don't end with "/"
+    expectTypeOf<ValidPath<"/api">>().toEqualTypeOf<"/api">();
+    expectTypeOf<ValidPath<"/users">>().toEqualTypeOf<"/users">();
+    expectTypeOf<ValidPath<"/api/users">>().toEqualTypeOf<"/api/users">();
+    expectTypeOf<ValidPath<"/api/v1/users">>().toEqualTypeOf<"/api/v1/users">();
+    expectTypeOf<ValidPath<"/thing/**:path">>().toEqualTypeOf<"/thing/**:path">();
+    expectTypeOf<ValidPath<"/a">>().toEqualTypeOf<"/a">();
+  });
+
+  test("rejects paths that don't start with '/'", () => {
+    // Paths that don't start with "/" should have error brand
+    expectTypeOf<ValidPath<"api">>().toEqualTypeOf<"api" & [`Error: Path must start with '/'.`]>();
+    expectTypeOf<ValidPath<"users">>().toEqualTypeOf<
+      "users" & [`Error: Path must start with '/'.`]
+    >();
+    expectTypeOf<ValidPath<"api/users">>().toEqualTypeOf<
+      "api/users" & [`Error: Path must start with '/'.`]
+    >();
+    expectTypeOf<ValidPath<"">>().toEqualTypeOf<"" & [`Error: Path must start with '/'.`]>();
+  });
+
+  test("rejects root path '/'", () => {
+    // Root path "/" should have error brand
+    expectTypeOf<ValidPath<"/">>().toEqualTypeOf<"/" & [`Error: Path cannot be just '/'.`]>();
+  });
+
+  test("rejects paths ending with '/'", () => {
+    // This type should show the error in IDE hover
+    type _InvalidPathExample = ValidPath<"/api/">;
+
+    // Paths ending with "/" should have error brand
+    expectTypeOf<ValidPath<"/api/">>().toEqualTypeOf<
+      "/api/" & [`Error: Path cannot end with '/'.`]
+    >();
+    expectTypeOf<ValidPath<"/users/">>().toEqualTypeOf<
+      "/users/" & [`Error: Path cannot end with '/'.`]
+    >();
+    expectTypeOf<ValidPath<"/api/users/">>().toEqualTypeOf<
+      "/api/users/" & [`Error: Path cannot end with '/'.`]
+    >();
+    expectTypeOf<ValidPath<"/api/v1/users/">>().toEqualTypeOf<
+      "/api/v1/users/" & [`Error: Path cannot end with '/'.`]
+    >();
+  });
+
+  test("rejects empty string", () => {
+    // Empty string should have error brand
+    expectTypeOf<ValidPath<"">>().toEqualTypeOf<"" & [`Error: Path must start with '/'.`]>();
+  });
+
+  test("ValidPath is still assignable to string", () => {
+    // Valid paths should still be assignable to string
+    const validPath: ValidPath<"/api"> = "/api";
+    const str: string = validPath; // This should work
+    expect(str).toBe("/api");
+
+    // Invalid paths are also assignable to string (but have error brand)
+    // @ts-expect-error - This shows the error message to the user
+    const invalidPath: ValidPath<"/api/"> = "/api/";
+    const str2: string = invalidPath; // This should also work
+    expect(str2).toBe("/api/");
+  });
+
+  test("addRoute", () => {
+    addRoute({
+      method: "GET",
+      // @ts-expect-error - This shows the error message to the user
+      path: "/",
+      handler: async (_ctx, { empty }) => empty(),
+    });
+  });
+});

package/src/api/api.ts

@@ -0,0 +1,106 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { RequestInputContext } from "./request-input-context";
+import type { RequestOutputContext } from "./request-output-context";
+
+export type HTTPMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
+export type NonGetHTTPMethod = Exclude<HTTPMethod, "GET">;
+
+// Helper type to create branded error messages that are still assignable to string
+type PathError<T extends string, TMessage extends string> = T & [`Error: ${TMessage}`];
+
+/**
+ * A valid path string that:
+ * - Is non-empty
+ * - Starts with "/"
+ * - Is not just "/"
+ * - Does not end with "/"
+ */
+export type ValidPath<T extends string = string> = T extends `/${infer Rest}`
+  ? Rest extends ""
+    ? PathError<T, "Path cannot be just '/'."> // Excludes "/"
+    : T extends `${string}/`
+      ? PathError<T, "Path cannot end with '/'."> // Excludes paths ending with "/"
+      : T
+  : PathError<T, "Path must start with '/'.">; // Excludes paths not starting with "/"
+
+export interface FragnoRouteConfig<
+  TMethod extends HTTPMethod,
+  TPath extends string,
+  TInputSchema extends StandardSchemaV1 | undefined,
+  TOutputSchema extends StandardSchemaV1 | undefined,
+  TErrorCode extends string = string,
+  TQueryParameters extends string = string,
+> {
+  method: TMethod;
+  path: TPath;
+  inputSchema?: TInputSchema;
+  outputSchema?: TOutputSchema;
+  errorCodes?: readonly TErrorCode[];
+  queryParameters?: readonly TQueryParameters[];
+  handler(
+    inputCtx: RequestInputContext<TPath, TInputSchema>,
+    outputCtx: RequestOutputContext<TOutputSchema, TErrorCode>,
+  ): Promise<Response>;
+}
+
+// Overload for routes without inputSchema
+export function addRoute<
+  TMethod extends HTTPMethod,
+  TPath extends string,
+  TOutputSchema extends StandardSchemaV1 | undefined,
+  TErrorCode extends string = string,
+  TQueryParameters extends string = string,
+>(
+  route: FragnoRouteConfig<
+    TMethod,
+    ValidPath<TPath>,
+    undefined,
+    TOutputSchema,
+    TErrorCode,
+    TQueryParameters
+  > & { inputSchema?: undefined },
+): FragnoRouteConfig<TMethod, TPath, undefined, TOutputSchema, TErrorCode, TQueryParameters>;
+
+// Overload for routes with inputSchema
+export function addRoute<
+  TMethod extends HTTPMethod,
+  TPath extends string,
+  TInputSchema extends StandardSchemaV1,
+  TOutputSchema extends StandardSchemaV1 | undefined,
+  TErrorCode extends string = string,
+  TQueryParameters extends string = string,
+>(
+  route: FragnoRouteConfig<
+    TMethod,
+    ValidPath<TPath>,
+    TInputSchema,
+    TOutputSchema,
+    TErrorCode,
+    TQueryParameters
+  > & {
+    inputSchema: TInputSchema;
+  },
+): FragnoRouteConfig<TMethod, TPath, TInputSchema, TOutputSchema, TErrorCode, TQueryParameters>;
+
+// Implementation
+export function addRoute<
+  TMethod extends HTTPMethod,
+  TPath extends string,
+  TInputSchema extends StandardSchemaV1 | undefined,
+  TOutputSchema extends StandardSchemaV1 | undefined,
+  TErrorCode extends string = string,
+  TQueryParameters extends string = string,
+>(
+  route: FragnoRouteConfig<
+    TMethod,
+    ValidPath<TPath>,
+    TInputSchema,
+    TOutputSchema,
+    TErrorCode,
+    TQueryParameters
+  >,
+): FragnoRouteConfig<TMethod, TPath, TInputSchema, TOutputSchema, TErrorCode, TQueryParameters> {
+  return route;
+}
+
+export { FragnoApiError, FragnoApiValidationError } from "./error";

package/src/api/error.ts

@@ -0,0 +1,47 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { StatusCode } from "../http/http-status";
+
+export class FragnoApiError extends Error {
+  readonly #status: StatusCode;
+  readonly #code: string;
+
+  constructor({ message, code }: { message: string; code: string }, status: StatusCode) {
+    super(message);
+    this.name = "FragnoApiError";
+    this.#status = status;
+    this.#code = code;
+  }
+
+  get status() {
+    return this.#status;
+  }
+
+  get code() {
+    return this.#code;
+  }
+
+  toResponse() {
+    return Response.json({ message: this.message, code: this.code }, { status: this.status });
+  }
+}
+
+export class FragnoApiValidationError extends FragnoApiError {
+  #issues: readonly StandardSchemaV1.Issue[];
+
+  constructor(message: string, issues: readonly StandardSchemaV1.Issue[]) {
+    super({ message, code: "FRAGNO_VALIDATION_ERROR" }, 400);
+    this.name = "FragnoApiValidationError";
+    this.#issues = issues;
+  }
+
+  get issues() {
+    return this.#issues;
+  }
+
+  override toResponse() {
+    return Response.json(
+      { message: this.message, issues: this.#issues, code: this.code },
+      { status: this.status },
+    );
+  }
+}