compact-encoding 3.3.2: c.uint

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 c.uint in pkg:npm/compact-encoding@3.3.2
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/compact-encoding@3.3.2
Demonstrate these symbols/APIs:
  - c.uint

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:e854b3a94dbd2b5f02b21c0ac93dbf1a62e307b3c297d04af8fefce9dd0532c9","contract":["c.uint preencode calculates variable byte lengths based on unsigned integer value ranges","c.uint encode serializes single-byte unsigned integers under 253 and decode recovers them","c.uint encode serializes 2-byte unsigned integers up to 65535 with 0xfd tag and decode recovers them","c.uint encode serializes 4-byte unsigned integers up to 4294967295 with 0xfe tag and decode recovers them","c.uint encode serializes large integers up to MAX_SAFE_INTEGER with 0xff tag and decode recovers them","c.uint state-based encode and decode sequentially pack and unpack multiple unsigned integers","c.uint decode throws an Out of bounds error on empty or truncated buffers"],"goal":"verify c.uint in pkg:npm/compact-encoding@3.3.2","kind":"HOW","packages":["pkg:npm/compact-encoding@3.3.2"],"schemaVersion":1,"symbols":["c.uint"]},"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/compact-encoding@3.3.2"],"schemaVersion":1,"subject":"pkg:npm/compact-encoding@3.3.2","symbols":["c.uint"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-compact-encoding-uint",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-compact-encoding-uint",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "compact-encoding": "3.3.2"
      }
    },
    "node_modules/b4a": {
      "version": "1.8.1",
      "resolved": "https://registry.npmjs.org/b4a/-/b4a-1.8.1.tgz",
      "integrity": "sha512-aiqre1Nr0B/6DgE2N5vwTc+2/oQZ4Wh1t4NznYY4E00y8LCt6NqdRv81so00oo27D8MVKTpUa/MwUUtBLXCoDw==",
      "license": "Apache-2.0",
      "peerDependencies": {
        "react-native-b4a": "*"
      },
      "peerDependenciesMeta": {
        "react-native-b4a": {
          "optional": true
        }
      }
    },
    "node_modules/compact-encoding": {
      "version": "3.3.2",
      "resolved": "https://registry.npmjs.org/compact-encoding/-/compact-encoding-3.3.2.tgz",
      "integrity": "sha512-bgZ84oVSzjQmVHXBYWON+wQUkdVflrr8fM5+0X6UwQHZyzolsGIkdsjNK3vLLn22dhdASGFz5mS6Lf7rfrPdlg==",
      "license": "Apache-2.0",
      "dependencies": {
        "b4a": "^1.3.0"
      }
    }
  }
}

{
  "name": "sample-compact-encoding-uint",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "compact-encoding": "3.3.2"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify c.uint in pkg:npm/compact-encoding@3.3.2",
  "kind": "HOW",
  "packages": [
    "pkg:npm/compact-encoding@3.3.2"
  ],
  "symbols": [
    "c.uint"
  ]
}

import c from 'compact-encoding';

export const { encode, decode, state, uint } = c;

/**
 * Encode an unsigned integer to a compact buffer using c.uint.
 * @param {number} value
 * @returns {Uint8Array}
 */
export function encodeUint(value) {
  return c.encode(c.uint, value);
}

/**
 * Decode an unsigned integer from a buffer using c.uint.
 * @param {Uint8Array} buffer
 * @returns {number}
 */
export function decodeUint(buffer) {
  return c.decode(c.uint, buffer);
}

/**
 * Pre-calculate byte size required for an unsigned integer.
 * @param {number} value
 * @returns {number}
 */
export function getUintSize(value) {
  const st = c.state();
  c.uint.preencode(st, value);
  return st.end;
}

/**
 * Sequentially encode multiple unsigned integers into a single buffer.
 * @param {number[]} numbers
 * @returns {Uint8Array}
 */
export function encodeUintSequence(numbers) {
  const st = c.state();
  for (const num of numbers) {
    c.uint.preencode(st, num);
  }
  st.buffer = Buffer.alloc(st.end);
  for (const num of numbers) {
    c.uint.encode(st, num);
  }
  return st.buffer;
}

