eden-tanstack-query 0.0.1

package/README.md

@@ -0,0 +1,218 @@
+# @elysiajs/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
+
+## Installation
+
+```bash
+bun add @elysiajs/eden-tanstack-query @tanstack/query-core
+```
+
+## Basic Usage
+
+### Setup
+
+```typescript
+import { treaty } from '@elysiajs/eden/treaty2'
+import { createEdenQuery } from '@elysiajs/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 }
+    }
+  }
+}
+
+// Create Eden Query client
+const eden = createEdenQuery<App>('http://localhost:8080')
+```
+
+### Queries
+
+```typescript
+// Basic query (auto-generated query key)
+const query = useQuery(eden.users.get.queryOptions())
+
+// Query with parameters
+const query = useQuery(
+  eden.users.get.queryOptions({ query: { page: 1 } })
+)
+
+// Access the data
+query.data?.users  // Fully typed from your Elysia response
+```
+
+### 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
+
+### Throw on Error (Default for most apps)
+
+```typescript
+const eden = createEdenQuery<App>('http://localhost:8080', {
+  throwOnError: true
+})
+
+useQuery(eden.users.get.queryOptions(undefined, {
+  onError: (error: EdenFetchError) => {
+    // error.status and error.value are available
+    // extra context is attached: error.queryKey, error.method, error.path, error.input
+    if (error.status === 401) {
+      router.push('/login')
+    }
+  }
+}))
+```
+
+### 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
+  }
+})
+```
+
+## Advanced Usage
+
+### 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' }
+    },
+    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']
+
+// Nested paths
+ eden.users.posts({ userId: '123' }).get.queryKey()
+// → ['users', 'posts', { userId: '123' }, 'get']
+```
+
+## 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.ts

@@ -0,0 +1,59 @@
+import { QueryFilters, QueryKey, QueryObserverOptions, QueryFunctionContext, MutationOptions, InfiniteQueryObserverOptions } from '@tanstack/query-core';
+import { EdenFetchError } from '@elysiajs/eden';
+import { Elysia } from 'elysia';
+import { Treaty } from '@elysiajs/eden/treaty2';
+export { Treaty, treaty } from '@elysiajs/eden/treaty2';
+
+type HTTPMethod = 'get' | 'post' | 'put' | 'patch' | 'delete' | 'head' | 'options';
+interface EdenThrowOnErrorContext {
+    queryKey: readonly unknown[];
+    status: number;
+    method: HTTPMethod;
+    path: string[];
+    input: unknown;
+}
+type EdenThrowOnError = ((queryKey: readonly unknown[], status: number) => boolean) | ((context: EdenThrowOnErrorContext) => boolean);
+interface EdenQueryConfig {
+    throwOnError?: boolean | EdenThrowOnError;
+    queryKeyPrefix?: string | string[];
+}
+interface EdenOptions<TEden = unknown> {
+    eden?: TEden;
+}
+type EdenQueryKey<TInput = unknown, TMethod extends HTTPMethod = HTTPMethod> = readonly [...string[], TInput, TMethod];
+type EdenQueryOptions<TQueryFnData, TError = Error, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TEden = unknown> = Omit<QueryObserverOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>, 'queryKey' | 'queryFn'> & EdenOptions<TEden>;
+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;
+type AwaitedReturn<T> = T extends (...args: any[]) => infer R ? Awaited<R> : never;
+type FirstArg<T> = T extends (arg1: infer A, ...args: any[]) => any ? A : never;
+type SecondArg<T> = T extends (arg1: any, arg2: infer B, ...args: any[]) => any ? B : never;
+type EdenData<T> = Extract<AwaitedReturn<T>, {
+    error: null;
+}> extends {
+    data: infer D;
+} ? D : never;
+type EdenQueryMethod<TMethod extends Extract<HTTPMethod, 'get' | 'head'>, TCall extends (...args: any[]) => Promise<any>> = TCall & {
+    queryKey: (input?: FirstArg<TCall>) => EdenQueryKey<FirstArg<TCall>, TMethod>;
+    queryFilter: (input?: FirstArg<TCall>) => QueryFilters<EdenQueryKey<FirstArg<TCall>, TMethod>>;
+    queryOptions: (input?: FirstArg<TCall>, options?: EdenQueryOptions<EdenData<TCall>, EdenFetchError | Error, EdenData<TCall>, EdenQueryKey<FirstArg<TCall>, TMethod>, EdenPartial<NonNullable<FirstArg<TCall>>>>) => EdenQueryOptions<EdenData<TCall>, EdenFetchError | Error, EdenData<TCall>, EdenQueryKey<FirstArg<TCall>, TMethod>, EdenPartial<NonNullable<FirstArg<TCall>>>> & {
+        queryKey: EdenQueryKey<FirstArg<TCall>, TMethod>;
+        queryFn: (context: QueryFunctionContext<EdenQueryKey<FirstArg<TCall>, TMethod>>) => Promise<EdenData<TCall>>;
+    };
+};
+type EdenMutationMethod<TMethod extends Extract<HTTPMethod, 'post' | 'put' | 'patch' | 'delete'>, TCall extends (...args: any[]) => Promise<any>> = TCall & {
+    mutationOptions: (options?: EdenMutationOptions<EdenData<TCall>, EdenFetchError | Error, FirstArg<TCall>, unknown, EdenPartial<NonNullable<SecondArg<TCall>>>>) => EdenMutationOptions<EdenData<TCall>, EdenFetchError | Error, FirstArg<TCall>, unknown, EdenPartial<NonNullable<SecondArg<TCall>>>> & {
+        mutationKey: EdenQueryKey<undefined, TMethod>;
+        mutationFn: (variables: FirstArg<TCall>) => Promise<EdenData<TCall>>;
+    };
+};
+type EdenQueryify<T> = (T extends (...args: infer A) => infer R ? (...args: A) => EdenQueryify<R> : unknown) & (T extends object ? {
+    [K in keyof T]: EdenQueryifyValue<K, T[K]>;
+} : unknown);
+type EdenQueryifyValue<K, V> = K extends 'get' | 'head' ? V extends (...args: any[]) => Promise<any> ? EdenQueryMethod<Extract<K, 'get' | 'head'>, V> : V : K extends 'post' | 'put' | 'patch' | 'delete' ? V extends (...args: any[]) => Promise<any> ? EdenMutationMethod<Extract<K, 'post' | 'put' | 'patch' | 'delete'>, V> : V : EdenQueryify<V>;
+
+declare function createEdenQuery<App extends Elysia<any, any, any, any, any, any, any>>(domain: string, options?: EdenQueryConfig & {
+    treaty?: Treaty.Config;
+}): EdenQueryify<Treaty.Create<App>>;
+
+export { type EdenInfiniteQueryOptions, type EdenMutationMethod, type EdenMutationOptions, type EdenOptions, type EdenQueryConfig, type EdenQueryKey, type EdenQueryMethod, type EdenQueryOptions, type EdenQueryify, type EdenThrowOnError, type EdenThrowOnErrorContext, type HTTPMethod, createEdenQuery };

