Modify type of query function's meta property to be more precise

[kevin-dp]

Fixes #802

By default a Tanstack Query function's meta property is typed as Record<string, unknown> | undefined. However, the Query Collection actually extends the meta property with a loadSubsetOptions property but this is not reflected in the type of meta.

This PR augments the @tanstack/query-core module such that the meta property is typed as Record<string, unknown> & { loadSubsetOptions: LoadSubsetOptions }. I find it a bit odd that we have to resort to module augmentation but this seems to be the recommended approach.

I added a type test that reproduces the problem.

Note: the type of the meta property still allows it to be undefined even though we know that won't be the case. I didn't find an elegant way to solve this.

[changeset-bot]

🦋 Changeset detected

Latest commit: af196fa

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

This PR includes changesets to release 2 packages

Name	Type
@tanstack/query-db-collection	Patch
@tanstack/db-collection-e2e	Patch

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

[pkg-pr-new]

More templates

• todos
• tanstack-start-example-basic
• @tanstack/db-example-paced-mutations-demo
• tanstack-start-db-projects-example
• @tanstack/db-example-react-todo
• @tanstack/db-example-solid-todo

@tanstack/angular-db

npm i https://pkg.pr.new/@tanstack/angular-db@857

@tanstack/db

npm i https://pkg.pr.new/@tanstack/db@857

@tanstack/db-ivm

npm i https://pkg.pr.new/@tanstack/db-ivm@857

@tanstack/electric-db-collection

npm i https://pkg.pr.new/@tanstack/electric-db-collection@857

@tanstack/offline-transactions

npm i https://pkg.pr.new/@tanstack/offline-transactions@857

@tanstack/powersync-db-collection

npm i https://pkg.pr.new/@tanstack/powersync-db-collection@857

@tanstack/query-db-collection

npm i https://pkg.pr.new/@tanstack/query-db-collection@857

@tanstack/react-db

npm i https://pkg.pr.new/@tanstack/react-db@857

@tanstack/rxdb-db-collection

npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@857

@tanstack/solid-db

npm i https://pkg.pr.new/@tanstack/solid-db@857

@tanstack/svelte-db

npm i https://pkg.pr.new/@tanstack/svelte-db@857

@tanstack/trailbase-db-collection

npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@857

@tanstack/vue-db

npm i https://pkg.pr.new/@tanstack/vue-db@857

commit: af196fa

[github-actions]

Size Change: 0 B

Total Size: 85.8 kB

ℹ️ View Unchanged

Filename	Size
./packages/db/dist/esm/collection/change-events.js	1.38 kB
./packages/db/dist/esm/collection/changes.js	977 B
./packages/db/dist/esm/collection/events.js	388 B
./packages/db/dist/esm/collection/index.js	3.24 kB
./packages/db/dist/esm/collection/indexes.js	1.1 kB
./packages/db/dist/esm/collection/lifecycle.js	1.67 kB
./packages/db/dist/esm/collection/mutations.js	2.26 kB
./packages/db/dist/esm/collection/state.js	3.43 kB
./packages/db/dist/esm/collection/subscription.js	2.42 kB
./packages/db/dist/esm/collection/sync.js	2.12 kB
./packages/db/dist/esm/deferred.js	207 B
./packages/db/dist/esm/errors.js	4.11 kB
./packages/db/dist/esm/event-emitter.js	748 B
./packages/db/dist/esm/index.js	2.63 kB
./packages/db/dist/esm/indexes/auto-index.js	742 B
./packages/db/dist/esm/indexes/base-index.js	766 B
./packages/db/dist/esm/indexes/btree-index.js	1.87 kB
./packages/db/dist/esm/indexes/lazy-index.js	1.1 kB
./packages/db/dist/esm/indexes/reverse-index.js	513 B
./packages/db/dist/esm/local-only.js	837 B
./packages/db/dist/esm/local-storage.js	2.1 kB
./packages/db/dist/esm/optimistic-action.js	359 B
./packages/db/dist/esm/paced-mutations.js	496 B
./packages/db/dist/esm/proxy.js	3.22 kB
./packages/db/dist/esm/query/builder/functions.js	733 B
./packages/db/dist/esm/query/builder/index.js	3.84 kB
./packages/db/dist/esm/query/builder/ref-proxy.js	917 B
./packages/db/dist/esm/query/compiler/evaluators.js	1.35 kB
./packages/db/dist/esm/query/compiler/expressions.js	430 B
./packages/db/dist/esm/query/compiler/group-by.js	1.8 kB
./packages/db/dist/esm/query/compiler/index.js	1.96 kB
./packages/db/dist/esm/query/compiler/joins.js	2 kB
./packages/db/dist/esm/query/compiler/order-by.js	1.25 kB
./packages/db/dist/esm/query/compiler/select.js	1.07 kB
./packages/db/dist/esm/query/expression-helpers.js	1.43 kB
./packages/db/dist/esm/query/ir.js	673 B
./packages/db/dist/esm/query/live-query-collection.js	360 B
./packages/db/dist/esm/query/live/collection-config-builder.js	5.26 kB
./packages/db/dist/esm/query/live/collection-registry.js	264 B
./packages/db/dist/esm/query/live/collection-subscriber.js	1.74 kB
./packages/db/dist/esm/query/live/internal.js	130 B
./packages/db/dist/esm/query/optimizer.js	2.56 kB
./packages/db/dist/esm/query/predicate-utils.js	2.88 kB
./packages/db/dist/esm/query/subset-dedupe.js	921 B
./packages/db/dist/esm/scheduler.js	1.21 kB
./packages/db/dist/esm/SortedMap.js	1.18 kB
./packages/db/dist/esm/strategies/debounceStrategy.js	237 B
./packages/db/dist/esm/strategies/queueStrategy.js	422 B
./packages/db/dist/esm/strategies/throttleStrategy.js	236 B
./packages/db/dist/esm/transactions.js	2.9 kB
./packages/db/dist/esm/utils.js	881 B
./packages/db/dist/esm/utils/browser-polyfills.js	304 B
./packages/db/dist/esm/utils/btree.js	5.61 kB
./packages/db/dist/esm/utils/comparison.js	852 B
./packages/db/dist/esm/utils/index-optimization.js	1.51 kB
./packages/db/dist/esm/utils/type-guards.js	157 B

