ieee754 1.2.1: read

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 ieee754.read in pkg:npm/ieee754@1.2.1
Kind: HOW

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

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:dd55a9a1003f12a1e40e964c1c1ca0502a50f22775f0ea0a3040c1ba63aa7853","contract":["ieee754.read is exported as a callable decoding function","ieee754.read decodes 32-bit single-precision floats in big-endian and little-endian format across buffer offsets","ieee754.read decodes 64-bit double-precision floats in big-endian and little-endian format across buffer offsets","ieee754.read correctly decodes special floating point values including infinities, NaN, and signed zeros","ieee754.read decodes subnormal floating point numbers without losing subnormal precision","ieee754.read operates uniformly on standard Uint8Array instances and Node.js Buffer instances"],"goal":"verify ieee754.read in pkg:npm/ieee754@1.2.1","kind":"HOW","packages":["pkg:npm/ieee754@1.2.1"],"schemaVersion":1,"symbols":["ieee754.read"]},"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/ieee754@1.2.1"],"schemaVersion":1,"subject":"pkg:npm/ieee754@1.2.1","symbols":["ieee754.read"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-ieee754-read",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-ieee754-read",
      "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==",
      "license": "BSD-3-Clause"
    }
  }
}

{
  "name": "sample-ieee754-read",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room code sample demonstrating ieee754.read in ieee754@1.2.1",
  "main": "src/index.js",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "license": "MIT-0",
  "dependencies": {
    "ieee754": "1.2.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify ieee754.read in pkg:npm/ieee754@1.2.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/ieee754@1.2.1"
  ],
  "symbols": [
    "ieee754.read"
  ]
}

'use strict';

const ieee754 = require('ieee754');

/**
 * Reads a single-precision (32-bit) IEEE 754 floating point number from a buffer or Uint8Array.
 *
 * @param {Uint8Array|Buffer} buffer - Source buffer containing binary data.
 * @param {number} [offset=0] - Byte offset into the buffer.
 * @param {boolean} [isLE=false] - True for little-endian, false for big-endian.
 * @returns {number} The decoded 32-bit float.
 */
function readFloat32(buffer, offset = 0, isLE = false) {
  return ieee754.read(buffer, offset, isLE, 23, 4);
}

/**
 * Reads a double-precision (64-bit) IEEE 754 floating point number from a buffer or Uint8Array.
 *
 * @param {Uint8Array|Buffer} buffer - Source buffer containing binary data.
 * @param {number} [offset=0] - Byte offset into the buffer.
 * @param {boolean} [isLE=false] - True for little-endian, false for big-endian.
 * @returns {number} The decoded 64-bit float.
 */
function readFloat64(buffer, offset = 0, isLE = false) {
  return ieee754.read(buffer, offset, isLE, 52, 8);
}

module.exports = {
  read: ieee754.read,
  readFloat32,
  readFloat64
};

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

const require = createRequire(import.meta.url);
const ieee754 = require('ieee754');
const { read, readFloat32, readFloat64 } = require('../src/index.js');

