// src/utils/format.mjs

// Option A: export in the declaration itself.
export function formatPrice(cents) {
  const euros = Math.floor(cents / 100);
  const remainder = String(cents % 100).padStart(2, '0');
  return `${euros}.${remainder} EUR`;
}

export function formatDate(isoDate) {
  const date = new Date(isoDate);
  const day = String(date.getDate()).padStart(2, '0');
  const month = String(date.getMonth() + 1).padStart(2, '0');
  return `${day}/${month}/${date.getFullYear()}`;
}

export const CURRENCY_SYMBOL = 'EUR';

// Option B: export as a block at the end. It matches the single module.exports
// of CommonJS and has the same advantage: an index of the public API.
function formatPrice(cents) { /* ... */ }
function formatDate(isoDate) { /* ... */ }
const CURRENCY_SYMBOL = 'EUR';

export { formatPrice, formatDate, CURRENCY_SYMBOL };

// Import what you need, by name.
import { formatPrice, formatDate } from './utils/format.mjs';

// Rename, to avoid collisions.
import { formatPrice as price } from './utils/format.mjs';

// Import EVERYTHING into a namespace.
import * as format from './utils/format.mjs';
console.log(format.formatPrice(2500));

// Import purely for the side effect (rare, but it exists).
import './global-config.mjs';

// src/domain/session.mjs
export default class Session {
  /* ... */
}

// When importing, you choose the name: no braces.
import Session from './domain/session.mjs';
import Whatever from './domain/session.mjs';   // Legal, and confusing

// src/domain/event.mjs
export default class Event { /* ... */ }
export const EVENT_STATUSES = ['draft', 'published', 'finished'];

import Event, { EVENT_STATUSES } from './domain/event.mjs';

// src/domain/index.mjs

// Re-export EVERYTHING named from each module.
export * from './session.mjs';
export * from './event.mjs';
export * from './sales-manager.mjs';

// Or be selective, which is usually better.
export { Session } from './session.mjs';
export { Event } from './event.mjs';
export { SalesManager, LOW_CAPACITY_THRESHOLD } from './sales-manager.mjs';

// Re-export under a different name.
export { Session as EventSession } from './session.mjs';

export { default as Session } from './session.mjs';

// All of this is legal in CommonJS.
const loaded = require('./' + moduleName + '.js');

if (process.env.MODE === 'production') {
  logger = require('./production-logger.js');
}

for (const name of ['a', 'b', 'c']) {
  modules[name] = require(`./plugins/${name}.js`);
}

function loadLazily() {
  const heavy = require('./very-heavy-module.js');   // Only if it is called
  return heavy.process();
}

// ALL of this is a SyntaxError in ESM.
import loaded from './' + name + '.mjs';          // Non-literal path

if (production) {
  import logger from './logger.mjs';              // Not inside a block
}

function load() {
  import heavy from './heavy.mjs';                // Not inside a function
}

// src/lab/counter.mjs
export let count = 0;
export function increment() {
  count++;
}

// src/lab/use-counter.mjs
import { count, increment } from './counter.mjs';

console.log(count);   // 0
increment();
console.log(count);   // 1  <-- The imported value CHANGED

// This works in ESM, even though it looks impossible.
console.log(formatPrice(2500));            // 25.00 EUR
import { formatPrice } from './format.mjs';

{
  "type": "module"
}

escena-viva/
├── package.json              { "type": "module" }
├── src/
│   ├── catalog.js            -> ESM (from the root package.json)
│   ├── domain/
│   │   └── event.js          -> ESM
│   └── legacy/
│       ├── package.json      { "type": "commonjs" }
│       └── old.js            -> CommonJS (from ITS package.json)
└── tools/
    └── migrate.cjs           -> CommonJS (from the extension)

# A .mjs file is always ESM
echo 'console.log(typeof require);' > test.mjs
node test.mjs
# ReferenceError: require is not defined in ES module scope

# The same content as .cjs
echo 'console.log(typeof require);' > test.cjs
node test.cjs
# function

// CommonJS: all four forms work.
require('./session');
require('./session.js');
require('./domain');          // Finds domain/index.js
require('./domain/index.js');

