feat(interface): re-write concise descriptions.#1741
Merged
samchon merged 10 commits intofeat/monorepofrom Feb 21, 2026
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR rewrites and expands concise descriptions (JSDoc/comments) across typia’s packages (interface/core/transform/utils) to better document OpenAPI/LLM/validation/transformer utilities, with a few small formatting and code adjustments.
Changes:
- Added/rewrote JSDoc across many public APIs (validators, converters, HTTP utilities, interface typings/tags, transformer/core internals).
- Refactored/normalized example/comment formatting in internal example sources and minor whitespace/import ordering tweaks.
- Added a root
formatscript and adjusted some embedded example strings.
Reviewed changes
Copilot reviewed 139 out of 141 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| website/src/compiler/PlaygroundExampleStorage.ts | Reformat embedded playground example source strings. |
| packages/utils/src/validators/SwaggerV2TypeChecker.ts | Add namespace-level JSDoc for Swagger v2 type guards. |
| packages/utils/src/validators/OpenApiValidator.ts | Add module-level JSDoc describing validator use cases. |
| packages/utils/src/validators/OpenApiV3_1TypeChecker.ts | Add namespace-level JSDoc for OpenAPI v3.1 raw schema guards. |
| packages/utils/src/validators/OpenApiV3TypeChecker.ts | Add namespace-level JSDoc for OpenAPI v3.0 raw schema guards. |
| packages/utils/src/validators/OpenApiTypeChecker.ts | Rewrite existing JSDoc to clarify “emended” OpenAPI format and utilities. |
| packages/utils/src/utils/stringifyValidationFailure.ts | Add JSDoc describing LLM feedback formatting output. |
| packages/utils/src/utils/dedent.ts | Add JSDoc and translate inline comments to English. |
| packages/utils/src/utils/NamingConvention.ts | Add function-level JSDoc for naming helpers. |
| packages/utils/src/http/HttpMigration.ts | Add/expand JSDoc for OpenAPI→HTTP migration utilities and types. |
| packages/utils/src/http/HttpLlm.ts | Rewrite JSDoc to be more structured and workflow-oriented. |
| packages/utils/src/http/HttpError.ts | Rewrite JSDoc to be more concise and link related utilities. |
| packages/utils/src/converters/OpenApiConverter.ts | Add extensive JSDoc for version conversion APIs. |
| packages/utils/src/converters/LlmSchemaConverter.ts | Add module/function JSDoc for OpenAPI→LLM schema conversion. |
| packages/typia/src/reflect.ts | Rewrite JSDoc and add overload docs for reflect helpers. |
| packages/typia/src/internal/_randomString.ts | Change min/max assignment expressions using satisfies (code change). |
| packages/typia/src/internal/_randomArray.ts | Change minItems assignment expression using satisfies (code change). |
| packages/typia/src/executable/TypiaGenerateWizard.ts | Remove an extra blank line in imports. |
| packages/typia/src/TypeGuardError.ts | Rewrite/condense JSDoc and examples for the error type. |
| packages/transform/src/index.ts | Add entry-point JSDoc for the transformer export. |
| packages/transform/src/features/protobuf/ProtobufMessageTransformer.ts | Normalize import ordering. |
| packages/transform/src/features/misc/MiscLiteralsTransformer.ts | Normalize import ordering. |
| packages/transform/src/features/functional/FunctionalGenericTransformer.ts | Normalize import ordering. |
| packages/transform/src/features/RandomTransformer.ts | Normalize import ordering. |
| packages/transform/src/features/CreateRandomTransformer.ts | Normalize import ordering. |
| packages/transform/src/TransformerError.ts | Add/expand class/interface JSDoc for transformer errors. |
| packages/transform/src/NodeTransformer.ts | Add namespace-level JSDoc. |
| packages/transform/src/ImportTransformer.ts | Add namespace-level JSDoc. |
| packages/transform/src/ITransformProps.ts | Add interface-level/property JSDoc. |
| packages/transform/src/ITransformOptions.ts | Rewrite option docs for finite/numeric/functional/undefined. |
| packages/transform/src/FileTransformer.ts | Add namespace-level JSDoc. |
| packages/transform/src/CallExpressionTransformer.ts | Add namespace-level JSDoc. |
| packages/interface/src/utils/IReadableURLSearchParams.ts | Rewrite JSDoc for subset URLSearchParams interface. |
| packages/interface/src/utils/IRandomGenerator.ts | Condense JSDoc across generator interface and CustomMap. |
| packages/interface/src/typings/internal/ValueOf.ts | Add JSDoc for boxed-primitive extraction helper type. |
| packages/interface/src/typings/internal/NativeClass.ts | Add JSDoc for native class union type. |
| packages/interface/src/typings/internal/IsTuple.ts | Add JSDoc for tuple detection helper type. |
| packages/interface/src/typings/internal/Equal.ts | Rewrite JSDoc to clarify “exact equality” type utility. |
| packages/interface/src/typings/ValidationPipe.ts | Add JSDoc for discriminated validation result type. |
| packages/interface/src/typings/SpecialFields.ts | Add JSDoc for key-extraction helper type. |
| packages/interface/src/typings/SnakeCase.ts | Rewrite JSDoc for recursive key transformation type. |
| packages/interface/src/typings/Resolved.ts | Rewrite JSDoc for method-erasing resolved type. |
| packages/interface/src/typings/ProtobufAtomic.ts | Add JSDoc and clarify nested numeric subsets. |
| packages/interface/src/typings/Primitive.ts | Rewrite JSDoc for JSON-primitive conversion type. |
| packages/interface/src/typings/PascalCase.ts | Rewrite JSDoc for recursive key transformation type. |
| packages/interface/src/typings/OmitNever.ts | Add JSDoc for never-property omission helper. |
| packages/interface/src/typings/ClassProperties.ts | Add JSDoc for non-function property extraction type. |
| packages/interface/src/typings/CamelCase.ts | Rewrite JSDoc for recursive key transformation type. |
| packages/interface/src/typings/Atomic.ts | Add JSDoc for atomic type utilities. |
| packages/interface/src/typings/AssertionGuard.ts | Rewrite JSDoc for assertion guard function type. |
| packages/interface/src/tags/UniqueItems.ts | Rewrite JSDoc and examples for unique-items tag. |
| packages/interface/src/tags/Type.ts | Rewrite JSDoc and examples for numeric wire/precision tag. |
| packages/interface/src/tags/TagBase.ts | Expand JSDoc explaining phantom tag metadata model. |
| packages/interface/src/tags/Sequence.ts | Rewrite JSDoc and examples for protobuf field numbering tag. |
| packages/interface/src/tags/Pattern.ts | Rewrite JSDoc and examples for regex constraint tag. |
| packages/interface/src/tags/MultipleOf.ts | Rewrite JSDoc and examples for divisibility constraint tag. |
| packages/interface/src/tags/Minimum.ts | Rewrite JSDoc and examples for inclusive minimum tag. |
| packages/interface/src/tags/MinLength.ts | Rewrite JSDoc and examples for min-length tag. |
| packages/interface/src/tags/MinItems.ts | Rewrite JSDoc and examples for min-items tag. |
| packages/interface/src/tags/Maximum.ts | Rewrite JSDoc and examples for inclusive maximum tag. |
| packages/interface/src/tags/MaxLength.ts | Rewrite JSDoc and examples for max-length tag. |
| packages/interface/src/tags/MaxItems.ts | Rewrite JSDoc and examples for max-items tag. |
| packages/interface/src/tags/JsonSchemaPlugin.ts | Rewrite JSDoc and examples for schema plugin metadata tag. |
| packages/interface/src/tags/Format.ts | Rewrite JSDoc and expand supported format list docs. |
| packages/interface/src/tags/ExclusiveMinimum.ts | Rewrite JSDoc and examples for exclusive minimum tag. |
| packages/interface/src/tags/ExclusiveMaximum.ts | Rewrite JSDoc and examples for exclusive maximum tag. |
| packages/interface/src/tags/Examples.ts | Rewrite JSDoc and examples for multiple examples tag. |
| packages/interface/src/tags/Example.ts | Rewrite JSDoc and examples for single example tag. |
| packages/interface/src/tags/Default.ts | Rewrite JSDoc clarifying metadata-only default behavior. |
| packages/interface/src/tags/ContentMediaType.ts | Rewrite JSDoc clarifying metadata-only media type behavior. |
| packages/interface/src/tags/Constant.ts | Rewrite JSDoc and examples for literal documentation tag. |
| packages/interface/src/schema/IValidation.ts | Rewrite JSDoc for structured validation result. |
| packages/interface/src/schema/IResult.ts | Rewrite/expand JSDoc for result/either type. |
| packages/interface/src/schema/ILlmFunction.ts | Rewrite/expand JSDoc for LLM function schema and validation. |
| packages/interface/src/schema/ILlmController.ts | Condense JSDoc and clarify protocol alternatives. |
| packages/interface/src/schema/ILlmApplication.ts | Rewrite/expand JSDoc for app config and separation/validation hooks. |
| packages/interface/src/schema/IJsonSchemaTransformError.ts | Rewrite JSDoc describing transformation failure reasons. |
| packages/interface/src/schema/IJsonSchemaCollection.ts | Rewrite/condense JSDoc for multi-type schema collections. |
| packages/interface/src/schema/IJsonSchemaAttribute.ts | Expand base attribute JSDoc and type-specific variants. |
| packages/interface/src/schema/IJsonSchemaApplication.ts | Add extensive JSDoc for function-application schemas. |
| packages/interface/src/protobuf/ProtobufWire.ts | Add JSDoc for protobuf wire type enum. |
| packages/interface/src/metadata/IMetadataTypeTag.ts | Add JSDoc for metadata tag structure. |
| packages/interface/src/metadata/IMetadataSchemaUnit.ts | Add JSDoc for single-type metadata schema unit. |
| packages/interface/src/metadata/IMetadataSchemaCollection.ts | Add JSDoc for multi-type metadata schema collection. |
| packages/interface/src/metadata/IMetadataSchema.ts | Add extensive JSDoc describing metadata schema structure. |
| packages/interface/src/metadata/IMetadataComponents.ts | Add JSDoc for shared metadata component pools. |
| packages/interface/src/metadata/IJsDocTagInfo.ts | Add JSDoc for extracted JSDoc tag payloads. |
| packages/interface/src/http/IHttpResponse.ts | Rewrite/expand JSDoc for structured HTTP response interface. |
| packages/interface/src/http/IHttpMigrateApplication.ts | Rewrite JSDoc clarifying purpose vs LLM app and error handling. |
| packages/interface/src/http/IHttpLlmApplication.ts | Rewrite/condense JSDoc clarifying failure causes and config options. |
| packages/interface/src/http/IHttpConnection.ts | Rewrite/expand JSDoc for fetch options, Node polyfill guidance. |
| packages/core/src/schemas/metadata/MetadataStorage.ts | Add class-level JSDoc for metadata caching/storage. |
| packages/core/src/schemas/metadata/MetadataSchema.ts | Add class-level JSDoc for internal metadata representation. |
| packages/core/src/schemas/metadata/IMetadataDictionary.ts | Add JSDoc for dictionary used in metadata deserialization. |
| packages/core/src/programmers/llm/LlmApplicationProgrammer.ts | Add JSDoc describing LLM application generation. |
| packages/core/src/programmers/iterate/stringify_dynamic_properties.ts | Remove an extra blank line. |
| packages/core/src/programmers/iterate/prune_object_properties.ts | Remove an extra blank line. |
| packages/core/src/programmers/iterate/check_template.ts | Remove an extra blank line. |
| packages/core/src/programmers/ValidateProgrammer.ts | Add module/type JSDoc for validation code generation. |
| packages/core/src/programmers/RandomProgrammer.ts | Add module/type JSDoc for random data code generation. |
| packages/core/src/programmers/IsProgrammer.ts | Add module-level JSDoc for type guard generation. |
| packages/core/src/programmers/ImportProgrammer.ts | Add class-level JSDoc for import management. |
| packages/core/src/programmers/AssertProgrammer.ts | Add module/type JSDoc for assertion code generation. |
| packages/core/src/factories/internal/metadata/iterate_metadata_comment_tags.ts | Remove an extra blank line. |
| packages/core/src/factories/MetadataFactory.ts | Add/expand JSDoc for metadata extraction APIs and types. |
| packages/core/src/factories/IdentifierFactory.ts | Add module-level JSDoc for identifier/property access factories. |
| packages/core/src/factories/ExpressionFactory.ts | Add module-level JSDoc for expression factories and transpile helper. |
| packages/core/src/factories/CommentFactory.ts | Add module-level JSDoc for comment extraction utilities. |
| packages/core/src/context/TransformerError.ts | Add/expand JSDoc mirroring transform package error docs. |
| packages/core/src/context/ITypiaContext.ts | Add extensive JSDoc for the transformation context structure. |
| packages/core/src/context/ITransformOptions.ts | Add extensive JSDoc for transformer options semantics. |
| packages/core/src/context/IProgrammerProps.ts | Add extensive JSDoc for programmer input props. |
| package.json | Add format script for running prettier over key directories. |
| internals/examples/src/validators/is-type-tag.ts | Condense block comments into single-line JSDoc comments. |
| internals/examples/src/validators/is-comment-tag.ts | Condense block comments into single-line JSDoc comments. |
| internals/examples/src/random/random-comment-tag.ts | Condense block comments into single-line JSDoc comments. |
| internals/examples/src/protobuf/message-comment-tag.ts | Normalize whitespace and condense comment-tag blocks. |
| internals/examples/src/protobuf/decode.ts | Normalize whitespace/trailing newline formatting. |
| internals/examples/src/misc/assertPrune.ts | Condense comment-tag blocks into single-line comments. |
| internals/examples/src/misc/assertClone.ts | Condense comment-tag blocks into single-line comments. |
| internals/examples/src/llm/IMember.ts | Rewrite @description indentation guidance in comment. |
| internals/examples/src/llm/IBbsArticle.ts | Wrap comment lines and condense property docs. |
| internals/examples/src/json/schemas.ts | Condense property doc blocks into single-line comments. |
| internals/examples/src/json/schemas-comment-tags.ts | Reorder tags and change hidden marker tag usage. |
| internals/benchmark/src/structures/pure/ObjectUnionImplicit.ts | Fix indentation in ternary expression. |
Comment on lines
+24
to
+29
| * interface Preferences { | ||
| * // No duplicate tags allowed | ||
| * tags: (string & UniqueItems)[]; | ||
| * // Unique user IDs | ||
| * favoriteUserIds: (number & UniqueItems)[]; | ||
| * } |
There was a problem hiding this comment.
The example applies UniqueItems to the element type ((string & UniqueItems)[]), but UniqueItems targets arrays (target: "array"). This example won’t express “array elements are unique” as intended.
Suggestion: change examples to apply the tag to the array type, e.g. tags: string[] & UniqueItems and favoriteUserIds: number[] & UniqueItems.
Comment on lines
18
to
+26
| * @example | ||
| * // Require at least 3 selections | ||
| * type MultipleChoice = number[] & MinItems<3>; | ||
| * interface Order { | ||
| * // Must have at least 1 item | ||
| * items: (Product & MinItems<1>)[]; | ||
| * } | ||
| * interface Team { | ||
| * // Team must have 2-10 members | ||
| * members: (User & MinItems<2> & MaxItems<10>)[]; | ||
| * } |
There was a problem hiding this comment.
These examples apply MinItems/MaxItems to the element type ((User & MinItems<2> & MaxItems<10>)[]), but both tags target arrays (target: "array"). As written, they don’t constrain array length.
Suggestion: apply tags to the array type instead, e.g. members: User[] & MinItems<2> & MaxItems<10>.
Comment on lines
18
to
+26
| * @example | ||
| * // Limit tags to 10 items | ||
| * type ProductTags = string[] & MaxItems<10>; | ||
| * interface Upload { | ||
| * // Maximum 5 files per upload | ||
| * files: (File & MaxItems<5>)[]; | ||
| * } | ||
| * interface Config { | ||
| * // Between 1-3 backup servers allowed | ||
| * backupServers: (Server & MinItems<1> & MaxItems<3>)[]; | ||
| * } |
There was a problem hiding this comment.
These examples apply MaxItems/MinItems to the element type ((File & MaxItems<5>)[], (Server & MinItems<1> & MaxItems<3>)[]), but both tags target arrays (target: "array"). As written, they don’t constrain array length.
Suggestion: apply tags to the array type instead, e.g. files: File[] & MaxItems<5> and backupServers: Server[] & MinItems<1> & MaxItems<3>.
Comment on lines
+14
to
17
| * The pattern should be a valid JavaScript regular expression string without | ||
| * the surrounding slashes. The entire string must match (implicit `^` and `$` | ||
| * anchors). | ||
| * |
There was a problem hiding this comment.
The docs say the pattern matches the entire string via “implicit ^/$ anchors”, but the generated validator is RegExp("...").test($input), which does not add anchors. Full-string matching only happens if the user includes ^...$ themselves.
Suggestion: update the comment to say the regex is used as-provided (recommend including ^ and $ when full-string matching is desired).
Comment on lines
9
to
+24
| /** | ||
| * Whether to validate finite number or not. | ||
| * Validate that numbers are finite (not NaN/Infinity). | ||
| * | ||
| * If configured true, number typed values would be validated by | ||
| * Number.isNaN(). | ||
| * | ||
| * However, whatever you configure, it would be ignored when marshaling or | ||
| * parsing. | ||
| * | ||
| * - When marshaling, always be true | ||
| * | ||
| * - AssertStringify() | ||
| * - ValidateEncode() | ||
| * - When parsing, always be false | ||
| * | ||
| * - AssertParse() | ||
| * - IsDecode() | ||
| * When `true`, validates numbers using `Number.isNaN()`. Ignored during | ||
| * marshaling (always true) and parsing (always false). | ||
| * | ||
| * @default false | ||
| */ | ||
| finite?: undefined | boolean; | ||
|
|
||
| /** | ||
| * Whether to validate finite number or not. | ||
| * | ||
| * If configured true, number typed values would be validated by | ||
| * Number.isFinite(). | ||
| * Validate that numbers are numeric (not NaN). | ||
| * | ||
| * However, whatever you configure, it can be ignored in below case. | ||
| * | ||
| * - When `finite` option is true, this option would be ignored | ||
| * - When marshaling, always be true | ||
| * | ||
| * - AssertStringify() | ||
| * - ValidateEncode() | ||
| * - When parsing, always be false | ||
| * | ||
| * - AssertParse() | ||
| * - IsDecode() | ||
| * When `true`, validates numbers using `Number.isFinite()`. Ignored if | ||
| * `finite` is true, during marshaling (always true), or during parsing | ||
| * (always false). |
There was a problem hiding this comment.
The docstrings for finite and numeric are swapped relative to actual behavior. In the implementation, finite enables Number.isFinite(...) checks (rejects NaN and Infinity) and numeric enables !Number.isNaN(...) checks (rejects NaN only).
Suggestion: update the comments so finite references Number.isFinite() and numeric references Number.isNaN() (or its negation).
Comment on lines
+112
to
118
| /** | ||
| * Lowercase first character. | ||
| * | ||
| * @param str Input string | ||
| * @returns Localized string | ||
| */ | ||
| export const localize = (str: string) => str[0]!.toLowerCase() + str.slice(1); |
There was a problem hiding this comment.
localize will throw for empty strings because it unconditionally reads str[0]!. The newly added JSDoc also says “Localized string”, but this function is specifically lowercasing the first character.
Suggestion: mirror capitalize’s empty-string guard (return str when str.length === 0) and adjust the @returns text to something like “Lowercased-first-character string”.
Comment on lines
6
to
10
| const length: number = _randomInteger({ | ||
| type: "integer", | ||
| minimum: props.minLength ?? 0, | ||
| maximum: props.maxLength, | ||
| minimum: (props.minLength ?? 0) satisfies number as number, | ||
| maximum: props.maxLength satisfies number | undefined as number | undefined, | ||
| }); |
There was a problem hiding this comment.
The satisfies number as number pattern here is invalid TypeScript syntax (it parses as a satisfies expression followed by an as cast and will fail to compile). There’s also no need for satisfies since (props.minLength ?? 0) is already a number.
Suggestion: revert to minimum: props.minLength ?? 0 and maximum: props.maxLength, or if you want a compile-time check use (props.minLength ?? 0) satisfies number (without any as cast).
Comment on lines
10
to
14
| const count: number = _randomInteger({ | ||
| type: "integer", | ||
| minimum: props.minItems ?? 0, | ||
| minimum: (props.minItems ?? 0) satisfies number as number, | ||
| maximum: props.maxItems ?? (props.minItems ?? 0) + 5, | ||
| }); |
There was a problem hiding this comment.
Same issue as _randomString: satisfies number as number is not valid TypeScript syntax and will break compilation. Also unnecessary because props.minItems ?? 0 already produces a number.
Suggestion: use minimum: props.minItems ?? 0 (or (props.minItems ?? 0) satisfies number without as).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.