Keep a port private

Goal: a module with internals — a connection pool, a raw client, a parsed config — that nothing outside the module can reach, with the boundary enforced by the compiler rather than a naming convention.

Export the surface, withhold the rest

Privacy in di is not a keyword; it is the exports list. Everything a module provides but does not export is internal:

const Persistence = Module("Persistence")({
  imports: [Config],
  provides: [
    Provider(Pool)([AppConfig], {
      acquire: openPool,
      release: (pool) => pool.close(),
    }),
    Provider(OrderRepository)([Pool], {
      sync: (pool) => makeRepository(pool),
    }),
  ],
  exports: [OrderRepository], // Pool and AppConfig: not listed, not visible.
});

Any module importing Persistence sees exactly one port:

const App = Module("App")({
  imports: [Persistence],
  provides: [
    Provider(GetOrder)([OrderRepository], { class: GetOrderInteractor }), // ✓
    Provider(Audit)([Pool], { sync: makeAudit }), // ✗ no provider for Pool here
  ],
  exports: [GetOrder],
});

The second provider does not wire: Pool is not among what App can see (its own provides plus its imports' exports), so the dependency stays unmet — and surfaces as the "UNSATISFIED DEPENDENCIES" compile error at the build call.

And on a built context:

const ctx = await Module.scoped(App, use); /* ... */
ctx.get(Pool); // ✗ does not compile
ctx.get(GetOrder); // ✓

What makes this work — and what it is not

The built container is a single flat map at runtime. Pool's service is genuinely in it — there is nowhere else to put it — so this is not runtime sandboxing. What exports withholds is the type: the built Context's channel contains only the exported ports, so ctx.get(Pool) has no overload that accepts it. The port class itself may even be a plain TypeScript export (so tests can name it); what matters is the DI module's exports list.

The hexagonal-order-api example pins exactly this with a @ts-expect-error in its index.test-d.ts — the guarantee is compile-time-only, so the proof is a type-level test, not a runtime assertion. (Why that split.)

Exports are checked, not declarative

The exports list cannot lie:

Module("Persistence")({
  provides: [Provider(OrderRepository)([Pool], { sync: makeRepository })],
  exports: [OrderRepository, Metrics], // ✗ Metrics: neither provided nor imported
});

An export must be available — provided by this module, or exported by one of its imports. Exporting something never imported, or re-exporting a neighbour's internal, is a compile error at the declaration, not a silent no-op.

Re-export a whole module

Listing an imported module in exports re-exports its whole public surface — useful for a facade module that groups plugins without re-listing every port:

const AppModule = Module("App")({
  imports: [DatabaseModule, CacheModule],
  exports: [DatabaseModule, CacheModule],
});

What stays private in DatabaseModule stays private here too: a whole-module re-export forwards the module's exports, not its internals.

Related

• Modules — imports/provides/exports, precisely.
• Modules and privacy — the flat map, the withheld type, and why that is enough.
• Swap an adapter for tests — privacy is what makes the adapters interchangeable.