// ESM: only COMPLETE paths work.
import { Session } from './session.js';         // RIGHT
import { Session } from './session';            // ERROR
import { Event } from './domain';               // ERROR: it does not look for index.js
import { Event } from './domain/index.js';      // RIGHT

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/home/joan/escena-viva/src/session'
imported from /home/joan/escena-viva/src/catalog.js
Did you mean to import ./session.js?

// src/lab/metadata.mjs
console.log(import.meta.url);
// file:///home/joan/escena-viva/src/lab/metadata.mjs

// src/utils/paths.mjs
import { fileURLToPath } from 'node:url';
import { dirname, join } from 'node:path';

// Exact equivalents of the CommonJS variables.
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

console.log(__filename);   // /home/joan/escena-viva/src/utils/paths.mjs
console.log(__dirname);    // /home/joan/escena-viva/src/utils

// The usual use: a reliable path to the data.
const DATA_PATH = join(__dirname, '..', '..', 'data', 'events.json');

const __dirname = import.meta.dirname;    // Directly, with no conversion
const __filename = import.meta.filename;

// src/lab/use-require.mjs
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);

// Now it works as in CommonJS, JSON included.
const catalog = require('../data/events.json');
const legacyPackage = require('commonjs-only-package');

console.log(`${catalog.length} events`);

// src/reports/occupancy.mjs
import { pathToFileURL } from 'node:url';

const isMainProgram = import.meta.url === pathToFileURL(process.argv[1]).href;

if (isMainProgram) {
  // Only with: node src/reports/occupancy.mjs
  runReport();
}

// Import attributes syntax (Node 20.10+ / 22+).
import catalog from '../data/events.json' with { type: 'json' };

console.log(catalog.length);

// src/lab/load.mjs
import { readFile } from 'node:fs/promises';

// await directly, without wrapping it in any async function.
const content = await readFile('data/events.json', 'utf8');
const catalog = JSON.parse(content);

console.log(`Loaded ${catalog.length} events`);

// CommonJS: you need a wrapper function and its .catch.
const { readFile } = require('node:fs/promises');

async function main() {
  const content = await readFile('data/events.json', 'utf8');
  const catalog = JSON.parse(content);
  console.log(`Loaded ${catalog.length} events`);
}

main().catch((error) => {
  console.error(error.message);
  process.exitCode = 1;
});

// 1. Asynchronous initialization before exporting.
const configuration = JSON.parse(await readFile('./config.json', 'utf8'));
export { configuration };

// 2. Choosing a dependency at run time.
const logger = process.env.NODE_ENV === 'production'
  ? await import('./production-logger.mjs')
  : await import('./development-logger.mjs');

// 3. Resources that must be ready before anyone uses the module.
const connection = await connectToDatabase();
export { connection };

// It works in both ESM and CommonJS.
const loaded = await import('./domain/event.mjs');
console.log(loaded.Event);

// With destructuring.
const { Event } = await import('./domain/event.mjs');

// src/lab/conditional-load.mjs

const mode = process.env.NODE_ENV ?? 'development';

// The path can be an expression: here it can.
const { logger } = await import(`./loggers/${mode}.mjs`);

logger.info('Escena Viva starting up');

// The ticket PDF generator is heavy and rarely used.
// We do not want to load it at every process startup.

export async function generateTicketPdf(ticket) {
  const { createPdf } = await import('./pdf/generator.mjs');
  return createPdf(ticket);
}

// src/utils/format.cjs  (CommonJS)
function formatPrice(cents) { /* ... */ }
function formatDate(isoDate) { /* ... */ }

module.exports = { formatPrice, formatDate };

// src/catalog.mjs  (ESM)

// The complete module.exports arrives as the DEFAULT export.
import format from './utils/format.cjs';
console.log(format.formatPrice(2500));   // Always works

// Named exports work... if Node manages to detect them.
import { formatPrice } from './utils/format.cjs';   // Usually works

// CommonJS with dynamic exports: the analyzer CANNOT detect them.
const functions = { formatPrice, formatDate };
for (const [name, fn] of Object.entries(functions)) {
  module.exports[name] = fn;
}

