typia 15.0.0 → 15.0.1

package/native/core/utils/number_util_reads_javascript_number_grammar_test.go

@@ -0,0 +1,147 @@
+package utils
+
+import (
+  "math"
+  "testing"
+)
+
+// TestNumberUtilReadsJavaScriptNumberGrammar verifies NumberUtil.Read against
+// JavaScript's `Number()`.
+//
+// Tag values and JSDoc extensions are TypeScript source, so the grammar that
+// reads them is JavaScript's StringNumericLiteral. The expectations below are
+// what `Number(text)` returns in JavaScript (samchon/typia#2442), not what the
+// Go float parser accepts; the Go-only spellings (`NaN`, `Inf`, `0x1p4`,
+// `1_000`) are the cases that used to leak through. Text without digits is the
+// one deliberate difference: `Number("")` is 0, but it names no number here.
+//
+//  1. Read decimal, signed, exponent, and point-edge spellings.
+//  2. Read hexadecimal, octal, and binary integers, and reject signed ones.
+//  3. Classify `Infinity`, overflow, and underflow by finiteness.
+//  4. Reject Go-only spellings, separators, and empty or blank text.
+//  5. Spell values back exactly as JavaScript's `String()` does.
+//  6. Read integer spellings exactly, beyond double precision.
+func TestNumberUtilReadsJavaScriptNumberGrammar(t *testing.T) {
+  finite := func(value float64) NumberUtil_Reading {
+    return NumberUtil_Reading{Value: value, Numeric: true, Finite: true}
+  }
+  infinite := func(sign int) NumberUtil_Reading {
+    return NumberUtil_Reading{Value: math.Inf(sign), Numeric: true, Finite: false}
+  }
+  invalid := NumberUtil_Reading{}
+  for _, item := range []struct {
+    text     string
+    expected NumberUtil_Reading
+  }{
+    // Decimal notation, including every point and sign edge `Number()` admits.
+    {"0", finite(0)},
+    {"3", finite(3)},
+    {"-2.5", finite(-2.5)},
+    {"+5", finite(5)},
+    {".5", finite(0.5)},
+    {"5.", finite(5)},
+    {"1e3", finite(1000)},
+    {"1E-3", finite(0.001)},
+    {"-0", finite(0)},
+    {"  12\t", finite(12)},
+    {"\u00a012\u2028", finite(12)},
+    {"007", finite(7)},
+    // Non-decimal integers: unsigned only, any letter case in the prefix.
+    {"0x10", finite(16)},
+    {"0XfF", finite(255)},
+    {"0o7", finite(7)},
+    {"0b101", finite(5)},
+    {"-0x10", invalid},
+    {"+0x10", invalid},
+    {"0o8", invalid},
+    {"0b2", invalid},
+    {"0x", invalid},
+    // Non-finite values are numeric but not finite.
+    {"Infinity", infinite(1)},
+    {"+Infinity", infinite(1)},
+    {"-Infinity", infinite(-1)},
+    {"1e400", infinite(1)},
+    {"-1e400", infinite(-1)},
+    {"1e-400", finite(0)},
+    // Go-only spellings and separators: NaN in JavaScript.
+    {"NaN", invalid},
+    {"nan", invalid},
+    {"Inf", invalid},
+    {"inf", invalid},
+    {"-inf", invalid},
+    {"infinity", invalid},
+    {"0x1p4", invalid},
+    {"1_000", invalid},
+    {"1e", invalid},
+    {".", invalid},
+    {"1.2.3", invalid},
+    {"12px", invalid},
+    // No digits at all.
+    {"", invalid},
+    {"   ", invalid},
+    {"+", invalid},
+  } {
+    actual := NumberUtil.Read(item.text)
+    if actual != item.expected || math.Signbit(actual.Value) != math.Signbit(item.expected.Value) {
+      t.Fatalf("Read(%q) = %+v, expected %+v", item.text, actual, item.expected)
+    }
+  }
+
+  // String: the oracle is JavaScript's `String(value)`.
+  for _, item := range []struct {
+    value    float64
+    expected string
+  }{
+    {0, "0"},
+    {math.Copysign(0, -1), "0"},
+    {16, "16"},
+    {-2.5, "-2.5"},
+    {0.001, "0.001"},
+    {0.000001, "0.000001"},
+    {1e6, "1000000"},
+    {123456789012345680000, "123456789012345680000"},
+    {1e21, "1e+21"},
+    {1e-7, "1e-7"},
+    {-1e-7, "-1e-7"},
+    {1.23e-18, "1.23e-18"},
+    {1.5e300, "1.5e+300"},
+    {9007199254740993, "9007199254740992"},
+    {math.NaN(), "NaN"},
+    {math.Inf(1), "Infinity"},
+    {math.Inf(-1), "-Infinity"},
+  } {
+    if actual := NumberUtil.String(item.value); actual != item.expected {
+      t.Fatalf("String(%v) = %q, expected %q", item.value, actual, item.expected)
+    }
+  }
+
+  // Integer: exact digits for integer spellings, nothing for the rest.
+  for _, item := range []struct {
+    text     string
+    expected string
+    ok       bool
+  }{
+    {"9007199254740993", "9007199254740993", true},
+    {"-12", "-12", true},
+    {"+5", "5", true},
+    {"007", "7", true},
+    {"-0", "0", true},
+    {" 42 ", "42", true},
+    {"0x10", "16", true},
+    {"0b101", "5", true},
+    {"0o17", "15", true},
+    {"0xffffffffffffffffff", "4722366482869645213695", true},
+    {"1e3", "", false},
+    {"1.0", "", false},
+    {"-0x10", "", false},
+    {"0o8", "", false},
+    {"", "", false},
+    {"Infinity", "", false},
+  } {
+    integer, ok := NumberUtil.Integer(item.text)
+    if ok != item.ok || (ok && integer.String() != item.expected) {
+      t.Fatalf("Integer(%q) = %v, %v; expected %q, %v", item.text, integer, ok, item.expected, item.ok)
+    }
+  }
+
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typia",
-  "version": "15.0.0",
+  "version": "15.0.1",
   "description": "Superfast runtime validators with only one line",
   "main": "lib/index.js",
   "exports": {
@@ -43,8 +43,8 @@
   "homepage": "https://typia.io",
   "dependencies": {
     "randexp": "^0.5.3",
-    "@typia/utils": "^15.0.0",
-    "@typia/interface": "^15.0.0"
+    "@typia/interface": "^15.0.1",
+    "@typia/utils": "^15.0.1"
   },
   "peerDependencies": {
     "ttsc": ">=0.19.2"

package/src/http.ts

@@ -22,7 +22,10 @@ import { NoTransformConfigurationError } from "./transformers/NoTransformConfigu
  * Decodes `FormData` into type `T`.
  *
  * Parses a `FormData` instance with automatic type casting. Properties typed as
- * `boolean` or `Blob` are cast to expected types during decoding.
+ * `boolean`, `bigint`, or `number` are cast from their text, and `Blob` and
+ * `File` properties are read as given, except that the text `null` reads as
+ * `null`: as `undefined` instead for an optional single property whose type
+ * does not admit `null`, and always as `null` for an array element.
  *
  * Type `T` constraints:
  *
@@ -32,6 +35,11 @@ import { NoTransformConfigurationError } from "./transformers/NoTransformConfigu
  *    types allowed
  * 4. No union types allowed
  *
+ * An absent key decodes a required array to `[]`, a nullable one to `null`, and
+ * an optional one to `undefined`. A string property keeps the text `null`
+ * unless its type admits `null`, and a blank numeric value decodes to
+ * `undefined`.
+ *
  * Does not validate the decoded value. For validation, use:
  *
  * - {@link assertFormData} — Throws on type mismatch
@@ -164,8 +172,8 @@ export function validateFormData(): never {
  * Decodes URL query string into type `T`.
  *
  * Parses a query string or `URLSearchParams` instance with automatic type
- * casting. Properties typed as `boolean` or `number` are cast to expected types
- * during decoding.
+ * casting. Properties typed as `boolean`, `bigint`, or `number` are cast to
+ * expected types during decoding.
  *
  * Type `T` constraints:
  *
@@ -174,6 +182,12 @@ export function validateFormData(): never {
  * 3. Only `boolean`, `bigint`, `number`, `string` or their array types allowed
  * 4. No union types allowed
  *
+ * An absent key decodes a required array to `[]`, a nullable one to `null`, and
+ * an optional one to `undefined`, since a query string has no other spelling
+ * for an empty array. An absent required non-array property throws
+ * `Error("missing <key>")`. A string property keeps the text `null` unless its
+ * type admits `null`, and a blank numeric value decodes to `undefined`.
+ *
  * Does not validate the decoded value. For validation, use:
  *
  * - {@link assertQuery} — Throws on type mismatch
@@ -308,14 +322,15 @@ export function validateQuery(): never {
  * Decodes HTTP headers into type `T`.
  *
  * Parses HTTP headers object with automatic type casting. Properties typed as
- * `boolean` or `number` are cast to expected types during decoding. Compatible
- * with Express and Fastify request headers.
+ * `boolean`, `bigint`, or `number` are cast to expected types during decoding.
+ * Compatible with Express and Fastify request headers.
  *
  * Type `T` constraints:
  *
  * 1. Must be an object type
  * 2. No dynamic properties allowed
- * 3. Property keys must be lowercase
+ * 3. Property keys are read by their lowercase name; two keys that differ only by
+ *    case are not allowed
  * 4. Property values cannot be `null` (but `undefined` is allowed)
  * 5. Only `boolean`, `bigint`, `number`, `string` or their array types allowed
  * 6. No union types allowed
@@ -326,6 +341,10 @@ export function validateQuery(): never {
  *    `max-forwards`, `proxy-authorization`, `referer`, `retry-after`, `server`,
  *    `user-agent`
  *
+ * An absent optional array header, or one given as an empty array, is omitted,
+ * and an absent required one decodes to `[]`. `set-cookie` values are never
+ * split. A blank numeric header decodes to `undefined`.
+ *
  * Does not validate the decoded value. For validation, use:
  *
  * - {@link assertHeaders} — Throws on type mismatch
@@ -357,7 +376,8 @@ export function headers(): never {
  *
  * 1. Must be an object type
  * 2. No dynamic properties allowed
- * 3. Property keys must be lowercase
+ * 3. Property keys are read by their lowercase name; two keys that differ only by
+ *    case are not allowed
  * 4. Property values cannot be `null` (but `undefined` is allowed)
  * 5. Only `boolean`, `bigint`, `number`, `string` or their array types allowed
  * 6. No union types allowed
@@ -403,7 +423,8 @@ export function assertHeaders(): never {
  *
  * 1. Must be an object type
  * 2. No dynamic properties allowed
- * 3. Property keys must be lowercase
+ * 3. Property keys are read by their lowercase name; two keys that differ only by
+ *    case are not allowed
  * 4. Property values cannot be `null` (but `undefined` is allowed)
  * 5. Only `boolean`, `bigint`, `number`, `string` or their array types allowed
  * 6. No union types allowed
@@ -446,7 +467,8 @@ export function isHeaders(): never {
  *
  * 1. Must be an object type
  * 2. No dynamic properties allowed
- * 3. Property keys must be lowercase
+ * 3. Property keys are read by their lowercase name; two keys that differ only by
+ *    case are not allowed
  * 4. Property values cannot be `null` (but `undefined` is allowed)
  * 5. Only `boolean`, `bigint`, `number`, `string` or their array types allowed
  * 6. No union types allowed
@@ -484,12 +506,15 @@ export function validateHeaders(): never {
  * Decodes URL path parameter into type `T`.
  *
  * Parses a path parameter string with automatic type casting. When type `T` is
- * `boolean` or `number`, casts the string value to the expected type. Also
- * performs type assertion via {@link assert}, throwing {@link TypeGuardError} on
- * mismatch.
+ * `boolean`, `bigint`, or `number`, casts the string value to the expected
+ * type. Also performs type assertion via {@link assert}, throwing
+ * {@link TypeGuardError} on mismatch.
  *
- * @template T Target atomic type (`boolean`, `bigint`, `number`, `string`, or
- *   `null`)
+ * A blank value is not a number, and a string parameter keeps the text `null`
+ * unless `T` admits `null`.
+ *
+ * @template T Target atomic type (`boolean`, `bigint`, `number`, or `string`),
+ *   optionally with `null`
  * @param input Path parameter string
  * @returns Decoded value of type `T`
  * @throws {TypeGuardError} When decoded value doesn't conform to type `T`
@@ -521,10 +546,12 @@ export function createFormData(): never;
  * @template T Target object type
  * @returns Reusable decoder function
  */
-export function createFormData<T extends object>(): (input: FormData) => T;
+export function createFormData<T extends object>(): (
+  input: FormData,
+) => Resolved<T>;
 
 /** @internal */
-export function createFormData<T>(): (input: FormData) => T {
+export function createFormData<T>(): (input: FormData) => Resolved<T> {
   NoTransformConfigurationError("http.createFormData");
 }
 
@@ -553,13 +580,13 @@ export function createAssertFormData<T extends object>(
 ): (
   input: FormData,
   errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error),
-) => T;
+) => Resolved<T>;
 
 /** @internal */
 export function createAssertFormData<T>(): (
   input: FormData,
   errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error),
-) => T {
+) => Resolved<T> {
   NoTransformConfigurationError("http.createAssertFormData");
 }
 
@@ -579,10 +606,10 @@ export function createIsFormData(): never;
  */
 export function createIsFormData<T extends object>(): (
   input: FormData,
-) => T | null;
+) => Resolved<T> | null;
 
 /** @internal */
-export function createIsFormData<T>(): (input: FormData) => T | null {
+export function createIsFormData<T>(): (input: FormData) => Resolved<T> | null {
   NoTransformConfigurationError("http.createIsFormData");
 }
 
@@ -627,12 +654,12 @@ export function createQuery(): never;
  */
 export function createQuery<T extends object>(): (
   input: string | IReadableURLSearchParams,
-) => T;
+) => Resolved<T>;
 
 /** @internal */
 export function createQuery<T>(): (
   input: string | IReadableURLSearchParams,
-) => T {
+) => Resolved<T> {
   NoTransformConfigurationError("http.createQuery");
 }
 
@@ -661,13 +688,13 @@ export function createAssertQuery<T extends object>(
 ): (
   input: string | IReadableURLSearchParams,
   errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error),
-) => T;
+) => Resolved<T>;
 
 /** @internal */
 export function createAssertQuery<T>(): (
   input: string | IReadableURLSearchParams,
   errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error),
-) => T {
+) => Resolved<T> {
   NoTransformConfigurationError("http.createAssertQuery");
 }
 
@@ -687,12 +714,12 @@ export function createIsQuery(): never;
  */
 export function createIsQuery<T extends object>(): (
   input: string | IReadableURLSearchParams,
-) => T | null;
+) => Resolved<T> | null;
 
 /** @internal */
 export function createIsQuery<T>(): (
   input: string | IReadableURLSearchParams,
-) => T | null {
+) => Resolved<T> | null {
   NoTransformConfigurationError("http.createIsQuery");
 }
 
@@ -737,12 +764,12 @@ export function createHeaders(): never;
  */
 export function createHeaders<T extends object>(): (
   input: Record<string, string | string[] | undefined>,
-) => T;
+) => Resolved<T>;
 
 /** @internal */
 export function createHeaders<T>(): (
   input: Record<string, string | string[] | undefined>,
-) => T {
+) => Resolved<T> {
   NoTransformConfigurationError("http.createHeaders");
 }
 
@@ -771,13 +798,13 @@ export function createAssertHeaders<T extends object>(
 ): (
   input: Record<string, string | string[] | undefined>,
   errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error),
-) => T;
+) => Resolved<T>;
 
 /** @internal */
 export function createAssertHeaders<T>(): (
   input: Record<string, string | string[] | undefined>,
   errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error),
-) => T {
+) => Resolved<T> {
   NoTransformConfigurationError("http.createAssertHeaders");
 }
 
