Node.js Modules and CommonJS Explained — require, exports, and Real-World Patterns

// Run this file with: node showModuleWrapper.js
// It reveals the five injected variables every Node.js file receives for free.

// __filename: the absolute path of this specific file
console.log('Current file:', __filename);

// __dirname: the directory that contains this file
// Use this when building file paths — never use process.cwd() for asset paths
console.log('Current directory:', __dirname);

// module: the object that represents THIS file in the module system
console.log('Module id:', module.id);
console.log('Has this module been loaded before?', module.loaded);

// exports: a shorthand reference to module.exports (more on this soon)
console.log('Exports object starts as:', exports);

// require: the function we use to pull in other modules
console.log('Type of require:', typeof require);

// FILE: userService.js
// This module encapsulates all user-related business logic.
// We export a single object with named methods — a clean, common pattern.

const MAX_USERNAME_LENGTH = 30; // private constant — NOT exported, not accessible outside

// Private helper — callers of this module never know this function exists
function sanitiseInput(rawString) {
  return rawString.trim().toLowerCase();
}

// Public API — everything on module.exports is accessible to callers
module.exports = {
  // Creates a user object after validating the inputs
  createUser(username, email) {
    const cleanName = sanitiseInput(username);

    if (cleanName.length > MAX_USERNAME_LENGTH) {
      throw new Error(`Username exceeds ${MAX_USERNAME_LENGTH} characters`);
    }

    // Returns a plain data object — no class overhead needed here
    return {
      id: Date.now(), // simple id for demo purposes
      username: cleanName,
      email: sanitiseInput(email),
      createdAt: new Date().toISOString(),
    };
  },

  // Checks whether a username string meets basic rules
  isValidUsername(username) {
    const clean = sanitiseInput(username);
    // Only letters, numbers, and underscores allowed
    return /^[a-z0-9_]+$/.test(clean) && clean.length >= 3;
  },
};

// --- FILE: app.js ---
// const userService = require('./userService');
//
// const newUser = userService.createUser('  Alice_Dev  ', 'Alice@Example.com');
// console.log(newUser);
// console.log('Valid username?', userService.isValidUsername('al'));
// console.log('Valid username?', userService.isValidUsername('alice_42'));

// FILE: databaseConnection.js
// Demonstrates the singleton caching pattern — perfect for DB connections.
// The connection is created ONCE, then every require() returns the same instance.

const EventEmitter = require('events'); // Node.js core module — no path needed

class DatabaseConnection extends EventEmitter {
  constructor(connectionString) {
    super();
    this.connectionString = connectionString;
    this.isConnected = false;
    this.queryCount = 0;
    console.log('[DB] New DatabaseConnection instance created'); // runs ONCE due to caching
  }

  connect() {
    // Simulates an async connection — in real life this would be pg.connect() or similar
    this.isConnected = true;
    this.emit('connected');
    console.log('[DB] Connected to:', this.connectionString);
  }

  query(sql) {
    if (!this.isConnected) throw new Error('Call connect() before querying');
    this.queryCount++;
    console.log(`[DB] Query #${this.queryCount}: ${sql}`);
    // Would return a Promise in a real driver
    return { rows: [], rowCount: 0 };
  }
}

// Module exports a SINGLE shared instance — not the class itself.
// Every file that require()s this module gets the SAME object from cache.
const sharedConnection = new DatabaseConnection('postgres://localhost:5432/myapp');
module.exports = sharedConnection;


// FILE: userRepository.js
// const db = require('./databaseConnection'); // gets the cached instance
// db.query('SELECT * FROM users');

// FILE: productRepository.js
// const db = require('./databaseConnection'); // same instance — '[DB] New...' does NOT print again
// db.query('SELECT * FROM products');
// console.log('Total queries so far:', db.queryCount); // reflects queries from BOTH files

// PROJECT STRUCTURE:
// /src
//   config.js
//   /services
//     emailService.js
//     smsService.js
//     index.js        <-- barrel file, controls public API of the folder
//   app.js

// ─────────────────────────────────────────
// FILE: src/config.js
// Single source of truth for all environment configuration.
// Fails fast at startup if required variables are missing.
// ─────────────────────────────────────────
function requireEnv(variableName) {
  const value = process.env[variableName];
  if (!value) {
    // Crashing at startup is far better than a cryptic error mid-request
    throw new Error(`Missing required environment variable: ${variableName}`);
  }
  return value;
}

module.exports = {
  port: parseInt(process.env.PORT || '3000', 10),
  database: {
    url: process.env.DATABASE_URL || 'postgres://localhost:5432/dev',
    poolSize: parseInt(process.env.DB_POOL_SIZE || '10', 10),
  },
  email: {
    apiKey: process.env.NODE_ENV === 'test' ? 'test-key' : requireEnv('EMAIL_API_KEY'),
    fromAddress: process.env.EMAIL_FROM || 'no-reply@myapp.com',
  },
};


// ─────────────────────────────────────────
// FILE: src/services/emailService.js
// Handles all outbound email logic. Private to this folder.
// ─────────────────────────────────────────
const config = require('../config'); // always use config, never process.env directly

function sendWelcomeEmail(recipientAddress, username) {
  console.log(`[Email] Sending welcome to ${recipientAddress} via key: ${config.email.apiKey}`);
  // In production: return sgMail.send({ to: recipientAddress, ... })
  return Promise.resolve({ accepted: [recipientAddress] });
}

module.exports = { sendWelcomeEmail };


// ─────────────────────────────────────────
// FILE: src/services/smsService.js
// Handles all outbound SMS logic. Private to this folder.
// ─────────────────────────────────────────
function sendVerificationSms(phoneNumber, code) {
  console.log(`[SMS] Sending code ${code} to ${phoneNumber}`);
  return Promise.resolve({ sid: 'SM_demo_123' });
}

module.exports = { sendVerificationSms };


// ─────────────────────────────────────────
// FILE: src/services/index.js  — the barrel file
// This is the ONLY public face of the services folder.
// Callers never need to know whether email lives in one file or ten.
// ─────────────────────────────────────────
const { sendWelcomeEmail } = require('./emailService');
const { sendVerificationSms } = require('./smsService');

// Explicitly choose what to expose — everything else stays private
module.exports = {
  sendWelcomeEmail,
  sendVerificationSms,
};


// ─────────────────────────────────────────
// FILE: src/app.js
// Clean import — no knowledge of internal folder structure needed
// ─────────────────────────────────────────
process.env.NODE_ENV = 'test'; // so config doesn't demand EMAIL_API_KEY
const config = require('./config');
const services = require('./services'); // Node finds services/index.js automatically

console.log('Server starting on port:', config.port);

async function onUserRegistered(email, phone, username) {
  await services.sendWelcomeEmail(email, username);
  await services.sendVerificationSms(phone, '847291');
  console.log('Onboarding notifications dispatched for:', username);
}

onUserRegistered('alice@example.com', '+447700900000', 'alice_dev');