JavaScript Modules Explained — import, export and Real-World Patterns

// currencyUtils.js — a shared utility module
// Each export is a deliberate part of the public API

// Named export: a pure function to format a number as currency
export function formatCurrency(amount, currencyCode = 'USD') {
  // Intl.NumberFormat gives us locale-aware formatting for free
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: currencyCode,
  }).format(amount);
}

// Named export: another utility living in the same file
export function calculateTax(subtotal, taxRate) {
  // taxRate is expected as a decimal, e.g. 0.08 for 8%
  const taxAmount = subtotal * taxRate;
  return Math.round(taxAmount * 100) / 100; // round to 2 decimal places
}

// This helper is NOT exported — it's an internal implementation detail
// Nothing outside this file can touch it
function _validateAmount(amount) {
  return typeof amount === 'number' && amount >= 0;
}

// ─────────────────────────────────────────────────
// checkout.js — consuming the named exports
// ─────────────────────────────────────────────────

// We only import what we actually need — tree-shakers love this
import { formatCurrency, calculateTax } from './currencyUtils.js';

const itemSubtotal = 49.99;
const stateTaxRate = 0.08; // 8% tax

const taxOwed = calculateTax(itemSubtotal, stateTaxRate);
const totalAmount = itemSubtotal + taxOwed;

console.log(`Subtotal:  ${formatCurrency(itemSubtotal)}`); // Subtotal:  $49.99
console.log(`Tax (8%):  ${formatCurrency(taxOwed)}`);
console.log(`Total:     ${formatCurrency(totalAmount)}`);

// You can also alias an import if a name would clash with something local
import { formatCurrency as formatPrice } from './currencyUtils.js';
console.log(formatPrice(19.99, 'EUR')); // €19.99

// ShoppingCart.js — a component-style module with one clear purpose

// Named export: the cart item shape is useful to callers too
export const EMPTY_CART_MESSAGE = 'Your cart is empty. Start shopping!';

// Named export: a helper that callers might want to use independently
export function sumCartItems(cartItems) {
  return cartItems.reduce((total, item) => {
    return total + item.price * item.quantity;
  }, 0);
}

// Default export: the main class this file is really about
// Only one default export allowed per file
export default class ShoppingCart {
  constructor() {
    this.items = [];
  }

  addItem(product, quantity = 1) {
    const existingItem = this.items.find(item => item.id === product.id);

    if (existingItem) {
      // Increment quantity instead of adding a duplicate
      existingItem.quantity += quantity;
    } else {
      // Spread to avoid mutating the original product object
      this.items.push({ ...product, quantity });
    }
  }

  getTotal() {
    // Delegate to the named export — shared logic stays DRY
    return sumCartItems(this.items);
  }

  isEmpty() {
    return this.items.length === 0;
  }
}

// ─────────────────────────────────────────────────
// storePage.js — consuming both the default and named exports
// ─────────────────────────────────────────────────

// Default import: name it whatever makes sense in context
import ShoppingCart, { EMPTY_CART_MESSAGE, sumCartItems } from './ShoppingCart.js';

const cart = new ShoppingCart();

console.log(cart.isEmpty()); // true
console.log(EMPTY_CART_MESSAGE); // Your cart is empty. Start shopping!

cart.addItem({ id: 'shoe-42', name: 'Trail Runner', price: 89.99 }, 2);
cart.addItem({ id: 'sock-m', name: 'Merino Socks', price: 12.50 }, 3);

console.log(`Cart total: $${cart.getTotal().toFixed(2)}`); // Cart total: $217.48

// sumCartItems works independently — useful for a cart preview elsewhere
const previewItems = [{ price: 10, quantity: 3 }];
console.log(sumCartItems(previewItems)); // 30

// utils/index.js — the barrel file for the entire utils folder
// This is the ONLY file that consumers of this folder should import from
// It defines the public API; everything else inside utils/ is an internal detail

// Re-export specific named exports from each utility module
// The 'export { } from' syntax passes through without polluting this scope
export { formatCurrency, calculateTax } from './currencyUtils.js';
export { truncateText, capitalise, slugify } from './stringUtils.js';
export { debounce, throttle } from './functionUtils.js';

