@sdxc/random 0.0.0-pre.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio Xalambrí
+
+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.

package/README.md

@@ -0,0 +1,185 @@
+# @sdxc/random
+
+Seeded and system random streams with integer, float, pick and shuffle draws, and resumable state.
+
+## Installation
+
+```bash
+npm add @sdxc/random
+```
+
+The main entry point has no dependencies. `@sdxc/random/schema` exports `RANDOM_STATE_SCHEMA`, a [`remix/data-schema`](https://www.npmjs.com/package/remix) schema; install `remix` to use it.
+
+## Usage
+
+### Rolling From A Seed
+
+```typescript
+import { createRandom } from "@sdxc/random";
+
+let dice = createRandom("battle-42");
+
+dice.int(1, 6); // the same six numbers, in the same order, on every run
+dice.float(0.85, 1);
+dice.bool(0.1);
+dice.pick(["rock", "paper", "scissors"]);
+dice.shuffle([1, 2, 3, 4, 5]);
+```
+
+### Accepting Randomness In Your Own API
+
+Declare the parameter as `Random` and default it to `systemRandom()`. Production passes nothing, and a test passes a seeded stream instead of stubbing `Math.random`.
+
+```typescript
+import type { Random } from "@sdxc/random";
+
+import { createRandom, systemRandom } from "@sdxc/random";
+
+function shouldSample(rate: number, random: Random = systemRandom()): boolean {
+	return random.bool(rate);
+}
+
+shouldSample(0.1); // crypto-backed
+shouldSample(0.1, createRandom("sampler-test")); // reproducible
+```
+
+### Saving And Resuming A Stream
+
+`state()` is plain JSON. `restoreRandom` continues from the next draw the original would have taken.
+
+```typescript
+import { createRandom, restoreRandom } from "@sdxc/random";
+
+let encounters = createRandom("world-7");
+encounters.int(1, 100);
+
+let saved = JSON.stringify(encounters.state());
+let resumed = restoreRandom(JSON.parse(saved));
+
+resumed.int(1, 100) === encounters.int(1, 100); // true
+```
+
+### Independent Streams From One Seed
+
+`derive(label)` opens a stream seeded from the parent's seed and the label, so extra draws in one part of a program never shift the values another part sees.
+
+```typescript
+import { createRandom, systemSeed } from "@sdxc/random";
+
+let session = createRandom(systemSeed());
+
+let battle = session.derive("battle");
+let loot = session.derive("loot");
+```
+
+## API
+
+### `createRandom(seed: Seed): SeededRandom`
+
+Open a stream on a seed. The same seed produces the same values in the same order on any machine; `42` and `"42"` name the same stream.
+
+### `restoreRandom(state: RandomState): SeededRandom`
+
+Rebuild a stream from a `state()` snapshot, positioned exactly where the snapshot was taken.
+
+### `systemRandom(): Random`
+
+An unseeded stream drawing from `crypto.getRandomValues`, for jitter, sampling and short tie-breakers. It has no seed and no state, so it cannot be replayed. Use Web Crypto directly, or a token library, for keys and secrets.
+
+### `systemSeed(): number`
+
+A fresh 32-bit seed from `crypto.getRandomValues`. Log it, and the run replays by passing it back to `createRandom`.
+
+### `RANDOM_STATE_SCHEMA` from `@sdxc/random/schema`
+
+A `remix/data-schema` schema for a `RandomState` read from storage. It checks the seed's type and that each of the four words is an unsigned 32-bit integer.
+
+### `Random`
+
+The draws every stream offers:
+
+- `next()`: the raw draw, in `[0, 1)`
+- `int(min, max)`: an integer with both ends included; throws `RangeError` on non-integer bounds or `max < min`
+- `float(min = 0, max = 1)`: a number in `[min, max)`
+- `bool(chance = 0.5)`: `true` with probability `chance`
+- `pick(items)`: one element, each equally likely; throws `RangeError` on an empty list
+- `shuffle(items)`: a shuffled copy, leaving the input untouched
+
+### `SeededRandom`
+
+A `Random` with `seed`, `derive(label)` and `state()`.
+
+### `Seed` and `RandomState`
+
+`Seed` is `number | string`. `RandomState` is `{ seed, words }`, where `words` holds the generator's four unsigned 32-bit words.
+
+## Pattern: A Reproducible Fuzz Run
+
+Draw a fresh seed per run unless one is supplied, and print it, so a failing run replays from that number.
+
+```typescript
+import { createRandom, systemSeed } from "@sdxc/random";
+
+let seed = Number(process.env.FUZZ_SEED) || systemSeed();
+console.info(`fuzz seed: ${seed}`);
+
+let random = createRandom(seed);
+let cases = Array.from({ length: 1000 }, () => ({
+	minute: random.int(0, 59),
+	hour: random.int(0, 23),
+	weekday: random.pick(["MON", "TUE", "WED", "THU", "FRI"]),
+}));
+```
+
+## Pattern: Persisting A Simulation
+
+Store each stream's state next to the world it shaped, and validate it on load, since a save file is untrusted input.
+
+```typescript
+import * as s from "remix/data-schema";
+
+import { createRandom, restoreRandom } from "@sdxc/random";
+import { RANDOM_STATE_SCHEMA } from "@sdxc/random/schema";
+
+const SAVE_SCHEMA = s.object({ turn: s.number(), random: RANDOM_STATE_SCHEMA });
+
+let random = createRandom("campaign");
+let turn = 0;
+
+function save(): string {
+	return JSON.stringify({ turn, random: random.state() });
+}
+
+function load(text: string) {
+	let parsed = s.parseSafe(SAVE_SCHEMA, JSON.parse(text));
+	if (!parsed.success) throw new Error("Corrupt save file");
+	turn = parsed.value.turn;
+	random = restoreRandom(parsed.value.random);
+}
+```
+
+## Versioning
+
+Releases are dated rather than semantic. A version is the UTC date it was published, written `YYYY.M.D`, so `2026.9.4` is the release from 4 September 2026. At most one release goes out per day.
+
+Those numbers say when, not what: a later date means a later release and carries no compatibility promise. Any release may change or remove an export.
+
+Depend on one exact date, and move it when you are ready to take the change:
+
+```json
+{
+	"dependencies": {
+		"@sdxc/random": "2026.9.4"
+	}
+}
+```
+
+A caret or tilde range reads the date as major, minor and patch, so it accepts every later release in the same year. An exact version keeps the upgrade yours to schedule.
+
+## License
+
+MIT
+
+## Author
+
+[Sergio Xalambrí](https://sergiodxa.com)

package/dist/draws.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The `Random` interface and the draws built on a raw `[0, 1)` source. Every
+ * stream, seeded or system, shares these definitions, so `int`, `pick` and
+ * `shuffle` carry one set of bounds and one set of errors across the package.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** A source of random values, and the draws that consume it. */
+export interface Random {
+    /** The next raw draw, in `[0, 1)`. */
+    next(): number;
+    /**
+     * An integer in `[min, max]`, both ends included.
+     *
+     * @throws RangeError when a bound is not a safe integer, or `max` is below
+     * `min`.
+     */
+    int(min: number, max: number): number;
+    /** A number in `[min, max)`, defaulting to `[0, 1)`. */
+    float(min?: number, max?: number): number;
+    /** `true` with probability `chance`, half the time by default. */
+    bool(chance?: number): boolean;
+    /**
+     * One element, every element equally likely.
+     *
+     * @throws RangeError when the list is empty.
+     */
+    pick<T>(items: readonly T[]): T;
+    /** A shuffled copy; the argument keeps its order. */
+    shuffle<T>(items: readonly T[]): T[];
+}
+/**
+ * Build every draw on top of `next`. Each draw consumes a fixed number of raw
+ * values for a given input, which is what keeps a seeded sequence stable.
+ *
+ * @param next - The raw source, returning values in `[0, 1)`.
+ * @returns The draws, all reading from `next`.
+ */
+export declare function drawsFrom(next: () => number): Random;

package/dist/draws.js

@@ -0,0 +1,50 @@
+/**
+ * The `Random` interface and the draws built on a raw `[0, 1)` source. Every
+ * stream, seeded or system, shares these definitions, so `int`, `pick` and
+ * `shuffle` carry one set of bounds and one set of errors across the package.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Build every draw on top of `next`. Each draw consumes a fixed number of raw
+ * values for a given input, which is what keeps a seeded sequence stable.
+ *
+ * @param next - The raw source, returning values in `[0, 1)`.
+ * @returns The draws, all reading from `next`.
+ */
+export function drawsFrom(next) {
+    let random = {
+        next,
+        int(min, max) {
+            if (!Number.isSafeInteger(min) || !Number.isSafeInteger(max)) {
+                throw new RangeError(`int() needs safe integer bounds, received ${min} and ${max}.`);
+            }
+            if (max < min)
+                throw new RangeError(`int() needs max (${max}) to be at least min (${min}).`);
+            return min + Math.floor(next() * (max - min + 1));
+        },
+        float(min = 0, max = 1) {
+            return min + next() * (max - min);
+        },
+        bool(chance = 0.5) {
+            return next() < chance;
+        },
+        pick(items) {
+            if (items.length === 0)
+                throw new RangeError("pick() needs a list with at least one item.");
+            return items[random.int(0, items.length - 1)];
+        },
+        shuffle(items) {
+            let copy = [...items];
+            for (let index = copy.length - 1; index > 0; index--) {
+                let target = random.int(0, index);
+                let held = copy[index];
+                copy[index] = copy[target];
+                copy[target] = held;
+            }
+            return copy;
+        },
+    };
+    return random;
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The package entrypoint: the `Random` interface a consumer accepts, the seeded
+ * stream a caller replays or persists, and the Web Crypto stream for values that
+ * only need a good spread. It has no dependencies; the snapshot parser lives in
+ * `@sdxc/random/schema`.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export type { Random } from "./draws.js";
+export type { RandomState, Seed, SeededRandom } from "./seeded.js";
+export { createRandom, restoreRandom } from "./seeded.js";
+export { systemRandom, systemSeed } from "./system.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createRandom, restoreRandom } from "./seeded.js";
+export { systemRandom, systemSeed } from "./system.js";

package/dist/schema.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The parser for a `RandomState` read back from storage, on its own entry point
+ * so only a caller that parses snapshots installs `remix`. A save file is
+ * untrusted input, and a malformed snapshot would resume a different stream.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Schema } from "remix/data-schema";
+import type { RandomState } from "./seeded.js";
+/**
+ * Reads a snapshot from `state()`, so `restoreRandom` receives exactly the
+ * shape it was written in.
+ *
+ * @example s.parseSafe(RANDOM_STATE_SCHEMA, JSON.parse(stored))
+ */
+export declare const RANDOM_STATE_SCHEMA: Schema<unknown, RandomState>;

package/dist/schema.js

@@ -0,0 +1,20 @@
+import * as s from "remix/data-schema";
+/** Reads one generator word, which the stream stores as an unsigned 32-bit integer. */
+const WORD_SCHEMA = s
+    .number()
+    .refine((value) => Number.isInteger(value) && value >= 0 && value <= 0xffffffff, "Expected an unsigned 32-bit integer");
+/**
+ * Reads a snapshot from `state()`, so `restoreRandom` receives exactly the
+ * shape it was written in.
+ *
+ * @example s.parseSafe(RANDOM_STATE_SCHEMA, JSON.parse(stored))
+ */
+export const RANDOM_STATE_SCHEMA = s.object({
+    seed: s.union([s.string(), s.number()]),
+    words: s.tuple([
+        WORD_SCHEMA,
+        WORD_SCHEMA,
+        WORD_SCHEMA,
+        WORD_SCHEMA,
+    ]),
+});

package/dist/seeded.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The seeded stream: output depends on the seed and on how many draws have been
+ * taken, and on nothing else, so a seed replays the same sequence on any machine.
+ * Its four words of state can be saved and restored to resume a stream mid-way.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Random } from "./draws.js";
+/** A seed as a caller supplies it; text and numbers both name a stream. */
+export type Seed = number | string;
+/**
+ * Where a seeded stream stands. It is plain JSON, so it can be stored beside the
+ * data it produced and handed back to `restoreRandom` later.
+ */
+export interface RandomState {
+    /** The seed the stream was opened on, which `derive` keeps building from. */
+    seed: Seed;
+    /** The generator's four unsigned 32-bit words. */
+    words: [number, number, number, number];
+}
+/** A stream that can be replayed, derived from and persisted. */
+export interface SeededRandom extends Random {
+    /** The seed this stream replays from. */
+    readonly seed: Seed;
+    /**
+     * An independent stream named by `label`. It is seeded from this stream's
+     * seed and the label alone, so its values hold still no matter how many
+     * draws this stream has taken or takes later.
+     */
+    derive(label: string): SeededRandom;
+    /** A snapshot that `restoreRandom` resumes from the next draw on. */
+    state(): RandomState;
+}
+/**
+ * Open a stream on a seed. Two streams on the same seed produce the same values
+ * in the same order, which is what lets a run be reproduced from the seed alone.
+ *
+ * @param seed - Text or a number naming the stream to replay.
+ * @returns The stream, positioned at its first value.
+ * @example createRandom("battle-42").int(1, 6)
+ */
+export declare function createRandom(seed: Seed): SeededRandom;
+/**
+ * Resume a stream from a snapshot. The restored stream draws exactly what the
+ * original would have drawn next, and derives the same streams it would have.
+ *
+ * @param state - A snapshot from `state()`; validate one read from storage with `RANDOM_STATE_SCHEMA`.
+ * @returns The stream, positioned where the snapshot was taken.
+ * @example restoreRandom(saved.random).int(1, 6)
+ */
+export declare function restoreRandom(state: RandomState): SeededRandom;

package/dist/seeded.js

@@ -0,0 +1,80 @@
+import { drawsFrom } from "./draws.js";
+/** Joins a seed to a label so `derive` composes into a readable seed. */
+const LABEL_SEPARATOR = " ";
+/**
+ * Hash text into the four 32-bit words the generator starts from, so a seed can
+ * be anything a caller finds meaningful and still spreads across the state.
+ */
+function hashSeed(seed) {
+    let text = String(seed);
+    let a = 1779033703;
+    let b = 3144134277;
+    let c = 1013904242;
+    let d = 2773480762;
+    for (let index = 0; index < text.length; index++) {
+        let code = text.charCodeAt(index);
+        a = b ^ Math.imul(a ^ code, 597399067);
+        b = c ^ Math.imul(b ^ code, 2869860233);
+        c = d ^ Math.imul(c ^ code, 951274213);
+        d = a ^ Math.imul(d ^ code, 2716044179);
+    }
+    a = Math.imul(c ^ (a >>> 18), 597399067);
+    b = Math.imul(d ^ (b >>> 22), 2869860233);
+    c = Math.imul(a ^ (c >>> 17), 951274213);
+    d = Math.imul(b ^ (d >>> 19), 2716044179);
+    return [(a ^ b ^ c ^ d) >>> 0, (b ^ a) >>> 0, (c ^ a) >>> 0, (d ^ a) >>> 0];
+}
+/**
+ * Open the generator on `seed` positioned at `words`: four words of state
+ * advanced per draw, which buys a long period and a flat distribution for a
+ * handful of integer operations.
+ */
+function seededStream(seed, words) {
+    let [a, b, c, d] = words;
+    /** Advance the state one step and read the draw it produced. */
+    function next() {
+        a |= 0;
+        b |= 0;
+        c |= 0;
+        d |= 0;
+        let sum = (((a + b) | 0) + d) | 0;
+        d = (d + 1) | 0;
+        a = b ^ (b >>> 9);
+        b = (c + (c << 3)) | 0;
+        c = (c << 21) | (c >>> 11);
+        c = (c + sum) | 0;
+        return (sum >>> 0) / 4294967296;
+    }
+    return {
+        ...drawsFrom(next),
+        seed,
+        derive(label) {
+            return createRandom(`${seed}${LABEL_SEPARATOR}${label}`);
+        },
+        state() {
+            return { seed, words: [a >>> 0, b >>> 0, c >>> 0, d >>> 0] };
+        },
+    };
+}
+/**
+ * Open a stream on a seed. Two streams on the same seed produce the same values
+ * in the same order, which is what lets a run be reproduced from the seed alone.
+ *
+ * @param seed - Text or a number naming the stream to replay.
+ * @returns The stream, positioned at its first value.
+ * @example createRandom("battle-42").int(1, 6)
+ */
+export function createRandom(seed) {
+    return seededStream(seed, hashSeed(seed));
+}
+/**
+ * Resume a stream from a snapshot. The restored stream draws exactly what the
+ * original would have drawn next, and derives the same streams it would have.
+ *
+ * @param state - A snapshot from `state()`; validate one read from storage with `RANDOM_STATE_SCHEMA`.
+ * @returns The stream, positioned where the snapshot was taken.
+ * @example restoreRandom(saved.random).int(1, 6)
+ */
+export function restoreRandom(state) {
+    return seededStream(state.seed, [...state.words]);
+}

package/dist/system.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Randomness drawn from `crypto.getRandomValues`: a well-spread source for
+ * jitter, sampling and short tie-breakers, and the fresh seed a reproducible run
+ * starts from. Both work in every runtime that ships Web Crypto.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Random } from "./draws.js";
+/**
+ * Open an unseeded stream. Each draw is a fresh 32-bit value from Web Crypto,
+ * so its sequence never repeats across calls, processes or runs.
+ *
+ * @returns A stream with the same draws a seeded stream offers.
+ * @example systemRandom().float(0.8, 1.2)
+ */
+export declare function systemRandom(): Random;
+/**
+ * Draw a seed from Web Crypto, for a process that wants fresh values on every
+ * run. Log the returned number and that run stays reproducible by passing it back.
+ *
+ * @returns A 32-bit seed.
+ * @example createRandom(systemSeed())
+ */
+export declare function systemSeed(): number;

