string_decoder 1.1.1

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/string_decoder@1.1.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/string_decoder@1.1.1

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:771db1497064592311d05c8d8eedc877d824a84633a8a41d156031431407978a","contract":["StringDecoder() instantiates with default utf8 encoding and supports custom encodings like latin1, base64, and hex","StringDecoder.prototype.write() buffers incomplete multi-byte UTF-8 sequences across chunk boundaries","StringDecoder.prototype.write() decodes multi-byte UTF-8 sequences including 4-byte emojis when completed","StringDecoder.prototype.write() returns complete ASCII and UTF-8 strings immediately","StringDecoder.prototype.end() flushes trailing incomplete bytes as Unicode replacement characters","StringDecoder.prototype.end(buffer) decodes the final buffer chunk and flushes the decoder","StringDecoder.prototype.write() and end() decode base64 across buffer boundaries","StringDecoder.prototype.write() and end() decode hex across buffer boundaries"],"goal":"verify pkg:npm/string_decoder@1.1.1","kind":"HOW","packages":["pkg:npm/string_decoder@1.1.1"],"schemaVersion":1,"symbols":["StringDecoder","StringDecoder.prototype.write","StringDecoder.prototype.end"]},"contractCommand":["node","test/contract.cjs"],"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/string_decoder@1.1.1"],"schemaVersion":1,"subject":"pkg:npm/string_decoder@1.1.1","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-string-decoder",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-string-decoder",
      "version": "1.0.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",
  "private": true,
  "description": "Clean-room verification for string_decoder",
  "main": "src/index.js",
  "dependencies": {
    "string_decoder": "1.1.1"
  }
}

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

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

/**
 * Creates a new StringDecoder instance with the specified encoding.
 * @param {string} [encoding='utf8'] - The character encoding to use.
 * @returns {StringDecoder} A new StringDecoder instance.
 */
function createDecoder(encoding) {
  return new StringDecoder(encoding);
}

/**
 * Decodes a buffer or array of buffers sequentially using StringDecoder.
 * @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 (let i = 0; i < chunks.length; i++) {
    result += decoder.write(chunks[i]);
  }
  result += decoder.end();
  return result;
}

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

const assert = require('node:assert');
const { StringDecoder } = require('string_decoder');
const { createDecoder, decodeChunks } = require('../src/index.js');

// 1. StringDecoder() instantiates with default utf8 encoding and supports custom encodings like latin1, base64, and hex
const utf8Decoder = new StringDecoder();
assert.strictEqual(utf8Decoder.encoding, 'utf8');

const helperUtf8 = createDecoder();
assert.strictEqual(helperUtf8.encoding, 'utf8');

const latin1Decoder = new StringDecoder('latin1');
assert.strictEqual(latin1Decoder.encoding, 'latin1');

const base64Decoder = new StringDecoder('base64');
assert.strictEqual(base64Decoder.encoding, 'base64');

const hexDecoder = new StringDecoder('hex');
assert.strictEqual(hexDecoder.encoding, 'hex');

// 2. StringDecoder.prototype.write() buffers incomplete multi-byte UTF-8 sequences across chunk boundaries
const euroDecoder = new StringDecoder('utf8');
const euroPart1 = Buffer.from([0xE2, 0x82]);
const euroPart2 = Buffer.from([0xAC]);
assert.strictEqual(euroDecoder.write(euroPart1), '');
assert.strictEqual(euroDecoder.write(euroPart2), '€');

// 3. StringDecoder.prototype.write() decodes multi-byte UTF-8 sequences including 4-byte emojis when completed
const emojiDecoder = new StringDecoder('utf8');
const emPart1 = Buffer.from([0xF0, 0x9F]);
const emPart2 = Buffer.from([0x9A, 0x80]); // 🚀 (\uD83D\uDE80)
assert.strictEqual(emojiDecoder.write(emPart1), '');
assert.strictEqual(emojiDecoder.write(emPart2), '🚀');

// Helper function decodeChunks test
const decodedEmoji = decodeChunks([emPart1, emPart2], 'utf8');
assert.strictEqual(decodedEmoji, '🚀');

// 4. StringDecoder.prototype.write() returns complete ASCII and UTF-8 strings immediately
const greetingDecoder = new StringDecoder('utf8');
assert.strictEqual(greetingDecoder.write(Buffer.from('Hello, ')), 'Hello, ');
assert.strictEqual(greetingDecoder.write(Buffer.from('World!')), 'World!');

// 5. StringDecoder.prototype.end() flushes trailing incomplete bytes as Unicode replacement characters
const incompleteDecoder = new StringDecoder('utf8');
assert.strictEqual(incompleteDecoder.write(Buffer.from([0xE2, 0x82])), '');
assert.strictEqual(incompleteDecoder.end(), '\uFFFD');

// 6. StringDecoder.prototype.end(buffer) decodes the final buffer chunk and flushes the decoder
const endWithBufDecoder = new StringDecoder('utf8');
assert.strictEqual(endWithBufDecoder.end(Buffer.from('Final chunk')), 'Final chunk');

// 7. StringDecoder.prototype.write() and end() decode base64 across buffer boundaries
const b64Dec = new StringDecoder('base64');
const b64Buf1 = Buffer.from('Hello ');
const b64Buf2 = Buffer.from('World');
const out1 = b64Dec.write(b64Buf1);
const out2 = b64Dec.end(b64Buf2);
assert.strictEqual(out1 + out2, Buffer.from('Hello World').toString('base64'));

// 8. StringDecoder.prototype.write() and end() decode hex across buffer boundaries
const hexDec = new StringDecoder('hex');
const hexBuf1 = Buffer.from([0xde, 0xad]);
const hexBuf2 = Buffer.from([0xbe, 0xef]);
assert.strictEqual(hexDec.write(hexBuf1), 'dead');
assert.strictEqual(hexDec.end(hexBuf2), 'beef');

console.log('Contract tests passed successfully.');