ieee754 1.2.1: read and write IEEE 754 floating point numbers in buffer

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: read and write IEEE 754 floating point numbers in buffer
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/ieee754@1.2.1
Demonstrate these symbols/APIs:
  - read
  - write

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:60df84f38a2bfb6f858e594282b70865f15fff514dfc2831f4bb825e02ca5024","contract":["read decodes 32-bit single-precision IEEE 754 floats from buffer in little-endian and big-endian order","write encodes 32-bit single-precision IEEE 754 floats into buffer matching native representation","read and write decode and encode 64-bit double-precision IEEE 754 floats including subnormal numbers","read and write correctly handle special floating point values including Infinity, -Infinity, NaN, and negative zero","read and write operate at specified buffer offsets without corrupting surrounding bytes","encodeFloat and encodeDouble allocate new Uint8Array buffers containing encoded float values"],"goal":"read and write IEEE 754 floating point numbers in buffer","kind":"HOW","packages":["pkg:npm/ieee754@1.2.1"],"schemaVersion":1,"symbols":["read","write"]},"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/ieee754@1.2.1"],"schemaVersion":1,"subject":"pkg:npm/ieee754@1.2.1","symbols":["read","write"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-ieee754",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-ieee754",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "ieee754": "1.2.1"
      }
    },
    "node_modules/ieee754": {
      "version": "1.2.1",
      "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz",
      "integrity": "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/feross"
        },
        {
          "type": "patreon",
          "url": "https://www.patreon.com/feross"
        },
        {
          "type": "consulting",
          "url": "https://feross.org/support"
        }
      ],
      "license": "BSD-3-Clause"
    }
  }
}

{
  "name": "sample-ieee754",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room code sample for ieee754@1.2.1",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "ieee754": "1.2.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "read and write IEEE 754 floating point numbers in buffer",
  "kind": "HOW",
  "packages": [
    "pkg:npm/ieee754@1.2.1"
  ],
  "symbols": [
    "read",
    "write"
  ]
}

'use strict';

const ieee754 = require('ieee754');

/**
 * Reads an IEEE 754 floating point number from a buffer or byte array.
 *
 * @param {Uint8Array|Buffer|Array<number>} buffer - The source buffer.
 * @param {number} offset - The starting offset within the buffer.
 * @param {boolean} isLE - Whether the byte order is little-endian.
 * @param {number} mLen - Mantissa bit length (23 for float32, 52 for float64).
 * @param {number} nBytes - Total byte length (4 for float32, 8 for float64).
 * @returns {number} The decoded floating point number.
 */
function read(buffer, offset, isLE, mLen, nBytes) {
  return ieee754.read(buffer, offset, isLE, mLen, nBytes);
}

/**
 * Writes an IEEE 754 floating point number into a buffer or byte array.
 *
 * @param {Uint8Array|Buffer|Array<number>} buffer - The destination buffer.
 * @param {number} value - The floating point number to encode.
 * @param {number} offset - The starting offset within the buffer.
 * @param {boolean} isLE - Whether the byte order is little-endian.
 * @param {number} mLen - Mantissa bit length (23 for float32, 52 for float64).
 * @param {number} nBytes - Total byte length (4 for float32, 8 for float64).
 */
function write(buffer, value, offset, isLE, mLen, nBytes) {
  ieee754.write(buffer, value, offset, isLE, mLen, nBytes);
}

/**
 * Reads a 32-bit single-precision IEEE 754 float from buffer.
 *
 * @param {Uint8Array|Buffer} buffer
 * @param {number} [offset=0]
 * @param {boolean} [isLE=true]
 * @returns {number}
 */
function readFloat(buffer, offset = 0, isLE = true) {
  return ieee754.read(buffer, offset, isLE, 23, 4);
}

/**
 * Writes a 32-bit single-precision IEEE 754 float to buffer.
 *
 * @param {Uint8Array|Buffer} buffer
 * @param {number} value
 * @param {number} [offset=0]
 * @param {boolean} [isLE=true]
 */
function writeFloat(buffer, value, offset = 0, isLE = true) {
  ieee754.write(buffer, value, offset, isLE, 23, 4);
}

/**
 * Reads a 64-bit double-precision IEEE 754 float from buffer.
 *
 * @param {Uint8Array|Buffer} buffer
 * @param {number} [offset=0]
 * @param {boolean} [isLE=true]
 * @returns {number}
 */
function readDouble(buffer, offset = 0, isLE = true) {
  return ieee754.read(buffer, offset, isLE, 52, 8);
}

/**
 * Writes a 64-bit double-precision IEEE 754 float to buffer.
 *
 * @param {Uint8Array|Buffer} buffer
 * @param {number} value
 * @param {number} [offset=0]
 * @param {boolean} [isLE=true]
 */
