@fgv/ts-random 5.1.0-10

package/docs/variables/Animals.md

@@ -0,0 +1,7 @@
+[Home](../README.md) > Animals
+
+# Variable: Animals
+
+## Type
+
+`ReadonlyArray<string>`

package/docs/variables/Cities.md

@@ -0,0 +1,7 @@
+[Home](../README.md) > Cities
+
+# Variable: Cities
+
+## Type
+
+`ReadonlyArray<string>`

package/docs/variables/Colors.md

@@ -0,0 +1,7 @@
+[Home](../README.md) > Colors
+
+# Variable: Colors
+
+## Type
+
+`ReadonlyArray<string>`

package/docs/variables/Countries.md

@@ -0,0 +1,7 @@
+[Home](../README.md) > Countries
+
+# Variable: Countries
+
+## Type
+
+`ReadonlyArray<string>`

package/docs/variables/Domains.md

@@ -0,0 +1,7 @@
+[Home](../README.md) > Domains
+
+# Variable: Domains
+
+## Type
+
+`ReadonlyArray<string>`

package/docs/variables/FamilyNames.md

@@ -0,0 +1,9 @@
+[Home](../README.md) > FamilyNames
+
+# Variable: FamilyNames
+
+Family names / surnames
+
+## Type
+
+`ReadonlyArray<string>`

package/docs/variables/FirstNames.md

@@ -0,0 +1,9 @@
+[Home](../README.md) > FirstNames
+
+# Variable: FirstNames
+
+All first names
+
+## Type
+
+`ReadonlyArray<string>`

package/docs/variables/FirstNamesFemale.md

@@ -0,0 +1,9 @@
+[Home](../README.md) > FirstNamesFemale
+
+# Variable: FirstNamesFemale
+
+Female first names
+
+## Type
+
+`ReadonlyArray<string>`

package/docs/variables/FirstNamesMale.md

@@ -0,0 +1,9 @@
+[Home](../README.md) > FirstNamesMale
+
+# Variable: FirstNamesMale
+
+Male first names
+
+## Type
+
+`ReadonlyArray<string>`

package/docs/variables/Gerunds.md

@@ -0,0 +1,7 @@
+[Home](../README.md) > Gerunds
+
+# Variable: Gerunds
+
+## Type
+
+`ReadonlyArray<string>`

package/docs/variables/all.md

@@ -0,0 +1,9 @@
+[Home](../README.md) > all
+
+# Variable: all
+
+All
+
+## Type
+
+`string`

package/docs/variables/alphanumeric.md

@@ -0,0 +1,9 @@
+[Home](../README.md) > alphanumeric
+
+# Variable: alphanumeric
+
+Alphanumeric
+
+## Type
+
+`string`

package/docs/variables/base64.md

@@ -0,0 +1,9 @@
+[Home](../README.md) > base64
+
+# Variable: base64
+
+Base64
+
+## Type
+
+`string`

package/docs/variables/base64Url.md

@@ -0,0 +1,9 @@
+[Home](../README.md) > base64Url
+
+# Variable: base64Url
+
+Base64 URL
+
+## Type
+
+`string`

package/docs/variables/base64UrlNoPadding.md

@@ -0,0 +1,9 @@
+[Home](../README.md) > base64UrlNoPadding
+
+# Variable: base64UrlNoPadding
+
+Base64 URL no padding
+
+## Type
+
+`string`

package/docs/variables/digits.md

@@ -0,0 +1,9 @@
+[Home](../README.md) > digits
+
+# Variable: digits
+
+Digits
+
+## Type
+
+`string`

package/docs/variables/hex.md

@@ -0,0 +1,9 @@
+[Home](../README.md) > hex
+
+# Variable: hex
+
+Hex
+
+## Type
+
+`string`

package/docs/variables/hexDigits.md

@@ -0,0 +1,9 @@
+[Home](../README.md) > hexDigits
+
+# Variable: hexDigits
+
+Hex digits
+
+## Type
+
+`string`

package/docs/variables/hexDigitsUpper.md

@@ -0,0 +1,9 @@
+[Home](../README.md) > hexDigitsUpper
+
+# Variable: hexDigitsUpper
+
+Hex digits upper
+
+## Type
+
+`string`

