smart-buffer 4.2.0

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/smart-buffer@4.2.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/smart-buffer@4.2.0

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:764ee53c5cf3865b46a5ec5fc493063b2b972d5e8871d1d207269d9a499f7ac4","contract":["assert SmartBuffer instance automatically resizes and maintains read and write offsets during sequential numeric writes and reads","assert SmartBuffer writes and reads fixed-length strings and null-terminated strings using writeStringNT and readStringNT","assert SmartBuffer writes and reads binary Buffer payloads using writeBuffer and readBuffer in packet serialization","assert SmartBuffer.fromBuffer wraps existing Buffer and supports both sequential and offset-based reads","assert SmartBuffer toBuffer returns exact binary Buffer and clear resets offsets and length"],"goal":"verify pkg:npm/smart-buffer@4.2.0","kind":"HOW","packages":["pkg:npm/smart-buffer@4.2.0"],"schemaVersion":1},"contractCommand":["node","test/contract.mjs"],"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/smart-buffer@4.2.0"],"schemaVersion":1,"subject":"pkg:npm/smart-buffer@4.2.0","verifierAdapter":"node-typescript@1"}

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

/**
 * Creates a new empty SmartBuffer instance.
 * @param {Object} [options]
 * @returns {SmartBuffer}
 */
function createSmartBuffer(options) {
  return new SmartBuffer(options);
}

/**
 * Creates a SmartBuffer initialized with an existing Buffer.
 * @param {Buffer} buffer
 * @param {string} [encoding]
 * @returns {SmartBuffer}
 */
function createFromBuffer(buffer, encoding) {
  return SmartBuffer.fromBuffer(buffer, encoding);
}

/**
 * Serializes a structured packet containing metadata and binary payload.
 * @param {number} packetId
 * @param {string} tag
 * @param {Buffer} payload
 * @returns {Buffer}
 */
function serializePacket(packetId, tag, payload) {
  const sb = new SmartBuffer();
  sb.writeUInt16BE(packetId);
  sb.writeStringNT(tag);
  sb.writeUInt32BE(payload.length);
  sb.writeBuffer(payload);
  return sb.toBuffer();
}

/**
 * Deserializes a structured packet created by serializePacket.
 * @param {Buffer} buffer
 * @returns {{ packetId: number, tag: string, payload: Buffer }}
 */
function deserializePacket(buffer) {
  const sb = SmartBuffer.fromBuffer(buffer);
  const packetId = sb.readUInt16BE();
  const tag = sb.readStringNT();
  const length = sb.readUInt32BE();
  const payload = sb.readBuffer(length);
  return { packetId, tag, payload };
}

module.exports = {
  SmartBuffer,
  createSmartBuffer,
  createFromBuffer,
  serializePacket,
  deserializePacket,
};

{
  "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",
  "main": "index.js",
  "license": "MIT-0",
  "dependencies": {
    "smart-buffer": "4.2.0"
  }
}

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

import assert from 'node:assert';
import {
  SmartBuffer,
  createSmartBuffer,
  createFromBuffer,
  serializePacket,
  deserializePacket
} from '../index.js';

// 1. SmartBuffer instance automatically resizes and maintains read and write offsets during sequential numeric writes and reads
const sb = createSmartBuffer();
assert.strictEqual(sb.length, 0);
assert.strictEqual(sb.writeOffset, 0);
assert.strictEqual(sb.readOffset, 0);

sb.writeUInt8(0x42);
sb.writeInt16LE(-1234);
sb.writeInt32BE(0x12345678);
sb.writeBigInt64LE(1234567890123456789n);
sb.writeFloatLE(1.5);
sb.writeDoubleBE(3.141592653589793);

assert.strictEqual(sb.length, 1 + 2 + 4 + 8 + 4 + 8);
assert.strictEqual(sb.writeOffset, 27);
assert.strictEqual(sb.readOffset, 0);

assert.strictEqual(sb.readUInt8(), 0x42);
assert.strictEqual(sb.readInt16LE(), -1234);
assert.strictEqual(sb.readInt32BE(), 0x12345678);
assert.strictEqual(sb.readBigInt64LE(), 1234567890123456789n);
assert.strictEqual(sb.readFloatLE(), 1.5);
assert.strictEqual(sb.readDoubleBE(), 3.141592653589793);
assert.strictEqual(sb.remaining(), 0);

// 2. SmartBuffer writes and reads fixed-length strings and null-terminated strings using writeStringNT and readStringNT
const sbStr = createSmartBuffer();
sbStr.writeString('Header');
sbStr.writeStringNT('NullTerminatedString');

assert.strictEqual(sbStr.length, 6 + 21); // 20 chars + null terminator = 21
assert.strictEqual(sbStr.readString(6), 'Header');
assert.strictEqual(sbStr.readStringNT(), 'NullTerminatedString');
assert.strictEqual(sbStr.remaining(), 0);

// 3. SmartBuffer writes and reads binary Buffer payloads using writeBuffer and readBuffer in packet serialization
const payloadData = Buffer.from([0xde, 0xad, 0xbe, 0xef, 0x01, 0x02, 0x03]);
const packet = serializePacket(1001, 'auth-session', payloadData);
assert(Buffer.isBuffer(packet), 'serializePacket must return a Buffer instance');

const decoded = deserializePacket(packet);
assert.strictEqual(decoded.packetId, 1001);
assert.strictEqual(decoded.tag, 'auth-session');
assert.deepStrictEqual(Array.from(decoded.payload), Array.from(payloadData));

// 4. SmartBuffer.fromBuffer wraps existing Buffer and supports both sequential and offset-based reads
const rawBuffer = Buffer.from([0x10, 0x20, 0x30, 0x40, 0x50]);
const sbFrom = createFromBuffer(rawBuffer);
assert.strictEqual(sbFrom.length, 5);
assert.strictEqual(sbFrom.readUInt8(0), 0x10);
assert.strictEqual(sbFrom.readUInt8(4), 0x50);
assert.strictEqual(sbFrom.readUInt8(), 0x10);
assert.strictEqual(sbFrom.readUInt8(), 0x20);
assert.strictEqual(sbFrom.readUInt8(), 0x30);
assert.strictEqual(sbFrom.remaining(), 2);

// 5. SmartBuffer toBuffer returns exact binary Buffer and clear resets offsets and length
const sbFinal = createSmartBuffer();
sbFinal.writeUInt8(0xfe);
sbFinal.writeUInt8(0xed);
const rawOut = sbFinal.toBuffer();
assert.deepStrictEqual(Array.from(rawOut), [0xfe, 0xed]);

sbFinal.clear();
assert.strictEqual(sbFinal.length, 0);
assert.strictEqual(sbFinal.readOffset, 0);
assert.strictEqual(sbFinal.writeOffset, 0);
assert.strictEqual(sbFinal.remaining(), 0);

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