@fgv/ts-random 5.1.0-8

package/src/generator/randomSource.ts

@@ -0,0 +1,224 @@
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+import { captureResult, Result } from '@fgv/ts-utils';
+
+/**
+ * Represents a seed as both a string and a number.
+ * @public
+ */
+export interface ISeedPair {
+  seed: string;
+  state: number;
+}
+
+/**
+ * Result of an internal next() operation.
+ * @public
+ */
+export interface INextResult {
+  value: number;
+  nextState: number;
+}
+
+/**
+ * Function that steps a random number generator state and returns the next value.
+ * @public
+ */
+export type RandomStepFunction = (state: number) => INextResult;
+
+/**
+ * Constructor params for a {@link Generator.SeededRandomSource | SeededRandomSource}.
+ * @public
+ */
+export interface ISeededRandomSourceConstructorParams {
+  state: number;
+  seed: string;
+  counter: number;
+  lineage: ReadonlyArray<string>;
+  step: RandomStepFunction;
+}
+
+/**
+ * Static create parameters for a {@link Generator.SeededRandomSource | SeededRandomSource}.
+ * @public
+ */
+export interface ISeededRandomSourceCreateParams {
+  seed?: number | string;
+  step?: RandomStepFunction;
+}
+
+/**
+ * Seeded random number generator that can be cloned and used for deterministic generation.
+ * @public
+ */
+export class SeededRandomSource {
+  private currentState: number;
+  public readonly seed: string;
+  public readonly lineage: ReadonlyArray<string>;
+  private _counter: number;
+  private _step: RandomStepFunction;
+
+  /**
+   * Gets the current counter value.
+   */
+  public get counter(): number {
+    return this._counter;
+  }
+
+  /**
+   * Creates a new seeded random source.
+   * @param seed - The seed value.
+   */
+  protected constructor(init: ISeededRandomSourceConstructorParams) {
+    this.currentState = init.state;
+    this.seed = init.seed;
+    this._counter = init.counter;
+    this._step = init.step;
+    this.lineage = init.lineage;
+  }
+
+  /**
+   * Creates a new seeded random source from an optional seed.
+   * @param seed - The optional seed value.
+   * @returns A new seeded random source.
+   */
+  public static create(seed?: number | string): Result<SeededRandomSource>;
+
+  /**
+   * Creates a new seeded random source from {@link Generator.ISeededRandomSourceCreateParams | ISeededRandomSourceCreateParams}.
+   * @param init - The initialization parameters.
+   * @returns A new seeded random source.
+   */
+  public static create(init: ISeededRandomSourceCreateParams): Result<SeededRandomSource>;
+
+  public static create(
+    seedOrInit?: number | string | ISeededRandomSourceCreateParams
+  ): Result<SeededRandomSource> {
+    const init = typeof seedOrInit === 'object' ? seedOrInit : { seed: seedOrInit };
+    const step = init?.step ?? SeededRandomSource.mulberryStep;
+    const { seed, state } = SeededRandomSource.hashSeed(init?.seed ?? Date.now());
+    return captureResult(
+      () =>
+        new SeededRandomSource({
+          state,
+          seed,
+          counter: 0,
+          lineage: [],
+          step
+        })
+    );
+  }
+
+  /**
+   * Generates the next random number.
+   * @returns A random number between 0 and 1.
+   */
+  public next(): number {
+    this._counter += 1;
+    const { value, nextState } = this._step(this.currentState);
+    this.currentState = nextState;
+    return value;
+  }
+
+  /**
+   * Creates a clone of this random source.
+   * @returns A new seeded random source with the same state.
+   */
+  public clone(): SeededRandomSource {
+    return new SeededRandomSource({
+      state: this.currentState,
+      seed: this.seed,
+      counter: this._counter,
+      lineage: this.lineage,
+      step: this._step
+    });
+  }
+
+  /**
+   * Creates a child random source with a label.
+   * @param label - The label for the child.
+   * @returns A new seeded random source with a hashed state and label.
+   */
+  public createChild(label: string): SeededRandomSource {
+    const { seed, state } = SeededRandomSource.hashStateAndLabel(this.currentState, label);
+    const lineage = [...this.lineage, `${this._counter}:${label}`];
+    return new SeededRandomSource({ state, seed, counter: 0, lineage, step: this._step });
+  }
+
+  /**
+   * Steps a mulberry32 random number generator state and returns the next value.
+   * @param currentState - The current state of the generator.
+   * @returns The next random number and the next state.
+   */
+  public static mulberryStep(currentState: number): INextResult {
+    const nextState = (currentState + 0x6d2b79f5) >>> 0;
+
+    let t = nextState;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+
+    const value = ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    return { value, nextState };
+  }
+
+  /**
+   * Hashes a seed value.
+   * @param seed - The seed value.
+   * @returns A hashed seed value.
+   */
+  public static hashSeed(seed: number | string): ISeedPair {
+    if (typeof seed === 'number') {
+      return { seed: seed.toString(), state: seed };
+    }
+    const parsedSeed = Number(seed);
+    if (!isNaN(parsedSeed) && isFinite(parsedSeed)) {
+      return { seed, state: parsedSeed };
+    }
+    return { seed, state: SeededRandomSource.hashString(seed) };
+  }
+
+  /**
+   * Hashes a state and label.
+   * @param state - The state value.
+   * @param label - The label value.
+   * @returns A hashed state and label value.
+   */
+  public static hashStateAndLabel(state: number, label: string): ISeedPair {
+    const seed = `${state >>> 0}:${label}`;
+    return { seed, state: SeededRandomSource.hashString(seed) };
+  }
+
+  /**
+   * Hashes a string value.
+   * @param value - The string value.
+   * @returns A hashed string value.
+   */
+  private static hashString(value: string): number {
+    let hash = 0x811c9dc5;
+
+    for (let index = 0; index < value.length; index++) {
+      hash ^= value.charCodeAt(index);
+      hash = Math.imul(hash, 0x01000193);
+    }
+
+    return hash >>> 0;
+  }
+}

