Skip to content
Logo

T.string

A scalar. It can't be used bare, because there's no sensible default length. Call .whereby({ length }) first.

T.string.whereby({ length: 8 });
T.string.whereby({ length: { min: 1, max: 25 } });
T.string.whereby({ length: { min: { value: 0, exclusive: true }, max: 25 } });

length is either a number N, for exactly N, or { min?, max, distribution? }. length.min defaults to 0. The length is drawn uniformly unless you add a distribution (see Distributions). length counts UTF-16 code units, so the result's .length is exactly the drawn length.

T.string.as(produce) replaces how the string is generated with your own function. See T.opaque.

.admits({ length, format, pattern }) changes what adapters accept without changing what is generated: a wider length, and JSON Schema's format and pattern. See .admits(...).

For strings that never repeat, see T.unique.string.

Composition

By default, characters can be any Unicode character except unpaired surrogates, so the result is always valid UTF-16. Use composition to control which characters appear, either by weighting the built-in classes by name or with [weight, source] pairs.

Classes

T.string.whereby({ length: 8, composition: { lowercase: 3, digit: 1 } });
ClassCharactersCode points
lowercasea–zU+0061–U+007A
uppercaseA–ZU+0041–U+005A
digit0–9U+0030–U+0039
symbol!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~U+0021–U+002F, U+003A–U+0040, U+005B–U+0060, U+007B–U+007E
spacethe space character onlyU+0020

Every class is ASCII, and together they cover exactly the printable ASCII characters (U+0020–U+007E). space is only the space character, with no tab, newline, or other whitespace. Write those as a custom source.

For each character, a class is picked by weight, then a character is picked evenly within that class. Weights are relative and describe the average makeup, so any one string can differ from the proportions. A class you leave out never appears, a weight of 0 turns a class off, and it throws if every weight is 0.

Custom sources

T.string.whereby({
  length: 12,
  composition: [
    [3, "abc"],
    [1, { from: 0x30, to: 0x39 }], // 0–9
    [
      1,
      [
        { from: 0x3b1, to: 0x3c1 },
        { from: 0x3c3, to: 0x3c9 },
      ],
    ], // α–ω, skipping final ς
  ],
});

The [weight, source] form takes any character source: a string of characters, a code point range { from, to } (including both ends), or a list of ranges. Weights work the same way: a source is picked by weight, then a code point is picked evenly across all of that source's ranges.

Class names aren't accepted in this form. To mix a class with a custom source, use the class's ranges from classes, exported from @ghostry/fabricator, such as [[3, classes.lowercase], [1, "-_"]]. unicode is exported alongside it, with presets like unicode.bmp and unicode.range(from, to).

A string source counts each character separately, so a repeated character is drawn more often: "aab" gives a twice as often as b.

Exact length

length is always met exactly, even when the composition can't fill it. If the drawn character takes two code units but only one is left, that last unit is filled with a single-unit character from outside the composition, inserted at a random position between characters.