@lazy-random/generators-seedrandom
基於 seedrandom 的可設定種子 (Seedable) 亂數產生器 (Random Number Generator)，隸屬 @lazy-random 系列套件。
本套件以 RNGSeedRandom 類別包裝 seedrandom，繼承自 @lazy-random/generators-function 的 RNGFunction，除了一般的種子亂數之外，也可切換 seedrandom 內建的多種擬隨機演算法 (PRNG Algorithm)。
特色 (Features)
- 支援以任意字串、數字或函式作為種子 (Seed)，可重複重現的亂數序列 (Reproducible Sequence)
- 可切換
seedrandom內建演算法：alea、tychei、xor128、xor4096、xorshift7、xorwow - 亦可傳入
seedrandom/lib/下的其他演算法名稱字串 - 預設啟用平台熵值 (Entropy)，讓未指定種子時仍能取得非固定序列
- 可讀取／還原內部狀態 (State)，並支援
clone()複製實例 - 同時提供 CommonJS (
dist/index.cjs) 與 ECMAScript Module (dist/index.esm.mjs) 兩種輸出，並附帶型別宣告 (dist/index.d.ts)
安裝 (Installation)
yarn add @lazy-random/generators-seedrandom
yarn-tool add @lazy-random/generators-seedrandom
yt add @lazy-random/generators-seedrandom使用方式 (Usage)
基本用法：
import RNGSeedRandom from '@lazy-random/generators-seedrandom'
const rng = new RNGSeedRandom('my seed')
console.log(rng.name) // 'seedrandom'指定 seedrandom 內建演算法，建議使用 createLib()，其參數順序為 (lib, seed, opts)：
import { RNGSeedRandom } from '@lazy-random/generators-seedrandom'
const rng = RNGSeedRandom.createLib('alea', 'my seed')
console.log(rng.name)直接以建構子建立時，演算法名稱 (Library Name) 為第三個參數：
import { RNGSeedRandom } from '@lazy-random/generators-seedrandom'
const rng = new RNGSeedRandom('my seed', undefined, 'xor128')重新指定種子 (Reseed)：
rng.seed('another seed')API 文件 (API Documentation)
class RNGSeedRandom
繼承自 RNGFunction<ISeedRandomPRNG>，內部以 seedrandom 產生擬隨機數列 (Pseudorandom Sequence)。
constructor(seed?, opts?, lib?, ...argv)
| 參數 (Parameter) | 型別 (Type) | 說明 (Description) |
|---|---|---|
seed |
any |
種子 (Seed)，可省略 |
opts |
IRNGSeedRandomOptions |
傳給 seedrandom 的選項 (Options)，即 seedrandom(seed, opts) 的第二個參數 |
lib |
IRNGSeedRandomLib |
演算法名稱字串或函式；省略時使用 seedrandom 預設演算法 |
...argv |
any[] |
其餘參數，原樣轉交基類 (Forwarded to the base class) |
static createLib(lib?, seed?, opts?, ...argv): RNGSeedRandom
以「演算法在最前」的參數順序建立實例，內部會重新排列為建構子的 (seed, opts, lib) 順序。
static create(seed?, opts?, lib?, ...argv): RNGSeedRandom
與 new RNGSeedRandom(...) 等價的靜態工厂方法 (Static Factory Method)。
get name(): string
回傳產生器名稱 (Generator Name)，格式為 seedrandom，若指定了演算法則附加 :<演算法> 後綴。
get options(): IRNGSeedRandomOptions
回傳目前生效的 seedrandom 選項 (Options)。
get state(): IRNGSeedRandomState | undefined
回傳 seedrandom 的內部狀態 (Internal State)，僅在選項 state: true 時有值，否則回傳 undefined。
seed(seed?, opts?, ...argv): void
重新指定種子並重建亂數序列。傳入 opts === null 會清除既有選項（_opts 設為 undefined，待下一次 _init() 才重新套用 defaultOptions）；傳入其他假值 (Falsy) 則沿用現有選項，真值 (Truthy) 才覆寫。
clone(seed?, opts?, ...argv): RNGSeedRandom
以目前實例的設定複製出新的 RNGSeedRandom。
defaultOptions: IRNGSeedRandomOptions
以 Object.freeze 凍結的預設選項，內容為 { entropy: true }，於 _init() 時套用。
型別 (Types)
| 型別 (Type) | 說明 (Description) |
|---|---|
IRNGSeedRandomOptions |
seedrandom 函式第二個參數的型別，由 Parameters<typeof seedrandom>[1] 推導 |
ISeedRandomPRNG |
seedrandom 回傳的擬隨機數列產生器 (PRNG)，即 seedrandom.PRNG |
IRNGSeedRandomLibName |
seedrandom 內建演算法名稱：'alea' | 'tychei' | 'xor128' | 'xor4096' | 'xorshift7' | 'xorwow' |
IRNGSeedRandomLib |
演算法名稱字串的聯合型別 (Union Type)，允許任何字串 |
IRNGSeedRandomState |
內部狀態結構：i、j 索引 (Index) 與洗牌後的記憶池 S (Shuffled Pool) |
IRNGSeedRandomGenerator |
可呼叫的亂數來源函式 (Callable Random Source) |
設定 (Configuration)
seedrandom 選項會於 _init() 時以 defaultOptions（{ entropy: true }）作為基底，並可於建構子或 seed() 呼叫時覆寫：
import { RNGSeedRandom, defaultOptions } from '@lazy-random/generators-seedrandom'
console.log(defaultOptions) // Object { entropy: true }
const rng = new RNGSeedRandom('my seed', { entropy: false, state: true })
console.log(rng.state)開發 (Development)
專案根目錄使用 pnpm + lerna 的 monorepo 結構，本套件常見指令：
pnpm run build # 以 tsdx 建置 dist，並輸出型別宣告
pnpm run test # 執行測試
pnpm run lint # 執行 ESLint變更日誌 (Changelog)
請見 CHANGELOG.md。
相關資源 (Related Resources)
- 原始碼倉庫 (Repository)：https://github.com/bluelovers/ws-random
- 問題回報 (Issues)：https://github.com/bluelovers/ws-random/issues
- seedrandom：https://github.com/davidbau/seedrandom
- 相依套件 (Dependencies)：@lazy-random/generators-function、@lazy-random/clone-class、@lazy-random/shared-lib