Node.js Explained: How It Works, Why It Exists, and When to Use It

// hello_node_runtime.js
// Run this with: node hello_node_runtime.js
// This proves Node.js has access to OS-level info — something impossible in a browser.

const os = require('os');       // 'os' is a built-in Node.js module — no npm install needed
const process = require('process'); // 'process' gives us info about the running Node process

// --- System Info (this would throw a ReferenceError in a browser) ---
const totalMemoryGB = (os.totalmem() / 1e9).toFixed(2);  // Convert bytes to GB
const freeMemoryGB  = (os.freemem()  / 1e9).toFixed(2);
const platform      = os.platform();   // e.g. 'linux', 'darwin', 'win32'
const cpuModel      = os.cpus()[0].model; // Info about the first CPU core

console.log('=== Node.js Runtime Demo ===');
console.log(`Platform      : ${platform}`);
console.log(`CPU           : ${cpuModel}`);
console.log(`Total Memory  : ${totalMemoryGB} GB`);
console.log(`Free Memory   : ${freeMemoryGB} GB`);
console.log(`Node Version  : ${process.version}`);
console.log(`Process ID    : ${process.pid}`);

// --- This is WHY Node exists: it bridges JS into the operating system ---
console.log('\nIf this were browser JS, every line above would crash.');
console.log('Node.js gives JavaScript a body — not just a brain.');

// event_loop_demo.js
// Run with: node event_loop_demo.js
// PURPOSE: Watch the event loop in action — see how Node handles async work
// without blocking the main thread.

const fs = require('fs');       // Built-in file system module
const path = require('path');   // Built-in path utility

const logFilePath = path.join(__dirname, 'event_loop_demo.js'); // Read this very file

console.log('[1] Script started — we are on the main thread');

// --- ASYNC file read: Node hands this off and moves on immediately ---
fs.readFile(logFilePath, 'utf8', (err, fileContents) => {
  // This callback runs LATER — only when the OS has finished reading the file.
  // The event loop delivered it back here once the I/O was done.
  if (err) {
    console.error('File read failed:', err.message);
    return;
  }
  const lineCount = fileContents.split('\n').length;
  console.log(`[3] File read complete — ${lineCount} lines found (this ran AFTER [2])`);
});

// --- This line runs IMMEDIATELY after registering the file read above ---
// Node did NOT wait for the file. That's the whole point.
console.log('[2] Main thread kept moving while file read is in progress');

// --- setTimeout pushes a callback to the event loop queue ---
setTimeout(() => {
  console.log('[4] setTimeout fired — event loop picked this up after I/O settled');
}, 0); // Even 0ms means "next event loop tick", not "right now"

console.log('[5] End of synchronous code — now the event loop takes over');

/*
  Expected order: 1 → 2 → 5 → 3 (or 4) → 4 (or 3)
  The exact order of 3 and 4 depends on how fast the OS reads the file.
  But 1, 2, 5 will ALWAYS print before 3 and 4.
  That non-obvious ordering is the event loop at work.
*/

// raw_http_server.js
// Run with: node raw_http_server.js
// Test with: curl http://localhost:3000/health
//            curl http://localhost:3000/greet?name=Ada
// No npm install needed — this uses only Node.js built-ins.

const http = require('http');  // Built-in HTTP module
const url  = require('url');   // Built-in URL parser

const SERVER_PORT = 3000;
const SERVER_HOST = '127.0.0.1';

// --- Helper: send a JSON response (reusable utility) ---
function sendJsonResponse(res, statusCode, payload) {
  res.writeHead(statusCode, {
    'Content-Type': 'application/json',  // Tell the client to expect JSON
    'X-Powered-By': 'Raw Node.js'        // Custom header — Express sets this automatically
  });
  res.end(JSON.stringify(payload));  // Serialize and close the response
}

