@fragno-dev/core 0.0.1

package/src/api/internal/path.ts

@@ -0,0 +1,322 @@
+// Helper type to split a string by '/'
+type SplitPath<T extends string> = T extends `${infer First}/${infer Rest}`
+  ? First extends ""
+    ? SplitPath<Rest>
+    : [First, ...SplitPath<Rest>]
+  : T extends ""
+    ? []
+    : [T];
+
+// Helper type to extract parameter name from a single segment
+type ExtractParam<T extends string> = T extends `:${infer Name}`
+  ? Name
+  : T extends `**:${infer Name}`
+    ? Name
+    : T extends "**"
+      ? "**"
+      : never;
+
+// Helper type to extract all parameter names from path segments
+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
+ */
+export 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.
+ */
+export type ExtractPathParamsOrWiden<T extends string, ValueType = string> = string extends T
+  ? Record<string, ValueType>
+  : ExtractPathParams<T, ValueType>;
+
+// TODO: MaybeExtractPathParamsOrWiden<string> --> undefined, should that be Record<string, string>?
+/**
+ * Same as @see ExtractPathParamsOrWiden, but returns `undefined` when no path parameters in the
+ * const.
+ */
+export type MaybeExtractPathParamsOrWiden<T extends string, ValueType = string> =
+  HasPathParams<T> extends true ? ExtractPathParamsOrWiden<T, ValueType> : undefined;
+
+// Alternative version that returns the parameter names as a union type
+export type ExtractPathParamNames<T extends string> = ExtractParamsFromSegments<SplitPath<T>>;
+
+// Helper type to extract parameter names as an ordered tuple from path segments
+type ExtractParamNamesAsTuple<T extends readonly string[]> = T extends readonly [
+  infer First,
+  ...infer Rest,
+]
+  ? First extends string
+    ? Rest extends readonly string[]
+      ? ExtractParam<First> extends never
+        ? ExtractParamNamesAsTuple<Rest>
+        : [ExtractParam<First>, ...ExtractParamNamesAsTuple<Rest>]
+      : ExtractParam<First> extends never
+        ? []
+        : [ExtractParam<First>]
+    : []
+  : [];
+
+// Type to convert ExtractPathParamNames result to a string tuple with the same number of elements
+export type ExtractPathParamNamesAsTuple<T extends string> = ExtractParamNamesAsTuple<SplitPath<T>>;
+
+// Helper type to create labeled tuple from parameter names
+type CreateLabeledTuple<T extends readonly string[], ElementType = string> = T extends readonly [
+  infer First,
+  ...infer Rest,
+]
+  ? First extends string
+    ? Rest extends readonly string[]
+      ? [{ [K in First]: ElementType }[First], ...CreateLabeledTuple<Rest, ElementType>]
+      : [{ [K in First]: ElementType }[First]]
+    : []
+  : [];
+
+// Type to convert path parameters to a labeled tuple
+export type ExtractPathParamsAsLabeledTuple<
+  T extends string,
+  ElementType = string,
+> = CreateLabeledTuple<ExtractParamNamesAsTuple<SplitPath<T>>, ElementType>;
+
+// Type to check if a path has parameters
+export 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
+ * ```
+ */
+export type QueryParamsHint<TQueryParameters extends string, ValueType = string> = Partial<
+  Record<TQueryParameters, ValueType>
+> &
+  Record<string, ValueType>;
+
+// Runtime utilities
+
+/**
+ * Extract parameter names from a path pattern at runtime.
+ * Examples:
+ * - "/users/:id" => ["id"]
+ * - "/files/**" => ["**"]
+ * - "/files/**:rest" => ["rest"]
+ */
+export function extractPathParams<TPath extends string>(
+  pathPattern: TPath,
+): ExtractPathParamNames<TPath>[] {
+  const segments = pathPattern.split("/").filter((s) => s.length > 0);
+  const names: string[] = [];
+
+  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 as ExtractPathParamNames<TPath>[];
+}
+
+/**
+ * Match an actual path against a path pattern and return extracted params.
+ *
+ * Notes and limitations:
+ * - Named segment ":name" captures a single path segment.
+ * - Wildcard "**" or "**:name" greedily captures the remainder of the path and
+ *   should be placed at the end of the pattern.
+ * - If the path does not match the pattern, an empty object is returned.
+ */
+export function matchPathParams<TPath extends string>(
+  pathPattern: TPath,
+  actualPath: string,
+): ExtractPathParams<TPath> {
+  const patternSegments = pathPattern.split("/").filter((s) => s.length > 0);
+  const actualSegments = actualPath.split("/").filter((s) => s.length > 0);
+
+  const params: Record<string, string> = {};
+
+  let i = 0;
+  let j = 0;
+
+  while (i < patternSegments.length && j < actualSegments.length) {
+    const patternSegment = patternSegments[i];
+    const actualSegment = actualSegments[j];
+
+    if (patternSegment.startsWith(":")) {
+      const name = patternSegment.slice(1);
+      params[name] = decodeURIComponent(actualSegment);
+      i += 1;
+      j += 1;
+      continue;
+    }
+
+    if (patternSegment === "**") {
+      const remainder = actualSegments.slice(j).join("/");
+      params["**"] = remainder ? decodeURIComponent(remainder) : "";
+      // Wildcard consumes the rest; pattern should end here
+      i = patternSegments.length;
+      j = actualSegments.length;
+      break;
+    }
+
+    if (patternSegment.startsWith("**:")) {
+      const name = patternSegment.slice(3);
+      const remainder = actualSegments.slice(j).join("/");
+      params[name] = remainder ? decodeURIComponent(remainder) : "";
+      // Wildcard consumes the rest; pattern should end here
+      i = patternSegments.length;
+      j = actualSegments.length;
+      break;
+    }
+
+    // Literal segment must match exactly
+    if (patternSegment === actualSegment) {
+      i += 1;
+      j += 1;
+      continue;
+    }
+
+    // Mismatch
+    return {} as ExtractPathParams<TPath>;
+  }
+
+  // If there are remaining pattern segments
+  while (i < patternSegments.length) {
+    const remaining = patternSegments[i];
+    if (remaining === "**") {
+      params["**"] = "";
+      i += 1;
+      continue;
+    }
+    if (remaining.startsWith(":")) {
+      const name = remaining.slice(1);
+      params[name] = "";
+      i += 1;
+      continue;
+    }
+    if (remaining.startsWith("**:")) {
+      const name = remaining.slice(3);
+      params[name] = "";
+      i += 1;
+      continue;
+    }
+    // Non-parameter remaining segment without corresponding actual segment → mismatch
+    return {} as ExtractPathParams<TPath>;
+  }
+
+  // If there are remaining actual segments without pattern to match → mismatch
+  if (j < actualSegments.length) {
+    return {} as ExtractPathParams<TPath>;
+  }
+
+  return params as ExtractPathParams<TPath>;
+}
+
+/**
+ * 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"
+ */
+export function buildPath<TPath extends string>(
+  pathPattern: TPath,
+  params: ExtractPathParams<TPath>,
+): string {
+  const patternSegments = pathPattern.split("/");
+
+  const builtSegments: string[] = [];
+
+  for (const segment of patternSegments) {
+    if (segment.length === 0) {
+      // Preserve leading/trailing/duplicate slashes
+      builtSegments.push("");
+      continue;
+    }
+
+    if (segment.startsWith(":")) {
+      const name = segment.slice(1);
+      const value = (params as Record<string, string | undefined>)[name];
+      if (value === undefined) {
+        throw new Error(`Missing value for path parameter :${name}`);
+      }
+      builtSegments.push(encodeURIComponent(value));
+      continue;
+    }
+
+    if (segment === "**") {
+      const value = (params as Record<string, string | undefined>)["**"];
+      if (value === undefined) {
+        throw new Error("Missing value for path wildcard **");
+      }
+      builtSegments.push(value);
+      continue;
+    }
+
+    if (segment.startsWith("**:")) {
+      const name = segment.slice(3);
+      const value = (params as Record<string, string | undefined>)[name];
+      if (value === undefined) {
+        throw new Error(`Missing value for path wildcard **:${name}`);
+      }
+      builtSegments.push(value);
+      continue;
+    }
+
+    // Literal segment
+    builtSegments.push(segment);
+  }
+
+  // Join with '/'. Empty segments preserve leading/trailing slashes
+  return builtSegments.join("/");
+}

package/src/api/internal/response-stream.ts

@@ -0,0 +1,118 @@
+/**
+ * @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 };
+
+export class ResponseStream<TArray> {
+  #writer: WritableStreamDefaultWriter<Uint8Array>;
+  #encoder: TextEncoder;
+  #abortSubscribers: (() => void | Promise<void>)[] = [];
+  #responseReadable: ReadableStream;
+
+  #aborted: boolean = false;
+  #closed: boolean = false;
+
+  /**
+   * Whether the stream has been aborted.
+   */
+  get aborted(): boolean {
+    return this.#aborted;
+  }
+
+  /**
+   * Whether the stream has been closed normally.
+   */
+  get closed(): boolean {
+    return this.#closed;
+  }
+
+  /**
+   * The readable stream that the response is piped to.
+   */
+  get responseReadable(): ReadableStream {
+    return this.#responseReadable;
+  }
+
+  constructor(writable: WritableStream, readable: ReadableStream) {
+    this.#writer = writable.getWriter();
+    this.#encoder = new TextEncoder();
+    const reader = readable.getReader();
+
+    // in case the user disconnects, let the reader know to cancel
+    // this in-turn results in responseReadable being closed
+    // and writeSSE method no longer blocks indefinitely
+    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: Uint8Array | string): Promise<void> {
+    try {
+      if (typeof input === "string") {
+        input = this.#encoder.encode(input);
+      }
+      await this.#writer.write(input);
+    } catch {
+      // Do nothing.
+    }
+  }
+
+  write(
+    input: TArray extends (infer U)[]
+      ? U
+      : Error<"To use a streaming response, outputSchema must be an array.">,
+  ): Promise<void> {
+    return this.writeRaw(JSON.stringify(input) + "\n");
+  }
+
+  sleep(ms: number): Promise<unknown> {
+    return new Promise((res) => setTimeout(res, ms));
+  }
+
+  async close() {
+    try {
+      await this.#writer.close();
+    } catch {
+      // Do nothing. If you want to handle errors, create a stream by yourself.
+    } finally {
+      this.#closed = true;
+    }
+  }
+
+  onAbort(listener: () => void | Promise<void>) {
+    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());
+    }
+  }
+}

package/src/api/internal/route.test.ts

@@ -0,0 +1,56 @@
+import { test, expect } from "vitest";
+import { getMountRoute } from "./route";
+
+test("getMountRoute - default mount route", () => {
+  expect(getMountRoute({ name: "test" })).toBe("/api/test");
+});
+
+test("getMountRoute - custom mount route without trailing slash", () => {
+  expect(getMountRoute({ name: "test", mountRoute: "/custom/path" })).toBe("/custom/path");
+});
+
+test("getMountRoute - custom mount route with trailing slash", () => {
+  expect(getMountRoute({ name: "test", mountRoute: "/custom/path/" })).toBe("/custom/path");
+});
+
+test("getMountRoute - multiple trailing slashes", () => {
+  expect(getMountRoute({ name: "test", mountRoute: "/custom/path///" })).toBe("/custom/path//");
+});
+
+test("getMountRoute - root path", () => {
+  expect(getMountRoute({ name: "test", mountRoute: "/" })).toBe("");
+});
+
+test("getMountRoute - empty name", () => {
+  expect(getMountRoute({ name: "" })).toBe("/api");
+});
+
+test("getMountRoute - name with special characters", () => {
+  expect(getMountRoute({ name: "test-api_v1" })).toBe("/api/test-api_v1");
+});
+
+test("getMountRoute - name with spaces", () => {
+  expect(getMountRoute({ name: "test api" })).toBe("/api/test api");
+});
+
+test("getMountRoute - custom mount route with query parameters", () => {
+  expect(getMountRoute({ name: "test", mountRoute: "/api/v1?version=latest" })).toBe(
+    "/api/v1?version=latest",
+  );
+});
+
+test("getMountRoute - custom mount route with fragment", () => {
+  expect(getMountRoute({ name: "test", mountRoute: "/api/v1#section" })).toBe("/api/v1#section");
+});
+
+test("getMountRoute - deeply nested path", () => {
+  expect(
+    getMountRoute({ name: "deeply-nested", mountRoute: "/api/v1/users/profile/settings" }),
+  ).toBe("/api/v1/users/profile/settings");
+});
+
+test("getMountRoute - deeply nested path with trailing slash", () => {
+  expect(
+    getMountRoute({ name: "deeply-nested", mountRoute: "/api/v1/users/profile/settings/" }),
+  ).toBe("/api/v1/users/profile/settings");
+});

package/src/api/internal/route.ts

@@ -0,0 +1,9 @@
+export function getMountRoute(opts: { mountRoute?: string; name: string }) {
+  const mountRoute = opts.mountRoute ?? `/api/${opts.name}`;
+
+  if (mountRoute.endsWith("/")) {
+    return mountRoute.slice(0, -1);
+  }
+
+  return mountRoute;
+}