typia 14.0.6 → 15.0.1

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;

package/src/internal/_randomBigint.ts

@@ -1,6 +1,114 @@
 import { OpenApi } from "@typia/interface";
 
-import { _randomInteger } from "./_randomInteger";
+import { _decimalIntegerStep } from "./_decimal";
 
-export const _randomBigint = (props: OpenApi.IJsonSchema.IInteger): bigint =>
-  BigInt(_randomInteger(props));
+/**
+ * Generates a random `bigint` satisfying an integer schema.
+ *
+ * The schema carries its bounds and step as numbers, but the value is a
+ * `bigint`, so the draw runs on integers. Drawing through doubles rounded every
+ * value past 2^53, and it checked `multipleOf` against a double's shortest
+ * decimal text rather than the integer `BigInt` makes of it, so `random`
+ * returned values the validator rejects, or gave up on a range that holds one
+ * (#2457). An integral bound or step is read as the integer the double holds,
+ * which is the integer the validator compares with.
+ */
+export const _randomBigint = (schema: OpenApi.IJsonSchema.IInteger): bigint => {
+  const lower: bigint | null = boundary(
+    schema.minimum,
+    schema.exclusiveMinimum,
+    "lower",
+  );
+  const upper: bigint | null = boundary(
+    schema.maximum,
+    schema.exclusiveMaximum,
+    "upper",
+  );
+  const minimum: bigint =
+    lower ?? (upper === null ? BigInt(0) : upper - BigInt(100));
+  const maximum: bigint =
+    upper ?? (lower === null ? BigInt(100) : lower + BigInt(100));
+  if (minimum > maximum)
+    throw new Error("Minimum value is greater than maximum value.");
+  if (schema.multipleOf === undefined) return between(minimum, maximum);
+
+  const step: bigint | null = integerStep(schema.multipleOf);
+  if (step === null || step <= BigInt(0))
+    throw new Error("The multipleOf value must be a positive finite number.");
+  const first: bigint = ceilDivide(minimum, step);
+  const last: bigint = floorDivide(maximum, step);
+  if (first > last)
+    throw new Error("The range does not contain a multipleOf value.");
+  return between(first, last) * step;
+};
+
+/**
+ * Reads one side's inclusive integer bound.
+ *
+ * `-Infinity` below or `Infinity` above excludes no integer, so it is no bound
+ * at all; `Infinity` below or `-Infinity` above excludes every integer.
+ */
+const boundary = (
+  inclusive: number | undefined,
+  exclusive: number | undefined,
+  side: "lower" | "upper",
+): bigint | null => {
+  const candidates: bigint[] = [];
+  for (const [value, open] of [
+    [inclusive, false],
+    [exclusive, true],
+  ] as const) {
+    if (value === undefined) continue;
+    if (Number.isFinite(value) === false) {
+      if (value === (side === "lower" ? -Infinity : Infinity)) continue;
+      throw new Error("Numeric range has no finite value.");
+    }
+    candidates.push(
+      side === "lower"
+        ? open
+          ? BigInt(Math.floor(value)) + BigInt(1)
+          : BigInt(Math.ceil(value))
+        : open
+          ? BigInt(Math.ceil(value)) - BigInt(1)
+          : BigInt(Math.floor(value)),
+    );
+  }
+  if (candidates.length === 0) return null;
+  return candidates.reduce((x, y) =>
+    side === "lower" ? (x > y ? x : y) : x < y ? x : y,
+  );
+};
+
+/**
+ * The smallest positive integer a `multipleOf` divides.
+ *
+ * An integral step is the integer its double holds; a fractional one, such as
+ * `1.5`, steps by its smallest integer multiple (`3`).
+ */
+const integerStep = (multipleOf: number): bigint | null => {
+  if (Number.isFinite(multipleOf) === false) return null;
+  if (Number.isInteger(multipleOf)) return BigInt(multipleOf);
+  return _decimalIntegerStep(multipleOf)?.coefficient ?? null;
+};
+
+const ceilDivide = (x: bigint, y: bigint): bigint => {
+  const quotient: bigint = x / y;
+  return x % y > BigInt(0) ? quotient + BigInt(1) : quotient;
+};
+
+const floorDivide = (x: bigint, y: bigint): bigint => {
+  const quotient: bigint = x / y;
+  return x % y < BigInt(0) ? quotient - BigInt(1) : quotient;
+};
+
+/** Draws an integer in `[minimum, maximum]`, scaling one 53-bit sample. */
+const between = (minimum: bigint, maximum: bigint): bigint => {
+  const scale: bigint = BigInt(1) << BigInt(53);
+  const sample: bigint = BigInt(
+    Math.min(
+      Number(scale - BigInt(1)),
+      Math.floor(Math.max(0, Math.random()) * Number(scale)),
+    ),
+  );
+  return minimum + ((maximum - minimum + BigInt(1)) * sample) / scale;
+};

