eden-tanstack-query 0.0.9 → 0.1.0-alpha.2

package/README.md

@@ -1,360 +1,119 @@
 # eden-tanstack-query
 
-A TanStack Query integration for [Eden Treaty](https://eden.ts), the type-safe client for [Elysia](https://elysiajs.com).
-
-## Features
-
-- 🔗 **Type-safe** - Full TypeScript inference from Elysia server types
-- ⚡ **Framework-agnostic** - Works with React Query, Svelte Query, Solid Query, Vue Query
-- 🎯 **queryOptions** - Reusable, type-safe query configurations
-- 🔄 **mutationOptions** - Type-safe mutation configurations
-- 🔑 **Query keys** - Auto-generated, type-safe query keys for cache operations
-- ⚠️ **Error handling** - Configurable error throwing
-- 🛠️ **Eden integration** - Seamlessly integrates with existing Treaty clients
+TanStack Query integration for [Elysia Eden](https://github.com/elysiajs/eden) - type-safe queries and mutations with zero boilerplate.
 
 ## Installation
 
 ```bash
-bun add eden-tanstack-query @tanstack/query-core
+bun add eden-tanstack-query @elysiajs/eden @tanstack/query-core
+# or
+npm install eden-tanstack-query @elysiajs/eden @tanstack/query-core
 ```
 
-## Basic Usage
-
-### Setup
-
-```typescript
-import { treaty } from '@elysiajs/eden/treaty2'
-import { createEdenQuery } from 'eden-tanstack-query'
-import { useQuery } from '@tanstack/svelte-query'
-
-// Your Elysia app type
-type App = {
-  users: {
-    get: {
-      query: { page?: number }
-      response: { users: User[] }
-    }
-    post: {
-      body: { name: string, email: string }
-      response: { user: User }
-    }
-  }
-}
+## Usage
 
-// Create Eden Query client
-const eden = createEdenQuery<App>('http://localhost:8080')
+```ts
+import { createEdenTQ } from 'eden-tanstack-query'
+import type { App } from './server' // Your Elysia app type
+
+const eden = createEdenTQ<App>('http://localhost:3000')
 ```
 
 ### Queries
 
-```typescript
-// Basic query (auto-generated query key)
-const query = useQuery(eden.users.get.queryOptions())
+```ts
+import { createQuery } from '@tanstack/svelte-query' // or react-query, vue-query, etc.
 
-// Query with parameters
-const query = useQuery(
-  eden.users.get.queryOptions({ query: { page: 1 } })
+// Fully type-safe, auto-generated query key
+const query = createQuery(() => 
+  eden.users({ id: '123' }).get.queryOptions({
+    params: { id: '123' }
+  })
 )
 
-// Access the data
-query.data?.users  // Fully typed from your Elysia response
+// query.data is typed as your Elysia response type!
 ```
 
 ### Mutations
 
-```typescript
-import { useMutation } from '@tanstack/svelte-query'
-
-// Basic mutation
-const mutation = useMutation(eden.users.post.mutationOptions())
-
-// Using the mutation
-mutation.mutate({ name: 'John', email: 'john@example.com' })
-
-// Access the response
-mutation.data?.user  // Fully typed
-```
-
-### Query Keys
-
-```typescript
-// Get type-safe query keys for cache operations
-const usersKey = eden.users.get.queryKey()
-
-// Invalidate queries
-const queryClient = useQueryClient()
-queryClient.invalidateQueries({ queryKey: usersKey })
-
-// Get query data type-safely
-const data = queryClient.getQueryData(eden.users.get.queryKey())
-```
-
-## Error Handling
-
-### Global Error Handler
-
-Define error handling logic once when creating the client:
+```ts
+import { createMutation } from '@tanstack/svelte-query'
 
-```typescript
-import type { EdenErrorContext } from 'eden-tanstack-query'
-
-const eden = createEdenQuery<App>('http://localhost:8080', {
-  throwOnError: true,
-  onError: ({ error, path, method, type }: EdenErrorContext) => {
-    // Runs for ALL queries and mutations before throwing
-
-    if (error.status === 401) {
-      authStore.logout()
-      router.push('/login')
-    }
-
-    if (error.status === 403) {
-      toast.error('Not authorized')
-    }
-
-    if (error.status >= 500) {
-      toast.error('Server error, please try again')
-      logger.error('API Error', { path, method, error })
-    }
-  }
-})
-```
-
-The `EdenErrorContext` provides:
-- `error` - The `EdenFetchError` with status and value
-- `queryKey` - The generated query key
-- `method` - HTTP method ('get', 'post', etc.)
-- `path` - API path segments (['users', 'posts'])
-- `input` - The request input
-- `type` - Either 'query' or 'mutation'
-
-### Throw on Error (Default)
-
-```typescript
-const eden = createEdenQuery<App>('http://localhost:8080', {
-  throwOnError: true
-})
-
-// Per-query error handling (in addition to global handler)
-useQuery(eden.users.get.queryOptions(undefined, {
-  onError: (error: EdenFetchError) => {
-    // Runs after global handler, only for this query
-    if (error.status === 404) {
-      // Handle not found specifically for this query
-    }
-  }
-}))
-```
+const mutation = createMutation(() => 
+  eden.users.post.mutationOptions()
+)
 
-### Conditional Throwing
-
-```typescript
-const eden = createEdenQuery<App>('http://localhost:8080', {
-  throwOnError: (queryKey, status) => {
-    // Don't throw on 404 (not found)
-    if (status === 404) return false
-    // Throw on server errors
-    if (status >= 500) return true
-    return false
-  }
+// Type-safe variables
+mutation.mutate({
+  body: { name: 'Alice', email: 'alice@example.com' }
 })
 ```
 
-### Type-Safe Data Narrowing
-
-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
-// 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: User[] }
-    // Error shape is excluded - errors throw before reaching here
-    return data.users  // No type guard needed
-  },
-  onSuccess: (data) => {
-    // data: { users: User[] }
-    console.log(data.users)
-  }
-}))
-
-// query.data type: { users: User[] } | undefined
-```
-
-When `throwOnError` is `false`, the full union type is preserved since errors don't throw:
+### Invalidation
 
-```typescript
-// Explicit: throwOnError = false
-const eden = createEdenQuery<App>('http://localhost:8080', {
-  throwOnError: false
-})
+```ts
+import { useQueryClient } from '@tanstack/svelte-query'
 
-useQuery(eden.users.get.queryOptions(undefined, {
-  select: (data) => {
-    // 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):
+const queryClient = useQueryClient()
 
-```typescript
-// Conditional throwing
-const eden = createEdenQuery<App>('http://localhost:8080', {
-  throwOnError: (queryKey, status) => status >= 500
+// Invalidate specific query
+await eden.users({ id: '123' }).get.invalidate(queryClient, {
+  params: { id: '123' }
 })
 
-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
-  }
-}))
+// Invalidate all queries for a route
+await eden.users({ id: '123' }).get.invalidate(queryClient)
 ```
 
-### Known Limitation: createQuery Inference
+## API
 
-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.
+### `createEdenTQ<App>(domain, config?)`
 
-**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
+Creates a type-safe Eden client with TanStack Query helpers.
 
-**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
+- `domain`: Your API URL or Elysia app instance
+- `config.queryKeyPrefix`: Custom prefix for query keys (default: `['eden']`)
 
-**Workarounds:**
+### Method Helpers
 
-```typescript
-// 1. Use select to transform with explicit types
-useQuery(eden.users.get.queryOptions(undefined, {
-  select: (data) => data.users  // data is narrowed here
-}))
+Each HTTP method (`get`, `post`, `put`, `delete`, `patch`) has:
 
-// 2. Add explicit type annotation
-const query = useQuery(eden.users.get.queryOptions()) as CreateQueryResult<{ users: User[] }>
+- `.queryOptions(input, overrides?)` - Returns `{ queryKey, queryFn }`
+- `.mutationOptions(overrides?)` - Returns `{ mutationKey, mutationFn }`
+- `.queryKey(input?)` - Returns the query key
+- `.mutationKey(input?)` - Returns the mutation key
+- `.invalidate(queryClient, input?, exact?)` - Invalidates matching queries
 
-// 3. Access queryFn directly for fully typed results
-const options = eden.users.get.queryOptions()
-const data = await options.queryFn()  // Correctly typed
-```
+## Before / After
 
-## Advanced Usage
+### Before (manual boilerplate)
 
-### Custom Eden Treaty Options
-
-```typescript
-const eden = createEdenQuery<App>('http://localhost:8080', {
-  treaty: {
-    headers: { authorization: 'Bearer token' },
-    fetch: customFetch
-  }
-})
-
-useQuery(eden.users.get.queryOptions(
-  { query: { page: 1 } },
-  {
-    eden: {
-      headers: { 'X-Custom': 'value' }
+```ts
+export function createUserQuery(userId: string) {
+  return createQuery<User>(() => ({
+    queryKey: ['users', userId],
+    queryFn: async () => {
+      const { data, error } = await api.users({ id: userId }).get()
+      if (error) throw error
+      return data as User // Manual cast!
     },
-    staleTime: 5000
-  }
-))
-```
-
-### Query Key Prefix
-
-```typescript
-const eden = createEdenQuery<App>('http://localhost:8080', {
-  queryKeyPrefix: 'my-api'
-})
-
-// Keys will be prefixed: ['my-api', 'users', 'get']
-```
-
-### Using with React Query
-
-```typescript
-import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
-
-const query = useQuery(eden.users.get.queryOptions())
-const mutation = useMutation(eden.users.post.mutationOptions())
-const queryClient = useQueryClient()
-```
-
-### Using with Solid Query
-
-```typescript
-import { createQuery, createMutation } from '@tanstack/solid-query'
-
-const query = createQuery(() => eden.users.get.queryOptions())
-const mutation = createMutation(() => eden.users.post.mutationOptions())
-```
-
-### Using with Vue Query
-
-```typescript
-import { useQuery, useMutation, useQueryClient } from '@tanstack/vue-query'
-
-const query = useQuery(eden.users.get.queryOptions())
-const mutation = useMutation(eden.users.post.mutationOptions())
-const queryClient = useQueryClient()
+  }))
+}
 ```
 
-## Query Key Structure
-
-Query keys are auto-generated from your API paths:
-
-```typescript
-// Simple path
-eden.users.get.queryKey()
-// → ['users', 'get']
-
-// Path with parameters
-eden.users({ id: '123' }).get.queryKey()
-// → ['users', { id: '123' }, 'get']
+### After (with eden-tanstack-query)
 
-// Nested paths
- eden.users.posts({ userId: '123' }).get.queryKey()
-// → ['users', 'posts', { userId: '123' }, 'get']
+```ts
+export function createUserQuery(userId: string) {
+  return createQuery(() => 
+    eden.users({ id: userId }).get.queryOptions({
+      params: { id: userId }
+    })
+  )
+}
+// Types are inferred from your Elysia server!
 ```
 
-## Type Safety
-
-All types are fully inferred from your Elysia server:
-
-- ✅ Query data type (from success responses)
-- ✅ Error type (from EdenFetchError or Treaty response)
-- ✅ Input validation (query params, body)
-- ✅ Query keys (type-safe, auto-generated)
-- ✅ Framework-agnostic (works with all TanStack Query variants)
-
 ## License
 
 MIT

package/dist/index.d.mts

@@ -0,0 +1,84 @@
+import { Elysia, ELYSIA_FORM_DATA } from 'elysia';
+import { QueryKey, QueryClient } from '@tanstack/query-core';
+export { QueryClient, QueryKey } from '@tanstack/query-core';
+import { Treaty } from '@elysiajs/eden/treaty2';
+
+type IsNever<T> = [T] extends [never] ? true : false;
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type Enumerate<N extends number, Acc extends number[] = []> = Acc['length'] extends N ? Acc[number] : Enumerate<N, [...Acc, Acc['length']]>;
+type IntegerRange<F extends number, T extends number> = Exclude<Enumerate<T>, Enumerate<F>>;
+type SuccessCodeRange = IntegerRange<200, 300>;
+type ExtractData<Res extends Record<number, unknown>> = Res[Extract<keyof Res, SuccessCodeRange>] extends {
+    [ELYSIA_FORM_DATA]: infer Data;
+} ? Data : Res[Extract<keyof Res, SuccessCodeRange>];
+type ExtractError<Res extends Record<number, unknown>> = Exclude<keyof Res, SuccessCodeRange> extends never ? {
+    status: unknown;
+    value: unknown;
+} : {
+    [Status in keyof Res]: {
+        status: Status;
+        value: Res[Status] extends {
+            [ELYSIA_FORM_DATA]: infer Data;
+        } ? Data : Res[Status];
+    };
+}[Exclude<keyof Res, SuccessCodeRange>];
+interface TQParamBase {
+    fetch?: RequestInit;
+}
+type SerializeQueryParams<T> = T extends Record<string, any> ? {
+    [K in keyof T]: T[K] extends Date ? string : T[K] extends Date | undefined ? string | undefined : T[K];
+} : T;
+type IsEmptyObject<T> = T extends Record<string, never> ? [keyof T] extends [never] ? true : false : false;
+type MaybeEmptyObject<T, K extends PropertyKey> = [T] extends [never] ? {} : [T] extends [undefined] ? {
+    [P in K]?: T;
+} : IsEmptyObject<T> extends true ? {
+    [P in K]?: T;
+} : undefined extends T ? {
+    [P in K]?: T;
+} : {
+    [P in K]: T;
+};
+type TQMethodParam<Body, Headers, Query, Params> = MaybeEmptyObject<Headers, 'headers'> & MaybeEmptyObject<SerializeQueryParams<Query>, 'query'> & MaybeEmptyObject<Params, 'params'> & MaybeEmptyObject<Body, 'body'> & TQParamBase;
+interface EdenQueryOptions<TData = unknown, TError = unknown> {
+    queryKey: QueryKey;
+    queryFn: () => Promise<TData>;
+}
+interface EdenMutationOptions<TData = unknown, TError = unknown, TVariables = unknown> {
+    mutationKey: QueryKey;
+    mutationFn: (variables: TVariables) => Promise<TData>;
+}
+interface EdenTQMethod<Body, Headers, Query, Params, Res extends Record<number, unknown>> {
+    <TQueryFnData = ExtractData<Res>>(input: TQMethodParam<Body, Headers, Query, Params>, options?: RequestInit): Promise<Treaty.TreatyResponse<Res>>;
+    queryKey(input?: TQMethodParam<Body, Headers, Query, Params>): QueryKey;
+    queryOptions<TData = ExtractData<Res>>(input: TQMethodParam<Body, Headers, Query, Params>, overrides?: Partial<EdenQueryOptions<TData, ExtractError<Res>>>): EdenQueryOptions<TData, ExtractError<Res>>;
+    mutationKey(input?: TQMethodParam<Body, Headers, Query, Params>): QueryKey;
+    mutationOptions<TData = ExtractData<Res>>(overrides?: Partial<EdenMutationOptions<TData, ExtractError<Res>, TQMethodParam<Body, Headers, Query, Params>>>): EdenMutationOptions<TData, ExtractError<Res>, TQMethodParam<Body, Headers, Query, Params>>;
+    invalidate(queryClient: QueryClient, input?: TQMethodParam<Body, Headers, Query, Params>, exact?: boolean): Promise<void>;
+}
+declare namespace EdenTQ {
+    export type Config = Treaty.Config & {
+        queryKeyPrefix?: QueryKey;
+    };
+    export type Create<App extends Elysia<any, any, any, any, any, any, any>> = App extends {
+        '~Routes': infer Schema extends Record<any, any>;
+    } ? Prettify<Sign<Schema>> & CreateParams<Schema> : 'Please install Elysia before using Eden';
+    export type Sign<in out Route extends Record<any, any>> = {
+        [K in keyof Route as K extends `:${string}` ? never : K]: Route[K] extends {
+            body: infer Body;
+            headers: infer Headers;
+            params: infer Params;
+            query: infer Query;
+            response: infer Res extends Record<number, unknown>;
+        } ? EdenTQMethod<Body, Headers, Query, Params, Res> : CreateParams<Route[K]>;
+    };
+    type CreateParams<Route extends Record<string, any>> = Extract<keyof Route, `:${string}`> extends infer Path extends string ? IsNever<Path> extends true ? Prettify<Sign<Route>> : (((params: {
+        [param in Path extends `:${infer Param}` ? Param extends `${infer P}?` ? P : Param : never]: string | number;
+    }) => Prettify<Sign<Route[Path]>> & CreateParams<Route[Path]>) & Prettify<Sign<Route>>) & (Path extends `:${string}?` ? CreateParams<Route[Path]> : {}) : never;
+    export {  };
+}
+
+declare function createEdenTQ<const App extends Elysia<any, any, any, any, any, any, any>>(domain: string | App, config?: EdenTQ.Config): EdenTQ.Create<App>;
+
+export { type EdenMutationOptions, type EdenQueryOptions, EdenTQ, createEdenTQ };