fix(query): emit plain SolidMutationOptions for user-facing mutation param (#3365)

Solid Query's `Use*Options` / `Create*Options` aliases are
`Accessor<…>` wrappers, so typing `options.mutation` as
`UseMutationOptions<…>` made callers fail with "object literal may
only specify known properties, and 'onSuccess' does not exist". The
runtime then spreads it as a plain object, which only "worked"
because no caller could legally produce that shape.

The mutation now uses the adapter's plain options interface
(`SolidMutationOptions` < 5.100.6, `MutationOptions` ≥ 5.100.6 after
TanStack dropped the `Solid` prefix) for both the helper return type
and the user-facing `options.mutation` param. Detection lives in a
new `isSolidQueryWithRenamedOptionsTypes` helper, plumbed into the
solid adapter so generated imports stay in sync with the installed
package.

Queries keep their existing prefix-based `Use*Options` shape for the
user-facing `options.query` param: Solid's `useQuery` overloads only
discriminate against `Undefined/DefinedInitialDataOptions`, both of
which are Accessor types, so widening to the plain options here would
break `initialData` discrimination at the call site.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mhamri

packages/query/src/dependencies.test.ts

@@ -5,6 +5,8 @@ import {
   isQueryV5,
   isQueryV5WithDataTagError,
   isQueryV5WithInfiniteQueryOptionsError,
+  isSolidQueryWithRenamedOptionsTypes,
+  isSolidQueryWithUsePrefix,
 } from './dependencies';
 
 describe('isQueryV5', () => {
@@ -112,3 +114,57 @@ describe('isQueryV5WithDataTagError', () => {
     expect(isQueryV5WithDataTagError(packageJson, 'react-query')).toBe(false);
   });
 });
+
+describe('isSolidQueryWithUsePrefix', () => {
+  it('should return true for 5.71.5 (boundary)', () => {
+    const packageJson: PackageJson = {
+      resolvedVersions: { '@tanstack/solid-query': '5.71.5' },
+    };
+    expect(isSolidQueryWithUsePrefix(packageJson)).toBe(true);
+  });
+
+  it('should return false for 5.71.4', () => {
+    const packageJson: PackageJson = {
+      resolvedVersions: { '@tanstack/solid-query': '5.71.4' },
+    };
+    expect(isSolidQueryWithUsePrefix(packageJson)).toBe(false);
+  });
+
+  it('should return false when solid-query is not installed', () => {
+    expect(isSolidQueryWithUsePrefix({})).toBe(false);
+  });
+});
+
+describe('isSolidQueryWithRenamedOptionsTypes', () => {
+  it('should return true for 5.100.6 (boundary — Solid prefix dropped)', () => {
+    const packageJson: PackageJson = {
+      resolvedVersions: { '@tanstack/solid-query': '5.100.6' },
+    };
+    expect(isSolidQueryWithRenamedOptionsTypes(packageJson)).toBe(true);
+  });
+
+  it('should return true for 5.100.10', () => {
+    const packageJson: PackageJson = {
+      resolvedVersions: { '@tanstack/solid-query': '5.100.10' },
+    };
+    expect(isSolidQueryWithRenamedOptionsTypes(packageJson)).toBe(true);
+  });
+
+  it('should return false for 5.100.5 (just below boundary)', () => {
+    const packageJson: PackageJson = {
+      resolvedVersions: { '@tanstack/solid-query': '5.100.5' },
+    };
+    expect(isSolidQueryWithRenamedOptionsTypes(packageJson)).toBe(false);
+  });
+
+  it('should return false for 5.90.21 (well below boundary)', () => {
+    const packageJson: PackageJson = {
+      resolvedVersions: { '@tanstack/solid-query': '5.90.21' },
+    };
+    expect(isSolidQueryWithRenamedOptionsTypes(packageJson)).toBe(false);
+  });
+
+  it('should return false when solid-query is not installed', () => {
+    expect(isSolidQueryWithRenamedOptionsTypes({})).toBe(false);
+  });
+});

packages/query/src/dependencies.ts

@@ -285,8 +285,25 @@ const VUE_QUERY_DEPENDENCIES: GeneratorDependency[] = [
 
 const getSolidQueryImports = (
   prefix: 'use' | 'create',
+  hasRenamedOptionsTypes: boolean,
 ): GeneratorDependency[] => {
   const capitalized = prefix === 'use' ? 'Use' : 'Create';
+  // Solid Query renamed the plain options interfaces in v5.100.6, dropping the
+  // `Solid` prefix: `SolidQueryOptions` → `QueryOptions`, `SolidInfiniteQueryOptions` →
+  // `InfiniteQueryOptions`, `SolidMutationOptions` → `MutationOptions`. The
+  // `Use*Options` / `Create*Options` Accessor aliases keep their names but
+  // are still imported because queries use them as the user-facing
+  // `options.query` param type (Solid's `useQuery` overloads rely on that
+  // shape so the `initialData?` discrimination keeps working).
+  const queryOptionsTypeName = hasRenamedOptionsTypes
+    ? 'QueryOptions'
+    : 'SolidQueryOptions';
+  const infiniteQueryOptionsTypeName = hasRenamedOptionsTypes
+    ? 'InfiniteQueryOptions'
+    : 'SolidInfiniteQueryOptions';
+  const mutationOptionsTypeName = hasRenamedOptionsTypes
+    ? 'MutationOptions'
+    : 'SolidMutationOptions';
   return [
     {
       exports: [
@@ -295,10 +312,9 @@ const getSolidQueryImports = (
         { name: `${prefix}Mutation`, values: true },
         { name: `${capitalized}QueryOptions` },
         { name: `${capitalized}InfiniteQueryOptions` },
-        { name: `${capitalized}MutationOptions` },
-        { name: 'SolidQueryOptions' },
-        { name: 'SolidInfiniteQueryOptions' },
-        { name: 'SolidMutationOptions' },
+        { name: queryOptionsTypeName },
+        { name: infiniteQueryOptionsTypeName },
+        { name: mutationOptionsTypeName },
         { name: 'QueryFunction' },
         { name: 'MutationFunction' },
         { name: `${capitalized}QueryResult` },
@@ -393,6 +409,7 @@ export const getSolidQueryDependencies: ClientDependenciesBuilder = (
     ...(hasParamsSerializerOptions ? PARAMS_SERIALIZER_DEPENDENCIES : []),
     ...getSolidQueryImports(
       isSolidQueryWithUsePrefix(packageJson) ? 'use' : 'create',
+      isSolidQueryWithRenamedOptionsTypes(packageJson),
     ),
   ];
 };
@@ -561,6 +578,33 @@ export const isSolidQueryWithUsePrefix = (
   return compareVersions(withoutRc, '5.71.5');
 };
 
+/**
+ * Solid Query renamed its plain options interfaces in v5.100.6, dropping the
+ * `Solid` prefix:
+ *   - `SolidQueryOptions` → `QueryOptions`
+ *   - `SolidInfiniteQueryOptions` → `InfiniteQueryOptions`
+ *   - `SolidMutationOptions` → `MutationOptions`
+ *
+ * The Accessor wrappers `UseQueryOptions` / `UseInfiniteQueryOptions` /
+ * `UseMutationOptions` keep the same names but reference the renamed
+ * interfaces internally.
+ *
+ * https://github.com/TanStack/query/commit/<rename-commit>
+ */
+export const isSolidQueryWithRenamedOptionsTypes = (
+  packageJson: PackageJson | undefined,
+) => {
+  const version = getPackageByQueryClient(packageJson, 'solid-query');
+
+  if (!version) {
+    return false;
+  }
+
+  const withoutRc = version.split('-')[0];
+
+  return compareVersions(withoutRc, '5.100.6');
+};
+
 const getPackageByQueryClient = (
   packageJson: PackageJson | undefined,
   queryClient:

packages/query/src/framework-adapter.ts

@@ -185,8 +185,26 @@ export interface FrameworkAdapter {
   getQueryOptionsDefinitionPrefix(): string;
 
   /**
-   * Get the options type name for return types of getOptions functions.
-   * Solid: 'SolidQueryOptions' / 'SolidMutationOptions'. Others: use prefix + type.
+   * Get the plain (non-Accessor) options interface name for this framework.
+   *
+   * Used as:
+   *   - the helper function's return type for queries, infinite queries, and
+   *     mutations (`isReturnType: true`), AND
+   *   - the user-facing `options.mutation` parameter type
+   *     (`isReturnType: false`, mutation only — issue #3365).
+   *
+   * Queries intentionally keep the prefix-based `Use*Options` / `Create*Options`
+   * for the user-facing param: in Solid Query that aliases an `Accessor<…>`,
+   * which is the shape `useQuery`'s `Undefined/DefinedInitialDataOptions`
+   * overloads accept, preserving the `initialData?` discrimination at the call
+   * site.
+   *
+   * Solid Query overrides this with `SolidQueryOptions` / `SolidMutationOptions`
+   * (pre-v5.100.6) or `QueryOptions` / `MutationOptions` (v5.100.6+).
+   *
+   * Other adapters can leave this undefined and fall back to the prefix-based
+   * default (`UseMutationOptions`, `CreateMutationOptions`, …), which IS the
+   * plain options shape in their target libraries.
    */
   getOptionsReturnTypeName?(
     type: 'query' | 'infiniteQuery' | 'mutation',

packages/query/src/frameworks/index.ts

@@ -18,6 +18,7 @@ import {
   isQueryV5WithInfiniteQueryOptionsError,
   isQueryV5WithMutationContextOnSuccess,
   isQueryV5WithRequiredContextOnSuccess,
+  isSolidQueryWithRenamedOptionsTypes,
   isSolidQueryWithUsePrefix,
   isSvelteQueryV3,
   isSvelteQueryV6,
@@ -143,6 +144,7 @@ const withDefaults = (adapter: FrameworkAdapterConfig): FrameworkAdapter => ({
       queryParam,
       isReturnType: false,
       initialData,
+      adapter: adapter as FrameworkAdapter,
     });
 
     if (!isRequestOptions) {
@@ -297,6 +299,8 @@ export const createFrameworkAdapter = ({
 
     case OutputClientConst.SOLID_QUERY: {
       const hasSolidQueryWithUsePrefix = isSolidQueryWithUsePrefix(packageJson);
+      const hasSolidQueryWithRenamedOptionsTypes =
+        isSolidQueryWithRenamedOptionsTypes(packageJson);
       return withDefaults(
         createSolidAdapter({
           hasQueryV5: _hasQueryV5,
@@ -308,6 +312,8 @@ export const createFrameworkAdapter = ({
           hasQueryV5WithRequiredContextOnSuccess:
             _hasQueryV5WithRequiredContextOnSuccess,
           hasSolidQueryUsePrefix: hasSolidQueryWithUsePrefix,
+          hasSolidQueryRenamedOptionsTypes:
+            hasSolidQueryWithRenamedOptionsTypes,
         }),
       );
     }

packages/query/src/frameworks/solid.ts

@@ -24,13 +24,15 @@ export const createSolidAdapter = ({
   hasQueryV5WithMutationContextOnSuccess,
   hasQueryV5WithRequiredContextOnSuccess,
   hasSolidQueryUsePrefix,
+  hasSolidQueryRenamedOptionsTypes,
 }: {
   hasQueryV5: boolean;
   hasQueryV5WithDataTagError: boolean;
   hasQueryV5WithInfiniteQueryOptionsError: boolean;
   hasQueryV5WithMutationContextOnSuccess: boolean;
   hasQueryV5WithRequiredContextOnSuccess: boolean;
   hasSolidQueryUsePrefix: boolean;
+  hasSolidQueryRenamedOptionsTypes: boolean;
 }): FrameworkAdapterConfig => ({
   outputClient: OutputClient.SOLID_QUERY,
   hookPrefix: hasSolidQueryUsePrefix ? 'use' : 'create',
@@ -47,11 +49,26 @@ export const createSolidAdapter = ({
   getOptionsReturnTypeName(
     type: 'query' | 'infiniteQuery' | 'mutation',
   ): string | undefined {
-    // Solid Query uses SolidQueryOptions for queries, SolidInfiniteQueryOptions for infinite queries,
-    // and SolidMutationOptions for mutations (these are accessors)
-    if (type === 'mutation') return 'SolidMutationOptions';
-    if (type === 'infiniteQuery') return 'SolidInfiniteQueryOptions';
-    return 'SolidQueryOptions';
+    // Solid Query exposes plain (non-Accessor) options interfaces. The
+    // Accessor-wrapped `Use*Options` / `Create*Options` variants cannot be
+    // used here because the generated code passes options as a plain object
+    // (`{ ...options.mutation }`) before the call site wraps the whole result
+    // in an accessor (`useMutation(() => mutationOptions(...))`).
+    //
+    // v5.100.6 renamed these interfaces to drop the `Solid` prefix.
+    if (type === 'mutation') {
+      return hasSolidQueryRenamedOptionsTypes
+        ? 'MutationOptions'
+        : 'SolidMutationOptions';
+    }
+    if (type === 'infiniteQuery') {
+      return hasSolidQueryRenamedOptionsTypes
+        ? 'InfiniteQueryOptions'
+        : 'SolidInfiniteQueryOptions';
+    }
+    return hasSolidQueryRenamedOptionsTypes
+      ? 'QueryOptions'
+      : 'SolidQueryOptions';
   },
 
   getQueryKeyPrefix(): string {