engine.io-parser 5.2.3: decodePacket, decodePayload, encodePacket

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/engine.io-parser@5.2.3
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/engine.io-parser@5.2.3
Demonstrate these symbols/APIs:
  - decodePacket
  - decodePayload
  - encodePacket
  - encodePayload

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:3deb95755df4e195f4d9ec571fa67d991069a1eb7663bf110a5c7c3fe15e7de0","contract":["encodePacket encodes text packets with numeric type prefixes","encodePacket encodes binary payloads as raw Buffer when supportsBinary is true, and as base64 string with 'b' prefix when false","decodePacket decodes string packets into packet objects with type and payload data, returning error packet on invalid type","decodePacket decodes base64 string packets and raw binary Buffers into message packets with binary data","encodePayload bundles multiple packets into a record-separator delimited string, forcing base64 for binary packets","decodePayload parses record-separator delimited payload strings into an array of decoded packet objects"],"goal":"verify pkg:npm/engine.io-parser@5.2.3","kind":"HOW","packages":["pkg:npm/engine.io-parser@5.2.3"],"schemaVersion":1,"symbols":["decodePacket","decodePayload","encodePacket","encodePayload"]},"contractCommand":["node","test/contract.js"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/engine.io-parser@5.2.3"],"schemaVersion":1,"subject":"pkg:npm/engine.io-parser@5.2.3","symbols":["decodePacket","decodePayload","encodePacket","encodePayload"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-engine-io-parser",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-engine-io-parser",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "engine.io-parser": "5.2.3"
      }
    },
    "node_modules/engine.io-parser": {
      "version": "5.2.3",
      "resolved": "https://registry.npmjs.org/engine.io-parser/-/engine.io-parser-5.2.3.tgz",
      "integrity": "sha512-HqD3yTBfnBxIrbnM1DoD6Pcq8NECnh8d4As1Qgh0z5Gg3jRRIqijury0CL3ghu/edArpUYiYqQiDUQBIs4np3Q==",
      "license": "MIT",
      "engines": {
        "node": ">=10.0.0"
      }
    }
  }
}

