@bluehive/random – Full TypeScript Meteor Random Port (API Compatible, Unit Tested, GitHub CI, Modern Packaging)

announce
1

Hey Meteor Community!

I’m excited to share @bluehive/random, a TypeScript-first, fully unit-tested, 100% API-compatible port of Meteor’s random package, now available as a modern npm package!
GitHub Repo | Live Demos & Docs

Why Another Random Port?

There are a few Meteor random ports, but I needed a solution that checks these boxes:

  • Full TypeScript support (with complete type definitions)
  • Comprehensive unit tests (89%+ coverage, 79 tests, see coverage reports)
  • GitHub Actions CI/CD for every commit/PR
  • Modern ESM/CommonJS packaging (works in Node, browsers, bundlers)
  • Zero runtime dependencies
  • API and deterministic output match Meteor’s original package
  • Easy migration: existing Meteor code should “just work” after changing the import.
  • Live interactive docs and playground

I’m migrating Meteor methods to a Fastify API for docs.bluehive.com and needed a drop-in replacement for Random.id() and Random.secret() that would behave identically—especially for session tokens and reproducible test data.

:rocket: Features

  • Cryptographically secure: Uses crypto.randomBytes() (Node) or window.crypto.getRandomValues() (browser); falls back to Alea PRNG with entropy if crypto is unavailable.
  • API Compatibility: All Meteor Random methods supported:
    import { Random } from '@bluehive/random';
const id = Random.id();
const secret = Random.secret();
const seeded = Random.createWithSeeds(42);
  • Deterministic output: Seeded generators produce the same sequence as Meteor’s implementation.
  • Character sets:
    • IDs: “Unmistakable” (avoids 0, 1, I, l, O)
    • Secrets: URL-safe base64
    • Hex strings: lowercase hex
  • Zero dependencies and modern JS packaging
  • Full coverage and test suite (89%+ coverage, 79 tests)
  • Works everywhere (Node, browsers, ESM/CJS, React/Next, etc.)
  • Live playground: Try it here

:technologist: TypeScript & Testing

  • Every API is fully typed; includes advanced usage and generic utilities (see the TypeScript examples)
  • 79 unit tests, including edge cases and environment fallbacks
  • Test commands:
    npm test
npm run test:coverage

:arrows_counterclockwise: Migration from Meteor

  1. npm install @bluehive/random
  2. Change imports:
    - import { Random } from 'meteor/random';
+ import { Random } from '@bluehive/random';
  3. All existing code should “just work”.

:package: Install & Example

npm install @bluehive/random

import { Random } from '@bluehive/random';

const id = Random.id();                // 17-char unique ID
const secret = Random.secret();        // 43-char cryptographically secure secret
const hex = Random.hexString(8);       // 8-char hex string
const seeded = Random.createWithSeeds(0);
console.log(seeded.id());              // Deterministic ID (matches Meteor)

:globe_with_meridians: Docs, Live Demos, and More

Use Cases

  • Drop-in replacement for Meteor’s random utilities (works in Meteor, Fastify, Next.js, Node, browser, etc.)
  • Generating session tokens, secrets, test data, API keys, etc.
  • Deterministic/random testing with seeds

Feedback, issues, and PRs welcome!
Let me know if you hit any migration snags or want to see more features/examples.

Thanks and happy hacking!

7 Likes
2

Splendid!
What do you think about extending the API? Over the years, I’ve run into a number of additional randoms that projects needed, which got partially recorded in the clinical:extended-api package. I’m thinking:

Random.uuid():
Random.date();
Random.integer();
Random.cardinal();
Random.number();
Random.decimal();
Random.fromRange();
3

Great idea!

I let copilot take a stab… Thoughts?

4

How long will we maintain our code abilities before our brains turn into mush? :smile:

1 Like