typia 13.1.19 → 13.3.0

package/src/internal/_randomFormatDatetime.ts

@@ -1,21 +1,35 @@
-import { _randomInteger } from "./_randomInteger";
-import { _randomFormatLength } from "./_randomStringLength";
+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;
-  minLength?: number;
-  maxLength?: number;
-}) =>
-  _randomFormatLength(props, () =>
-    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,8 +1,13 @@
 import { _randomInteger } from "./_randomInteger";
-import { _ILengthProps, _randomFormatLength } from "./_randomStringLength";
+import {
+  _ILengthProps,
+  _randomLengthPick,
+  _randomLengthWindow,
+} from "./_randomStringLength";
+import { __randomNumeric } from "./private/__randomComposition";
 
-export const _randomFormatDuration = (props?: _ILengthProps): string =>
-  _randomFormatLength(props, () => {
+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)],
@@ -15,7 +20,17 @@ export const _randomFormatDuration = (props?: _ILengthProps): string =>
     ]);
     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/_randomFormatHostname.ts

@@ -29,8 +29,8 @@ const pickLength = (props: _ILengthProps): number => {
 
 /**
  * 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.
+ * label within 63 chars. Shared with the idn-hostname generator, which realizes
+ * its length the same way since #2317 gave the two formats one structure.
  */
 export const _randomHostnameLabels = (length: number): string => {
   const parts: string[] = [];

package/src/internal/_randomFormatIdnHostname.ts

@@ -6,20 +6,19 @@ import { _ILengthProps } from "./_randomStringLength";
 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)}`;
+  // idn-hostname shares hostname's structure (a single label of 1..63 chars is
+  // valid, no dot or trailing label required), so the requested length is
+  // realized the same way: split it across dot-joined labels. #2317 dropped the
+  // mandatory dot and two-character trailing label this generator used to
+  // reserve, which is why it now realizes a length below four.
+  return _randomHostnameLabels(pickLength(props));
 };
 
 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;
+  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)

package/src/internal/_randomFormatIpv4.ts

@@ -1,8 +1,37 @@
 import { _randomInteger } from "./_randomInteger";
-import { _ILengthProps, _randomFormatLength } from "./_randomStringLength";
+import {
+  _ILengthProps,
+  _randomLengthPick,
+  _randomLengthWindow,
+} from "./_randomStringLength";
+import { __randomComposition } from "./private/__randomComposition";
 
-export const _randomFormatIpv4 = (props?: _ILengthProps): string =>
-  _randomFormatLength(props, () => new Array(4).fill(0).map(random).join("."));
+export const _randomFormatIpv4 = (props?: _ILengthProps): string => {
+  if (props?.minLength === undefined && props?.maxLength === undefined)
+    return new Array(4).fill(0).map(random).join(".");
+  // Three dots plus four octets of one to three digits: `0.0.0.0` is the
+  // shortest address and `255.255.255.255` the longest, and every length
+  // between them is reached by choosing how many digits each octet spends.
+  const length: number = _randomLengthPick(
+    _randomLengthWindow(props, {
+      minimum: 4 * DIGITS_MIN + DOTS,
+      maximum: 4 * DIGITS_MAX + DOTS,
+      spread: 8,
+    }),
+  );
+  return __randomComposition({
+    total: length - DOTS,
+    count: 4,
+    minimum: DIGITS_MIN,
+    maximum: DIGITS_MAX,
+  })
+    .map(octet)
+    .join(".");
+};
+
+const DOTS = 3;
+const DIGITS_MIN = 1;
+const DIGITS_MAX = 3;
 
 const random = () =>
   _randomInteger({
@@ -10,3 +39,14 @@ const random = () =>
     minimum: 0,
     maximum: 255,
   });
+
+// An octet is bounded by 255, so a three-digit one starts at 100 and stops
+// there rather than at 999.
+const octet = (digits: number): string =>
+  String(
+    _randomInteger({
+      type: "integer",
+      minimum: digits === 1 ? 0 : Math.pow(10, digits - 1),
+      maximum: digits === 3 ? 255 : Math.pow(10, digits) - 1,
+    }),
+  );

package/src/internal/_randomFormatIpv6.ts

@@ -1,8 +1,61 @@
+import { _randomFormatIpv4 } from "./_randomFormatIpv4";
 import { _randomInteger } from "./_randomInteger";
-import { _ILengthProps, _randomFormatLength } from "./_randomStringLength";
+import {
+  _ILengthProps,
+  _randomLengthPick,
+  _randomLengthWindow,
+} from "./_randomStringLength";
+import { __randomComposition } from "./private/__randomComposition";
 
-export const _randomFormatIpv6 = (props?: _ILengthProps): string =>
-  _randomFormatLength(props, () => new Array(8).fill(0).map(random).join(":"));
+export const _randomFormatIpv6 = (props?: _ILengthProps): string => {
+  if (props?.minLength === undefined && props?.maxLength === undefined)
+    return new Array(GROUPS).fill(0).map(random).join(":");
+  const length: number = _randomLengthPick(
+    _randomLengthWindow(props, {
+      minimum: SHORTEST,
+      maximum: LONGEST,
+      spread: 12,
+    }),
+  );
+  // `::` alone is the all-zero address, and the three forms below cover every
+  // length between it and the padded IPv4-suffixed address: a compressed prefix
+  // for the short ones, eight groups of one to four hexadecimal digits for the
+  // middle, and six groups plus a dotted-quad tail for the long ones.
+  if (length === SHORTEST) return "::";
+  if (length < GROUPS * DIGITS_MIN + COLONS) {
+    // `::` plus `count` groups spends one colon between each pair.
+    const count: number = Math.ceil((length - 1) / (DIGITS_MAX + 1));
+    return `::${compose(length - 1 - count, count)}`;
+  }
+  if (length <= GROUPS * DIGITS_MAX + COLONS)
+    return compose(length - COLONS, GROUPS);
+  // The dotted-quad tail is drawn at its longest so the six leading groups keep
+  // a composable number of digits.
+  const tail: string = _randomFormatIpv4({
+    minLength: IPV4_MAX,
+    maxLength: IPV4_MAX,
+  });
+  return `${compose(length - IPV4_MAX - EMBEDDED, EMBEDDED)}:${tail}`;
+};
+
+const GROUPS = 8;
+const COLONS = GROUPS - 1;
+const DIGITS_MIN = 1;
+const DIGITS_MAX = 4;
+const EMBEDDED = 6; // groups preceding a dotted-quad tail
+const IPV4_MAX = "255.255.255.255".length;
+const SHORTEST = "::".length;
+const LONGEST = EMBEDDED * DIGITS_MAX + EMBEDDED + IPV4_MAX;
+
+const compose = (digits: number, count: number): string =>
+  __randomComposition({
+    total: digits,
+    count,
+    minimum: DIGITS_MIN,
+    maximum: DIGITS_MAX,
+  })
+    .map(group)
+    .join(":");
 
 const random = () =>
   _randomInteger({
@@ -10,3 +63,14 @@ const random = () =>
     minimum: 0,
     maximum: 65_535,
   }).toString(16);
+
+const group = (digits: number): string => {
+  let text: string = "";
+  for (let i: number = 0; i < digits; ++i)
+    text += _randomInteger({
+      type: "integer",
+      minimum: 0,
+      maximum: 15,
+    }).toString(16);
+  return text;
+};

package/src/internal/_randomFormatJsonPointer.ts

@@ -1,13 +1,33 @@
 import { _randomString } from "./_randomString";
-import { _ILengthProps, _randomSegmentLength } from "./_randomStringLength";
+import {
+  _ILengthProps,
+  _randomLengthPick,
+  _randomLengthWindow,
+  _randomSegmentLength,
+} from "./_randomStringLength";
 
 export const _randomFormatJsonPointer = (props?: _ILengthProps): string => {
   if (props?.minLength === undefined && props?.maxLength === undefined)
-    return `/components/schemas/${random()}`;
+    return `${PREFIX}${random()}`;
   // The `/components/schemas/` prefix (20 chars) is fixed; the reference token
   // after it grows or shrinks to hit the requested length.
-  return `/components/schemas/${_randomSegmentLength(props, 20, 10, 0)}`;
+  if (props.maxLength === undefined || props.maxLength >= PREFIX.length)
+    return `${PREFIX}${_randomSegmentLength(props, PREFIX.length, 10, 0)}`;
+  // Below that prefix a pointer still exists: the empty pointer addresses the
+  // whole document, and one `/`-prefixed token addresses a member of it.
+  const length: number = _randomLengthPick(
+    _randomLengthWindow(props, { minimum: 0, spread: 6 }),
+  );
+  return length === 0
+    ? ""
+    : `/${_randomString({
+        type: "string",
+        minLength: length - 1,
+        maxLength: length - 1,
+      })}`;
 };
 
+const PREFIX = "/components/schemas/";
+
 const random = () =>
   _randomString({ type: "string", minLength: 10, maxLength: 10 });

package/src/internal/_randomFormatRegex.ts

@@ -1,7 +1,23 @@
-import { _ILengthProps, _randomFormatLength } from "./_randomStringLength";
+import { _randomString } from "./_randomString";
+import {
+  _ILengthProps,
+  _randomLengthPick,
+  _randomLengthWindow,
+} from "./_randomStringLength";
 
-export const _randomFormatRegex = (props?: _ILengthProps): string =>
-  _randomFormatLength(props, () => FIXED);
-
-const FIXED =
-  "/^(?:(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)\\.){3}(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)$/";
+export const _randomFormatRegex = (props?: _ILengthProps): string => {
+  // Every character `_randomString` emits is a literal in regular expression
+  // syntax, so a source of any length — including the empty source `new
+  // RegExp("")` accepts — compiles. An unconstrained draw is therefore an
+  // unconstrained string, and a constrained one fixes the length first.
+  if (props?.minLength === undefined && props?.maxLength === undefined)
+    return _randomString({ type: "string" });
+  const length: number = _randomLengthPick(
+    _randomLengthWindow(props, { minimum: 0, spread: 16 }),
+  );
+  return _randomString({
+    type: "string",
+    minLength: length,
+    maxLength: length,
+  });
+};

