feat(shared): add internal directory sync react-query hooks by kalafut · Pull Request #9591 · clerk/javascript

kalafut · 2026-08-27T16:55:20Z

Description

Part 2 of 4 of the self-serve Directory Sync stack. Stacked on jim/dir-sync-1-resource. This change depends on the first PR and the stack will be squashed on merge.

Adds the internal react-query hooks __internal_useOrganizationDirectorySync and __internal_useOrganizationDirectorySyncUsers. Mutations go through the loaded DirectorySync resource, so they resolve undefined until the directory has loaded. The users hook takes the directory resource itself and stays dormant while it is nullish; it polls while armed via startPolling, so the wizard's test step doubles as a recent-activity feed.

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

✎

changeset-bot · 2026-08-27T16:55:27Z

⚠️ No Changeset found

Latest commit: c40e012

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

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

Click here to learn what changesets are, and how to add one.

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

vercel · 2026-08-27T16:55:28Z

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

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

pkg-pr-new · 2026-08-28T22:47:43Z

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-google-signin

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: c40e012

github-actions · 2026-08-28T22:50:43Z

API Changes Report

Generated by Break Check on 2026-09-03T15:41:51.855Z

Summary

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

@clerk/shared

Current version: 4.31.0
Recommended bump: MINOR → 4.32.0

Subpath `./react`

🟢 Additions (4)

Added: `UseOrganizationDirectorySyncParams`

+ type UseOrganizationDirectorySyncParams = {
+   enterpriseConnectionId: string | null;
+   enabled?: boolean;
+ };

Added type alias UseOrganizationDirectorySyncParams

Added: `UseOrganizationDirectorySyncReturn`

+ type UseOrganizationDirectorySyncReturn = {
+   data: DirectorySyncResource | null | undefined;
+   error: Error | null;
+   isLoading: boolean;
+   isFetching: boolean;
+   createDirectorySync: (params?: CreateDirectorySyncParams) => Promise<DirectorySyncResource | undefined>; /** Resolves `undefined` until `data` has loaded, since the mutations act on the loaded directory. */
+   updateDirectorySync: (params: UpdateDirectorySyncParams) => Promise<DirectorySyncResource | undefined>;
+   rotateDirectorySyncToken: () => Promise<DirectorySyncResource | undefined>;
+   deleteDirectorySync: () => Promise<DeletedObjectResource | undefined>;
+   revalidate: () => Promise<void>;
+ };

Added type alias UseOrganizationDirectorySyncReturn

Added: `UseOrganizationDirectorySyncUsersParams`

+ type UseOrganizationDirectorySyncUsersParams = {
+   directory: DirectorySyncResource | null | undefined;
+   params?: GetDirectorySyncUsersParams;
+   pollIntervalMs?: number;
+   enabled?: boolean;
+   keepPreviousData?: boolean;
+ };

Added type alias UseOrganizationDirectorySyncUsersParams

Added: `UseOrganizationDirectorySyncUsersReturn`

+ type UseOrganizationDirectorySyncUsersReturn = {
+   data: DirectorySyncUserResource[] | undefined;
+   totalCount: number | undefined;
+   error: Error | null;
+   isLoading: boolean;
+   isFetching: boolean;
+   isPolling: boolean;
+   startPolling: () => void;
+   stopPolling: () => void;
+   revalidate: () => Promise<void>;
+ };

Added type alias UseOrganizationDirectorySyncUsersReturn

Report generated by Break Check

_{Last ran on c40e012.}

coderabbitai · 2026-09-01T20:23:28Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

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

Review profile: ASSERTIVE

Plan: Team

Run ID: 4cb27338-597a-408e-9547-09640040d86a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

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

NicolasLopes7

Got fable looking/running this and had a couple of inline-comments. Other than that I'd suggest tests for the hooks to cover the regressions, otherwise LGTM

