library-random

The reference WASM implementation of perfscale's @std/random value-generation library, built with perfscale-library-sdk. It is also the template-quality example for library authors: every function, error message, the memo semantics, and the embedded corpora are a direct port of the engine's native built-in (crates/perfscale-core/src/library/std_random.rs in the perfscale repo), so a run with this component behaves identically to the built-in random alias.

The component exports one library, random (from the crate name), so tokens work as ${random.fn(...)} with the default alias.

Functions

Every function accepts an optional trailing key argument: within one message, repeat calls with the same key return the same (memoized) value; ${random.uuid4(order)} appearing twice in one message yields one id, while ${random.uuid4()} is always fresh.

Function	Returns
uuid4([key])	Random RFC 4122 v4 UUID
uuid7([key])	Time-ordered RFC 9562 v7 UUID (48-bit unix-ms prefix)
ulid([key])	26-char Crockford-base32 ULID (unix-ms prefix)
nanoid([len], [key])	URL-safe id from A-Za-z0-9_- (default len 21)
int(a, b, [key])	Random integer in [a, b] inclusive
float(a, b, [dp], [key])	Random float in [a, b], dp decimals (default 2)
pick(a|b|c, [key])	Random pick among |-separated options
weighted(a:10|b:90, [key])	Weighted random pick among value:weight pairs
seq(name)	Named monotonic counter per generator instance, starting at 1
pattern("ORD-####-????")	Template fill: #→digit, ?→a-z, ^→A-Z, *→alphanumeric
first_name() / last_name() / name()	Random names (small embedded corpora)
username() / email() / company()	Random username / email / company
lorem([words])	Lorem-ipsum words (default 5)
phone()	Random phone number (+1-NNN-NNN-NNNN)
date(a, b)	Random date between YYYY-MM-DD a and b inclusive, YYYY-MM-DD out
timestamp(a, b)	Random unix-ms timestamp in [a, b]
datetime(a, b)	Random RFC 3339 datetime between dates a and b (whole end day included)

Usage

Download random.wasm from a release (or build it yourself), then declare it in your perfscale config or test file — paths are relative to the declaring file:

libraries:
  - use: ./random.wasm # default alias: random

steps:
  - name: insert order
    use: std/db-query@v1
    with:
      id: "${{ db.id }}"
      query: INSERT INTO orders (id, code, who) VALUES (?, ?, ?)
      params:
        - "${random.ulid()}"
        - "${random.pattern("ORD-####-^^")}"
        - "${random.email()}"

No capabilities: grants are needed — the component imports no WASI interfaces beyond the library ABI.

Building

Rust ≥ 1.82 emits WASI Preview 2 components natively — no cargo-component needed:

$ rustup target add wasm32-wasip2
$ cargo build --release --target wasm32-wasip2
# → target/wasm32-wasip2/release/random.wasm

Unit tests run on the host through the SDK's test_call harness (no wasm runtime needed):

$ cargo test

On macOS, builds need the Command Line Tools SDK selected:

$ export DEVELOPER_DIR=/Library/Developer/CommandLineTools

Relationship to the engine's built-in

The perfscale engine embeds @std/random@v1 as a native (non-WASM) built-in library — declare - use: '@std/random@v1' and nothing is loaded from disk. This repo is the same library compiled to a WASM component: it serves as the reference proving the WASM library ABI can reproduce the native behavior exactly (same xorshift64 PRNG, same draw order, same error messages), and as the template to copy when authoring your own library.

License

MIT OR Apache-2.0, same as perfscale.