compact-encoding 3.3.2: binary encode and decode primitives with compact-encoding

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: binary encode and decode primitives with compact-encoding
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/compact-encoding@3.3.2
Demonstrate these symbols/APIs:
  - decode
  - encode
  - string
  - 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:85844ee3b9940aa53726145fd2c670eccd1e9861f0e14dd3fd14ee674078be1e","contract":["encode serializes uint numbers into compact binary buffer and decode parses them back","encode serializes UTF-8 strings with length prefix into binary buffer and decode parses them back","preencode calculates required buffer size for multi-field records combining uint and string","state-based encode and decode sequentially pack and unpack composite structures into a single buffer","decode throws an error when reading uint or string from an empty or truncated buffer"],"goal":"binary encode and decode primitives with compact-encoding","kind":"HOW","packages":["pkg:npm/compact-encoding@3.3.2"],"schemaVersion":1,"symbols":["decode","encode","string","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":["decode","encode","string","uint"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-compact-encoding",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-compact-encoding",
      "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",
  "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": "binary encode and decode primitives with compact-encoding",
  "kind": "HOW",
  "packages": [
    "pkg:npm/compact-encoding@3.3.2"
  ],
  "symbols": [
    "decode",
    "encode",
    "string",
    "uint"
  ]
}

import c from 'compact-encoding';

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

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

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

/**
 * Encode a string to a buffer with UTF-8 length prefix.
 * @param {string} value
 * @returns {Uint8Array}
 */
export function encodeString(value) {
  return encode(string, value);
}

/**
 * Decode a string from a buffer.
 * @param {Uint8Array} buffer
 * @returns {string}
 */
export function decodeString(buffer) {
  return decode(string, buffer);
}

/**
 * Encode a structured record containing an ID and a name into a single binary buffer.
 * @param {{ id: number, name: string }} record
 * @returns {Uint8Array}
 */
export function encodeRecord(record) {
  const st = state();
  uint.preencode(st, record.id);
  string.preencode(st, record.name);
  st.buffer = Buffer.alloc(st.end);
  uint.encode(st, record.id);
  string.encode(st, record.name);
  return st.buffer;
}

/**
 * Decode a structured record containing an ID and a name from a binary buffer.
 * @param {Uint8Array} buffer
 * @returns {{ id: number, name: string }}
 */
export function decodeRecord(buffer) {
  const st = state(0, buffer.length, buffer);
  const id = uint.decode(st);
  const name = string.decode(st);
  return { id, name };
}

export default c;

import assert from 'node:assert/strict';
import c, {
  encode,
  decode,
  uint,
  string,
  state,
  encodeUint,
  decodeUint,
  encodeString,
  decodeString,
  encodeRecord,
  decodeRecord
} from '../src/index.mjs';

// 1. encode serializes uint numbers into compact binary buffer and decode parses them back
{
  const values = [0, 1, 42, 255, 65535, 1000000];
  for (const val of values) {
    const encoded = encode(uint, val);
    assert(encoded instanceof Uint8Array);
    const decoded = decode(uint, encoded);
    assert.equal(decoded, val);

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

// 2. encode serializes UTF-8 strings with length prefix into binary buffer and decode parses them back
{
  const testStrings = ['', 'hello', 'compact encoding test', '🚀 UTF-8 multibyte 🌟'];
  for (const str of testStrings) {
    const encoded = encode(string, str);
    assert(encoded instanceof Uint8Array);
    const decoded = decode(string, encoded);
    assert.equal(decoded, str);

    const helperEncoded = encodeString(str);
    const helperDecoded = decodeString(helperEncoded);
    assert.equal(helperDecoded, str);
  }
}

// 3. preencode calculates required buffer size for multi-field records combining uint and string
{
  const st = state();
  assert.equal(st.end, 0);

  uint.preencode(st, 42);
  assert.equal(st.end, 1);

  string.preencode(st, 'hello');
  assert.equal(st.end, 7);
}

// 4. state-based encode and decode sequentially pack and unpack composite structures into a single buffer
{
  const record = { id: 1337, name: 'sample payload' };
  const packed = encodeRecord(record);
  assert(packed instanceof Uint8Array);

  const unpacked = decodeRecord(packed);
  assert.deepEqual(unpacked, record);
}

// 5. decode throws an error when reading uint or string from an empty or truncated buffer
{
  assert.throws(() => {
    decode(uint, Buffer.alloc(0));
  }, /Out of bounds/);

  assert.throws(() => {
    decode(string, Buffer.from([100]));
  }, /Out of bounds/);
}

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