_{compressed-size-action::db-package-size}

[github-actions]

Size Change: 0 B

Total Size: 3.34 kB

ℹ️ View Unchanged

Filename	Size
./packages/react-db/dist/esm/index.js	225 B
./packages/react-db/dist/esm/useLiveInfiniteQuery.js	1.17 kB
./packages/react-db/dist/esm/useLiveQuery.js	1.11 kB
./packages/react-db/dist/esm/useLiveSuspenseQuery.js	431 B
./packages/react-db/dist/esm/usePacedMutations.js	401 B

_{compressed-size-action::react-db-package-size}

[samwillis]

@kevin-dp this may be the recommended approach, but like you I don't really like it.

Could we just modify the type here:

db/packages/query-db-collection/src/query.ts

Lines 72 to 76 in 1527028

	queryFn: TQueryFn extends (
	context: QueryFunctionContext<TQueryKey>
	) => Promise<Array<any>>
	? (context: QueryFunctionContext<TQueryKey>) => Promise<Array<T>>
	: TQueryFn

such that it includes our metadata?

[kevin-dp]

@kevin-dp this may be the recommended approach, but like you I don't really like it.

Could we just modify the type here:

db/packages/query-db-collection/src/query.ts

Lines 72 to 76 in 1527028

	queryFn: TQueryFn extends (
	context: QueryFunctionContext<TQueryKey>
	) => Promise<Array<any>>
	? (context: QueryFunctionContext<TQueryKey>) => Promise<Array<T>>
	: TQueryFn

such that it includes our metadata?

@samwillis i had given this a try before but i abandoned it early, so i tried again now with a bit more perseverance. I got close but i don't think this is the right approach: d895a98

Essentially, it works on our side but it breaks types when interacting with Tanstack Query features. For example:

const queryFn = (
  context: QueryCollectionFunctionContext // <-- this is our new context type
) => {
  // ...
}
await queryClient.prefetchQuery({ queryKey, queryFn }) // expects queryFn to take a QueryFunctionContext

The call to prefetchQuery yields a type error because it expects the queryFn to have this type: (context: QueryFunctionContext) => Promise<TData>. However, with our approach of typing our query function differently, our function is typed as (context: QueryCollectionFunctionContext<TQueryKey>) => Promise<...>. This is incompatible with Tanstack's expected type because tanstack expect the function to be able to handle any QueryFunctionContext (i.e. any Record<string, unknown> | undefined value) but our function can only handle Record<string, unknown> & { loadSubsetOptions: LoadSubsetOptions } values. So our function is too narrow and the type checker complains.

If what i'm saying is not completely clear you can checkout the commit i linked and run the tests in the query package. You will see the error i'm describing above.

[samwillis]

Great work, and thanks for digging into this issue. Let's go for this module interface.

Just needs a changeset.