Externalize tanstack-client `utils`

[genu]

This is a just a tracking issue for externalizing the utils that are currently present in the tanstack-query client into a separate package since those utilities are not tanstack specific.

Relevant discussion: https://discord.com/channels/1035538056146595961/1352359627525718056/1450162025211887738

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

zenstackhq/zenstack#1565 - fix(tanstack): incorrect vue-query options typing for vue-query v5 [merged]
#361 - chore(tanstack): add an extra export [merged]
#365 - feat(tanstack): migrate vue query [merged]

👤 Suggested Assignees

• ymc9

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[coderabbitai]

Coding Plan

Approach

Ticket Summary

Extract the framework-agnostic utilities from the tanstack-query client package into a separate reusable package, as these utilities (mutation application, query analysis, visitor patterns, serialization) are not specific to TanStack Query and could be used by other client implementations.

Observations

Codebase Summary

The ZenStack monorepo contains a packages/clients/tanstack-query implementation with framework-specific entry points (React, Vue, Svelte) that share common utilities located in src/utils/. The codebase follows patterns established by packages/common-helpers: modular file-per-function organization, central index exports, modern TypeScript tooling (tsup), and dual module support. The tanstack-query utils consist of mutation logic, query analysis, visitor patterns for traversing ORM operations, and serialization—all operating on generic data structures and ZenStack schemas without dependencies on TanStack Query runtime libraries.

Assumptions

Assumption 1: Scope of Generic vs Tanstack-Specific Utilities

Options Considered:

• Extract only the obviously framework-agnostic files (mutator, visitors, query-analysis, serialization) and leave all of common.ts in tanstack-query
• Extract both the framework-agnostic files AND the generic functions from common.ts (fetcher, marshal, unmarshal, makeUrl)

Chosen Option: Extract both the framework-agnostic files AND the generic functions from common.ts (fetcher, marshal, unmarshal, makeUrl)

Rationale: While these functions currently sit alongside tanstack-specific code, they perform generic operations (HTTP fetching, JSON serialization, URL construction) with no tanstack runtime dependencies, making them valuable for future client implementations. The tanstack-specific functions (getQueryKey, setupInvalidation, setupOptimisticUpdate) and related types will remain in the tanstack-query package where they belong.

Assumption 2: Package Naming Convention

Options Considered:

• @zenstackhq/orm-utils - emphasizes ORM operation handling
• @zenstackhq/client-utils - broader scope for any client implementation
• Extend existing @zenstackhq/common-helpers package

Chosen Option: @zenstackhq/client-utils

Rationale: It's more descriptive of the utilities' purpose (supporting client query/mutation operations) and leaves room for future client implementations beyond TanStack Query. Extending common-helpers is not ideal since that package has zero external dependencies while these utilities require superjson, decimal.js, buffer, and @zenstackhq/schema.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Create Client Utils Package Structure

Set up a new shared package following ZenStack monorepo patterns to house the externalized utilities.

Task 1: Initialize Package Directory and Configuration

Create the foundation for the new package with proper TypeScript and build tooling.

• Create packages/client-utils/ directory structure
• Create package.json following the pattern from common-helpers: set name to @zenstackhq/client-utils, configure dual module support (ESM/CommonJS) using modern exports field, add dependencies (superjson, decimal.js, buffer, @zenstackhq/schema, @zenstackhq/common-helpers)
• Create tsconfig.json extending the shared ZenStack TypeScript configuration
• Create tsup.config.ts for bundling configuration (similar to common-helpers)
• Create eslint.config.mjs for linting setup
• Add src/ directory for source files
• Add src/index.ts as central barrel export file

Task 2: Configure Build and Package Metadata

Set up the package for proper building and publishing within the monorepo.

• Configure tsup in tsup.config.ts to output ESM (.js/.d.ts) and CommonJS (.cjs/.d.cts) bundles
• Add build scripts to package.json ("build", "clean", "lint" following monorepo patterns)
• Ensure the package.json exports field properly maps to generated bundle outputs
• Add the new package to workspace configuration if needed

