@typia/utils 12.0.0-dev.20260225

package/src/http/internal/HttpMigrateRouteFetcher.ts

@@ -0,0 +1,203 @@
+import { IHttpConnection, IHttpResponse } from "@typia/interface";
+
+import { HttpError } from "../HttpError";
+import type { HttpMigration } from "../HttpMigration";
+
+export namespace HttpMigrateRouteFetcher {
+  export const execute = async (
+    props: HttpMigration.IFetchProps,
+  ): Promise<unknown> => {
+    const result: IHttpResponse = await _Propagate("request", props);
+    props.route.success?.media;
+    if (result.status !== 200 && result.status !== 201)
+      throw new HttpError(
+        props.route.method.toUpperCase() as "GET",
+        props.route.path,
+        result.status,
+        result.headers,
+        result.body as string,
+      );
+    return result.body;
+  };
+
+  export const propagate = (
+    props: HttpMigration.IFetchProps,
+  ): Promise<IHttpResponse> => _Propagate("propagate", props);
+}
+
+const _Propagate = async (
+  from: string,
+  props: HttpMigration.IFetchProps,
+): Promise<IHttpResponse> => {
+  // VALIDATE PARAMETERS
+  const error = (message: string) =>
+    new Error(`Error on MigrateRouteFetcher.${from}(): ${message}`);
+  if (Array.isArray(props.parameters)) {
+    if (props.route.parameters.length !== props.parameters.length)
+      throw error(`number of parameters is not matched.`);
+  } else if (
+    props.route.parameters.every(
+      (p) => (props.parameters as Record<string, any>)[p.key] !== undefined,
+    ) === false
+  )
+    throw error(`number of parameters is not matched.`);
+
+  // VALIDATE QUERY
+  if (!!props.route.query !== !!props.query)
+    throw error(`query is not matched.`);
+  else if (!!props.route.body !== (props.body !== undefined))
+    throw error(`body is not matched.`);
+
+  // INIT REQUEST DATA
+  const headers: Record<string, IHttpConnection.HeaderValue | undefined> = {
+    ...(props.connection.headers ?? {}),
+    ...(props.route.body?.type &&
+    props.route.body.type !== "multipart/form-data"
+      ? { "Content-Type": props.route.body.type }
+      : {}),
+  };
+  const init: RequestInit = {
+    ...(props.connection.options ?? {}),
+    method: props.route.method.toUpperCase(),
+    headers: (() => {
+      const output: [string, string][] = [];
+      for (const [key, value] of Object.entries(headers))
+        if (value === undefined) continue;
+        else if (Array.isArray(value))
+          for (const v of value) output.push([key, String(v)]);
+        else output.push([key, String(value)]);
+      return output;
+    })(),
+  };
+  if (props.body !== undefined)
+    init.body = (
+      props.route.body?.type === "application/x-www-form-urlencoded"
+        ? requestQueryBody(props.body)
+        : props.route.body?.type === "multipart/form-data"
+          ? requestFormDataBody(props.body)
+          : props.route.body?.type === "application/json"
+            ? JSON.stringify(props.body)
+            : props.body
+    ) as any;
+
+  // DO REQUEST
+  const resolvedPath: string =
+    props.connection.host.endsWith("/") === false &&
+    props.route.emendedPath.startsWith("/") === false
+      ? `/${getPath(props)}`
+      : getPath(props);
+  const url: URL = new URL(`${props.connection.host}${resolvedPath}`);
+
+  const response: Response = await (props.connection.fetch ?? fetch)(url, init);
+  const status: number = response.status;
+  const out = (body: unknown): IHttpResponse => ({
+    status,
+    headers: responseHeaders(response.headers),
+    body,
+  });
+
+  if (status === 200 || status === 201) {
+    // SUCCESS CASE
+    if (props.route.method.toUpperCase() === "HEAD") return out(undefined);
+    else if (
+      props.route.success === null ||
+      props.route.success.type === "text/plain"
+    )
+      return out(await response.text());
+    else if (props.route.success.type === "application/json") {
+      const text: string = await response.text();
+      return out(text.length ? JSON.parse(text) : undefined);
+    } else if (props.route.success.type === "application/x-www-form-urlencoded")
+      return out(new URLSearchParams(await response.text()));
+    else if (props.route.success.type === "multipart/form-data")
+      return out(await response.formData());
+    throw error("Unsupported response body type.");
+  } else {
+    // FAILURE CASE
+    const type: string = (
+      response.headers.get("content-type") ??
+      response.headers.get("Content-Type") ??
+      ""
+    )
+      .split(";")[0]!
+      .trim();
+    if (type === "" || type.startsWith("text/"))
+      return out(await response.text());
+    else if (type === "application/json") return out(await response.json());
+    else if (type === "application/x-www-form-urlencoded")
+      return out(new URLSearchParams(await response.text()));
+    else if (type === "multipart/form-data")
+      return out(await response.formData());
+    else if (type === "application/octet-stream")
+      return out(await response.blob());
+    return out(await response.text());
+  }
+};
+
+const getPath = (
+  props: Pick<HttpMigration.IFetchProps, "route" | "parameters" | "query">,
+): string => {
+  let path: string = props.route.emendedPath;
+  props.route.parameters.forEach((p, i) => {
+    path = path.replace(
+      `:${p.key}`,
+      encodeURIComponent(
+        String(
+          (Array.isArray(props.parameters)
+            ? props.parameters[i]
+            : props.parameters[p.key]) ?? "null",
+        ),
+      ),
+    );
+  });
+  if (props.route.query) path += getQueryPath(props.query ?? {});
+  return path;
+};
+
+const getQueryPath = (query: Record<string, any>): string => {
+  const variables = new URLSearchParams();
+  for (const [key, value] of Object.entries(query))
+    if (undefined === value) continue;
+    else if (Array.isArray(value))
+      value.forEach((elem: any) => variables.append(key, String(elem)));
+    else variables.set(key, String(value));
+  return 0 === variables.size ? "" : `?${variables.toString()}`;
+};
+
+const requestQueryBody = (input: any): URLSearchParams => {
+  const q: URLSearchParams = new URLSearchParams();
+  for (const [key, value] of Object.entries(input))
+    if (value === undefined) continue;
+    else if (Array.isArray(value))
+      value.forEach((elem) => q.append(key, String(elem)));
+    else q.set(key, String(value));
+  return q;
+};
+const requestFormDataBody = (input: Record<string, any>): FormData => {
+  const encoded: FormData = new FormData();
+  const append = (key: string) => (value: any) => {
+    if (value === undefined) return;
+    else if (typeof File === "function" && value instanceof File)
+      encoded.append(key, value, value.name);
+    else encoded.append(key, value);
+  };
+  for (const [key, value] of Object.entries(input))
+    if (Array.isArray(value)) value.map(append(key));
+    else append(key)(value);
+  return encoded;
+};
+
+const responseHeaders = (
+  headers: Headers,
+): Record<string, string | string[]> => {
+  const output: Record<string, string | string[]> = {};
+  headers.forEach((value, key) => {
+    if (key === "set-cookie") {
+      output[key] ??= [];
+      (output[key] as string[]).push(
+        ...value.split(";").map((str) => str.trim()),
+      );
+    } else output[key] = value;
+  });
+  return output;
+};

