Make ctx.meta.loadSubsetOptions type safe (#869)

* fix: ensure module augmentation for ctx.meta is automatically loaded

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.

* fix: change QueryCollectionMeta to interface for proper extensibility

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.

* chore: run prettier on query.test-d.ts

* fix: resolve eslint errors in query-db-collection

- 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.

* chore: add changeset for automatic meta type-safety

* docs: add section on extending meta with custom properties

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.

* fix: ensure global.ts is emitted in build output

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.

---------

Co-authored-by: Claude <[email protected]>

Author: KyleAMathews

.changeset/automatic-meta-type-safety.md

@@ -0,0 +1,17 @@
+---
+"@tanstack/query-db-collection": patch
+---
+
+fix: ensure ctx.meta.loadSubsetOptions type-safety works automatically
+
+The module augmentation for ctx.meta.loadSubsetOptions is now guaranteed to load automatically when importing from @tanstack/query-db-collection. Previously, users needed to explicitly import QueryCollectionMeta or use @ts-ignore to pass ctx.meta?.loadSubsetOptions to parseLoadSubsetOptions.
+
+Additionally, QueryCollectionMeta is now an interface (instead of a type alias), enabling users to safely extend meta with custom properties via declaration merging:
+
+```typescript
+declare module "@tanstack/query-db-collection" {
+  interface QueryCollectionMeta {
+    myCustomProperty: string
+  }
+}
+```

docs/collections/query-collection.md

@@ -77,6 +77,126 @@ The `queryCollectionOptions` function accepts the following options:
 - `onUpdate`: Handler called before update operations
 - `onDelete`: Handler called before delete operations
 
+## Extending Meta with Custom Properties
+
+The `meta` option allows you to pass additional metadata to your query function. By default, Query Collections automatically include `loadSubsetOptions` in the meta object, which contains filtering, sorting, and pagination options for on-demand queries.
+
+### Type-Safe Meta Access
+
+The `ctx.meta.loadSubsetOptions` property is automatically typed as `LoadSubsetOptions` without requiring any additional imports or type assertions:
+
+```typescript
+import { parseLoadSubsetOptions } from "@tanstack/query-db-collection"
+
+const collection = createCollection(
+  queryCollectionOptions({
+    queryKey: ["products"],
+    syncMode: "on-demand",
+    queryFn: async (ctx) => {
+      // ✅ Type-safe access - no @ts-ignore needed!
+      const options = parseLoadSubsetOptions(ctx.meta?.loadSubsetOptions)
+
+      // Use the parsed options to fetch only what you need
+      return api.getProducts(options)
+    },
+    queryClient,
+    getKey: (item) => item.id,
+  })
+)
+```
+
+### Adding Custom Meta Properties
+
+You can extend the meta type to include your own custom properties using TypeScript's module augmentation:
+
+```typescript
+// In a global type definition file (e.g., types.d.ts or global.d.ts)
+declare module "@tanstack/query-db-collection" {
+  interface QueryCollectionMeta {
+    // Add your custom properties here
+    userId?: string
+    includeDeleted?: boolean
+    cacheTTL?: number
+  }
+}
+```
+
+Once you've extended the interface, your custom properties are fully typed throughout your application:
+
+```typescript
+const collection = createCollection(
+  queryCollectionOptions({
+    queryKey: ["todos"],
+    queryFn: async (ctx) => {
+      // ✅ Both loadSubsetOptions and custom properties are typed
+      const { loadSubsetOptions, userId, includeDeleted } = ctx.meta
+
+      return api.getTodos({
+        ...parseLoadSubsetOptions(loadSubsetOptions),
+        userId,
+        includeDeleted,
+      })
+    },
+    queryClient,
+    getKey: (item) => item.id,
+    // Pass custom meta alongside Query Collection defaults
+    meta: {
+      userId: "user-123",
+      includeDeleted: false,
+    },
+  })
+)
+```
+
+### Important Notes
+
+- The module augmentation pattern follows TanStack Query's official approach for typing meta
+- `QueryCollectionMeta` is an interface (not a type alias), enabling proper TypeScript declaration merging
+- Your custom properties are merged with the base `loadSubsetOptions` property
+- All meta properties must be compatible with `Record<string, unknown>`
+- The augmentation should be done in a file that's included in your TypeScript compilation
+
+### Example: API Request Context
+
+A common use case is passing request context to your query function:
+
+```typescript
+// types.d.ts
+declare module "@tanstack/query-db-collection" {
+  interface QueryCollectionMeta {
+    authToken?: string
+    locale?: string
+    version?: string
+  }
+}
+
+// collections.ts
+const productsCollection = createCollection(
+  queryCollectionOptions({
+    queryKey: ["products"],
+    queryFn: async (ctx) => {
+      const { loadSubsetOptions, authToken, locale, version } = ctx.meta
+
+      return api.getProducts({
+        ...parseLoadSubsetOptions(loadSubsetOptions),
+        headers: {
+          Authorization: `Bearer ${authToken}`,
+          "Accept-Language": locale,
+          "API-Version": version,
+        },
+      })
+    },
+    queryClient,
+    getKey: (item) => item.id,
+    meta: {
+      authToken: session.token,
+      locale: "en-US",
+      version: "v1",
+    },
+  })
+)
+```
+
 ## Persistence Handlers
 
 You can define handlers that are called when mutations occur. These handlers can persist changes to your backend and control whether the query should refetch after the operation:

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

@@ -0,0 +1,40 @@
+/**
+ * Global type augmentation for @tanstack/query-core
+ *
+ * This file ensures the module augmentation is always loaded when the package is imported.
+ * The index.ts file re-exports QueryCollectionMeta from this file, which guarantees
+ * TypeScript processes this file (and its module augmentation) whenever anyone imports
+ * from @tanstack/query-db-collection.
+ *
+ * This makes ctx.meta?.loadSubsetOptions automatically type-safe without requiring
+ * users to manually import QueryCollectionMeta.
+ */
+
+import type { LoadSubsetOptions } from "@tanstack/db"
+
+/**
+ * Base interface for Query Collection meta properties.
+ * Users can extend this interface to add their own custom properties while
+ * preserving loadSubsetOptions.
+ *
+ * @example
+ * ```typescript
+ * declare module "@tanstack/query-db-collection" {
+ *   interface QueryCollectionMeta {
+ *     myCustomProperty: string
+ *     userId?: number
+ *   }
+ * }
+ * ```
+ */
+export interface QueryCollectionMeta extends Record<string, unknown> {
+  loadSubsetOptions: LoadSubsetOptions
+}
+
+// Module augmentation to extend TanStack Query's Register interface
+// This ensures that ctx.meta always includes loadSubsetOptions
+declare module "@tanstack/query-core" {
+  interface Register {
+    queryMeta: QueryCollectionMeta
+  }
+}

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

@@ -1,7 +1,10 @@
+// Export QueryCollectionMeta from global.ts
+// This ensures the module augmentation in global.ts is processed by TypeScript
+export type { QueryCollectionMeta } from "./global"
+
 export {
   queryCollectionOptions,
   type QueryCollectionConfig,
-  type QueryCollectionMeta,
   type QueryCollectionUtils,
   type SyncOperation,
 } from "./query"

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

@@ -31,35 +31,6 @@ import type { StandardSchemaV1 } from "@standard-schema/spec"
 // Re-export for external use
 export type { SyncOperation } from "./manual-sync"
 
-/**
- * Base type for Query Collection meta properties.
- * Users can extend this type when augmenting the @tanstack/query-core module
- * to add their own custom properties while preserving loadSubsetOptions.
- *
- * @example
- * ```typescript
- * declare module "@tanstack/query-core" {
- *   interface Register {
- *     queryMeta: QueryCollectionMeta & {
- *       myCustomProperty: string
- *     }
- *   }
- * }
- * ```
- */
-export type QueryCollectionMeta = Record<string, unknown> & {
-  loadSubsetOptions: LoadSubsetOptions
-}
-
-// Module augmentation to extend TanStack Query's Register interface
-// This ensures that ctx.meta always includes loadSubsetOptions
-// We extend Record<string, unknown> to preserve the ability to add other meta properties
-declare module "@tanstack/query-core" {
-  interface Register {
-    queryMeta: QueryCollectionMeta
-  }
-}
-
 // Schema output type inference helper (matches electric.ts pattern)
 type InferSchemaOutput<T> = T extends StandardSchemaV1
   ? StandardSchemaV1.InferOutput<T> extends object

packages/query-db-collection/tests/query.test-d.ts

@@ -488,5 +488,76 @@ describe(`Query collection type resolution tests`, () => {
       const options = queryCollectionOptions(config)
       createCollection(options)
     })
+
+    it(`should have loadSubsetOptions typed automatically without explicit QueryCollectionMeta import`, () => {
+      // This test validates that the module augmentation works automatically
+      // Note: We are NOT importing QueryCollectionMeta, yet ctx.meta.loadSubsetOptions
+      // should still be properly typed as LoadSubsetOptions
+      const config: QueryCollectionConfig<TestItem> = {
+        id: `autoTypeTest`,
+        queryClient,
+        queryKey: [`autoTypeTest`],
+        queryFn: (ctx) => {
+          // This should compile without errors because the module augmentation
+          // in global.d.ts is automatically loaded via the triple-slash reference
+          // in index.ts
+          const options = ctx.meta?.loadSubsetOptions
+
+          // Verify the type is correct
+          expectTypeOf(options).toMatchTypeOf<LoadSubsetOptions | undefined>()
+
+          // Verify it can be passed to parseLoadSubsetOptions without type errors
+          const parsed = parseLoadSubsetOptions(options)
+          expectTypeOf(parsed).toMatchTypeOf<{
+            filters: Array<any>
+            sorts: Array<any>
+            limit?: number
+          }>()
+
+          return Promise.resolve([])
+        },
+        getKey: (item) => item.id,
+        syncMode: `on-demand`,
+      }
+
+      const options = queryCollectionOptions(config)
+      createCollection(options)
+    })
+
+    it(`should allow users to extend QueryCollectionMeta via module augmentation`, () => {
+      // This test validates that users can extend QueryCollectionMeta to add custom properties
+      // by augmenting the @tanstack/query-db-collection module
+
+      // In reality, users would do:
+      // declare module "@tanstack/query-db-collection" {
+      //   interface QueryCollectionMeta {
+      //     customUserId: number
+      //     customContext?: string
+      //   }
+      // }
+
+      const config: QueryCollectionConfig<TestItem> = {
+        id: `extendMetaTest`,
+        queryClient,
+        queryKey: [`extendMetaTest`],
+        queryFn: (ctx) => {
+          // ctx.meta still has loadSubsetOptions
+          expectTypeOf(ctx.meta?.loadSubsetOptions).toMatchTypeOf<
+            LoadSubsetOptions | undefined
+          >()
+
+          // This test documents the extension pattern even though we can't
+          // actually augment QueryCollectionMeta in a test file (it would
+          // affect all other tests in the same compilation unit)
+
+          return Promise.resolve([])
+        },
+        getKey: (item) => item.id,
+        syncMode: `on-demand`,
+      }
+
+      const options = queryCollectionOptions(config)
+      createCollection(options)
+    })
   })
 })