Node.js fs — readFileSync Stalled My API Gateway

const fs = require('fs');
const path = require('path');

const configFilePath = path.join(__dirname, 'app-config.json');

// ─── SYNCHRONOUS — blocks the entire thread until the disk read completes ───
// This is acceptable here because we are at startup, before server.listen().
// If the config is missing or unreadable, we want to crash loudly with a clear
// error message — not silently proceed with undefined configuration.
try {
  const rawConfig = fs.readFileSync(configFilePath, 'utf8'); // returns a string directly
  const config = JSON.parse(rawConfig);
  console.log('Config loaded synchronously:', config.appName);
} catch (startupError) {
  // Crash at startup with a useful message — much better than crashing
  // in a request handler later with a confusing ENOENT mid-traffic.
  console.error('Could not load config. Aborting startup:', startupError.message);
  process.exit(1);
}

// ─── ASYNCHRONOUS — hands I/O to the OS, returns control to the event loop ───
// Use this inside request handlers, scheduled jobs, and anywhere after startup.
// The event loop stays free to handle other work while the disk responds.
fs.readFile(configFilePath, 'utf8', (readError, fileContents) => {
  // Node's error-first callback pattern: the first argument is always the error
  // (or null on success). Always check it. Always return after handling it.
  if (readError) {
    console.error('Async read failed:', readError.message);
    return; // do not let execution fall through to the JSON.parse below
  }

  const config = JSON.parse(fileContents);
  console.log('Config loaded asynchronously:', config.appName);
});

// This line executes immediately after fs.readFile() registers the I/O request —
// before the disk responds. This is the proof that the event loop stayed free.
console.log('This line prints BEFORE the async callback fires — proof the thread is free');

// The modern approach — fs/promises with async/await for all new code
const { readFile, writeFile, mkdir, access, constants } = require('fs/promises');
const path = require('path');

// ─── Real-world pattern: load multiple config files in parallel at startup ───
// This is the correct way to do multi-file startup loading.
// Sequential awaits would take the sum of all read times.
// Promise.all takes only the time of the slowest single read.
async function loadApplicationConfig() {
  const configDir = path.join(__dirname, 'config');

  // Verify the config directory exists before attempting reads —
  // a clearer error message than the ENOENT that would follow.
  try {
    await access(configDir, constants.R_OK);
  } catch {
    throw new Error(`Config directory not found or not readable: ${configDir}`);
  }

  try {
    // All three reads start simultaneously — none waits for the others to finish.
    // If any one fails, the entire Promise.all rejects and the catch block fires.
    const [dbConfigRaw, serverConfigRaw, featureFlagsRaw] = await Promise.all([
      readFile(path.join(configDir, 'database.json'), 'utf8'),
      readFile(path.join(configDir, 'server.json'), 'utf8'),
      readFile(path.join(configDir, 'features.json'), 'utf8'),
    ]);

    // Parse only after confirming all three reads succeeded.
    // JSON.parse is synchronous — keep it outside the async boundary.
    const dbConfig     = JSON.parse(dbConfigRaw);
    const serverConfig = JSON.parse(serverConfigRaw);
    const featureFlags = JSON.parse(featureFlagsRaw);

    console.log('All configs loaded in parallel');
    console.log(`   DB host:     ${dbConfig.host}`);
    console.log(`   Server port: ${serverConfig.port}`);
    console.log(`   Dark mode:   ${featureFlags.darkMode}`);

    return { dbConfig, serverConfig, featureFlags };
  } catch (loadError) {
    // One try/catch covers all three reads — if any file is missing or
    // unreadable, this fires with a clear error. No nested callbacks,
    // no separate error checks per file.
    console.error('Config load failed:', loadError.message);
    throw loadError; // re-throw so the caller knows startup failed
  }
}

// ─── Writing a file — creating nested output directories first ───
// The { recursive: true } option on mkdir is the Node.js equivalent of
// 'mkdir -p' — it creates all missing parent directories and does not
// throw if the directory already exists.
async function saveProcessedReport(reportData) {
  const outputDir  = path.join(__dirname, 'reports');
  const outputFile = path.join(outputDir, `report-${Date.now()}.json`);

  try {
    await mkdir(outputDir, { recursive: true });

    // JSON.stringify with indent=2 produces human-readable output —
    // useful for reports that operations teams might read directly.
    await writeFile(outputFile, JSON.stringify(reportData, null, 2), 'utf8');

    console.log(`Report saved to: ${outputFile}`);
    return outputFile;
  } catch (writeError) {
    console.error('Failed to save report:', writeError.message);
    throw writeError;
  }
}

