fix(utils): enhance LlmJson.{parse|stringify} logics. (#1768)

* enhance logics

* `parseLenientJson` completed.

* enhanced

* complete parseLenientJson

* documentation

* fix type

* fix import path

* fix typo

* Rename from `ILlmJsonParseResult` to `IJsonParseResult`

* publish next version

* more example case

Author: samchon

benchmark/package.json

@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@typia/benchmark",
-  "version": "12.0.0-dev.20260306",
+  "version": "12.0.0-dev.20260307",
   "description": "Benchmark program of typia performance",
   "main": "bin/index.js",
   "scripts": {

config/package.json

@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@typia/config",
-  "version": "12.0.0-dev.20260306",
+  "version": "12.0.0-dev.20260307",
   "description": "Shared build configuration for typia packages",
   "devDependencies": {
     "@rollup/plugin-commonjs": "catalog:rollup",

examples/package.json

@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@typia/examples",
-  "version": "12.0.0-dev.20260306",
+  "version": "12.0.0-dev.20260307",
   "description": "Example codes for typia website",
   "scripts": {
     "build": "rimraf bin && cross-env NODE_OPTIONS=\"--no-experimental-strip-types -r ts-node/register\" tsc && prettier --write bin/**/*.js",

package.json

@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@typia/station",
-  "version": "12.0.0-dev.20260306",
+  "version": "12.0.0-dev.20260307",
   "description": "Typia Station",
   "scripts": {
     "build": "pnpm --filter=./packages/* -r build",

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typia/core",
-  "version": "12.0.0-dev.20260306",
+  "version": "12.0.0-dev.20260307",
   "description": "Superfast runtime validators with only one line",
   "main": "src/index.ts",
   "exports": {

packages/interface/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typia/interface",
-  "version": "12.0.0-dev.20260306",
+  "version": "12.0.0-dev.20260307",
   "description": "Superfast runtime validators with only one line",
   "main": "src/index.ts",
   "exports": {

packages/interface/src/http/IHttpLlmFunction.ts

@@ -1,92 +1,31 @@
 import { OpenApi } from "../openapi/OpenApi";
-import { ILlmSchema } from "../schema/ILlmSchema";
-import { IValidation } from "../schema/IValidation";
+import { ILlmFunction } from "../schema/ILlmFunction";
 import { IHttpMigrateRoute } from "./IHttpMigrateRoute";
 
 /**
  * LLM function calling schema from OpenAPI operation.
  *
- * `IHttpLlmFunction` represents a single HTTP endpoint converted to LLM
- * function calling format. Generated from {@link OpenApi.IOperation} as part of
- * {@link IHttpLlmApplication}.
+ * Extends {@link ILlmFunction} with HTTP-specific properties. Generated from
+ * {@link OpenApi.IOperation} as part of {@link IHttpLlmApplication}.
  *
- * Key properties:
+ * - {@link method}, {@link path}: HTTP endpoint info
+ * - {@link operation}: Source OpenAPI operation
+ * - {@link route}: Source migration route
  *
- * - {@link name}: Function name (max 64 chars for OpenAI compatibility)
- * - {@link parameters}: Input schema with path/query/body merged
- * - {@link output}: Response schema (undefined if void)
- * - {@link description}: Critical for LLM function selection
- * - {@link validate}: Built-in argument validator for error feedback
- *
- * The {@link validate} function is essential: LLMs make frequent type errors
- * (e.g., `"123"` instead of `123`). Validate and retry improves success rate
- * from ~50% to 99%.
+ * Inherits {@link parse} and {@link validate} from {@link ILlmFunction}.
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export interface IHttpLlmFunction {
+export interface IHttpLlmFunction extends ILlmFunction {
   /** HTTP method of the endpoint. */
   method: "get" | "post" | "patch" | "put" | "delete";
 
   /** Path of the endpoint. */
   path: string;
 
-  /**
-   * Function name composed from {@link IHttpMigrateRoute.accessor}.
-   *
-   * @maxLength 64
-   */
-  name: string;
-
-  /**
-   * Parameter schema.
-   *
-   * With keyword mode: single object with pathParameters, query, body merged.
-   * Without keyword mode: array of [pathParameters..., query?, body?].
-   */
-  parameters: ILlmSchema.IParameters;
-
-  /**
-   * Return type as an object parameters schema.
-   *
-   * Wraps the return type in an {@link ILlmSchema.IParameters} object with
-   * `$defs` for shared type definitions and `properties` for the structured
-   * output. `undefined` if the endpoint returns void.
-   */
-  output?: ILlmSchema.IParameters | undefined;
-
-  /** Function description for LLM context. Critical for function selection. */
-  description?: string | undefined;
-
-  /** Whether the function is deprecated. */
-  deprecated?: boolean | undefined;
-
   /** Category tags from {@link OpenApi.IOperation.tags}. */
   tags?: string[];
 
-  /**
-   * Lenient JSON parser with schema-based coercion.
-   *
-   * Parses incomplete/malformed JSON (unclosed brackets, trailing commas,
-   * unclosed strings) and coerces double-stringified values using the
-   * function's own {@link parameters} schema.
-   *
-   * This does NOT perform type validation — use {@link validate} after
-   * parsing to check the result.
-   *
-   * @param str Raw JSON string from LLM output
-   * @returns Validation result with parsed data or syntax errors
-   */
-  parse: (str: string) => IValidation<unknown>;
-
-  /**
-   * Validates LLM-composed arguments.
-   *
-   * LLMs frequently make type errors. Use this to provide validation feedback
-   * and retry. Success rate improves from ~50% to 99% on retry.
-   */
-  validate: (args: unknown) => IValidation<unknown>;
-
   /** Returns the source {@link OpenApi.IOperation}. */
   operation: () => OpenApi.IOperation;
 

packages/interface/src/schema/IJsonParseResult.ts

@@ -0,0 +1,136 @@
+import { DeepPartial } from "../typings/DeepPartial";
+
+/**
+ * Result of lenient JSON parsing.
+ *
+ * `IJsonParseResult<T>` represents the result of parsing JSON that may be
+ * incomplete, malformed, or contain non-standard syntax (e.g., unquoted keys,
+ * trailing commas, missing quotes).
+ *
+ * Unlike standard JSON parsing which fails on any syntax error, lenient parsing
+ * attempts to recover as much data as possible while reporting issues.
+ *
+ * Check the {@link IJsonParseResult.success} discriminator:
+ *
+ * - `true` → {@link IJsonParseResult.ISuccess} with parsed
+ *   {@link IJsonParseResult.ISuccess.data}
+ * - `false` → {@link IJsonParseResult.IFailure} with partial
+ *   {@link IJsonParseResult.IFailure.data} and
+ *   {@link IJsonParseResult.IFailure.errors}
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @template T The expected type after successful parsing
+ */
+export type IJsonParseResult<T = unknown> =
+  | IJsonParseResult.ISuccess<T>
+  | IJsonParseResult.IFailure<T>;
+
+export namespace IJsonParseResult {
+  /**
+   * Successful parsing result.
+   *
+   * Indicates the JSON was parsed without any errors. The data may still have
+   * been recovered from non-standard syntax (e.g., unquoted keys, trailing
+   * commas), but no information was lost.
+   *
+   * @template T The parsed type
+   */
+  export interface ISuccess<T = unknown> {
+    /**
+     * Success discriminator.
+     *
+     * Always `true` for successful parsing.
+     */
+    success: true;
+
+    /** The parsed data with correct type. */
+    data: T;
+  }
+
+  /**
+   * Failed parsing result with partial data and errors.
+   *
+   * Indicates the JSON had syntax errors that could not be fully recovered. The
+   * {@link data} contains whatever could be parsed, and {@link errors} describes
+   * what went wrong.
+   *
+   * @template T The expected type (data may be partial)
+   */
+  export interface IFailure<T = unknown> {
+    /**
+     * Success discriminator.
+     *
+     * Always `false` for failed parsing.
+     */
+    success: false;
+
+    /**
+     * Partially parsed data.
+     *
+     * Contains whatever could be recovered from the malformed JSON. May be
+     * incomplete or have missing properties.
+     */
+    data: DeepPartial<T>;
+
+    /**
+     * The original input string that was parsed.
+     *
+     * Preserved for debugging or error correction purposes.
+     */
+    input: string;
+
+    /**
+     * Array of parsing errors encountered.
+     *
+     * Each error describes a specific issue found during parsing, with location
+     * and suggested fix.
+     */
+    errors: IError[];
+  }
+
+  /**
+   * Detailed information about a parsing error.
+   */
+  export interface IError {
+    /**
+     * Property path to the error location.
+     *
+     * A dot-notation path from the root to the error location. Uses `$input` as
+     * the root.
+     *
+     * @example
+     *   $input.user.email;
+     *
+     * @example
+     *   $input.items[0].price;
+     */
+    path: string;
+
+    /**
+     * What was expected at this location.
+     *
+     * @example
+     *   JSON value (string, number, boolean, null, object, or array)
+     *
+     * @example
+     *   quoted string
+     *
+     * @example
+     *   ":";
+     */
+    expected: string;
+
+    /**
+     * Description of what was actually found.
+     *
+     * Human/AI-readable message explaining the issue.
+     *
+     * @example
+     *   unquoted string 'abc' - did you forget quotes?
+     *
+     * @example
+     *   missing opening quote for 'hello'
+     */
+    value: unknown;
+  }
+}

packages/interface/src/schema/ILlmFunction.ts

@@ -1,20 +1,18 @@
+import { IJsonParseResult } from "./IJsonParseResult";
 import { ILlmSchema } from "./ILlmSchema";
 import { IValidation } from "./IValidation";
 
 /**
- * LLM function calling metadata.
+ * LLM function calling schema for TypeScript functions.
  *
- * `ILlmFunction` describes a single callable function for LLM agents. Generated
- * as part of {@link ILlmApplication} by `typia.llm.application<App>()`.
+ * Generated by `typia.llm.application<App>()` as part of
+ * {@link ILlmApplication}.
  *
- * Contains the function {@link name} (max 64 chars for OpenAI),
- * {@link parameters} schema for input types, optional {@link output} schema for
- * return type, and {@link description} for LLM to understand the function's
- * purpose.
- *
- * The built-in {@link validate} function checks LLM-generated arguments against
- * the schema, enabling auto-correction when the LLM makes type errors (e.g.,
- * returning `"123"` instead of `123`).
+ * - {@link name}: Function identifier (max 64 chars for OpenAI)
+ * - {@link parameters}: Input schema, {@link output}: Return schema
+ * - {@link description}: Guides LLM function selection
+ * - {@link parse}: Lenient JSON parser with type coercion
+ * - {@link validate}: Argument validator for LLM error correction
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
@@ -79,17 +77,22 @@ export interface ILlmFunction {
   /**
    * Lenient JSON parser with schema-based coercion.
    *
-   * Parses incomplete/malformed JSON (unclosed brackets, trailing commas,
-   * unclosed strings) and coerces double-stringified values using the
-   * function's own {@link parameters} schema.
+   * Handles incomplete/malformed JSON commonly produced by LLMs:
+   *
+   * - Unclosed brackets, strings, trailing commas
+   * - JavaScript-style comments (`//` and multi-line)
+   * - Unquoted object keys, incomplete keywords (`tru`, `fal`, `nul`)
+   * - Markdown code block extraction, junk prefix skipping
+   *
+   * Also coerces double-stringified values (`"42"` → `42`) using the
+   * {@link parameters} schema.
    *
-   * This does NOT perform type validation — use {@link validate} after
-   * parsing to check the result.
+   * Type validation is NOT performed — use {@link validate} after parsing.
    *
    * @param str Raw JSON string from LLM output
-   * @returns Validation result with parsed data or syntax errors
+   * @returns Parse result with data on success, or partial data with errors
    */
-  parse: (str: string) => IValidation<unknown>;
+  parse: (str: string) => IJsonParseResult<unknown>;
 
   /**
    * Validates LLM-generated arguments against the schema.

packages/interface/src/schema/index.ts

@@ -11,3 +11,4 @@ export * from "./ILlmController";
 export * from "./ILlmApplication";
 export * from "./ILlmFunction";
 export * from "./ILlmSchema";
+export * from "./IJsonParseResult";