iconv-lite 0.6.3: iconv.encode

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 iconv.encode in pkg:npm/iconv-lite@0.6.3
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/iconv-lite@0.6.3
Demonstrate these symbols/APIs:
  - iconv.encode

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:a8d052ab569ed06907e411dd0491574e4d5174c924a0b92788c70cacaed6843b","contract":["assert iconv.encode returns a Buffer when encoding UTF-8 strings","assert iconv.encode with addBOM option prepends 0xEF 0xBB 0xBF byte order mark to UTF-8 output","assert iconv.encode accurately encodes multibyte CJK characters in EUC-KR and Shift_JIS","assert iconv.encode accurately encodes single-byte Western text in Windows-1252 and ISO-8859-1","assert iconv.encode handles empty strings by returning an empty Buffer","assert iconv.encode substitutes unrepresentable characters with default replacement character in single-byte encoding"],"goal":"verify iconv.encode in pkg:npm/iconv-lite@0.6.3","kind":"HOW","packages":["pkg:npm/iconv-lite@0.6.3"],"schemaVersion":1,"symbols":["iconv.encode"]},"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/iconv-lite@0.6.3"],"schemaVersion":1,"subject":"pkg:npm/iconv-lite@0.6.3","symbols":["iconv.encode"],"verifierAdapter":"node-typescript@1"}

const iconv = require('iconv-lite');

function encodeText(text, encoding, options) {
  return iconv.encode(text, encoding, options);
}

function encodeWithBOM(text, encoding) {
  return iconv.encode(text, encoding, { addBOM: true });
}

function encodeWithFallback(text, encoding, defaultChar) {
  return iconv.encode(text, encoding, { defaultCharSingleByte: defaultChar });
}

module.exports = {
  encodeText,
  encodeWithBOM,
  encodeWithFallback,
  iconv,
};

{
  "name": "sample-iconv-lite-encode",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-iconv-lite-encode",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "iconv-lite": "0.6.3"
      }
    },
    "node_modules/iconv-lite": {
      "version": "0.6.3",
      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz",
      "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==",
      "license": "MIT",
      "dependencies": {
        "safer-buffer": ">= 2.1.2 < 3.0.0"
      },
      "engines": {
        "node": ">=0.10.0"
      }
    },
    "node_modules/safer-buffer": {
      "version": "2.1.2",
      "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz",
      "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-iconv-lite-encode",
  "version": "1.0.0",
  "description": "Minimal clean-room sample verifying iconv.encode in iconv-lite",
  "main": "index.js",
  "license": "MIT-0",
  "dependencies": {
    "iconv-lite": "0.6.3"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify iconv.encode in pkg:npm/iconv-lite@0.6.3",
  "kind": "HOW",
  "packages": [
    "pkg:npm/iconv-lite@0.6.3"
  ],
  "symbols": [
    "iconv.encode"
  ]
}

import assert from 'node:assert';
import iconv from 'iconv-lite';
import {
  encodeText,
  encodeWithBOM,
  encodeWithFallback,
} from '../index.js';

// 1. iconv.encode returns a Buffer when encoding UTF-8 strings
const utf8Str = 'Hello, CodeSampleX!';
const utf8Buf = encodeText(utf8Str, 'utf-8');
assert(Buffer.isBuffer(utf8Buf), 'encodeText must return a Buffer instance');
assert.strictEqual(utf8Buf.toString('utf-8'), utf8Str, 'UTF-8 encoded buffer must match original string');

// 2. iconv.encode with addBOM option prepends 0xEF 0xBB 0xBF byte order mark to UTF-8 output
const bomStr = 'BOM Test';
const bomBuf = encodeWithBOM(bomStr, 'utf-8');
assert.strictEqual(bomBuf[0], 0xef, 'First byte of UTF-8 BOM must be 0xEF');
assert.strictEqual(bomBuf[1], 0xbb, 'Second byte of UTF-8 BOM must be 0xBB');
assert.strictEqual(bomBuf[2], 0xbf, 'Third byte of UTF-8 BOM must be 0xBF');
assert.strictEqual(bomBuf.subarray(3).toString('utf-8'), bomStr, 'Bytes after BOM must match original string');

// 3. iconv.encode accurately encodes multibyte CJK characters in EUC-KR and Shift_JIS
const koreanText = '한글 인코딩 테스트';
const eucKrBuf = encodeText(koreanText, 'euc-kr');
assert(Buffer.isBuffer(eucKrBuf), 'EUC-KR encoded output must be a Buffer');
assert.strictEqual(iconv.decode(eucKrBuf, 'euc-kr'), koreanText, 'Decoded EUC-KR buffer must match original Korean string');

const japaneseText = '日本語テスト';
const shiftJisBuf = encodeText(japaneseText, 'shift_jis');
assert(Buffer.isBuffer(shiftJisBuf), 'Shift_JIS encoded output must be a Buffer');
assert.strictEqual(iconv.decode(shiftJisBuf, 'shift_jis'), japaneseText, 'Decoded Shift_JIS buffer must match original Japanese string');

// 4. iconv.encode accurately encodes single-byte Western text in Windows-1252 and ISO-8859-1
const euroText = 'Price: €100';
const win1252Buf = encodeText(euroText, 'windows-1252');
assert.strictEqual(win1252Buf[7], 0x80, 'Euro sign in Windows-1252 must encode to byte 0x80');
assert.strictEqual(iconv.decode(win1252Buf, 'windows-1252'), euroText, 'Decoded Windows-1252 buffer must match original text');

// 5. iconv.encode handles empty strings by returning an empty Buffer
const emptyBuf = encodeText('', 'utf-8');
assert(Buffer.isBuffer(emptyBuf), 'Empty string encoding must return a Buffer');
assert.strictEqual(emptyBuf.length, 0, 'Empty string encoded buffer must have length 0');

// 6. iconv.encode substitutes unrepresentable characters with default replacement character in single-byte encoding
const unrepresentable = 'Hello \u2603';
const asciiBuf = encodeWithFallback(unrepresentable, 'ascii', '?');
assert(Buffer.isBuffer(asciiBuf), 'Fallback encoding must return a Buffer');
assert.strictEqual(iconv.decode(asciiBuf, 'ascii'), 'Hello ?', 'Unrepresentable character must be replaced with question mark');

console.log('All iconv.encode contract assertions passed.');