@fgv/ts-random 5.1.0-8 → 5.1.0-9

package/dist/generator/generators.js

@@ -0,0 +1,207 @@
+// 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, Success } from '@fgv/ts-utils';
+import { SeededRandomSource } from './randomSource';
+/**
+ * A pseudo-random number generator that can be used to generate random values
+ * of various shapes.
+ * @public
+ */
+export class PseudoRandomGenerator {
+    constructor(rng) {
+        this.rng = rng;
+    }
+    /**
+     * Creates a new pseudo-random number generator.
+     * @param params - The parameters for creating the generator.
+     * @returns A result containing the new generator or an error.
+     */
+    static create(params = {}) {
+        return SeededRandomSource.create(params)
+            .onSuccess((rng) => captureResult(() => new PseudoRandomGenerator(rng)))
+            .onSuccess((generator) => {
+            if ((params === null || params === void 0 ? void 0 : params.global) === true) {
+                PseudoRandomGenerator.setGlobalRng(generator);
+            }
+            return Success.with(generator);
+        });
+    }
+    /**
+     * Creates a clone of this generator.
+     * @returns A new generator with the same state.
+     */
+    clone() {
+        return new PseudoRandomGenerator(this.rng.clone());
+    }
+    /**
+     * Creates a child generator with the given label.
+     * @param label - The label for the child generator.
+     * @returns A new generator with the given label.
+     */
+    createChild(label) {
+        return new PseudoRandomGenerator(this.rng.createChild(label));
+    }
+    /**
+     * Generates a random float between 0 and 1.
+     * @returns A random float between 0 and 1.
+     */
+    nextFloat() {
+        return this.rng.next();
+    }
+    /**
+     * Generates a random integer between 0 and the specified extent (positive or negative).
+     * @param extent - The maximum (or minimum) value (exclusive).
+     * @returns A random integer between 0 and the specified extent.
+     */
+    nextInt(extent) {
+        if (extent !== undefined && Number.isFinite(extent)) {
+            if (extent < 0) {
+                return Math.ceil(this.rng.next() * extent);
+            }
+            return Math.floor(this.rng.next() * extent);
+        }
+        return Math.floor(this.rng.next() * Number.MAX_SAFE_INTEGER);
+    }
+    /**
+     * Generates a random integer between the specified minimum and maximum values.
+     * @param min - The minimum value (inclusive).
+     * @param max - The maximum value (inclusive).
+     * @returns A random integer between the specified minimum and maximum values.
+     * @remarks If min is greater than max, the values are swapped.
+     */
+    nextInRange(min, max) {
+        min = min !== null && min !== void 0 ? min : 0;
+        max = max !== null && max !== void 0 ? max : Number.MAX_SAFE_INTEGER;
+        if (min > max) {
+            return Math.ceil(this.rng.next() * (min - max - 1)) + max;
+        }
+        return Math.floor(this.rng.next() * (max - min + 1)) + min;
+    }
+    /**
+     * Generates a random boolean value.
+     * @param trueProbability - The probability of returning true (default is 0.5).
+     * @returns A random boolean value.
+     */
+    nextBoolean(trueProbability = 0.5) {
+        return this.rng.next() < trueProbability;
+    }
+    /**
+     * Generates a random string of the specified length using the given characters.
+     * @param length - The length of the string to generate.
+     * @param chars - The characters to use for the string (default is alphanumeric).
+     * @returns A random string of the specified length.
+     */
+    nextString(length, chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789') {
+        let result = '';
+        for (let i = 0; i < length; i++) {
+            result += chars[this.nextInt(chars.length)];
+        }
+        return result;
+    }
+    /**
+     * Generates a random item from the given array.
+     * @param items - The array to select from.
+     * @returns A random item from the array or undefined if the array is empty.
+     */
+    pickNext(items) {
+        if (items === undefined || items.length === 0) {
+            return undefined;
+        }
+        return items[this.nextInt(items.length)];
+    }
+    /**
+     * Generates a sequence of values by randomly selecting from the given candidate
+     * dictionaries in order.
+     * @param params - The parameters for generating the sequence.
+     * @returns A sequence of values.
+     */
+    pickSequential(params) {
+        var _a;
+        const count = (_a = params.count) !== null && _a !== void 0 ? _a : params.candidates.length;
+        const items = [];
+        for (let i = 0; i < count; i++) {
+            const dIndex = i % params.candidates.length;
+            const item = this.pickNext(params.candidates[dIndex]);
+            if (item !== undefined) {
+                items.push(item);
+            }
+        }
+        return items;
+    }
+    /**
+     * Generates a sequence of values by randomly selecting from the supplied
+     * dictionaries in random order.
+     * @param params - The parameters for generating the sequence.
+     * @returns A sequence of values.
+     */
+    pickRandom(params) {
+        const items = [];
+        for (let i = 0; i < params.count; i++) {
+            const dIndex = this.nextInt(params.candidates.length);
+            const item = this.pickNext(params.candidates[dIndex]);
+            if (item !== undefined) {
+                items.push(item);
+            }
+        }
+        return items;
+    }
+    /**
+     * Generates a sequence of values by randomly selecting from the given candidates.
+     * @param params - The parameters for generating the sequence.
+     * @returns A sequence of values.
+     */
+    pickSequence(params) {
+        if (params.how === 'sequence') {
+            return this.pickSequential(params);
+        }
+        else {
+            return this.pickRandom(params);
+        }
+    }
+    /**
+     * Sets this generator as the global random number generator.
+     * @returns A result containing this generator or an error.
+     */
+    static setGlobalRng(rng) {
+        PseudoRandomGenerator._globalRng = rng;
+        return rng;
+    }
+    /**
+     * Gets the global random number generator.
+     * @returns The global random number generator or undefined if not set.
+     */
+    static getGlobalRng() {
+        return PseudoRandomGenerator._globalRng;
+    }
+    /**
+     * Ensures a random number generator is available, using the global generator if available
+     * or creating a new one if not.
+     * @param rng - The random number generator to use, or undefined to use the global one.
+     * @returns A random number generator.
+     */
+    static ensureRng(rng) {
+        rng = rng !== null && rng !== void 0 ? rng : PseudoRandomGenerator.getGlobalRng();
+        if (rng) {
+            return Success.with(rng);
+        }
+        return PseudoRandomGenerator.create();
+    }
+}
+//# sourceMappingURL=generators.js.map

