Node.js fs Module Explained — Reading, Writing, and Real-World File Patterns

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

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

// ─── SYNCHRONOUS — blocks the thread until the file is fully read ───
// Safe here because this runs ONCE at startup, before the server opens.
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) {
  // If the config is missing at startup, crash loudly — that's the RIGHT behaviour.
  console.error('❌ Could not load config. Aborting startup.', startupError.message);
  process.exit(1); // intentional hard stop
}

// ─── ASYNCHRONOUS — hands off to the OS, callback fires when done ───
// Use this inside request handlers, scheduled jobs, or anywhere after startup.
fs.readFile(configFilePath, 'utf8', (readError, fileContents) => {
  // Node's error-first callback pattern: first arg is always the error (or null)
  if (readError) {
    console.error('❌ Async read failed:', readError.message);
    return; // always return after handling an error — don't let execution fall through
  }

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

console.log('👀 This line prints BEFORE the async callback fires — proof the thread is free');

// The modern way — use fs/promises for clean async/await code
const { readFile, writeFile, mkdir } = require('fs/promises');
const path = require('path');

// ─── Real-world pattern: load multiple config files before server start ───
async function loadApplicationConfig() {
  const configDir = path.join(__dirname, 'config');

  try {
    // Promise.all fires ALL reads at the same time — parallel, not sequential
    // This is faster than awaiting each one individually
    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 all three now that we know they all succeeded
    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 — much cleaner than three separate callbacks
    console.error('❌ Config load failed:', loadError.message);
    throw loadError; // re-throw so the caller knows startup failed
  }
}

// ─── Writing a file — creating an output directory first ───
async function saveProcessedReport(reportData) {
  const outputDir  = path.join(__dirname, 'reports');
  const outputFile = path.join(outputDir, `report-${Date.now()}.json`);

  try {
    // { recursive: true } means: create parent dirs too, and don't throw if it already exists
    await mkdir(outputDir, { recursive: true });

    // JSON.stringify with indent=2 makes the file human-readable
    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;
  }
}

// ─── Wire it all together ───
(async () => {
  await loadApplicationConfig();
  await saveProcessedReport({ totalOrders: 1482, revenue: 94300, currency: 'USD' });
})();

const fs   = require('fs');
const zlib = require('zlib'); // built-in compression module
const path = require('path');

const sourceLogFile      = path.join(__dirname, 'server.log');       // could be gigabytes
const compressedOutput   = path.join(__dirname, 'server.log.gz');    // gzipped destination
const lineCountOutput    = path.join(__dirname, 'line-count.txt');   // simple write target

// ─── Pattern 1: Stream + pipe to compress a large file on the fly ───
function compressLogFile(source, destination) {
  return new Promise((resolve, reject) => {
    const readStream   = fs.createReadStream(source);    // reads in ~64KB chunks by default
    const gzipStream   = zlib.createGzip();              // transform: compresses each chunk
    const writeStream  = fs.createWriteStream(destination);

    // pipe() chains: each chunk flows source → gzip → disk
    // error handling: attach error listeners BEFORE piping
    readStream.on('error', reject);
    gzipStream.on('error', reject);
    writeStream.on('error', reject);
    writeStream.on('finish', () => {
      console.log(`✅ Compressed: ${source} → ${destination}`);
      resolve(destination);
    });

    readStream.pipe(gzipStream).pipe(writeStream);
  });
}

// ─── Pattern 2: Read a large file line-by-line using readline ───
// readline + createReadStream is the memory-efficient way to process CSV/log lines
const readline = require('readline');

async function countLinesInLargeFile(filePath) {
  const fileStream    = fs.createReadStream(filePath);
  const lineInterface = readline.createInterface({
    input: fileStream,
    crlfDelay: Infinity, // handle both \r\n (Windows) and \n (Unix) line endings
  });

  let lineCount = 0;

  for await (const line of lineInterface) {
    // Each iteration handles ONE line — memory usage is constant regardless of file size
    lineCount++;
    // In a real log processor you'd parse or filter the line here
  }

  console.log(`✅ Total lines counted: ${lineCount.toLocaleString()}`);
  return lineCount;
}

// ─── Run both patterns ───
(async () => {
  await compressLogFile(sourceLogFile, compressedOutput);
  const total = await countLinesInLargeFile(sourceLogFile);
  await fs.promises.writeFile(lineCountOutput, `Line count: ${total}`, 'utf8');
})();

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

// ─── Pattern 1: Watch a config file and reload on change ───
function watchConfigFile(filePath, onChangeCallback) {
  console.log(`👀 Watching for changes: ${filePath}`);

  // fs.watch fires 'rename' or 'change' events
  // debounce is critical — editors fire multiple events per save
  let debounceTimer = null;

  const watcher = fs.watch(filePath, (eventType) => {
    clearTimeout(debounceTimer); // cancel any previously scheduled reload
    debounceTimer = setTimeout(() => {
      console.log(`🔄 File changed (${eventType}), reloading...`);
      onChangeCallback(filePath);
    }, 100); // wait 100ms for the dust to settle before reacting
  });

  // Always return the watcher so the caller can close it
  return watcher;
}

// ─── Pattern 2: Safe directory setup (like mkdir -p) ───
async function ensureOutputDirectory(dirPath) {
  try {
    // stat() tells us if the path exists and what it is
    const stats = await fs.promises.stat(dirPath);

    if (!stats.isDirectory()) {
      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') {
      // ENOENT = "Error NO ENTry" — the path simply doesn't exist yet, so create it
      await fs.promises.mkdir(dirPath, { recursive: true });
      console.log(`📁 Created output directory: ${dirPath}`);
    } else {
      throw statError; // something unexpected — bubble it up
    }
  }
}

// ─── Pattern 3: Clean a build directory between runs ───
async function cleanBuildDirectory(buildDir) {
  try {
    // { recursive: true, force: true } = rm -rf — won't throw if dir doesn't exist
    await fs.promises.rm(buildDir, { recursive: true, force: true });
    await fs.promises.mkdir(buildDir, { recursive: true });
    console.log(`🧹 Build directory cleaned and recreated: ${buildDir}`);
  } catch (cleanError) {
    console.error('❌ Failed to clean build directory:', cleanError.message);
    throw cleanError;
  }
}

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

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

  const watcher = watchConfigFile(configFile, (changedFile) => {
    console.log(`⚙️  Re-reading config from: ${changedFile}`);
  });

  // In a real app the watcher stays open — close it on shutdown
  process.on('SIGINT', () => {
    watcher.close();
    console.log('\n🛑 File watcher closed. Shutting down.');
    process.exit(0);
  });
})();