@sdxc/random 0.0.0-pre.1 → 2026.10.13

package/README.md

@@ -4,31 +4,31 @@ Seeded and system random streams with integer, float, pick and shuffle draws, an
 
 ## Installation
 
-```bash
+```sh
 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.
+The main entry point has no dependencies. The `@sdxc/random/schema` entry point needs [`remix`](https://www.npmjs.com/package/remix) for `remix/data-schema`.
 
 ## Usage
 
-### Rolling From A Seed
+### Roll 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.int(1, 6); // the same values, 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
+### Accept 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`.
+Type the parameter as `Random` and default it to `systemRandom()`. Production passes nothing; a test passes a seeded stream instead of stubbing `Math.random`.
 
 ```typescript
 import type { Random } from "@sdxc/random";
@@ -39,13 +39,13 @@ function shouldSample(rate: number, random: Random = systemRandom()): boolean {
 	return random.bool(rate);
 }
 
-shouldSample(0.1); // crypto-backed
+shouldSample(0.1); // Web Crypto backed
 shouldSample(0.1, createRandom("sampler-test")); // reproducible
 ```
 
-### Saving And Resuming A Stream
+### Save and resume a stream
 
-`state()` is plain JSON. `restoreRandom` continues from the next draw the original would have taken.
+`state()` is plain JSON, and `restoreRandom` continues with the draw the original would have taken next.
 
 ```typescript
 import { createRandom, restoreRandom } from "@sdxc/random";
@@ -59,9 +59,9 @@ let resumed = restoreRandom(JSON.parse(saved));
 resumed.int(1, 100) === encounters.int(1, 100); // true
 ```
 
-### Independent Streams From One Seed
+### Split one seed into independent streams
 
-`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.
+`derive(label)` opens a stream seeded from the parent's seed and the label, so extra draws in one part of a program leave the values of another part unchanged.
 
 ```typescript
 import { createRandom, systemSeed } from "@sdxc/random";
@@ -76,64 +76,108 @@ let loot = session.derive("loot");
 
 ### `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.
+Opens 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.
+Rebuilds 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.
+An unseeded stream drawing from `crypto.getRandomValues`, for jitter, sampling and tie-breakers. It has no seed or state, so it never replays. Generate keys and secrets with Web Crypto directly.
 
 ### `systemSeed(): number`
 
-A fresh 32-bit seed from `crypto.getRandomValues`. Log it, and the run replays by passing it back to `createRandom`.
+A fresh 32-bit seed from `crypto.getRandomValues`. Log it, and passing it back to `createRandom` replays the run.
 
-### `RANDOM_STATE_SCHEMA` from `@sdxc/random/schema`
+### `RANDOM_STATE_SCHEMA: Schema<unknown, RandomState>`
 
-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.
+From `@sdxc/random/schema`. A `remix/data-schema` schema for a `RandomState` read from storage: the seed is a string or number, and each of the four words is an unsigned 32-bit integer.
 
-### `Random`
+### Types
+
+#### `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`
+- `int(min, max)`: an integer with both ends included; throws `RangeError` when a bound is not a safe integer 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
+- `shuffle(items)`: a shuffled copy, leaving the input in its order
+
+#### `SeededRandom`
+
+A `Random` plus `seed`, `derive(label: string): SeededRandom` and `state(): RandomState`.
 
-### `SeededRandom`
+#### `Seed`
 
-A `Random` with `seed`, `derive(label)` and `state()`.
+`number | string`.
 
-### `Seed` and `RandomState`
+#### `RandomState`
 
-`Seed` is `number | string`. `RandomState` is `{ seed, words }`, where `words` holds the generator's four unsigned 32-bit words.
+`{ seed: Seed; words: [number, number, number, number] }`, the seed and the generator's four unsigned 32-bit words.
 
-## Pattern: A Reproducible Fuzz Run
+## Pattern: A Reproducible Fuzz Test
 
-Draw a fresh seed per run unless one is supplied, and print it, so a failing run replays from that number.
+Draw a fresh seed per run unless one is supplied, and put it in the suite name, so a failure reports the number that replays it.
 
 ```typescript
 import { createRandom, systemSeed } from "@sdxc/random";
+import { describe, expect, test } from "vitest";
+
+import { parseCron } from "./cron.js";
 
 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"]),
-}));
+
+describe(`cron parsing (FUZZ_SEED=${seed})`, () => {
+	test("every generated expression parses", () => {
+		let random = createRandom(seed);
+
+		for (let index = 0; index < 1000; index++) {
+			let minute = random.int(0, 59);
+			let hour = random.int(0, 23);
+			let weekday = random.pick(["MON", "TUE", "WED", "THU", "FRI"]);
+			expect(parseCron(`${minute} ${hour} * * ${weekday}`).success).toBe(true);
+		}
+	});
+});
+```
+
+## Pattern: Stable Procedural Generation
+
+Give each feature of a generated world its own derived stream. Adding a draw to the terrain generator later keeps every existing world's loot exactly as it was.
+
+```typescript
+import type { Random } from "@sdxc/random";
+
+import { createRandom } from "@sdxc/random";
+
+function terrain(random: Random): string[] {
+	return Array.from({ length: 8 }, () => random.pick(["plains", "forest", "hills", "lake"]));
+}
+
+function loot(random: Random): { gold: number; items: string[] } {
+	let gold = random.int(10, 100);
+	let items = random.shuffle(["sword", "shield", "potion", "map"]).slice(0, random.int(1, 3));
+	return { gold, items };
+}
+
+function generateWorld(seed: string) {
+	let world = createRandom(seed);
+	return {
+		terrain: terrain(world.derive("terrain")),
+		loot: loot(world.derive("loot")),
+	};
+}
+
+generateWorld("world-7"); // identical output for "world-7" on every machine
 ```
 
 ## 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.
+Store the stream's state next to the data it shaped, and validate it on load, since a save file is untrusted input.
 
 ```typescript
 import * as s from "remix/data-schema";
@@ -141,7 +185,7 @@ 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 saveSchema = s.object({ turn: s.number(), random: RANDOM_STATE_SCHEMA });
 
 let random = createRandom("campaign");
 let turn = 0;
@@ -150,14 +194,18 @@ 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");
+function load(text: string): boolean {
+	let parsed = s.parseSafe(saveSchema, JSON.parse(text));
+	if (!parsed.success) return false;
+
 	turn = parsed.value.turn;
 	random = restoreRandom(parsed.value.random);
+	return true;
 }
 ```
 
+A save that fails the schema leaves the running simulation untouched, and `load` answers `false`.
+
 ## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sdxc/random",
-	"version": "0.0.0-pre.1",
+	"version": "2026.10.13",
 	"description": "Seeded and system random streams with integer, float, pick and shuffle draws, and resumable state",
 	"license": "MIT",
 	"type": "module",
@@ -16,7 +16,7 @@
 			"optional": true
 		}
 	},
-	"gitHead": "47e70835fe3943a13cf37f07c3dfb8203aba1c35",
+	"gitHead": "5ff758a57e35480a8db7abd24f1d9527b81bfb51",
 	"publishConfig": {
 		"access": "public"
 	},
@@ -24,5 +24,14 @@
 		"type": "git",
 		"url": "git+https://github.com/sergiodxa/monorepo.git",
 		"directory": "packages/random"
+	},
+	"homepage": "https://sdxc.sergiodxa.com/api/random",
+	"author": {
+		"name": "Sergio Xalambrí",
+		"url": "https://sergiodxa.com"
+	},
+	"funding": {
+		"type": "github",
+		"url": "https://github.com/sponsors/sergiodxa"
 	}
 }