🤖 Prompt for AI agents

Initialize a new `@zenstackhq/client-utils` package following ZenStack monorepo
conventions.

Create package directory structure at `packages/client-utils/` with src/
subdirectory.

Create package.json with:
- Package name: @zenstackhq/client-utils
- Dual module support via exports field (ESM/CommonJS)
- Dependencies: superjson, decimal.js, buffer, @zenstackhq/schema,
@zenstackhq/common-helpers
- Build scripts: build, clean, lint
- Exports field mapping to bundle outputs

Create tsconfig.json extending shared ZenStack TypeScript configuration.

Create tsup.config.ts for bundling with ESM and CommonJS outputs (.js/.d.ts and
.cjs/.d.cts).

Create eslint.config.mjs for linting.

Create src/index.ts as central barrel export file.

Add package to workspace configuration if needed.

Phase 2: Extract and Migrate Generic Utilities

Move framework-agnostic utilities from tanstack-query to the new client-utils package.

Task 1: Migrate Complete Utility Files

Copy the utilities that are entirely framework-agnostic to the new package.

• Copy packages/clients/tanstack-query/src/utils/mutator.ts to packages/client-utils/src/mutator.ts
• Copy packages/clients/tanstack-query/src/utils/query-analysis.ts to packages/client-utils/src/query-analysis.ts
• Copy packages/clients/tanstack-query/src/utils/nested-read-visitor.ts to packages/client-utils/src/nested-read-visitor.ts
• Copy packages/clients/tanstack-query/src/utils/nested-write-visitor.ts to packages/client-utils/src/nested-write-visitor.ts
• Copy packages/clients/tanstack-query/src/utils/serialization.ts to packages/client-utils/src/serialization.ts
• Update internal import paths in copied files to reference new package structure (e.g., relative imports between utils should still work)

Task 2: Extract Generic Functions from common.ts

Separate the framework-agnostic functions from common.ts into dedicated utility files in the new package.

• Create packages/client-utils/src/fetcher.ts and extract the fetcher function and FetchFn type from tanstack-query's common.ts
• Create packages/client-utils/src/marshalling.ts and extract the marshal and unmarshal functions from common.ts
• Create packages/client-utils/src/url.ts and extract the makeUrl function from common.ts
• Create packages/client-utils/src/types.ts and extract generic type definitions from tanstack-query's types.ts (ORMWriteActionType enum, TrimDelegateModelOperations type, any other non-tanstack-specific types)
• Ensure extracted functions maintain their existing signatures and behavior

Task 3: Set Up Package Exports

Configure the central index file to expose all externalized utilities.

• In packages/client-utils/src/index.ts, add barrel exports for all migrated files using export * from './mutator', export * from './query-analysis', etc.
• Export individual utilities by name where appropriate for better tree-shaking
• Ensure type definitions are properly exported

🤖 Prompt for AI agents

Migrate framework-agnostic utilities from tanstack-query to client-utils
package.

Copy complete utility files from tanstack-query/src/utils/ to client-utils/src/:
- mutator.ts
- query-analysis.ts
- nested-read-visitor.ts
- nested-write-visitor.ts
- serialization.ts

Update internal import paths in copied files to work with new package structure.

Extract generic functions from tanstack-query common.ts and types.ts:
- Create fetcher.ts with fetcher function and FetchFn type
- Create marshalling.ts with marshal and unmarshal functions
- Create url.ts with makeUrl function
- Create types.ts with generic type definitions (ORMWriteActionType enum,
TrimDelegateModelOperations, other non-tanstack types)

Maintain existing signatures and behavior for all extracted functions.

Configure src/index.ts with barrel exports for all migrated files (export * from
'./mutator', etc.).

Export individual utilities by name for tree-shaking.

Ensure type definitions are properly exported.