package/docs/variables/jobs.md

@@ -0,0 +1,7 @@
+[Home](../README.md) > jobs
+
+# Variable: jobs
+
+## Type
+
+`string[]`

package/docs/variables/letters.md

@@ -0,0 +1,9 @@
+[Home](../README.md) > letters
+
+# Variable: letters
+
+Letters
+
+## Type
+
+`string`

package/docs/variables/lowerCase.md

@@ -0,0 +1,9 @@
+[Home](../README.md) > lowerCase
+
+# Variable: lowerCase
+
+Lowercase letters
+
+## Type
+
+`string`

package/docs/variables/printable.md

@@ -0,0 +1,9 @@
+[Home](../README.md) > printable
+
+# Variable: printable
+
+Printable
+
+## Type
+
+`string`

package/docs/variables/symbols.md

@@ -0,0 +1,9 @@
+[Home](../README.md) > symbols
+
+# Variable: symbols
+
+Symbols
+
+## Type
+
+`string`

package/docs/variables/upperCase.md

@@ -0,0 +1,9 @@
+[Home](../README.md) > upperCase
+
+# Variable: upperCase
+
+Uppercase letters
+
+## Type
+
+`string`

package/docs/variables/whitespace.md

@@ -0,0 +1,9 @@
+[Home](../README.md) > whitespace
+
+# Variable: whitespace
+
+Whitespace
+
+## Type
+
+`string`

package/lib/generator/generators.d.ts