// From ESM:
import { formatPrice } from './format.cjs';
// SyntaxError: The requested module './format.cjs' does not provide
// an export named 'formatPrice'

// Import the whole object as the default and destructure afterwards.
import format from './utils/format.cjs';
const { formatPrice, formatDate } = format;

// src/legacy.cjs
const { Event } = require('./domain/event.mjs');

Error [ERR_REQUIRE_ESM]: require() of ES Module
/home/joan/escena-viva/src/domain/event.mjs not supported.
Instead change the require of event.mjs to a dynamic import() which is
available in all CommonJS modules.

// src/legacy.cjs
async function main() {
  const { Event } = await import('./domain/event.mjs');

  const event = new Event({ id: 'evt-001', title: 'Concierto de Otono' });
  console.log(event.toString());
}

main().catch((error) => {
  console.error(error.message);
  process.exitCode = 1;
});

// ---------- CommonJS ----------
function formatPrice(cents) {
  const euros = Math.floor(cents / 100);
  const remainder = String(cents % 100).padStart(2, '0');
  return `${euros}.${remainder} EUR`;
}

function formatDate(isoDate) { /* ... */ }
function generateTicketCode(year, sequence) { /* ... */ }

module.exports = { formatPrice, formatDate, generateTicketCode };

// ---------- ES modules ----------
export function formatPrice(cents) {
  const euros = Math.floor(cents / 100);
  const remainder = String(cents % 100).padStart(2, '0');
  return `${euros}.${remainder} EUR`;
}

export function formatDate(isoDate) { /* ... */ }
export function generateTicketCode(year, sequence) { /* ... */ }

// ---------- CommonJS ----------
const { formatPrice, formatDate } = require('../utils/format.js');

class Session {
  #sold = 0;
  /* ... the entire body, without a single change ... */
}

module.exports = { Session };

// ---------- ES modules ----------
import { formatPrice, formatDate } from '../utils/format.js';

export class Session {
  #sold = 0;
  /* ... the entire body, without a single change ... */
}

// ---------- CommonJS ----------
const EventEmitter = require('node:events');

const LOW_CAPACITY_THRESHOLD = 0.10;

class SalesManager extends EventEmitter { /* ... */ }

module.exports = { SalesManager, LOW_CAPACITY_THRESHOLD };

// ---------- ES modules ----------
import { EventEmitter } from 'node:events';

export const LOW_CAPACITY_THRESHOLD = 0.10;

export class SalesManager extends EventEmitter { /* ... */ }

// ---------- CommonJS ----------
const { Session } = require('./session.js');
const { Event } = require('./event.js');
const { SalesManager, LOW_CAPACITY_THRESHOLD } = require('./sales-manager.js');

module.exports = { Session, Event, SalesManager, LOW_CAPACITY_THRESHOLD };

// ---------- ES modules ----------
export { Session } from './session.js';
export { Event } from './event.js';
export { SalesManager, LOW_CAPACITY_THRESHOLD } from './sales-manager.js';

// ---------- CommonJS ----------
const catalog = [ /* the 3 events */ ];

function getCatalog() {
  return structuredClone(catalog);
}

function getEventById(id) { /* ... */ }

module.exports = { getCatalog, getEventById };

// ---------- ES modules ----------
// The array stays PRIVATE: by not exporting it, nobody outside can touch it.
const catalog = [ /* the 3 events */ ];

export function getCatalog() {
  return structuredClone(catalog);
}

export function getEventById(id) { /* ... */ }

// ---------- CommonJS ----------
const { getCatalog } = require('./catalog-data.js');
const { Event } = require('./domain');                 // No extension: valid
const { formatPrice } = require('./utils/format.js');

function main() { /* ... */ }

if (require.main === module) {
  main();
}

module.exports = { readOptions, main };

// ---------- ES modules ----------
import { pathToFileURL } from 'node:url';
import { getCatalog } from './catalog-data.js';
import { Event } from './domain/index.js';             // Extension MANDATORY
import { formatPrice } from './utils/format.js';