package/dist/generator/generators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generators.js","sourceRoot":"","sources":["../../src/generator/generators.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) 2026 Erik Fortune\n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in all\n// copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n// SOFTWARE.\n\nimport { captureResult, Result, Success } from '@fgv/ts-utils';\nimport { RandomStepFunction, SeededRandomSource } from './randomSource';\n\n/**\n * Parameters for creating a generator.\n * @public\n */\nexport interface IPseudoRandomGeneratorCreateParams {\n  seed?: number | string;\n  step?: RandomStepFunction;\n  global?: boolean;\n}\n\n/**\n * Parameters for generating a sequence of values\n * from each dictionary in a supplied set, in turn.\n * @public\n */\nexport interface ISequentialPickParams<T> {\n  how: 'sequence';\n  count?: number;\n  candidates: ReadonlyArray<ReadonlyArray<T>>;\n}\n\n/**\n * Parameters for generating a sequence of values\n * by randomly selecting from dictionaries in a supplied set.\n * @public\n */\nexport interface IRandomSequencePickParams<T> {\n  how: 'random';\n  count: number;\n  candidates: ReadonlyArray<ReadonlyArray<T>>;\n}\n\n/**\n * Type representing parameters for generating a sequence of values.\n * @public\n */\nexport type SequencePickParams<T> = ISequentialPickParams<T> | IRandomSequencePickParams<T>;\n\n/**\n * A pseudo-random number generator that can be used to generate random values\n * of various shapes.\n * @public\n */\nexport class PseudoRandomGenerator {\n  private static _globalRng: PseudoRandomGenerator | undefined;\n\n  /**\n   * The underlying random number generator.\n   */\n  public readonly rng: SeededRandomSource;\n\n  private constructor(rng: SeededRandomSource) {\n    this.rng = rng;\n  }\n\n  /**\n   * Creates a new pseudo-random number generator.\n   * @param params - The parameters for creating the generator.\n   * @returns A result containing the new generator or an error.\n   */\n  public static create(params: IPseudoRandomGeneratorCreateParams = {}): Result<PseudoRandomGenerator> {\n    return SeededRandomSource.create(params)\n      .onSuccess((rng) => captureResult(() => new PseudoRandomGenerator(rng)))\n      .onSuccess((generator) => {\n        if (params?.global === true) {\n          PseudoRandomGenerator.setGlobalRng(generator);\n        }\n        return Success.with(generator);\n      });\n  }\n\n  /**\n   * Creates a clone of this generator.\n   * @returns A new generator with the same state.\n   */\n  public clone(): PseudoRandomGenerator {\n    return new PseudoRandomGenerator(this.rng.clone());\n  }\n\n  /**\n   * Creates a child generator with the given label.\n   * @param label - The label for the child generator.\n   * @returns A new generator with the given label.\n   */\n  public createChild(label: string): PseudoRandomGenerator {\n    return new PseudoRandomGenerator(this.rng.createChild(label));\n  }\n\n  /**\n   * Generates a random float between 0 and 1.\n   * @returns A random float between 0 and 1.\n   */\n  public nextFloat(): number {\n    return this.rng.next();\n  }\n\n  /**\n   * Generates a random integer between 0 and the specified extent (positive or negative).\n   * @param extent - The maximum (or minimum) value (exclusive).\n   * @returns A random integer between 0 and the specified extent.\n   */\n  public nextInt(extent?: number): number {\n    if (extent !== undefined && Number.isFinite(extent)) {\n      if (extent < 0) {\n        return Math.ceil(this.rng.next() * extent);\n      }\n      return Math.floor(this.rng.next() * extent);\n    }\n    return Math.floor(this.rng.next() * Number.MAX_SAFE_INTEGER);\n  }\n\n  /**\n   * Generates a random integer between the specified minimum and maximum values.\n   * @param min - The minimum value (inclusive).\n   * @param max - The maximum value (inclusive).\n   * @returns A random integer between the specified minimum and maximum values.\n   * @remarks If min is greater than max, the values are swapped.\n   */\n  public nextInRange(min: number | undefined, max: number | undefined): number {\n    min = min ?? 0;\n    max = max ?? Number.MAX_SAFE_INTEGER;\n    if (min > max) {\n      return Math.ceil(this.rng.next() * (min - max - 1)) + max;\n    }\n    return Math.floor(this.rng.next() * (max - min + 1)) + min;\n  }\n\n  /**\n   * Generates a random boolean value.\n   * @param trueProbability - The probability of returning true (default is 0.5).\n   * @returns A random boolean value.\n   */\n  public nextBoolean(trueProbability: number = 0.5): boolean {\n    return this.rng.next() < trueProbability;\n  }\n\n  /**\n   * Generates a random string of the specified length using the given characters.\n   * @param length - The length of the string to generate.\n   * @param chars - The characters to use for the string (default is alphanumeric).\n   * @returns A random string of the specified length.\n   */\n  public nextString(\n    length: number,\n    chars: string = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'\n  ): string {\n    let result = '';\n    for (let i = 0; i < length; i++) {\n      result += chars[this.nextInt(chars.length)];\n    }\n    return result;\n  }\n\n  /**\n   * Generates a random item from the given array.\n   * @param items - The array to select from.\n   * @returns A random item from the array or undefined if the array is empty.\n   */\n  public pickNext<T>(items?: ReadonlyArray<T>): T | undefined {\n    if (items === undefined || items.length === 0) {\n      return undefined;\n    }\n    return items[this.nextInt(items.length)];\n  }\n\n  /**\n   * Generates a sequence of values by randomly selecting from the given candidate\n   * dictionaries in order.\n   * @param params - The parameters for generating the sequence.\n   * @returns A sequence of values.\n   */\n  public pickSequential<T>(params: ISequentialPickParams<T>): ReadonlyArray<T> {\n    const count = params.count ?? params.candidates.length;\n    const items: T[] = [];\n\n    for (let i = 0; i < count; i++) {\n      const dIndex = i % params.candidates.length;\n      const item = this.pickNext(params.candidates[dIndex]);\n      if (item !== undefined) {\n        items.push(item);\n      }\n    }\n\n    return items;\n  }\n\n  /**\n   * Generates a sequence of values by randomly selecting from the supplied\n   * dictionaries in random order.\n   * @param params - The parameters for generating the sequence.\n   * @returns A sequence of values.\n   */\n  public pickRandom<T>(params: IRandomSequencePickParams<T>): ReadonlyArray<T> {\n    const items: T[] = [];\n\n    for (let i = 0; i < params.count; i++) {\n      const dIndex = this.nextInt(params.candidates.length);\n      const item = this.pickNext(params.candidates[dIndex]);\n      if (item !== undefined) {\n        items.push(item);\n      }\n    }\n\n    return items;\n  }\n\n  /**\n   * Generates a sequence of values by randomly selecting from the given candidates.\n   * @param params - The parameters for generating the sequence.\n   * @returns A sequence of values.\n   */\n  public pickSequence<T>(params: SequencePickParams<T>): ReadonlyArray<T> {\n    if (params.how === 'sequence') {\n      return this.pickSequential(params);\n    } else {\n      return this.pickRandom(params);\n    }\n  }\n\n  /**\n   * Sets this generator as the global random number generator.\n   * @returns A result containing this generator or an error.\n   */\n  public static setGlobalRng(rng?: PseudoRandomGenerator): PseudoRandomGenerator | undefined {\n    PseudoRandomGenerator._globalRng = rng;\n    return rng;\n  }\n\n  /**\n   * Gets the global random number generator.\n   * @returns The global random number generator or undefined if not set.\n   */\n  public static getGlobalRng(): PseudoRandomGenerator | undefined {\n    return PseudoRandomGenerator._globalRng;\n  }\n\n  /**\n   * Ensures a random number generator is available, using the global generator if available\n   * or creating a new one if not.\n   * @param rng - The random number generator to use, or undefined to use the global one.\n   * @returns A random number generator.\n   */\n  public static ensureRng(rng?: PseudoRandomGenerator): Result<PseudoRandomGenerator> {\n    rng = rng ?? PseudoRandomGenerator.getGlobalRng();\n    if (rng) {\n      return Success.with(rng);\n    }\n    return PseudoRandomGenerator.create();\n  }\n}\n"]}

