exported url generator

[jonathanMLDev]

Pull Request

src/server/url-generation.ts

• UrlGeneratorFn — exported alias of UrlGenerator; registry map typed as UrlGeneratorFn.
• RegisterBuiltinUrlGeneratorsOptions — { reinstallBuiltins?: boolean }.
• registerBuiltinUrlGenerators(options?) — unchanged default (idempotent first install). With { reinstallBuiltins: true }, always reapplies built-in mailing and slack-Cpplang handlers (for tests / restoring after overrides).
• registerUrlGenerator — second parameter typed as UrlGeneratorFn.

src/server.ts

• Re-exports UrlGeneratorFn and RegisterBuiltinUrlGeneratorsOptions.
• Package doc mentions UrlGeneratorFn.

src/server/url-generation.test.ts

• New registerUrlGenerator describe block with afterEach cleanup (unregisterUrlGenerator('acme-docs') + registerBuiltinUrlGenerators({ reinstallBuiltins: true })).
• Tests: custom namespace (acme-docs) and override mailing with a fixed URL.

README.md

• “Custom URL generators” subsection after Deployment model (when to register vs override, example using UrlGeneratorFn / UrlGenerationResult, link to examples/custom-url-generator.ts

CHANGE- LOG.md

• Unreleased → Added bullet for UrlGeneratorFn, reinstallBuiltins, README section, and tests.

Checks:

npm run typecheck, npm run test (74 tests), npm run lint — all pass

Related Issue

close #83

Summary by CodeRabbit

• New Features

  • Register custom URL generator functions per namespace and override built-in generators.
  • Option to reinstall default generators to restore original behavior.

• Documentation

  • README updated with a "Custom URL generators" guide and TypeScript usage example.

• Tests

  • Added tests for registration, override behavior, and teardown/reset of URL generators.

• Chores

  • CHANGELOG updated with the new entries.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a8967fa8-29d8-465c-96ac-4b7fce85dab7

📥 Commits

Reviewing files that changed from the base of the PR and between e55e239 and c94a459.

📒 Files selected for processing (3)

• CHANGELOG.md
• README.md
• src/server.ts

✅ Files skipped from review due to trivial changes (1)

• CHANGELOG.md

🚧 Files skipped from review as they are similar to previous changes (2)

• README.md
• src/server.ts

---

📝 Walkthrough

Walkthrough

This PR exposes a type alias and runtime APIs to register custom URL generators: it exports UrlGeneratorFn, adds RegisterBuiltinUrlGeneratorsOptions to allow reinstalling built-ins, updates registerBuiltinUrlGenerators to accept options, and adds validation/normalization to registerUrlGenerator.

Changes

Custom URL Generator Registration

Layer / File(s)	Summary
Custom URL generator registration API src/server/url-generation.ts	Adds UrlGeneratorFn alias, changes the registry to store UrlGeneratorFn, introduces RegisterBuiltinUrlGeneratorsOptions (reinstallBuiltins?: boolean) and makes registerBuiltinUrlGenerators(options?) conditionally re-register built-ins. Updates registerUrlGenerator to trim/validate namespace and require a function before registering.
Tests for registration behavior src/server/url-generation.test.ts	Adds imports and afterEach teardown plus tests verifying custom namespace registration and that a custom generator can override the built-in mailing generator.
Module exports and docs src/server.ts, README.md, CHANGELOG.md	Re-exports UrlGeneratorFn and RegisterBuiltinUrlGeneratorsOptions from the server public surface; documents the custom URL generator APIs and usage in README and CHANGELOG.

🎯 3 (Moderate) | ⏱️ ~20 minutes

"🐰 A generator's born, no longer shy,
Custom namespaces now catch the eye!
Register, override, extend with glee,
No fork required for your URL spree! 🌟"

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'exported url generator' is vague and overly broad, using generic language that doesn't convey the specific functional changes made in this PR.	Consider a more descriptive title such as 'Add URL generator registration API with built-in reinstall option' to better reflect the primary changes.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	All acceptance criteria from issue #83 are met: registration function exported [registerUrlGenerator], types exported [UrlGeneratorFn, RegisterBuiltinUrlGeneratorsOptions], built-ins preserved, validation implemented, tests added [custom registration + override], and README documented with example.
Out of Scope Changes check	✅ Passed	All changes directly support issue #83 requirements: url-generation.ts exports and APIs, type re-exports in server.ts, documentation in README.md, tests in url-generation.test.ts, and CHANGELOG updates; no unrelated modifications detected.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ 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.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/server/url-generation.ts`:
- Around line 158-160: Validate inputs in registerUrlGenerator: ensure namespace
is a non-empty string and generator matches UrlGeneratorFn (a function). If
namespace is invalid or empty, throw a TypeError; if generator is not a
function, throw a TypeError describing the expected signature. Use these checks
before calling urlGenerators.set(namespace, generator) so
generateUrlForNamespace won't encounter invalid entries; reference the
registerUrlGenerator function, UrlGeneratorFn type, urlGenerators map, and
generateUrlForNamespace in your changes.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: cfbf28d6-5db7-4144-9151-889d08be076d

📥 Commits

Reviewing files that changed from the base of the PR and between 335bda1 and 998ce80.

📒 Files selected for processing (5)

• CHANGELOG.md
• README.md
• src/server.ts
• src/server/url-generation.test.ts
• src/server/url-generation.ts

[codecov]

Codecov Report

❌ Patch coverage is 85.71429% with 2 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@4b78587). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
src/server/url-generation.ts	85.71%	2 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #87   +/-   ##
=======================================
  Coverage        ?   75.40%           
=======================================
  Files           ?       33           
  Lines           ?     1175           
  Branches        ?      372           
=======================================
  Hits            ?      886           
  Misses          ?      289           
  Partials        ?        0           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

🧹 Nitpick comments (1)

src/server/url-generation.ts (1)

31-35: 💤 Low value

Consider simplifying the alias documentation.

The phrase "(issue / API naming: UrlGeneratorFn)" references the development process but will be unclear to future maintainers. Consider revising to focus on the purpose:

/**
 * Alias for {`@link` UrlGenerator}.
 * Exported as `UrlGeneratorFn` for consumers who prefer function-style naming.
 */
export type UrlGeneratorFn = UrlGenerator;

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/server/url-generation.ts` around lines 31 - 35, Update the doc comment
for the UrlGeneratorFn type to remove the internal "(issue / API naming:
`UrlGeneratorFn`)" note and instead describe purpose-only: state that
UrlGeneratorFn is an alias for UrlGenerator and is exported for consumers who
prefer function-style naming; update the comment immediately above the export
type UrlGeneratorFn = UrlGenerator; so it reads like the provided suggested
comment referencing UrlGenerator and UrlGeneratorFn.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/server/url-generation.ts`:
- Around line 31-35: Update the doc comment for the UrlGeneratorFn type to
remove the internal "(issue / API naming: `UrlGeneratorFn`)" note and instead
describe purpose-only: state that UrlGeneratorFn is an alias for UrlGenerator
and is exported for consumers who prefer function-style naming; update the
comment immediately above the export type UrlGeneratorFn = UrlGenerator; so it
reads like the provided suggested comment referencing UrlGenerator and
UrlGeneratorFn.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: bf1c8e96-e5d5-4096-9c6c-808666df9e24

📥 Commits

Reviewing files that changed from the base of the PR and between 998ce80 and e55e239.

📒 Files selected for processing (2)

• README.md
• src/server/url-generation.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• README.md