(async () => {
  const config = await loadApplicationConfig();
  await saveProcessedReport({ totalOrders: 1482, revenue: 94300, currency: 'USD' });
})();

const fs       = require('fs');
const zlib     = require('zlib');
const readline = require('readline');
const path     = require('path');
const { pipeline } = require('stream/promises');

const sourceLogFile    = path.join(__dirname, 'server.log');
const compressedOutput = path.join(__dirname, 'server.log.gz');

// ─── Pattern 1: Compress a large file with pipeline() from stream/promises ───
// pipeline() is preferred over pipe() in production because it:
//  - propagates errors from any stream in the chain
//  - destroys all streams on failure (preventing file descriptor leaks)
//  - returns a Promise compatible with async/await
async function compressLogFile(source, destination) {
  const readStream  = fs.createReadStream(source);   // reads in ~64KB chunks
  const gzipStream  = zlib.createGzip({ level: 6 }); // compress each chunk
  const writeStream = fs.createWriteStream(destination);

  // pipeline() wires backpressure between all three streams automatically.
  // If gzip falls behind the reader, the reader pauses. No manual event wiring needed.
  await pipeline(readStream, gzipStream, writeStream);

  console.log(`Compressed: ${source} -> ${destination}`);
  return destination;
}

// ─── Pattern 2: Process a large text file line-by-line with readline ───
// readline + createReadStream is the memory-efficient way to handle
// CSV, NDJSON, log files, or any line-structured text file.
// Memory cost: one line at a time, not the entire file.
async function countLinesInLargeFile(filePath) {
  const fileStream = fs.createReadStream(filePath, { encoding: 'utf8' });

  const lineInterface = readline.createInterface({
    input: fileStream,
    crlfDelay: Infinity, // treat \r\n as a single newline — handles Windows line endings
  });

  let lineCount = 0;
  let errorCount = 0;

  // for-await-of on readline gives you one line per iteration.
  // The loop pauses between iterations — readline and createReadStream
  // handle backpressure so the file is not read faster than lines are processed.
  for await (const line of lineInterface) {
    lineCount++;

    // Example: count malformed JSON lines in an NDJSON log file
    if (line.trim()) {
      try {
        JSON.parse(line);
      } catch {
        errorCount++;
      }
    }
  }

  console.log(`Lines processed: ${lineCount.toLocaleString()}`);
  console.log(`Parse errors: ${errorCount.toLocaleString()}`);
  return { lineCount, errorCount };
}

(async () => {
  await compressLogFile(sourceLogFile, compressedOutput);
  const { lineCount, errorCount } = await countLinesInLargeFile(sourceLogFile);
  await fs.promises.writeFile(
    path.join(__dirname, 'summary.json'),
    JSON.stringify({ lineCount, errorCount, processedAt: new Date().toISOString() }, null, 2),
    'utf8'
  );
})();

const fs   = require('fs');
const path = require('path');

// ─── Pattern 1: Watch a config file and reload on change ───
// The debounce is not optional — without it, a single save fires
// the callback 2-3 times due to atomic write patterns in text editors.
function watchConfigFile(filePath, onChangeCallback) {
  // Verify the file exists before attaching the watcher.
  // A watcher on a non-existent file silently does nothing on some OSes.
  try {
    fs.accessSync(filePath, fs.constants.R_OK);
  } catch {
    throw new Error(`Cannot watch non-existent or unreadable file: ${filePath}`);
  }

  console.log(`Watching for changes: ${filePath}`);

  let debounceTimer = null;

  const watcher = fs.watch(filePath, (eventType) => {
    // Clear any previously scheduled callback — if another event arrives
    // within 100ms, we start the timer over.
    clearTimeout(debounceTimer);
    debounceTimer = setTimeout(() => {
      console.log(`File changed (${eventType}), reloading...`);
      onChangeCallback(filePath);
    }, 100); // 100ms covers the window for most editor atomic save sequences
  });

  // Return the watcher so the caller can close it during graceful shutdown.
  // An unclosed watcher prevents the event loop from exiting naturally.
  return watcher;
}

// ─── Pattern 2: Safe directory creation (mkdir -p equivalent) ───
async function ensureOutputDirectory(dirPath) {
  try {
    const stats = await fs.promises.stat(dirPath);

    if (!stats.isDirectory()) {
      // A FILE at this path is a real problem — mkdir would fail with EEXIST
      // and the error message would not explain why.
      throw new Error(`Path exists but is a file, not a directory: ${dirPath}`);
    }
    console.log(`Output directory already exists: ${dirPath}`);
  } catch (statError) {
    if (statError.code === 'ENOENT') {
      // Path does not exist — create it and all missing parents
      await fs.promises.mkdir(dirPath, { recursive: true });
      console.log(`Created output directory: ${dirPath}`);
    } else {
      throw statError; // EACCES, ENOTDIR, or something unexpected — bubble it up
    }
  }
}

