fd-slicer 1.1.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/fd-slicer@1.1.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/fd-slicer@1.1.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:6765fcd0669163fd00bded4c4761fa70924b1116c0e35583441c02ca68918753","contract":["createFromFd creates read streams that slice specific byte ranges from a file descriptor","createFromFd creates write streams that write bytes at specific offsets in a file descriptor","createFromFd reads and writes chunks concurrently with serialized operations via read and write methods","createFromFd with autoClose option closes the underlying file descriptor when all references are unrefed","createFromBuffer creates read streams that slice sections from an in-memory buffer","createFromBuffer creates write streams that write slices into an in-memory buffer"],"goal":"verify pkg:npm/fd-slicer@1.1.0","kind":"HOW","packages":["pkg:npm/fd-slicer@1.1.0"],"schemaVersion":1},"contractCommand":["node","test/contract.cjs"],"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/fd-slicer@1.1.0"],"schemaVersion":1,"subject":"pkg:npm/fd-slicer@1.1.0","verifierAdapter":"node-typescript@1"}

'use strict';

const fdSlicer = require('fd-slicer');

function sliceFd(fd, options) {
  return fdSlicer.createFromFd(fd, options);
}

function sliceBuffer(buffer, options) {
  return fdSlicer.createFromBuffer(buffer, options);
}

module.exports = {
  sliceFd,
  sliceBuffer,
  createFromFd: fdSlicer.createFromFd,
  createFromBuffer: fdSlicer.createFromBuffer,
  FdSlicer: fdSlicer.FdSlicer,
  BufferSlicer: fdSlicer.BufferSlicer
};

{
  "name": "sample-fd-slicer",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-fd-slicer",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "fd-slicer": "1.1.0"
      }
    },
    "node_modules/fd-slicer": {
      "version": "1.1.0",
      "resolved": "https://registry.npmjs.org/fd-slicer/-/fd-slicer-1.1.0.tgz",
      "integrity": "sha512-cE1qsB/VwyQozZ+q1dGxR8LBYNZeofhEdUNGSMbQD3Gw2lAzX9Zb3uIU6Ebc/Fmyjo9AWWfnn0AUCHqtevs/8g==",
      "license": "MIT",
      "dependencies": {
        "pend": "~1.2.0"
      }
    },
    "node_modules/pend": {
      "version": "1.2.0",
      "resolved": "https://registry.npmjs.org/pend/-/pend-1.2.0.tgz",
      "integrity": "sha512-F3asv42UuXchdzt+xXqfW1OGlVBe+mxa2mqI0pg5yAHZPvFmY3Y6drSf/GQ1A86WgWEN9Kzh/WrgKa6iGcHXLg==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-fd-slicer",
  "version": "1.0.0",
  "private": true,
  "description": "Code sample verifying fd-slicer",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.cjs"
  },
  "dependencies": {
    "fd-slicer": "1.1.0"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/fd-slicer@1.1.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/fd-slicer@1.1.0"
  ]
}

'use strict';

const assert = require('node:assert/strict');
const fs = require('node:fs');
const path = require('node:path');
const os = require('node:os');
const fdSlicer = require('fd-slicer');
const { sliceFd, sliceBuffer } = require('../index.js');