package/src/http/internal/LlmDataMerger.ts

@@ -0,0 +1,73 @@
+import { ILlmFunction } from "@typia/interface";
+
+/**
+ * Data combiner for LLM function call.
+ *
+ * @author Samchon
+ */
+export namespace LlmDataMerger {
+  /** Properties of {@link parameters} function. */
+  export interface IProps {
+    /** Target function to call. */
+    function: ILlmFunction;
+
+    /** Arguments composed by LLM (Large Language Model). */
+    llm: object | null;
+
+    /** Arguments composed by human. */
+    human: object | null;
+  }
+
+  /**
+   * Combine LLM and human arguments into one.
+   *
+   * When you compose {@link IHttpLlmApplication} with
+   * {@link IHttpLlmApplication.IConfig.separate} option, then the arguments of
+   * the target function would be separated into two parts; LLM (Large Language
+   * Model) and human.
+   *
+   * In that case, you can combine both LLM and human composed arguments into
+   * one by utilizing this {@link LlmDataMerger.parameters} function, referencing
+   * the target function metadata {@link ILlmFunction.separated}.
+   *
+   * @param props Properties to combine LLM and human arguments with metadata.
+   * @returns Combined arguments
+   */
+  export const parameters = (props: IProps): object => {
+    const separated = props.function.separated;
+    if (separated === undefined)
+      throw new Error(
+        "Error on LlmDataMerger.parameters(): the function parameters are not separated.",
+      );
+    return value(props.llm, props.human) as object;
+  };
+
+  /**
+   * Combine two values into one.
+   *
+   * If both values are objects, then combines them in the properties level.
+   *
+   * Otherwise, returns the latter value if it's not null, otherwise the former
+   * value
+   *
+   * - `return (y ?? x)`
+   *
+   * @param x Value X
+   * @param y Value Y
+   * @returns Combined value
+   */
+  export const value = (x: unknown, y: unknown): unknown =>
+    typeof x === "object" && typeof y === "object" && x !== null && y !== null
+      ? combineObject(x, y)
+      : Array.isArray(x) && Array.isArray(y)
+        ? new Array(Math.max(x.length, y.length))
+            .fill(0)
+            .map((_, i) => value(x[i], y[i]))
+        : (y ?? x);
+
+  const combineObject = (x: any, y: any): any => {
+    const output: any = { ...x };
+    for (const [k, v] of Object.entries(y)) output[k] = value(x[k], v);
+    return output;
+  };
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./converters/index";
+export * from "./http/index";
+export * from "./utils/index";
+export * from "./validators/index";

package/src/utils/ArrayUtil.ts

@@ -0,0 +1,42 @@
+/** @internal */
+export namespace ArrayUtil {
+  export const has = <T>(array: T[], pred: (elem: T) => boolean): boolean =>
+    array.some(pred);
+
+  export const add = <T>(
+    array: T[],
+    value: T,
+    pred: (x: T, y: T) => boolean = (x, y) => x === y,
+  ): boolean => {
+    if (array.some((elem) => pred(elem, value))) return false;
+    array.push(value);
+    return true;
+  };
+
+  export const set = <Key, T>(
+    array: T[],
+    value: T,
+    key: (elem: T) => Key,
+  ): void => {
+    if (array.some((elem) => key(elem) === key(value))) return;
+    array.push(value);
+  };
+
+  export const take = <T>(
+    array: T[],
+    pred: (elem: T) => boolean,
+    init: () => T,
+  ): T => {
+    const index: number = array.findIndex(pred);
+    if (index !== -1) return array[index]!;
+
+    const elem: T = init();
+    array.push(elem);
+    return elem;
+  };
+
+  export const repeat = <T>(
+    count: number,
+    closure: (index: number, count: number) => T,
+  ): T[] => new Array(count).fill("").map((_, index) => closure(index, count));
+}

package/src/utils/MapUtil.ts

@@ -0,0 +1,15 @@
+/** @internal */
+export namespace MapUtil {
+  export const take = <Key, T>(
+    dict: Map<Key, T>,
+    key: Key,
+    generator: () => T,
+  ): T => {
+    const oldbie: T | undefined = dict.get(key);
+    if (oldbie) return oldbie;
+
+    const value: T = generator();
+    dict.set(key, value);
+    return value;
+  };
+}

package/src/utils/NamingConvention.ts

@@ -0,0 +1,205 @@
+/**
+ * String naming convention converters.
+ *
+ * `NamingConvention` converts between common code naming conventions:
+ * camelCase, PascalCase, and snake_case. Handles edge cases like consecutive
+ * uppercase letters (e.g., `XMLParser` → `xml_parser`) and leading
+ * underscores.
+ *
+ * Functions:
+ *
+ * - {@link camel}: Convert to camelCase (`fooBar`)
+ * - {@link pascal}: Convert to PascalCase (`FooBar`)
+ * - {@link snake}: Convert to snake_case (`foo_bar`)
+ * - {@link variable}: Test if string is valid JavaScript variable name
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export namespace NamingConvention {
+  /**
+   * Convert to camelCase.
+   *
+   * @param str Input string
+   * @returns CamelCase string
+   */
+  export function camel(str: string) {
+    return unsnake({
+      plain: (str) =>
+        str.length
+          ? str === str.toUpperCase()
+            ? str.toLocaleLowerCase()
+            : `${str[0]!.toLowerCase()}${str.substring(1)}`
+          : str,
+      snake: (str, i) =>
+        i === 0 ? str.toLowerCase() : capitalize(str.toLowerCase()),
+    })(str);
+  }
+
+  /**
+   * Convert to PascalCase.
+   *
+   * @param str Input string
+   * @returns PascalCase string
+   */
+  export function pascal(str: string) {
+    return unsnake({
+      plain: (str) =>
+        str.length ? `${str[0]!.toUpperCase()}${str.substring(1)}` : str,
+      snake: capitalize,
+    })(str);
+  }
+
+  /**
+   * Convert to snake_case.
+   *
+   * @param str Input string
+   * @returns Snake_case string
+   */
+  export function snake(str: string): string {
+    if (str.length === 0) return str;
+
+    // PREFIX
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    let prefix: string = "";
+    for (let i: number = 0; i < str.length; i++) {
+      if (str[i] === "_") prefix += "_";
+      else break;
+    }
+    if (prefix.length !== 0) str = str.substring(prefix.length);
+
+    const out = (s: string) => `${prefix}${s}`;
+
+    // SNAKE CASE
+    const items: string[] = str.split("_");
+    if (items.length > 1)
+      return out(items.map((s) => s.toLowerCase()).join("_"));
+
+    // CAMEL OR PASCAL CASE
+    const indexes: number[] = [];
+    for (let i: number = 0; i < str.length; i++) {
+      const code: number = str.charCodeAt(i);
+      if (65 <= code && code <= 90) indexes.push(i);
+    }
+    for (let i: number = indexes.length - 1; i > 0; --i) {
+      const now: number = indexes[i]!;
+      const prev: number = indexes[i - 1]!;
+      if (now - prev === 1) indexes.splice(i, 1);
+    }
+    if (indexes.length !== 0 && indexes[0] === 0) indexes.splice(0, 1);
+    if (indexes.length === 0) return str.toLowerCase();
+
+    let ret: string = "";
+    for (let i: number = 0; i < indexes.length; i++) {
+      const first: number = i === 0 ? 0 : indexes[i - 1]!;
+      const last: number = indexes[i]!;
+
+      ret += str.substring(first, last).toLowerCase();
+      ret += "_";
+    }
+    ret += str.substring(indexes[indexes.length - 1]!).toLowerCase();
+    return out(ret);
+  }
+
+  /**
+   * Capitalize first character.
+   *
+   * @param str Input string
+   * @returns Capitalized string
+   */
+  export const capitalize = (str: string): string =>
+    str.length !== 0 ? str[0]!.toUpperCase() + str.slice(1) : str;
+
+  /**
+   * Lowercase first character.
+   *
+   * @param str Input string
+   * @returns Localized string
+   */
+  export const localize = (str: string) => str[0]!.toLowerCase() + str.slice(1);
+
+  /**
+   * Check if string is valid JavaScript variable name.
+   *
+   * @param str String to check
+   * @returns True if valid variable name
+   */
+  export const variable = (str: string): boolean =>
+    reserved(str) === false && /^[a-zA-Z_$][a-zA-Z_$0-9]*$/g.test(str);
+
+  /**
+   * Check if string is JavaScript reserved word.
+   *
+   * @param str String to check
+   * @returns True if reserved word
+   */
+  export const reserved = (str: string): boolean => RESERVED.has(str);
+}
+
+const RESERVED: Set<string> = new Set([
+  "break",
+  "case",
+  "catch",
+  "class",
+  "const",
+  "continue",
+  "debugger",
+  "default",
+  "delete",
+  "do",
+  "else",
+  "enum",
+  "export",
+  "extends",
+  "false",
+  "finally",
+  "for",
+  "function",
+  "if",
+  "import",
+  "in",
+  "instanceof",
+  "module",
+  "new",
+  "null",
+  "package",
+  "public",
+  "private",
+  "protected",
+  "return",
+  "super",
+  "switch",
+  "this",
+  "throw",
+  "true",
+  "try",
+  "typeof",
+  "var",
+  "void",
+  "while",
+  "with",
+]);
+
+const unsnake =
+  (props: {
+    plain: (str: string) => string;
+    snake: (str: string, index: number) => string;
+  }) =>
+  (str: string): string => {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    let prefix: string = "";
+    for (let i: number = 0; i < str.length; i++) {
+      if (str[i] === "_") prefix += "_";
+      else break;
+    }
+    if (prefix.length !== 0) str = str.substring(prefix.length);
+
+    const out = (s: string) => `${prefix}${s}`;
+    if (str.length === 0) return out("");
+
+    const items: string[] = str.split("_").filter((s) => s.length !== 0);
+    return items.length === 0
+      ? out("")
+      : items.length === 1
+        ? out(props.plain(items[0]!))
+        : out(items.map(props.snake).join(""));
+  };

