eden-tanstack-query 0.0.6 → 0.0.8

package/README.md

@@ -165,34 +165,104 @@ const eden = createEdenQuery<App>('http://localhost:8080', {
 When `throwOnError` is `true` (the default), errors are thrown before reaching callbacks like `select` and `onSuccess`. The library automatically narrows the data type to exclude error shapes:
 
 ```typescript
-// Default: throwOnError = true
-// Data type in select/onSuccess excludes { error: string } shapes
+// Given an endpoint that returns:
+// - Success: { users: User[] }
+// - Error: { error: string }
+
+// Default: throwOnError = true (or omitted)
 const eden = createEdenQuery<App>('http://localhost:8080')
+// OR explicitly:
+const eden = createEdenQuery<App>('http://localhost:8080', { throwOnError: true })
 
 useQuery(eden.users.get.queryOptions(undefined, {
-  select: (data) => data.users,  // TypeScript knows data doesn't have error shape
+  select: (data) => {
+    // data: { users: User[] }
+    // Error shape is excluded - errors throw before reaching here
+    return data.users  // No type guard needed
+  },
   onSuccess: (data) => {
-    console.log(data.users)  // No need for type guards
+    // data: { users: User[] }
+    console.log(data.users)
   }
 }))
+
+// query.data type: { users: User[] } | undefined
 ```
 
-When `throwOnError` is `false` or a function, the full union type is preserved:
+When `throwOnError` is `false`, the full union type is preserved since errors don't throw:
 
 ```typescript
 // Explicit: throwOnError = false
-// Data type includes all response shapes (success and error)
 const eden = createEdenQuery<App>('http://localhost:8080', {
   throwOnError: false
 })
 
 useQuery(eden.users.get.queryOptions(undefined, {
   select: (data) => {
-    // Need to handle both success and error shapes
+    // data: { users: User[] } | { error: string }
+    // Must handle both cases since errors don't throw
     if ('error' in data) return null
     return data.users
+  },
+  onSuccess: (data) => {
+    // data: { users: User[] } | { error: string }
+    if ('error' in data) {
+      console.log('Error:', data.error)
+    } else {
+      console.log(data.users)
+    }
   }
 }))
+
+// query.data type: { users: User[] } | { error: string } | undefined
+```
+
+When `throwOnError` is a function, the full union type is also preserved (since throwing is conditional):
+
+```typescript
+// Conditional throwing
+const eden = createEdenQuery<App>('http://localhost:8080', {
+  throwOnError: (queryKey, status) => status >= 500
+})
+
+useQuery(eden.users.get.queryOptions(undefined, {
+  select: (data) => {
+    // data: { users: User[] } | { error: string }
+    // Full union - some errors may not throw (e.g., 404)
+    if ('error' in data) return null
+    return data.users
+  }
+}))
+```
+
+### Known Limitation: createQuery Inference
+
+The type narrowing works correctly at the library level (queryFn return type), but TanStack Query's `createQuery`/`useQuery` may not always infer the narrowed type due to complex generic inference.
+
+**What works:**
+- `NarrowedData` type correctly excludes error shapes
+- `queryFn` return type is narrowed at the library level
+- Query keys are correctly typed
+- Direct access to options properties
+
+**What may vary:**
+- `createQuery(options)` inference depends on framework version and TS config
+- `query.data` may show as `unknown` or full union in some cases
+
+**Workarounds:**
+
+```typescript
+// 1. Use select to transform with explicit types
+useQuery(eden.users.get.queryOptions(undefined, {
+  select: (data) => data.users  // data is narrowed here
+}))
+
+// 2. Add explicit type annotation
+const query = useQuery(eden.users.get.queryOptions()) as CreateQueryResult<{ users: User[] }>
+
+// 3. Access queryFn directly for fully typed results
+const options = eden.users.get.queryOptions()
+const data = await options.queryFn()  // Correctly typed
 ```
 
 ## Advanced Usage

package/dist/index.d.ts

@@ -33,15 +33,32 @@ interface EdenQueryConfig<TThrowOnError extends ThrowOnErrorOption = true> {
  * Narrows data type by excluding error-shaped objects when throwOnError is true.
  * When throwOnError is true, errors are thrown before reaching callbacks like
  * `select` or `onSuccess`, so the data type should exclude error shapes.
+ *
+ * Uses conditional type to check if each union member has an `error: string` property,
+ * which handles cases like `{ error: string; message?: undefined }` that simple
+ * `Exclude<T, { error: string }>` misses due to structural typing quirks.
  */
-type NarrowedData<TData, TThrowOnError> = TThrowOnError extends true ? Exclude<TData, {
+type NarrowedData<TData, TThrowOnError> = TThrowOnError extends true ? TData extends {
     error: string;
-}> : TData;
+} ? never : TData : TData;
 interface EdenOptions<TEden = unknown> {
     eden?: TEden;
 }
 type EdenQueryKey<TInput = unknown, TMethod extends HTTPMethod = HTTPMethod> = readonly [...string[], TInput, TMethod];
+/**
+ * Options for eden queries, extending QueryObserverOptions.
+ * Used for the optional `options` parameter in `queryOptions()`.
+ */
 type EdenQueryOptions<TQueryFnData, TError = Error, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TEden = unknown> = Omit<QueryObserverOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>, 'queryKey' | 'queryFn'> & EdenOptions<TEden>;
+/**
+ * Full query options returned by `queryOptions()`, compatible with createQuery.
+ * This type uses a simpler structure to ensure TypeScript properly infers TData
+ * when passed to createQuery.
+ */
+type EdenQueryOptionsResult<TQueryFnData, TError = Error, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> = {
+    queryKey: TQueryKey;
+    queryFn: (context: QueryFunctionContext<TQueryKey>) => Promise<TQueryFnData>;
+} & Omit<QueryObserverOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>, 'queryKey' | 'queryFn'>;
 type EdenMutationOptions<TData, TError = Error, TVariables = void, TContext = unknown, TEden = unknown> = Omit<MutationOptions<TData, TError, TVariables, TContext>, 'mutationFn'> & EdenOptions<TEden>;
 type EdenInfiniteQueryOptions<TQueryFnData, TError = Error, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TPageParam = unknown, TEden = unknown> = Omit<InfiniteQueryObserverOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, 'queryKey' | 'queryFn'> & EdenOptions<TEden>;
 type EdenPartial<T> = T extends object ? Partial<T> : never;
@@ -56,10 +73,7 @@ type EdenData<T> = Extract<AwaitedReturn<T>, {
 type EdenQueryMethod<TMethod extends Extract<HTTPMethod, 'get' | 'head'>, TCall extends (...args: any[]) => Promise<any>, TThrowOnError extends ThrowOnErrorOption = true> = TCall & {
     queryKey: (input?: FirstArg<TCall>) => EdenQueryKey<FirstArg<TCall>, TMethod>;
     queryFilter: (input?: FirstArg<TCall>) => QueryFilters<EdenQueryKey<FirstArg<TCall>, TMethod>>;
-    queryOptions: (input?: FirstArg<TCall>, options?: EdenQueryOptions<NarrowedData<EdenData<TCall>, TThrowOnError>, EdenFetchError | Error, NarrowedData<EdenData<TCall>, TThrowOnError>, EdenQueryKey<FirstArg<TCall>, TMethod>, EdenPartial<NonNullable<FirstArg<TCall>>>>) => EdenQueryOptions<NarrowedData<EdenData<TCall>, TThrowOnError>, EdenFetchError | Error, NarrowedData<EdenData<TCall>, TThrowOnError>, EdenQueryKey<FirstArg<TCall>, TMethod>, EdenPartial<NonNullable<FirstArg<TCall>>>> & {
-        queryKey: EdenQueryKey<FirstArg<TCall>, TMethod>;
-        queryFn: (context: QueryFunctionContext<EdenQueryKey<FirstArg<TCall>, TMethod>>) => Promise<NarrowedData<EdenData<TCall>, TThrowOnError>>;
-    };
+    queryOptions: (input?: FirstArg<TCall>, options?: EdenQueryOptions<NarrowedData<EdenData<TCall>, TThrowOnError>, EdenFetchError | Error, NarrowedData<EdenData<TCall>, TThrowOnError>, EdenQueryKey<FirstArg<TCall>, TMethod>, EdenPartial<NonNullable<FirstArg<TCall>>>>) => EdenQueryOptionsResult<NarrowedData<EdenData<TCall>, TThrowOnError>, EdenFetchError | Error, NarrowedData<EdenData<TCall>, TThrowOnError>, EdenQueryKey<FirstArg<TCall>, TMethod>>;
 };
 type EdenMutationMethod<TMethod extends Extract<HTTPMethod, 'post' | 'put' | 'patch' | 'delete'>, TCall extends (...args: any[]) => Promise<any>, TThrowOnError extends ThrowOnErrorOption = true> = TCall & {
     mutationOptions: (options?: EdenMutationOptions<NarrowedData<EdenData<TCall>, TThrowOnError>, EdenFetchError | Error, FirstArg<TCall>, unknown, EdenPartial<NonNullable<SecondArg<TCall>>>>) => EdenMutationOptions<NarrowedData<EdenData<TCall>, TThrowOnError>, EdenFetchError | Error, FirstArg<TCall>, unknown, EdenPartial<NonNullable<SecondArg<TCall>>>> & {
@@ -95,4 +109,4 @@ declare function createEdenQuery<App extends Elysia<any, any, any, any, any, any
     treaty?: Treaty.Config;
 }): EdenQueryify<Treaty.Create<App>, TThrowOnError>;
 
-export { type EdenErrorContext, type EdenInfiniteQueryOptions, type EdenMutationMethod, type EdenMutationOptions, type EdenOptions, type EdenQueryConfig, type EdenQueryKey, type EdenQueryMethod, type EdenQueryOptions, type EdenQueryify, type EdenThrowOnError, type EdenThrowOnErrorContext, type HTTPMethod, type NarrowedData, type ThrowOnErrorOption, createEdenQuery };
+export { type EdenErrorContext, type EdenInfiniteQueryOptions, type EdenMutationMethod, type EdenMutationOptions, type EdenOptions, type EdenQueryConfig, type EdenQueryKey, type EdenQueryMethod, type EdenQueryOptions, type EdenQueryOptionsResult, type EdenQueryify, type EdenThrowOnError, type EdenThrowOnErrorContext, type HTTPMethod, type NarrowedData, type ThrowOnErrorOption, createEdenQuery };

package/dist/index.js

@@ -35,7 +35,12 @@ function createQueryOptions(treatyCall, paths, method, globalConfig) {
   return (input, options) => {
     const eden = options?.eden;
     const finalInput = input === void 0 && eden === void 0 ? void 0 : { ...input, ...eden };
-    const queryKey = buildQueryKey(paths, finalInput, method, globalConfig.queryKeyPrefix);
+    const queryKey = buildQueryKey(
+      paths,
+      finalInput,
+      method,
+      globalConfig.queryKeyPrefix
+    );
     const { eden: _eden, ...tanstackOptions } = options ?? {};
     return {
       ...tanstackOptions,
@@ -157,7 +162,7 @@ function createQueryFilter(paths, method, prefix) {
 // src/proxy.ts
 var HTTP_METHODS = ["get", "post", "put", "patch", "delete", "head", "options"];
 function extendProxy(proxy, paths, config) {
-  return new Proxy(proxy, {
+  const handler = {
     get(target, prop) {
       if (typeof prop === "symbol") return target[prop];
       const value = target[prop];
@@ -189,8 +194,16 @@ function extendProxy(proxy, paths, config) {
         return extendProxy(value, [...paths, prop], config);
       }
       return value;
+    },
+    apply(target, thisArg, args) {
+      const result = Reflect.apply(target, thisArg, args);
+      if (result !== null && (typeof result === "object" || typeof result === "function")) {
+        return extendProxy(result, paths, config);
+      }
+      return result;
     }
-  });
+  };
+  return new Proxy(proxy, handler);
 }
 
 // src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eden-tanstack-query",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "TanStack Query integration for Eden Treaty",
   "type": "module",
   "main": "./dist/index.js",