export function main() { /* ... */ }

// The equivalent of require.main === module
if (import.meta.url === pathToFileURL(process.argv[1]).href) {
  main();
}

// src/catalog-data.mjs  (a preview of module 3)
import { readFile } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';
import { dirname, join } from 'node:path';

const __dirname = dirname(fileURLToPath(import.meta.url));
const DATA_PATH = join(__dirname, '..', 'data', 'events.json');

// Top-level await: the catalog is loaded ONCE, when the module is imported.
// Whoever imports this module will get the data ready to use.
const catalog = JSON.parse(await readFile(DATA_PATH, 'utf8'));

export function getCatalog() {
  return structuredClone(catalog);
}

export function getEventById(id) {
  const event = catalog.find((e) => e.id === id);
  return event ? structuredClone(event) : undefined;
}

// escena-viva-esm/package.json
{
  "type": "module"
}

// src/utils/format.js
export function formatPrice(cents) {
  const euros = Math.floor(cents / 100);
  const remainder = String(cents % 100).padStart(2, '0');
  return `${euros}.${remainder} EUR`;
}

export function formatDate(isoDate) {
  const date = new Date(isoDate);
  const day = String(date.getDate()).padStart(2, '0');
  const month = String(date.getMonth() + 1).padStart(2, '0');
  const year = date.getFullYear();
  const hour = String(date.getHours()).padStart(2, '0');
  const minute = String(date.getMinutes()).padStart(2, '0');
  return `${day}/${month}/${year} ${hour}:${minute}`;
}

export function generateTicketCode(year, sequence) {
  return `EV-${year}-${String(sequence).padStart(6, '0')}`;
}

// src/domain/session.js
import { formatPrice, formatDate } from '../utils/format.js';

export class Session {
  #sold = 0;

  constructor({ id, dateTime, capacity, sold = 0, priceCents }) {
    this.id = id;
    this.dateTime = dateTime;
    this.capacity = capacity;
    this.priceCents = priceCents;
    this.#sold = sold;
  }