Phase 3: Update Tanstack-Query Package

Refactor the tanstack-query package to consume utilities from the new shared package.

Task 1: Update Dependencies and Imports

Configure tanstack-query to use the new external package.

• Add @zenstackhq/client-utils as a dependency in packages/clients/tanstack-query/package.json
• Update imports in packages/clients/tanstack-query/src/react.ts, vue.ts, and svelte.ts to import from @zenstackhq/client-utils instead of local utils
• Update imports in the remaining files in packages/clients/tanstack-query/src/utils/common.ts to import shared utilities from @zenstackhq/client-utils

Task 2: Reorganize Remaining Tanstack-Specific Code

Clean up the tanstack-query utils directory to contain only framework-specific utilities.

• Remove the migrated files from packages/clients/tanstack-query/src/utils/ (mutator.ts, query-analysis.ts, visitors, serialization.ts)
• Keep common.ts but remove the externalized functions (fetcher, marshal, unmarshal, makeUrl), retaining only tanstack-specific functions (getQueryKey, setupInvalidation, setupOptimisticUpdate)
• Update common.ts to import externalized utilities from @zenstackhq/client-utils and re-export them if needed for backward compatibility
• Keep types.ts but remove externalized types, retaining only tanstack-specific types (OptimisticDataProvider, ExtraMutationOptions, etc.)
• Update any remaining internal imports within the utils directory

Task 3: Maintain Public API Compatibility

Ensure external consumers of tanstack-query aren't broken by the refactoring.

• Review public exports from react.ts, vue.ts, svelte.ts - currently only FetchFn is exported
• Update the export statement for FetchFn to reference @zenstackhq/client-utils instead of local utils
• Verify that no other utils were publicly exposed that now need re-exporting

🤖 Prompt for AI agents

Refactor tanstack-query package to consume utilities from client-utils.

Add @zenstackhq/client-utils as dependency in tanstack-query package.json.

Update imports in react.ts, vue.ts, and svelte.ts to import from
@zenstackhq/client-utils instead of local utils.

Update imports in utils/common.ts to import shared utilities from
@zenstackhq/client-utils.

Clean up tanstack-query utils directory:
- Remove migrated files (mutator.ts, query-analysis.ts, visitors,
serialization.ts)
- Keep common.ts but remove externalized functions (fetcher, marshal, unmarshal,
makeUrl)
- Retain tanstack-specific functions (getQueryKey, setupInvalidation,
setupOptimisticUpdate)
- Import externalized utilities from @zenstackhq/client-utils and re-export if
needed for backward compatibility
- Keep types.ts but remove externalized types
- Retain tanstack-specific types (OptimisticDataProvider, ExtraMutationOptions,
etc.)
- Update remaining internal imports

Maintain public API compatibility:
- Update FetchFn export in react.ts, vue.ts, svelte.ts to reference
@zenstackhq/client-utils
- Verify no other utils need re-exporting

Phase 4: Update Tests and Validation

Ensure the refactoring doesn't break existing functionality.

Task 1: Update Test Imports

Fix test files to import from the correct locations.