package/dist/index.js

@@ -0,0 +1,196 @@
+// src/index.ts
+import { treaty } from "@elysiajs/eden/treaty2";
+
+// src/query-options.ts
+import { EdenFetchError } from "@elysiajs/eden";
+
+// src/query-key.ts
+function buildQueryKey(paths, input, method, prefix) {
+  if (prefix) {
+    return typeof prefix === "string" ? [prefix, ...paths, input, method] : [...prefix, ...paths, input, method];
+  }
+  return [...paths, input, method];
+}
+
+// src/query-options.ts
+function shouldThrowOnError(config, context) {
+  if (typeof config.throwOnError === "boolean") return config.throwOnError;
+  if (typeof config.throwOnError === "function") {
+    const fn = config.throwOnError;
+    return fn.length >= 2 ? fn(
+      context.queryKey,
+      context.status
+    ) : fn(context);
+  }
+  return true;
+}
+function toEdenFetchError(error, status) {
+  if (error instanceof EdenFetchError) return error;
+  if (error && typeof error === "object" && "value" in error) {
+    return new EdenFetchError(status, error.value);
+  }
+  return new EdenFetchError(status, error);
+}
+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 { eden: _eden, ...tanstackOptions } = options ?? {};
+    return {
+      ...tanstackOptions,
+      queryKey,
+      queryFn: async (_context) => {
+        const result = await treatyCall(finalInput);
+        if (result.error) {
+          const error = toEdenFetchError(result.error, result.status);
+          error.queryKey = queryKey;
+          error.method = method;
+          error.path = paths;
+          error.input = finalInput;
+          error.response = result.response;
+          error.headers = result.headers;
+          if (shouldThrowOnError(globalConfig, {
+            queryKey,
+            status: result.status,
+            method,
+            path: paths,
+            input: finalInput
+          })) {
+            throw error;
+          }
+          return null;
+        }
+        return result.data;
+      }
+    };
+  };
+}
+
+// src/mutation-options.ts
+import { EdenFetchError as EdenFetchError2 } from "@elysiajs/eden";
+function shouldThrowOnError2(config, context) {
+  if (typeof config.throwOnError === "boolean") return config.throwOnError;
+  if (typeof config.throwOnError === "function") {
+    const fn = config.throwOnError;
+    return fn.length >= 2 ? fn(
+      context.queryKey,
+      context.status
+    ) : fn(context);
+  }
+  return true;
+}
+function toEdenFetchError2(error, status) {
+  if (error instanceof EdenFetchError2) return error;
+  if (error && typeof error === "object" && "value" in error) {
+    return new EdenFetchError2(status, error.value);
+  }
+  return new EdenFetchError2(status, error);
+}
+function createMutationOptions(treatyCall, paths, method, globalConfig) {
+  return (options) => {
+    const eden = options?.eden;
+    const mutationKey = buildQueryKey(
+      paths,
+      void 0,
+      method,
+      globalConfig.queryKeyPrefix
+    );
+    const { eden: _eden, ...tanstackOptions } = options ?? {};
+    return {
+      ...tanstackOptions,
+      mutationKey,
+      mutationFn: async (variables) => {
+        const result = await treatyCall(variables, eden);
+        if (result.error) {
+          const error = toEdenFetchError2(result.error, result.status);
+          error.queryKey = mutationKey;
+          error.method = method;
+          error.path = paths;
+          error.input = variables;
+          error.response = result.response;
+          error.headers = result.headers;
+          if (shouldThrowOnError2(globalConfig, {
+            queryKey: mutationKey,
+            status: result.status,
+            method,
+            path: paths,
+            input: variables
+          })) {
+            throw error;
+          }
+          return null;
+        }
+        return result.data;
+      }
+    };
+  };
+}
+
+// src/query-key-helpers.ts
+function createQueryKeyGetter(paths, method, prefix) {
+  return (input) => buildQueryKey(paths, input, method, prefix);
+}
+function createQueryFilter(paths, method, prefix) {
+  return (input) => ({
+    queryKey: buildQueryKey(paths, input, method, prefix),
+    exact: true
+  });
+}
+
+// src/proxy.ts
+var HTTP_METHODS = ["get", "post", "put", "patch", "delete", "head", "options"];
+function extendProxy(proxy, paths, config) {
+  return new Proxy(proxy, {
+    get(target, prop) {
+      if (typeof prop === "symbol") return target[prop];
+      const value = target[prop];
+      if (typeof value === "function" && HTTP_METHODS.includes(prop)) {
+        const httpMethod = prop;
+        const callable = (...args) => value(...args);
+        return Object.assign(callable, {
+          ...httpMethod === "get" || httpMethod === "head" ? {
+            queryOptions: createQueryOptions(
+              callable,
+              paths,
+              httpMethod,
+              config
+            ),
+            queryKey: createQueryKeyGetter(paths, httpMethod, config.queryKeyPrefix),
+            queryFilter: createQueryFilter(paths, httpMethod, config.queryKeyPrefix)
+          } : {},
+          ...httpMethod === "post" || httpMethod === "put" || httpMethod === "patch" || httpMethod === "delete" ? {
+            mutationOptions: createMutationOptions(
+              callable,
+              paths,
+              httpMethod,
+              config
+            )
+          } : {}
+        });
+      }
+      if (value !== null && (typeof value === "object" || typeof value === "function")) {
+        return extendProxy(value, [...paths, prop], config);
+      }
+      return value;
+    }
+  });
+}
+
+// src/index.ts
+import { treaty as treaty2 } from "@elysiajs/eden/treaty2";
+function createEdenQuery(domain, options) {
+  const treatyInstance = treaty(domain, options?.treaty);
+  return extendProxy(
+    treatyInstance,
+    [],
+    {
+      throwOnError: options?.throwOnError ?? true,
+      queryKeyPrefix: options?.queryKeyPrefix
+    }
+  );
+}
+export {
+  createEdenQuery,
+  treaty2 as treaty
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "eden-tanstack-query",
+  "version": "0.0.1",
+  "description": "TanStack Query integration for Eden Treaty",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@elysiajs/eden": ">=1.0.0",
+    "@tanstack/query-core": "^5.0.0"
+  },
+  "devDependencies": {
+    "@elysiajs/eden": "file:../..",
+    "@tanstack/react-query": "^5.0.0",
+    "@tanstack/svelte-query": "^5.0.0",
+    "bun-types": "latest",
+    "typescript": "^5.0.0"
+  },
+  "keywords": [
+    "elysia",
+    "eden",
+    "tanstack",
+    "query",
+    "react-query",
+    "svelte-query",
+    "typescript"
+  ]
+}