package/dist/generator/index.js

@@ -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 * from './randomSource';
+export * from './generators';
+//# sourceMappingURL=index.js.map

package/dist/generator/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/generator/index.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,wEAAwE;AACxE,2DAA2D;AAC3D,EAAE;AACF,iFAAiF;AACjF,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,yEAAyE;AACzE,gFAAgF;AAChF,gFAAgF;AAChF,YAAY;AAEZ,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC","sourcesContent":["// Copyright (c) 2026 Erik Fortune\n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in all\n// copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n// SOFTWARE.\n\nexport * from './randomSource';\nexport * from './generators';\n"]}

package/dist/generator/randomSource.js

@@ -0,0 +1,141 @@
+// 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 } from '@fgv/ts-utils';
+/**
+ * Seeded random number generator that can be cloned and used for deterministic generation.
+ * @public
+ */
+export class SeededRandomSource {
+    /**
+     * Gets the current counter value.
+     */
+    get counter() {
+        return this._counter;
+    }
+    /**
+     * Creates a new seeded random source.
+     * @param seed - The seed value.
+     */
+    constructor(init) {
+        this.currentState = init.state;
+        this.seed = init.seed;
+        this._counter = init.counter;
+        this._step = init.step;
+        this.lineage = init.lineage;
+    }
+    static create(seedOrInit) {
+        var _a, _b;
+        const init = typeof seedOrInit === 'object' ? seedOrInit : { seed: seedOrInit };
+        const step = (_a = init === null || init === void 0 ? void 0 : init.step) !== null && _a !== void 0 ? _a : SeededRandomSource.mulberryStep;
+        const { seed, state } = SeededRandomSource.hashSeed((_b = init === null || init === void 0 ? void 0 : init.seed) !== null && _b !== void 0 ? _b : 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.
+     */
+    next() {
+        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.
+     */
+    clone() {
+        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.
+     */
+    createChild(label) {
+        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.
+     */
+    static mulberryStep(currentState) {
+        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.
+     */
+    static hashSeed(seed) {
+        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.
+     */
+    static hashStateAndLabel(state, label) {
+        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.
+     */
+    static hashString(value) {
+        let hash = 0x811c9dc5;
+        for (let index = 0; index < value.length; index++) {
+            hash ^= value.charCodeAt(index);
+            hash = Math.imul(hash, 0x01000193);
+        }
+        return hash >>> 0;
+    }
+}
+//# sourceMappingURL=randomSource.js.map

package/dist/generator/randomSource.js.map

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

package/dist/generator-data/charClasses.js

@@ -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 = 'abcdefghijklmnopqrstuvwxyz';
+/**
+ * Uppercase letters
+ * @public
+ */
+export const upperCase = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+/**
+ * Digits
+ * @public
+ */
+export const digits = '0123456789';
+/**
+ * Letters
+ * @public
+ */
+export const letters = lowerCase + upperCase;
+/**
+ * Alphanumeric
+ * @public
+ */
+export const alphanumeric = letters + digits;
+/**
+ * Symbols
+ * @public
+ */
+export const symbols = '!@#$%^&*()_+-=[]{}|;:,.<>?';
+/**
+ * Whitespace
+ * @public
+ */
+export const whitespace = ' \t\n\r';
+/**
+ * Printable
+ * @public
+ */
+export const printable = letters + digits + symbols + whitespace;
+/**
+ * All
+ * @public
+ */
+export const all = printable;
+/**
+ * Hex digits
+ * @public
+ */
+export const hexDigits = '0123456789abcdef';
+/**
+ * Hex digits upper
+ * @public
+ */
+export const hexDigitsUpper = '0123456789ABCDEF';
+/**
+ * Hex
+ * @public
+ */
+export const hex = hexDigits + hexDigitsUpper;
+/**
+ * Base64
+ * @public
+ */
+export const base64 = letters + digits + '+/';
+/**
+ * Base64 URL
+ * @public
+ */
+export const base64Url = letters + digits + '-_';
+/**
+ * Base64 URL no padding
+ * @public
+ */
+export const base64UrlNoPadding = base64Url + '=';
+//# sourceMappingURL=charClasses.js.map

package/dist/generator-data/charClasses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"charClasses.js","sourceRoot":"","sources":["../../src/generator-data/charClasses.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,wEAAwE;AACxE,2DAA2D;AAC3D,EAAE;AACF,iFAAiF;AACjF,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,yEAAyE;AACzE,gFAAgF;AAChF,gFAAgF;AAChF,YAAY;AAEZ;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAW,4BAA4B,CAAC;AAC9D;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAW,4BAA4B,CAAC;AAC9D;;;GAGG;AACH,MAAM,CAAC,MAAM,MAAM,GAAW,YAAY,CAAC;AAC3C;;;GAGG;AACH,MAAM,CAAC,MAAM,OAAO,GAAW,SAAS,GAAG,SAAS,CAAC;AACrD;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAW,OAAO,GAAG,MAAM,CAAC;AACrD;;;GAGG;AACH,MAAM,CAAC,MAAM,OAAO,GAAW,4BAA4B,CAAC;AAC5D;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAW,SAAS,CAAC;AAC5C;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAW,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;AACzE;;;GAGG;AACH,MAAM,CAAC,MAAM,GAAG,GAAW,SAAS,CAAC;AACrC;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAW,kBAAkB,CAAC;AACpD;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAW,kBAAkB,CAAC;AACzD;;;GAGG;AACH,MAAM,CAAC,MAAM,GAAG,GAAW,SAAS,GAAG,cAAc,CAAC;AACtD;;;GAGG;AACH,MAAM,CAAC,MAAM,MAAM,GAAW,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;AACtD;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAW,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;AACzD;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAW,SAAS,GAAG,GAAG,CAAC","sourcesContent":["// Copyright (c) 2026 Erik Fortune\n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in all\n// copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n// SOFTWARE.\n\n/**\n * Lowercase letters\n * @public\n */\nexport const lowerCase: string = 'abcdefghijklmnopqrstuvwxyz';\n/**\n * Uppercase letters\n * @public\n */\nexport const upperCase: string = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';\n/**\n * Digits\n * @public\n */\nexport const digits: string = '0123456789';\n/**\n * Letters\n * @public\n */\nexport const letters: string = lowerCase + upperCase;\n/**\n * Alphanumeric\n * @public\n */\nexport const alphanumeric: string = letters + digits;\n/**\n * Symbols\n * @public\n */\nexport const symbols: string = '!@#$%^&*()_+-=[]{}|;:,.<>?';\n/**\n * Whitespace\n * @public\n */\nexport const whitespace: string = ' \\t\\n\\r';\n/**\n * Printable\n * @public\n */\nexport const printable: string = letters + digits + symbols + whitespace;\n/**\n * All\n * @public\n */\nexport const all: string = printable;\n/**\n * Hex digits\n * @public\n */\nexport const hexDigits: string = '0123456789abcdef';\n/**\n * Hex digits upper\n * @public\n */\nexport const hexDigitsUpper: string = '0123456789ABCDEF';\n/**\n * Hex\n * @public\n */\nexport const hex: string = hexDigits + hexDigitsUpper;\n/**\n * Base64\n * @public\n */\nexport const base64: string = letters + digits + '+/';\n/**\n * Base64 URL\n * @public\n */\nexport const base64Url: string = letters + digits + '-_';\n/**\n * Base64 URL no padding\n * @public\n */\nexport const base64UrlNoPadding: string = base64Url + '=';\n"]}

package/dist/generator-data/index.js

@@ -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';
+//# sourceMappingURL=index.js.map

package/dist/generator-data/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/generator-data/index.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,wEAAwE;AACxE,2DAA2D;AAC3D,EAAE;AACF,iFAAiF;AACjF,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,yEAAyE;AACzE,gFAAgF;AAChF,gFAAgF;AAChF,YAAY;AAEZ,OAAO,KAAK,KAAK,MAAM,eAAe,CAAC;AACvC,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC","sourcesContent":["// Copyright (c) 2026 Erik Fortune\n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in all\n// copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n// SOFTWARE.\n\nexport * as Chars from './charClasses';\nexport * as Words from './words';\n"]}