@typia/core 12.0.0-dev.20260225

package/src/programmers/json/JsonValidateParseProgrammer.ts

@@ -0,0 +1,103 @@
+import ts from "typescript";
+
+import { IProgrammerProps } from "../../context/IProgrammerProps";
+import { ITypiaContext } from "../../context/ITypiaContext";
+import { IdentifierFactory } from "../../factories/IdentifierFactory";
+import { StatementFactory } from "../../factories/StatementFactory";
+import { TypeFactory } from "../../factories/TypeFactory";
+import { ValidateProgrammer } from "../ValidateProgrammer";
+import { FunctionProgrammer } from "../helpers/FunctionProgrammer";
+import { FeatureProgrammer } from "../internal/FeatureProgrammer";
+
+export namespace JsonValidateParseProgrammer {
+  export const decompose = (props: {
+    context: ITypiaContext;
+    modulo: ts.LeftHandSideExpression;
+    functor: FunctionProgrammer;
+    type: ts.Type;
+    name: string | undefined;
+  }): FeatureProgrammer.IDecomposed => {
+    const validate: FeatureProgrammer.IDecomposed =
+      ValidateProgrammer.decompose({
+        ...props,
+        context: {
+          ...props.context,
+          options: {
+            ...props.context.options,
+            functional: false,
+            numeric: false,
+          },
+        },
+        config: {
+          equals: false,
+        },
+      });
+    return {
+      functions: validate.functions,
+      statements: [
+        ...validate.statements,
+        StatementFactory.constant({
+          name: "__validate",
+          value: validate.arrow,
+        }),
+      ],
+      arrow: ts.factory.createArrowFunction(
+        undefined,
+        undefined,
+        [IdentifierFactory.parameter("input", TypeFactory.keyword("string"))],
+        props.context.importer.type({
+          file: "typia",
+          name: "IValidation",
+          arguments: [
+            props.context.importer.type({
+              file: "typia",
+              name: "Primitive",
+              arguments: [
+                ts.factory.createTypeReferenceNode(
+                  props.name ??
+                    TypeFactory.getFullName({
+                      checker: props.context.checker,
+                      type: props.type,
+                    }),
+                ),
+              ],
+            }),
+          ],
+        }),
+        undefined,
+        ts.factory.createAsExpression(
+          ts.factory.createCallExpression(
+            ts.factory.createIdentifier("__validate"),
+            undefined,
+            [
+              ts.factory.createCallExpression(
+                ts.factory.createIdentifier("JSON.parse"),
+                undefined,
+                [ts.factory.createIdentifier("input")],
+              ),
+            ],
+          ),
+          ts.factory.createTypeReferenceNode("any"),
+        ),
+      ),
+    };
+  };
+
+  export const write = (props: IProgrammerProps): ts.CallExpression => {
+    const functor: FunctionProgrammer = new FunctionProgrammer(
+      props.modulo.getText(),
+    );
+    const result: FeatureProgrammer.IDecomposed = decompose({
+      context: props.context,
+      modulo: props.modulo,
+      functor,
+      type: props.type,
+      name: props.name,
+    });
+    return FeatureProgrammer.writeDecomposed({
+      modulo: props.modulo,
+      functor,
+      result,
+    });
+  };
+}

package/src/programmers/json/JsonValidateStringifyProgrammer.ts