__internal_useOrganizationDirectorySync and __internal_useOrganizationDirectorySyncUsers; the users hook polls continuously while enabled so the test step can double as a recent-activity feed.

…Sync resource Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U54pszNFtqsBNpQhXaGvaa

Also add tests

dstaley · 2026-09-04T16:18:41Z

+   * Never carries the bearer token — that only exists on the resources resolved by
+   * `createDirectorySync` and `rotateDirectorySyncToken`.


don't think we need this

dstaley · 2026-09-04T16:20:23Z

+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+
+export type UseOrganizationDirectorySyncUsersParams = {
+  /** The directory to list users for, e.g. `data` from `useOrganizationDirectorySync`. Dormant while nullish. */


What does "Dormant while nullish." mean?

dstaley · 2026-09-04T16:21:39Z

+   * deprovisions keep appearing) until `stopPolling` is called — callers
+   * should stop on unmount of the view that armed it.


this sounds like we should encapsulate the start and stop polling into an effect that returns a cleanup callback function.

dstaley · 2026-09-04T16:22:38Z

+
+/**
+ * The users provisioned into an enterprise connection's Directory Sync
+ * directory, most recently touched first. Polls continuously while armed via


what does "armed" mean?

dstaley · 2026-09-04T16:23:43Z

+  const isPolling = queryEnabled && shouldPoll;
+
+  return {
+    // Dormant means dormant: never surface cached rows while the query cannot run.


dstaley · 2026-09-04T16:24:50Z

+ *
+ * @internal
+ */
+function useOrganizationDirectorySyncUsers(


will this internal hook always be used with polling?

dstaley · 2026-09-04T16:25:35Z

+  // Polling is armed for a specific connection and derived, not reset in an effect: a child
+  // effect arming it in the same commit the connection arrives would otherwise be cancelled.


I do not know what this means

vercel Bot deployed to Preview – clerk-js-sandbox August 27, 2026 16:56 View deployment

vercel Bot deployed to Preview – swingset August 27, 2026 16:58 View deployment

kalafut changed the title ~~feat(self-serve-ds): add internal Directory Sync react-query hooks~~ feat(shared): add internal directory sync react-query hooks Aug 27, 2026

kalafut force-pushed the jim/dir-sync-2-hooks branch from 9525da1 to 2291ba0 Compare August 28, 2026 22:44

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

vercel Bot deployed to Preview – swingset August 28, 2026 22:47 View deployment

kalafut force-pushed the jim/dir-sync-2-hooks branch from 2291ba0 to 8db31e5 Compare August 31, 2026 16:36

vercel Bot deployed to Preview – clerk-js-sandbox August 31, 2026 16:37 View deployment

vercel Bot deployed to Preview – swingset August 31, 2026 16:38 View deployment

kalafut force-pushed the jim/dir-sync-2-hooks branch from 8db31e5 to 875352a Compare August 31, 2026 16:48

vercel Bot deployed to Preview – clerk-js-sandbox August 31, 2026 16:48 View deployment

vercel Bot deployed to Preview – swingset August 31, 2026 16:50 View deployment

kalafut force-pushed the jim/dir-sync-2-hooks branch from 875352a to f801038 Compare August 31, 2026 22:40

vercel Bot deployed to Preview – clerk-js-sandbox August 31, 2026 22:41 View deployment

vercel Bot deployed to Preview – swingset August 31, 2026 22:43 View deployment

kalafut force-pushed the jim/dir-sync-2-hooks branch from f801038 to 3d18031 Compare September 1, 2026 20:23

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

vercel Bot deployed to Preview – swingset September 1, 2026 20:26 View deployment

kalafut force-pushed the jim/dir-sync-2-hooks branch from 3d18031 to 4adb710 Compare September 1, 2026 23:32

vercel Bot deployed to Preview – clerk-js-sandbox September 1, 2026 23:33 View deployment

vercel Bot deployed to Preview – swingset September 1, 2026 23:35 View deployment

kalafut requested a review from dstaley September 2, 2026 19:21

NicolasLopes7 reviewed Sep 2, 2026

View reviewed changes

Comment thread packages/shared/src/react/hooks/useOrganizationDirectorySyncUsers.tsx Outdated

NicolasLopes7 reviewed Sep 2, 2026

View reviewed changes

Comment thread packages/shared/src/react/hooks/useOrganizationDirectorySync.tsx Outdated

NicolasLopes7 approved these changes Sep 2, 2026

View reviewed changes

kalafut force-pushed the jim/dir-sync-2-hooks branch from 4adb710 to 247b096 Compare September 2, 2026 20:49

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

vercel Bot deployed to Preview – swingset September 2, 2026 20:51 View deployment

kalafut force-pushed the jim/dir-sync-2-hooks branch from 247b096 to 3342ab9 Compare September 2, 2026 21:24

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

vercel Bot deployed to Preview – swingset September 2, 2026 21:27 View deployment

kalafut force-pushed the jim/dir-sync-2-hooks branch from 3342ab9 to 6b53c5d Compare September 2, 2026 22:44

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

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

kalafut and others added 4 commits September 3, 2026 08:34

feat(self-serve-ds): add internal Directory Sync react-query hooks

b30901c

__internal_useOrganizationDirectorySync and __internal_useOrganizationDirectorySyncUsers; the users hook polls continuously while enabled so the test step can double as a recent-activity feed.

feat(self-serve-ds): route Directory Sync hooks through the Directory…

cfe3eff

…Sync resource Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U54pszNFtqsBNpQhXaGvaa

Remove placeholder reuse

1a86a5a

Fix test result polling, and invalidation

c40e012

Also add tests

kalafut force-pushed the jim/dir-sync-2-hooks branch from 6b53c5d to c40e012 Compare September 3, 2026 15:35

vercel Bot deployed to Preview – clerk-js-sandbox September 3, 2026 15:36 View deployment

vercel Bot deployed to Preview – swingset September 3, 2026 15:38 View deployment

dstaley requested changes Sep 4, 2026

View reviewed changes

		* Never carries the bearer token — that only exists on the resources resolved by
		* `createDirectorySync` and `rotateDirectorySyncToken`.

		* deprovisions keep appearing) until `stopPolling` is called — callers
		* should stop on unmount of the view that armed it.

		// Polling is armed for a specific connection and derived, not reset in an effect: a child
		// effect arming it in the same commit the connection arrives would otherwise be cancelled.

