Speed up codebase type-checking by collapsing dispatcher path overloads

[2chanhaeng]

Fixes #613.

Background

The setObjectDispatcher(), setCollectionDispatcher(), and setOrderedCollectionDispatcher() methods on FederationBuilderImpl typed their path parameter as RFC 6570 template-literal unions. Rfc6570Expression<TParam> is an 8-member union, and these overloads interpolated it up to four times, so each path type expanded to a Cartesian product of up to $8^4 = 4096$ template-literal variants.

TypeScript spent almost all of deno check's time structurally comparing these enormous unions. The cost was not confined to a single file: the context boundary checks (ContextImpl/FederationImpl vs Context/Federation) dragged these path types in throughout the type graph, so the combinatorial blowup propagated across the whole project.

Change

Collapse the affected dispatcher overloads on FederationBuilderImpl to a single path: string signature:

• setObjectDispatcher() — removed 6 template-literal overloads (interpolated Rfc6570Expression up to three times, 8^3 = 512 variants, plus several simple multi-variable forms).
• setCollectionDispatcher() and setOrderedCollectionDispatcher() — removed the template-literal overloads (up to 8^4 = 4096 variants each).

The net diff is 183 deletions in a single file (packages/fedify/src/federation/builder.ts).

Public API is unchanged

The template-literal overloads are kept on the public Federatable interface (and thus on Federation and FederationBuilder, which extend it). Users still get the same compile-time path validation and autocompletion. Only the internal implementation class signature was collapsed; because path: string is a wider, compatible implementation signature, it still satisfies the interface's narrower overloads.

Nothing is lost at runtime

Path validity—including the "one or more variables" requirement—is still enforced at runtime via assertPath() and Router.variables() (backed by @fedify/uri-template), exactly as before. The only thing removed is the costly compile-time RFC 6570 shape checking.

Impact

Full-codebase type-checking (mise run check:types) drops from ~99s to ~13s.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: dc4e3f3a-d67f-467b-bdf7-4ea9501c3541

📥 Commits

Reviewing files that changed from the base of the PR and between ee801b8 and bb2ef0a.

📒 Files selected for processing (2)

• CHANGES.md
• packages/fedify/src/federation/builder.ts

---

📝 Walkthrough

Walkthrough

The PR consolidates three public dispatcher registration method signatures in FederationBuilder by replacing template-literal path overloads with a single path: string parameter; it also updates CHANGES.md with a Version 2.3.0 entry and related reference fixes.

Changes

Dispatcher method signature consolidation

