fix(repo): flatten Pick parameters in TypeDoc output by SarahSoutoul · Pull Request #9701 · clerk/javascript

SarahSoutoul · 2026-09-10T00:06:46Z

Description

OrganizationResource.createDomain() accepts the domain name as its first argument and only enrollmentMode in its optional params object:

createDomain(domainName: string, params?: Pick<CreateOrganizationDomainParams, 'enrollmentMode'>)

The TypeDoc parameter-table renderer understands inline objects, interfaces, and type aliases, but it did not resolve TypeScript's built-in Pick<T, K>. As a result, the generated table documented only the opaque params?: Pick<...> parameter and did not surface params?.enrollmentMode?, its allowed values, description, or default.

The current docs work around that limitation by embedding the complete CreateOrganizationDomainParams declaration below the method. That declaration contains both name and enrollmentMode, even though this method receives name separately as domainName. Once enrollmentMode is flattened into the method table, retaining the workaround would also document it twice.

This PR teaches the parameter-table renderer to resolve the built-in Pick<T, K> when K is composed of string literal keys. It filters the source declaration to exactly the selected properties and passes that shape through the existing nested-parameter renderer. The parent parameter remains in the table, followed by rows for the selected properties with their original types and JSDoc.

Because the selected shape is documented inline, the source type is rendered without a link to the full unpicked declaration. Unsupported or partially resolved Pick shapes retain the existing output rather than producing incomplete documentation.

Adds an end-to-end snapshot for organization.createDomain(), which now documents params?.enrollmentMode? without leaking the omitted name property.

Although the repository contains other source-level Pick usages, createDomain() is currently the only generated standalone parameter table that enters this code path. Tests, internal types, packages outside the TypeDoc entry points, property tables, and function-valued resource-summary properties use different paths and remain unchanged.

Required merge flow:

Merge this PR.
Create the generated TypeDoc sync PR in clerk/clerk.
Merge the companion cleanup in clerk/clerk#3341 into the generated TypeDoc PR.
Merge the generated TypeDoc PR.

The Clerk cleanup should not merge directly into main; combining it with the generated output prevents an intermediate state with missing or duplicated parameter documentation.

Resolves DOCS-11879.

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

vercel · 2026-09-10T00:06:52Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
clerk-js-sandbox	Ready	Preview	Sep 10, 2026 10:51pm UTC
swingset	Ready	Preview	Sep 10, 2026 10:51pm UTC

changeset-bot · 2026-09-10T00:06:53Z

🦋 Changeset detected

Latest commit: fe3a2f3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

coderabbitai · 2026-09-10T00:06:54Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Team

Run ID: b98a8cbf-cfcd-421d-9371-b880b003ea3c

📥 Commits

Reviewing files that changed from the base of the PR and between 1492197 and 5568fb7.

📒 Files selected for processing (1)

packages/localizations/src/he-IL.ts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

clerk/clerk_go (manual)
clerk/dashboard (manual)
clerk/accounts (manual)
clerk/backoffice (manual)
clerk/clerk (manual) → reviewed against open PR #3341 ss/DOCS-11879 instead of the default branch

Included review availability: 6 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 8 reviews per hour.

📝 Walkthrough

Walkthrough

The Typedoc custom theme now resolves Pick<T, K> parameters, selects the requested properties, and removes source-type links from flattened output. Tests and snapshots cover the createDomain() documentation. An empty Changesets metadata file and formatting-only Hebrew localization changes were added.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested reviewers: alexcarpenter

Merge Risk: ⚪ Minimal · up to 5568f

The reviewed localization changes are formatting-only and do not alter behavior.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description clearly explains the TypeDoc change, the Pick parameter handling, the generated documentation impact, testing, and required merge flow.
Title check	✅ Passed	The title is concise and accurately identifies the main change: flattening Pick parameters in TypeDoc output.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 4 files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Warning

Linked repositories: Your configuration references 7 linked repositories, but your current plan allows 5. Analyzed clerk/clerk_go, clerk/dashboard, clerk/accounts, clerk/backoffice, clerk/clerk, skipped clerk/clerk-docs, clerk/cloudflare-workers.

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

pkg-pr-new · 2026-09-10T00:09:07Z

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@9701

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@9701

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@9701

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@9701

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9701

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9701

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9701

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@9701

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@9701

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@9701

@clerk/express

npm i https://pkg.pr.new/@clerk/express@9701

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@9701

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@9701

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@9701

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@9701

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@9701

@clerk/react

npm i https://pkg.pr.new/@clerk/react@9701

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@9701

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@9701

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@9701

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@9701

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@9701

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@9701

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@9701

commit: fe3a2f3

Export getPickPropertyNames and extend custom-theme.test.mts with the multi-key case and the fail-closed branches (missing keys, non-literal keys, Omit) that the generated-output snapshot does not exercise. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

manovotny · 2026-09-10T20:41:05Z

Pushed some changes directly in c0af671.

Extended custom-theme.test.mts with the multi-key Pick case and the fail-closed branches (missing keys, non-literal keys, Omit), plus unit coverage for getPickPropertyNames
Exported getPickPropertyNames so it can be tested directly

Leaving a comment for one more thing.

github-actions · 2026-09-10T21:30:46Z

API Changes Report

Generated by Break Check on 2026-09-10T22:54:08.237Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	0
🔴 Breaking changes	0
🟡 Non-breaking changes	0
🟢 Additions	0

No API Changes Detected

All packages have stable APIs with no detected changes.

Report generated by Break Check

_{Last ran on fe3a2f3.}