// You can also re-export a default export as a named export
// This normalises everything to named exports at the barrel level (recommended)
export { default as DatePicker } from './DatePicker.js';

// ─────────────────────────────────────────────────
// stringUtils.js — one of the internal util modules
// ─────────────────────────────────────────────────

export function truncateText(text, maxLength) {
  if (text.length <= maxLength) return text;
  return text.slice(0, maxLength).trimEnd() + '…';
}

export function capitalise(word) {
  if (!word) return '';
  return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
}

export function slugify(text) {
  return text
    .toLowerCase()
    .trim()
    .replace(/[^\w\s-]/g, '')  // remove non-word chars
    .replace(/[\s_-]+/g, '-')  // replace spaces/underscores with hyphens
    .replace(/^-+|-+$/g, '');  // strip leading/trailing hyphens
}

// ─────────────────────────────────────────────────
// productCard.js — a consumer anywhere in the project
// Clean single import, no fragile relative paths through internal structure
// ─────────────────────────────────────────────────

import { formatCurrency, truncateText, slugify } from '../utils/index.js';
// Or with path aliases set up in your bundler config:
// import { formatCurrency, truncateText, slugify } from '@/utils';

const product = {
  name: 'Handcrafted Leather Journal   ',
  description: 'A beautifully bound leather journal perfect for daily writing, sketching and planning your next adventure.',
  price: 34.95,
};

const productSlug = slugify(product.name);
const shortDescription = truncateText(product.description, 60);
const displayPrice = formatCurrency(product.price);

console.log(productSlug);       // handcrafted-leather-journal
console.log(shortDescription);  // A beautifully bound leather journal perfect for daily…
console.log(displayPrice);      // $34.95

// reportGenerator.js
// Demonstrates dynamic import for a heavy PDF-generation library
// The PDF library only loads when the user actually clicks 'Export PDF'
// — not on every page visit

async function generateSalesReport(salesData) {
  // Show feedback immediately — don't wait for the module to load
  console.log('Preparing your report...');

  try {
    // Dynamic import: the PDF module loads NOW, on demand
    // Bundlers split this into a separate chunk automatically
    const { createPdfDocument, addTable, saveAsPdf } = await import('./pdfUtils.js');

    // From here on it looks just like a normal module usage
    const document = createPdfDocument({ title: 'Q3 Sales Report', orientation: 'landscape' });

    addTable(document, {
      headers: ['Region', 'Units Sold', 'Revenue'],
      rows: salesData,
    });

    const filename = `sales-report-${new Date().getFullYear()}.pdf`;
    await saveAsPdf(document, filename);

    console.log(`Report saved: ${filename}`);
    return { success: true, filename };

  } catch (loadError) {
    // This catch handles BOTH module-load failures AND runtime errors
    // Worth noting: if the chunk fails to load (e.g. offline), you'll end up here
    console.error('Failed to generate report:', loadError.message);
    return { success: false, error: loadError.message };
  }
}

// ─────────────────────────────────────────────────
// Real-world pattern: lazy-loading a route in a SPA
// This is exactly what React.lazy() does under the hood
// ─────────────────────────────────────────────────

const routes = [
  {
    path: '/dashboard',
    // Module loads immediately — it's the landing page, it should be fast
    component: await import('./pages/Dashboard.js').then(m => m.default),
  },
  {
    path: '/analytics',
    // Wrapped in a function — only called when the user navigates to /analytics
    // The bundle for this page never touches the network until then
    loadComponent: () => import('./pages/Analytics.js').then(m => m.default),
  },
  {
    path: '/settings',
    loadComponent: () => import('./pages/Settings.js').then(m => m.default),
  },
];

// Simulating navigation to /analytics
const analyticsRoute = routes.find(r => r.path === '/analytics');
if (analyticsRoute.loadComponent) {
  const AnalyticsPage = await analyticsRoute.loadComponent();
  console.log('Analytics module loaded on demand:', typeof AnalyticsPage);
}

console.log(
  'Routes registered. Only Dashboard loaded at startup — ' +
  'other pages load on navigation.'
);