package/src/internal/_randomFormatRelativeJsonPointer.ts

@@ -1,15 +1,28 @@
 import { _randomInteger } from "./_randomInteger";
-import { _ILengthProps, _randomFormatLength } from "./_randomStringLength";
+import { _randomString } from "./_randomString";
+import {
+  _ILengthProps,
+  _randomLengthPick,
+  _randomLengthWindow,
+} from "./_randomStringLength";
+import { __randomNumeric } from "./private/__randomComposition";
 
 export const _randomFormatRelativeJsonPointer = (
   props?: _ILengthProps,
-): string =>
-  _randomFormatLength(
-    props,
-    () =>
-      `${_randomInteger({
-        type: "integer",
-        minimum: 0,
-        maximum: 10,
-      })}#`,
+): string => {
+  if (props?.minLength === undefined && props?.maxLength === undefined)
+    return `${_randomInteger({ type: "integer", minimum: 0, maximum: 10 })}#`;
+  // The leading non-negative integer stands alone as a pointer, so a single
+  // digit is the shortest form; `#` names the key and a `/`-prefixed token names
+  // a member, which absorbs any remaining length.
+  const length: number = _randomLengthPick(
+    _randomLengthWindow(props, { minimum: 1, spread: 6 }),
   );
+  if (length === 1) return __randomNumeric(1);
+  if (length === 2) return `${__randomNumeric(1)}#`;
+  return `${__randomNumeric(1)}/${_randomString({
+    type: "string",
+    minLength: length - 2,
+    maxLength: length - 2,
+  })}`;
+};

