nanoid 3.3.17: random

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify nanoid.random in pkg:npm/nanoid@3.3.17
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/nanoid@3.3.17
Demonstrate these symbols/APIs:
  - nanoid.random

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:77f71e332ed0228a9a80763968f5e900f7342d7a16336530d77a99daee005ba5","contract":["assert random is a function exported by nanoid","assert random returns a Uint8Array of the requested byte length","assert random returns an empty Uint8Array when requested length is 0","assert random generates cryptographically distinct byte sequences across consecutive calls","assert random outputs bytes spanning the full 0-255 uint8 range over multiple calls","assert random functions as a compatible RNG source for customRandom"],"goal":"verify nanoid.random in pkg:npm/nanoid@3.3.17","kind":"HOW","packages":["pkg:npm/nanoid@3.3.17"],"schemaVersion":1,"symbols":["nanoid.random"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/nanoid@3.3.17"],"schemaVersion":1,"subject":"pkg:npm/nanoid@3.3.17","symbols":["nanoid.random"],"verifierAdapter":"node-typescript@1"}

import { random, customRandom } from 'nanoid';

/**
 * Generate cryptographically secure random bytes of specified size.
 * @param {number} bytes
 * @returns {Uint8Array}
 */
export function generateRandomBytes(bytes) {
  return random(bytes);
}

/**
 * Create a custom ID generator backed by nanoid's random byte generator.
 * @param {string} alphabet
 * @param {number} size
 * @returns {() => string}
 */
export function createCustomIdGenerator(alphabet, size) {
  return customRandom(alphabet, size, random);
}

export { random };

{
  "name": "sample-nanoid-random",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-nanoid-random",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "nanoid": "3.3.17"
      }
    },
    "node_modules/nanoid": {
      "version": "3.3.17",
      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.17.tgz",
      "integrity": "sha512-xQLf0A3HOMlgHq0n247/LRuAOYmB7dXJ/DvAxGvsSBij45XtBSmQycu+F8ODbHwns/XyFZagyL1+J0Offw1E0g==",
      "license": "MIT",
      "bin": {
        "nanoid": "bin/nanoid.cjs"
      },
      "engines": {
        "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
      }
    }
  }
}

{
  "name": "sample-nanoid-random",
  "version": "1.0.0",
  "description": "Demonstrate cryptographic byte generation with nanoid.random in pkg:npm/nanoid@3.3.17",
  "main": "index.mjs",
  "type": "module",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "nanoid": "3.3.17"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify nanoid.random in pkg:npm/nanoid@3.3.17",
  "kind": "HOW",
  "packages": [
    "pkg:npm/nanoid@3.3.17"
  ],
  "symbols": [
    "nanoid.random"
  ]
}

import assert from 'node:assert/strict';
import { random, customRandom } from 'nanoid';
import { generateRandomBytes, createCustomIdGenerator } from '../index.mjs';

// 1. assert random is a function exported by nanoid
{
  assert.equal(typeof random, 'function', 'random must be exported as a function');
  assert.equal(typeof generateRandomBytes, 'function', 'generateRandomBytes helper must be a function');
}

// 2. assert random returns a Uint8Array of the requested byte length
{
  const lengths = [1, 8, 16, 32, 64, 128];
  for (const len of lengths) {
    const bytes = random(len);
    assert.ok(bytes instanceof Uint8Array, 'random must return a Uint8Array');
    assert.equal(bytes.length, len, `random(${len}) must return Uint8Array with length ${len}`);
    assert.equal(bytes.byteLength, len, `random(${len}) byteLength must match length`);
  }
}

// 3. assert random returns an empty Uint8Array when requested length is 0
{
  const emptyBytes = random(0);
  assert.ok(emptyBytes instanceof Uint8Array, 'random(0) must return a Uint8Array');
  assert.equal(emptyBytes.length, 0, 'random(0) length must be 0');
}

// 4. assert random generates cryptographically distinct byte sequences across consecutive calls
{
  const samples = new Set();
  const iterations = 50;
  for (let i = 0; i < iterations; i++) {
    const bytes = random(16);
    const hex = Buffer.from(bytes).toString('hex');
    samples.add(hex);
  }
  assert.equal(samples.size, iterations, 'All consecutive random byte sequences of length 16 must be unique');
}

// 5. assert random outputs bytes spanning the full 0-255 uint8 range over multiple calls
{
  const seenBytes = new Set();
  // Drawing 1000 chunks of 32 bytes (32,000 bytes total) gives near-certain coverage of 0-255
  for (let i = 0; i < 1000; i++) {
    const chunk = random(32);
    for (let j = 0; j < chunk.length; j++) {
      seenBytes.add(chunk[j]);
    }
  }
  assert.equal(seenBytes.size, 256, 'random generator should cover all 256 byte values');
}

// 6. assert random functions as a compatible RNG source for customRandom
{
  const alphabet = '0123456789abcdef';
  const size = 16;
  const customGen = customRandom(alphabet, size, random);
  const id1 = customGen();
  const id2 = customGen();

  assert.equal(typeof id1, 'string', 'customRandom with random must generate a string');
  assert.equal(id1.length, size, 'Generated id length must match requested size');
  assert.notEqual(id1, id2, 'Consecutive generated IDs should be distinct');
  for (const ch of id1) {
    assert.ok(alphabet.includes(ch), `Character "${ch}" must belong to custom alphabet`);
  }

  const helperGen = createCustomIdGenerator('ABCDEF', 8);
  const helperId = helperGen();
  assert.equal(helperId.length, 8);
  for (const ch of helperId) {
    assert.ok('ABCDEF'.includes(ch));
  }
}

console.log('CONTRACT PASS: nanoid.random verified successfully');