@augment-vir/common
Version:
A collection of augments, helpers types, functions, and classes for any JavaScript environment.
102 lines (101 loc) • 4.08 kB
TypeScript
/**
* A class that produces deterministic, pseudo random numbers based on a given seed. This uses the
* Alea v0.9 algorithm from Johannes Baagøe.
*
* @category Random : Util
* @category Package : @augment-vir/common
* @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
*/
export type SeededRandomState = [
number,
number,
number,
number
];
/**
* A class that produces deterministic, pseudo random numbers based on a given seed. This uses the
* Alea v0.9 algorithm from Johannes Baagøe.
*
* @category Random
* @category Package : @augment-vir/common
* @example
*
* ```ts
* import {SeededRandom} from '@augment-vir/common';
*
* const random = SeededRandom.fromSeed('hello there');
* console.info(random.next()); // this value will always be the same
*
* const random2 = SeededRandom.fromState(random.exportState());
* console.info(random.next(), random2.next()); // both of these values will always be identical
*
* const random3 = random2.clone();
* console.info(random.next(), random2.next(), random3.next()); // all of these values will always be identical
* ```
*
* @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
*/
export declare class SeededRandom {
protected readonly alea: AleaRandom;
/** Generate a new {@link SeededRandom} instance from a seed. */
static fromSeed(seed: string | number): SeededRandom;
/** Generate a new {@link SeededRandom} instance from a specific state. */
static fromState(state: SeededRandomState): SeededRandom;
/**
* Exports the current state of the seeded random number generator so it can be cloned to
* another instance. Use {@link SeededRandom.fromState} to consume this state.
*/
exportState(): SeededRandomState;
/**
* This constructor is private. Use {@link SeededRandom.fromSeed} or
* {@link SeededRandom.fromState} instead.
*/
protected constructor(alea: AleaRandom);
/** Generates the next deterministic pseudo random number. */
next(): number;
/**
* Create a {@link SeededRandom} copy with the same state as this one. This is the same as
* calling {@link SeededRandom.exportState} and passing it directly into
* {@link SeededRandom.fromState}.
*/
clone(): SeededRandom;
}
/**
* Alea algorithm has the following license from http://baagoe.com/en/RandomMusings/javascript. The
* code has been modified to fit into a class structure and simplify code flow and arguments. The
* algorithm itself has not changed.
*
* Copyright (C) 2010 by Johannes Baagøe (baagoe@baagoe.org)
*
* 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.
*/
/** Alea v0.9 */
declare class AleaRandom {
protected n: number;
protected s: [
number,
number,
number,
number
];
/** Mash v0.9. */
protected mash(input: any): number;
constructor(seed: string | number);
next(): number;
importState(state: typeof this.s): void;
exportState(): typeof this.s;
}
export {};