bytestreamjs 2.0.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/bytestreamjs@2.0.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/bytestreamjs@2.0.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:aad2c14fc084836cb23bba4a9214b70867c3aefa4a3263763e736592297eb4e5","contract":["ByteStream supports initialization from string, hexadecimal string, ArrayBuffer, and Uint8Array view","ByteStream provides uppercase hexadecimal and string conversions with toHexString and toString","ByteStream supports copying, slicing, and equality comparison via isEqual and isEqualView","ByteStream supports pattern searching returning offset after match and in-place pattern replacement","SeqStream serializes sequential mixed numeric types (char, uint16, int16, uint32) and raw byte views","SeqStream deserializes structured binary payloads accurately tracking remaining length","BitStream manipulates individual bits and converts between bit string representations and numeric values"],"goal":"verify pkg:npm/bytestreamjs@2.0.1","kind":"HOW","packages":["pkg:npm/bytestreamjs@2.0.1"],"schemaVersion":1},"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/bytestreamjs@2.0.1"],"schemaVersion":1,"subject":"pkg:npm/bytestreamjs@2.0.1","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-bytestreamjs",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-bytestreamjs",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "bytestreamjs": "2.0.1"
      }
    },
    "node_modules/bytestreamjs": {
      "version": "2.0.1",
      "resolved": "https://registry.npmjs.org/bytestreamjs/-/bytestreamjs-2.0.1.tgz",
      "integrity": "sha512-U1Z/ob71V/bXfVABvNr/Kumf5VyeQRBEm6Txb0PQ6S7V5GpBM3w4Cbqz/xPDicR5tN0uvDifng8C+5qECeGwyQ==",
      "license": "BSD-3-Clause",
      "engines": {
        "node": ">=6.0.0"
      }
    }
  }
}

{
  "name": "sample-bytestreamjs",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of pkg:npm/bytestreamjs@2.0.1",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "bytestreamjs": "2.0.1"
  }
}

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

const { ByteStream, SeqStream, BitStream, SeqBitStream } = require('bytestreamjs');

function createByteStream(parameters) {
  return new ByteStream(parameters);
}

function createSeqStream(parameters) {
  return new SeqStream(parameters);
}

function stringToByteStream(str) {
  const stream = new ByteStream();
  stream.fromString(str);
  return stream;
}

function hexToByteStream(hex) {
  const stream = new ByteStream();
  stream.fromHexString(hex);
  return stream;
}

function encodeBinaryMessage(header, payload) {
  const writer = new SeqStream();
  writer.appendChar(header.type);
  writer.appendUint16(header.seq);
  writer.appendInt16(header.status);
  writer.appendUint32(header.timestamp);
  if (payload && payload.length > 0) {
    writer.appendView(payload instanceof Uint8Array ? payload : new Uint8Array(payload));
  }
  return writer.stream.view.subarray(0, writer.start);
}

function decodeBinaryMessage(view) {
  const reader = new SeqStream({ view });
  const type = reader.getBlock(1)[0];
  const seq = reader.getUint16();
  const status = reader.getInt16();
  const timestamp = reader.getUint32() >>> 0;
  const payload = reader.length > 0 ? reader.getBlock(reader.length) : new Uint8Array(0);
  return {
    header: { type, seq, status, timestamp },
    payload
  };
}

function findAndReplacePattern(stream, search, replace) {
  const searchStream = search instanceof ByteStream ? search : stringToByteStream(search);
  const replaceStream = replace instanceof ByteStream ? replace : stringToByteStream(replace);
  return stream.replacePattern(searchStream, replaceStream);
}

module.exports = {
  ByteStream,
  SeqStream,
  BitStream,
  SeqBitStream,
  createByteStream,
  createSeqStream,
  stringToByteStream,
  hexToByteStream,
  encodeBinaryMessage,
  decodeBinaryMessage,
  findAndReplacePattern
};

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

const require = createRequire(import.meta.url);
const {
  ByteStream,
  SeqStream,
  BitStream,
  createByteStream,
  createSeqStream,
  stringToByteStream,
  hexToByteStream,
  encodeBinaryMessage,
  decodeBinaryMessage,
  findAndReplacePattern
} = require('../src/index.js');

