typia 13.1.1 → 13.2.0

package/src/internal/_notationSnake.ts

@@ -1,22 +1,4 @@
-export const _notationSnake = (str: string): string => {
-  if (str.length === 0) return str;
-
-  // PREFIX
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  let prefix: string = "";
-  for (let i: number = 0; i < str.length; i++) {
-    if (str[i] === "_") prefix += "_";
-    else break;
-  }
-  if (prefix.length !== 0) str = str.substring(prefix.length);
-
-  const out = (s: string) => `${prefix}${s}`;
-
-  // SNAKE CASE
-  const items: string[] = str.split("_");
-  if (items.length > 1) return out(items.map((s) => s.toLowerCase()).join("_"));
-
-  // CAMEL OR PASCAL CASE
+const _notationSnakeWord = (str: string): string => {
   const indexes: number[] = [];
   for (let i: number = 0; i < str.length; i++) {
     const code: number = str.charCodeAt(i);
@@ -28,7 +10,7 @@ export const _notationSnake = (str: string): string => {
     if (now - prev === 1) indexes.splice(i, 1);
   }
   if (indexes.length !== 0 && indexes[0] === 0) indexes.splice(0, 1);
-  if (indexes.length === 0) return out(str.toLowerCase());
+  if (indexes.length === 0) return str.toLowerCase();
 
   let ret: string = "";
   for (let i: number = 0; i < indexes.length; i++) {
@@ -39,5 +21,26 @@ export const _notationSnake = (str: string): string => {
     ret += "_";
   }
   ret += str.substring(indexes[indexes.length - 1]!).toLowerCase();
-  return out(ret);
+  return ret;
+};
+
+export const _notationSnake = (str: string): string => {
+  if (str.length === 0) return str;
+
+  // PREFIX
+  let prefix: string = "";
+  for (let i: number = 0; i < str.length; i++) {
+    if (str[i] === "_") prefix += "_";
+    else break;
+  }
+  if (prefix.length !== 0) str = str.substring(prefix.length);
+
+  // SNAKE CASE
+  //
+  // Run the case-boundary walk within each underscore-delimited segment, not
+  // over the whole segment at once. Lowercasing a segment atomically would drop
+  // the camelCase boundary inside it (`["fooBar", "baz"]` -> `["foobar", "baz"]`
+  // -> `foobar_baz`), diverging from `SnakeCase<T>`; the per-segment walk keeps
+  // it (`["foo_bar", "baz"]` -> `foo_bar_baz`).
+  return `${prefix}${str.split("_").map(_notationSnakeWord).join("_")}`;
 };

package/src/internal/_plainCloneAny.ts

@@ -3,44 +3,219 @@ import { Resolved } from "@typia/interface";
 export const _plainCloneAny = <T>(value: T): Resolved<T> =>
   cloneMain(value) as Resolved<T>;
 
+const NOT_NATIVE = Symbol("not-native");
+const objectToString = Object.prototype.toString;
+const getter = (prototype: object, key: PropertyKey): (() => unknown) =>
+  Object.getOwnPropertyDescriptor(prototype, key)!.get!;
+const read = <T>(accessor: () => unknown, value: object): T =>
+  Reflect.apply(accessor, value, []) as T;
+const tryRead = <T>(
+  accessor: (() => unknown) | undefined,
+  value: object,
+): { success: true; value: T } | { success: false } => {
+  if (accessor === undefined) return { success: false };
+  try {
+    return { success: true, value: read<T>(accessor, value) };
+  } catch {
+    return { success: false };
+  }
+};
+
+const arrayBufferByteLength = getter(ArrayBuffer.prototype, "byteLength");
+const sharedArrayBufferByteLength =
+  typeof SharedArrayBuffer === "undefined"
+    ? undefined
+    : getter(SharedArrayBuffer.prototype, "byteLength");
+const dataViewBuffer = getter(DataView.prototype, "buffer");
+const dataViewByteLength = getter(DataView.prototype, "byteLength");
+const dataViewByteOffset = getter(DataView.prototype, "byteOffset");
+const typedArrayName = getter(
+  Object.getPrototypeOf(Uint8Array.prototype),
+  Symbol.toStringTag,
+);
+const blobSize =
+  typeof Blob === "undefined" ? undefined : getter(Blob.prototype, "size");
+const blobType =
+  typeof Blob === "undefined" ? undefined : getter(Blob.prototype, "type");
+const fileName =
+  typeof File === "undefined" ? undefined : getter(File.prototype, "name");
+const fileLastModified =
+  typeof File === "undefined"
+    ? undefined
+    : getter(File.prototype, "lastModified");
+const regexpSource = getter(RegExp.prototype, "source");
+const regexpFlags = getter(RegExp.prototype, "flags");
+
+const nativeTag = (value: object): string | undefined => {
+  let tagged: boolean;
+  try {
+    tagged = Symbol.toStringTag in value;
+  } catch {
+    return undefined;
+  }
+  if (!tagged)
+    try {
+      return objectToString.call(value);
+    } catch {
+      return undefined;
+    }
+
+  const date = tryRead<number>(Date.prototype.getTime, value);
+  if (date.success) return "[object Date]";
+  const typed = tryRead<string>(typedArrayName, value);
+  if (typed.success && typed.value !== undefined)
+    return `[object ${typed.value}]`;
+  if (tryRead<number>(arrayBufferByteLength, value).success)
+    return "[object ArrayBuffer]";
+  if (tryRead<number>(sharedArrayBufferByteLength, value).success)
+    return "[object SharedArrayBuffer]";
+  if (tryRead<ArrayBufferLike>(dataViewBuffer, value).success)
+    return "[object DataView]";
+  if (tryRead<string>(fileName, value).success) return "[object File]";
+  if (tryRead<number>(blobSize, value).success) return "[object Blob]";
+  if (tryRead<string>(regexpSource, value).success) return "[object RegExp]";
+  return undefined;
+};
+
 const cloneMain = (value: any): any => {
   if (value === undefined) return undefined;
   else if (typeof value === "object")
     if (value === null) return null;
     else if (Array.isArray(value)) return value.map(cloneMain);
-    else if (value instanceof Date) return new Date(value);
-    else if (value instanceof Uint8Array) return new Uint8Array(value);
-    else if (value instanceof Uint8ClampedArray)
-      return new Uint8ClampedArray(value);
-    else if (value instanceof Uint16Array) return new Uint16Array(value);
-    else if (value instanceof Uint32Array) return new Uint32Array(value);
-    else if (value instanceof BigUint64Array) return new BigUint64Array(value);
-    else if (value instanceof Int8Array) return new Int8Array(value);
-    else if (value instanceof Int16Array) return new Int16Array(value);
-    else if (value instanceof Int32Array) return new Int32Array(value);
-    else if (value instanceof BigInt64Array) return new BigInt64Array(value);
-    else if (value instanceof Float32Array) return new Float32Array(value);
-    else if (value instanceof Float64Array) return new Float64Array(value);
-    else if (value instanceof ArrayBuffer) return value.slice(0);
-    else if (value instanceof SharedArrayBuffer) return value.slice(0);
-    else if (value instanceof DataView)
-      return new DataView(value.buffer.slice(0));
-    else if (typeof File !== "undefined" && value instanceof File)
-      return new File([value], value.name, { type: value.type });
-    else if (typeof Blob !== "undefined" && value instanceof Blob)
-      return new Blob([value], { type: value.type });
-    else if (value instanceof Set) return new Set([...value].map(cloneMain));
-    else if (value instanceof Map)
-      return new Map([...value].map(([k, v]) => [cloneMain(k), cloneMain(v)]));
-    else if (value instanceof WeakSet || value instanceof WeakMap)
-      throw new Error("WeakSet and WeakMap are not supported");
-    else if (value.valueOf() !== value) return cloneMain(value.valueOf());
-    else
-      return Object.fromEntries(
-        Object.entries(value)
-          .map(([k, v]) => [k, cloneMain(v)])
-          .filter(([, v]) => v !== undefined),
-      );
+    else {
+      const native: any | typeof NOT_NATIVE = cloneNative(value);
+      if (native !== NOT_NATIVE) return native;
+      else if (value instanceof Set) return new Set([...value].map(cloneMain));
+      else if (value instanceof Map)
+        return new Map(
+          [...value].map(([k, v]) => [cloneMain(k), cloneMain(v)]),
+        );
+      else if (value instanceof WeakSet || value instanceof WeakMap)
+        throw new Error("WeakSet and WeakMap are not supported");
+      else {
+        const primitive: unknown = value.valueOf();
+        if (primitive !== value) return cloneMain(primitive);
+        return Object.fromEntries(
+          Object.entries(value)
+            .map(([k, v]) => [k, cloneMain(v)])
+            .filter(([, v]) => v !== undefined),
+        );
+      }
+    }
   else if (typeof value === "function") return undefined;
   return value;
 };
+
+const cloneNative = (value: object): any | typeof NOT_NATIVE => {
+  const tag: string | undefined = nativeTag(value);
+  switch (tag) {
+    case "[object Date]": {
+      const time = tryRead<number>(Date.prototype.getTime, value);
+      return time.success ? new Date(time.value) : NOT_NATIVE;
+    }
+    case "[object Uint8Array]":
+      return new Uint8Array(value as ArrayLike<number>);
+    case "[object Uint8ClampedArray]":
+      return new Uint8ClampedArray(value as ArrayLike<number>);
+    case "[object Uint16Array]":
+      return new Uint16Array(value as ArrayLike<number>);
+    case "[object Uint32Array]":
+      return new Uint32Array(value as ArrayLike<number>);
+    case "[object BigUint64Array]":
+      return new BigUint64Array(value as ArrayLike<bigint>);
+    case "[object Int8Array]":
+      return new Int8Array(value as ArrayLike<number>);
+    case "[object Int16Array]":
+      return new Int16Array(value as ArrayLike<number>);
+    case "[object Int32Array]":
+      return new Int32Array(value as ArrayLike<number>);
+    case "[object BigInt64Array]":
+      return new BigInt64Array(value as ArrayLike<bigint>);
+    case "[object Float32Array]":
+      return new Float32Array(value as ArrayLike<number>);
+    case "[object Float64Array]":
+      return new Float64Array(value as ArrayLike<number>);
+    case "[object ArrayBuffer]": {
+      const byteLength = tryRead<number>(arrayBufferByteLength, value);
+      return byteLength.success
+        ? cloneBufferRange(value as ArrayBuffer, 0, byteLength.value, false)
+        : NOT_NATIVE;
+    }
+    case "[object SharedArrayBuffer]": {
+      const byteLength = tryRead<number>(sharedArrayBufferByteLength, value);
+      return byteLength.success
+        ? cloneBufferRange(
+            value as SharedArrayBuffer,
+            0,
+            byteLength.value,
+            true,
+          )
+        : NOT_NATIVE;
+    }
+    case "[object DataView]": {
+      const buffer = tryRead<ArrayBufferLike>(dataViewBuffer, value);
+      if (!buffer.success) return NOT_NATIVE;
+      const byteOffset: number = read(dataViewByteOffset, value);
+      const byteLength: number = read(dataViewByteLength, value);
+      return new DataView(
+        cloneBufferRange(buffer.value, byteOffset, byteLength),
+      );
+    }
+    case "[object File]": {
+      const size = tryRead<number>(blobSize, value);
+      if (
+        typeof File === "undefined" ||
+        !size.success ||
+        blobType === undefined ||
+        fileName === undefined ||
+        fileLastModified === undefined
+      )
+        return NOT_NATIVE;
+      return new File([value as Blob], read<string>(fileName, value), {
+        type: read<string>(blobType, value),
+        lastModified: read<number>(fileLastModified, value),
+      });
+    }
+    case "[object Blob]": {
+      const size = tryRead<number>(blobSize, value);
+      if (
+        typeof Blob === "undefined" ||
+        !size.success ||
+        blobType === undefined
+      )
+        return NOT_NATIVE;
+      return new Blob([value as Blob], {
+        type: read<string>(blobType, value),
+      });
+    }
+    case "[object RegExp]": {
+      const source = tryRead<string>(regexpSource, value);
+      return source.success
+        ? new RegExp(source.value, read<string>(regexpFlags, value))
+        : NOT_NATIVE;
+    }
+    default:
+      return NOT_NATIVE;
+  }
+};
+
+const cloneBufferRange = (
+  input: ArrayBufferLike,
+  byteOffset: number,
+  byteLength: number,
+  shared?: boolean,
+): ArrayBuffer | SharedArrayBuffer => {
+  if (shared === undefined)
+    shared = tryRead<number>(sharedArrayBufferByteLength, input).success;
+  let output: ArrayBuffer | SharedArrayBuffer;
+  if (shared) {
+    if (typeof SharedArrayBuffer === "undefined")
+      throw new TypeError("SharedArrayBuffer is not available");
+    output = new SharedArrayBuffer(byteLength);
+  } else {
+    read<number>(arrayBufferByteLength, input);
+    output = new ArrayBuffer(byteLength);
+  }
+  new Uint8Array(output).set(new Uint8Array(input, byteOffset, byteLength));
+  return output;
+};

package/src/internal/_randomArray.ts

@@ -1,5 +1,6 @@
 import type { OpenApi } from "@typia/interface";
 
+import { _isUniqueItems } from "./_isUniqueItems";
 import { _randomInteger } from "./_randomInteger";
 
 const DEFAULT_MIN_ITEMS = 1;
@@ -27,8 +28,16 @@ export const _randomArray = <T>(
   });
   if (props.uniqueItems !== true)
     return new Array(count).fill(null).map((_, i) => props.element(i, count));
-  const elements: Set<any> = new Set();
-  while (elements.size !== count)
-    elements.add(props.element(elements.size, count));
-  return Array.from(elements);
+  const elements: T[] = [];
+  const maximumAttempts: number = count * 100 + 1000;
+  for (let attempts = 0; elements.length !== count; attempts++) {
+    if (attempts === maximumAttempts)
+      throw new Error(
+        "Unable to generate enough unique items; the element domain may be too small.",
+      );
+    const candidate: T = props.element(elements.length, count);
+    if (elements.every((element) => _isUniqueItems([element, candidate])))
+      elements.push(candidate);
+  }
+  return elements;
 };

package/src/internal/_randomFormatByte.ts

@@ -1,3 +1,33 @@
-export const _randomFormatByte = (): string => FIXED;
+import { _randomString } from "./_randomString";
+import {
+  _ILengthProps,
+  _RANDOM_LENGTH_ERROR,
+  _randomLengthPick,
+  _randomLengthWindow,
+} from "./_randomStringLength";
+
+export const _randomFormatByte = (props?: _ILengthProps): string => {
+  if (props?.minLength === undefined && props?.maxLength === undefined)
+    return FIXED;
+  // Base64 encodes three bytes as four characters, so a valid length is always
+  // a multiple of four; the window is raised to the first multiple it contains
+  // and the draw steps by four from there. Every character `_randomString`
+  // emits is in the base64 alphabet, so the result needs no padding.
+  const window = _randomLengthWindow(props, { minimum: 0, spread: 16 });
+  const low: number = Math.ceil(window.low / 4) * 4;
+  if (low > window.high) throw new Error(_RANDOM_LENGTH_ERROR);
+  const length: number =
+    low +
+    4 *
+      _randomLengthPick({
+        low: 0,
+        high: Math.floor((window.high - low) / 4),
+      });
+  return _randomString({
+    type: "string",
+    minLength: length,
+    maxLength: length,
+  });
+};
 
 const FIXED = "vt7ekz4lIoNTTS9sDQYdWKharxIFAR54+z/umIxSgUM=";

package/src/internal/_randomFormatDate.ts

@@ -1,18 +1,7 @@
-import { _randomInteger } from "./_randomInteger";
+import { _ILengthProps, _randomFormatLength } from "./_randomStringLength";
+import { __IEpochProps, __randomEpoch } from "./private/__randomEpoch";
 
-export const _randomFormatDate = (props?: {
-  minimum?: number;
-  maximum?: number;
-}) =>
-  new Date(
-    _randomInteger({
-      type: "integer",
-      minimum: props?.minimum ?? 0,
-      maximum:
-        (props?.maximum ?? props?.minimum === undefined)
-          ? Date.now()
-          : props.minimum + 365 * 24 * 60 * 60 * 1_000,
-    }),
-  )
-    .toISOString()
-    .substring(0, 10);
+export const _randomFormatDate = (props?: __IEpochProps & _ILengthProps) =>
+  _randomFormatLength(props, () =>
+    new Date(__randomEpoch(props)).toISOString().substring(0, 10),
+  );

package/src/internal/_randomFormatDatetime.ts

@@ -1,16 +1,35 @@
-import { _randomInteger } from "./_randomInteger";
+import {
+  _ILengthProps,
+  _RANDOM_LENGTH_ERROR,
+  _randomLengthPick,
+  _randomLengthWindow,
+} from "./_randomStringLength";
+import { __randomDigits } from "./private/__randomComposition";
+import { __IEpochProps, __randomEpoch } from "./private/__randomEpoch";
 
-export const _randomFormatDatetime = (props?: {
-  minimum?: number;
-  maximum?: number;
-}) =>
-  new Date(
-    _randomInteger({
-      type: "integer",
-      minimum: props?.minimum ?? 0,
-      maximum:
-        (props?.maximum ?? props?.minimum === undefined)
-          ? Date.now()
-          : props.minimum + 365 * 24 * 60 * 60 * 1_000,
-    }),
-  ).toISOString();
+export const _randomFormatDatetime = (
+  props?: __IEpochProps & _ILengthProps,
+) => {
+  const instant = (): string => new Date(__randomEpoch(props)).toISOString();
+  if (props?.minLength === undefined && props?.maxLength === undefined)
+    return instant();
+  // `YYYY-MM-DDTHH:MM:SS` plus `Z` is the shortest instant, and a fractional
+  // second grows it one digit at a time. Because that fraction needs both a dot
+  // and at least one digit, 21 is the single length between the two forms that
+  // no instant can have.
+  const window = _randomLengthWindow(props, {
+    minimum: SECONDS + 1,
+    spread: 8,
+  });
+  let length: number = _randomLengthPick(window);
+  if (length === SECONDS + 2)
+    length = window.high >= SECONDS + 3 ? SECONDS + 3 : SECONDS + 1;
+  if (length < window.low || length > window.high)
+    throw new Error(_RANDOM_LENGTH_ERROR);
+  const base: string = instant().substring(0, SECONDS);
+  return length === SECONDS + 1
+    ? `${base}Z`
+    : `${base}.${__randomDigits(length - SECONDS - 2)}Z`;
+};
+
+const SECONDS = "0000-00-00T00:00:00".length;

package/src/internal/_randomFormatDuration.ts

@@ -1,19 +1,36 @@
 import { _randomInteger } from "./_randomInteger";
+import {
+  _ILengthProps,
+  _randomLengthPick,
+  _randomLengthWindow,
+} from "./_randomStringLength";
+import { __randomNumeric } from "./private/__randomComposition";
 
-export const _randomFormatDuration = (): string => {
-  const period: string = durate([
-    ["Y", random(0, 100)],
-    ["M", random(0, 12)],
-    ["D", random(0, 31)],
-  ]);
-  const time: string = durate([
-    ["H", random(0, 24)],
-    ["M", random(0, 60)],
-    ["S", random(0, 60)],
-  ]);
-  if (period.length + time.length === 0) return "PT0S";
-  return `P${period}${time.length ? "T" : ""}${time}`;
+export const _randomFormatDuration = (props?: _ILengthProps): string => {
+  if (props?.minLength === undefined && props?.maxLength === undefined) {
+    const period: string = durate([
+      ["Y", random(0, 100)],
+      ["M", random(0, 12)],
+      ["D", random(0, 31)],
+    ]);
+    const time: string = durate([
+      ["H", random(0, 24)],
+      ["M", random(0, 60)],
+      ["S", random(0, 60)],
+    ]);
+    if (period.length + time.length === 0) return "PT0S";
+    return `P${period}${time.length ? "T" : ""}${time}`;
+  }
+  // A single designator carries an unbounded digit count, so `P<n>Y` expresses
+  // every length from three upward and `P1Y` is the shortest duration there is.
+  const length: number = _randomLengthPick(
+    _randomLengthWindow(props, { minimum: MINIMUM, spread: 6 }),
+  );
+  return `P${__randomNumeric(length - MINIMUM + 1)}Y`;
 };
+
+const MINIMUM = "P1Y".length;
+
 const durate = (elements: [string, number][]) =>
   elements
     .filter(([_unit, value]) => value !== 0)

package/src/internal/_randomFormatEmail.ts

@@ -1,7 +1,13 @@
 import { _randomString } from "./_randomString";
+import { _ILengthProps, _randomSegmentLength } from "./_randomStringLength";
 
-export const _randomFormatEmail = (): string =>
-  `${random(10)}@${random(10)}.${random(3)}`;
+export const _randomFormatEmail = (props?: _ILengthProps): string => {
+  if (props?.minLength === undefined && props?.maxLength === undefined)
+    return `${random(10)}@${random(10)}.${random(3)}`;
+  // `<local>@<domain>.<tld>`: the local part absorbs the requested length while
+  // a one-character domain and tld keep the fixed overhead (`@`, `.`) minimal.
+  return `${_randomSegmentLength(props, 4, 10, 1)}@${random(1)}.${random(1)}`;
+};
 
 const random = (length: number) =>
   _randomString({

package/src/internal/_randomFormatHostname.ts

@@ -1,6 +1,53 @@
+import { _randomInteger } from "./_randomInteger";
 import { _randomString } from "./_randomString";
+import { _ILengthProps } from "./_randomStringLength";
 
-export const _randomFormatHostname = (): string => `${random(10)}.${random(3)}`;
+export const _randomFormatHostname = (props?: _ILengthProps): string => {
+  if (props?.minLength === undefined && props?.maxLength === undefined)
+    return `${random(10)}.${random(3)}`;
+  // A hostname is dot-joined labels of 1..63 chars whose total is capped at 253,
+  // so the requested length is realized by splitting it across enough labels.
+  return _randomHostnameLabels(pickLength(props));
+};
+
+const MAX_TOTAL = 253;
+const MAX_LABEL = 63;
+
+const pickLength = (props: _ILengthProps): number => {
+  let low: number = props.minLength === undefined ? 1 : props.minLength;
+  if (low < 1) low = 1;
+  const high: number =
+    props.maxLength === undefined
+      ? Math.min(MAX_TOTAL, low + 14)
+      : Math.min(MAX_TOTAL, props.maxLength);
+  if (high < low)
+    throw new Error(
+      "unable to generate a random hostname satisfying both the format and the length constraints.",
+    );
+  return _randomInteger({ type: "integer", minimum: low, maximum: high });
+};
+
+/**
+ * Builds dot-joined hostname labels totaling exactly `length` characters, each
+ * label within 63 chars. Shared with the idn-hostname generator, which reserves
+ * a fixed `.<tld>` suffix and realizes the rest as these leading labels.
+ */
+export const _randomHostnameLabels = (length: number): string => {
+  const parts: string[] = [];
+  let remaining: number = length;
+  while (remaining > MAX_LABEL + 1) {
+    // one full label plus its joining dot
+    parts.push(random(MAX_LABEL));
+    remaining -= MAX_LABEL + 1;
+  }
+  if (remaining <= MAX_LABEL) parts.push(random(remaining));
+  else {
+    // remaining === MAX_LABEL + 1: two labels keep every label within 63 chars
+    parts.push(random(MAX_LABEL - 1));
+    parts.push(random(1));
+  }
+  return parts.join(".");
+};
 
 const random = (length: number) =>
   _randomString({ type: "string", minLength: length, maxLength: length });

package/src/internal/_randomFormatIdnEmail.ts

@@ -1,3 +1,19 @@
-import { _randomFormatEmail } from "./_randomFormatEmail";
+import { _randomString } from "./_randomString";
+import { _ILengthProps, _randomSegmentLength } from "./_randomStringLength";
 
-export const _randomFormatIdnEmail = (): string => _randomFormatEmail();
+export const _randomFormatIdnEmail = (props?: _ILengthProps): string => {
+  if (props?.minLength === undefined && props?.maxLength === undefined)
+    return `${random(10)}@${random(10)}.${random(3)}`;
+  // `_isFormatIdnEmail` requires a >=2-char TLD (`(…\.)+[^…]{2,}`), so the fixed
+  // overhead is `@` + domain(1) + `.` + tld(2) = 5 and the local part absorbs the
+  // requested length; a one-character TLD (the non-idn generator's length path)
+  // would be rejected by the idn checker on every draw.
+  return `${_randomSegmentLength(props, 5, 10, 1)}@${random(1)}.${random(2)}`;
+};
+
+const random = (length: number) =>
+  _randomString({
+    type: "string",
+    minLength: length,
+    maxLength: length,
+  });

package/src/internal/_randomFormatIdnHostname.ts

@@ -1,3 +1,35 @@
-import { _randomFormatHostname } from "./_randomFormatHostname";
+import { _randomHostnameLabels } from "./_randomFormatHostname";
+import { _randomInteger } from "./_randomInteger";
+import { _randomString } from "./_randomString";
+import { _ILengthProps } from "./_randomStringLength";
 
-export const _randomFormatIdnHostname = (): string => _randomFormatHostname();
+export const _randomFormatIdnHostname = (props?: _ILengthProps): string => {
+  if (props?.minLength === undefined && props?.maxLength === undefined)
+    return `${random(10)}.${random(3)}`;
+  // `_isFormatIdnHostname` requires at least one label, a dot, and a >=2-char
+  // TLD (`(…\.)+[a-z¡-￿]{2,}`), none of which the non-idn hostname generator
+  // guarantees on its length path (it can emit a single dotless label). Reserve
+  // a fixed `.<2-char TLD>` and realize the rest as dot-joined leading labels.
+  const length: number = pickLength(props);
+  return `${_randomHostnameLabels(length - 3)}.${random(2)}`;
+};
+
+const MAX_TOTAL = 253;
+const MIN_TOTAL = 4; // the shortest idn hostname, `x.yy`: label(1) + `.` + tld(2)
+
+const pickLength = (props: _ILengthProps): number => {
+  let low: number = props.minLength === undefined ? MIN_TOTAL : props.minLength;
+  if (low < MIN_TOTAL) low = MIN_TOTAL;
+  const high: number =
+    props.maxLength === undefined
+      ? Math.min(MAX_TOTAL, low + 14)
+      : Math.min(MAX_TOTAL, props.maxLength);
+  if (high < low)
+    throw new Error(
+      "unable to generate a random idn hostname satisfying both the format and the length constraints.",
+    );
+  return _randomInteger({ type: "integer", minimum: low, maximum: high });
+};
+
+const random = (length: number) =>
+  _randomString({ type: "string", minLength: length, maxLength: length });