typia 15.0.0 → 15.1.0

package/src/internal/_httpFormDataReadNumber.ts

@@ -1,9 +1,22 @@
+/**
+ * Read one form field as a number.
+ *
+ * A file passes through, blank text is absent, `null` is null and other text is
+ * converted when it is a number and kept as text otherwise.
+ *
+ * @evidence contracts/common.md#principled-implementation A file is passed through, blank text is absent because `Number(" ")` would read as zero, `null` is null, and other text is converted when it is a number and kept as text when it is NaN so the assertion rejects it.
+ * @evidence contracts/common.md#clear-and-simple-design One conditional chain and a private converter.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The blank-text rule follows the cited issue and is general.
+ * @evidence contracts/common.md#meaningful-documentation A comment states the cases.
+ */
 export const _httpFormDataReadNumber = (
   input: string | File | null,
 ): number | null | undefined =>
   input instanceof File
     ? (input as any)
-    : !!input?.length
+    : // Blank text is absent, as the empty string always was: `Number(" ")`
+      // is 0, which would read a whitespace value as a real zero (#2448).
+      typeof input === "string" && input.trim().length !== 0
       ? input === "null"
         ? null
         : (toNumber(input) as any)

package/src/internal/_httpFormDataReadString.ts

@@ -1,10 +1,24 @@
+/**
+ * Reads one form field as a string.
+ *
+ * The text `"null"` spells `null` only where the property's type admits `null`;
+ * elsewhere it is the string `"null"` (#2450). The emitter passes `false` for a
+ * string whose type does not admit `null` and omits the argument otherwise, so
+ * code emitted before the parameter existed keeps its reading.
+ *
+ * @evidence contracts/common.md#principled-implementation A file is passed through, a missing field is absent, and the text `null` becomes null only when the property's type admits null, which the emitter states with the `nullable` argument; otherwise it is the string.
+ * @evidence contracts/common.md#clear-and-simple-design One conditional chain with a default that keeps older emitted code reading as before.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The default of true preserves a documented earlier reading and is not a hidden toggle.
+ * @evidence contracts/common.md#meaningful-documentation The doc explains the nullable parameter and the issue.
+ */
 export const _httpFormDataReadString = (
   input: string | File | null,
+  nullable: boolean = true,
 ): string | null | undefined =>
   input instanceof File
     ? (input as any)
     : input === null
       ? undefined
-      : input === "null"
+      : nullable === true && input === "null"
         ? null
         : input;

package/src/internal/_httpHeaderReadBigint.ts

@@ -1,5 +1,21 @@
+/**
+ * Read one header value as a bigint.
+ *
+ * A blank value is absent, and other text is converted when it parses and kept
+ * as text otherwise.
+ *
+ * @evidence contracts/common.md#principled-implementation A blank header, or a blank element, is absent because `BigInt("")` would read as zero; other text is converted when it parses and left as text when it does not.
+ * @evidence contracts/common.md#clear-and-simple-design One conditional and two private helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The blank rule follows the cited issue.
+ * @evidence contracts/common.md#meaningful-documentation A comment states the cases.
+ */
 export const _httpHeaderReadBigint = (value: string | undefined) =>