/**
 * Sequentially decode multiple unsigned integers from a buffer.
 * @param {Uint8Array} buffer
 * @param {number} count
 * @returns {number[]}
 */
export function decodeUintSequence(buffer, count) {
  const st = c.state(0, buffer.length, buffer);
  const result = [];
  for (let i = 0; i < count; i++) {
    result.push(c.uint.decode(st));
  }
  return result;
}

export default c;

import assert from 'node:assert/strict';
import c, {
  encode,
  decode,
  state,
  uint,
  encodeUint,
  decodeUint,
  getUintSize,
  encodeUintSequence,
  decodeUintSequence
} from '../src/index.mjs';

// 1. c.uint preencode calculates variable byte lengths based on unsigned integer value ranges
{
  assert.equal(getUintSize(0), 1);
  assert.equal(getUintSize(252), 1);
  assert.equal(getUintSize(253), 3);
  assert.equal(getUintSize(65535), 3);
  assert.equal(getUintSize(65536), 5);
  assert.equal(getUintSize(4294967295), 5);
  assert.equal(getUintSize(Number.MAX_SAFE_INTEGER), 9);
}

// 2. c.uint encode serializes single-byte unsigned integers under 253 and decode recovers them
{
  const testValues = [0, 1, 7, 42, 127, 200, 252];
  for (const val of testValues) {
    const direct = encode(uint, val);
    assert(direct instanceof Uint8Array);
    assert.equal(direct.length, 1);
    assert.equal(direct[0], val);
    assert.equal(decode(uint, direct), val);

    const helper = encodeUint(val);
    assert.equal(decodeUint(helper), val);
  }
}

// 3. c.uint encode serializes 2-byte unsigned integers up to 65535 with 0xfd tag and decode recovers them
{
  const testValues = [253, 254, 1000, 32768, 65535];
  for (const val of testValues) {
    const direct = encode(uint, val);
    assert(direct instanceof Uint8Array);
    assert.equal(direct.length, 3);
    assert.equal(direct[0], 0xfd);
    assert.equal(decode(uint, direct), val);

    const helper = encodeUint(val);
    assert.equal(decodeUint(helper), val);
  }
}

// 4. c.uint encode serializes 4-byte unsigned integers up to 4294967295 with 0xfe tag and decode recovers them
{
  const testValues = [65536, 100000, 16777215, 4294967295];
  for (const val of testValues) {
    const direct = encode(uint, val);
    assert(direct instanceof Uint8Array);
    assert.equal(direct.length, 5);
    assert.equal(direct[0], 0xfe);
    assert.equal(decode(uint, direct), val);

    const helper = encodeUint(val);
    assert.equal(decodeUint(helper), val);
  }
}

// 5. c.uint encode serializes large integers up to MAX_SAFE_INTEGER with 0xff tag and decode recovers them
{
  const testValues = [4294967296, 1000000000000, Number.MAX_SAFE_INTEGER];
  for (const val of testValues) {
    const direct = encode(uint, val);
    assert(direct instanceof Uint8Array);
    assert.equal(direct.length, 9);
    assert.equal(direct[0], 0xff);
    assert.equal(decode(uint, direct), val);

    const helper = encodeUint(val);
    assert.equal(decodeUint(helper), val);
  }
}

// 6. c.uint state-based encode and decode sequentially pack and unpack multiple unsigned integers
{
  const sequence = [0, 42, 253, 65536, 4294967296];
  const packed = encodeUintSequence(sequence);
  assert(packed instanceof Uint8Array);
  assert.equal(packed.length, 1 + 1 + 3 + 5 + 9);

  const unpacked = decodeUintSequence(packed, sequence.length);
  assert.deepEqual(unpacked, sequence);
}

// 7. c.uint decode throws an Out of bounds error on empty or truncated buffers
{
  assert.throws(() => {
    decode(uint, Buffer.alloc(0));
  }, /Out of bounds/);

  assert.throws(() => {
    decode(uint, Buffer.from([0xfd, 0x01]));
  }, /Out of bounds/);

  assert.throws(() => {
    decode(uint, Buffer.from([0xfe, 0x01, 0x02]));
  }, /Out of bounds/);
}

console.log('Contract assertions passed.');