package/src/internal/_randomFormatTime.ts

@@ -1,17 +1,55 @@
 import { _randomInteger } from "./_randomInteger";
-import { _ILengthProps, _randomFormatLength } from "./_randomStringLength";
+import {
+  _ILengthProps,
+  _RANDOM_LENGTH_ERROR,
+  _randomLengthPick,
+  _randomLengthWindow,
+} from "./_randomStringLength";
+import { __randomDigits } from "./private/__randomComposition";
 
-export const _randomFormatTime = (props?: _ILengthProps): string =>
-  _randomFormatLength(props, () =>
+export const _randomFormatTime = (props?: _ILengthProps): string => {
+  const clock = (): string =>
     new Date(
-      _randomInteger({
-        type: "integer",
-        minimum: 0,
-        maximum: DAY,
-      }),
-    )
-      .toISOString()
-      .substring(11),
-  );
+      _randomInteger({ type: "integer", minimum: 0, maximum: DAY }),
+    ).toISOString();
+  if (props?.minLength === undefined && props?.maxLength === undefined)
+    return clock().substring(11);
+  // `HH:MM:SS` carries a mandatory offset — one character as `Z`, six as
+  // `+HH:MM` — and an optional fraction between them that RFC 3339 leaves
+  // open above. Together they express 9 and every length from 11 upward; 10 is
+  // the one gap, because a fraction needs both a dot and a digit.
+  const window = _randomLengthWindow(props, {
+    minimum: CLOCK + 1,
+    spread: 6,
+  });
+  let length: number = _randomLengthPick(window);
+  if (length === CLOCK + 2)
+    length = window.high >= CLOCK + 3 ? CLOCK + 3 : CLOCK + 1;
+  if (length < window.low || length > window.high)
+    throw new Error(_RANDOM_LENGTH_ERROR);
+  const base: string = clock().substring(11, 11 + CLOCK);
+  if (length === CLOCK + 1) return `${base}Z`;
+  // The `Z` form reaches every remaining length by itself, so the numeric
+  // offset is a choice rather than a fallback: it spends six characters, which
+  // leaves either nothing (14, `HH:MM:SS+HH:MM`) or a whole fraction (16 and
+  // up). At 15 only the `Z` form fits, since the offset would demand a dot
+  // with no digit after it.
+  const fraction: number = length - CLOCK - OFFSET - 1;
+  return (fraction === -1 || fraction >= 1) &&
+    _randomInteger({ type: "integer", minimum: 0, maximum: 1 }) === 1
+    ? fraction === -1
+      ? `${base}${offset()}`
+      : `${base}.${__randomDigits(fraction)}${offset()}`
+    : `${base}.${__randomDigits(length - CLOCK - 2)}Z`;
+};
 
 const DAY = 86_400_000;