Layer / File(s)	Summary
Consolidate dispatcher method signatures packages/fedify/src/federation/builder.ts	setObjectDispatcher, setCollectionDispatcher, and setOrderedCollectionDispatcher accept path: string instead of template-literal overload variants. Methods retain runtime assertPath validation and derive/forward route variables via Router.variables() or internal casts.
Changelog entry and references CHANGES.md	Adds Version 2.3.0 bullet describing the TypeScript type-checking improvement and adds/moves issue reference definitions including [#800].

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: removing RFC 6570 template-literal overloads from dispatcher methods to improve type-checking performance.
Description check	✅ Passed	The description is detailed and directly related to the changeset, explaining the performance problem, solution, public API preservation, and measured impact.
Linked Issues check	✅ Passed	The PR meaningfully addresses the primary coding objective of #613 by removing costly RFC 6570 template-literal overloads and demonstrating substantial type-check time reduction (99s→13s), though it is a partial fix for the broader performance investigation goals.
Out of Scope Changes check	✅ Passed	All changes are in-scope: builder.ts removes the specified overloads, and CHANGES.md documents the optimization—no unrelated modifications detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request simplifies the method signatures of setObjectDispatcher, setCollectionDispatcher, and setOrderedCollectionDispatcher in FederationBuilderImpl by removing several complex template literal type overloads for the path parameter. I have no feedback to provide as there are no review comments.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[dahlia]

Although it's not a hard change, but since speed-ups are good news, we should add an entry about this speed-up to CHANGES.md.

[2chanhaeng]

Although it's not a hard change, but since speed-ups are good news, we should add an entry about this speed-up to CHANGES.md.

Addressed in 878ab20.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

Files with missing lines	Coverage Δ
packages/fedify/src/federation/builder.ts	60.68% <ø> (ø)

... and 17 files with indirect coverage changes

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[sij411]

I can reproduce that this meaningfully improves the expensive type-check phase, so I agree this is relevant to #613.

In my local A/B check against the PR base, the workspace deno check phase got much faster after this change. So this does address one real source of the slowdown.

That said, I would be careful about saying this fully fixes #613. The issue asks for the main slowdown sources to be understood and documented, and for check-all/pre-commit validation to become meaningfully faster without reducing coverage. This PR identifies and improves one major source, but it does not by itself show that the remaining check-all cost is understood, nor does it include a reusable benchmark/diagnostic artifact that future changes can compare against.

There is also a subtle API-boundary point worth documenting. Calls through the supported factory path still preserve the public overloads:

createFederationBuilder<void>().setObjectDispatcher(
  Note,
  "/notes/{id}",
  (_ctx, values) => {
    values.id satisfies string;
    // @ts-expect-error still rejected
    values.missing;
    return null;
  },
);

But direct use of the implementation class no longer has that compile-time protection:

  new FederationBuilderImpl<void>().setObjectDispatcher(
    Note,
    "/notes/{id}",
    (_ctx, values) => {
      // @ts-expect-error now unused
      values.missing;
      return null;
    },
  );

This seems acceptable if FederationBuilderImpl is intentionally internal; it is not re-exported from @fedify/fedify or @fedify/fedify/federation. But I think the PR description should say that explicitly: the public FederationBuilder/Federatable surface is unchanged, while direct source-level use of FederationBuilderImpl moves those checks from compile time to runtime.

So I would suggest either:

• clarify that this is a partial fix for #613 focused on the dispatcher overload hot path; and
• add a small type-level regression test for the supported factory/public path, or document FederationBuilderImpl as internal.

[2chanhaeng]

I can reproduce that this meaningfully improves the expensive type-check phase, so I agree this is relevant to #613.

In my local A/B check against the PR base, the workspace deno check phase got much faster after this change. So this does address one real source of the slowdown.

That said, I would be careful about saying this fully fixes #613. The issue asks for the main slowdown sources to be understood and documented, and for check-all/pre-commit validation to become meaningfully faster without reducing coverage. This PR identifies and improves one major source, but it does not by itself show that the remaining check-all cost is understood, nor does it include a reusable benchmark/diagnostic artifact that future changes can compare against.

There is also a subtle API-boundary point worth documenting. Calls through the supported factory path still preserve the public overloads:

createFederationBuilder<void>().setObjectDispatcher(
  Note,
  "/notes/{id}",
  (_ctx, values) => {
    values.id satisfies string;
    // @ts-expect-error still rejected
    values.missing;
    return null;
  },
);

But direct use of the implementation class no longer has that compile-time protection:

  new FederationBuilderImpl<void>().setObjectDispatcher(
    Note,
    "/notes/{id}",
    (_ctx, values) => {
      // @ts-expect-error now unused
      values.missing;
      return null;
    },
  );

This seems acceptable if FederationBuilderImpl is intentionally internal; it is not re-exported from @fedify/fedify or @fedify/fedify/federation. But I think the PR description should say that explicitly: the public FederationBuilder/Federatable surface is unchanged, while direct source-level use of FederationBuilderImpl moves those checks from compile time to runtime.

So I would suggest either:

* clarify that this is a partial fix for #613 focused on the dispatcher overload hot path; and

* add a small type-level regression test for the supported factory/public path, or document `FederationBuilderImpl` as internal.

Addressed in bb2ef0a. Thanks!