package/src/generator-data/charClasses.ts

@@ -0,0 +1,95 @@
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+/**
+ * Lowercase letters
+ * @public
+ */
+export const lowerCase: string = 'abcdefghijklmnopqrstuvwxyz';
+/**
+ * Uppercase letters
+ * @public
+ */
+export const upperCase: string = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+/**
+ * Digits
+ * @public
+ */
+export const digits: string = '0123456789';
+/**
+ * Letters
+ * @public
+ */
+export const letters: string = lowerCase + upperCase;
+/**
+ * Alphanumeric
+ * @public
+ */
+export const alphanumeric: string = letters + digits;
+/**
+ * Symbols
+ * @public
+ */
+export const symbols: string = '!@#$%^&*()_+-=[]{}|;:,.<>?';
+/**
+ * Whitespace
+ * @public
+ */
+export const whitespace: string = ' \t\n\r';
+/**
+ * Printable
+ * @public
+ */
+export const printable: string = letters + digits + symbols + whitespace;
+/**
+ * All
+ * @public
+ */
+export const all: string = printable;
+/**
+ * Hex digits
+ * @public
+ */
+export const hexDigits: string = '0123456789abcdef';
+/**
+ * Hex digits upper
+ * @public
+ */
+export const hexDigitsUpper: string = '0123456789ABCDEF';
+/**
+ * Hex
+ * @public
+ */
+export const hex: string = hexDigits + hexDigitsUpper;
+/**
+ * Base64
+ * @public
+ */
+export const base64: string = letters + digits + '+/';
+/**
+ * Base64 URL
+ * @public
+ */
+export const base64Url: string = letters + digits + '-_';
+/**
+ * Base64 URL no padding
+ * @public
+ */
+export const base64UrlNoPadding: string = base64Url + '=';

package/src/generator-data/index.ts

@@ -0,0 +1,22 @@
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+export * as Chars from './charClasses';
+export * as Words from './words';

package/src/generator-data/words/adjectives.ts

