qortex-react 0.3.2 → 0.3.4

package/index.d.ts

@@ -99,4 +99,148 @@ declare function useQuerySelect<F extends Fetcher>(key: QueryKey, opts: QueryOpt
 }): QueryState<InferFetcherResult<F>>;
 declare function useQuerySelect<T = any>(key: QueryKey, opts?: QueryOptions<T>): QueryState<T>;
 
-export { useQuery, useQueryData, useQuerySelect };
+/** Internal: Generic mutation function type for inference */
+type MutationFn = (...args: any[]) => Promise<any>;
+/** Internal: Infers the return data type from a mutation function */
+type InferData<Fn extends MutationFn> = Awaited<ReturnType<Fn>>;
+/** Internal: Infers the arguments tuple type from a mutation function */
+type InferArgs<Fn extends MutationFn> = Parameters<Fn>;
+/** Internal: Options type for inferred overload (without mutationFn) */
+type OptionsInferred<Fn extends MutationFn, Err = Error> = {
+    onSuccess?: (data: InferData<Fn>, args: InferArgs<Fn>) => void;
+    onError?: (error: Err, args: InferArgs<Fn>) => void;
+    onSettled?: (data: InferData<Fn> | undefined, error: Err | undefined, args: InferArgs<Fn>) => void;
+    queryKey?: QueryKey;
+};
+/** Internal: Result type for inferred overload */
+type ResultInferred<Fn extends MutationFn, Err> = {
+    isPending: boolean;
+    error: Err | undefined;
+    data: InferData<Fn> | undefined;
+    mutate: (...args: InferArgs<Fn>) => void;
+    mutateAsync: (...args: InferArgs<Fn>) => Promise<InferData<Fn>>;
+    reset: () => void;
+};
+/**
+ * Optional configuration for the useMutate hook.
+ * Pass as the second argument after the mutation function.
+ *
+ * @template Data - The type of data returned by the mutation
+ * @template Err - The type of error that can be thrown (defaults to Error)
+ * @template Args - The tuple type of arguments passed to the mutation (defaults to [])
+ *
+ * @example
+ * ```tsx
+ * const options: UseMutateOptions<Todo, Error, [CreateInput]> = {
+ *   onSuccess: (data) => console.log(data.id),
+ *   queryKey: ['todos'],
+ * };
+ * ```
+ */
+type UseMutateOptions<Data = any, Err = Error, Args extends any[] = []> = {
+    /**
+     * Callback fired when the mutation succeeds.
+     * @param data - The data returned from the mutation
+     * @param args - The arguments that were passed to the mutation
+     */
+    onSuccess?: (data: Data, args: Args) => void;
+    /**
+     * Callback fired when the mutation fails.
+     * @param error - The error thrown by the mutation
+     * @param args - The arguments that were passed to the mutation
+     */
+    onError?: (error: Err, args: Args) => void;
+    /**
+     * Callback fired when the mutation completes (success or error).
+     * @param data - The data returned from the mutation (undefined if error)
+     * @param error - The error thrown by the mutation (undefined if success)
+     * @param args - The arguments that were passed to the mutation
+     */
+    onSettled?: (data: Data | undefined, error: Err | undefined, args: Args) => void;
+    /**
+     * Optional query key to invalidate after successful mutation.
+     * If provided, the query will be refetched after mutation completes.
+     */
+    queryKey?: QueryKey;
+};
+/**
+ * Return type for the useMutate hook.
+ *
+ * @template Data - The type of data returned by the mutation
+ * @template Err - The type of error that can be thrown
+ * @template Args - The tuple type of arguments passed to the mutation
+ *
+ * @example
+ * ```tsx
+ * const result: UseMutateResult<Todo, Error, [CreateInput]> = useMutate(createTodo);
+ * result.mutate({ title: 'New Todo' });
+ * ```
+ */
+type UseMutateResult<Data, Err, Args extends any[]> = {
+    /** Whether the mutation is currently in progress */
+    isPending: boolean;
+    /** The error thrown by the last mutation attempt, or undefined */
+    error: Err | undefined;
+    /** The data returned by the last successful mutation, or undefined */
+    data: Data | undefined;
+    /** Function to trigger the mutation */
+    mutate: (...args: Args) => void;
+    /** Function to trigger the mutation and return a promise */
+    mutateAsync: (...args: Args) => Promise<Data>;
+    /** Resets the mutation state to its initial values */
+    reset: () => void;
+};
+/**
+ * A hook for handling asynchronous mutations with loading, error, and success states.
+ *
+ * @param mutationFn - The async function that performs the mutation (required)
+ * @param options - Optional configuration (callbacks, queryKey to invalidate)
+ *
+ * Supports two usage patterns:
+ * 1. **Inferred types**: Let TypeScript infer types from mutationFn (recommended)
+ * 2. **Explicit generics**: Specify Data, Error, and Args types manually
+ *
+ * @example
+ * ```tsx
+ * // Simple usage - just pass the mutation function
+ * const { mutate, isPending } = useMutate(api.createTodo);
+ * mutate({ title: 'New Todo' });
+ *
+ * // With options - callbacks and query invalidation
+ * const { mutate, data } = useMutate(
+ *   async (newTodo: { title: string }) => {
+ *     const res = await fetch('/api/todos', {
+ *       method: 'POST',
+ *       body: JSON.stringify(newTodo),
+ *     });
+ *     return res.json() as Promise<{ id: string; title: string }>;
+ *   },
+ *   {
+ *     onSuccess: (data, [todo]) => console.log('Created:', data.id, todo.title),
+ *     onError: (error) => console.error('Failed:', error),
+ *     queryKey: ['todos'], // Invalidate todos query after mutation
+ *   }
+ * );
+ * mutate({ title: 'New Todo' });
+ *
+ * // Multiple arguments - all types inferred
+ * const { mutate: updateTodo } = useMutate(
+ *   async (id: string, title: string, completed: boolean) => {
+ *     return await api.updateTodo(id, { title, completed });
+ *   },
+ *   { onSuccess: (data, [id, title]) => console.log(`Updated ${id}: ${title}`) }
+ * );
+ * updateTodo('123', 'Updated Title', true);
+ *
+ * // Explicit generics - when you need to override inferred types
+ * type Todo = { id: string; title: string };
+ * const { mutate } = useMutate<Todo, Error, [{ title: string }]>(
+ *   async (input) => api.createTodo(input),
+ *   { onSuccess: (data) => console.log(data.id) }
+ * );
+ * ```
+ */
+declare function useMutate<Fn extends MutationFn, Err = Error>(mutationFn: Fn, options?: OptionsInferred<Fn, Err>): ResultInferred<Fn, Err>;
+declare function useMutate<Data, Err = Error, Args extends any[] = []>(mutationFn: (...args: Args) => Promise<Data>, options?: UseMutateOptions<Data, Err, Args>): UseMutateResult<Data, Err, Args>;
+
+export { UseMutateOptions, UseMutateResult, useMutate, useQuery, useQueryData, useQuerySelect };

