sqids 0.3.0

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

Use EXACTLY these public packages and versions:
  - pkg:npm/sqids@0.3.0

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:d73d9e5b630e4b27f9c9cd785336783aaf0c2a25c86d24d616f82cdea6d6be09","contract":["Sqids instantiates with default options and custom options","Sqids encodes an array of non-negative integers into an 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"],"goal":"verify pkg:npm/sqids@0.3.0","kind":"HOW","packages":["pkg:npm/sqids@0.3.0"],"schemaVersion":1},"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","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",
  "private": true,
  "description": "Clean-room verification of sqids ID encoding and decoding utilities",
  "type": "module",
  "main": "src/index.js",
  "dependencies": {
    "sqids": "0.3.0"
  }
}

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

import Sqids, { defaultOptions } from 'sqids';

/**
 * Creates a new Sqids instance with optional configuration.
 * @param {object} [options]
 * @param {string} [options.alphabet]
 * @param {number} [options.minLength]
 * @param {string[]|Set<string>} [options.blocklist]
 * @returns {Sqids}
 */
export function createSqids(options) {
  return new Sqids(options);
}

/**
 * Encodes an array of numbers into a Sqids ID.
 * @param {number[]} numbers
 * @param {object} [options]
 * @returns {string}
 */
export function encodeNumbers(numbers, options) {
  const instance = new Sqids(options);
  return instance.encode(numbers);
}

/**
 * Decodes a Sqids ID into an array of numbers.
 * @param {string} id
 * @param {object} [options]
 * @returns {number[]}
 */
export function decodeId(id, options) {
  const instance = new Sqids(options);
  return instance.decode(id);
}

export { Sqids, defaultOptions };
export default Sqids;

import assert from 'node:assert/strict';
import Sqids, {
  createSqids,
  encodeNumbers,
  decodeId,
  defaultOptions,
} from '../src/index.js';

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

const customSqids = createSqids({
  alphabet: 'abcdefghijklmnopqrstuvwxyz0123456789',
  minLength: 8,
});
assert.ok(customSqids instanceof Sqids, 'customSqids should be a Sqids instance');

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

const helperEncoded = encodeNumbers([10, 20, 30]);
assert.strictEqual(typeof helperEncoded, 'string', 'helper encodeNumbers should return a string');
assert.ok(helperEncoded.length > 0, 'helper encoded string should not be empty');

// 3. Sqids decodes an ID string back to the original array of integers
const decoded = defaultSqids.decode(encoded);
assert.deepStrictEqual(decoded, sampleNumbers, 'decode should reproduce the original array');

const helperDecoded = decodeId(helperEncoded);
assert.deepStrictEqual(helperDecoded, [10, 20, 30], 'helper decodeId should reproduce original numbers');

// Invalid characters in ID return empty array
const invalidDecoded = defaultSqids.decode('!@#$%^&*()');
assert.deepStrictEqual(invalidDecoded, [], 'decoding string with characters outside alphabet returns []');

// 4. Sqids encodes empty array to empty string and decodes empty string to empty array
assert.strictEqual(defaultSqids.encode([]), '', 'encoding empty array returns empty string');
assert.deepStrictEqual(defaultSqids.decode(''), [], 'decoding empty string returns empty array');

// 5. Sqids enforces minLength by padding the generated ID string
const paddedSqids = createSqids({ minLength: 12 });
const paddedId = paddedSqids.encode([1, 2, 3]);
assert.ok(paddedId.length >= 12, 'encoded ID length must satisfy minLength >= 12');
assert.deepStrictEqual(paddedSqids.decode(paddedId), [1, 2, 3], 'padded ID must decode back correctly');

// 6. Sqids throws error when encoding negative numbers or numbers exceeding MAX_SAFE_INTEGER
assert.throws(
  () => defaultSqids.encode([-1]),
  /Encoding supports numbers between 0 and/,
  'encoding negative number should throw range error'
);

assert.throws(
  () => defaultSqids.encode([Number.MAX_SAFE_INTEGER + 1]),
  /Encoding supports numbers between 0 and/,
  'encoding number > MAX_SAFE_INTEGER should throw range error'
);

// 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 shorter than 3 characters 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 character should throw'
);

console.log('All sqids contract tests passed successfully.');