• Update packages/clients/tanstack-query/test/react-query.test.tsx to import getQueryKey from the updated location (still in tanstack-query utils/common.ts since it's tanstack-specific)
• If any tests imported utilities that moved to client-utils, update those imports to use @zenstackhq/client-utils
• Verify all imports resolve correctly

Task 2: Validate Build and Tests

Ensure the refactored code builds and tests pass.

• Build the client-utils package first to ensure it compiles correctly
• Build the tanstack-query package to ensure it consumes client-utils properly
• Run existing tanstack-query tests to verify functionality is preserved
• Verify that framework-specific implementations (React, Vue, Svelte) still work correctly

🤖 Prompt for AI agents

Update tests and validate refactored code.

Fix test imports:
- Update react-query.test.tsx to import getQueryKey from updated location
(tanstack-query utils/common.ts)
- Update any tests importing moved utilities to use @zenstackhq/client-utils
- Verify all imports resolve correctly

Validate builds and tests:
- Build client-utils package and verify compilation
- Build tanstack-query package and verify it consumes client-utils correctly
- Run existing tanstack-query tests to verify functionality is preserved
- Verify framework-specific implementations (React, Vue, Svelte) still work

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Initialize a new `@zenstackhq/client-utils` package following ZenStack monorepo
conventions.

Create package directory structure at `packages/client-utils/` with src/
subdirectory.

Create package.json with:
- Package name: @zenstackhq/client-utils
- Dual module support via exports field (ESM/CommonJS)
- Dependencies: superjson, decimal.js, buffer, @zenstackhq/schema,
@zenstackhq/common-helpers
- Build scripts: build, clean, lint
- Exports field mapping to bundle outputs

Create tsconfig.json extending shared ZenStack TypeScript configuration.

Create tsup.config.ts for bundling with ESM and CommonJS outputs (.js/.d.ts and
.cjs/.d.cts).

Create eslint.config.mjs for linting.

Create src/index.ts as central barrel export file.

Add package to workspace configuration if needed.
===============================================================================

Task: 2

Migrate framework-agnostic utilities from tanstack-query to client-utils
package.

Copy complete utility files from tanstack-query/src/utils/ to client-utils/src/:
- mutator.ts
- query-analysis.ts
- nested-read-visitor.ts
- nested-write-visitor.ts
- serialization.ts

Update internal import paths in copied files to work with new package structure.

Extract generic functions from tanstack-query common.ts and types.ts:
- Create fetcher.ts with fetcher function and FetchFn type
- Create marshalling.ts with marshal and unmarshal functions
- Create url.ts with makeUrl function
- Create types.ts with generic type definitions (ORMWriteActionType enum,
TrimDelegateModelOperations, other non-tanstack types)

Maintain existing signatures and behavior for all extracted functions.

Configure src/index.ts with barrel exports for all migrated files (export * from
'./mutator', etc.).

Export individual utilities by name for tree-shaking.

Ensure type definitions are properly exported.
===============================================================================

Task: 3

Refactor tanstack-query package to consume utilities from client-utils.

Add @zenstackhq/client-utils as dependency in tanstack-query package.json.

Update imports in react.ts, vue.ts, and svelte.ts to import from
@zenstackhq/client-utils instead of local utils.

Update imports in utils/common.ts to import shared utilities from
@zenstackhq/client-utils.

Clean up tanstack-query utils directory:
- Remove migrated files (mutator.ts, query-analysis.ts, visitors,
serialization.ts)
- Keep common.ts but remove externalized functions (fetcher, marshal, unmarshal,
makeUrl)
- Retain tanstack-specific functions (getQueryKey, setupInvalidation,
setupOptimisticUpdate)
- Import externalized utilities from @zenstackhq/client-utils and re-export if
needed for backward compatibility
- Keep types.ts but remove externalized types
- Retain tanstack-specific types (OptimisticDataProvider, ExtraMutationOptions,
etc.)
- Update remaining internal imports

Maintain public API compatibility:
- Update FetchFn export in react.ts, vue.ts, svelte.ts to reference
@zenstackhq/client-utils
- Verify no other utils need re-exporting
===============================================================================

Task: 4

Update tests and validate refactored code.

Fix test imports:
- Update react-query.test.tsx to import getQueryKey from updated location
(tanstack-query utils/common.ts)
- Update any tests importing moved utilities to use @zenstackhq/client-utils
- Verify all imports resolve correctly

Validate builds and tests:
- Build client-utils package and verify compilation
- Build tanstack-query package and verify it consumes client-utils correctly
- Run existing tanstack-query tests to verify functionality is preserved
- Verify framework-specific implementations (React, Vue, Svelte) still work

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[ymc9]

Fixed in 3.1.0