Uh oh!

Conversation

kalafut commented Aug 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Uh oh!

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

Uh oh!

⚠️ No Changeset found

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

API Changes Report

Summary

@clerk/shared

Subpath ./react

🟢 Additions (4)

Added: UseOrganizationDirectorySyncParams

Added: UseOrganizationDirectorySyncReturn

Added: UseOrganizationDirectorySyncUsersParams

Added: UseOrganizationDirectorySyncUsersReturn

Uh oh!

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

Uh oh!

Review skipped

Uh oh!

Uh oh!

Uh oh!

NicolasLopes7 left a comment

Choose a reason for hiding this comment

Uh oh!

dstaley Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

dstaley Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

dstaley Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

dstaley Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

dstaley Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

dstaley Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

dstaley Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kalafut commented Aug 27, 2026 •

edited

Loading

changeset-bot Bot commented Aug 27, 2026 •

edited

Loading

vercel Bot commented Aug 27, 2026 •

edited

Loading

pkg-pr-new Bot commented Aug 28, 2026 •

edited

Loading

github-actions Bot commented Aug 28, 2026 •

edited

Loading

Subpath `./react`

Added: `UseOrganizationDirectorySyncParams`

Added: `UseOrganizationDirectorySyncReturn`

Added: `UseOrganizationDirectorySyncUsersParams`

Added: `UseOrganizationDirectorySyncUsersReturn`

coderabbitai Bot commented Sep 1, 2026 •

edited

Loading