@@ -0,0 +1,247 @@
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+export const Adjectives: ReadonlyArray<string> = [
+  'happy',
+  'sad',
+  'angry',
+  'calm',
+  'excited',
+  'bored',
+  'tired',
+  'hungry',
+  'thirsty',
+  'sleepy',
+  'awake',
+  'alert',
+  'anxious',
+  'brave',
+  'bright',
+  'brilliant',
+  'busy',
+  'careful',
+  'careless',
+  'cautious',
+  'cheerful',
+  'clever',
+  'clumsy',
+  'confident',
+  'confused',
+  'content',
+  'courageous',
+  'cowardly',
+  'creative',
+  'cruel',
+  'curious',
+  'daring',
+  'dark',
+  'delightful',
+  'determined',
+  'diligent',
+  'dizzy',
+  'doubtful',
+  'eager',
+  'elegant',
+  'embarrassed',
+  'energetic',
+  'enthusiastic',
+  'envious',
+  'evil',
+  'faithful',
+  'famous',
+  'fancy',
+  'fantastic',
+  'fearful',
+  'fearless',
+  'fierce',
+  'filthy',
+  'foolish',
+  'fortunate',
+  'fragile',
+  'frantic',
+  'friendly',
+  'frightened',
+  'funny',
+  'generous',
+  'gentle',
+  'gloomy',
+  'glorious',
+  'graceful',
+  'grateful',
+  'greedy',
+  'grumpy',
+  'guilty',
+  'handsome',
+  'harsh',
+  'hasty',
+  'healthy',
+  'helpful',
+  'helpless',
+  'hesitant',
+  'hilarious',
+  'honest',
+  'hopeful',
+  'hopeless',
+  'horrible',
+  'hostile',
+  'humble',
+  'humorous',
+  'ignorant',
+  'imaginative',
+  'impatient',
+  'important',
+  'impossible',
+  'impressive',
+  'incredible',
+  'independent',
+  'innocent',
+  'intelligent',
+  'interesting',
+  'jealous',
+  'joyful',
+  'joyous',
+  'kind',
+  'lazy',
+  'lively',
+  'lonely',
+  'lovely',
+  'loyal',
+  'lucky',
+  'magnificent',
+  'marvelous',
+  'mature',
+  'mean',
+  'melancholy',
+  'merry',
+  'mighty',
+  'miserable',
+  'modest',
+  'mysterious',
+  'nasty',
+  'naughty',
+  'nervous',
+  'nice',
+  'noble',
+  'noisy',
+  'obedient',
+  'obnoxious',
+  'odd',
+  'optimistic',
+  'outrageous',
+  'peaceful',
+  'peculiar',
+  'perfect',
+  'persistent',
+  'pessimistic',
+  'pleasant',
+  'polite',
+  'poor',
+  'popular',
+  'positive',
+  'powerful',
+  'precious',
+  'proud',
+  'puzzled',
+  'quiet',
+  'rapid',
+  'rare',
+  'reckless',
+  'relaxed',
+  'reliable',
+  'relieved',
+  'reluctant',
+  'remarkable',
+  'reserved',
+  'respectful',
+  'responsible',
+  'restless',
+  'rich',
+  'ridiculous',
+  'romantic',
+  'rough',
+  'rude',
+  'ruthless',
+  'satisfied',
+  'scared',
+  'selfish',
+  'sensible',
+  'sensitive',
+  'serious',
+  'sharp',
+  'shy',
+  'silly',
+  'sincere',
+  'skeptical',
+  'skillful',
+  'sleek',
+  'sly',
+  'smart',
+  'sneaky',
+  'sociable',
+  'sorrowful',
+  'splendid',
+  'spontaneous',
+  'stern',
+  'strange',
+  'strong',
+  'stubborn',
+  'stunning',
+  'stupid',
+  'successful',
+  'suspicious',
+  'sweet',
+  'talented',
+  'tense',
+  'terrible',
+  'thankful',
+  'thoughtful',
+  'timid',
+  'tough',
+  'tragic',
+  'tremendous',
+  'troubled',
+  'trustworthy',
+  'ugly',
+  'unique',
+  'unlucky',
+  'unusual',
+  'upset',
+  'useful',
+  'useless',
+  'vain',
+  'victorious',
+  'vigorous',
+  'violent',
+  'vivid',
+  'warm',
+  'weak',
+  'wealthy',
+  'weary',
+  'wicked',
+  'wild',
+  'wise',
+  'witty',
+  'wonderful',
+  'worried',
+  'worthy',
+  'wretched',
+  'youthful',
+  'zealous'
+];

package/src/generator-data/words/animals.ts

@@ -0,0 +1,75 @@
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+export const Animals: ReadonlyArray<string> = [
+  'cat',
+  'dog',
+  'bird',
+  'fish',
+  'rabbit',
+  'hamster',
+  'panda',
+  'cow',
+  'horse',
+  'sheep',
+  'goat',
+  'pig',
+  'chicken',
+  'duck',
+  'turkey',
+  'goose',
+  'rabbit',
+  'fox',
+  'wolf',
+  'bear',
+  'capybara',
+  'panda',
+  'koala',
+  'red panda',
+  'pangolin',
+  'anteater',
+  'armadillo',
+  'porcupine',
+  'hippopotamus',
+  'rhinoceros',
+  'elephant',
+  'giraffe',
+  'zebra',
+  'monkey',
+  'gorilla',
+  'chimpanzee',
+  'orangutan',
+  'turtle',
+  'snake',
+  'lizard',
+  'frog',
+  'toad',
+  'salamander',
+  'newt',
+  'axolotl',
+  'gecko',
+  'chameleon',
+  'iguana',
+  'snake',
+  'python',
+  'cobra',
+  'viper',
+  'rattlesnake'
+];