sqids 0.3.0: Sqids

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 Sqids in pkg:npm/sqids@0.3.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/sqids@0.3.0
Demonstrate these symbols/APIs:
  - Sqids

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:e6e541039cada1d8dd65477199a6ffc58eb231ce0d49b60350c6096f2e5b7569","contract":["Sqids instantiates with default options and custom options (alphabet, minLength, blocklist)","Sqids encodes an array of non-negative integers into a canonical ID string","Sqids decodes an ID string back to the original array of integers","Sqids encodes empty array to empty string and decodes empty string to empty array","Sqids enforces minLength by padding the generated ID string","Sqids throws error when encoding negative numbers or numbers exceeding MAX_SAFE_INTEGER","Sqids rejects alphabets with multibyte characters, length under 3, or non-unique characters","Sqids decodes invalid ID strings containing characters outside the alphabet to an empty array"],"goal":"verify Sqids in pkg:npm/sqids@0.3.0","kind":"HOW","packages":["pkg:npm/sqids@0.3.0"],"schemaVersion":1,"symbols":["Sqids"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/sqids@0.3.0"],"schemaVersion":1,"subject":"pkg:npm/sqids@0.3.0","symbols":["Sqids"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-sqids",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-sqids",
      "version": "1.0.0",
      "dependencies": {
        "sqids": "0.3.0"
      }
    },
    "node_modules/sqids": {
      "version": "0.3.0",
      "resolved": "https://registry.npmjs.org/sqids/-/sqids-0.3.0.tgz",
      "integrity": "sha512-lOQK1ucVg+W6n3FhRwwSeUijxe93b51Bfz5PMRMihVf1iVkl82ePQG7V5vwrhzB11v0NtsR25PSZRGiSomJaJw==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-sqids",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "dependencies": {
    "sqids": "0.3.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify Sqids in pkg:npm/sqids@0.3.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/sqids@0.3.0"
  ],
  "symbols": [
    "Sqids"
  ]
}

import assert from 'node:assert/strict';
import Sqids, { defaultOptions } from 'sqids';

// 1. Sqids instantiates with default options and custom options (alphabet, minLength, blocklist)
{
  const sqids = new Sqids();
  assert.ok(sqids instanceof Sqids, 'Sqids constructor should return a Sqids instance');
  assert.strictEqual(typeof defaultOptions.alphabet, 'string', 'defaultOptions.alphabet should be a string');
  assert.strictEqual(defaultOptions.minLength, 0, 'defaultOptions.minLength should be 0');
  assert.ok(defaultOptions.blocklist instanceof Set, 'defaultOptions.blocklist should be a Set');

  const customAlphabet = 'abcdefghijklmnopqrstuvwxyz0123456789';
  const customSqids = new Sqids({
    alphabet: customAlphabet,
    minLength: 10,
    blocklist: new Set(['customblock']),
  });
  assert.ok(customSqids instanceof Sqids, 'Sqids constructor with custom options should succeed');
}

// 2. Sqids encodes an array of non-negative integers into a canonical ID string
{
  const sqids = new Sqids();
  const id1 = sqids.encode([1, 2, 3]);
  assert.strictEqual(typeof id1, 'string', 'encode should return a string');
  assert.ok(id1.length > 0, 'encoded ID string should not be empty');

  // Single number encoding
  const id2 = sqids.encode([42]);
  assert.strictEqual(typeof id2, 'string', 'encode single number should return a string');

  // Different numbers produce different IDs
  const id3 = sqids.encode([1, 2, 4]);
  assert.notStrictEqual(id1, id3, 'different numbers should yield different IDs');
}

// 3. Sqids decodes an ID string back to the original array of integers
{
  const sqids = new Sqids();
  const original = [1, 2, 3];
  const id = sqids.encode(original);
  const decoded = sqids.decode(id);
  assert.deepStrictEqual(decoded, original, 'decode should reproduce original numbers');

  const numbersWithZero = [0, 99, 1000];
  assert.deepStrictEqual(sqids.decode(sqids.encode(numbersWithZero)), numbersWithZero, 'decoding round-trip including zero should match');
}

// 4. Sqids encodes empty array to empty string and decodes empty string to empty array
{
  const sqids = new Sqids();
  const emptyEncoded = sqids.encode([]);
  assert.strictEqual(emptyEncoded, '', 'encoding empty array should return empty string');
  const emptyDecoded = sqids.decode('');
  assert.deepStrictEqual(emptyDecoded, [], 'decoding empty string should return empty array');
}

// 5. Sqids enforces minLength by padding the generated ID string
{
  const minLength = 12;
  const sqids = new Sqids({ minLength });
  const id = sqids.encode([1, 2, 3]);
  assert.ok(id.length >= minLength, `encoded ID length (${id.length}) should be at least minLength (${minLength})`);
  assert.deepStrictEqual(sqids.decode(id), [1, 2, 3], 'padded ID should decode correctly back to original numbers');
}

// 6. Sqids throws error when encoding negative numbers or numbers exceeding MAX_SAFE_INTEGER
{
  const sqids = new Sqids();
  assert.throws(
    () => sqids.encode([-1]),
    /Encoding supports numbers between 0 and/,
    'encoding negative number should throw RangeError'
  );
  assert.throws(
    () => sqids.encode([Number.MAX_SAFE_INTEGER + 1]),
    /Encoding supports numbers between 0 and/,
    'encoding number > MAX_SAFE_INTEGER should throw RangeError'
  );
}

// 7. Sqids rejects alphabets with multibyte characters, length under 3, or non-unique characters
{
  assert.throws(
    () => new Sqids({ alphabet: 'ab' }),
    /Alphabet length must be at least 3/,
    'alphabet length < 3 should throw'
  );
  assert.throws(
    () => new Sqids({ alphabet: 'aabcdef' }),
    /Alphabet must contain unique characters/,
    'alphabet with duplicate characters should throw'
  );
  assert.throws(
    () => new Sqids({ alphabet: 'abc\u{1F680}def' }),
    /Alphabet cannot contain multibyte characters/,
    'alphabet with multibyte characters should throw'
  );
}

// 8. Sqids decodes invalid ID strings containing characters outside the alphabet to an empty array
{
  const sqids = new Sqids();
  const invalidDecoded = sqids.decode('!@#$%^&*()');
  assert.deepStrictEqual(invalidDecoded, [], 'decoding ID with characters outside the alphabet should return empty array');
}

console.log('All Sqids contract assertions passed successfully.');