Nightclub Party Music

    @thi.ng/random-fxhash
    TypeScript icon, indicating that this package has built-in type declarations

    0.2.6 • Public • Published

    random-fxhash

    npm version npm downloads Twitter Follow

    This project is part of the @thi.ng/umbrella monorepo.

    About

    @thi.ng/random compatible wrapper & utilities for fxhash's PRNG.

    fxhash is a platform for publishing generative art projects on the Tezos blockchain, where each individual project edition is driven by an unique transaction hash, incl. the platform's provided PRNG which is meant to be used by each project to ensure deterministic behavior and reproducibility. The fxhash PRNG is an implementation of the SFC32 (Simple Fast Counter) algorithm, which is also provided by the @thi.ng/random parent package.

    This support package provides a singleton implementation (RND) of that PRNG, pre-seeded with the global fxhash var injected by the platform. Of course pre-seeding with a transaction hash is only possible when using this package in the browser and in conjunction with a fxhash HTML template. If the global fxhash var is not defined, the RND instance will be seeded with a default seed (but can also be re-seeded later on). This also allows this package to be used outside the browser env, where the fxhash provided code snippet isn't available...

    Additionally, the package also provides various wrappers for other commonly used utilities from the @thi.ng/random package. These are wrapped in such a way that they're using the RND singleton by default (but optionally accept any other IRandom implementation as additional arg). See examples below.

    Further functionality

    All thi.ng/umbrella packages dealing with randomness in any shape or form are supporting the above mentioned IRandom interface. That means the RND instance can be passed to any of the functions/classes to provide more advanced functionality, e.g.:

    Status

    ALPHA - bleeding edge / work-in-progress

    Search or submit any issues for this package

    Related packages

    • @thi.ng/base-n - Arbitrary base-n conversions w/ presets for base16/32/36/58/62/64/85, support for arrays & bigints

    Installation

    yarn add @thi.ng/random-fxhash

    For Node.js REPL:

    # with flag only for < v16
    node --experimental-repl-await
    
    > const randomFxhash = await import("@thi.ng/random-fxhash");
    

    Package sizes (gzipped, pre-treeshake): ESM: 499 bytes

    IMPORTANT: When using this package (or any other packages from this monorepo) for fxhash, you MUST use a bundler (e.g. Vite, Parcel or Webpack), since the platform does not support ES module imports from external sources/CDNs. A related boilerplate project template will be published soon. Follow @thing_umbrella on Twitter for updates...

    Dependencies

    API

    Generated API docs

    TODO

    import {
        RND,
        probability,
        pick, pickKey,
        weighted, weightedKey,
        seedFromHash,
    } from "@thi.ng/random-fxhash";
    
    const themes = {
        bw: ["#000", "#fff"],
        gray: ["#666", "#ccc"],
        red: ["#f00", "#000"],
        yellow: ["#ff0", "#00f"],
    };
    
    // (uniformly) pick a random value
    const thickness = pick([0.5, 1, 2, 3]);
    
    // (uniformly) pick random key from `themes`
    const themeID = pickKey(themes);
    // "gray"
    
    // pick a key from given object of weights
    // i.e. "bw" is 8x more likely to be picked than "yellow"
    const themeID = weightedKey({ bw: 8, gray: 4, red: 2, yellow: 1 })
    // "bw"
    
    // same, but using individual arrays of choices/weights
    const themeID = weighted(["bw", "gray", "red", "yellow"], [8, 4, 2, 1]);
    
    // 20% chance for slow mode
    const isSlow = probability(0.2);
    
    // the IRandom interface also provides these methods:
    
    // return a 32bit unsigned int
    RND.int()
    
    // return a float in [0..n) interval (default n = 1)
    RND.float(n)
    
    // return a float in [-n..n) interval (default n = 1)
    RND.norm(n)
    
    // return a float in [min..max) interval
    RND.minmax(0.5, 1)
    
    // return a int in [min..max) interval
    RND.minmaxInt(0, 100)
    
    // (re)seed from transaction hash
    RND.seed(seedFromHash("ookorwLedQrCTPesBcUPrR2oRbPHgsAxe9xgCSNq4XAuZSaCvaB"));
    
    // or reseed from uint's
    RND.seed([1, 2, 3, 4]);

    Authors

    Karsten Schmidt

    If this project contributes to an academic publication, please cite it as:

    @misc{thing-random-fxhash,
      title = "@thi.ng/random-fxhash",
      author = "Karsten Schmidt",
      note = "https://thi.ng/random-fxhash",
      year = 2022
    }

    License

    © 2022 Karsten Schmidt // Apache Software License 2.0

    Install

    npm i @thi.ng/random-fxhash

    DownloadsWeekly Downloads

    83

    Version

    0.2.6

    License

    Apache-2.0

    Unpacked Size

    28 kB

    Total Files

    6

    Last publish

    Collaborators

    • thi.ng