@@ -797,12 +824,12 @@ export function createIsHeaders(): never;
  */
 export function createIsHeaders<T extends object>(): (
   input: Record<string, string | string[] | undefined>,
-) => T | null;
+) => Resolved<T> | null;
 
 /** @internal */
 export function createIsHeaders<T>(): (
   input: Record<string, string | string[] | undefined>,
-) => T | null {
+) => Resolved<T> | null {
   NoTransformConfigurationError("http.createIsHeaders");
 }
 
@@ -847,11 +874,11 @@ export function createParameter(): never;
  */
 export function createParameter<T extends Atomic.Type | null>(): (
   input: string,
-) => T;
+) => Resolved<T>;
 
 /** @internal */
 export function createParameter<T extends Atomic.Type | null>(): (
   input: string,
-) => T {
+) => Resolved<T> {
   NoTransformConfigurationError("http.createParameter");
 }

package/src/internal/_httpFormDataReadBigint.ts

@@ -3,7 +3,9 @@ export const _httpFormDataReadBigint = (
 ): bigint | null | undefined =>
   input instanceof File
     ? (input as any)
-    : !!input?.length
+    : // 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 input === "string" && input.trim().length !== 0
       ? input === "null"
         ? null
         : (toBigint(input) as any)

package/src/internal/_httpFormDataReadBoolean.ts

@@ -3,7 +3,9 @@ export const _httpFormDataReadBoolean = (
 ): boolean | null | undefined =>
   input instanceof File
     ? (input as any)
-    : input === null
+    : // `undefined` is as absent as `null`, which `FormData.get` returns; a
+      // stand-in that answers `undefined` must not throw on `.length`.
+      input === null || input === undefined
       ? undefined
       : input === "null"
         ? null

package/src/internal/_httpFormDataReadNumber.ts

@@ -3,7 +3,9 @@ export const _httpFormDataReadNumber = (
 ): 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,19 @@
+/**
+ * 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.
+ */
 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,10 @@
 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/_httpHeaderReadNumber.ts

@@ -1,5 +1,10 @@
 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

@@ -2,6 +2,9 @@ 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/_httpParameterReadNumber.ts

@@ -2,6 +2,9 @@ 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,12 @@
-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.
+ */
+export const _httpParameterReadString = (
+  value: string,
+  nullable: boolean = true,
+) => (nullable === true && value === "null" ? null : value);

package/src/internal/_httpQueryReadBigint.ts

@@ -1,7 +1,13 @@
 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,9 @@
 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,13 @@
 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,13 @@
+/**
+ * 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.
+ */
 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;