// ─── Pattern 3: Clean a build directory between runs ───
// { recursive: true, force: true } is rm -rf — won't throw if the directory
// doesn't exist. Create it fresh immediately after removal.
async function cleanBuildDirectory(buildDir) {
  await fs.promises.rm(buildDir, { recursive: true, force: true });
  await fs.promises.mkdir(buildDir, { recursive: true });
  console.log(`Build directory cleaned and recreated: ${buildDir}`);
}

(async () => {
  const buildDir   = path.join(__dirname, 'dist');
  const configFile = path.join(__dirname, 'app-config.json');

  await cleanBuildDirectory(buildDir);
  await ensureOutputDirectory(path.join(buildDir, 'assets'));
  await ensureOutputDirectory(path.join(buildDir, 'assets', 'images'));

  const watcher = watchConfigFile(configFile, async (changedFile) => {
    console.log(`Re-reading config from: ${changedFile}`);
    // In a real app: invalidate the in-memory config cache here
  });

  // Close the watcher on SIGINT (Ctrl+C) and SIGTERM (process manager shutdown).
  // Without this, open watchers prevent the process from exiting cleanly,
  // which causes test suites to hang after completion.
  const shutdown = () => {
    watcher.close();
    console.log('File watcher closed. Shutting down.');
    process.exit(0);
  };
  process.on('SIGINT', shutdown);
  process.on('SIGTERM', shutdown);
})();

const fs   = require('fs');
const path = require('path');

// ─── Pattern: handle fs errors by error code, not by message ───
// err.message changes between Node.js versions and OS platforms.
// err.code is stable — it is the correct thing to switch on.
async function safeFileRead(filePath) {
  try {
    const content = await fs.promises.readFile(filePath, 'utf8');
    return { success: true, content };
  } catch (err) {
    switch (err.code) {
      case 'ENOENT':
        // The file does not exist. This is often recoverable —
        // return a default, create the file, or log a warning.
        // Do not throw here unless missing file is fatal to the operation.
        console.warn(`File not found: ${filePath} — using defaults`);
        return { success: false, reason: 'NOT_FOUND', fallback: true };

      case 'EACCES':
        // Permission denied. The process user cannot read this file.
        // This requires an infrastructure fix (chown, Dockerfile USER) —
        // there is nothing the application can do at runtime to recover.
        console.error(
          `Permission denied: ${filePath}. ` +
          `Check file ownership (ls -la) and process UID (process.getuid())`
        );
        return { success: false, reason: 'PERMISSION_DENIED', fallback: false };

      case 'EBUSY':
        // File is locked by another process — most common on Windows
        // or with file systems that use exclusive locks.
        // Retry after a short delay is the appropriate response.
        console.error(`File busy: ${filePath} — another process has it locked. Retry after delay.`);
        return { success: false, reason: 'FILE_BUSY', fallback: false };

      case 'EISDIR':
        // The path points to a directory, not a file.
        // Almost always a path resolution bug.
        console.error(`Expected a file but found a directory: ${filePath}`);
        return { success: false, reason: 'IS_DIRECTORY', fallback: false };

      default:
        // Unexpected error — re-throw with context so the caller knows
        // where it originated.
        throw err;
    }
  }
}

// ─── Cross-platform path construction ───
// Never concatenate paths with string operators.
// path.join normalizes separators for the current OS automatically.
const reportPath = path.join(__dirname, 'data', 'report.csv');
console.log('Cross-platform safe path:', reportPath);
// On macOS/Linux: /app/data/report.csv
// On Windows:     C:\app\data\report.csv
// Both correct for their OS — path.join handled it.

// ─── Create parent directories before writing to avoid ENOENT ───
// A common mistake: writeFile fails with ENOENT not because the file
// is missing, but because a parent directory in the path does not exist.
async function safeWriteFile(filePath, content) {
  const parentDir = path.dirname(filePath);

  // Ensure the entire parent path exists before attempting the write.
  // { recursive: true } means: create all missing parents, don't fail
  // if any already exist.
  await fs.promises.mkdir(parentDir, { recursive: true });
  await fs.promises.writeFile(filePath, content, 'utf8');
  console.log(`Written: ${filePath}`);
}

(async () => {
  const readResult = await safeFileRead('/tmp/missing-config.json');
  console.log('Read result:', readResult);

  await safeWriteFile(
    path.join(__dirname, 'output', 'nested', 'deep', 'report.json'),
    JSON.stringify({ status: 'ok', generatedAt: new Date().toISOString() }, null, 2)
  );
})();