smart-buffer 4.2.0: SmartBuffer

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 smart-buffer.SmartBuffer in pkg:npm/smart-buffer@4.2.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/smart-buffer@4.2.0
Demonstrate these symbols/APIs:
  - smart-buffer.SmartBuffer

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:1cde9c7e5ba1a35eee701a4739e8ff25070f2ca3e0cb8dfbfdf655a5ee5ef98e","contract":["createBuffer creates SmartBuffer instances that support sequential numeric and string reads and writes while tracking offsets","fromBuffer creates a SmartBuffer instance initialized with existing binary data","fromSize creates a SmartBuffer instance with pre-allocated capacity","SmartBuffer supports inserting data at arbitrary offsets shifting trailing data","SmartBuffer reads and writes null-terminated strings with writeStringNT and readStringNT","toBuffer returns binary Buffer representation and clear resets all offsets and length","encodePacket and decodePacket provide structured binary packet serialization and parsing"],"goal":"verify smart-buffer.SmartBuffer in pkg:npm/smart-buffer@4.2.0","kind":"HOW","packages":["pkg:npm/smart-buffer@4.2.0"],"schemaVersion":1,"symbols":["smart-buffer.SmartBuffer"]},"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/smart-buffer@4.2.0"],"schemaVersion":1,"subject":"pkg:npm/smart-buffer@4.2.0","symbols":["smart-buffer.SmartBuffer"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-smart-buffer",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-smart-buffer",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "smart-buffer": "4.2.0"
      }
    },
    "node_modules/smart-buffer": {
      "version": "4.2.0",
      "resolved": "https://registry.npmjs.org/smart-buffer/-/smart-buffer-4.2.0.tgz",
      "integrity": "sha512-94hK0Hh8rPqQl2xXc3HsaBoOXKV20MToPkcXvwbISWLEs+64sBq5kFgn2kJDHb1Pry9yrP0dxrCI9RRci7RXKg==",
      "license": "MIT",
      "engines": {
        "node": ">= 6.0.0",
        "npm": ">= 3.0.0"
      }
    }
  }
}

{
  "name": "sample-smart-buffer",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of smart-buffer.SmartBuffer",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "smart-buffer": "4.2.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify smart-buffer.SmartBuffer in pkg:npm/smart-buffer@4.2.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/smart-buffer@4.2.0"
  ],
  "symbols": [
    "smart-buffer.SmartBuffer"
  ]
}

const { SmartBuffer } = require('smart-buffer');

function createBuffer(options) {
  return new SmartBuffer(options);
}

function fromBuffer(buffer, encoding) {
  return SmartBuffer.fromBuffer(buffer, encoding);
}

function fromSize(size, encoding) {
  return SmartBuffer.fromSize(size, encoding);
}

function encodePacket(header, payload) {
  const sb = new SmartBuffer();
  sb.writeUInt8(header.type);
  sb.writeUInt16BE(header.seq);
  sb.writeStringNT(header.name);
  sb.writeBuffer(payload);
  return sb.toBuffer();
}

function decodePacket(buffer) {
  const sb = SmartBuffer.fromBuffer(buffer);
  const type = sb.readUInt8();
  const seq = sb.readUInt16BE();
  const name = sb.readStringNT();
  const payload = sb.readBuffer(sb.remaining());
  return {
    header: { type, seq, name },
    payload
  };
}

module.exports = {
  SmartBuffer,
  createBuffer,
  fromBuffer,
  fromSize,
  encodePacket,
  decodePacket
};

import assert from 'node:assert';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const {
  SmartBuffer,
  createBuffer,
  fromBuffer,
  fromSize,
  encodePacket,
  decodePacket
} = require('../src/index.js');

// 1. SmartBuffer constructor and sequential read/write operations
const sb = createBuffer();
assert(sb instanceof SmartBuffer, 'createBuffer should return a SmartBuffer instance');
sb.writeUInt8(42);
sb.writeInt16BE(1000);
sb.writeInt32LE(123456);
sb.writeString('hello');

