graceful-fs 4.2.11: graceful-fs readFile and writeFile with gracefulify patch

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: graceful-fs readFile and writeFile with gracefulify patch
Kind: HOW

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

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:4cc378ddd7ff12665041797c9f372616ea8e2d9c376c98694f65147a8618ac21","contract":["gracefulify patches a standard file system module with retry queue capabilities","readFile asynchronously reads file contents from disk with string and buffer encodings","writeFile asynchronously creates and writes data to disk","readFile returns ENOENT error when target file does not exist","readFileSync synchronously reads file contents created by writeFileSync","writeFile and readFile safely handle concurrent file system operations"],"goal":"graceful-fs readFile and writeFile with gracefulify patch","kind":"HOW","packages":["pkg:npm/graceful-fs@4.2.11"],"schemaVersion":1,"symbols":["gracefulify","readFile","writeFile"]},"contractCommand":["node","test/contract.js"],"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":["gracefulify","readFile","writeFile"],"verifierAdapter":"node-typescript@1"}

{
  "name": "graceful-fs-sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "graceful-fs-sample",
      "version": "1.0.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": "graceful-fs-sample",
  "version": "1.0.0",
  "private": true,
  "description": "CodeSampleX sample for graceful-fs",
  "main": "src/index.js",
  "dependencies": {
    "graceful-fs": "4.2.11"
  }
}

{
  "schemaVersion": 1,
  "goal": "graceful-fs readFile and writeFile with gracefulify patch",
  "kind": "HOW",
  "packages": [
    "pkg:npm/graceful-fs@4.2.11"
  ],
  "symbols": [
    "gracefulify",
    "readFile",
    "writeFile"
  ]
}

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

/**
 * Patch an existing fs instance using gracefulify.
 * @param {object} fsInstance - File system object to patch.
 * @returns {object} The patched file system object.
 */
function patchFs(fsInstance) {
  return gracefulFs.gracefulify(fsInstance);
}

/**
 * Read file contents asynchronously using graceful-fs.
 * @param {string} filePath - Path to the file.
 * @param {string|object} [options] - Encoding or options object.
 * @returns {Promise<string|Buffer>} File contents.
 */
function readFileAsync(filePath, options = 'utf8') {
  return new Promise((resolve, reject) => {
    gracefulFs.readFile(filePath, options, (err, data) => {
      if (err) {
        return reject(err);
      }
      resolve(data);
    });
  });
}

/**
 * Write file contents asynchronously using graceful-fs.
 * @param {string} filePath - Path to the file.
 * @param {string|Buffer} data - Data to write.
 * @param {string|object} [options] - Encoding or options object.
 * @returns {Promise<void>}
 */
function writeFileAsync(filePath, data, options = 'utf8') {
  return new Promise((resolve, reject) => {
    gracefulFs.writeFile(filePath, data, options, (err) => {
      if (err) {
        return reject(err);
      }
      resolve();
    });
  });
}

/**
 * Read file contents synchronously using graceful-fs.
 * @param {string} filePath - Path to the file.
 * @param {string|object} [options] - Encoding or options object.
 * @returns {string|Buffer}
 */
function readFileSync(filePath, options = 'utf8') {
  return gracefulFs.readFileSync(filePath, options);
}

/**
 * Write file contents synchronously using graceful-fs.
 * @param {string} filePath - Path to the file.
 * @param {string|Buffer} data - Data to write.
 * @param {string|object} [options] - Encoding or options object.
 */
function writeFileSync(filePath, data, options = 'utf8') {
  gracefulFs.writeFileSync(filePath, data, options);
}

module.exports = {
  gracefulFs,
  patchFs,
  readFileAsync,
  writeFileAsync,
  readFileSync,
  writeFileSync,
};

const assert = require('node:assert/strict');
const path = require('node:path');
const os = require('node:os');
const fs = require('node:fs');
const {
  gracefulFs,
  patchFs,
  readFileAsync,
  writeFileAsync,
  readFileSync,
  writeFileSync,
} = require('../src/index.js');

async function main() {
  const testRoot = path.join(
    os.tmpdir(),
    `gfs-contract-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
  );
  fs.mkdirSync(testRoot, { recursive: true });

  try {
    // Contract 1: gracefulify patches a standard file system module with retry queue capabilities
    {
      const customFs = Object.assign({}, fs);
      assert.strictEqual(typeof customFs.gracefulify, 'undefined');
      const patched = patchFs(customFs);
      assert.strictEqual(typeof patched.gracefulify, 'function');
      assert.strictEqual(typeof patched.readFile, 'function');
      assert.strictEqual(typeof patched.writeFile, 'function');
    }

    // Contract 2: readFile asynchronously reads file contents from disk with string and buffer encodings
    {
      const filePath = path.join(testRoot, 'read_sample.txt');
      const sampleText = 'Hello Graceful-FS Async Read!';
      fs.writeFileSync(filePath, sampleText, 'utf8');

      const textResult = await readFileAsync(filePath, 'utf8');
      assert.strictEqual(textResult, sampleText);

      const bufferResult = await readFileAsync(filePath, null);
      assert.ok(Buffer.isBuffer(bufferResult));
      assert.strictEqual(bufferResult.toString('utf8'), sampleText);
    }

    // Contract 3: writeFile asynchronously creates and writes data to disk
    {
      const filePath = path.join(testRoot, 'write_sample.txt');
      const sampleContent = 'Async written payload via graceful-fs';

      await writeFileAsync(filePath, sampleContent, 'utf8');
      assert.ok(fs.existsSync(filePath));
      assert.strictEqual(fs.readFileSync(filePath, 'utf8'), sampleContent);
    }

    // Contract 4: readFile returns ENOENT error when target file does not exist
    {
      const missingPath = path.join(testRoot, 'non_existent_file.txt');
      let caughtErr = null;
      try {
        await readFileAsync(missingPath, 'utf8');
      } catch (err) {
        caughtErr = err;
      }
      assert.ok(caughtErr !== null);
      assert.strictEqual(caughtErr.code, 'ENOENT');
    }

    // Contract 5: readFileSync synchronously reads file contents created by writeFileSync
    {
      const syncPath = path.join(testRoot, 'sync_sample.txt');
      const syncData = 'Synchronous write and read validation data';

      writeFileSync(syncPath, syncData, 'utf8');
      assert.ok(fs.existsSync(syncPath));

      const syncResult = readFileSync(syncPath, 'utf8');
      assert.strictEqual(syncResult, syncData);
    }

    // Contract 6: writeFile and readFile safely handle concurrent file system operations
    {
      const concurrentTasks = [];
      const count = 20;

      for (let i = 0; i < count; i++) {
        const itemPath = path.join(testRoot, `concurrent_${i}.txt`);
        const itemContent = `Concurrent item ${i} data payload`;
        concurrentTasks.push(
          writeFileAsync(itemPath, itemContent, 'utf8').then(async () => {
            const readBack = await readFileAsync(itemPath, 'utf8');
            assert.strictEqual(readBack, itemContent);
          })
        );
      }

      await Promise.all(concurrentTasks);
    }

    console.log('All pkg:npm/graceful-fs@4.2.11 contracts passed successfully.');
  } finally {
    try {
      fs.rmSync(testRoot, { recursive: true, force: true });
    } catch (_) {}
  }
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});