+const CLOCK = "00:00:00".length;
+const OFFSET = "+00:00".length;
+
+const offset = (): string =>
+  `${_randomInteger({ type: "integer", minimum: 0, maximum: 1 }) === 0 ? "+" : "-"}${pad(
+    _randomInteger({ type: "integer", minimum: 0, maximum: 23 }),
+  )}:${pad(_randomInteger({ type: "integer", minimum: 0, maximum: 59 }))}`;
+
+const pad = (value: number): string => String(value).padStart(2, "0");

package/src/internal/_randomPattern.ts

@@ -2,7 +2,10 @@ import RandExp from "randexp";
 
 import { _ILengthProps } from "./_randomStringLength";
 
-export const _randomPattern = (regex: RegExp, props?: _ILengthProps): string => {
+export const _randomPattern = (
+  regex: RegExp,
+  props?: _ILengthProps,
+): string => {
   const r: RandExp = new RandExp(regex);
   const min: number | undefined = props?.minLength;
   const max: number | undefined = props?.maxLength;

package/src/internal/_randomStringLength.ts

@@ -1,5 +1,9 @@
+import { _randomInteger } from "./_randomInteger";
 import { _randomString } from "./_randomString";
 
+export const _RANDOM_LENGTH_ERROR =
+  "unable to generate a random string satisfying both the format and the length constraints.";
+
 /**
  * Length bounds forwarded to a string format or pattern generator.
  *
@@ -18,10 +22,10 @@ export interface _ILengthProps {
  * length `fixed + segment.length` lands inside the requested window.
  *
  * `fixed` is the number of characters the format always contributes around the
- * segment, `fallback` is the segment length used when the leaf is
- * unconstrained on that side, and `minimum` is the smallest segment the format
- * still validates with. Throws when the window cannot be satisfied by this
- * format's shape (e.g. `Format<"email"> & MaxLength<3>`).
+ * segment, `fallback` is the segment length used when the leaf is unconstrained
+ * on that side, and `minimum` is the smallest segment the format still
+ * validates with. Throws when the window cannot be satisfied by this format's
+ * shape (e.g. `Format<"email"> & MaxLength<3>`).
  */
 export const _randomSegmentLength = (
   props: _ILengthProps | undefined,
@@ -36,21 +40,63 @@ export const _randomSegmentLength = (
   // characters so the generated length varies, mirroring `_randomString`.
   const high: number =
     props?.maxLength === undefined ? low + fallback : props.maxLength - fixed;
-  if (high < low || high < minimum)
-    throw new Error(
-      "unable to generate a random string satisfying both the format and the length constraints.",
-    );
+  if (high < low || high < minimum) throw new Error(_RANDOM_LENGTH_ERROR);
   return _randomString({ type: "string", minLength: low, maxLength: high });
 };
 
 /**
- * Wraps a fixed- or narrow-length format generator (uuid, ipv4, date, ...) with
- * the requested length window.
+ * Intersects the requested length window with the lengths a format's grammar
+ * can express, and draws one of them.
+ *
+ * `minimum` and `maximum` are the shortest and longest values the format admits
+ * — omit `maximum` when the grammar is open above — and `spread` is how far
+ * past the floor an unbounded request may reach, so an open side still varies
+ * the way `_randomString` does. The caller draws from the returned window and
+ * applies whatever step its grammar has (base64 lengths are multiples of four,
+ * a fractional second needs at least one digit).
+ *
+ * Throws only when the window and the grammar do not overlap at all. That is
+ * the distinction the retry driver below cannot make: it redraws one shape, so
+ * it gives up on every length that shape never emits even when the format
+ * itself accepts one (issue #2284).
+ */
+export const _randomLengthWindow = (
+  props: _ILengthProps | undefined,
+  format: { minimum: number; maximum?: number; spread?: number },
+): { low: number; high: number } => {
+  const ceiling: number = format.maximum ?? Number.MAX_SAFE_INTEGER;
+  const low: number = Math.max(
+    props?.minLength ?? format.minimum,
+    format.minimum,
+  );
+  const high: number = Math.min(
+    props?.maxLength ?? low + (format.spread ?? 0),
+    ceiling,
+  );
+  if (low > high) throw new Error(_RANDOM_LENGTH_ERROR);
+  return { low, high };
+};
+
+/** Draws a length inside a window produced by {@link _randomLengthWindow}. */
+export const _randomLengthPick = (window: {
+  low: number;
+  high: number;
+}): number =>
+  _randomInteger({
+    type: "integer",
+    minimum: window.low,
+    maximum: window.high,
+  });
+
+/**
+ * Wraps a fixed-length format generator (uuid, date) with the requested length
+ * window.
  *
- * These formats cannot grow an arbitrary segment, so the generator is retried a
- * bounded number of times and the first draw inside the window is returned. A
- * window that excludes every length the format can produce is unsatisfiable and
- * throws instead of silently yielding an out-of-range value.
+ * Use it only where the grammar admits exactly one length, so a window that
+ * excludes it is genuinely unsatisfiable. A format that can express more than
+ * one length must build its value at a length drawn from
+ * {@link _randomLengthWindow} instead; redrawing one shape cannot reach a length
+ * that shape never emits.
  */
 export const _randomFormatLength = (
   props: _ILengthProps | undefined,
@@ -66,7 +112,5 @@ export const _randomFormatLength = (
     )
       return value;
   }
-  throw new Error(
-    "unable to generate a random string satisfying both the format and the length constraints.",
-  );
+  throw new Error(_RANDOM_LENGTH_ERROR);
 };

package/src/internal/private/__notationRename.ts

@@ -9,10 +9,7 @@
  * collapsing it to the underscore-free `plain` path.
  */
 export const __notationRename =
-  (props: {
-    plain: (str: string) => string;
-    snake: (str: string) => string;
-  }) =>
+  (props: { plain: (str: string) => string; snake: (str: string) => string }) =>
   (str: string): string => {
     let prefix: string = "";
     while (str.startsWith("_")) {

package/src/internal/private/__randomComposition.ts

@@ -0,0 +1,74 @@
+import { _randomInteger } from "../_randomInteger";
+
+/**
+ * Splits `total` into `count` parts, each inside `[minimum, maximum]`.
+ *
+ * Used where a format's length is the sum of its segments — an IPv4 octet spans
+ * one to three digits, an IPv6 group one to four — so a requested total length
+ * is realized by choosing how many characters each segment contributes instead
+ * of redrawing whole addresses and hoping one lands in the window (issue
+ * #2284).
+ *
+ * The caller guarantees `count * minimum <= total <= count * maximum`; each
+ * part is drawn from the range that still leaves the remaining parts
+ * satisfiable.
+ */
+export const __randomComposition = (props: {
+  total: number;
+  count: number;
+  minimum: number;
+  maximum: number;
+}): number[] => {
+  const parts: number[] = [];
+  let remaining: number = props.total;
+  for (let i: number = 0; i < props.count; ++i) {
+    const rest: number = props.count - i - 1;
+    const value: number = _randomInteger({
+      type: "integer",
+      minimum: Math.max(props.minimum, remaining - rest * props.maximum),
+      maximum: Math.min(props.maximum, remaining - rest * props.minimum),
+    });
+    parts.push(value);
+    remaining -= value;
+  }
+  return parts;
+};
+
+/**
+ * Draws `length` characters of the base64 alphabet.
+ *
+ * The caller passes a multiple of four, which `format: "byte"` accepts without
+ * padding; every character below is in the alphabet its validator spells out,
+ * so the result needs no encoding step.
+ */
+export const __randomBase64 = (length: number): string => {
+  let text: string = "";
+  for (let i: number = 0; i < length; ++i)
+    text +=
+      BASE64[
+        _randomInteger({
+          type: "integer",
+          minimum: 0,
+          maximum: BASE64.length - 1,
+        })
+      ];
+  return text;
+};
+
+const BASE64 =
+  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+/** Draws `length` decimal digits, leading zeros included. */
+export const __randomDigits = (length: number): string => {
+  let text: string = "";
+  for (let i: number = 0; i < length; ++i)
+    text += String(_randomInteger({ type: "integer", minimum: 0, maximum: 9 }));
+  return text;
+};
+
+/** Draws a decimal number of exactly `length` digits without a leading zero. */
+export const __randomNumeric = (length: number): string =>
+  length <= 1
+    ? String(_randomInteger({ type: "integer", minimum: 0, maximum: 9 }))
+    : String(_randomInteger({ type: "integer", minimum: 1, maximum: 9 })) +
+      __randomDigits(length - 1);