// --- Request handler: this fires on EVERY incoming HTTP request ---
// Each call is a separate event on the event loop — Node handles them concurrently.
function handleRequest(req, res) {
  const parsedUrl  = url.parse(req.url, true);  // true = parse query string into an object
  const pathname   = parsedUrl.pathname;         // e.g. '/greet'
  const queryParams = parsedUrl.query;           // e.g. { name: 'Ada' }

  console.log(`[${new Date().toISOString()}] ${req.method} ${pathname}`);

  // --- Route: GET /health — standard health check endpoint ---
  if (pathname === '/health' && req.method === 'GET') {
    sendJsonResponse(res, 200, {
      status: 'ok',
      uptime: `${process.uptime().toFixed(2)}s`,  // Seconds since Node process started
      timestamp: new Date().toISOString()
    });
    return;
  }

  // --- Route: GET /greet?name=YourName ---
  if (pathname === '/greet' && req.method === 'GET') {
    const visitorName = queryParams.name || 'stranger'; // Default if no name provided
    sendJsonResponse(res, 200, {
      message: `Hello, ${visitorName}! Welcome to raw Node.js.`,
      hint: 'No Express was harmed in the making of this response.'
    });
    return;
  }

  // --- Fallback: 404 for anything unrecognised ---
  sendJsonResponse(res, 404, {
    error: 'Route not found',
    availableRoutes: ['/health', '/greet?name=YourName']
  });
}

// --- Create and start the server ---
const server = http.createServer(handleRequest);

server.listen(SERVER_PORT, SERVER_HOST, () => {
  // This callback fires once — when the server is ready to accept connections
  console.log(`Server running at http://${SERVER_HOST}:${SERVER_PORT}`);
  console.log('Try: curl http://localhost:3000/greet?name=Ada');
});

// --- Graceful shutdown: handle Ctrl+C cleanly ---
process.on('SIGINT', () => {
  console.log('\nShutting down gracefully...');
  server.close(() => {
    console.log('Server closed. Goodbye.');
    process.exit(0);
  });
});

// ─────────────────────────────────────────────
// FILE 1: request_counter.js
// This module maintains a shared counter.
// Because Node caches modules, this counter is
// a TRUE singleton — every file that requires it
// shares the same instance.
// ─────────────────────────────────────────────

// request_counter.js
let totalRequestCount = 0; // This lives in module cache — shared across all importers

function incrementRequestCount() {
  totalRequestCount += 1;
  return totalRequestCount;
}

function getCurrentCount() {
  return totalRequestCount;
}

// Export an object — not the raw variables — so callers use our controlled API
module.exports = { incrementRequestCount, getCurrentCount };


// ─────────────────────────────────────────────
// FILE 2: module_system_demo.js  ← run THIS file
// ─────────────────────────────────────────────

const path = require('path'); // Built-in — resolves file paths safely across OS

// Requiring our custom local module (note the './' prefix for local files)
const requestCounter = require('./request_counter');

// Requiring the SAME module a second time — Node returns the CACHED version
// No code in request_counter.js runs again. Same object, same state.
const anotherReferenceToCounter = require('./request_counter');

console.log('--- Module Singleton Demo ---');

// Increment via first reference
requestCounter.incrementRequestCount();
requestCounter.incrementRequestCount();

// Read via second reference — same underlying state
const countFromSecondRef = anotherReferenceToCounter.getCurrentCount();
console.log(`Count via second require: ${countFromSecondRef}`);
// Outputs 2 — NOT 0. Both variables point to the same cached module.

// Are they literally the same object in memory?
console.log(`Same object? ${requestCounter === anotherReferenceToCounter}`);
// Outputs: true — this is the singleton pattern, built into Node's module system

console.log('\n--- Path Module Demo ---');
const projectRoot = path.resolve(__dirname); // Absolute path to this file's directory
const configPath  = path.join(projectRoot, 'config', 'settings.json'); // Safe path join
console.log(`Project root : ${projectRoot}`);
console.log(`Config path  : ${configPath}`);
// path.join handles slashes correctly on Windows AND Unix — always use it over string concat