async function runContract() {
  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'csx-contract-fdslicer-'));
  const testFile = path.join(tmpDir, 'test-data.bin');

  try {
    // 1. createFromFd creates read streams that slice specific byte ranges from a file descriptor
    {
      const content = Buffer.from('ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789');
      fs.writeFileSync(testFile, content);

      const fd = fs.openSync(testFile, 'r');
      const slicer = sliceFd(fd);

      const readChunk = (start, end) => {
        return new Promise((resolve, reject) => {
          const stream = slicer.createReadStream({ start, end });
          const chunks = [];
          stream.on('data', (chunk) => chunks.push(chunk));
          stream.on('end', () => resolve(Buffer.concat(chunks)));
          stream.on('error', reject);
        });
      };

      const part1 = await readChunk(0, 4);
      const part2 = await readChunk(10, 15);
      const part3 = await readChunk(26, 36);

      assert.equal(part1.toString('utf8'), 'ABCD', 'Slice 0..4 should match ABCD');
      assert.equal(part2.toString('utf8'), 'KLMNO', 'Slice 10..15 should match KLMNO');
      assert.equal(part3.toString('utf8'), '0123456789', 'Slice 26..36 should match 0123456789');

      fs.closeSync(fd);
    }

    // 2. createFromFd creates write streams that write bytes at specific offsets in a file descriptor
    {
      const initialBuffer = Buffer.alloc(20, 0x20);
      fs.writeFileSync(testFile, initialBuffer);

      const fd = fs.openSync(testFile, 'r+');
      const slicer = sliceFd(fd);

      const writeChunk = (data, start) => {
        return new Promise((resolve, reject) => {
          const stream = slicer.createWriteStream({ start });
          stream.on('finish', resolve);
          stream.on('error', reject);
          stream.end(Buffer.from(data));
        });
      };

      await writeChunk('HELLO', 0);
      await writeChunk('WORLD', 10);

      fs.closeSync(fd);

      const result = fs.readFileSync(testFile, 'utf8');
      assert.equal(result.slice(0, 5), 'HELLO');
      assert.equal(result.slice(10, 15), 'WORLD');
    }

    // 3. createFromFd reads and writes chunks concurrently with serialized operations via read and write methods
    {
      const fd = fs.openSync(testFile, 'w+');
      const slicer = sliceFd(fd);

      const pWrite = (buf, offset, length, pos) => {
        return new Promise((resolve, reject) => {
          slicer.write(buf, offset, length, pos, (err, written) => {
            if (err) return reject(err);
            resolve(written);
          });
        });
      };

      const pRead = (buf, offset, length, pos) => {
        return new Promise((resolve, reject) => {
          slicer.read(buf, offset, length, pos, (err, bytesRead) => {
            if (err) return reject(err);
            resolve(bytesRead);
          });
        });
      };

      const dataA = Buffer.from('FOOBAR');
      const dataB = Buffer.from('BAZQUX');

      await Promise.all([
        pWrite(dataA, 0, dataA.length, 0),
        pWrite(dataB, 0, dataB.length, 10)
      ]);

      const readBufA = Buffer.alloc(6);
      const readBufB = Buffer.alloc(6);

      await Promise.all([
        pRead(readBufA, 0, 6, 0),
        pRead(readBufB, 0, 6, 10)
      ]);

      assert.equal(readBufA.toString('utf8'), 'FOOBAR');
      assert.equal(readBufB.toString('utf8'), 'BAZQUX');

      fs.closeSync(fd);
    }

    // 4. createFromFd with autoClose option closes the underlying file descriptor when all references are unrefed
    {
      const fd = fs.openSync(testFile, 'r');
      const slicer = sliceFd(fd, { autoClose: true });

      const closedPromise = new Promise((resolve) => {
        slicer.on('close', resolve);
      });

      const stream1 = slicer.createReadStream({ start: 0, end: 2 });
      const stream2 = slicer.createReadStream({ start: 2, end: 4 });

      await new Promise((resolve) => {
        stream1.on('data', () => {});
        stream1.on('end', resolve);
      });

      await new Promise((resolve) => {
        stream2.on('data', () => {});
        stream2.on('end', resolve);
      });

      await closedPromise;

      assert.throws(() => {
        fs.fstatSync(fd);
      }, /EBADF/, 'File descriptor should be closed after autoClose triggers');
    }

    // 5. createFromBuffer creates read streams that slice sections from an in-memory buffer
    {
      const buffer = Buffer.from('The quick brown fox jumps over the lazy dog');
      const slicer = sliceBuffer(buffer);

      const stream = slicer.createReadStream({ start: 4, end: 9 });
      const chunks = [];
      await new Promise((resolve, reject) => {
        stream.on('data', (c) => chunks.push(c));
        stream.on('end', resolve);
        stream.on('error', reject);
      });

      assert.equal(Buffer.concat(chunks).toString('utf8'), 'quick');
    }

    // 6. createFromBuffer creates write streams that write slices into an in-memory buffer
    {
      const buffer = Buffer.alloc(20, 0);
      const slicer = sliceBuffer(buffer);

      const stream = slicer.createWriteStream({ start: 2 });
      await new Promise((resolve, reject) => {
        stream.on('finish', resolve);
        stream.on('error', reject);
        stream.end(Buffer.from('MUTATED'));
      });

      assert.equal(buffer.slice(2, 9).toString('utf8'), 'MUTATED');
    }

    console.log('All contract assertions passed successfully.');
  } finally {
    fs.rmSync(tmpDir, { recursive: true, force: true });
  }
}

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