function writeDouble(buffer, value, offset = 0, isLE = true) {
  ieee754.write(buffer, value, offset, isLE, 52, 8);
}

/**
 * Encodes a 32-bit float into a new Uint8Array buffer.
 *
 * @param {number} value
 * @param {boolean} [isLE=true]
 * @returns {Uint8Array}
 */
function encodeFloat(value, isLE = true) {
  const buf = new Uint8Array(4);
  ieee754.write(buf, value, 0, isLE, 23, 4);
  return buf;
}

/**
 * Encodes a 64-bit double into a new Uint8Array buffer.
 *
 * @param {number} value
 * @param {boolean} [isLE=true]
 * @returns {Uint8Array}
 */
function encodeDouble(value, isLE = true) {
  const buf = new Uint8Array(8);
  ieee754.write(buf, value, 0, isLE, 52, 8);
  return buf;
}

module.exports = {
  read,
  write,
  readFloat,
  writeFloat,
  readDouble,
  writeDouble,
  encodeFloat,
  encodeDouble
};

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

const require = createRequire(import.meta.url);
const {
  read,
  write,
  readFloat,
  writeFloat,
  readDouble,
  writeDouble,
  encodeFloat,
  encodeDouble
} = require('../src/index.js');

async function testAll() {
  // 1. Export verification
  assert.equal(typeof read, 'function', 'read must be a function');
  assert.equal(typeof write, 'function', 'write must be a function');
  assert.equal(typeof readFloat, 'function', 'readFloat must be a function');
  assert.equal(typeof writeFloat, 'function', 'writeFloat must be a function');
  assert.equal(typeof readDouble, 'function', 'readDouble must be a function');
  assert.equal(typeof writeDouble, 'function', 'writeDouble must be a function');
  assert.equal(typeof encodeFloat, 'function', 'encodeFloat must be a function');
  assert.equal(typeof encodeDouble, 'function', 'encodeDouble must be a function');

  // 2. IEEE 754 32-bit single-precision float read and write
  const floatTestValues = [
    0,
    1,
    -1,
    0.5,
    -0.5,
    123.45600128173828,
    3.1415927410125732,
    1.5e-10,
    3.4028234663852886e38
  ];

  for (const val of floatTestValues) {
    // Little-Endian test
    const bufLE = Buffer.alloc(4);
    write(bufLE, val, 0, true, 23, 4);
    const decodedLE = read(bufLE, 0, true, 23, 4);
    assert.equal(Math.fround(decodedLE), Math.fround(val), `Float LE mismatch for ${val}`);

    const nativeLE = Buffer.alloc(4);
    nativeLE.writeFloatLE(val, 0);
    assert.deepEqual(bufLE, nativeLE, `Byte representation mismatch for float LE ${val}`);

    // Big-Endian test
    const bufBE = Buffer.alloc(4);
    write(bufBE, val, 0, false, 23, 4);
    const decodedBE = read(bufBE, 0, false, 23, 4);
    assert.equal(Math.fround(decodedBE), Math.fround(val), `Float BE mismatch for ${val}`);

    const nativeBE = Buffer.alloc(4);
    nativeBE.writeFloatBE(val, 0);
    assert.deepEqual(bufBE, nativeBE, `Byte representation mismatch for float BE ${val}`);
  }

  // Float special values: +Infinity, -Infinity, NaN, -0
  {
    // +Infinity
    const infBuf = Buffer.alloc(4);
    write(infBuf, Infinity, 0, true, 23, 4);
    assert.equal(read(infBuf, 0, true, 23, 4), Infinity, 'Should encode and decode +Infinity');

    // -Infinity
    const negInfBuf = Buffer.alloc(4);
    write(negInfBuf, -Infinity, 0, true, 23, 4);
    assert.equal(read(negInfBuf, 0, true, 23, 4), -Infinity, 'Should encode and decode -Infinity');

    // NaN
    const nanBuf = Buffer.alloc(4);
    write(nanBuf, NaN, 0, true, 23, 4);
    assert.ok(Number.isNaN(read(nanBuf, 0, true, 23, 4)), 'Should encode and decode NaN');

    // -0
    const negZeroBuf = Buffer.alloc(4);
    write(negZeroBuf, -0, 0, true, 23, 4);
    const decodedNegZero = read(negZeroBuf, 0, true, 23, 4);
    assert.equal(1 / decodedNegZero, -Infinity, 'Should preserve negative zero sign');
  }

  // 3. IEEE 754 64-bit double-precision float read and write
  const doubleTestValues = [
    0,
    1,
    -1,
    0.1,
    Math.PI,
    Number.MAX_SAFE_INTEGER,
    -Number.MAX_SAFE_INTEGER,
    Number.MAX_VALUE,
    Number.MIN_VALUE, // Subnormal
    1.23456789012345e-100,
    9.87654321098765e100
  ];

  for (const val of doubleTestValues) {
    // Little-Endian test
    const bufLE = Buffer.alloc(8);
    write(bufLE, val, 0, true, 52, 8);
    const decodedLE = read(bufLE, 0, true, 52, 8);
    assert.equal(decodedLE, val, `Double LE mismatch for ${val}`);

    const nativeLE = Buffer.alloc(8);
    nativeLE.writeDoubleLE(val, 0);
    assert.deepEqual(bufLE, nativeLE, `Byte representation mismatch for double LE ${val}`);

    // Big-Endian test
    const bufBE = Buffer.alloc(8);
    write(bufBE, val, 0, false, 52, 8);
    const decodedBE = read(bufBE, 0, false, 52, 8);
    assert.equal(decodedBE, val, `Double BE mismatch for ${val}`);

    const nativeBE = Buffer.alloc(8);
    nativeBE.writeDoubleBE(val, 0);
    assert.deepEqual(bufBE, nativeBE, `Byte representation mismatch for double BE ${val}`);
  }

  // Double special values: +Infinity, -Infinity, NaN, -0
  {
    // +Infinity
    const infBuf = Buffer.alloc(8);
    write(infBuf, Infinity, 0, true, 52, 8);
    assert.equal(read(infBuf, 0, true, 52, 8), Infinity, 'Should encode and decode +Infinity double');

    // -Infinity
    const negInfBuf = Buffer.alloc(8);
    write(negInfBuf, -Infinity, 0, true, 52, 8);
    assert.equal(read(negInfBuf, 0, true, 52, 8), -Infinity, 'Should encode and decode -Infinity double');

    // NaN
    const nanBuf = Buffer.alloc(8);
    write(nanBuf, NaN, 0, true, 52, 8);
    assert.ok(Number.isNaN(read(nanBuf, 0, true, 52, 8)), 'Should encode and decode NaN double');

    // -0
    const negZeroBuf = Buffer.alloc(8);
    write(negZeroBuf, -0, 0, true, 52, 8);
    const decodedNegZero = read(negZeroBuf, 0, true, 52, 8);
    assert.equal(1 / decodedNegZero, -Infinity, 'Should preserve negative zero sign in double');
  }

  // 4. Offset handling and buffer preservation
  {
    const targetBuffer = Buffer.from([0xAA, 0xBB, 0x00, 0x00, 0x00, 0x00, 0xCC, 0xDD]);
    const originalHeader = targetBuffer.subarray(0, 2).toString('hex');
    const originalFooter = targetBuffer.subarray(6, 8).toString('hex');

    writeFloat(targetBuffer, 42.5, 2, true);
    const readVal = readFloat(targetBuffer, 2, true);
    assert.equal(readVal, 42.5, 'readFloat should correctly read value written at offset 2');

    assert.equal(targetBuffer.subarray(0, 2).toString('hex'), originalHeader, 'Bytes before offset must remain unmodified');
    assert.equal(targetBuffer.subarray(6, 8).toString('hex'), originalFooter, 'Bytes after offset must remain unmodified');
  }

  {
    const targetBuffer = Buffer.alloc(20, 0xFF);
    writeDouble(targetBuffer, 1234567.89, 4, false);
    const readVal = readDouble(targetBuffer, 4, false);
    assert.equal(readVal, 1234567.89, 'readDouble should correctly read value written at offset 4 BE');

    assert.equal(targetBuffer.subarray(0, 4).every((b) => b === 0xFF), true, 'Prefix bytes must remain 0xFF');
    assert.equal(targetBuffer.subarray(12).every((b) => b === 0xFF), true, 'Suffix bytes must remain 0xFF');
  }

  // 5. Convenience encode functions
  {
    const encodedF = encodeFloat(1.25, true);
    assert.equal(encodedF instanceof Uint8Array, true, 'encodeFloat returns Uint8Array');
    assert.equal(encodedF.length, 4, 'encodeFloat returns 4 bytes');
    assert.equal(readFloat(encodedF, 0, true), 1.25, 'readFloat decodes encodeFloat output');

    const encodedD = encodeDouble(12345.6789, true);
    assert.equal(encodedD instanceof Uint8Array, true, 'encodeDouble returns Uint8Array');
    assert.equal(encodedD.length, 8, 'encodeDouble returns 8 bytes');
    assert.equal(readDouble(encodedD, 0, true), 12345.6789, 'readDouble decodes encodeDouble output');
  }

  console.log('All ieee754 contract tests passed successfully.');
}

testAll().catch((err) => {
  console.error('Contract test failure:', err);
  process.exit(1);
});