@@ -0,0 +1,142 @@
+import { Result } from '@fgv/ts-utils';
+import { RandomStepFunction, SeededRandomSource } from './randomSource';
+/**
+ * Parameters for creating a generator.
+ * @public
+ */
+export interface IPseudoRandomGeneratorCreateParams {
+    seed?: number | string;
+    step?: RandomStepFunction;
+    global?: boolean;
+}
+/**
+ * Parameters for generating a sequence of values
+ * from each dictionary in a supplied set, in turn.
+ * @public
+ */
+export interface ISequentialPickParams<T> {
+    how: 'sequence';
+    count?: number;
+    candidates: ReadonlyArray<ReadonlyArray<T>>;
+}
+/**
+ * Parameters for generating a sequence of values
+ * by randomly selecting from dictionaries in a supplied set.
+ * @public
+ */
+export interface IRandomSequencePickParams<T> {
+    how: 'random';
+    count: number;
+    candidates: ReadonlyArray<ReadonlyArray<T>>;
+}
+/**
+ * Type representing parameters for generating a sequence of values.
+ * @public
+ */
+export type SequencePickParams<T> = ISequentialPickParams<T> | IRandomSequencePickParams<T>;
+/**
+ * A pseudo-random number generator that can be used to generate random values
+ * of various shapes.
+ * @public
+ */
+export declare class PseudoRandomGenerator {
+    private static _globalRng;
+    /**
+     * The underlying random number generator.
+     */
+    readonly rng: SeededRandomSource;
+    private constructor();
+    /**
+     * 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?: IPseudoRandomGeneratorCreateParams): Result<PseudoRandomGenerator>;
+    /**
+     * Creates a clone of this generator.
+     * @returns A new generator with the same state.
+     */
+    clone(): PseudoRandomGenerator;
+    /**
+     * 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: string): PseudoRandomGenerator;
+    /**
+     * Generates a random float between 0 and 1.
+     * @returns A random float between 0 and 1.
+     */
+    nextFloat(): number;
+    /**
+     * 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?: number): number;
+    /**
+     * 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: number | undefined, max: number | undefined): number;
+    /**
+     * Generates a random boolean value.
+     * @param trueProbability - The probability of returning true (default is 0.5).
+     * @returns A random boolean value.
+     */
+    nextBoolean(trueProbability?: number): boolean;
+    /**
+     * 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: number, chars?: string): string;
+    /**
+     * 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<T>(items?: ReadonlyArray<T>): T | undefined;
+    /**
+     * 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<T>(params: ISequentialPickParams<T>): ReadonlyArray<T>;
+    /**
+     * 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<T>(params: IRandomSequencePickParams<T>): ReadonlyArray<T>;
+    /**
+     * 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<T>(params: SequencePickParams<T>): ReadonlyArray<T>;
+    /**
+     * Sets this generator as the global random number generator.
+     * @returns A result containing this generator or an error.
+     */
+    static setGlobalRng(rng?: PseudoRandomGenerator): PseudoRandomGenerator | undefined;
+    /**
+     * Gets the global random number generator.
+     * @returns The global random number generator or undefined if not set.
+     */
+    static getGlobalRng(): PseudoRandomGenerator | undefined;
+    /**
+     * 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?: PseudoRandomGenerator): Result<PseudoRandomGenerator>;
+}
+//# sourceMappingURL=generators.d.ts.map

package/lib/generator/generators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generators.d.ts","sourceRoot":"","sources":["../../src/generator/generators.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAiB,MAAM,EAAW,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAExE;;;GAGG;AACH,MAAM,WAAW,kCAAkC;IACjD,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC,GAAG,EAAE,UAAU,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;CAC7C;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB,CAAC,CAAC;IAC1C,GAAG,EAAE,QAAQ,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;CAC7C;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI,qBAAqB,CAAC,CAAC,CAAC,GAAG,yBAAyB,CAAC,CAAC,CAAC,CAAC;AAE5F;;;;GAIG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAoC;IAE7D;;OAEG;IACH,SAAgB,GAAG,EAAE,kBAAkB,CAAC;IAExC,OAAO;IAIP;;;;OAIG;WACW,MAAM,CAAC,MAAM,GAAE,kCAAuC,GAAG,MAAM,CAAC,qBAAqB,CAAC;IAWpG;;;OAGG;IACI,KAAK,IAAI,qBAAqB;IAIrC;;;;OAIG;IACI,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,qBAAqB;IAIxD;;;OAGG;IACI,SAAS,IAAI,MAAM;IAI1B;;;;OAIG;IACI,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM;IAUvC;;;;;;OAMG;IACI,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM;IAS5E;;;;OAIG;IACI,WAAW,CAAC,eAAe,GAAE,MAAY,GAAG,OAAO;IAI1D;;;;;OAKG;IACI,UAAU,CACf,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,MAAyE,GAC/E,MAAM;IAQT;;;;OAIG;IACI,QAAQ,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS;IAO3D;;;;;OAKG;IACI,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC;IAe5E;;;;;OAKG;IACI,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,yBAAyB,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC;IAc5E;;;;OAIG;IACI,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC;IAQvE;;;OAGG;WACW,YAAY,CAAC,GAAG,CAAC,EAAE,qBAAqB,GAAG,qBAAqB,GAAG,SAAS;IAK1F;;;OAGG;WACW,YAAY,IAAI,qBAAqB,GAAG,SAAS;IAI/D;;;;;OAKG;WACW,SAAS,CAAC,GAAG,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAAC,qBAAqB,CAAC;CAOpF"}

package/lib/generator/generators.js

@@ -0,0 +1,211 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PseudoRandomGenerator = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const randomSource_1 = require("./randomSource");
+/**
+ * A pseudo-random number generator that can be used to generate random values
+ * of various shapes.
+ * @public
+ */
+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 randomSource_1.SeededRandomSource.create(params)
+            .onSuccess((rng) => (0, ts_utils_1.captureResult)(() => new PseudoRandomGenerator(rng)))
+            .onSuccess((generator) => {
+            if ((params === null || params === void 0 ? void 0 : params.global) === true) {
+                PseudoRandomGenerator.setGlobalRng(generator);
+            }
+            return ts_utils_1.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 ts_utils_1.Success.with(rng);
+        }
+        return PseudoRandomGenerator.create();
+    }
+}
+exports.PseudoRandomGenerator = PseudoRandomGenerator;
+//# sourceMappingURL=generators.js.map

package/lib/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/lib/generator/index.d.ts

@@ -0,0 +1,3 @@
+export * from './randomSource';
+export * from './generators';
+//# sourceMappingURL=index.d.ts.map

package/lib/generator/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/generator/index.ts"],"names":[],"mappings":"AAoBA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC"}