@@ -0,0 +1,122 @@
+import ts from "typescript";
+
+import { IProgrammerProps } from "../../context/IProgrammerProps";
+import { ITypiaContext } from "../../context/ITypiaContext";
+import { IdentifierFactory } from "../../factories/IdentifierFactory";
+import { StatementFactory } from "../../factories/StatementFactory";
+import { TypeFactory } from "../../factories/TypeFactory";
+import { ValidateProgrammer } from "../ValidateProgrammer";
+import { FunctionProgrammer } from "../helpers/FunctionProgrammer";
+import { FeatureProgrammer } from "../internal/FeatureProgrammer";
+import { JsonStringifyProgrammer } from "./JsonStringifyProgrammer";
+
+export namespace JsonValidateStringifyProgrammer {
+  export const decompose = (props: {
+    context: ITypiaContext;
+    modulo: ts.LeftHandSideExpression;
+    functor: FunctionProgrammer;
+    type: ts.Type;
+    name: string | undefined;
+  }): FeatureProgrammer.IDecomposed => {
+    const validate: FeatureProgrammer.IDecomposed =
+      ValidateProgrammer.decompose({
+        ...props,
+        context: {
+          ...props.context,
+          options: {
+            ...props.context.options,
+            functional: false,
+            finite: true,
+          },
+        },
+        config: {
+          equals: false,
+        },
+      });
+    const stringify: FeatureProgrammer.IDecomposed =
+      JsonStringifyProgrammer.decompose({
+        ...props,
+        validated: true,
+      });
+    return {
+      functions: {
+        ...validate.functions,
+        ...stringify.functions,
+      },
+      statements: [
+        ...validate.statements,
+        ...stringify.statements,
+        StatementFactory.constant({
+          name: "__validate",
+          value: validate.arrow,
+        }),
+        StatementFactory.constant({
+          name: "__stringify",
+          value: stringify.arrow,
+        }),
+      ],
+      arrow: ts.factory.createArrowFunction(
+        undefined,
+        undefined,
+        [IdentifierFactory.parameter("input", TypeFactory.keyword("any"))],
+        props.context.importer.type({
+          file: "typia",
+          name: "IValidation",
+          arguments: [
+            stringify.arrow.type ??
+              ts.factory.createTypeReferenceNode("string"),
+          ],
+        }),
+        undefined,
+        ts.factory.createBlock([
+          StatementFactory.constant({
+            name: "result",
+            value: ts.factory.createAsExpression(
+              ts.factory.createCallExpression(
+                ts.factory.createIdentifier("__validate"),
+                undefined,
+                [ts.factory.createIdentifier("input")],
+              ),
+              TypeFactory.keyword("any"),
+            ),
+          }),
+          ts.factory.createIfStatement(
+            ts.factory.createIdentifier("result.success"),
+            ts.factory.createExpressionStatement(
+              ts.factory.createBinaryExpression(
+                ts.factory.createIdentifier("result.data"),
+                ts.SyntaxKind.EqualsToken,
+                ts.factory.createCallExpression(
+                  ts.factory.createIdentifier("__stringify"),
+                  undefined,
+                  [ts.factory.createIdentifier("input")],
+                ),
+              ),
+            ),
+          ),
+          ts.factory.createReturnStatement(
+            ts.factory.createIdentifier("result"),
+          ),
+        ]),
+      ),
+    };
+  };
+
+  export const write = (props: IProgrammerProps): ts.CallExpression => {
+    const functor: FunctionProgrammer = new FunctionProgrammer(
+      props.modulo.getText(),
+    );
+    const result: FeatureProgrammer.IDecomposed = decompose({
+      context: props.context,
+      modulo: props.modulo,
+      functor,
+      type: props.type,
+      name: props.name,
+    });
+    return FeatureProgrammer.writeDecomposed({
+      modulo: props.modulo,
+      functor,
+      result,
+    });
+  };
+}

package/src/programmers/json/index.ts

@@ -0,0 +1,10 @@
+export * from "./JsonApplicationProgrammer";
+export * from "./JsonAssertParseProgrammer";
+export * from "./JsonAssertStringifyProgrammer";
+export * from "./JsonIsParseProgrammer";
+export * from "./JsonIsStringifyProgrammer";
+export * from "./JsonSchemaProgrammer";
+export * from "./JsonSchemasProgrammer";
+export * from "./JsonStringifyProgrammer";
+export * from "./JsonValidateParseProgrammer";
+export * from "./JsonValidateStringifyProgrammer";

package/src/programmers/llm/LlmApplicationProgrammer.ts