package/index.js

@@ -3,11 +3,12 @@
 var qortexCore = require('qortex-core');
 var react = require('react');
 
-function P(e,t){let r=qortexCore.serializeKey(e),u=react.useCallback(()=>qortexCore.queryManager.getQueryState(e,t),[r]),n=react.useCallback(o=>qortexCore.queryManager.subscribeQuery(e,o,t),[r]);return react.useSyncExternalStore(n,u)}function L(e,t){let r=qortexCore.serializeKey(e),u=react.useCallback(()=>qortexCore.queryManager.getQueryData(e,t),[r]),n=react.useCallback(o=>qortexCore.queryManager.subscribeQuery(e,o,t),[r]);return react.useSyncExternalStore(n,u)}function $(e,t){let r=qortexCore.serializeKey(e),u=react.useRef(),n=react.useRef(new Set),a=react.useCallback(y=>qortexCore.queryManager.subscribeQuery(e,s=>{let x=u.current,i=n.current;if(i.size===0){u.current=s,y();return}let Q=!1;for(let f of i)if(x?.[f]!==s[f]){Q=!0;break}Q&&(u.current=s,y());},t),[r]),o=react.useCallback(()=>qortexCore.queryManager.getQueryState(e,t),[r]),c=react.useSyncExternalStore(a,o);return react.useMemo(()=>new Proxy(c,{get(y,s){return n.current.add(s),y[s]}}),[c])}
+function B(e,r){let t=qortexCore.serializeKey(e),n=react.useCallback(()=>qortexCore.queryManager.getQueryState(e,r),[t]),s=react.useCallback(o=>qortexCore.queryManager.subscribeQuery(e,o,r),[t]);return react.useSyncExternalStore(s,n)}function X(e,r){let t=qortexCore.serializeKey(e),n=react.useCallback(()=>qortexCore.queryManager.getQueryData(e,r),[t]),s=react.useCallback(o=>qortexCore.queryManager.subscribeQuery(e,o,r),[t]);return react.useSyncExternalStore(s,n)}function se(e,r){let t=qortexCore.serializeKey(e),n=react.useRef(),s=react.useRef(new Set),a=react.useCallback(y=>qortexCore.queryManager.subscribeQuery(e,u=>{let Q=n.current,f=s.current;if(f.size===0){n.current=u,y();return}let p=!1;for(let g of f)if(Q?.[g]!==u[g]){p=!0;break}p&&(n.current=u,y());},r),[t]),o=react.useCallback(()=>qortexCore.queryManager.getQueryState(e,r),[t]),i=react.useSyncExternalStore(a,o);return react.useMemo(()=>new Proxy(i,{get(y,u){return s.current.add(u),y[u]}}),[i])}function ye(e,r={}){let{onSuccess:t,onError:n,onSettled:s,queryKey:a}=r,[o,i]=react.useState(!1),[m,y]=react.useState(void 0),[u,Q]=react.useState(void 0),f=()=>{i(!1),y(void 0),Q(void 0);},p=async(...d)=>{f(),i(!0);try{let c=await e(...d);return Q(c),i(!1),t?.(c,d),s?.(c,void 0,d),a&&qortexCore.invalidateQuery(a),c}catch(c){let F=c;throw y(F),i(!1),n?.(F,d),s?.(void 0,F,d),a&&qortexCore.invalidateQuery(a),F}};return {isPending:o,error:m,data:u,mutate:(...d)=>{p(...d).catch(()=>{});},mutateAsync:p,reset:f}}
 