SarahSoutoul · 2026-09-10T23:20:09Z

Pushed some changes directly in c0af671.

Extended custom-theme.test.mts with the multi-key Pick case and the fail-closed branches (missing keys, non-literal keys, Omit), plus unit coverage for getPickPropertyNames

Exported getPickPropertyNames so it can be tested directly

Leaving a comment for one more thing.

Thanks Michael! Not seeing the comment you're referring to? @manovotny

manovotny · 2026-09-10T20:41:13Z

+        return undefined;
+      }
+      const selected = new Set(propertyNames);
+      const children = sourceWithChildren.children.filter(child => selected.has(child.name));


For a generic source like Pick<Box<string>, 'value'>, this reuses Box<T>'s child reflections, so the flattened row documents the property's type as T rather than string — TypeDoc keeps the instantiation in the use-site typeArguments and doesn't rewrite the referenced declaration's children.

Nothing in the entry points hits this today (CreateOrganizationDomainParams isn't generic), and it's a pre-existing trait of the reference-flatten path, not something this PR introduces. The one wrinkle: this branch fails open (a wrong type) rather than closed.

Worth bailing to the opaque output when the source is a generic instantiation — returning undefined here when sourceType.typeArguments?.length — so it degrades instead of documenting T?

fix(repo): flatten Pick parameters in TypeDoc output

0887de9

SarahSoutoul self-assigned this Sep 10, 2026

fix(repo): unlink flattened Pick source types

ceb7a34

vercel Bot deployed to Preview – clerk-js-sandbox September 10, 2026 16:21 View deployment

vercel Bot deployed to Preview – swingset September 10, 2026 16:22 View deployment

SarahSoutoul requested review from manovotny and wobsoriano September 10, 2026 17:15

SarahSoutoul marked this pull request as ready for review September 10, 2026 17:17

Merge branch 'main' into ss/DOCS-11879

178f59c

vercel Bot deployed to Preview – clerk-js-sandbox September 10, 2026 17:18 View deployment

vercel Bot deployed to Preview – swingset September 10, 2026 17:20 View deployment

manovotny self-assigned this Sep 10, 2026

fix(repo): guard Pick source reflection kinds

0bbd87e

vercel Bot deployed to Preview – clerk-js-sandbox September 10, 2026 18:40 View deployment

vercel Bot deployed to Preview – swingset September 10, 2026 18:42 View deployment

vercel Bot deployed to Preview – clerk-js-sandbox September 10, 2026 20:40 View deployment

vercel Bot deployed to Preview – swingset September 10, 2026 20:42 View deployment

Merge remote-tracking branch 'origin/main' into ss/DOCS-11879

c6fd683

github-actions Bot added the localizations label Sep 10, 2026

vercel Bot deployed to Preview – clerk-js-sandbox September 10, 2026 21:27 View deployment

vercel Bot deployed to Preview – swingset September 10, 2026 21:29 View deployment

SarahSoutoul force-pushed the ss/DOCS-11879 branch from a077bef to c6fd683 Compare September 10, 2026 21:59

vercel Bot deployed to Preview – clerk-js-sandbox September 10, 2026 22:00 View deployment

Merge branch 'main' into ss/DOCS-11879

1492197

vercel Bot deployed to Preview – clerk-js-sandbox September 10, 2026 22:01 View deployment

vercel Bot deployed to Preview – swingset September 10, 2026 22:03 View deployment

fix(localizations): format Hebrew OAuth consent messages

5568fb7

vercel Bot deployed to Preview – clerk-js-sandbox September 10, 2026 22:45 View deployment

vercel Bot deployed to Preview – swingset September 10, 2026 22:47 View deployment

fix(localizations): regenerate Hebrew localization

fe3a2f3

vercel Bot deployed to Preview – clerk-js-sandbox September 10, 2026 22:49 View deployment

vercel Bot deployed to Preview – swingset September 10, 2026 22:51 View deployment

manovotny reviewed Sep 11, 2026

View reviewed changes

Navigation Menu

Uh oh!

fix(repo): flatten Pick parameters in TypeDoc output - #9701

fix(repo): flatten Pick parameters in TypeDoc output#9701
SarahSoutoul wants to merge 9 commits into
mainfrom
ss/DOCS-11879

SarahSoutoul commented Sep 10, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Sep 10, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Sep 10, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Sep 10, 2026 •

edited

Loading

Reviews paused

Walkthrough

Uh oh!

pkg-pr-new Bot commented Sep 10, 2026 •

edited

Loading

Uh oh!

manovotny commented Sep 10, 2026

Uh oh!

github-actions Bot commented Sep 10, 2026 •

edited

Loading

Uh oh!

SarahSoutoul commented Sep 10, 2026

Uh oh!

manovotny Sep 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

SarahSoutoul commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Uh oh!

vercel Bot commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

coderabbitai Bot commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Uh oh!

pkg-pr-new Bot commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

manovotny commented Sep 10, 2026

Uh oh!

github-actions Bot commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API Changes Report

Summary

No API Changes Detected

Uh oh!

SarahSoutoul commented Sep 10, 2026

Uh oh!

manovotny Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

SarahSoutoul commented Sep 10, 2026 •

edited

Loading

vercel Bot commented Sep 10, 2026 •

edited

Loading

changeset-bot Bot commented Sep 10, 2026 •

edited

Loading

coderabbitai Bot commented Sep 10, 2026 •

edited

Loading

pkg-pr-new Bot commented Sep 10, 2026 •

edited

Loading

github-actions Bot commented Sep 10, 2026 •

edited

Loading