  get sold() { return this.#sold; }
  get available() { return this.capacity - this.#sold; }
  get occupancy() { return Math.round((this.#sold / this.capacity) * 100); }
  get soldOut() { return this.available === 0; }
  get priceEuros() { return (this.priceCents / 100).toFixed(2); }
  get revenueCents() { return this.#sold * this.priceCents; }

  sell(quantity = 1) {
    if (!Number.isInteger(quantity) || quantity < 1) {
      const error = new Error('The quantity must be a positive integer');
      error.code = 'INVALID_QUANTITY';
      throw error;
    }
    if (quantity > this.available) {
      const error = new Error(`Insufficient capacity in ${this.id}: ${this.available} left`);
      error.code = 'INSUFFICIENT_CAPACITY';
      throw error;
    }
    this.#sold += quantity;
    return this.#sold;
  }

  describe() {
    return (
      `${formatDate(this.dateTime)}  ${formatPrice(this.priceCents)}  ` +
      `${this.available}/${this.capacity} available  (${this.occupancy}% occupied)` +
      (this.soldOut ? '  [SOLD OUT]' : '')
    );
  }

  toJSON() {
    return {
      id: this.id,
      dateTime: this.dateTime,
      capacity: this.capacity,
      sold: this.#sold,
      priceCents: this.priceCents
    };
  }
}

// src/domain/index.js
export { Session } from './session.js';
export { Event } from './event.js';
export { SalesManager, LOW_CAPACITY_THRESHOLD } from './sales-manager.js';

// src/catalog.js  (only the parts that change)
import { pathToFileURL } from 'node:url';
import { getCatalog } from './catalog-data.js';
import { Event } from './domain/index.js';
import { formatPrice } from './utils/format.js';

export function readOptions(args) { /* identical */ }

export function main() { /* identical */ }

if (import.meta.url === pathToFileURL(process.argv[1]).href) {
  main();
}

node src/catalog.js --table
# IDENTICAL output to the CommonJS version
# 3 events | capacity 3000 | sold 1811 | available 1189 | revenue 62298.00 EUR

// src/utils/format.cjs
// CommonJS with STATIC exports: Node's analyzer detects them.
function formatPrice(cents) {
  const euros = Math.floor(cents / 100);
  return `${euros}.${String(cents % 100).padStart(2, '0')} EUR`;
}

function formatDate(isoDate) {
  return isoDate.slice(0, 10).split('-').reverse().join('/');
}

module.exports = { formatPrice, formatDate };

// src/utils/dynamic-legacy.cjs
// CommonJS with DYNAMIC exports: the analyzer CANNOT detect them.
function calculateOccupancy(session) {
  return Math.round((session.sold / session.capacity) * 100);
}

function calculateAvailable(session) {
  return session.capacity - session.sold;
}

// Dynamic construction: only known at run time.
const functions = { calculateOccupancy, calculateAvailable };
for (const [name, fn] of Object.entries(functions)) {
  module.exports[name] = fn;
}

// src/domain/session.mjs
// ESM importing CommonJS in its two variants.

// 1. Static exports: the named import WORKS.
import { formatPrice } from '../utils/format.cjs';

// 2. Dynamic exports: the named one WOULD FAIL.
//    import { calculateOccupancy } from '../utils/dynamic-legacy.cjs';
//    SyntaxError: does not provide an export named 'calculateOccupancy'
//
//    Universal solution: import the default and destructure.
import legacy from '../utils/dynamic-legacy.cjs';
const { calculateOccupancy, calculateAvailable } = legacy;

export class Session {
  constructor({ id, capacity, sold = 0, priceCents }) {
    this.id = id;
    this.capacity = capacity;
    this.sold = sold;
    this.priceCents = priceCents;
  }

  describe() {
    return (
      `${this.id}  ${formatPrice(this.priceCents)}  ` +
      `${calculateAvailable(this)} available  (${calculateOccupancy(this)}%)`
    );
  }
}

// src/report.cjs
// CommonJS that needs a class defined in an ES module.

// 1. Demonstration that require FAILS.
try {
  const { Session } = require('./domain/session.mjs');
  console.log('This is not printed:', Session);
} catch (error) {
  console.error(`require failed with code: ${error.code}`);
  console.error(`  ${error.message.split('\n')[0]}`);
}

// 2. The solution with dynamic import.
async function main() {
  const { Session } = await import('./domain/session.mjs');

  const session = new Session({
    id: 'ses-002-1', capacity: 120, sold: 118, priceCents: 1800
  });

  console.log('');
  console.log('With await import() it DOES work:');
  console.log(`  ${session.describe()}`);
}

main().catch((error) => {
  console.error(`Failure: ${error.message}`);
  process.exitCode = 1;
});

node src/report.cjs

require failed with code: ERR_REQUIRE_ESM
  require() of ES Module /home/joan/escena-viva-mixed/src/domain/session.mjs not supported.

With await import() it DOES work:
  ses-002-1  18.00 EUR  2 available  (98%)

// src/catalog-data.mjs
// Loading the catalog with top-level await. Exclusive to ESM.

import { readFile } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';
import { dirname, join } from 'node:path';

const __dirname = dirname(fileURLToPath(import.meta.url));
const DATA_PATH = join(__dirname, '..', 'data', 'events.json');

// 1 and 2. Loading with top-level await and graceful degradation on failure.
let catalog = [];

try {
  const content = await readFile(DATA_PATH, 'utf8');
  catalog = JSON.parse(content);
  console.error(`[catalog] loaded ${catalog.length} events from ${DATA_PATH}`);
} catch (error) {
  if (error.code === 'ENOENT') {
    console.error(`[catalog] WARNING: ${DATA_PATH} not found. Empty catalog.`);
  } else if (error instanceof SyntaxError) {
    console.error(`[catalog] WARNING: the file is not valid JSON (${error.message}).`);
  } else {
    console.error(`[catalog] WARNING: read failure (${error.message}).`);
  }
  // We do not rethrow: the application starts with an empty catalog.
}

// 4. Timestamp of the moment of loading.
export const LOADED_AT = new Date().toISOString();

// 3. Data access, always with copies.
export function getCatalog() {
  return structuredClone(catalog);
}

export function getEventById(id) {
  const event = catalog.find((e) => e.id === id);
  return event ? structuredClone(event) : undefined;
}

export function getSession(sessionId) {
  for (const event of catalog) {
    const session = event.sessions.find((s) => s.id === sessionId);
    if (session) {
      return structuredClone({ event: { id: event.id, title: event.title }, session });
    }
  }
  return undefined;
}

// src/consumer-a.mjs
import { LOADED_AT, getCatalog } from './catalog-data.mjs';

export function report() {
  return { module: 'consumer-a', loadedAt: LOADED_AT, events: getCatalog().length };
}

// src/consumer-b.mjs
import { LOADED_AT, getEventById } from './catalog-data.mjs';

export function report() {
  const event = getEventById('evt-002');
  return { module: 'consumer-b', loadedAt: LOADED_AT, title: event?.title ?? '(no data)' };
}

// src/main.mjs
// No wrapper function: top-level await throughout the file.

import { setTimeout as sleep } from 'node:timers/promises';
import { LOADED_AT, getCatalog, getSession } from './catalog-data.mjs';
import { report as reportA } from './consumer-a.mjs';
import { report as reportB } from './consumer-b.mjs';

const events = getCatalog();

console.log('CATALOG');
console.table(events.map((e) => ({
  id: e.id,
  title: e.title,
  venue: e.venue,
  sessions: e.sessions.length,
  capacity: e.sessions.reduce((t, s) => t + s.capacity, 0),
  sold: e.sessions.reduce((t, s) => t + s.sold, 0)
})));

const found = getSession('ses-002-1');
console.log('');
console.log(`Session ses-002-1: ${found.event.title}, ` +
  `${found.session.capacity - found.session.sold} available`);

// A pause with top-level await: impossible in CommonJS.
await sleep(50);

// 4. The timestamp is the SAME in all three modules.
console.log('');
console.log('MODULE CACHE IN ESM');
console.table([
  { module: 'main', loadedAt: LOADED_AT, data: `${events.length} events` },
  { ...reportA(), data: `${reportA().events} events` },
  { ...reportB(), data: reportB().title }
]);

const allEqual = LOADED_AT === reportA().loadedAt && LOADED_AT === reportB().loadedAt;
console.log('');
console.log(`Same timestamp in all three modules? ${allEqual}`);

[catalog] loaded 3 events from /home/joan/escena-viva-esm/data/events.json
CATALOG
┌─────────┬───────────┬─────────────────────────────────┬────────────────────┬──────────┬──────────┬──────┐
│ (index) │ id        │ title                           │ venue              │ sessions │ capacity │ sold │
├─────────┼───────────┼─────────────────────────────────┼────────────────────┼──────────┼──────────┼──────┤
│ 0       │ 'evt-001' │ 'Concierto de Otono'            │ 'Teatro Almendra'  │ 2        │ 840      │ 276  │
│ 1       │ 'evt-002' │ 'Noche de Monologos'            │ 'Sala Boveda'      │ 3        │ 360      │ 175  │
│ 2       │ 'evt-003' │ 'Festival de Jazz de Primavera' │ 'Auditorio Ribera' │ 2        │ 1800     │ 1360 │
└─────────┴───────────┴─────────────────────────────────┴────────────────────┴──────────┴──────────┴──────┘

Session ses-002-1: Noche de Monologos, 2 available

MODULE CACHE IN ESM
┌─────────┬──────────────┬────────────────────────────┬──────────────────────┐
│ (index) │ module       │ loadedAt                   │ data                 │
├─────────┼──────────────┼────────────────────────────┼──────────────────────┤
│ 0       │ 'main'       │ '2026-08-11T18:42:07.331Z' │ '3 events'           │
│ 1       │ 'consumer-a' │ '2026-08-11T18:42:07.331Z' │ '3 events'           │
│ 2       │ 'consumer-b' │ '2026-08-11T18:42:07.331Z' │ 'Noche de Monologos' │
└─────────┴──────────────┴────────────────────────────┴──────────────────────┘

Same timestamp in all three modules? true