string_decoder 1.1.1: StringDecoder

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 string_decoder.StringDecoder in pkg:npm/string_decoder@1.1.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/string_decoder@1.1.1
Demonstrate these symbols/APIs:
  - string_decoder.StringDecoder

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:76adfb6e9d8f2100198c64f508a27ab813e15153b67152f4a80d1532838669ea","contract":["assert StringDecoder decodes multi-byte UTF-8 sequences split across chunks preserving character boundaries","assert StringDecoder end flushes incomplete trailing multi-byte sequences as unicode replacement characters","assert StringDecoder end with buffer parameter decodes trailing buffer and flushes in a single call","assert StringDecoder supports hex, base64, and latin1 encodings correctly","assert decodeChunks and createDecoder helper functions correctly stream and decode multi-part buffer arrays"],"goal":"verify string_decoder.StringDecoder in pkg:npm/string_decoder@1.1.1","kind":"HOW","packages":["pkg:npm/string_decoder@1.1.1"],"schemaVersion":1,"symbols":["string_decoder.StringDecoder"]},"contractCommand":["node","test/contract.js"],"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/string_decoder@1.1.1"],"schemaVersion":1,"subject":"pkg:npm/string_decoder@1.1.1","symbols":["string_decoder.StringDecoder"],"verifierAdapter":"node-typescript@1"}

const { StringDecoder } = require('string_decoder');

/**
 * Creates a new StringDecoder instance for the given encoding.
 *
 * @param {string} [encoding='utf8'] - Character encoding (e.g., 'utf8', 'hex', 'base64', 'latin1').
 * @returns {StringDecoder} A new StringDecoder instance.
 */
function createDecoder(encoding) {
  return new StringDecoder(encoding);
}

/**
 * Decodes an array of Buffer chunks into a single concatenated string,
 * correctly handling multibyte sequences split across chunk boundaries.
 *
 * @param {Buffer[]} chunks - Array of Buffer chunks to decode.
 * @param {string} [encoding='utf8'] - Character encoding.
 * @returns {string} Fully decoded string.
 */
function decodeChunks(chunks, encoding) {
  const decoder = new StringDecoder(encoding);
  let result = '';
  for (const chunk of chunks) {
    result += decoder.write(chunk);
  }
  result += decoder.end();
  return result;
}

/**
 * Flushes any remaining bytes in a decoder instance, optionally appending a final buffer chunk.
 *
 * @param {StringDecoder} decoder - Active StringDecoder instance.
 * @param {Buffer} [trailingChunk] - Optional trailing buffer chunk.
 * @returns {string} Decoded remaining characters.
 */
function flushDecoder(decoder, trailingChunk) {
  return decoder.end(trailingChunk);
}

module.exports = {
  StringDecoder,
  createDecoder,
  decodeChunks,
  flushDecoder,
};

{
  "name": "sample-string-decoder",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-string-decoder",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "string_decoder": "1.1.1"
      }
    },
    "node_modules/safe-buffer": {
      "version": "5.1.2",
      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz",
      "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==",
      "license": "MIT"
    },
    "node_modules/string_decoder": {
      "version": "1.1.1",
      "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz",
      "integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==",
      "license": "MIT",
      "dependencies": {
        "safe-buffer": "~5.1.0"
      }
    }
  }
}

{
  "name": "sample-string-decoder",
  "version": "1.0.0",
  "description": "Clean-room verification of string_decoder.StringDecoder in string_decoder@1.1.1",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.js"
  },
  "license": "MIT-0",
  "dependencies": {
    "string_decoder": "1.1.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify string_decoder.StringDecoder in pkg:npm/string_decoder@1.1.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/string_decoder@1.1.1"
  ],
  "symbols": [
    "string_decoder.StringDecoder"
  ]
}

const assert = require('assert');
const { StringDecoder, createDecoder, decodeChunks, flushDecoder } = require('../index');

function runContractTests() {
  // 1. Multi-byte UTF-8 split across chunk boundaries
  {
    const decoder = new StringDecoder('utf8');
    const chunk1 = decoder.write(Buffer.from([0xed, 0x95]));
    assert.strictEqual(chunk1, '', 'Incomplete 3-byte sequence should buffer without emitting text');

    const chunk2 = decoder.write(Buffer.from([0x9c, 0xf0, 0x9f]));
    assert.strictEqual(chunk2, '한', 'Completing 3-byte sequence emits character; incomplete 4-byte buffers');

    const chunk3 = decoder.write(Buffer.from([0x9a, 0x80]));
    assert.strictEqual(chunk3, '🚀', 'Completing 4-byte emoji sequence emits character');

    const end = decoder.end();
    assert.strictEqual(end, '', 'Clean stream flush yields empty string');
  }

  // 2. Incomplete trailing multibyte sequence flushed on end() produces replacement character \ufffd
  {
    const decoder = new StringDecoder('utf8');
    const written = decoder.write(Buffer.from([0xed, 0x95]));
    assert.strictEqual(written, '');
    const flushed = decoder.end();
    assert.strictEqual(flushed, '\ufffd', 'Incomplete multibyte sequence at stream end emits replacement character');
  }

  // 3. end(buffer) decodes final chunk and flushes in one operation
  {
    const decoder = new StringDecoder('utf8');
    decoder.write(Buffer.from([0xed]));
    const finalResult = decoder.end(Buffer.from([0x95, 0x9c]));
    assert.strictEqual(finalResult, '한', 'end(buffer) should complete buffered sequence and return character');
  }

  // 4. Hex, base64, and latin1 encodings
  {
    const hexDecoder = new StringDecoder('hex');
    const hex1 = hexDecoder.write(Buffer.from([0xde, 0xad]));
    const hex2 = hexDecoder.write(Buffer.from([0xbe, 0xef]));
    assert.strictEqual(hex1 + hex2 + hexDecoder.end(), 'deadbeef', 'Hex decoder should produce continuous hex string');

    const b64Decoder = new StringDecoder('base64');
    const b64_1 = b64Decoder.write(Buffer.from('Hello, '));
    const b64_2 = b64Decoder.write(Buffer.from('World!'));
    assert.strictEqual(b64_1 + b64_2 + b64Decoder.end(), 'SGVsbG8sIFdvcmxkIQ==', 'Base64 decoder should produce valid base64');

    const latinDecoder = new StringDecoder('latin1');
    const lat1 = latinDecoder.write(Buffer.from([0xe9, 0xe0]));
    assert.strictEqual(lat1 + latinDecoder.end(), 'éà', 'Latin1 decoder should decode high-order bytes directly');
  }

  // 5. decodeChunks and createDecoder helper functions
  {
    const decoder = createDecoder('utf8');
    assert.ok(decoder instanceof StringDecoder, 'createDecoder must return a StringDecoder instance');

    const chunks = [
      Buffer.from([0xea, 0xb0]),
      Buffer.from([0x80, 0xeb]),
      Buffer.from([0x82, 0x98, 0xeb, 0x8b]),
      Buffer.from([0xa4])
    ];
    const decoded = decodeChunks(chunks, 'utf8');
    assert.strictEqual(decoded, '가나다', 'decodeChunks should properly assemble split multibyte chunks');

    const partialDec = createDecoder('utf8');
    partialDec.write(Buffer.from([0xea, 0xb0]));
    const trailingFlushed = flushDecoder(partialDec, Buffer.from([0x80]));
    assert.strictEqual(trailingFlushed, '가', 'flushDecoder should flush trailing buffer');
  }

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

runContractTests();