nanoid 3.3.16: customRandom

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.customRandom in pkg:npm/nanoid@3.3.16
Kind: HOW

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

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:0b6e8e4cdfc7b8ac2626fc388973cf394a4c8791c7416d56471bbc912d064bb9","contract":["customRandom creates an ID generator function using specified alphabet, default size, and random byte provider","generated IDs contain only characters from the specified alphabet","generator produces strings matching default size when called without arguments","generator produces strings of the requested size when passed an explicit positive size argument","generator produces deterministic output given a deterministic byte generator","customRandom integrates with nanoid standard random byte generator and urlAlphabet","customRandom works correctly across alphabets of varying lengths and helper wrappers"],"goal":"verify nanoid.customRandom in pkg:npm/nanoid@3.3.16","kind":"HOW","packages":["pkg:npm/nanoid@3.3.16"],"schemaVersion":1,"symbols":["nanoid.customRandom"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","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.16"],"schemaVersion":1,"subject":"pkg:npm/nanoid@3.3.16","symbols":["nanoid.customRandom"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-nanoid-customrandom",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-nanoid-customrandom",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "nanoid": "3.3.16"
      }
    },
    "node_modules/nanoid": {
      "version": "3.3.16",
      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.16.tgz",
      "integrity": "sha512-bzlKTyNJ7+LdGIIwy8ijFpIqEQIvafahV7eYykJ8Cvh42EdJeODoJ6gUJXpQJvej1BddH8OqTXZNE/KfbWAu8Q==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/ai"
        }
      ],
      "license": "MIT",
      "bin": {
        "nanoid": "bin/nanoid.cjs"
      },
      "engines": {
        "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
      }
    }
  }
}

{
  "name": "sample-nanoid-customrandom",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "nanoid": "3.3.16"
  }
}

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

import { customRandom, random, urlAlphabet } from 'nanoid';

/**
 * Creates a custom nanoid generator with the specified alphabet, size, and random byte provider.
 * @param {string} alphabet Characters to use in generated IDs.
 * @param {number} size Default length of generated IDs.
 * @param {function(number): Uint8Array} getRandom Byte generator function.
 * @returns {function(number=): string} ID generator function.
 */
export function createCustomGenerator(alphabet, size, getRandom) {
  return customRandom(alphabet, size, getRandom);
}

/**
 * Creates a deterministic nanoid generator using a custom PRNG / byte source.
 * @param {string} alphabet Characters to use in generated IDs.
 * @param {number} size Default length of generated IDs.
 * @param {function(number): Uint8Array} customByteSource Byte provider function.
 * @returns {function(number=): string} ID generator function.
 */
export function createDeterministicGenerator(alphabet, size, customByteSource) {
  return customRandom(alphabet, size, customByteSource);
}

export { customRandom, random, urlAlphabet };
export default customRandom;

import assert from 'node:assert/strict';
import { customRandom, random, urlAlphabet } from 'nanoid';
import { createCustomGenerator, createDeterministicGenerator } from '../src/index.mjs';

// 1. customRandom creates an ID generator function using specified alphabet, default size, and random byte provider
{
  const nanoid = customRandom('abcdef123456', 10, random);
  assert.equal(typeof nanoid, 'function', 'customRandom must return a generator function');

  const id = nanoid();
  assert.equal(typeof id, 'string', 'generator must return a string');
  assert.equal(id.length, 10, 'generator must return ID of default size 10');
}

// 2. generated IDs contain only characters from the specified alphabet
{
  const alphabet = 'abcABC123!_';
  const nanoid = customRandom(alphabet, 20, random);

  for (let i = 0; i < 50; i++) {
    const id = nanoid();
    for (const char of id) {
      assert.ok(alphabet.includes(char), `Character "${char}" must belong to alphabet`);
    }
  }
}

// 3. generator produces strings matching default size when called without arguments
{
  const sizes = [1, 5, 16, 21, 64];
  for (const size of sizes) {
    const nanoid = customRandom('0123456789', size, random);
    assert.equal(nanoid().length, size, `ID length must match configured default size ${size}`);
  }
}

// 4. generator produces strings of the requested size when passed an explicit positive size argument
{
  const nanoid = customRandom('abcdef012345', 12, random);
  assert.equal(nanoid().length, 12, 'default size must be 12');
  assert.equal(nanoid(1).length, 1, 'custom size override must be 1');
  assert.equal(nanoid(5).length, 5, 'custom size override must be 5');
  assert.equal(nanoid(30).length, 30, 'custom size override must be 30');
}

// 5. generator produces deterministic output given a deterministic byte generator
{
  let sequenceIndex = 0;
  const deterministicBytes = (step) => {
    const buffer = new Uint8Array(step);
    for (let i = 0; i < step; i++) {
      buffer[i] = sequenceIndex++;
    }
    return buffer;
  };

  const alphabet = 'abcdefghij';
  const nanoidDeterministic1 = customRandom(alphabet, 5, deterministicBytes);
  const output1 = nanoidDeterministic1();

  sequenceIndex = 0;
  const nanoidDeterministic2 = customRandom(alphabet, 5, deterministicBytes);
  const output2 = nanoidDeterministic2();

  assert.equal(output1, output2, 'deterministic byte source must produce identical outputs');
  assert.equal(output1.length, 5);
}

// 6. customRandom integrates with nanoid standard random byte generator and urlAlphabet
{
  const nanoid = customRandom(urlAlphabet, 21, random);
  const id1 = nanoid();
  const id2 = nanoid();
  assert.equal(id1.length, 21);
  assert.equal(id2.length, 21);
  assert.notEqual(id1, id2, 'sequential random IDs must differ');
  for (const ch of id1) {
    assert.ok(urlAlphabet.includes(ch));
  }
}

// 7. customRandom works correctly across alphabets of varying lengths and helper wrappers
{
  // Binary alphabet (length 2)
  const binaryGen = customRandom('01', 8, random);
  const binId = binaryGen();
  assert.match(binId, /^[01]{8}$/);

  // Hex alphabet (length 16)
  const hexGen = customRandom('0123456789abcdef', 16, random);
  const hexId = hexGen();
  assert.match(hexId, /^[0-9a-f]{16}$/);

  // Single character alphabet (length 1)
  const singleGen = customRandom('a', 5, random);
  assert.equal(singleGen(), 'aaaaa');

  // Helpers from index.mjs
  const helperCustom = createCustomGenerator('xyz', 6, random);
  assert.match(helperCustom(), /^[xyz]{6}$/);

  let counter = 0;
  const helperDeterministic = createDeterministicGenerator('0123456789', 4, (bytes) => {
    const b = new Uint8Array(bytes);
    b.fill(counter++);
    return b;
  });
  assert.equal(helperDeterministic().length, 4);
}

console.log('Contract tests passed successfully.');