assert.strictEqual(sb.length, 1 + 2 + 4 + 5, 'length should match total written bytes');
assert.strictEqual(sb.readOffset, 0, 'readOffset should start at 0');
assert.strictEqual(sb.writeOffset, 12, 'writeOffset should advance with writes');

assert.strictEqual(sb.readUInt8(), 42, 'readUInt8 should match written value');
assert.strictEqual(sb.readInt16BE(), 1000, 'readInt16BE should match written value');
assert.strictEqual(sb.readInt32LE(), 123456, 'readInt32LE should match written value');
assert.strictEqual(sb.readString(5), 'hello', 'readString should read specified number of chars');
assert.strictEqual(sb.remaining(), 0, 'remaining should be 0 when all bytes read');

// 2. SmartBuffer.fromBuffer creates instance initialized with existing binary data
const existingData = Buffer.from([0x01, 0x02, 0x03, 0x04]);
const sbFromBuf = fromBuffer(existingData);
assert.strictEqual(sbFromBuf.length, 4, 'length should match buffer size');
assert.strictEqual(sbFromBuf.readUInt8(), 0x01, 'readUInt8 should return first byte');
assert.strictEqual(sbFromBuf.readUInt8(), 0x02, 'readUInt8 should return second byte');
assert.strictEqual(sbFromBuf.remaining(), 2, 'remaining should track unread bytes');

// 3. SmartBuffer.fromSize creates instance with pre-allocated capacity
const sbFromSize = fromSize(64);
assert.strictEqual(sbFromSize.length, 0, 'length should start at 0 for pre-allocated buffer');
sbFromSize.writeString('test-size');
assert.strictEqual(sbFromSize.length, 9, 'length should track written length');
assert.strictEqual(sbFromSize.readString(9), 'test-size', 'readString should return written string');

// 4. SmartBuffer supports inserting data at arbitrary offsets shifting trailing data
const sbInsert = new SmartBuffer();
sbInsert.writeString('AC');
sbInsert.insertString('B', 1);
assert.strictEqual(sbInsert.toString(), 'ABC', 'insertString should insert character at offset 1');
assert.strictEqual(sbInsert.length, 3, 'length should reflect inserted string');

// 5. SmartBuffer reads and writes null-terminated strings
const sbNT = new SmartBuffer();
sbNT.writeStringNT('null-terminated');
sbNT.writeUInt8(99);
assert.strictEqual(sbNT.readStringNT(), 'null-terminated', 'readStringNT should read up to null byte');
assert.strictEqual(sbNT.readUInt8(), 99, 'readUInt8 should read subsequent byte after null terminator');

// 6. SmartBuffer.toBuffer returns Buffer and clear() resets offsets
const sbClear = new SmartBuffer();
sbClear.writeUInt16LE(512);
const outBuf = sbClear.toBuffer();
assert(Buffer.isBuffer(outBuf), 'toBuffer should return a Buffer');
assert.strictEqual(outBuf.length, 2, 'output buffer length should match written bytes');
sbClear.clear();
assert.strictEqual(sbClear.length, 0, 'clear should reset length to 0');
assert.strictEqual(sbClear.readOffset, 0, 'clear should reset readOffset to 0');
assert.strictEqual(sbClear.writeOffset, 0, 'clear should reset writeOffset to 0');

// 7. Packet encoding and decoding using SmartBuffer
const rawPayload = Buffer.from('payload-content', 'utf8');
const packet = encodePacket({ type: 1, seq: 100, name: 'ping' }, rawPayload);
assert(Buffer.isBuffer(packet), 'encodePacket should return Buffer');

const decoded = decodePacket(packet);
assert.strictEqual(decoded.header.type, 1, 'decoded packet header type should match');
assert.strictEqual(decoded.header.seq, 100, 'decoded packet header seq should match');
assert.strictEqual(decoded.header.name, 'ping', 'decoded packet header name should match');
assert.deepStrictEqual(decoded.payload, rawPayload, 'decoded packet payload should match');

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