graceful-fs 4.2.11: readFile

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.readFile 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.readFile

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:f68c2b4cdf6149db96dab2e8999a61bff35ef80d100c1b0310f4f31881f7da53","contract":["graceful-fs.readFile reads file contents as a Buffer when no encoding is specified","graceful-fs.readFile reads file contents as a string when utf8 encoding option is specified","graceful-fs.readFile accepts options object specifying encoding","graceful-fs.readFile yields an ENOENT error when target file does not exist","graceful-fs.promises.readFile returns a promise resolving to file contents"],"goal":"verify graceful-fs.readFile in pkg:npm/graceful-fs@4.2.11","kind":"HOW","packages":["pkg:npm/graceful-fs@4.2.11"],"schemaVersion":1,"symbols":["graceful-fs.readFile"]},"contractCommand":["node","test/contract.cjs"],"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.readFile"],"verifierAdapter":"node-typescript@1"}

'use strict';

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

/**
 * Asynchronously reads file content using callback-based graceful-fs.readFile.
 * @param {string} filePath
 * @param {string|object} [options]
 * @returns {Promise<string|Buffer>}
 */
function readWithCallback(filePath, options) {
  return new Promise((resolve, reject) => {
    gracefulFs.readFile(filePath, options, (err, data) => {
      if (err) {
        return reject(err);
      }
      resolve(data);
    });
  });
}

/**
 * Asynchronously reads file content using graceful-fs.promises.readFile.
 * @param {string} filePath
 * @param {string|object} [options]
 * @returns {Promise<string|Buffer>}
 */
async function readWithPromise(filePath, options) {
  return gracefulFs.promises.readFile(filePath, options);
}

module.exports = {
  gracefulFs,
  readWithCallback,
  readWithPromise
};

{
  "name": "sample-graceful-fs-readfile",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-graceful-fs-readfile",
      "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-readfile",
  "version": "1.0.0",
  "private": true,
  "description": "verify graceful-fs.readFile in pkg:npm/graceful-fs@4.2.11",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.cjs"
  },
  "dependencies": {
    "graceful-fs": "4.2.11"
  },
  "license": "MIT-0"
}

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

'use strict';

const assert = require('node:assert/strict');
const path = require('node:path');
const os = require('node:os');
const fs = require('node:fs');
const gracefulFs = require('graceful-fs');
const { readWithCallback, readWithPromise } = require('../index.js');

async function run() {
  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gfs-readfile-test-'));
  const testFile = path.join(tmpDir, 'test.txt');
  const missingFile = path.join(tmpDir, 'missing.txt');
  const expectedContent = 'Hello graceful-fs readFile content!';

  try {
    fs.writeFileSync(testFile, expectedContent, 'utf8');

    // 1. graceful-fs.readFile reads file contents as a Buffer when no encoding is provided
    await new Promise((resolve, reject) => {
      gracefulFs.readFile(testFile, (err, data) => {
        if (err) return reject(err);
        try {
          assert.ok(Buffer.isBuffer(data), 'readFile without encoding must return Buffer');
          assert.strictEqual(data.toString('utf8'), expectedContent);
          resolve();
        } catch (e) {
          reject(e);
        }
      });
    });

    // 2. graceful-fs.readFile reads file contents as a string when utf8 encoding option is specified
    await new Promise((resolve, reject) => {
      gracefulFs.readFile(testFile, 'utf8', (err, data) => {
        if (err) return reject(err);
        try {
          assert.strictEqual(typeof data, 'string', 'readFile with utf8 must return string');
          assert.strictEqual(data, expectedContent);
          resolve();
        } catch (e) {
          reject(e);
        }
      });
    });

    // 3. graceful-fs.readFile accepts options object specifying encoding
    await new Promise((resolve, reject) => {
      gracefulFs.readFile(testFile, { encoding: 'utf8' }, (err, data) => {
        if (err) return reject(err);
        try {
          assert.strictEqual(data, expectedContent);
          resolve();
        } catch (e) {
          reject(e);
        }
      });
    });

    // 4. graceful-fs.readFile yields an ENOENT error when target file does not exist
    await new Promise((resolve, reject) => {
      gracefulFs.readFile(missingFile, 'utf8', (err, data) => {
        try {
          assert.ok(err !== null, 'readFile on missing file must yield error');
          assert.strictEqual(err.code, 'ENOENT');
          assert.strictEqual(typeof data, 'undefined');
          resolve();
        } catch (e) {
          reject(e);
        }
      });
    });

    // 5. graceful-fs.promises.readFile returns a promise resolving to file contents
    const promiseData = await gracefulFs.promises.readFile(testFile, 'utf8');
    assert.strictEqual(promiseData, expectedContent);

    // 6. Helper functions from index.js
    const helperCallbackData = await readWithCallback(testFile, 'utf8');
    assert.strictEqual(helperCallbackData, expectedContent);

    const helperPromiseData = await readWithPromise(testFile, 'utf8');
    assert.strictEqual(helperPromiseData, expectedContent);

    console.log('Contract tests passed successfully.');
    process.exit(0);
  } finally {
    try {
      if (fs.existsSync(tmpDir)) {
        fs.rmSync(tmpDir, { recursive: true, force: true });
      }
    } catch (_) {}
  }
}

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