graceful-fs 4.2.11: gracefulify

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 graceful-fs.gracefulify in pkg:npm/graceful-fs@4.2.11
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/graceful-fs@4.2.11
Demonstrate these symbols/APIs:
  - graceful-fs.gracefulify

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:e4e74600ef7654291626e26fe411343e36e2fdc701a6eb3669b519397583c911","contract":["assert gracefulify is exported as a function by graceful-fs","assert gracefulify mutates and returns the target object","assert gracefulify attaches gracefulify method to target object","assert gracefulified fs asynchronously writes and reads files","assert gracefulified fs reads directory contents","assert gracefulified fs provides createReadStream and createWriteStream","assert gracefulified fs enqueues and retries file operations upon EMFILE error until closed"],"goal":"verify graceful-fs.gracefulify in pkg:npm/graceful-fs@4.2.11","kind":"HOW","packages":["pkg:npm/graceful-fs@4.2.11"],"schemaVersion":1,"symbols":["graceful-fs.gracefulify"]},"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/graceful-fs@4.2.11"],"schemaVersion":1,"subject":"pkg:npm/graceful-fs@4.2.11","symbols":["graceful-fs.gracefulify"],"verifierAdapter":"node-typescript@1"}

const gracefulFs = require('graceful-fs');

/**
 * Applies graceful-fs patches to the provided fs module or fs-like object.
 *
 * @param {object} fsModule - The target fs object to monkeypatch.
 * @returns {object} The patched fs object.
 */
function applyGracefulify(fsModule) {
  return gracefulFs.gracefulify(fsModule);
}

module.exports = {
  gracefulFs,
  gracefulify: gracefulFs.gracefulify,
  applyGracefulify,
};

{
  "name": "sample-graceful-fs",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-graceful-fs",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "graceful-fs": "4.2.11"
      }
    },
    "node_modules/graceful-fs": {
      "version": "4.2.11",
      "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz",
      "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==",
      "license": "ISC"
    }
  }
}

{
  "name": "sample-graceful-fs",
  "version": "1.0.0",
  "description": "Clean-room sample verifying graceful-fs.gracefulify in pkg:npm/graceful-fs@4.2.11",
  "main": "index.js",
  "type": "commonjs",
  "license": "MIT-0",
  "dependencies": {
    "graceful-fs": "4.2.11"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify graceful-fs.gracefulify in pkg:npm/graceful-fs@4.2.11",
  "kind": "HOW",
  "packages": [
    "pkg:npm/graceful-fs@4.2.11"
  ],
  "symbols": [
    "graceful-fs.gracefulify"
  ]
}

import assert from 'node:assert';
import fs from 'node:fs';
import path from 'node:path';
import os from 'node:os';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const {
  gracefulFs,
  gracefulify,
  applyGracefulify,
} = require('../index.js');

const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'graceful-fs-contract-'));

try {
  // Contract 1: assert gracefulify is exported as a function by graceful-fs
  assert.strictEqual(typeof gracefulify, 'function', 'gracefulify must be a function');
  assert.strictEqual(typeof gracefulFs.gracefulify, 'function', 'gracefulFs.gracefulify must be a function');

  // Contract 2: assert gracefulify mutates and returns the target object
  const targetObj = Object.assign({}, fs);
  const returnedObj = applyGracefulify(targetObj);
  assert.strictEqual(returnedObj, targetObj, 'gracefulify must return the exact passed target object');

  // Contract 3: assert gracefulify attaches gracefulify method to target object
  assert.strictEqual(typeof targetObj.gracefulify, 'function', 'target object must have gracefulify method attached');

  // Contract 4: assert gracefulified fs asynchronously writes and reads files
  const testFile = path.join(tmpDir, 'test-rw.txt');
  const payload = 'graceful-fs-payload-verification';
  await new Promise((resolve, reject) => {
    targetObj.writeFile(testFile, payload, 'utf8', (err) => {
      if (err) return reject(err);
      targetObj.readFile(testFile, 'utf8', (readErr, content) => {
        if (readErr) return reject(readErr);
        assert.strictEqual(content, payload, 'file contents must match written payload');
        resolve();
      });
    });
  });

  // Contract 5: assert gracefulified fs reads directory contents
  await new Promise((resolve, reject) => {
    targetObj.readdir(tmpDir, (err, files) => {
      if (err) return reject(err);
      assert.ok(files.includes('test-rw.txt'), 'directory entries must include written file');
      resolve();
    });
  });

  // Contract 6: assert gracefulified fs provides createReadStream and createWriteStream
  assert.strictEqual(typeof targetObj.createReadStream, 'function', 'createReadStream must be a function');
  assert.strictEqual(typeof targetObj.createWriteStream, 'function', 'createWriteStream must be a function');
  const streamFile = path.join(tmpDir, 'test-stream.txt');
  const streamPayload = 'streamed-verification-data';
  await new Promise((resolve, reject) => {
    const ws = targetObj.createWriteStream(streamFile);
    ws.on('finish', resolve);
    ws.on('error', reject);
    ws.write(streamPayload);
    ws.end();
  });
  const streamRead = await new Promise((resolve, reject) => {
    const rs = targetObj.createReadStream(streamFile, { encoding: 'utf8' });
    let buf = '';
    rs.on('data', chunk => { buf += chunk; });
    rs.on('end', () => resolve(buf));
    rs.on('error', reject);
  });
  assert.strictEqual(streamRead, streamPayload, 'streamed read content must match streamed write');

  // Contract 7: assert gracefulified fs enqueues and retries file operations upon EMFILE error until closed
  let callCount = 0;
  const mockTarget = {
    close: fs.close,
    closeSync: fs.closeSync,
    readFile: (p, opt, cb) => {
      callCount++;
      if (callCount === 1) {
        const emfileErr = new Error('EMFILE: too many open files');
        emfileErr.code = 'EMFILE';
        return cb(emfileErr);
      }
      return cb(null, 'retry-success');
    },
  };
  applyGracefulify(mockTarget);

  const retryResult = await new Promise((resolve, reject) => {
    mockTarget.readFile('/virtual/path', 'utf8', (err, data) => {
      if (err) return reject(err);
      resolve(data);
    });

    setTimeout(() => {
      try {
        const fd = fs.openSync(testFile, 'r');
        fs.closeSync(fd);
      } catch (err) {
        reject(err);
      }
    }, 25);
  });

  assert.strictEqual(callCount, 2, 'EMFILE error must cause operation to be retried');
  assert.strictEqual(retryResult, 'retry-success', 'retried operation must deliver final callback value');

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