@modelence/react-query 1.0.0

package/README.md

@@ -0,0 +1,214 @@
+# @modelence/react-query
+
+React Query utilities for Modelence method calls.
+
+## Installation
+
+```bash
+npm i @modelence/react-query @tanstack/react-query
+```
+
+## Overview
+
+This package provides `getQueryOptions` and `getMutationOptions` factory functions that can be used with TanStack Query's native `useQuery` and `useMutation` hooks. This approach, recommended by TanStack, gives you direct access to TanStack Query's full API while providing Modelence-specific query configurations.
+
+## Usage
+
+### Basic Query
+
+```tsx
+import { useQuery } from '@tanstack/react-query';
+import { getQueryOptions } from '@modelence/react-query';
+
+function TodoList() {
+  const { data, isPending, error } = useQuery(
+    getQueryOptions('todo.getAll', { limit: 10 })
+  );
+  
+  if (isPending) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  
+  return (
+    <div>
+      {data?.map(todo => (
+        <div key={todo.id}>{todo.title}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Basic Mutation
+
+```tsx
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { getMutationOptions } from '@modelence/react-query';
+
+function CreateTodo() {
+  const queryClient = useQueryClient();
+  
+  const { mutate: createTodo, isPending } = useMutation({
+    ...getMutationOptions('todo.create'),
+    onSuccess: () => {
+      // Invalidate and refetch todos
+      queryClient.invalidateQueries({ queryKey: ['todo.getAll'] });
+    },
+  });
+  
+  return (
+    <button 
+      onClick={() => createTodo({ title: 'New Todo', completed: false })}
+      disabled={isPending}
+    >
+      {isPending ? 'Creating...' : 'Create Todo'}
+    </button>
+  );
+}
+```
+
+### Advanced Usage
+
+#### Query with Additional Options
+
+```tsx
+import { useQuery } from '@tanstack/react-query';
+import { getQueryOptions } from '@modelence/react-query';
+
+function TodoDetail({ id }: { id: string }) {
+  const { data: todo } = useQuery({
+    ...getQueryOptions('todo.getById', { id }),
+    enabled: !!id, // Only run query if id exists
+    staleTime: 5 * 60 * 1000, // 5 minutes
+    refetchOnWindowFocus: false,
+  });
+  
+  return <div>{todo?.title}</div>;
+}
+```
+
+#### Mutation with Default Args
+
+```tsx
+import { useMutation } from '@tanstack/react-query';
+import { getMutationOptions } from '@modelence/react-query';
+
+function UpdateTodo({ todoId }: { todoId: string }) {
+  const { mutate: updateTodo } = useMutation({
+    ...getMutationOptions('todo.update', { id: todoId }), // Default args
+    onSuccess: (data) => {
+      console.log('Todo updated:', data);
+    },
+  });
+  
+  return (
+    <button onClick={() => updateTodo({ title: 'Updated Title' })}>
+      Update Todo
+    </button>
+  );
+}
+```
+
+#### Manual Cache Operations
+
+```tsx
+import { useQueryClient } from '@tanstack/react-query';
+import { createQueryKey, getQueryOptions } from '@modelence/react-query';
+
+function TodoActions() {
+  const queryClient = useQueryClient();
+  
+  const refreshTodos = () => {
+    queryClient.invalidateQueries({ 
+      queryKey: createQueryKey('todo.getAll', { limit: 10 }) 
+    });
+  };
+  
+  const prefetchTodo = (id: string) => {
+    queryClient.prefetchQuery({
+      ...getQueryOptions('todo.getById', { id }),
+      staleTime: 10 * 60 * 1000, // 10 minutes
+    });
+  };
+  
+  return (
+    <div>
+      <button onClick={refreshTodos}>Refresh Todos</button>
+      <button onClick={() => prefetchTodo('123')}>Prefetch Todo</button>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### `getQueryOptions<T>(methodName, args?)`
+
+Creates a query configuration object for use with TanStack Query's `useQuery`.
+
+**Parameters:**
+- `methodName` (string): The Modelence method name (e.g., 'todo.getAll')
+- `args` (object, optional): Arguments to pass to the method
+
+**Returns:** Query configuration object with `queryKey` and `queryFn`
+
+### `getMutationOptions<T, TVariables>(methodName, defaultArgs?)`
+
+Creates a mutation configuration object for use with TanStack Query's `useMutation`.
+
+**Parameters:**
+- `methodName` (string): The Modelence method name (e.g., 'todo.create')
+- `defaultArgs` (object, optional): Default arguments merged with mutation variables
+
+**Returns:** Mutation configuration object with `mutationFn`
+
+### `createQueryKey<T, U>(methodName, args?)`
+
+Utility function to create typed query keys for manual cache operations.
+
+**Parameters:**
+- `methodName` (T): The method name
+- `args` (U, optional): The arguments
+
+**Returns:** Typed query key array
+
+## Migration from Modelence's useQuery/useMutation
+
+### Before
+
+```tsx
+import { useQuery, useMutation } from 'modelence/client';
+
+function TodoComponent() {
+  const { data, isFetching, error } = useQuery('todo.getAll');
+  const { mutate: createTodo } = useMutation('todo.create');
+  
+  // ...
+}
+```
+
+### After
+
+```tsx
+import { useQuery, useMutation } from '@tanstack/react-query';
+import { getQueryOptions, getMutationOptions } from '@modelence/react-query';
+
+function TodoComponent() {
+  const { data, isPending: isFetching, error } = useQuery(
+    getQueryOptions('todo.getAll')
+  );
+  const { mutate: createTodo } = useMutation(
+    getMutationOptions('todo.create')
+  );
+  
+  // ...
+}
+```
+
+## Benefits
+
+1. **Full TanStack Query API**: Access to all TanStack Query features and options
+2. **Simple and Explicit**: Clear separation between Modelence configuration and TanStack Query options
+3. **Better TypeScript Support**: Improved type inference and safety
+4. **Familiar API**: Standard TanStack Query patterns that developers already know
+5. **Future-Proof**: Easy to adopt new TanStack Query features as they're released
+6. **Composability**: Easy to combine with other TanStack Query utilities

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+type Args = Record<string, unknown>;
+/**
+ * Creates query options for use with TanStack Query's useQuery hook.
+ *
+ * @typeParam T - The expected return type of the query
+ * @param methodName - The name of the method to query
+ * @param args - Optional arguments to pass to the method
+ * @returns Query options object for TanStack Query's useQuery
+ *
+ * @example
+ * ```tsx
+ * import { useQuery } from '@tanstack/react-query';
+ * import { modelenceQuery } from '@modelence/react-query';
+ *
+ * function MyComponent() {
+ *   // Basic usage
+ *   const { data } = useQuery(modelenceQuery('todo.getAll'));
+ *
+ *   // With additional options
+ *   const { data: todo } = useQuery({
+ *     ...modelenceQuery('todo.getById', { id: '123' }),
+ *     enabled: !!id,
+ *     staleTime: 5 * 60 * 1000,
+ *   });
+ *
+ *   return <div>{data?.name}</div>;
+ * }
+ * ```
+ */
+declare function modelenceQuery<T = unknown>(methodName: string, args?: Args): {
+    queryKey: (string | Args)[];
+    queryFn: () => Promise<T>;
+};
+/**
+ * Creates mutation options for use with TanStack Query's useMutation hook.
+ *
+ * @typeParam T - The expected return type of the mutation
+ * @param methodName - The name of the method to mutate
+ * @param defaultArgs - Optional default arguments to merge with mutation variables
+ * @returns Mutation options object for TanStack Query's useMutation
+ *
+ * @example
+ * ```tsx
+ * import { useMutation, useQueryClient } from '@tanstack/react-query';
+ * import { modelenceMutation } from '@modelence/react-query';
+ *
+ * function MyComponent() {
+ *   const queryClient = useQueryClient();
+ *
+ *   // Basic usage
+ *   const { mutate } = useMutation(modelenceMutation('todos.create'));
+ *
+ *   // With additional options
+ *   const { mutate: updateTodo } = useMutation({
+ *     ...modelenceMutation('todos.update'),
+ *     onSuccess: () => {
+ *       queryClient.invalidateQueries({ queryKey: ['todos.getAll'] });
+ *     },
+ *   });
+ *
+ *   return <button onClick={() => mutate({ title: 'New Todo' })}>Create</button>;
+ * }
+ * ```
+ */
+declare function modelenceMutation<T = unknown>(methodName: string, defaultArgs?: Args): {
+    mutationFn: (variables?: Args) => Promise<T>;
+};
+/**
+ * Type helper for creating properly typed query keys
+ */
+type ModelenceQueryKey<T extends string, U extends Args = Args> = readonly [T, U];
+/**
+ * Utility function to create query keys for manual cache operations
+ *
+ * @param methodName - The method name
+ * @param args - The arguments
+ * @returns Typed query key
+ *
+ * @example
+ * ```tsx
+ * import { useQueryClient } from '@tanstack/react-query';
+ * import { createQueryKey } from '@modelence/react-query';
+ *
+ * function TodoActions() {
+ *   const queryClient = useQueryClient();
+ *
+ *   const refreshTodos = () => {
+ *     queryClient.invalidateQueries({
+ *       queryKey: createQueryKey('todo.getAll', { limit: 10 })
+ *     });
+ *   };
+ * }
+ * ```
+ */
+declare function createQueryKey<T extends string, U extends Args = Args>(methodName: T, args?: U): ModelenceQueryKey<T, U>;
+
+export { type ModelenceQueryKey, createQueryKey, modelenceMutation, modelenceQuery };

package/dist/index.js

@@ -0,0 +1,2 @@
+import {callMethod}from'modelence/client';function s(e,n={}){return {queryKey:[e,n],queryFn:()=>callMethod(e,n)}}function u(e,n={}){return {mutationFn:(t={})=>callMethod(e,{...n,...t})}}function y(e,n={}){return [e,n]}export{y as createQueryKey,u as modelenceMutation,s as modelenceQuery};//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["modelenceQuery","methodName","args","callMethod","modelenceMutation","defaultArgs","variables","createQueryKey"],"mappings":"0CAgCO,SAASA,CACdC,CAAAA,CAAAA,CACAC,CAAa,CAAA,EACb,CAAA,CACA,OAAO,CACL,QAAU,CAAA,CAACD,CAAYC,CAAAA,CAAI,CAC3B,CAAA,OAAA,CAAS,IAAMC,UAAAA,CAAcF,CAAYC,CAAAA,CAAI,CAC/C,CACF,CAiCO,SAASE,CACdH,CAAAA,CAAAA,CACAI,CAAoB,CAAA,EACpB,CAAA,CACA,OAAO,CACL,UAAY,CAAA,CAACC,CAAkB,CAAA,EAAOH,GAAAA,UAAAA,CAAcF,CAAY,CAAA,CAAE,GAAGI,CAAAA,CAAa,GAAGC,CAAU,CAAC,CAClG,CACF,CA8BO,SAASC,CAAAA,CACdN,CACAC,CAAAA,CAAAA,CAAU,EAAC,CACc,CACzB,OAAO,CAACD,CAAAA,CAAYC,CAAI,CAC1B","file":"index.js","sourcesContent":["import { callMethod } from 'modelence/client';\n\ntype Args = Record<string, unknown>;\n\n/**\n * Creates query options for use with TanStack Query's useQuery hook.\n * \n * @typeParam T - The expected return type of the query\n * @param methodName - The name of the method to query\n * @param args - Optional arguments to pass to the method\n * @returns Query options object for TanStack Query's useQuery\n * \n * @example\n * ```tsx\n * import { useQuery } from '@tanstack/react-query';\n * import { modelenceQuery } from '@modelence/react-query';\n * \n * function MyComponent() {\n *   // Basic usage\n *   const { data } = useQuery(modelenceQuery('todo.getAll'));\n * \n *   // With additional options\n *   const { data: todo } = useQuery({\n *     ...modelenceQuery('todo.getById', { id: '123' }),\n *     enabled: !!id,\n *     staleTime: 5 * 60 * 1000,\n *   });\n * \n *   return <div>{data?.name}</div>;\n * }\n * ```\n */\nexport function modelenceQuery<T = unknown>(\n  methodName: string, \n  args: Args = {}\n) {\n  return {\n    queryKey: [methodName, args],\n    queryFn: () => callMethod<T>(methodName, args),\n  };\n}\n\n/**\n * Creates mutation options for use with TanStack Query's useMutation hook.\n * \n * @typeParam T - The expected return type of the mutation\n * @param methodName - The name of the method to mutate\n * @param defaultArgs - Optional default arguments to merge with mutation variables\n * @returns Mutation options object for TanStack Query's useMutation\n * \n * @example\n * ```tsx\n * import { useMutation, useQueryClient } from '@tanstack/react-query';\n * import { modelenceMutation } from '@modelence/react-query';\n * \n * function MyComponent() {\n *   const queryClient = useQueryClient();\n *   \n *   // Basic usage\n *   const { mutate } = useMutation(modelenceMutation('todos.create'));\n * \n *   // With additional options\n *   const { mutate: updateTodo } = useMutation({\n *     ...modelenceMutation('todos.update'),\n *     onSuccess: () => {\n *       queryClient.invalidateQueries({ queryKey: ['todos.getAll'] });\n *     },\n *   });\n * \n *   return <button onClick={() => mutate({ title: 'New Todo' })}>Create</button>;\n * }\n * ```\n */\nexport function modelenceMutation<T = unknown>(\n  methodName: string, \n  defaultArgs: Args = {}\n) {\n  return {\n    mutationFn: (variables: Args = {}) => callMethod<T>(methodName, { ...defaultArgs, ...variables }),\n  };\n}\n\n/**\n * Type helper for creating properly typed query keys\n */\nexport type ModelenceQueryKey<T extends string, U extends Args = Args> = readonly [T, U];\n\n/**\n * Utility function to create query keys for manual cache operations\n * \n * @param methodName - The method name\n * @param args - The arguments\n * @returns Typed query key\n * \n * @example\n * ```tsx\n * import { useQueryClient } from '@tanstack/react-query';\n * import { createQueryKey } from '@modelence/react-query';\n * \n * function TodoActions() {\n *   const queryClient = useQueryClient();\n *   \n *   const refreshTodos = () => {\n *     queryClient.invalidateQueries({ \n *       queryKey: createQueryKey('todo.getAll', { limit: 10 }) \n *     });\n *   };\n * }\n * ```\n */\nexport function createQueryKey<T extends string, U extends Args = Args>(\n  methodName: T,\n  args: U = {} as U\n): ModelenceQueryKey<T, U> {\n  return [methodName, args] as const;\n}\n"]}

package/examples/usage.tsx

@@ -0,0 +1,249 @@
+import React from 'react';
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { getQueryOptions, getMutationOptions, createQueryKey } from '@modelence/react-query';
+
+interface Todo {
+  id: string;
+  title: string;
+  completed: boolean;
+}
+
+// Example 1: Basic query usage
+function TodoList() {
+  const { data: todos, isPending, error } = useQuery<Todo[]>(
+    getQueryOptions('todo.getAll', { limit: 10 })
+  );
+
+  if (isPending) return <div>Loading todos...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      <h2>Todos</h2>
+      {todos?.map((todo) => (
+        <div key={todo.id}>
+          <h3>{todo.title}</h3>
+          <p>{todo.completed ? '✅' : '⏳'}</p>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+// Example 2: Query with options and enabled condition
+function TodoDetail({ todoId }: { todoId: string | null }) {
+  const { data: todo, isPending } = useQuery<Todo>({
+    ...getQueryOptions('todo.getById', { id: todoId }),
+    enabled: !!todoId, // Only run when todoId exists
+    staleTime: 5 * 60 * 1000, // 5 minutes
+    retry: 3,
+  });
+
+  if (!todoId) return <div>Select a todo</div>;
+  if (isPending) return <div>Loading todo...</div>;
+
+  return (
+    <div>
+      <h3>{todo?.title}</h3>
+      <p>Status: {todo?.completed ? 'Completed' : 'Pending'}</p>
+    </div>
+  );
+}
+
+// Example 3: Basic mutation
+function CreateTodo() {
+  const queryClient = useQueryClient();
+
+  const { mutate: createTodo, isPending, error } = useMutation<Todo, Error, { title: string; completed: boolean }>({
+    ...getMutationOptions('todo.create'),
+    onSuccess: () => {
+      // Invalidate and refetch all todo queries
+      queryClient.invalidateQueries({ queryKey: ['todo.getAll'] });
+    },
+    onError: (error) => {
+      console.error('Failed to create todo:', error);
+    },
+  });
+
+  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const title = formData.get('title') as string;
+    
+    createTodo({ title, completed: false });
+    e.currentTarget.reset();
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input 
+        name="title" 
+        placeholder="Enter todo title" 
+        required 
+        disabled={isPending}
+      />
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Creating...' : 'Create Todo'}
+      </button>
+      {error && <p style={{ color: 'red' }}>Error: {error.message}</p>}
+    </form>
+  );
+}
+
+// Example 4: Mutation with default args
+function UpdateTodo({ todoId }: { todoId: string }) {
+  const queryClient = useQueryClient();
+
+  const { mutate: updateTodo, isPending } = useMutation<Todo, Error, { completed: boolean }>({
+    ...getMutationOptions('todo.update', { id: todoId }), // Default id
+    onSuccess: () => {
+      // Invalidate specific todo and list
+      queryClient.invalidateQueries({ queryKey: ['todo.getById'] });
+      queryClient.invalidateQueries({ queryKey: ['todo.getAll'] });
+    },
+  });
+
+  const toggleComplete = () => {
+    // The id is already provided in defaultArgs, so we only need the fields to update
+    updateTodo({ completed: true });
+  };
+
+  return (
+    <button onClick={toggleComplete} disabled={isPending}>
+      {isPending ? 'Updating...' : 'Mark Complete'}
+    </button>
+  );
+}
+
+// Example 5: Manual cache operations
+function TodoActions() {
+  const queryClient = useQueryClient();
+
+  const refreshTodos = () => {
+    queryClient.invalidateQueries({ 
+      queryKey: createQueryKey('todo.getAll', { limit: 10 }) 
+    });
+  };
+
+  const prefetchTodo = (id: string) => {
+    queryClient.prefetchQuery<Todo>({
+      ...getQueryOptions('todo.getById', { id }),
+      staleTime: 10 * 60 * 1000, // 10 minutes
+    });
+  };
+
+  const setTodoData = (id: string, todo: Todo) => {
+    queryClient.setQueryData(
+      createQueryKey('todo.getById', { id }),
+      todo
+    );
+  };
+
+  return (
+    <div>
+      <button onClick={refreshTodos}>Refresh Todos</button>
+      <button onClick={() => prefetchTodo('123')}>Prefetch Todo 123</button>
+      <button onClick={() => setTodoData('123', { id: '123', title: 'Test', completed: false })}>
+        Set Todo Data
+      </button>
+    </div>
+  );
+}
+
+// Example 6: Advanced usage with optimistic updates
+function OptimisticTodo({ todoId }: { todoId: string }) {
+  const queryClient = useQueryClient();
+
+  const { mutate: updateTodo } = useMutation<
+    Todo, 
+    Error, 
+    { id: string; completed: boolean },
+    { previousTodo: Todo | undefined }
+  >({
+    ...getMutationOptions('todo.update'),
+    onMutate: async (variables) => {
+      // Cancel outgoing refetches (so they don't overwrite our optimistic update)
+      await queryClient.cancelQueries({ 
+        queryKey: createQueryKey('todo.getById', { id: todoId })
+      });
+
+      // Snapshot the previous value
+      const previousTodo = queryClient.getQueryData<Todo>(
+        createQueryKey('todo.getById', { id: todoId })
+      );
+
+      // Optimistically update to the new value
+      queryClient.setQueryData(
+        createQueryKey('todo.getById', { id: todoId }),
+        (old: Todo | undefined) => old ? { ...old, ...variables } : undefined
+      );
+
+      // Return a context object with the snapshotted value
+      return { previousTodo };
+    },
+    onError: (_err, _variables, context) => {
+      // If the mutation fails, use the context to roll back
+      if (context?.previousTodo) {
+        queryClient.setQueryData(
+          createQueryKey('todo.getById', { id: todoId }),
+          context.previousTodo
+        );
+      }
+    },
+    onSettled: () => {
+      // Always refetch after error or success
+      queryClient.invalidateQueries({ 
+        queryKey: createQueryKey('todo.getById', { id: todoId })
+      });
+    },
+  });
+
+  return (
+    <button onClick={() => updateTodo({ id: todoId, completed: true })}>
+      Update with Optimistic UI
+    </button>
+  );
+}
+
+// Main app component showcasing all examples
+export default function App() {
+  const [selectedTodoId, setSelectedTodoId] = React.useState<string | null>(null);
+
+  return (
+    <div style={{ padding: '20px', maxWidth: '800px', margin: '0 auto' }}>
+      <h1>@modelence/react-query Examples</h1>
+      
+      <section>
+        <h2>Create Todo</h2>
+        <CreateTodo />
+      </section>
+
+      <section>
+        <h2>Todo List</h2>
+        <TodoList />
+      </section>
+
+      <section>
+        <h2>Todo Detail</h2>
+        <input 
+          placeholder="Enter todo ID" 
+          onChange={(e) => setSelectedTodoId(e.target.value || null)}
+        />
+        <TodoDetail todoId={selectedTodoId} />
+      </section>
+
+      {selectedTodoId && (
+        <section>
+          <h2>Todo Actions</h2>
+          <UpdateTodo todoId={selectedTodoId} />
+          <OptimisticTodo todoId={selectedTodoId} />
+        </section>
+      )}
+
+      <section>
+        <h2>Cache Actions</h2>
+        <TodoActions />
+      </section>
+    </div>
+  );
+} 

package/package.json

@@ -0,0 +1,35 @@
+{
+  "type": "module",
+  "name": "@modelence/react-query",
+  "version": "1.0.0",
+  "description": "React Query utilities for Modelence",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "author": "Modelence",
+  "license": "SEE LICENSE IN LICENSE",
+  "peerDependencies": {
+    "@tanstack/react-query": ">=5.0.0",
+    "react": ">=18.0.0"
+  },
+  "dependencies": {
+    "modelence": "^0.5.0"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.76.2",
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.2"
+  }
+}

package/src/index.ts

@@ -0,0 +1,116 @@
+import { callMethod } from 'modelence/client';
+
+type Args = Record<string, unknown>;
+
+/**
+ * Creates query options for use with TanStack Query's useQuery hook.
+ * 
+ * @typeParam T - The expected return type of the query
+ * @param methodName - The name of the method to query
+ * @param args - Optional arguments to pass to the method
+ * @returns Query options object for TanStack Query's useQuery
+ * 
+ * @example
+ * ```tsx
+ * import { useQuery } from '@tanstack/react-query';
+ * import { modelenceQuery } from '@modelence/react-query';
+ * 
+ * function MyComponent() {
+ *   // Basic usage
+ *   const { data } = useQuery(modelenceQuery('todo.getAll'));
+ * 
+ *   // With additional options
+ *   const { data: todo } = useQuery({
+ *     ...modelenceQuery('todo.getById', { id: '123' }),
+ *     enabled: !!id,
+ *     staleTime: 5 * 60 * 1000,
+ *   });
+ * 
+ *   return <div>{data?.name}</div>;
+ * }
+ * ```
+ */
+export function modelenceQuery<T = unknown>(
+  methodName: string, 
+  args: Args = {}
+) {
+  return {
+    queryKey: [methodName, args],
+    queryFn: () => callMethod<T>(methodName, args),
+  };
+}
+
+/**
+ * Creates mutation options for use with TanStack Query's useMutation hook.
+ * 
+ * @typeParam T - The expected return type of the mutation
+ * @param methodName - The name of the method to mutate
+ * @param defaultArgs - Optional default arguments to merge with mutation variables
+ * @returns Mutation options object for TanStack Query's useMutation
+ * 
+ * @example
+ * ```tsx
+ * import { useMutation, useQueryClient } from '@tanstack/react-query';
+ * import { modelenceMutation } from '@modelence/react-query';
+ * 
+ * function MyComponent() {
+ *   const queryClient = useQueryClient();
+ *   
+ *   // Basic usage
+ *   const { mutate } = useMutation(modelenceMutation('todos.create'));
+ * 
+ *   // With additional options
+ *   const { mutate: updateTodo } = useMutation({
+ *     ...modelenceMutation('todos.update'),
+ *     onSuccess: () => {
+ *       queryClient.invalidateQueries({ queryKey: ['todos.getAll'] });
+ *     },
+ *   });
+ * 
+ *   return <button onClick={() => mutate({ title: 'New Todo' })}>Create</button>;
+ * }
+ * ```
+ */
+export function modelenceMutation<T = unknown>(
+  methodName: string, 
+  defaultArgs: Args = {}
+) {
+  return {
+    mutationFn: (variables: Args = {}) => callMethod<T>(methodName, { ...defaultArgs, ...variables }),
+  };
+}
+
+/**
+ * Type helper for creating properly typed query keys
+ */
+export type ModelenceQueryKey<T extends string, U extends Args = Args> = readonly [T, U];
+
+/**
+ * Utility function to create query keys for manual cache operations
+ * 
+ * @param methodName - The method name
+ * @param args - The arguments
+ * @returns Typed query key
+ * 
+ * @example
+ * ```tsx
+ * import { useQueryClient } from '@tanstack/react-query';
+ * import { createQueryKey } from '@modelence/react-query';
+ * 
+ * function TodoActions() {
+ *   const queryClient = useQueryClient();
+ *   
+ *   const refreshTodos = () => {
+ *     queryClient.invalidateQueries({ 
+ *       queryKey: createQueryKey('todo.getAll', { limit: 10 }) 
+ *     });
+ *   };
+ * }
+ * ```
+ */
+export function createQueryKey<T extends string, U extends Args = Args>(
+  methodName: T,
+  args: U = {} as U
+): ModelenceQueryKey<T, U> {
+  return [methodName, args] as const;
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "allowJs": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "dist",
+    "jsx": "react-jsx"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+} 

package/tsup.config.ts

@@ -0,0 +1,28 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig((options) => ({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  dts: {
+    resolve: true,
+    entry: {
+      index: 'src/index.ts'
+    }
+  },
+  splitting: true,
+  clean: true,
+  outDir: 'dist',
+  sourcemap: true,
+  minify: !options.watch,
+  treeshake: !options.watch,
+  jsx: true,
+  esbuildOptions: (options) => {
+    options.resolveExtensions = ['.ts', '.js', '.tsx', '.jsx']
+    return options
+  },
+  external: [
+    'react',
+    '@tanstack/react-query',
+    'modelence'
+  ]
+}));