package/src/utils/Singleton.ts

@@ -0,0 +1,17 @@
+/** @internal */
+export class Singleton<T, Args extends any[] = []> {
+  private readonly closure_: (...args: Args) => T;
+  private value_: T | object;
+
+  public constructor(closure: (...args: Args) => T) {
+    this.closure_ = closure;
+    this.value_ = NOT_MOUNTED_YET;
+  }
+
+  public get(...args: Args): T {
+    if (this.value_ === NOT_MOUNTED_YET) this.value_ = this.closure_(...args);
+    return this.value_ as T;
+  }
+}
+
+const NOT_MOUNTED_YET = {};

package/src/utils/StringUtil.ts

@@ -0,0 +1,14 @@
+/** @internal */
+export namespace StringUtil {
+  export const escapeDuplicate = (props: {
+    keep: string[];
+    input: string;
+    escape?: (str: string) => string;
+  }): string =>
+    props.keep.includes(props.input)
+      ? escapeDuplicate({
+          keep: props.keep,
+          input: (props.escape ?? ((str) => `_${str}`))(props.input),
+        })
+      : props.input;
+}

package/src/utils/dedent.ts

@@ -0,0 +1,57 @@
+/**
+ * Remove common leading whitespace from template literal.
+ *
+ * Strips leading/trailing blank lines and removes the minimum indentation level
+ * from all lines.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param strings Template literal strings
+ * @param values Interpolated values
+ * @returns Dedented string
+ */
+export function dedent(
+  strings: TemplateStringsArray,
+  ...values: Array<boolean | number | string>
+): string {
+  // Combine all template string parts to understand the full structure
+  let combined: string = strings[0]!;
+  for (let i = 0; i < values.length; i++) {
+    combined += `__PLACEHOLDER_${i}__` + strings[i + 1];
+  }
+
+  // Split into lines
+  const lines = combined.split("\n");
+
+  // Remove leading and trailing empty lines
+  while (lines.length > 0 && lines[0]!.trim() === "") {
+    lines.shift();
+  }
+  while (lines.length > 0 && lines[lines.length - 1]!.trim() === "") {
+    lines.pop();
+  }
+
+  if (lines.length === 0) return "";
+
+  // Find minimum indentation from non-empty lines
+  const nonEmptyLines = lines.filter((line) => line.trim() !== "");
+  const minIndent = Math.min(
+    ...nonEmptyLines.map((line) => {
+      const match = line.match(/^[ \t]*/);
+      return match ? match[0].length : 0;
+    }),
+  );
+
+  // Remove minimum indentation from all lines
+  const dedentedLines = lines.map((line) => {
+    if (line.trim() === "") return "";
+    return line.slice(minIndent);
+  });
+
+  // Replace placeholders with actual values
+  let result = dedentedLines.join("\n");
+  for (let i = 0; i < values.length; i++) {
+    result = result.replace(`__PLACEHOLDER_${i}__`, String(values[i]));
+  }
+
+  return result;
+}