-exports.useQuery = P;
-exports.useQueryData = L;
-exports.useQuerySelect = $;
+exports.useMutate = ye;
+exports.useQuery = B;
+exports.useQueryData = X;
+exports.useQuerySelect = se;
 Object.keys(qortexCore).forEach(function (k) {
 	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
 		enumerable: true,

package/index.mjs

@@ -1,7 +1,7 @@
-import { serializeKey, queryManager } from 'qortex-core';
+import { serializeKey, queryManager, invalidateQuery } from 'qortex-core';
 export * from 'qortex-core';
-import { useCallback, useSyncExternalStore, useRef, useMemo } from 'react';
+import { useCallback, useSyncExternalStore, useRef, useMemo, useState } from 'react';
 
-function P(e,t){let r=serializeKey(e),u=useCallback(()=>queryManager.getQueryState(e,t),[r]),n=useCallback(o=>queryManager.subscribeQuery(e,o,t),[r]);return useSyncExternalStore(n,u)}function L(e,t){let r=serializeKey(e),u=useCallback(()=>queryManager.getQueryData(e,t),[r]),n=useCallback(o=>queryManager.subscribeQuery(e,o,t),[r]);return useSyncExternalStore(n,u)}function $(e,t){let r=serializeKey(e),u=useRef(),n=useRef(new Set),a=useCallback(y=>queryManager.subscribeQuery(e,s=>{let x=u.current,i=n.current;if(i.size===0){u.current=s,y();return}let Q=!1;for(let f of i)if(x?.[f]!==s[f]){Q=!0;break}Q&&(u.current=s,y());},t),[r]),o=useCallback(()=>queryManager.getQueryState(e,t),[r]),c=useSyncExternalStore(a,o);return useMemo(()=>new Proxy(c,{get(y,s){return n.current.add(s),y[s]}}),[c])}
+function B(e,r){let t=serializeKey(e),n=useCallback(()=>queryManager.getQueryState(e,r),[t]),s=useCallback(o=>queryManager.subscribeQuery(e,o,r),[t]);return useSyncExternalStore(s,n)}function X(e,r){let t=serializeKey(e),n=useCallback(()=>queryManager.getQueryData(e,r),[t]),s=useCallback(o=>queryManager.subscribeQuery(e,o,r),[t]);return useSyncExternalStore(s,n)}function se(e,r){let t=serializeKey(e),n=useRef(),s=useRef(new Set),a=useCallback(y=>queryManager.subscribeQuery(e,u=>{let Q=n.current,f=s.current;if(f.size===0){n.current=u,y();return}let p=!1;for(let g of f)if(Q?.[g]!==u[g]){p=!0;break}p&&(n.current=u,y());},r),[t]),o=useCallback(()=>queryManager.getQueryState(e,r),[t]),i=useSyncExternalStore(a,o);return useMemo(()=>new Proxy(i,{get(y,u){return s.current.add(u),y[u]}}),[i])}function ye(e,r={}){let{onSuccess:t,onError:n,onSettled:s,queryKey:a}=r,[o,i]=useState(!1),[m,y]=useState(void 0),[u,Q]=useState(void 0),f=()=>{i(!1),y(void 0),Q(void 0);},p=async(...d)=>{f(),i(!0);try{let c=await e(...d);return Q(c),i(!1),t?.(c,d),s?.(c,void 0,d),a&&invalidateQuery(a),c}catch(c){let F=c;throw y(F),i(!1),n?.(F,d),s?.(void 0,F,d),a&&invalidateQuery(a),F}};return {isPending:o,error:m,data:u,mutate:(...d)=>{p(...d).catch(()=>{});},mutateAsync:p,reset:f}}
 
-export { P as useQuery, L as useQueryData, $ as useQuerySelect };
+export { ye as useMutate, B as useQuery, X as useQueryData, se as useQuerySelect };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qortex-react",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "React hook bridge for qortex runtime",
   "main": "index.js",
   "module": "index.mjs",
@@ -50,7 +50,7 @@
   "author": "Darshan Naik",
   "license": "LGPL-3.0",
   "dependencies": {
-    "qortex-core": "0.3.2"
+    "qortex-core": "0.3.4"
   },
   "peerDependencies": {
     "react": ">=18"