base64id

base64id is a minimal Node.js utility, best known as the id generator originally built for Socket.IO/Engine.IO, that produces short, URL-safe unique identifiers encoded in base64. It buffers cryptographically secure random bytes from Node’s crypto module to reduce the overhead of repeated synchronous calls, then mixes in an internal sequence counter before encoding the result, replacing / and + with _ and - so the output is safe to use directly in URLs, filenames, or realtime handshake payloads.

The library predates modern id-generation packages like nanoid and uuid and has no runtime dependencies beyond Node’s built-in crypto module. It exposes a single generateId() function and falls back to a Math.random()-based path on Node.js runtimes too old to have crypto.randomBytes.

What You Get

• A single generateId() function that returns a URL-safe base64-encoded unique id string.
• Buffered random byte generation that amortizes the cost of Node’s crypto.randomBytes across many id generations.
• A safe legacy fallback path for pre-crypto Node.js runtimes (<= 0.4).
• Zero runtime dependencies beyond Node’s built-in crypto module.

Common Use Cases

• Generating unique session or connection ids for realtime servers (its original use inside Engine.IO/Socket.IO).
• Producing short, URL-safe tokens for cache keys or temporary identifiers.
• Issuing high volumes of ids in performance-sensitive services without paying for a synchronous crypto call every time.

Under The Hood

Architecture base64id ships as a single CommonJS file, lib/base64id.js, exporting one singleton instance of a Base64Id constructor with two prototype methods, getRandomBytes and generateId; there is no layering, dependency injection, or module boundary beyond this one file, and the only external dependency is Node’s built-in crypto module. Its one notable design decision is an internal buffering strategy inside getRandomBytes: it pre-allocates a 4096-byte buffer via an async crypto.randomBytes call, tracks a bytesBufferIndex to slice consecutive id-sized chunks off that buffer, and falls back to a synchronous crypto.randomBytes call whenever the buffer is exhausted or not yet filled — the buffer-refill call is fire-and-forget and races the exposed synchronous generateId() call, so under sustained load some ids come from the buffer and some fall back to direct synchronous calls. Because the whole module is a single object with mutable instance state (bytesBuffer, bytesBufferIndex, sequenceNumber), changing the buffering strategy or id-shape logic in generateId affects the entire library’s behavior with nothing to isolate the blast radius.

Tech Stack The project is plain CommonJS JavaScript targeting Node.js ^4.5.0 || >= 5.9 per package.json engines, with the only dependency being Node’s built-in crypto module — there is no external runtime dependency, no bundler, no TypeScript, and no build step; the package is published to npm as-is with lib/base64id.js as its main entry. There is no CI configuration, linter config, or test runner declared anywhere in the repository.

Code Quality There are no test files anywhere in the repository, and no test script, framework, or CI workflow is configured — this is an unverified, un-linted single file with no automated coverage. Style is legacy ES5 (var-based, callback-driven async), naming is short and consistent (getRandomBytes, generateId, bytesBufferIndex), and error handling is essentially absent — asynchronous errors from crypto.randomBytes are silently ignored in the buffer-refill callback (function(err, bytes) {...} never inspects err), so a crypto failure during buffer refill would fail silently rather than surface.

API Design The public API is about as minimal as it gets: a single generateId() call with no configuration, no options object, and no async variant — arguably good ergonomics for its narrow purpose (a drop-in random-id generator) but leaving no way to configure id length, alphabet, or entropy source. Documentation is a four-line README with one install command and one usage snippet; there are no inline JSDoc comments beyond a couple of section-banner comments, and no comparison against more actively maintained alternatives like nanoid or uuid — the package is more notable for its historical role inside Engine.IO/Socket.IO than for any documented feature of its own API.