A shared `db.mjs` module in your service runs `const pool = await connectToDatabase()` at the top level. Startup has become slow and the service sometimes hangs on boot. Explain why, and how you would restructure it.

## What the code actually does ```js // db.mjs — the problem export const pool = await connectToDatabase(process.env.DATABASE_URL); ``` This is not "connect when first needed". It is *connect during module evaluation*, which happens as part of loading the graph, before your entry point's first statement runs. Every module that imports `db.mjs` becomes an async module too, and so does every module importing those — the asynchrony propagates up the whole dependency chain. ## Symptom one: inherited latency The connection cost is not paid once by `db.mjs`; it gates every consumer. A route module that imports `db.mjs` only to satisfy one rarely-used handler still cannot run its own top-level code until the connection is up. Worse, the cost is invisible where it is felt: the person debugging slow boot is reading `routes/users.mjs`, which contains no `await` at all. This also compounds. Add a second module doing `await loadFeatureFlags()` and a third doing `await warmCache()`, and if they are on the same dependency chain their waits are serialised rather than overlapped, because a module's dependencies are fully evaluated before its own body. ## Symptom two: no control surface Module evaluation is not a function call you make, so there is nowhere to put the things production code needs: - **Timeout.** You cannot race the evaluation against a deadline. - **Retry/backoff.** A failed evaluation is cached as failed; re-importing does not re-run the body. - **Ordering.** You cannot say "start the HTTP server first, connect lazily after". - **Tests.** Every test file that touches this module transitively opens a real connection at import time, so unit tests need a live database or fragile module mocking. ## Symptom three: the boot hang If `connectToDatabase()` returns a promise that never settles — a TCP connect to an address that blackholes packets, a driver waiting on an unbounded internal queue — then `db.mjs` never finishes evaluating. Its dependents never run. No error is thrown, no rejection is reported, and if your health check module is anywhere on that dependency chain (it usually is, in a monolithic entry point) the process is alive but answers nothing. Orchestrators see a container that started and never became ready, with an empty log. ## The restructure Move the I/O out of module scope and behind a memoised accessor: ```js // db.mjs — lazy and memoised let poolPromise; export function getPool() { poolPromise ??= connectToDatabase(process.env.DATABASE_URL); return poolPromise; } ``` Importing `db.mjs` is now free. The first caller triggers the connection, concurrent callers share the same in-flight promise (so you do not open N pools), and every later call gets the resolved one. Consumers do `const pool = await getPool()` inside an already-async request handler, where `try`/`catch` works, where you can wrap the call in a timeout or retry helper, and where a failure produces a 503 for one request instead of a dead process. If you want a failed connection to be retryable, clear the memo on rejection: ```js export function getPool() { poolPromise ??= connectToDatabase(process.env.DATABASE_URL).catch((err) => { poolPromise = undefined; // allow a later attempt throw err; }); return poolPromise; } ``` An equally defensible variant is an explicit `await initDb()` called once from the entry point, after the server is listening — that keeps startup order visible in one file instead of emerging from the import graph. ## When top-level await is still the right tool It is not a rule against the feature. Top-level await earns its place when the program genuinely cannot proceed without the value and the wait belongs to the program as a whole: picking an implementation with a conditional dynamic `import()`, instantiating a WebAssembly module, reading a config file at the entry point. The distinguishing questions are *how many modules inherit this wait*, and *can it fail or hang in production*. A cheap, local, always-succeeding await at the entry point is fine. A network round-trip in a shared leaf module is the case in the question. ## What a strong answer sounds like Name the mechanism (module evaluation is where the wait happens, and it is contagious upward), name the three concrete symptoms (inherited latency, no timeout/retry surface, silent hang), and give the memoised-accessor fix with the detail that concurrent callers must share one in-flight promise. Mentioning the testability cost usually lands well, because it is the symptom teams hit first.