async function runTests() {
  // 1. ieee754.read is exported as a callable decoding function
  assert.equal(typeof ieee754.read, 'function', 'ieee754.read must be a function');
  assert.equal(typeof read, 'function', 'read export must be a function');
  assert.equal(read, ieee754.read, 'read must match ieee754.read');
  assert.equal(typeof readFloat32, 'function', 'readFloat32 must be a function');
  assert.equal(typeof readFloat64, 'function', 'readFloat64 must be a function');

  // 2. ieee754.read decodes 32-bit single-precision floats in big-endian and little-endian format across buffer offsets
  {
    const buf = Buffer.alloc(16);
    const testValues = [0.0, 1.0, -1.0, 12.375, -456.75, 1.5e10];
    const offset = 4;

    for (const val of testValues) {
      // Big-endian
      buf.writeFloatBE(val, offset);
      const decodedBE = readFloat32(buf, offset, false);
      assert.equal(decodedBE, buf.readFloatBE(offset), `Float32 BE mismatch for ${val}`);

      // Little-endian
      buf.writeFloatLE(val, offset);
      const decodedLE = readFloat32(buf, offset, true);
      assert.equal(decodedLE, buf.readFloatLE(offset), `Float32 LE mismatch for ${val}`);
    }
  }

  // 3. ieee754.read decodes 64-bit double-precision floats in big-endian and little-endian format across buffer offsets
  {
    const buf = Buffer.alloc(24);
    const testValues = [0.0, 1.0, -1.0, Math.PI, Math.E, 1.7976931348623157e+308, -1.23456789012345e-100];
    const offset = 8;

    for (const val of testValues) {
      // Big-endian
      buf.writeDoubleBE(val, offset);
      const decodedBE = readFloat64(buf, offset, false);
      assert.equal(decodedBE, buf.readDoubleBE(offset), `Float64 BE mismatch for ${val}`);

      // Little-endian
      buf.writeDoubleLE(val, offset);
      const decodedLE = readFloat64(buf, offset, true);
      assert.equal(decodedLE, buf.readDoubleLE(offset), `Float64 LE mismatch for ${val}`);
    }
  }

  // 4. ieee754.read correctly decodes special floating point values including infinities, NaN, and signed zeros
  {
    const buf = Buffer.alloc(32);

    // Infinities
    buf.writeFloatBE(Infinity, 0);
    assert.equal(readFloat32(buf, 0, false), Infinity, 'Float32 +Infinity must decode correctly');

    buf.writeFloatLE(-Infinity, 4);
    assert.equal(readFloat32(buf, 4, true), -Infinity, 'Float32 -Infinity must decode correctly');

    buf.writeDoubleBE(Infinity, 8);
    assert.equal(readFloat64(buf, 8, false), Infinity, 'Float64 +Infinity must decode correctly');

    buf.writeDoubleLE(-Infinity, 16);
    assert.equal(readFloat64(buf, 16, true), -Infinity, 'Float64 -Infinity must decode correctly');

    // NaN
    buf.writeFloatBE(NaN, 0);
    assert.ok(Number.isNaN(readFloat32(buf, 0, false)), 'Float32 NaN must decode to NaN');

    buf.writeDoubleLE(NaN, 8);
    assert.ok(Number.isNaN(readFloat64(buf, 8, true)), 'Float64 NaN must decode to NaN');

    // Signed zeros (+0 and -0)
    buf.writeFloatBE(0, 0);
    buf.writeFloatBE(-0, 4);
    const posZero32 = readFloat32(buf, 0, false);
    const negZero32 = readFloat32(buf, 4, false);
    assert.equal(posZero32, 0, 'Float32 +0 should equal 0');
    assert.equal(1 / posZero32, Infinity, 'Float32 +0 should have positive reciprocal infinity');
    assert.equal(negZero32, -0, 'Float32 -0 should equal -0');
    assert.equal(1 / negZero32, -Infinity, 'Float32 -0 should have negative reciprocal infinity');

    buf.writeDoubleLE(0, 8);
    buf.writeDoubleLE(-0, 16);
    const posZero64 = readFloat64(buf, 8, true);
    const negZero64 = readFloat64(buf, 16, true);
    assert.equal(posZero64, 0, 'Float64 +0 should equal 0');
    assert.equal(1 / posZero64, Infinity, 'Float64 +0 should have positive reciprocal infinity');
    assert.equal(negZero64, -0, 'Float64 -0 should equal -0');
    assert.equal(1 / negZero64, -Infinity, 'Float64 -0 should have negative reciprocal infinity');
  }

  // 5. ieee754.read decodes subnormal floating point numbers without losing subnormal precision
  {
    const buf = Buffer.alloc(16);

    // Smallest positive subnormal in float64 is Number.MIN_VALUE (approx 5e-324)
    buf.writeDoubleLE(Number.MIN_VALUE, 0);
    const readSubnormal64LE = readFloat64(buf, 0, true);
    assert.equal(readSubnormal64LE, Number.MIN_VALUE, 'Float64 subnormal MIN_VALUE LE must decode accurately');

    buf.writeDoubleBE(Number.MIN_VALUE, 8);
    const readSubnormal64BE = readFloat64(buf, 8, false);
    assert.equal(readSubnormal64BE, Number.MIN_VALUE, 'Float64 subnormal MIN_VALUE BE must decode accurately');

    // Subnormal float32: 2^-149 (approx 1.401298464324817e-45)
    const u8Subnormal32 = new Uint8Array([0x01, 0x00, 0x00, 0x00]);
    const expectedSubnormal32 = new DataView(u8Subnormal32.buffer).getFloat32(0, true);
    const readSubnormal32LE = ieee754.read(u8Subnormal32, 0, true, 23, 4);
    assert.equal(readSubnormal32LE, expectedSubnormal32, 'Float32 subnormal LE must decode accurately');
  }

  // 6. ieee754.read operates uniformly on standard Uint8Array instances and Node.js Buffer instances
  {
    const rawBytes = [0x40, 0x49, 0x0f, 0xdb];
    const uint8Arr = new Uint8Array(rawBytes);
    const nodeBuf = Buffer.from(rawBytes);

    const valUint8 = ieee754.read(uint8Arr, 0, false, 23, 4);
    const valBuf = ieee754.read(nodeBuf, 0, false, 23, 4);

    const expectedVal = new DataView(new Uint8Array(rawBytes).buffer).getFloat32(0, false);
    assert.equal(valUint8, expectedVal, 'Uint8Array read result must match DataView float32');
    assert.equal(valBuf, expectedVal, 'Buffer read result must match DataView float32');
    assert.equal(valUint8, valBuf, 'Uint8Array and Buffer reads must produce identical results');
  }

  console.log('All contract assertions for ieee754.read passed successfully.');
}

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