-  value !== undefined ? toBigint(value) : undefined;
+  // A blank header, or a blank element of a header list, is absent: `BigInt("")`
+  // is 0n, which let validators accept an empty header as a real zero (#2448).
+  value !== undefined && isBlank(value) === false ? toBigint(value) : undefined;
+
+const isBlank = (value: string): boolean =>
+  typeof value === "string" && value.trim().length === 0;
 
 const toBigint = (str: string): bigint | string => {
   try {

package/src/internal/_httpHeaderReadBoolean.ts

@@ -1,3 +1,15 @@
+/**
+ * Read one header value as a boolean.
+ *
+ * Only `true` and `false` are read as booleans; other text is kept for the
+ * assertion to reject, unlike query and path values, which also accept `1` and
+ * `0`.
+ *
+ * @evidence contracts/common.md#principled-implementation Only the texts `true` and `false` are read as booleans and any other text, including `1` and `0` and the empty string, is returned for the validator to reject; a missing header is absent. This differs from the query and path readers, which also accept `1` and `0`.
+ * @evidence contracts/common.md#clear-and-simple-design One conditional chain.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The narrower mapping is a stated difference and not an accident of copying.
+ * @evidence contracts/common.md#meaningful-documentation A comment states the accepted texts and the difference.
+ */
 export const _httpHeaderReadBoolean = (value: string | undefined) =>
   value !== undefined
     ? value === "true"

package/src/internal/_httpHeaderReadNumber.ts

@@ -1,5 +1,21 @@
+/**
+ * Read one header value as a number.
+ *
+ * A blank value is absent, and other text is converted when it is a number and
+ * kept as text otherwise.
+ *
+ * @evidence contracts/common.md#principled-implementation A blank header, or a blank element, is absent because `Number("")` would read as zero; other text is converted when it is a number and kept as text otherwise.
+ * @evidence contracts/common.md#clear-and-simple-design One conditional and two private helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The blank rule follows the cited issue.
+ * @evidence contracts/common.md#meaningful-documentation A comment states the cases.
+ */
 export const _httpHeaderReadNumber = (value: string | undefined) =>
-  value !== undefined ? toNumber(value) : undefined;
+  // A blank header, or a blank element of a header list, is absent: `Number("")`
+  // is 0, which let validators accept an empty header as a real zero (#2448).
+  value !== undefined && isBlank(value) === false ? toNumber(value) : undefined;
+
+const isBlank = (value: string): boolean =>
+  typeof value === "string" && value.trim().length === 0;
 
 const toNumber = (str: string): number | string => {
   const value: number = Number(str);

package/src/internal/_httpParameterReadBigint.ts

@@ -1,7 +1,21 @@
+/**
+ * Read one path parameter as a bigint.
+ *
+ * `null` is null, blank text is kept as text so the assertion rejects it, and
+ * other text is converted when it parses.
+ *
+ * @evidence contracts/common.md#principled-implementation The text `null` is null, blank text stays text so the assertion rejects it and does not read as zero, and other text is converted with BigInt where it parses.
+ * @evidence contracts/common.md#clear-and-simple-design One conditional and one private converter.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The blank rule follows the cited issue.
+ * @evidence contracts/common.md#meaningful-documentation A comment states the cases.
+ */
 export const _httpParameterReadBigint = (value: string) =>
   value !== "null" ? toBigint(value) : null;
 
 const toBigint = (str: string): bigint | string => {
+  // Blank text stays text, so the assertion rejects it: `BigInt(" ")` is 0n,
+  // which read a blank path segment as a real zero (#2448).
+  if (str.trim().length === 0) return str;
   try {
     return BigInt(str);
   } catch {

package/src/internal/_httpParameterReadBoolean.ts

@@ -1,3 +1,14 @@
+/**
+ * Read one path parameter as a boolean.
+ *
+ * `true` and `1` are true, `false` and `0` are false, `null` is null and other
+ * text is kept for the assertion to reject.
+ *
+ * @evidence contracts/common.md#principled-implementation The text `null` is null, `true` and `1` are true, `false` and `0` are false and other text is returned for the validator to reject.
+ * @evidence contracts/common.md#clear-and-simple-design One conditional chain.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The mapping is the path-parameter contract.
+ * @evidence contracts/common.md#meaningful-documentation A comment states the mapping.
+ */
 export const _httpParameterReadBoolean = (value: string) =>
   value !== "null"
     ? value === "true" || value === "1"

package/src/internal/_httpParameterReadNumber.ts

@@ -1,7 +1,21 @@
+/**
+ * Read one path parameter as a number.
+ *
+ * `null` is null, blank text is kept as text so the assertion rejects it, and
+ * other text is converted when it is a number.
+ *
+ * @evidence contracts/common.md#principled-implementation The text `null` is null, blank text stays text so the assertion rejects it, and other text is converted when it is a number and kept as text otherwise.
+ * @evidence contracts/common.md#clear-and-simple-design One conditional and one private converter.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The blank rule follows the cited issue.
+ * @evidence contracts/common.md#meaningful-documentation A comment states the cases.
+ */
 export const _httpParameterReadNumber = (value: string) =>
   value !== "null" ? toNumber(value) : null;
 
 const toNumber = (str: string): number | string => {
+  // Blank text stays text, so the assertion rejects it: `Number(" ")` is 0,
+  // which read a blank path segment as a real zero (#2448).
+  if (str.trim().length === 0) return str;
   const value: number = Number(str);
   return isNaN(value) ? str : value;
 };

package/src/internal/_httpParameterReadString.ts

@@ -1,2 +1,17 @@
-export const _httpParameterReadString = (value: string) =>
-  value !== "null" ? value : null;
+/**
+ * Reads one path parameter as a string.
+ *
+ * The text `"null"` spells `null` only where the parameter's type admits
+ * `null`; elsewhere it is the string `"null"` (#2450). The emitter passes
+ * `false` for a string whose type does not admit `null` and omits the argument
+ * otherwise, so code emitted before the parameter existed keeps its reading.
+ *
+ * @evidence contracts/common.md#principled-implementation The text `null` becomes null only when the parameter's type admits null, which the emitter states with the `nullable` argument, and otherwise the value is returned.
+ * @evidence contracts/common.md#clear-and-simple-design One conditional with a default that keeps older emitted code reading as before.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The default is documented and not a hidden toggle.
+ * @evidence contracts/common.md#meaningful-documentation The doc explains the nullable parameter and the issue.
+ */
+export const _httpParameterReadString = (
+  value: string,
+  nullable: boolean = true,
+) => (nullable === true && value === "null" ? null : value);

package/src/internal/_httpQueryParseURLSearchParams.ts

@@ -1,5 +1,19 @@
 import { IReadableURLSearchParams } from "@typia/interface";
 
+/**
+ * Parse a query input into URLSearchParams.
+ *
+ * A string may be a bare query, a query with a leading `?`, or a URL; a prefix
+ * before the first `?` is dropped when it looks like a URL prefix (a scheme, a
+ * slash or dot path, or text without `=` or `&`), and a fragment is removed
+ * from a URL. An object that already reads like URLSearchParams is returned as
+ * it is.
+ *
+ * @evidence contracts/common.md#principled-implementation A string input is reduced to its query: a leading `?` is dropped, text before a `?` is dropped when it looks like a URL prefix (a scheme, a leading slash or dot path, or text without `=` or `&`), and a fragment is removed for URL inputs; an object that already reads like URLSearchParams is returned as is. The URL-prefix test is a heuristic, so a bare query string whose first key contains no `=` or `&` is read as a prefix.
+ * @evidence contracts/common.md#clear-and-simple-design One function and two private prefix predicates.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The heuristic is stated and has a defined boundary instead of a list of known URLs.
+ * @evidence contracts/common.md#meaningful-documentation The doc states the accepted inputs and the heuristic.
+ */
 export const _httpQueryParseURLSearchParams = (
   input: string | IReadableURLSearchParams,
 ): IReadableURLSearchParams => {

package/src/internal/_httpQueryReadArray.ts

@@ -1,3 +1,12 @@
+/**
+ * Read a collected query value list; an empty list means the key was absent and
+ * gives the alternative that the property's type calls for.
+ *
+ * @evidence contracts/common.md#principled-implementation An empty collected array means the key was absent and returns the alternative that the transform chose for the property's type, and otherwise the array.
+ * @evidence contracts/common.md#clear-and-simple-design One conditional.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The alternative is passed by the emitted code.
+ * @evidence contracts/common.md#meaningful-documentation A comment states the absent-versus-empty rule.
+ */
 export const _httpQueryReadArray = (
   input: any[],
   alternative: null | undefined,

package/src/internal/_httpQueryReadBigint.ts

@@ -1,7 +1,24 @@
+/**
+ * Read one query value as a bigint.
+ *
+ * Blank text is absent, `null` is null and other text is converted when it
+ * parses and kept as text otherwise.
+ *
+ * @evidence contracts/common.md#principled-implementation Blank or missing text is absent because `BigInt(" ")` would read as zero, the text `null` is null and other text is converted with BigInt where it parses and kept as text otherwise.
+ * @evidence contracts/common.md#clear-and-simple-design One conditional and a private converter.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The blank rule follows the cited issue.
+ * @evidence contracts/common.md#meaningful-documentation A comment states the cases.
+ */
 export const _httpQueryReadBigint = (
   str: string | null,
 ): bigint | null | undefined =>
-  !!str?.length ? (str === "null" ? null : (toBigint(str) as any)) : undefined;
+  // Blank text is absent, as the empty string always was: `BigInt(" ")` is 0n,
+  // which would read a whitespace value as a real zero (#2448).
+  typeof str === "string" && str.trim().length !== 0
+    ? str === "null"
+      ? null
+      : (toBigint(str) as any)
+    : undefined;
 
 const toBigint = (str: string): bigint | string => {
   try {

package/src/internal/_httpQueryReadBoolean.ts

@@ -1,7 +1,21 @@
+/**
+ * Read one query value as a boolean.
+ *
+ * A missing value is absent, an empty value is true, `true` and `1` are true,
+ * `false` and `0` are false, `null` is null and other text is kept for the
+ * assertion to reject.
+ *
+ * @evidence contracts/common.md#principled-implementation A missing or undefined value is absent, `null` is null, an empty value is true (a present flag), `true` and `1` are true, `false` and `0` are false and other text is returned for the validator to reject; `undefined` is treated like null so a stand-in reader does not throw.
+ * @evidence contracts/common.md#clear-and-simple-design One conditional chain.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The mapping is the query contract.
+ * @evidence contracts/common.md#meaningful-documentation A comment states the mapping.
+ */
 export const _httpQueryReadBoolean = (
   str: string | null,
 ): boolean | null | undefined =>
-  str === null
+  // `undefined` is as absent as `null`, which the contract returns; a
+  // stand-in reader that answers `undefined` must not throw on `.length`.
+  str === null || str === undefined
     ? undefined
     : str === "null"
       ? null

package/src/internal/_httpQueryReadNumber.ts

@@ -1,7 +1,24 @@
+/**
+ * Read one query value as a number.
+ *
+ * Blank text is absent, `null` is null and other text is converted when it is a
+ * number and kept as text otherwise.
+ *
+ * @evidence contracts/common.md#principled-implementation Blank or missing text is absent because `Number(" ")` would read as zero, the text `null` is null and other text is converted when it is a number and kept as text otherwise.
+ * @evidence contracts/common.md#clear-and-simple-design One conditional and a private converter.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The blank rule follows the cited issue.
+ * @evidence contracts/common.md#meaningful-documentation A comment states the cases.
+ */
 export const _httpQueryReadNumber = (
   str: string | null,
 ): number | null | undefined =>
-  !!str?.length ? (str === "null" ? null : (toNumber(str) as any)) : undefined;
+  // Blank text is absent, as the empty string always was: `Number(" ")` is 0,
+  // which would read a whitespace value as a real zero (#2448).
+  typeof str === "string" && str.trim().length !== 0
+    ? str === "null"
+      ? null
+      : (toNumber(str) as any)
+    : undefined;
 
 const toNumber = (str: string): number | string => {
   const value: number = Number(str);

package/src/internal/_httpQueryReadString.ts

@@ -1,4 +1,18 @@
+/**
+ * Reads one query value as a string.
+ *
+ * The text `"null"` spells `null` only where the property's type admits `null`;
+ * elsewhere it is the string `"null"` (#2450). The emitter passes `false` for a
+ * string whose type does not admit `null` and omits the argument otherwise, so
+ * code emitted before the parameter existed keeps its reading.
+ *
+ * @evidence contracts/common.md#principled-implementation A missing value is absent and the text `null` becomes null only when the property's type admits null, which the emitter states with the `nullable` argument.
+ * @evidence contracts/common.md#clear-and-simple-design One conditional with a default that keeps older emitted code reading as before.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The default is documented and not a hidden toggle.
+ * @evidence contracts/common.md#meaningful-documentation The doc explains the nullable parameter and the issue.
+ */
 export const _httpQueryReadString = (
   str: string | null,
+  nullable: boolean = true,
 ): string | null | undefined =>
-  str === null ? undefined : str === "null" ? null : str;
+  str === null ? undefined : nullable === true && str === "null" ? null : str;

package/src/internal/_isBetween.ts

@@ -1,2 +1,10 @@
+/**
+ * Test whether a number is within an inclusive range.
+ *
+ * @evidence contracts/common.md#principled-implementation The inclusive range test `minimum <= value && value <= maximum` is the definition of a closed interval, and NaN fails both comparisons.
+ * @evidence contracts/common.md#clear-and-simple-design One expression.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A general comparison.
+ * @evidence contracts/common.md#meaningful-documentation A comment states the inclusive bounds.
+ */
 export const _isBetween = (value: number, minimum: number, maximum: number) =>
   minimum <= value && value <= maximum;

package/src/internal/_isBigintString.ts

@@ -1,3 +1,14 @@
+/**
+ * Checks whether ECMAScript BigInt accepts a string without throwing.
+ *
+ * The accepted spellings follow the runtime conversion, including its
+ * whitespace and radix handling; this is not a decimal-only grammar.
+ *
+ * @evidence contracts/common.md#principled-implementation BigInt conversion determines the actual runtime language. Successful construction returns true and conversion exceptions return false without coercing a different representation.
+ * @evidence contracts/common.md#clear-and-simple-design One conversion and its exception boundary own the verdict; no parallel numeric parser or canonicalization policy is introduced.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The runtime conversion is the supported requirement, not a fixture-specific exception. The function changes no conversion implementation or global.
+ * @evidence contracts/common.md#meaningful-documentation The doc states that acceptance follows the runtime BigInt conversion, including whitespace and radix prefixes, and is not a decimal-only grammar.
+ */
 export const _isBigintString = (str: string): boolean => {
   try {
     BigInt(str);

package/src/internal/_isFormatByte.ts

@@ -1,3 +1,15 @@
+/**
+ * Checks the padded Base64 spelling accepted by the byte format.
+ *
+ * Empty data is valid. The predicate checks alphabet, four-character grouping
+ * and terminal padding; it does not decode bytes or require canonical zero
+ * padding bits.
+ *
+ * @evidence contracts/common.md#principled-implementation Full-input grouping admits complete four-symbol blocks and only the two valid padded tail lengths. The fixed alphabet and suffix positions establish lexical validity without byte allocation.
+ * @evidence contracts/common.md#clear-and-simple-design One private expression owns this lexical check; decoding and content interpretation remain with their consumers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Alphabet and grouping are format rules rather than special inputs. The predicate applies the same expression to every supplied string.
+ * @evidence contracts/common.md#meaningful-documentation The doc states the accepted padded Base64 spelling, that empty data is valid, and that bytes are not decoded and zero padding bits are not required to be canonical.
+ */
 export const _isFormatByte = (str: string): boolean => PATTERN.test(str);
 
 const PATTERN =

package/src/internal/_isFormatDate.ts

@@ -1,3 +1,14 @@
+/**
+ * Checks four-digit year, month and day syntax and Gregorian month length.
+ *
+ * The numeric year is used directly, including year zero; Date parsing and its
+ * local-time normalization do not determine validity.
+ *
+ * @evidence contracts/common.md#principled-implementation Captured ranges establish month and positive day bounds before indexing the month-length table. The divisible-by-400 or divisible-by-4-but-not-100 rule adds the February leap day, so syntactically valid impossible dates fail.
+ * @evidence contracts/common.md#clear-and-simple-design The private syntax expression and month-length table separate lexical ranges from the one calendar calculation that syntax cannot establish.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The table and divisibility rules represent the calendar uniformly; no dates or consumers receive special outcomes.
+ * @evidence contracts/common.md#meaningful-documentation The doc states the four-digit year, month and day syntax and the Gregorian month length, that year zero is accepted and that Date parsing does not decide validity.
+ */
 export const _isFormatDate = (str: string): boolean => {
   const match: RegExpExecArray | null = PATTERN.exec(str);
   if (match === null) return false;

package/src/internal/_isFormatDateTime.ts

@@ -1,5 +1,18 @@
 import { _isFormatDate } from "./_isFormatDate";
 
+/**
+ * Checks timestamp syntax, calendar dates and possible UTC leap-second
+ * position.
+ *
+ * An explicit Z or numeric offset is required. A second of 60 is permitted only
+ * at a UTC June or December month-end boundary; this does not consult a
+ * historical leap-second announcement table.
+ *
+ * @evidence contracts/common.md#principled-implementation The syntax expression bounds clock and offset fields and delegates the date to the calendar predicate. UTC setters preserve literal years, and offset subtraction determines whether a potential leap second occupies the permitted month-end minute.
+ * @evidence contracts/common.md#clear-and-simple-design Ordinary seconds finish after syntax/calendar validation; only the leap-second branch constructs the UTC instant needed for the boundary decision.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts UTC conversion and the potential leap-second boundary are uniform rules. The implementation neither relies on local timezone nor special-cases fixture dates; historical announcements are outside this check.
+ * @evidence contracts/common.md#meaningful-documentation The doc states that an offset is required, when a second of 60 is allowed and that no leap-second announcement table is consulted.
+ */
 export const _isFormatDateTime = (str: string): boolean => {
   const match: RegExpExecArray | null = PATTERN.exec(str);
   if (match === null || _isFormatDate(match[1]!) === false) return false;

package/src/internal/_isFormatDuration.ts

@@ -1,3 +1,16 @@
+/**
+ * Checks the ISO 8601 duration spelling of the `duration` format.
+ *
+ * Accepts `P` followed by years, months and days, optionally `T` and hours,
+ * minutes and seconds, or `P` and weeks alone, all as non-negative integers. A
+ * bare `P`, a `T` with no time component, fractions and signs are rejected. The
+ * predicate does not check that the components are in a calendar range.
+ *
+ * @evidence contracts/common.md#principled-implementation One anchored expression encodes the ISO 8601 duration grammar as RFC 3339 Appendix A gives it: designators in order Y, M, D, then an optional T with H, M, S, or weeks alone, with a lookahead that rejects a bare `P` and a `T` with no time part. Components are integers only.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate and one private pattern; this package keeps this copy under its internal folder because its emitted code imports predicates from there, and @typia/utils holds an identical copy because it cannot import typia.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The grammar comes from the specification and the predicate has no accepted examples hardcoded.
+ * @evidence contracts/common.md#meaningful-documentation The doc states the accepted forms and what is not checked.
+ */
 export const _isFormatDuration = (str: string): boolean => PATTERN.test(str);
 
 const PATTERN =

package/src/internal/_isFormatEmail.ts

@@ -1,3 +1,16 @@
+/**
+ * Checks the ASCII email spelling of the `email` format.
+ *
+ * Accepts a dot-separated local part of RFC 5322 atom characters and a domain
+ * of at least two dot-separated alphanumeric labels, ignoring case. Quoted
+ * local parts, address literals, non-ASCII characters and the 64 and 254
+ * character length limits are not handled.
+ *
+ * @evidence contracts/common.md#principled-implementation One expression accepts a dot-atom local part of RFC 5322 atext characters and a domain of at least two alphanumeric labels with interior hyphens, ignoring case; it is a practical subset and not the full address grammar, so quoted local parts, address literals, non-ASCII characters and the length limits are outside it.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate and one private pattern, identical to the copy in @typia/utils.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The grammar is the stated subset and nothing is keyed on addresses.
+ * @evidence contracts/common.md#meaningful-documentation The doc lists the accepted and unsupported forms.
+ */
 export const _isFormatEmail = (str: string): boolean => PATTERN.test(str);
 
 const PATTERN =

package/src/internal/_isFormatHostname.ts

@@ -1,3 +1,15 @@
+/**
+ * Checks the RFC 1123 hostname spelling of the `hostname` format.
+ *
+ * Accepts dot-separated ASCII labels of one to 63 letters, digits and interior
+ * hyphens, at most 253 characters before one optional trailing dot, and ignores
+ * case. A name of a single label is valid.
+ *
+ * @evidence contracts/common.md#principled-implementation A lookahead bounds the name to 253 characters before an optional trailing dot, then labels of one to 63 letters, digits and interior hyphens are required, which is the RFC 1123 hostname grammar; a single label is valid and underscores are not.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate and one private pattern, identical to the copy in @typia/utils.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The limits are the standard's own numbers.
+ * @evidence contracts/common.md#meaningful-documentation The doc states the length and label rules.
+ */
 export const _isFormatHostname = (str: string): boolean => PATTERN.test(str);
 
 const PATTERN =

package/src/internal/_isFormatIdnEmail.ts

@@ -1,3 +1,17 @@
+/**
+ * Checks the internationalized email spelling of the `idn-email` format.
+ *
+ * Accepts a local part of dotted atoms that exclude only whitespace and the
+ * characters `<>()[]\.,;:@"`, or a quoted string, and a domain of labels ending
+ * in a top-level label of at least two UTF-16 code units. Non-ASCII units,
+ * including unpaired surrogates, are allowed. Length limits, surrogate validity
+ * and the IDNA rules for the domain are not checked.
+ *
+ * @evidence contracts/common.md#principled-implementation The local part is dotted atoms excluding whitespace and the specials, or a quoted string, and the domain is dotted labels with a final label of at least two UTF-16 code units. The expression has no Unicode flag, so its permissive non-special set also accepts surrogate units; it does not apply IDNA, surrogate validity or length limits.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate and one private pattern, identical to the copy in @typia/utils.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The permissive set is stated and no address is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The doc lists what is and is not checked.
+ */
 export const _isFormatIdnEmail = (str: string): boolean => PATTERN.test(str);
 
 const PATTERN =

package/src/internal/_isFormatIdnHostname.ts

@@ -1,3 +1,17 @@
+/**
+ * Checks the internationalized hostname spelling of the `idn-hostname` format.
+ *
+ * Accepts the hostname structure with label characters extended to the code
+ * units from U+00A1 to U+FFFF. It checks characters and lengths only: IDNA
+ * mapping, Punycode and the contextual and bidirectional rules are not applied.
+ * Surrogate pairs are accepted as two label code units, so astral characters
+ * consume two units of the label and hostname length limits.
+ *
+ * @evidence contracts/common.md#principled-implementation The ASCII hostname structure is reused with the label class widened to code units from U+00A1 to U+FFFF, so every valid hostname is also a valid IDN hostname as the comment records. Without the `u` flag, both units of a surrogate pair match separately and consume two units of the length limits; this also admits unpaired surrogates. IDNA mapping, Punycode and contextual and bidirectional rules are not applied, so this spelling check is an approximation rather than IDNA validation.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate and one private pattern, identical to the copy in @typia/utils.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The widening is a stated approximation of IDNA, not a fixture accommodation.
+ * @evidence contracts/common.md#meaningful-documentation The doc states the character range and the checks that are absent.
+ */
 export const _isFormatIdnHostname = (str: string): boolean => PATTERN.test(str);
 
 // The ASCII `hostname` structure with the label character class extended by the

package/src/internal/_isFormatIpv4.ts

@@ -1,3 +1,14 @@
+/**
+ * Checks the dotted-decimal spelling of the `ipv4` format.
+ *
+ * Accepts exactly four decimal octets from 0 to 255 separated by dots, with no
+ * leading zeros.
+ *
+ * @evidence contracts/common.md#principled-implementation Four octets of 0 to 255 without leading zeros are matched by an alternation of the decimal ranges, so values above 255 and zero-padded octets are rejected.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate and one private pattern, identical to the copy in @typia/utils.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The ranges are the dotted-decimal grammar's.
+ * @evidence contracts/common.md#meaningful-documentation The doc states the octet rule.
+ */
 export const _isFormatIpv4 = (str: string): boolean => PATTERN.test(str);
 
 const PATTERN =

package/src/internal/_isFormatIpv6.ts

@@ -1,3 +1,15 @@
+/**
+ * Checks the RFC 4291 text spelling of the `ipv6` format.
+ *
+ * Accepts eight groups of one to four hexadecimal digits, one `::` compression
+ * and an embedded dotted IPv4 tail, ignoring case. A zone identifier and a
+ * prefix length are not accepted.
+ *
+ * @evidence contracts/common.md#principled-implementation The expression enumerates the RFC 4291 text forms: eight groups, each position of a single `::` compression and an embedded dotted IPv4 tail, ignoring case; a zone identifier and a prefix length are not part of the grammar.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate and one private pattern, identical to the copy in @typia/utils; the pattern is long because the compression positions are listed, and no helper is split off.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The forms are the standard's, with no address special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The doc lists the accepted forms and the excluded suffixes.
+ */
 export const _isFormatIpv6 = (str: string): boolean => PATTERN.test(str);
 
 const PATTERN =

package/src/internal/_isFormatIri.ts

@@ -1,5 +1,16 @@
 import { _isFormatIriReference } from "./_isFormatIriReference";
 
+/**
+ * Checks the `iri` format: an IRI reference that begins with a scheme.
+ *
+ * The scheme must be a letter followed by letters, digits, `+`, `.` or `-` and
+ * a colon. The rest is judged by {@link _isFormatIriReference}.
+ *
+ * @evidence contracts/common.md#principled-implementation An IRI is an IRI reference that begins with a scheme, so the predicate requires the scheme prefix and delegates the character rules to the reference predicate.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate that composes the scheme test and the reference predicate, identical to the copy in @typia/utils.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The composition follows the definition of an IRI as an absolute reference.
+ * @evidence contracts/common.md#meaningful-documentation The doc states the scheme requirement and the delegation.
+ */
 export const _isFormatIri = (str: string): boolean =>
   SCHEME.test(str) && _isFormatIriReference(str);
 

package/src/internal/_isFormatIriReference.ts

@@ -1,3 +1,16 @@
+/**
+ * Checks the `iri-reference` format at the character level.
+ *
+ * Rejects control characters, DEL and C1 controls, lone surrogates, space and
+ * the characters `"<>\^`{|}`, and any `%`that is not followed by two
+ * hexadecimal digits. A colon before the first`/`, `?`or`#` must end a valid
+ * scheme. Authority, port and path structure are not parsed.
+ *
+ * @evidence contracts/common.md#principled-implementation Characters that no IRI may contain (controls, space, lone surrogates and a few ASCII delimiters) and malformed percent escapes are rejected, and a colon before the first path delimiter must be the end of a valid scheme, which separates `a:b` from the relative `./a:b`. Authority, port and path structure are not parsed, so the predicate is a character and scheme check and not full grammar validation.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate with three private patterns, identical to the copy in @typia/utils.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The forbidden set comes from the IRI grammar and not from examples.
+ * @evidence contracts/common.md#meaningful-documentation The doc states what is rejected and what is not parsed.
+ */
 export const _isFormatIriReference = (str: string): boolean => {
   if (FORBIDDEN.test(str) || INVALID_PERCENT.test(str)) return false;
   const colon: number = str.indexOf(":");

package/src/internal/_isFormatJsonPointer.ts

@@ -1,3 +1,14 @@
+/**
+ * Checks the RFC 6901 JSON pointer spelling of the `json-pointer` format.
+ *
+ * The empty string is the whole-document pointer; otherwise every reference
+ * token starts with `/` and may contain `~` only as `~0` or `~1`.
+ *
+ * @evidence contracts/common.md#principled-implementation RFC 6901 allows the empty pointer and otherwise tokens that each start with a slash, where a tilde is valid only as `~0` or `~1`, which the expression states directly.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate and one private pattern, identical to the copy in @typia/utils.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The grammar is the standard's.
+ * @evidence contracts/common.md#meaningful-documentation The doc states the empty pointer and the tilde rule.
+ */
 export const _isFormatJsonPointer = (str: string): boolean => PATTERN.test(str);
 
 const PATTERN = /^(?:\/(?:[^~/]|~0|~1)*)*$/;

package/src/internal/_isFormatPassword.ts

@@ -1 +1,12 @@
+/**
+ * Accepts the password annotation without imposing a content rule.
+ *
+ * The owning schema validator verifies the string type. Password strength,
+ * secrecy and presentation policy are not format validation decisions here.
+ *
+ * @evidence contracts/common.md#principled-implementation Password supplies no additional lexical restriction, so literal true expresses annotation-only behavior after the type check owned by the consumer.
+ * @evidence contracts/common.md#clear-and-simple-design A zero-argument constant predicate exposes that there is no content analysis or policy configuration to coordinate.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The unrestricted verdict is the annotation contract, not a bypass for a consumer or fixture. No external password policy is substituted.
+ * @evidence contracts/common.md#meaningful-documentation The doc states that any string is accepted, that the schema validator owns the type check and that strength and secrecy policy are not decided here.
+ */
 export const _isFormatPassword = (): boolean => true;

package/src/internal/_isFormatRegex.ts

@@ -1,3 +1,14 @@
+/**
+ * Checks whether the runtime accepts a regular expression source without flags.
+ *
+ * Construction validates syntax; the resulting expression is never executed
+ * against a value and is not retained.
+ *
+ * @evidence contracts/common.md#principled-implementation RegExp construction is the syntax authority of the runtime. Only successful construction returns true; syntax exceptions are converted to false.
+ * @evidence contracts/common.md#clear-and-simple-design A single construction/exception boundary avoids maintaining a second regular expression grammar.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Native RegExp construction is the required syntax check and is not replaced or patched. No source receives an exceptional verdict.
+ * @evidence contracts/common.md#meaningful-documentation The doc states that the source is tested by construction without flags, and that the expression is neither executed against a value nor retained.
+ */
 export const _isFormatRegex = (str: string): boolean => {
   try {
     new RegExp(str);