graceful-fs 4.2.11: statSync

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

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:ba21ac9f46171d85e28369b8bee5a9de1aa2ffe32fa156c352dc78c181351070","contract":["gracefulFs.statSync returns a fs.Stats instance for an existing file with isFile returning true","gracefulFs.statSync returns a fs.Stats instance for an existing directory with isDirectory returning true","gracefulFs.statSync supports bigint option returning numerical metadata as BigInt values","gracefulFs.statSync supports throwIfNoEntry option returning undefined when target path does not exist","gracefulFs.statSync throws ENOENT when target path does not exist and throwIfNoEntry is default","gracefulFs.statSync throws TypeError when path argument is not a valid string, Buffer, or URL"],"goal":"verify graceful-fs.statSync in pkg:npm/graceful-fs@4.2.11","kind":"HOW","packages":["pkg:npm/graceful-fs@4.2.11"],"schemaVersion":1,"symbols":["graceful-fs.statSync"]},"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.statSync"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-graceful-fs-stat-sync",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-graceful-fs-stat-sync",
      "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-stat-sync",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room code sample for graceful-fs.statSync in graceful-fs@4.2.11",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "graceful-fs": "4.2.11"
  }
}

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

'use strict';

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

/**
 * Retrieves file or directory statistics using graceful-fs.statSync.
 *
 * @param {string|Buffer|URL} targetPath - Path to the file or directory.
 * @param {object} [options] - Options object (e.g. { bigint, throwIfNoEntry }).
 * @returns {fs.Stats|fs.BigIntStats|undefined} Stats object, or undefined if throwIfNoEntry is false and target is missing.
 */
function getStatSync(targetPath, options) {
  return fs.statSync(targetPath, options);
}

module.exports = {
  gracefulFs: fs,
  getStatSync
};

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

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

function testAll() {
  // Verify export functions
  assert.equal(typeof gracefulFs.statSync, 'function', 'gracefulFs.statSync must be a function');
  assert.equal(typeof getStatSync, 'function', 'getStatSync helper must be a function');

  const baseDir = gracefulFs.mkdtempSync(path.join(os.tmpdir(), 'gfs-statsync-'));

  try {
    const testFile = path.join(baseDir, 'test-file.txt');
    gracefulFs.writeFileSync(testFile, 'Hello CodeSampleX!', 'utf8');

    // 1. gracefulFs.statSync returns a fs.Stats instance for an existing file with isFile returning true
    const fileStats = getStatSync(testFile);
    assert.ok(fileStats, 'fileStats must be defined');
    assert.equal(typeof fileStats.isFile, 'function', 'fileStats.isFile must be a function');
    assert.equal(fileStats.isFile(), true, 'fileStats.isFile() must return true for regular file');
    assert.equal(fileStats.isDirectory(), false, 'fileStats.isDirectory() must return false for regular file');
    assert.equal(fileStats.size, 18, 'fileStats.size must match written content byte length');

    // 2. gracefulFs.statSync returns a fs.Stats instance for an existing directory with isDirectory returning true
    const dirStats = getStatSync(baseDir);
    assert.ok(dirStats, 'dirStats must be defined');
    assert.equal(typeof dirStats.isDirectory, 'function', 'dirStats.isDirectory must be a function');
    assert.equal(dirStats.isDirectory(), true, 'dirStats.isDirectory() must return true for directory');
    assert.equal(dirStats.isFile(), false, 'dirStats.isFile() must return false for directory');

    // 3. gracefulFs.statSync supports bigint option returning numerical metadata as BigInt values
    const bigintStats = getStatSync(testFile, { bigint: true });
    assert.ok(bigintStats, 'bigintStats must be defined');
    assert.equal(typeof bigintStats.size, 'bigint', 'bigintStats.size must be of type bigint');
    assert.equal(bigintStats.size, 18n, 'bigintStats.size must match BigInt 18n');
    assert.equal(typeof bigintStats.ino, 'bigint', 'bigintStats.ino must be of type bigint');
    assert.equal(typeof bigintStats.mode, 'bigint', 'bigintStats.mode must be of type bigint');

    // 4. gracefulFs.statSync supports throwIfNoEntry option returning undefined when target path does not exist
    const nonExistentPath = path.join(baseDir, 'non-existent-target.txt');
    const noEntryResult = getStatSync(nonExistentPath, { throwIfNoEntry: false });
    assert.equal(noEntryResult, undefined, 'statSync with throwIfNoEntry: false must return undefined for missing path');

    // 5. gracefulFs.statSync throws ENOENT when target path does not exist and throwIfNoEntry is default
    assert.throws(
      () => getStatSync(nonExistentPath),
      (err) => err && (err.code === 'ENOENT' || (err.message && err.message.includes('ENOENT'))),
      'statSync must throw ENOENT when path does not exist'
    );

    // 6. gracefulFs.statSync throws TypeError when path argument is not a valid string, Buffer, or URL
    assert.throws(
      () => getStatSync(12345),
      { name: 'TypeError' },
      'statSync must throw TypeError when path argument is not string, Buffer, or URL'
    );
  } finally {
    if (gracefulFs.existsSync(baseDir)) {
      gracefulFs.rmSync(baseDir, { recursive: true, force: true });
    }
  }

  console.log('All graceful-fs.statSync contract assertions passed successfully.');
}

testAll();