{
  "name": "sample-engine-io-parser",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification sample for engine.io-parser",
  "main": "src/index.js",
  "scripts": {
    "test": "node test/contract.js"
  },
  "dependencies": {
    "engine.io-parser": "5.2.3"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/engine.io-parser@5.2.3",
  "kind": "HOW",
  "packages": [
    "pkg:npm/engine.io-parser@5.2.3"
  ],
  "symbols": [
    "decodePacket",
    "decodePayload",
    "encodePacket",
    "encodePayload"
  ]
}

const {
  protocol,
  encodePacket,
  decodePacket,
  encodePayload,
  decodePayload,
} = require('engine.io-parser');

/**
 * Encodes a single packet asynchronously using a Promise wrapper.
 * @param {{ type: string, data?: any }} packet
 * @param {boolean} [supportsBinary=true]
 * @returns {Promise<string | Buffer | ArrayBuffer>}
 */
function encodePacketAsync(packet, supportsBinary = true) {
  return new Promise((resolve) => {
    encodePacket(packet, supportsBinary, (encoded) => {
      resolve(encoded);
    });
  });
}

/**
 * Encodes an array of packets into a single payload string asynchronously.
 * @param {Array<{ type: string, data?: any }>} packets
 * @returns {Promise<string>}
 */
function encodePayloadAsync(packets) {
  return new Promise((resolve) => {
    encodePayload(packets, (encoded) => {
      resolve(encoded);
    });
  });
}

/**
 * Decodes a single encoded packet string or buffer.
 * @param {string | Buffer | ArrayBuffer} encodedPacket
 * @param {string} [binaryType]
 * @returns {{ type: string, data?: any }}
 */
function parsePacket(encodedPacket, binaryType) {
  return decodePacket(encodedPacket, binaryType);
}

/**
 * Decodes a payload string into an array of packet objects.
 * @param {string} encodedPayload
 * @param {string} [binaryType]
 * @returns {Array<{ type: string, data?: any }>}
 */
function parsePayload(encodedPayload, binaryType) {
  return decodePayload(encodedPayload, binaryType);
}

module.exports = {
  protocol,
  encodePacket,
  decodePacket,
  encodePayload,
  decodePayload,
  encodePacketAsync,
  encodePayloadAsync,
  parsePacket,
  parsePayload,
};

const assert = require('node:assert');
const {
  protocol,
  encodePacket,
  decodePacket,
  encodePayload,
  decodePayload,
  encodePacketAsync,
  encodePayloadAsync,
  parsePacket,
  parsePayload,
} = require('../src/index.js');

async function runContractTests() {
  // Protocol check
  assert.strictEqual(protocol, 4, 'Engine.IO protocol version must be 4');

  // Contract 1: encodePacket encodes text packets with numeric type prefixes
  const textCases = [
    { type: 'open', data: '{"sid":"abc","upgrades":[],"pingInterval":25000,"pingTimeout":20000}', prefix: '0' },
    { type: 'close', data: undefined, prefix: '1' },
    { type: 'ping', data: 'probe', prefix: '2' },
    { type: 'pong', data: 'probe', prefix: '3' },
    { type: 'message', data: 'hello CodeSampleX', prefix: '4' },
    { type: 'upgrade', data: undefined, prefix: '5' },
    { type: 'noop', data: undefined, prefix: '6' },
  ];

  for (const item of textCases) {
    const packet = item.data !== undefined ? { type: item.type, data: item.data } : { type: item.type };
    const encoded = await encodePacketAsync(packet, true);
    assert.strictEqual(typeof encoded, 'string');
    assert.strictEqual(encoded.charAt(0), item.prefix, `Packet type ${item.type} should have prefix ${item.prefix}`);
    if (item.data !== undefined) {
      assert.strictEqual(encoded.substring(1), item.data);
    }
  }

  // Contract 2: encodePacket encodes binary payloads as raw Buffer when supportsBinary is true, and as base64 string with 'b' prefix when false
  const binaryBuffer = Buffer.from([10, 20, 30, 40, 50]);
  const encodedRaw = await encodePacketAsync({ type: 'message', data: binaryBuffer }, true);
  assert(Buffer.isBuffer(encodedRaw) || encodedRaw instanceof Uint8Array, 'Binary with supportsBinary=true should return buffer');
  assert.deepStrictEqual(Buffer.from(encodedRaw), binaryBuffer);

  const encodedBase64 = await encodePacketAsync({ type: 'message', data: binaryBuffer }, false);
  assert.strictEqual(typeof encodedBase64, 'string');
  assert.strictEqual(encodedBase64.charAt(0), 'b', 'Base64 binary packet must start with prefix "b"');
  assert.strictEqual(encodedBase64.substring(1), binaryBuffer.toString('base64'));

  // Contract 3: decodePacket decodes string packets into packet objects with type and payload data, returning error packet on invalid type
  const decodedOpen = parsePacket('0{"sid":"xyz"}');
  assert.deepStrictEqual(decodedOpen, { type: 'open', data: '{"sid":"xyz"}' });

  const decodedClose = parsePacket('1');
  assert.deepStrictEqual(decodedClose, { type: 'close' });

  const decodedPing = parsePacket('2probe');
  assert.deepStrictEqual(decodedPing, { type: 'ping', data: 'probe' });

  const decodedPong = parsePacket('3probe');
  assert.deepStrictEqual(decodedPong, { type: 'pong', data: 'probe' });

  const decodedMessage = parsePacket('4test message');
  assert.deepStrictEqual(decodedMessage, { type: 'message', data: 'test message' });

  const decodedUpgrade = parsePacket('5');
  assert.deepStrictEqual(decodedUpgrade, { type: 'upgrade' });

  const decodedNoop = parsePacket('6');
  assert.deepStrictEqual(decodedNoop, { type: 'noop' });

  const decodedInvalid = parsePacket('9invalid_packet');
  assert.deepStrictEqual(decodedInvalid, { type: 'error', data: 'parser error' });

  // Contract 4: decodePacket decodes base64 string packets and raw binary Buffers into message packets with binary data
  const base64Packet = 'b' + binaryBuffer.toString('base64');
  const decodedFromBase64 = parsePacket(base64Packet, 'nodebuffer');
  assert.strictEqual(decodedFromBase64.type, 'message');
  assert.deepStrictEqual(Buffer.from(decodedFromBase64.data), binaryBuffer);

  const decodedFromRaw = parsePacket(binaryBuffer, 'nodebuffer');
  assert.strictEqual(decodedFromRaw.type, 'message');
  assert.deepStrictEqual(Buffer.from(decodedFromRaw.data), binaryBuffer);

  // Contract 5: encodePayload bundles multiple packets into a record-separator delimited string, forcing base64 for binary packets
  const payloadPackets = [
    { type: 'ping', data: 'probe' },
    { type: 'message', data: 'hello' },
    { type: 'message', data: binaryBuffer },
  ];
  const encodedPayload = await encodePayloadAsync(payloadPackets);
  assert.strictEqual(typeof encodedPayload, 'string');
  const separator = String.fromCharCode(30);
  const parts = encodedPayload.split(separator);
  assert.strictEqual(parts.length, 3);
  assert.strictEqual(parts[0], '2probe');
  assert.strictEqual(parts[1], '4hello');
  assert.strictEqual(parts[2], 'b' + binaryBuffer.toString('base64'));

  // Contract 6: decodePayload parses record-separator delimited payload strings into an array of decoded packet objects
  const decodedPayloadList = parsePayload(encodedPayload, 'nodebuffer');
  assert.strictEqual(decodedPayloadList.length, 3);
  assert.deepStrictEqual(decodedPayloadList[0], { type: 'ping', data: 'probe' });
  assert.deepStrictEqual(decodedPayloadList[1], { type: 'message', data: 'hello' });
  assert.strictEqual(decodedPayloadList[2].type, 'message');
  assert.deepStrictEqual(Buffer.from(decodedPayloadList[2].data), binaryBuffer);

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

runContractTests().catch((err) => {
  console.error('Contract test failure:', err);
  process.exit(1);
});