feat(di): export ConcretePortClass for ports built from data

[btravers]

Found while building @btravstack/config, whose Config(prefix)(shape) derives a port's service from a schema record.

The gap

PortClass<Id> (exported by #1 for declaration emit) covers the case where Service is still open — supplied later by a heritage clause at the consumer's own class X extends Port("X")<Shape> {}. The emitter stops at PortClass<"Metrics"> and everything works.

A factory that applies Service itself returns a class whose instance type is already resolved. There is no exported name to stop at, so the emitter expands to the module-private [ID]/[SERVICE] brands:

error TS4023: Exported variable 'defineFixedPort' has or is using name 'ID'
from external module "@btravstack/di" but cannot be named.

Same class of bug #1 fixed, in the one shape that fix did not reach — and emit-guards.ts says as much in its own words ("nothing in the emitted output needs them once the class types are reachable"), which held until a port could be built from data.

The fix

FixedPortClass<Id, Service> — the name such a factory annotates its return with. Exporting PortInstance was tried first and is not enough: it names the instance, not the class, so the emitter still expands. Annotating the return is what stops it, which also means the smaller widening is the one that ships — PortInstance and the brand symbols stay unexported, so a port instance remains unforgeable and the @ts-expect-error guards on ID/SERVICE/MANY are untouched.

defineFixedPort in examples/hexagonal-order-api/src/emit-guards.ts is the regression fixture, sitting beside the existing definePort/defineSetPort guards it complements: without the export it is TS4023, which I verified by reproducing the failure before adding the type.

Gate green: 10/10 turbo tasks (build, typecheck incl. the emit re-check, test), lint and format clean.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a new exported type alias to support TypeScript declaration emit for ports whose service type is fixed inside a factory (i.e., factories that return a fully-resolved port class value). This closes a remaining TS4023 failure mode for downstream consumers emitting .d.ts.

Changes:

• Introduces FixedPortClass<Id, Service> in port.ts to name “fixed-service” port class values without exporting the private brand symbols.
• Re-exports FixedPortClass (type-only) from the package index alongside PortClass/ManyPortClass.
• Extends the declaration-emit regression fixture (emit-guards.ts) with defineFixedPort, and adds a changeset for the new exported type.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
packages/di/src/port.ts	Adds the FixedPortClass<Id, Service> type alias for naming fixed-service port classes.
packages/di/src/index.ts	Re-exports FixedPortClass as a type to make it usable by consumers for .d.ts emit.
examples/hexagonal-order-api/src/emit-guards.ts	Adds a new emit-guard shape (defineFixedPort) using FixedPortClass.
.changeset/fixed-port-class.md	Documents the new export and why it’s needed (TS4023 scenario).

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[btravers]

Fixed in fee47a6. The comment claimed the emitter needed PortInstance exported; that was left over from the first attempt, which did export it and did NOT work — naming the instance does not stop the emitter, annotating the factory's return does. The comment now says that, and says the annotation is the stop, so a reader who deletes it knows what breaks.

[btravers]

Suggested change

	export type ManyPortClass<Id extends string> = {
	/**
	* A port class whose `Service` is already applied — what a factory returns when
	* it builds a port from data rather than from a type argument
	* (`Config(prefix)(shape)` deriving a service from a schema record).
	*
	* `PortClass<Id>` covers the open case, where `Service` is still supplied by a
	* heritage clause at the consumer's own `class X extends Port("X")<Shape> {}`.
	* Once a factory has applied it, the return type is a class whose instance is a
	* fully-resolved `PortInstance`, and the declaration emitter has no exported
	* name to stop at: it expands to the `[ID]`/`[SERVICE]` brands and every
	* consumer fails with `TS4023`. Annotating such a factory's return with this
	* alias is the stop the emitter needs — see `defineFixedPort` in
	* `examples/hexagonal-order-api/src/emit-guards.ts`.
	*
	* The brands themselves stay unexported, so this buys naming, not forgery.
	*/
	export type FixedPortClass<Id extends string, Service> = {
	new (): PortInstance<Id, Service>;
	readonly portId: Id;
	};
	/**
	* A set port: several providers may target it, and `Context.get` yields every
	* contribution rather than one service. `Port.many("Id")<Member>` fixes the
	* *member* shape via the same generic-heritage-instantiation trick
	* `PortClass` uses (`class Handlers extends Port.many("Id")<Member> {}`), but
	* the port's own `Service` — what actually lands in a `Context` and what
	* `Context.get` returns — is `readonly Member[]`, not `Member`. The `[MANY]`
	* brand on the instance type exists purely at the type level (no
	* `ManyPortClass` is ever constructed at runtime; ports are phantom tokens,
	* same as `PortClass`) so a member's *own* shape can be recovered from a
	* concrete set-port class via `MemberOf` below, the same way `ServiceOf`
	* recovers an ordinary port's shape from `PortInstance`.
	*
	* The `many: true` *static* field is the actual runtime discriminant —
	* `build.ts`'s `plan`/`constructLevel` read `port.many` off the concrete
	* class object at runtime (inherited from whatever `Port.many` returns, the
	* same way a concrete port's `portId` is inherited), since the `[MANY]`
	* symbol lives only in the (never-instantiated) instance type and cannot be
	* read back at runtime.
	*/
	export type ManyPortClass<Id extends string> = {

[btravers]

Would FinalPort be a better naming than FixedPort? Or ValuePort?

[btravers]

ConcretePortClass — done in e351fb4, across the type, the guard (defineConcretePort), the changeset and the prose.

Neither of your two quite fit, but they pushed me to the word the repo had already chosen. Final carries the Java sealed-class connotation — it suggests the class cannot be extended, when what actually changed is that the Service type argument is bound. Value captures the real axis (built from a value rather than a type argument) but reads cold as though the port's service is a value, or as though it carries something different from other ports.

The deciding evidence was already in port.ts: the existing note on PortClass says a port class "has a concrete constructor once Shape is fixed by the heritage clause". So the state has a name here, and the type had a different one. Now the pair reads as the distinction it is — generic PortClass<Id>, concrete ConcretePortClass<Id, Service> — and the paragraph explaining it uses the same word as the thing it explains.

@btravstack/config follows in its own commit (fccfd45).

[btravers]

Closing unmerged — the need evaporated.

This PR existed to support a design where @btravstack/config's Config(prefix)(shape) returned a value that was simultaneously a di Port and a di Module. Because that factory applied Service itself, its return type was a service-applied port class, the declaration emitter had no exported name to stop at, and consumers hit TS4023 — hence ConcretePortClass.

Benoit's review of the config design took that apart at the root: a concrete port is not a port any more; a port aims to be adapted. Welding the port to its environment-parsing provider meant a test could not hand it a literal and a future file or secret-manager source could not be a different adapter for the same port.

config is reworked so it declares no port at all — it implements one the starter declares normally:

export class AmqpConfig extends Port("AmqpConfig")<ValueOf<typeof shape>> {}
export const AmqpConfigFromEnv = Config(AmqpConfig, "AMQP")(shape);

Config(...) now returns a Module<InstanceType<P>, never, ConfigSource>. Every name in that is printable, so no port class is ever emitted from a factory and the TS4023 this PR fixed cannot occur.

Verified rather than assumed: config's full gate — build, typecheck (including declaration emit), 27 tests, lint, format — is green against the published @btravstack/di@0.1.0, resolved from the registry with no workspace override. So di needs no change for config to ship.

Worth keeping from this branch, if the shape ever comes back: exporting PortInstance alone does not fix it — naming the instance does not stop the emitter; annotating the factory's return does. The defineConcretePort guard in emit-guards.ts is the fixture that proved it.

#13 (unthrown 5.5.0 catalog) is unaffected and still worth merging.

[btravers]

Reopening. Benoit's review of the config API settled on the one-value shape after all — Config("AmqpConfig")({ … }) returning a single value that is both the di module and the port token, so imports: [amqpConfig] and ctx.get(amqpConfig) name the same thing.

That means a factory does apply Service itself again, its return type is a port class the declaration emitter cannot name, and TS4023 is back — which is precisely what this PR fixes. The reasoning I closed it with ("no factory returns a port class any more") no longer holds.

Also worth recording, since it corrects the argument that led to closing it: I had claimed the one-value shape made a port un-adaptable. That was wrong. The value is a token, and its module statics are only consulted when it appears in imports: — so a test can always write provides: [Provider(amqpConfig)({ value: … })] and simply not import it. Adaptability was never the trade-off; declaration emit was, and this PR is the fix for it.

Nothing about the branch changed while it was closed: the type is ConcretePortClass<Id, Service> (renamed per your review), defineConcretePort in emit-guards.ts is the regression fixture, and the brands stay unexported so naming the class buys no forgery.

[btravers]

Reopened. The config API settled on the one-value shape after all — Config("AmqpConfig")({ … }) returning a single value that is both the di module and the port token, so imports: [amqpConfig] and ctx.get(amqpConfig) name the same thing.

That means a factory applies Service itself again, its return type is a port class the declaration emitter cannot name, and TS4023 is back — exactly what this PR fixes. The reason I closed it ("no factory returns a port class any more") stopped being true.

Worth recording, because it corrects the argument that led to closing it: I had claimed the one-value shape made a port un-adaptable. That was wrong. The value is a token, and its module statics are only consulted when it appears in imports: — so a test can always write provides: [Provider(amqpConfig)({ value: … })] and simply not import it. Adaptability was never the trade-off; declaration emit was, and this is the fix for it.

The branch is unchanged from when it was closed: the type is ConcretePortClass<Id, Service> (renamed per your review), defineConcretePort in emit-guards.ts is the regression fixture that fails with TS4023 without the export, and the brand symbols stay unexported so naming the class buys no forgery. Title updated to match the rename.

One mechanical note: closing the PR deleted the branch, so I restored it from the local commits — same SHAs (e351fb4 at the head).

[btravers]

Rebased onto main (was based on a commit predating #13's catalog bump to unthrown 5.5.0). Build, typecheck and the 40 tests are green on 5.5.0; ConcretePortClass is unchanged.

Worth recording why the rebase mattered beyond hygiene: btravstack/start#35 builds @btravstack/config against this branch through a link: override, and link: is a raw filesystem symlink rather than a workspace package — so that dist resolved its bare unthrown import from this checkout's node_modules. Two physically distinct installs of the same version are structurally identical but nominally distinct to tsc, which broke every recursive Result/AsyncResult generic across the boundary. Aligning the catalogs removed the need for a second override downstream.