@@ -0,0 +1,422 @@
+import {
+  IJsonSchemaApplication,
+  IJsonSchemaTransformError,
+  ILlmApplication,
+  ILlmFunction,
+  ILlmSchema,
+  IResult,
+  IValidation,
+  OpenApi,
+} from "@typia/interface";
+import { LlmSchemaConverter, LlmTypeChecker } from "@typia/utils";
+import ts from "typescript";
+
+import { ITypiaContext } from "../../context/ITypiaContext";
+import { MetadataFactory } from "../../factories/MetadataFactory";
+import { TypeFactory } from "../../factories/TypeFactory";
+import { MetadataFunction } from "../../schemas/metadata/MetadataFunction";
+import { MetadataObjectType } from "../../schemas/metadata/MetadataObjectType";
+import { MetadataParameter } from "../../schemas/metadata/MetadataParameter";
+import { MetadataSchema } from "../../schemas/metadata/MetadataSchema";
+import { ValidateProgrammer } from "../ValidateProgrammer";
+import { JsonApplicationProgrammer } from "../json/JsonApplicationProgrammer";
+import { LlmSchemaProgrammer } from "./LlmSchemaProgrammer";
+
+/**
+ * Generates LLM function calling application from TypeScript class/interface.
+ *
+ * Converts TypeScript types to {@link ILlmApplication} with function schemas
+ * compatible with LLM function calling. Validates type constraints (single
+ * object parameter, no dynamic keys) and generates runtime validators.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export namespace LlmApplicationProgrammer {
+  export const validate = (props: {
+    config?: Partial<ILlmSchema.IConfig>;
+    metadata: MetadataSchema;
+    explore: MetadataFactory.IExplore;
+  }): string[] => {
+    const top: MetadataSchema = props.metadata;
+    if (props.explore.top === false)
+      if (
+        props.explore.object === top?.objects[0]?.type &&
+        typeof props.explore.property === "string" &&
+        props.metadata.size() === 1 &&
+        props.metadata.nullable === false &&
+        props.metadata.isRequired() === true &&
+        props.metadata.functions.length === 1
+      )
+        return validateFunction(
+          props.explore.property,
+          props.metadata.functions[0]!,
+        );
+      else return LlmSchemaProgrammer.validate(props);
+
+    const output: string[] = [];
+    const validity: boolean =
+      props.metadata.size() === 1 &&
+      props.metadata.objects.length === 1 &&
+      props.metadata.isRequired() === true &&
+      props.metadata.nullable === false;
+    if (validity === false)
+      output.push(
+        "LLM application's generic argument must be a class/interface type.",
+      );
+
+    const object: MetadataObjectType | undefined =
+      props.metadata.objects[0]?.type;
+    if (object !== undefined) {
+      if (object.properties.some((p) => p.key.isSoleLiteral() === false))
+        output.push(
+          "LLM application does not allow dynamic keys on class/interface type.",
+        );
+      let least: boolean = false;
+      for (const p of object.properties) {
+        const name: string = JSON.stringify(p.key.getSoleLiteral()!);
+        const value: MetadataSchema = p.value;
+        if (value.functions.length) {
+          least ||= true;
+          if (validity === false) {
+            if (value.functions.length !== 1 || value.size() !== 1)
+              output.push(
+                `LLM application's function (${name}) type does not allow union type.`,
+              );
+            if (value.isRequired() === false)
+              output.push(
+                `LLM application's function (${name}) type must be required.`,
+              );
+            if (value.nullable === true)
+              output.push(
+                `LLM application's function (${name}) type must not be nullable.`,
+              );
+          }
+
+          const description: string | undefined = concatDescription(
+            JsonApplicationProgrammer.writeDescription({
+              description:
+                p.description ??
+                p.jsDocTags.find((tag) => tag.name === "description")?.text?.[0]
+                  ?.text ??
+                null,
+              jsDocTags: p.jsDocTags,
+              kind: "summary",
+            }),
+          );
+          if (description !== undefined && description.length > 1_024)
+            output.push(
+              `LLM application's function (${name}) description must not exceed 1,024 characters.`,
+            );
+        }
+      }
+      if (least === false)
+        output.push(
+          "LLM application's target type must have at least a function type.",
+        );
+    }
+    return output;
+  };
+
+  const validateFunction = (name: string, func: MetadataFunction): string[] => {
+    const output: string[] = [];
+    const prefix: string = `LLM application's function (${JSON.stringify(name)})`;
+    if (func.output.size() && func.output.isRequired() === false)
+      output.push(
+        `${prefix} return type cannot be optional (union with undefined).`,
+      );
+    if (/^[0-9]/.test(name[0] ?? "") === true)
+      output.push(`${prefix} name cannot start with a number.`);
+    if (/^[a-zA-Z0-9_-]+$/.test(name) === false)
+      output.push(
+        `${prefix} name must contain only alphanumeric characters, underscores, or hyphens.`,
+      );
+    if (name.length > 64)
+      output.push(`${prefix} name cannot exceed 64 characters.`);
+    if (func.parameters.length !== 0 && func.parameters.length !== 1)
+      output.push(
+        `${prefix} must have exactly one parameter or no parameters.`,
+      );
+    if (func.parameters.length !== 0) {
+      const type: MetadataSchema = func.parameters[0]!.type;
+      if (type.size() !== 1 || type.objects.length !== 1)
+        output.push(`${prefix} parameter must be a single object type.`);
+      else {
+        if (
+          type.objects[0]!.type.properties.some(
+            (p) => p.key.isSoleLiteral() === false,
+          )
+        )
+          output.push(`${prefix} parameter cannot have dynamic property keys.`);
+        if (type.isRequired() === false)
+          output.push(
+            `${prefix} parameter cannot be optional (union with undefined).`,
+          );
+        if (type.nullable === true)
+          output.push(`${prefix} parameter cannot be nullable.`);
+      }
+    }
+    return output;
+  };
+
+  export const write = (props: {
+    context: ITypiaContext;
+    modulo: ts.LeftHandSideExpression;
+    metadata: MetadataSchema;
+    config?: Partial<
+      ILlmSchema.IConfig & {
+        equals: boolean;
+      }
+    >;
+    name?: string;
+  }): ILlmApplication => {
+    const metadata: MetadataSchema = MetadataSchema.unalias(props.metadata);
+    const functionParameters: Record<string, MetadataParameter> =
+      Object.fromEntries(
+        metadata.objects[0]!.type.properties.filter(
+          (p) =>
+            p.key.isSoleLiteral() &&
+            p.value.size() === 1 &&
+            p.value.nullable === false &&
+            p.value.isRequired() === true &&
+            MetadataSchema.unalias(p.value).functions.length === 1,
+        )
+          .filter(
+            (p) =>
+              p.jsDocTags.find(
+                (tag) =>
+                  tag.name === "hidden" ||
+                  tag.name === "ignore" ||
+                  tag.name === "internal",
+              ) === undefined,
+          )
+          .map((p) => [
+            p.key.getSoleLiteral()!,
+            MetadataSchema.unalias(p.value).functions[0]!.parameters[0]!,
+          ]),
+      );
+
+    const errorMessages: string[] = [];
+    const application: IJsonSchemaApplication<"3.1"> =
+      JsonApplicationProgrammer.write({
+        version: "3.1",
+        metadata,
+        filter: (p) =>
+          p.jsDocTags.some((tag) => tag.name === "human") === false,
+      });
+    const functions: Array<ILlmFunction | null> = application.functions.map(
+      (func) =>
+        writeFunction({
+          context: props.context,
+          modulo: props.modulo,
+          className: props.name,
+          config: props.config,
+          components: application.components,
+          function: func,
+          errors: errorMessages,
+          parameter: functionParameters[func.name] ?? null,
+        }),
+    );
+    if (functions.some((func) => func === null))
+      throw new Error(
+        "Failed to write LLM application:\n\n" +
+          errorMessages.map((str) => `  - ${str}`).join("\n"),
+      );
+    return {
+      config: {
+        ...LlmSchemaConverter.getConfig(props.config),
+        separate: null,
+        validate: null,
+      },
+      functions: functions.filter((f) => f !== null),
+    };
+  };
+
+  const writeFunction = (props: {
+    context: ITypiaContext;
+    modulo: ts.LeftHandSideExpression;
+    components: OpenApi.IComponents;
+    function: IJsonSchemaApplication.IFunction<OpenApi.IJsonSchema>;
+    parameter: MetadataParameter | null;
+    errors: string[];
+    className?: string;
+    config:
+      | Partial<
+          ILlmSchema.IConfig & {
+            equals: boolean;
+          }
+        >
+      | undefined;
+  }): ILlmFunction | null => {
+    const config: ILlmSchema.IConfig = LlmSchemaConverter.getConfig(
+      props.config,
+    );
+    const parameters: ILlmSchema.IParameters | null = writeParameters({
+      ...props,
+      config,
+      accessor: `$input.${props.function.name}.parameters`,
+    });
+    if (parameters === null) return null;
+    const output: ILlmSchema | null | undefined = writeOutput({
+      parameters,
+      config,
+      components: props.components,
+      schema: props.function.output?.schema ?? null,
+      errors: props.errors,
+      accessor: `$input.${props.function.name}.output`,
+    });
+    if (output === null) return null;
+
+    if (
+      output &&
+      LlmTypeChecker.isReference(output) === false &&
+      output.description === undefined &&
+      !!props.function.output?.description?.length
+    )
+      output.description = props.function.output.description;
+    return {
+      name: props.function.name,
+      parameters,
+      output: output ?? undefined,
+      description: (() => {
+        if (
+          !props.function.summary?.length ||
+          !props.function.description?.length
+        )
+          return props.function.summary || props.function.description;
+        const summary: string = props.function.summary.endsWith(".")
+          ? props.function.summary.slice(0, -1)
+          : props.function.summary;
+        return props.function.description.startsWith(summary)
+          ? props.function.description
+          : summary + ".\n\n" + props.function.description;
+      })(),
+      deprecated: props.function.deprecated,
+      tags: props.function.tags,
+      validate: writeValidator({
+        context: props.context,
+        modulo: props.modulo,
+        parameter: props.parameter,
+        name: props.function.name,
+        className: props.className,
+        equals: props.config?.equals ?? false,
+      }),
+    };
+  };
+
+  const writeParameters = (props: {
+    components: OpenApi.IComponents;
+    function: IJsonSchemaApplication.IFunction<OpenApi.IJsonSchema>;
+    errors: string[];
+    accessor: string;
+    config: ILlmSchema.IConfig;
+  }): ILlmSchema.IParameters | null => {
+    const schema: OpenApi.IJsonSchema.IObject | OpenApi.IJsonSchema.IReference =
+      (props.function.parameters[0]?.schema as
+        | OpenApi.IJsonSchema.IObject
+        | OpenApi.IJsonSchema.IReference) ?? {
+        type: "object",
+        properties: {},
+        additionalProperties: false,
+        required: [],
+      };
+    const result: IResult<ILlmSchema.IParameters, IJsonSchemaTransformError> =
+      LlmSchemaConverter.parameters({
+        config: props.config,
+        components: props.components,
+        schema: {
+          ...schema,
+          title: schema.title ?? props.function.parameters[0]?.title,
+          description:
+            schema.description ?? props.function.parameters[0]?.description,
+        },
+        accessor: props.accessor,
+      });
+    if (result.success === false) {
+      props.errors.push(
+        ...result.error.reasons.map((r) => `  - ${r.accessor}: ${r.message}`),
+      );
+      return null;
+    }
+    return result.value;
+  };
+
+  const writeOutput = (props: {
+    parameters: ILlmSchema.IParameters;
+    components: OpenApi.IComponents;
+    config: ILlmSchema.IConfig;
+    schema: OpenApi.IJsonSchema | null;
+    errors: string[];
+    accessor: string;
+  }): ILlmSchema | null | undefined => {
+    if (props.schema === null) return undefined;
+    const result: IResult<ILlmSchema, IJsonSchemaTransformError> =
+      LlmSchemaConverter.schema({
+        config: props.config,
+        components: props.components,
+        schema: props.schema,
+        $defs: (props.parameters as any).$defs,
+        accessor: props.accessor,
+      });
+    if (result.success === false) {
+      props.errors.push(
+        ...result.error.reasons.map((r) => `  - ${r.accessor}: ${r.message}`),
+      );
+      return null;
+    }
+    return result.value;
+  };
+
+  const writeValidator = (props: {
+    context: ITypiaContext;
+    modulo: ts.LeftHandSideExpression;
+    parameter: MetadataParameter | null;
+    name: string;
+    equals: boolean;
+    className?: string;
+  }): ((props: unknown) => IValidation<unknown>) => {
+    if (props.parameter === null)
+      return ValidateProgrammer.write({
+        ...props,
+        type: props.context.checker.getTypeFromTypeNode(
+          TypeFactory.keyword("any"),
+        ),
+        config: {
+          equals: props.equals,
+        },
+        name: undefined,
+      }) as any;
+
+    const type: ts.Type | undefined = props.parameter.tsType;
+    if (type === undefined)
+      // unreachable
+      throw new Error(
+        "Failed to write LLM application's function validator. You don't have to call `LlmApplicationOfValidator.write()` function by yourself, but only by the `typia.llm.applicationOfValidate()` function.",
+      );
+    return ValidateProgrammer.write({
+      ...props,
+      type: props.parameter.tsType!,
+      config: {
+        equals: props.equals,
+      },
+      name: props.className
+        ? `Parameters<${props.className}[${JSON.stringify(props.name)}]>[0]`
+        : undefined,
+    }) satisfies ts.CallExpression as any as (
+      props: unknown,
+    ) => IValidation<unknown>;
+  };
+}
+
+const concatDescription = (p: {
+  summary?: string | undefined;
+  description?: string | undefined;
+}): string | undefined => {
+  if (!p.summary?.length || !p.description?.length)
+    return p.summary ?? p.description;
+  const summary: string = p.summary.endsWith(".")
+    ? p.summary.slice(0, -1)
+    : p.summary;
+  return p.description.startsWith(summary)
+    ? p.description
+    : summary + ".\n\n" + p.description;
+};