package/dist/system.js

@@ -0,0 +1,31 @@
+import { drawsFrom } from "./draws.js";
+/** Words fetched per refill, so a burst of draws costs one Web Crypto call. */
+const BUFFER_WORDS = 64;
+/**
+ * Open an unseeded stream. Each draw is a fresh 32-bit value from Web Crypto,
+ * so its sequence never repeats across calls, processes or runs.
+ *
+ * @returns A stream with the same draws a seeded stream offers.
+ * @example systemRandom().float(0.8, 1.2)
+ */
+export function systemRandom() {
+    let buffer = new Uint32Array(BUFFER_WORDS);
+    let position = BUFFER_WORDS;
+    return drawsFrom(function next() {
+        if (position === BUFFER_WORDS) {
+            crypto.getRandomValues(buffer);
+            position = 0;
+        }
+        return buffer[position++] / 4294967296;
+    });
+}
+/**
+ * Draw a seed from Web Crypto, for a process that wants fresh values on every
+ * run. Log the returned number and that run stays reproducible by passing it back.
+ *
+ * @returns A 32-bit seed.
+ * @example createRandom(systemSeed())
+ */
+export function systemSeed() {
+    return crypto.getRandomValues(new Uint32Array(1))[0];
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "@sdxc/random",
+	"version": "0.0.0-pre.1",
+	"description": "Seeded and system random streams with integer, float, pick and shuffle draws, and resumable state",
+	"license": "MIT",
+	"type": "module",
+	"exports": {
+		".": "./dist/index.js",
+		"./schema": "./dist/schema.js"
+	},
+	"peerDependencies": {
+		"remix": "3.0.0"
+	},
+	"peerDependenciesMeta": {
+		"remix": {
+			"optional": true
+		}
+	},
+	"gitHead": "47e70835fe3943a13cf37f07c3dfb8203aba1c35",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/sergiodxa/monorepo.git",
+		"directory": "packages/random"
+	}
+}