package/src/internal/_randomInteger.ts

@@ -35,14 +35,12 @@ const scalar = (props: { minimum: number; maximum: number }): number => {
 const getLowerBoundary = (
   schema: OpenApi.IJsonSchema.IInteger,
 ): IBoundary | null => {
-  const inclusive: IBoundary | null =
-    schema.minimum === undefined
-      ? null
-      : { value: schema.minimum, exclusive: false };
-  const exclusive: IBoundary | null =
-    schema.exclusiveMinimum === undefined
-      ? null
-      : { value: schema.exclusiveMinimum, exclusive: true };
+  const inclusive: IBoundary | null = boundary(schema.minimum, false, "lower");
+  const exclusive: IBoundary | null = boundary(
+    schema.exclusiveMinimum,
+    true,
+    "lower",
+  );
   const selected: IBoundary | null = selectBoundary(
     inclusive,
     exclusive,
@@ -60,14 +58,12 @@ const getLowerBoundary = (
 const getUpperBoundary = (
   schema: OpenApi.IJsonSchema.IInteger,
 ): IBoundary | null => {
-  const inclusive: IBoundary | null =
-    schema.maximum === undefined
-      ? null
-      : { value: schema.maximum, exclusive: false };
-  const exclusive: IBoundary | null =
-    schema.exclusiveMaximum === undefined
-      ? null
-      : { value: schema.exclusiveMaximum, exclusive: true };
+  const inclusive: IBoundary | null = boundary(schema.maximum, false, "upper");
+  const exclusive: IBoundary | null = boundary(
+    schema.exclusiveMaximum,
+    true,
+    "upper",
+  );
   const selected: IBoundary | null = selectBoundary(
     inclusive,
     exclusive,
@@ -82,6 +78,25 @@ const getUpperBoundary = (
   };
 };
 
+/**
+ * Reads one bound, which may be infinite.
+ *
+ * A type tag built from an overflowing literal (`Maximum<1e400>`) carries an
+ * infinite bound (#2452). `-Infinity` below or `Infinity` above excludes no
+ * finite number, so it is no bound at all; `Infinity` below or `-Infinity`
+ * above excludes every finite number, so no value can be generated.
+ */
+const boundary = (
+  value: number | undefined,
+  exclusive: boolean,
+  side: "lower" | "upper",
+): IBoundary | null => {
+  if (value === undefined) return null;
+  if (Number.isFinite(value)) return { value, exclusive };
+  if (value === (side === "lower" ? -Infinity : Infinity)) return null;
+  throw new Error("Numeric range has no finite value.");
+};
+
 const selectBoundary = (
   x: IBoundary | null,
   y: IBoundary | null,

package/src/internal/_randomNumber.ts

@@ -57,12 +57,8 @@ const getLowerBoundary = (
   schema: OpenApi.IJsonSchema.INumber,
 ): IBoundary | null =>
   selectBoundary(
-    schema.minimum === undefined
-      ? null
-      : { value: schema.minimum, exclusive: false },
-    schema.exclusiveMinimum === undefined
-      ? null
-      : { value: schema.exclusiveMinimum, exclusive: true },
+    boundary(schema.minimum, false, "lower"),
+    boundary(schema.exclusiveMinimum, true, "lower"),
     Math.max,
   );
 
@@ -70,15 +66,30 @@ const getUpperBoundary = (
   schema: OpenApi.IJsonSchema.INumber,
 ): IBoundary | null =>
   selectBoundary(
-    schema.maximum === undefined
-      ? null
-      : { value: schema.maximum, exclusive: false },
-    schema.exclusiveMaximum === undefined
-      ? null
-      : { value: schema.exclusiveMaximum, exclusive: true },
+    boundary(schema.maximum, false, "upper"),
+    boundary(schema.exclusiveMaximum, true, "upper"),
     Math.min,
   );
 
+/**
+ * Reads one bound, which may be infinite.
+ *
+ * A type tag built from an overflowing literal (`Maximum<1e400>`) carries an
+ * infinite bound (#2452). `-Infinity` below or `Infinity` above excludes no
+ * finite number, so it is no bound at all; `Infinity` below or `-Infinity`
+ * above excludes every finite number, so no value can be generated.
+ */
+const boundary = (
+  value: number | undefined,
+  exclusive: boolean,
+  side: "lower" | "upper",
+): IBoundary | null => {
+  if (value === undefined) return null;
+  if (Number.isFinite(value)) return { value, exclusive };
+  if (value === (side === "lower" ? -Infinity : Infinity)) return null;
+  throw new Error("Numeric range has no finite value.");
+};
+
 const selectBoundary = (
   x: IBoundary | null,
   y: IBoundary | null,

package/src/internal/_stringLengthGte.ts

@@ -0,0 +1,6 @@
+export const _stringLengthGte = (value: string, length: number): boolean => {
+  let count: number = 0;
+  if (length <= count) return true;
+  for (const _ch of value) if (length <= ++count) return true;
+  return false;
+};

package/src/internal/_stringLengthLte.ts

@@ -0,0 +1,6 @@
+export const _stringLengthLte = (value: string, length: number): boolean => {
+  let count: number = 0;
+  if (!(count <= length)) return false;
+  for (const _ch of value) if (!(++count <= length)) return false;
+  return true;
+};

package/src/llm.ts

@@ -2,6 +2,7 @@ import {
   IJsonParseResult,
   ILlmApplication,
   ILlmController,
+  ILlmEvaluation,
   ILlmSchema,
   ILlmStructuredOutput,
 } from "@typia/interface";
@@ -201,6 +202,69 @@ export function structuredOutput(): never {
   NoTransformConfigurationError("llm.structuredOutput");
 }
 
+/* -----------------------------------------------------------
+  EVALUATION
+----------------------------------------------------------- */
+/**
+ * Creates LLM evaluation questions.
+ *
+ * @danger You must configure the generic argument `T`
+ */
+export function evaluation(): never;
+
+/**
+ * Creates LLM evaluation questions from TypeScript object type.
+ *
+ * Generates {@link ILlmEvaluation} for evaluation models, which answer typed
+ * questions about a shared state with probabilities instead of generating text:
+ * TypeSafe's Jev natively, and OpenAI, Anthropic, and Google through Vercel AI
+ * SDK's `experimental_evaluate()`.
+ *
+ * Every leaf property of `T` becomes one question, and its JSDoc description
+ * becomes the question text:
+ *
+ * - `boolean` → boolean question
+ * - String enum or string literal union → choice question
+ * - Numeric enum or numeric literal union → score question
+ * - Array of a string literal union or string enum → one boolean question per
+ *   member
+ * - Nested object → flattened, one question per leaf
+ *
+ * Types an evaluation model cannot answer, such as `string`, `number`, optional
+ * properties, or a leaf without a JSDoc description, are compile errors. Use
+ * `tags.Probability<N>` or `@probability N` to set decision thresholds and
+ * acceptance minimums. Once one choice, score, or set member declares a
+ * requirement, every member must declare one or inherit the property's
+ * `@probability` default. A nested object's own JSDoc description is not sent
+ * to the model; only the leaves' descriptions become question text. Other
+ * validation refinements that the answer decoder cannot enforce are compile
+ * errors.
+ *
+ * This feature is experimental. It follows Vercel AI SDK's evaluation model
+ * specification, which is itself experimental and may change in patch
+ * releases.
+ *
+ * Workflow:
+ *
+ * 1. Pass {@link ILlmEvaluation.questions} to the evaluation model
+ * 2. Receive the answer map keyed by the same question IDs
+ * 3. Use {@link ILlmEvaluation.decode} to fold the answers back into `T`; pass the
+ *    model's declared rounding precision when available
+ *
+ * Related functions:
+ *
+ * - {@link structuredOutput} — Structured output generated as text by an LLM
+ *
+ * @template T Target decision type (object with static properties)
+ * @returns LLM evaluation questions with a checked answer decoder
+ */
+export function evaluation<T extends Record<string, any>>(): ILlmEvaluation<T>;
+
+/** @internal */
+export function evaluation(): never {
+  NoTransformConfigurationError("llm.evaluation");
+}
+
 /* -----------------------------------------------------------
   RAW SCHEMAS
 ----------------------------------------------------------- */

package/src/re-exports.ts

@@ -25,6 +25,7 @@ export type {
   ILlmApplication,
   ILlmFunction,
   ILlmStructuredOutput,
+  ILlmEvaluation,
   ILlmSchema,
   // reflect
   IMetadataSchema,