Make ctx.meta.loadSubsetOptions type safe #869
+252
−30
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Previously, the module augmentation for @tanstack/query-core that makes ctx.meta?.loadSubsetOptions type-safe was in query.ts. This meant it wasn't always processed by TypeScript unless something from that file was directly imported. This commit fixes the issue by: 1. Moving the module augmentation to a dedicated global.d.ts file 2. Adding a triple-slash reference in index.ts to ensure global.d.ts is always loaded when the package is imported 3. Removing the duplicate module augmentation from query.ts Now, ctx.meta?.loadSubsetOptions is automatically typed as LoadSubsetOptions without requiring users to explicitly import QueryCollectionMeta or add any manual type assertions. Fixes the issue where users needed to use @ts-ignore or manual type assertions to pass ctx.meta?.loadSubsetOptions to parseLoadSubsetOptions.
🦋 Changeset detectedLatest commit: 2066a4e The changes in this PR will be included in the next version bump. This PR includes changesets to release 2 packages
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 |
More templates
@tanstack/angular-db
@tanstack/db
@tanstack/db-ivm
@tanstack/electric-db-collection
@tanstack/offline-transactions
@tanstack/powersync-db-collection
@tanstack/query-db-collection
@tanstack/react-db
@tanstack/rxdb-db-collection
@tanstack/solid-db
@tanstack/svelte-db
@tanstack/trailbase-db-collection
@tanstack/vue-db
commit: |
Contributor
|
Size Change: 0 B Total Size: 86.3 kB ℹ️ View Unchanged
|
Contributor
|
Size Change: 0 B Total Size: 3.34 kB ℹ️ View Unchanged
|
This commit addresses two critical issues identified in code review:
1. **Fixed double export**: Removed duplicate QueryCollectionMeta export from
the query.ts line in index.ts. QueryCollectionMeta is now only exported
from global.d.ts, which is its canonical source.
2. **Changed from type alias to interface**: Converting QueryCollectionMeta
from a type alias to an interface enables proper TypeScript declaration
merging. This allows users to extend meta with custom properties without
encountering "Subsequent property declarations must have the same type"
errors.
The updated documentation now shows the correct pattern for users to extend
meta:
```typescript
declare module "@tanstack/query-db-collection" {
interface QueryCollectionMeta {
myCustomProperty: string
}
}
```
This is safer than the previous pattern which would have caused users to
collide with the library's own Register.queryMeta augmentation.
Added a type test documenting the extension pattern for future reference.
- Replace triple-slash reference with import type {} from './global'
- Remove unused ExtendedMeta interface from test
All errors are now resolved, only pre-existing warnings remain.
Added comprehensive documentation explaining: - Automatic type-safety for ctx.meta.loadSubsetOptions - How to extend QueryCollectionMeta with custom properties via module augmentation - Real-world examples including API request context - Important notes about TypeScript declaration merging This aligns with TanStack Query's official approach to typing meta using the Register interface.
Changed global.d.ts to global.ts so TypeScript properly emits it as global.d.ts
in the dist folder. TypeScript's declaration emit only generates .d.ts files from
.ts source files - it does not copy handwritten .d.ts files to the output.
The module augmentation for @tanstack/query-core is now guaranteed to load because:
1. global.ts exports QueryCollectionMeta interface
2. index.ts re-exports it: export type { QueryCollectionMeta } from "./global"
3. When TypeScript processes the built index.d.ts, it must load global.d.ts to
resolve the export, which triggers processing of the module augmentation
This follows TypeScript best practices:
- Renamed .d.ts → .ts for proper build emission
- Re-export forces TypeScript to process the augmentation file
- No reliance on triple-slash references or side-effect imports
Updated comments to accurately reflect the mechanism.
Contributor
|
nice, it fixed the issue on my end! Thank you :) |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Reported here: https://discord.com/channels/719702312431386674/1441107002779631737/1441107002779631737
Previously, the module augmentation for @tanstack/query-core that makes ctx.meta?.loadSubsetOptions type-safe was in query.ts. This meant it wasn't always processed by TypeScript unless something from that file was directly imported.
This commit fixes the issue by:
Now, ctx.meta?.loadSubsetOptions is automatically typed as LoadSubsetOptions without requiring users to explicitly import QueryCollectionMeta or add any manual type assertions.
Fixes the issue where users needed to use @ts-ignore or manual type assertions to pass ctx.meta?.loadSubsetOptions to parseLoadSubsetOptions.
🎯 Changes
✅ Checklist
pnpm test:pr.🚀 Release Impact