package/src/utils/index.ts

@@ -0,0 +1,8 @@
+export * from "./ArrayUtil";
+export * from "./MapUtil";
+export * from "./NamingConvention";
+export * from "./Singleton";
+export * from "./StringUtil";
+
+export * from "./dedent";
+export * from "./stringifyValidationFailure";

package/src/utils/internal/EndpointUtil.ts

@@ -0,0 +1,44 @@
+import { NamingConvention } from "../NamingConvention";
+
+export namespace EndpointUtil {
+  export const capitalize = (str: string): string =>
+    str.length !== 0 ? str[0]!.toUpperCase() + str.slice(1).toLowerCase() : str;
+
+  export const pascal = (path: string): string =>
+    splitWithNormalization(path)
+      .filter((str) => str[0] !== "{")
+      .map(NamingConvention.pascal)
+      .join("");
+
+  export const splitWithNormalization = (path: string): string[] =>
+    path
+      .split("/")
+      .map((str) => normalize(str.trim()))
+      .filter((str) => !!str.length);
+
+  export const reJoinWithDecimalParameters = (path: string) => {
+    path = path
+      .split("/")
+      .map((str) =>
+        str[0] === "{" && str[str.length - 1] === "}"
+          ? `:${str.substring(1, str.length - 1)}`
+          : str,
+      )
+      .join("/");
+    return `${path.startsWith("/") ? "" : "/"}${path}`;
+  };
+
+  export const normalize = (str: string): string => {
+    str = str.split(".").join("_").split("-").join("_").trim();
+    if (str.length === 0) return str;
+    else if (NamingConvention.reserved(str)) return `_${str}`;
+    else if (str.length !== 0 && "0" <= str[0]! && str[0]! <= "9")
+      str = `_${str}`;
+    return str;
+  };
+
+  export const escapeDuplicate =
+    (keep: string[]) =>
+    (change: string): string =>
+      keep.includes(change) ? escapeDuplicate(keep)(`_${change}`) : change;
+}