// 1. ByteStream supports initialization from string, hexadecimal string, ArrayBuffer, and Uint8Array view
const strBs = stringToByteStream('CodeSampleX');
assert.strictEqual(strBs.toString(), 'CodeSampleX', 'fromString and toString should match');
assert.strictEqual(strBs.length, 11, 'length should match string length');

const hexBs = hexToByteStream('436F6465'); // "Code"
assert.strictEqual(hexBs.toString(), 'Code', 'hex string should decode to ASCII text');

const viewBs = createByteStream({ view: new Uint8Array([0x41, 0x42, 0x43]) });
assert.strictEqual(viewBs.toString(), 'ABC', 'view parameter should initialize buffer correctly');

const bufferBs = createByteStream({ buffer: new ArrayBuffer(4) });
assert.strictEqual(bufferBs.length, 4, 'buffer parameter should initialize buffer length');

// 2. ByteStream provides uppercase hexadecimal and string conversions with toHexString and toString
assert.strictEqual(strBs.toHexString(0, 4), '436F6465', 'toHexString should return uppercase hex values');
assert.strictEqual(hexBs.toHexString(), '436F6465', 'toHexString on hex stream should match original hex input');

// 3. ByteStream supports copying, slicing, and equality comparison via isEqual and isEqualView
const copyBs = strBs.copy();
assert.strictEqual(copyBs.isEqual(strBs), true, 'copy should be equal to source ByteStream');
const sliceBs = strBs.slice(0, 4);
assert.strictEqual(sliceBs.toString(), 'Code', 'slice should extract substring');
assert.strictEqual(sliceBs.isEqualView(new Uint8Array([0x43, 0x6F, 0x64, 0x65])), true, 'isEqualView should verify byte content');

// 4. ByteStream supports pattern searching returning offset after match and in-place pattern replacement
const textStream = stringToByteStream('foo bar foo baz');
const searchPattern = stringToByteStream('foo');
assert.strictEqual(textStream.findPattern(searchPattern), 3, 'findPattern forward should return position after pattern');
assert.deepStrictEqual(textStream.findAllPatternIn(searchPattern), [3, 11], 'findAllPatternIn should locate all occurrences');

const replaceResult = findAndReplacePattern(textStream, 'foo', 'qux');
assert.strictEqual(replaceResult.status, 1, 'replacePattern should succeed with status 1');
assert.strictEqual(textStream.toString(), 'qux bar qux baz', 'replacePattern should replace all pattern instances');

// 5. SeqStream serializes sequential mixed numeric types (char, uint16, int16, uint32) and raw byte views
const header = { type: 1, seq: 256, status: -100, timestamp: 1600000000 };
const rawPayload = new Uint8Array([0xDE, 0xAD, 0xBE, 0xEF]);
const encodedBytes = encodeBinaryMessage(header, rawPayload);
assert.strictEqual(encodedBytes.length, 1 + 2 + 2 + 4 + 4, 'encoded length should equal sum of header and payload bytes');

// 6. SeqStream deserializes structured binary payloads accurately tracking remaining length
const decoded = decodeBinaryMessage(encodedBytes);
assert.strictEqual(decoded.header.type, 1, 'decoded type should match header');
assert.strictEqual(decoded.header.seq, 256, 'decoded seq should match header');
assert.strictEqual(decoded.header.status, -100, 'decoded status should match signed int16');
assert.strictEqual(decoded.header.timestamp, 1600000000, 'decoded timestamp should match uint32');
assert.deepStrictEqual(Array.from(decoded.payload), [0xDE, 0xAD, 0xBE, 0xEF], 'decoded payload should match original payload');

// 7. BitStream manipulates individual bits and converts between bit string representations and numeric values
const bit = new BitStream({ string: '11110000' });
assert.strictEqual(bit.toString(), '11110000', 'BitStream toString should represent bit string');
assert.strictEqual(bit.getNumberValue(), 0xF0, 'BitStream getNumberValue should convert bits to unsigned integer');

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