fix: make TuyauPromise implement Promise<T> for TanStack Query compatibility

TuyauPromise only implemented PromiseLike<T> and was missing
[Symbol.toStringTag], so TypeScript didn't consider it assignable to
Promise<T>. This caused TanStack Query to infer data as
TuyauPromise<Response> instead of Response when using @tuyau/core
directly with useQuery.

Author: Julien-R44

.changeset/fix-tuyau-promise-compat.md

@@ -0,0 +1,17 @@
+---
+'@tuyau/core': patch
+---
+
+Fix `TuyauPromise` not being assignable to `Promise<T>`, which broke TanStack Query type inference.
+
+`TuyauPromise` implemented `PromiseLike<T>` but was missing `[Symbol.toStringTag]`, so TypeScript did not consider it structurally compatible with `Promise<T>`. When users passed a tuyau call directly to TanStack Query's `queryFn`, the `data` type was inferred as `TuyauPromise<Response>` instead of `Response`:
+
+```ts
+// Before: data was typed as TuyauPromise<User[]> instead of User[]
+const { data } = useQuery({
+  queryKey: ['users'],
+  queryFn: () => tuyau.request('users.index', {}),
+})
+```
+
+`TuyauPromise` now implements the full `Promise<T>` interface, so it works seamlessly with TanStack Query and any other library expecting `Promise<T>`.

packages/core/src/client/promise.ts

@@ -12,9 +12,11 @@ type NormalizeError<E> =
 
 /**
  * A promise wrapper that adds `.safe()` for non-throwing error handling.
- * Implements PromiseLike so `await` works transparently.
+ * Implements Promise so it's fully compatible with TanStack Query and other
+ * libraries that expect `Promise<T>` return types.
  */
-export class TuyauPromise<Data, Errors = unknown> implements PromiseLike<Data> {
+export class TuyauPromise<Data, Errors = unknown> implements Promise<Data> {
+  readonly [Symbol.toStringTag]: string = 'TuyauPromise'
   #promise: Promise<Data>
 
   constructor(promise: Promise<Data>) {

packages/core/tests/typings.spec.ts

@@ -473,6 +473,16 @@ test.group('Client | Typings', (group) => {
     expectTypeOf<DownloadsParams>().toEqualTypeOf<{ '*': string[] }>()
   })
 
+  test('TuyauPromise is assignable to Promise', ({ expectTypeOf }) => {
+    const tuyau = createTuyau({ baseUrl: 'http://localhost:3333', registry })
+
+    const result = tuyau.get('/users', {})
+
+    // This is the scenario that breaks TanStack Query:
+    // queryFn expects Promise<T>, but TuyauPromise only implements PromiseLike<T>
+    expectTypeOf(result).toMatchTypeOf<Promise<{ token: string }>>()
+  })
+
   test('safe() returns TuyauPromise with correct error types', ({ expectTypeOf }) => {
     const tuyau = createTuyau({ baseUrl: 'http://localhost:3333', registry })
 

packages/react-query/tests/query.spec.tsx

@@ -250,6 +250,31 @@ test.group('Types | queryOptions useSuspenseQuery compatibility', () => {
   })
 })
 
+test.group('Types | TuyauPromise assignable to Promise (TanStack Query compat)', () => {
+  test('useQuery with raw tuyau client should infer response type, not TuyauPromise', ({
+    expectTypeOf,
+  }) => {
+    const client = createTuyau({ baseUrl: 'http://localhost:3333', registry: defaultRegistry })
+
+    // When users use @tuyau/core directly with TanStack Query (without @tuyau/react-query),
+    // queryFn returns TuyauPromise which implements PromiseLike but NOT Promise.
+    // TanStack Query's queryFn is typed as `() => T | Promise<T>`.
+    // Since TuyauPromise is not a Promise, TS resolves T = TuyauPromise<Response>
+    // instead of unwrapping it to T = Response. This makes `data` wrongly typed.
+    const { result } = renderHookWithWrapper(() =>
+      useQuery({
+        queryKey: ['users'] as const,
+        queryFn: () => client.request('users.index', {}),
+      }),
+    )
+
+    // BUG: data is TuyauPromise<Array<...>> | undefined instead of Array<...> | undefined
+    expectTypeOf(result.current.data).toEqualTypeOf<
+      Array<{ id: number; name: string }> | undefined
+    >()
+  })
+})
+
 test.group('Query | Filters', () => {
   test('queryFilter should merge filters with queryKey', ({ assert }) => {
     const client = createTuyau({ baseUrl: 'http://localhost:3333', registry: defaultRegistry })