@pixotope/query 0.5.0 → 0.7.0

package/src/factories.ts

@@ -11,7 +11,7 @@ export type MutationInfo<TData, TError, TParams> = {
 
 type FnToParamsBase = Record<string, MutationInfo<unknown, unknown, unknown>>;
 
-export type TPromiseFunction<TResponse, TParams> = (
+export type TPromiseFunction<TResponse, TParams, TExtraParams> = (
   args: Omit<
     ZMQClient.Call<
       TResponse,
@@ -22,7 +22,9 @@ export type TPromiseFunction<TResponse, TParams> = (
       }
     >,
     "id"
-  >
+  > & {
+    meta?: TExtraParams;
+  }
 ) => Promise<TResponse>;
 
 const useCallMutationBase = <
@@ -30,48 +32,53 @@ const useCallMutationBase = <
   TData = unknown,
   TError = unknown,
   TParams = unknown,
+  TMetadata = unknown,
 >(
-  promiseFunc: TPromiseFunction<TData, TParams>,
+  promiseFunc: TPromiseFunction<TData, TParams, TMetadata>,
   functionName: keyof TFnToParams,
-  service: string,
-  options?: Omit<MutationOptions<TData, TError, TParams>, "mutationFn"> & {
-    avoidTimeout?: boolean;
-    customTimeout?: number;
-  }
+  service: (meta?: TMetadata) => string,
+  options?: Omit<
+    MutationOptions<TData, TError, TParams, TMetadata>,
+    "mutationFn"
+  >
 ) => {
-  const {
-    avoidTimeout = true,
-    customTimeout = undefined,
-    ...rest
-  } = useMemo(() => options ?? {}, [options]);
+  const timeout = options?.timeout;
+  const { ...rest } = useMemo(() => options ?? {}, [options]);
   const mutationFn = useCallback(
-    async (parameters: TParams) => {
+    async (parameters: TParams, meta?: TMetadata) => {
       try {
         return await promiseFunc({
-          service,
+          service: service(meta),
           functionName: functionName.toString(),
           parameters,
           options: {
-            avoidTimeout,
-            customTimeout,
+            avoidTimeout: !timeout,
+            customTimeout: timeout,
           },
+          meta,
         });
-      } catch (e: any) {
-        throw e.message;
+      } catch (e) {
+        if (e instanceof Error) {
+          throw e;
+        }
+        throw new Error(e as string);
       }
     },
-    [avoidTimeout, customTimeout, functionName, service]
+    [functionName, service, timeout]
   );
 
-  return useMutation<TData, TError, TParams>({
+  return useMutation<TData, TError, TParams, TMetadata>({
     mutationFn,
     ...rest,
   });
 };
 
-export function buildMutationHook<TFnToParams extends FnToParamsBase>(
-  promiseFunc: TPromiseFunction<unknown, unknown>,
-  genTargetService: (machine: string | undefined) => string
+export function buildMutationHook<
+  TFnToParams extends FnToParamsBase,
+  TMetadata = unknown,
+>(
+  promiseFunc: TPromiseFunction<unknown, unknown, unknown>,
+  genTargetService: (meta?: TMetadata) => string
 ) {
   return function useCallMutationBuilder<TFn extends keyof TFnToParams>(
     func: TFn,
@@ -80,18 +87,18 @@ export function buildMutationHook<TFnToParams extends FnToParamsBase>(
         TFnToParams,
         TFnToParams[TFn]["data"],
         TFnToParams[TFn]["error"],
-        TFnToParams[TFn]["params"]
+        TFnToParams[TFn]["params"],
+        TMetadata
       >
-    >[3] & { machine?: string }
+    >[3]
   ) {
-    const targetService = genTargetService(options?.machine);
-
     return useCallMutationBase<
       TFnToParams,
       TFnToParams[TFn]["data"],
       TFnToParams[TFn]["error"],
-      TFnToParams[TFn]["params"]
-    >(promiseFunc, func, targetService, options);
+      TFnToParams[TFn]["params"],
+      TMetadata
+    >(promiseFunc, func, genTargetService, options);
   };
 }
 
@@ -101,32 +108,30 @@ const useCallQueryBase = <
   TError = unknown,
   TParams = unknown,
   TSelect = TData,
+  TMetadata = unknown,
 >(
-  promiseFunction: TPromiseFunction<TData, TParams>,
+  promiseFunction: TPromiseFunction<TData, TParams, TMetadata>,
   functionName: keyof TFnToParams,
   params: TParams,
-  service: string,
+  service: (meta?: TMetadata) => string,
   options?: Omit<QueryOptions<TData, TError, TParams, TSelect>, "queryFn"> & {
-    avoidTimeout?: boolean;
-    customTimeout?: number;
+    meta?: TMetadata;
   }
 ) => {
-  const {
-    avoidTimeout = true,
-    customTimeout = undefined,
-    ...rest
-  } = useMemo(() => options ?? {}, [options]);
+  const timeout = options?.timeout;
+  const { ...rest } = useMemo(() => options ?? {}, [options]);
   const queryFn = useCallback(
-    async (refetchParams: TParams | void, overrideTargetMachine?: string) => {
+    async (refetchParams: TParams | void) => {
       try {
         return await promiseFunction({
-          service: overrideTargetMachine ?? service,
+          service: service(options?.meta),
           functionName: functionName.toString(),
           parameters: refetchParams ?? params,
           options: {
-            avoidTimeout,
-            customTimeout,
+            avoidTimeout: !timeout,
+            customTimeout: timeout,
           },
+          meta: options?.meta,
         });
       } catch (e) {
         if (e instanceof Error) {
@@ -135,7 +140,7 @@ const useCallQueryBase = <
         throw new Error(e as string);
       }
     },
-    [avoidTimeout, customTimeout, functionName, service, params]
+    [functionName, service, params, timeout]
   );
 
   return useQuery<TData, TError, TParams, TSelect>({
@@ -144,9 +149,12 @@ const useCallQueryBase = <
   });
 };
 
-export function buildQueryHook<TFnToParams extends FnToParamsBase>(
-  promiseFunction: TPromiseFunction<unknown, unknown>,
-  getTargetService: (machine: string | undefined) => string
+export function buildQueryHook<
+  TFnToParams extends FnToParamsBase,
+  TMetadata = unknown,
+>(
+  promiseFunction: TPromiseFunction<unknown, unknown, unknown>,
+  getTargetService: (meta?: TMetadata) => string
 ) {
   return function useCallQueryBuilder<
     TFn extends keyof TFnToParams,
@@ -160,18 +168,18 @@ export function buildQueryHook<TFnToParams extends FnToParamsBase>(
         TFnToParams[TFn]["data"],
         TFnToParams[TFn]["error"],
         TFnToParams[TFn]["params"],
-        TSelect
+        TSelect,
+        TMetadata
       >
-    >[4] & { machine?: string }
+    >[4] & { meta?: TMetadata }
   ) {
-    const targetService = getTargetService(options?.machine);
-
     return useCallQueryBase<
       TFnToParams,
       TFnToParams[TFn]["data"],
       TFnToParams[TFn]["error"],
       TFnToParams[TFn]["params"],
-      TSelect
-    >(promiseFunction, func, params, targetService, options);
+      TSelect,
+      TMetadata
+    >(promiseFunction, func, params, getTargetService, options);
   };
 }

package/src/proxyBinders.ts

@@ -17,7 +17,9 @@ export function bindClientSocketProxy(socketClientProxy: ZMQProxyWSClient) {
 }
 
 export function bindPromiseFunction(clientSocketProxy: ZMQProxyWSClient) {
-  return async (...args: Parameters<TPromiseFunction<unknown, unknown>>) => {
+  return async (
+    ...args: Parameters<TPromiseFunction<unknown, unknown, unknown>>
+  ) => {
     const res = await clientSocketProxy.callAsync(...args);
     return res.message.Result;
   };

package/src/useMutation.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it, vi } from "vitest";
+import { useMutation } from "./useMutation";
+import { act, renderHook, waitFor } from "@testing-library/react";
+
+describe("useMutation", () => {
+  it("should be in idle state on mount", () => {
+    const { result } = renderHook(() => useMutation({ mutationFn: vi.fn() }));
+    expect(result.current.status).toBe("idle");
+  });
+
+  it("should be in loading state after mutationFn is called", async () => {
+    const { result } = renderHook(() => useMutation({ mutationFn: vi.fn() }));
+    act(() => result.current.mutate({}));
+    await waitFor(() => expect(result.current.status).toBe("loading"));
+  });
+
+  it("should be in success state after mutationFn resolves", async () => {
+    const { result } = renderHook(() =>
+      useMutation({ mutationFn: vi.fn().mockResolvedValue("test") })
+    );
+    act(() => result.current.mutate({}));
+    await waitFor(() => expect(result.current.status).toBe("success"));
+  });
+
+  it("should be in error state after mutationFn rejects", async () => {
+    const { result } = renderHook(() =>
+      useMutation({ mutationFn: vi.fn().mockRejectedValue("test") })
+    );
+    act(() => result.current.mutate({}));
+    await waitFor(() => expect(result.current.status).toBe("error"));
+  });
+
+  it("should call onSuccess callback after mutationFn resolves", async () => {
+    const onSuccess = vi.fn();
+    const { result } = renderHook(() =>
+      useMutation({ mutationFn: vi.fn().mockResolvedValue("test"), onSuccess })
+    );
+    act(() => result.current.mutate({}, { onSuccess }));
+    await waitFor(() => expect(onSuccess).toBeCalledTimes(2));
+    expect(onSuccess).toBeCalledWith("test", {}, undefined);
+  });
+
+  it("should call onError callback after mutationFn rejects", async () => {
+    const onError = vi.fn();
+    const { result } = renderHook(() =>
+      useMutation({ mutationFn: vi.fn().mockRejectedValue("test"), onError })
+    );
+    act(() => result.current.mutate({}, { onError }));
+    await waitFor(() => expect(onError).toBeCalledTimes(2));
+    expect(onError).toBeCalledWith("test", {}, undefined);
+  });
+
+  it("should call onSettled callback after mutationFn resolves", async () => {
+    const onSettled = vi.fn();
+    const { result } = renderHook(() =>
+      useMutation({
+        mutationFn: vi.fn().mockResolvedValue("test"),
+        onSettled,
+      })
+    );
+    act(() => result.current.mutate({}, { onSettled }));
+    await waitFor(() => expect(onSettled).toBeCalledTimes(2));
+    expect(onSettled).toBeCalledWith("test", null, {}, undefined);
+  });
+
+  it("should call onSettled callback after mutationFn rejects", async () => {
+    const onSettled = vi.fn();
+    const { result } = renderHook(() =>
+      useMutation({ mutationFn: vi.fn().mockRejectedValue("test"), onSettled })
+    );
+    act(() => result.current.mutate({}, { onSettled }));
+    await waitFor(() => expect(onSettled).toBeCalledTimes(2));
+    expect(onSettled).toBeCalledWith(undefined, "test", {}, undefined);
+  });
+
+  it("should pass correct params mutationFn and callbacks to mutationFn", async () => {
+    const mutationFn = vi.fn();
+    const params = { foo: "bar" };
+    const { result } = renderHook(() => useMutation({ mutationFn }));
+    act(() => result.current.mutate(params));
+    await waitFor(() => expect(mutationFn).toBeCalledTimes(1));
+    expect(mutationFn).toBeCalledWith(params, undefined);
+  });
+
+  it("should pass meta to mutationFn", async () => {
+    const mutationFn = vi.fn();
+    const { result } = renderHook(() => useMutation({ mutationFn }));
+    act(() => result.current.mutate({}, { meta: { foo: "bar" } }));
+    await waitFor(() => expect(mutationFn).toBeCalledTimes(1));
+    expect(mutationFn).toBeCalledWith({}, { foo: "bar" });
+  });
+
+  it("should call prepareParams", async () => {
+    const prepareParams = vi.fn();
+    const { result } = renderHook(() =>
+      useMutation({
+        mutationFn: vi.fn(),
+        prepareParams,
+        params: { baz: "baz" },
+      })
+    );
+    act(() => result.current.mutate({}, { meta: { foo: "bar" } }));
+    await waitFor(() => expect(prepareParams).toBeCalledTimes(1));
+    expect(prepareParams).toBeCalledWith({}, { baz: "baz" }, { foo: "bar" });
+  });
+});

package/src/useMutation.ts

@@ -1,40 +1,63 @@
 import { useCallback, useRef, useState } from "react";
 
-export type MutationFunction<TData = unknown, TParams = unknown> = (
-  params: TParams,
-  overrideTargetMachine?: string
-) => Promise<TData>;
+export type MutationFunction<
+  TData = unknown,
+  TParams = unknown,
+  TMetadata = unknown,
+> = (params: TParams, meta?: TMetadata) => Promise<TData>;
 
 export interface MutationOptions<
   TData = unknown,
   TError = unknown,
   TParams = void,
+  TMetadata = unknown,
 > {
-  mutationFn: MutationFunction<TData, TParams>;
+  mutationFn: MutationFunction<TData, TParams, TMetadata>;
   params?: TParams;
-  onSuccess?: (data: TData, variables: TParams) => Promise<unknown> | unknown;
-  onError?: (error: TError, variables: TParams) => Promise<unknown> | unknown;
+  onSuccess?: (
+    data: TData,
+    variables: TParams,
+    meta?: TMetadata
+  ) => Promise<unknown> | unknown;
+  onError?: (
+    error: TMutationError<TError>,
+    variables: TParams,
+    meta?: TMetadata
+  ) => Promise<unknown> | unknown;
   onSettled?: (
     data: TData | undefined,
-    error: TError | null,
-    variables: TParams
+    error: TMutationError<TError> | null,
+    variables: TParams,
+    meta?: TMetadata
   ) => Promise<unknown> | unknown;
   compareOrThrow?: (result: TData | TError) => boolean;
   timeout?: number;
-  prepareParams?: (variables: TParams, defaults?: TParams) => TParams;
+  prepareParams?: (
+    variables: TParams,
+    defaults?: TParams,
+    meta?: TMetadata
+  ) => TParams;
 }
 
+type TMutationError<TError> = TError | Error | null;
+
 export interface MutateOptions<
   TData = unknown,
   TError = unknown,
   TParams = void,
+  TMetadata = unknown,
 > {
-  onSuccess?: (data: TData, variables: TParams) => void;
-  onError?: (error: TError, variables: TParams) => void;
+  onSuccess?: (data: TData, variables: TParams, meta?: TMetadata) => void;
+  onError?: (
+    error: TMutationError<TError>,
+    variables: TParams,
+    meta?: TMetadata
+  ) => void;
   onSettled?: (
     data: TData | undefined,
-    error: TError | null,
-    variables: TParams
+    error: TMutationError<TError> | null,
+    variables: TParams,
+    meta?: TMetadata
   ) => void;
 }
 
@@ -56,54 +79,13 @@ export class ComparisonFailError<TPayload = unknown> extends Error {
   }
 }
 
-/**
- * `useMutation` is a hook that allows you to perform a mutation/push updates to the services while
- * providing extensive API to tap into the status and results of the mutation.
- * @param mutationFn The mutation function to be called when the `mutate` function is called.
- * `useMutation` does not care about what the function does, all it needs it a function that returns
- * a promise.
- * @param options Options to configure the mutation.
- * @returns An object with the following properties:
- * - `mutateAsync`: A function that takes in the variables and returns a promise that resolves to the
- * result of the mutation. This function can be awaited to get the result of the mutation. Callbacks can
- * be passed to this function to be called when the mutation is successful or when it fails. It's good idea
- * to wrap this function in a try/catch block.
- * - `mutate`: A function that takes in the variables and returns nothing. This function does not
- * return a promise. Callbacks can be passed to this function to be called when the mutation is
- * successful or when it fails.
- * - `status`: The status of the mutation. Can be one of `idle`, `loading`, `success` or `error`.
- * - `result`: The result of the mutation. This is undefined until the mutation is successful.
- * - `reset`: A function that resets the mutation to the initial state.
- * - `error`: The error object if the mutation has failed.
- * @example
- * ```typescript
- * const mutationRes = useMutation({
- *    mutationFn: (variables) => {
- *      return ZMQHelper.callSomethingAsync(variables)
- *    },
- *    onSuccess: (data) => {
- *      // do something with the result
- *    },
- *    onError: (error) => {
- *      // do something with the error
- *    },
- *    onSettled: (data, error) => {
- *      // do something when the mutation is done
- *   }});
- *
- * // call the mutation
- * const res = await mutationRes.mutateAsync({ foo: "bar" });
- * // OR
- * mutationRes.mutate({ foo: "bar" }, {
- *  onSuccess: (data) => {
- *    // do something with the result
- *    // for example show a toast message
- *    // stop local loading state
- * });
- * ```
- */
-export const useMutation = <TData = unknown, TError = unknown, TParams = void>(
-  options: MutationOptions<TData, TError, TParams>
+export const useMutation = <
+  TData = unknown,
+  TError = TMutationError<unknown>,
+  TParams = void,
+  TMetadata = unknown,
+>(
+  options: MutationOptions<TData, TError, TParams, TMetadata>
 ) => {
   const {
     mutationFn,
@@ -116,7 +98,7 @@ export const useMutation = <TData = unknown, TError = unknown, TParams = void>(
     timeout,
   } = options;
   const [status, setStatus] = useState<MutationStatus>("idle");
-  const [error, setError] = useState<TError | null>(null);
+  const [error, setError] = useState<TMutationError<TError>>(null);
   const [result, setResult] = useState<TData | undefined>(undefined);
   const mutationFnRef = useRef(mutationFn);
   const internalOptionsRef = useRef({
@@ -133,84 +115,77 @@ export const useMutation = <TData = unknown, TError = unknown, TParams = void>(
   const internalCallbackRef = useRef(internalCallbackRefistry);
   internalCallbackRef.current = internalCallbackRefistry;
 
-  const mutateAsync = useCallback(
-    async (params: TParams, overrideTargetMachine?: string) => {
-      setStatus("loading");
-      setError(null);
-
-      try {
-        const promises: RacePromises<TData>[] = [
-          mutationFnRef.current(
-            internalCallbackRef.current.prepareParams
-              ? internalCallbackRef.current.prepareParams(
-                  params,
-                  internalOptionsRef.current.params
+  const mutateAsync = useCallback(async (params: TParams, meta?: TMetadata) => {
+    setStatus("loading");
+    setError(null);
+
+    try {
+      const promises: RacePromises<TData>[] = [
+        mutationFnRef.current(
+          internalCallbackRef.current.prepareParams
+            ? internalCallbackRef.current.prepareParams(
+                params,
+                internalOptionsRef.current.params,
+                meta
+              )
+            : params,
+          meta
+        ),
+        ...(internalOptionsRef.current.timeout
+          ? [
+              new Promise<RaceErrorReason>((resolve) =>
+                setTimeout(
+                  () => resolve("timeout"),
+                  internalOptionsRef.current.timeout
                 )
-              : params,
-            overrideTargetMachine
-          ),
-          ...(internalOptionsRef.current.timeout
-            ? [
-                new Promise<RaceErrorReason>((resolve) =>
-                  setTimeout(
-                    () => resolve("timeout"),
-                    internalOptionsRef.current.timeout
-                  )
-                ),
-              ]
-            : []),
-        ];
-
-        const res = await Promise.race(promises);
-
-        if (res === "timeout") {
-          throw new Error("timeout");
-        }
+              ),
+            ]
+          : []),
+      ];
 
-        if (internalCallbackRef.current.compareOrThrow?.(res)) {
-          throw new ComparisonFailError(JSON.stringify(res), res);
-        }
+      const res = await Promise.race(promises);
 
-        setResult(res);
-        setStatus("success");
+      if (res === "timeout") {
+        throw new Error("timeout");
+      }
 
-        internalCallbackRef.current.onSuccess?.(res, params);
-        internalCallbackRef.current.onSettled?.(res, null, params);
+      if (internalCallbackRef.current.compareOrThrow?.(res)) {
+        throw new ComparisonFailError(JSON.stringify(res), res);
+      }
 
-        return res;
-      } catch (error: any) {
-        setError(error);
-        setStatus("error");
+      setResult(res);
+      setStatus("success");
 
-        if (internalCallbackRef.current.onError) {
-          internalCallbackRef.current.onError(error, params);
-        }
+      internalCallbackRef.current.onSuccess?.(res, params, meta);
+      internalCallbackRef.current.onSettled?.(res, null, params, meta);
 
-        if (internalCallbackRef.current.onSettled) {
-          internalCallbackRef.current.onSettled(undefined, error, params);
-        }
+      return res;
+    } catch (error: any) {
+      setError(error);
+      setStatus("error");
 
-        throw error;
-      }
-    },
-    []
-  );
+      internalCallbackRef.current.onError?.(error, params, meta);
+      internalCallbackRef.current.onSettled?.(undefined, error, params, meta);
+
+      throw error;
+    }
+  }, []);
 
   const mutate = useCallback(
     (
       variables: TParams,
-      options?: MutateOptions<TData, TError, TParams> & {
-        overrideTargetMachine?: string;
+      options?: MutateOptions<TData, TError, TParams, TMetadata> & {
+        meta?: TMetadata;
       }
     ) => {
-      mutateAsync(variables, options?.overrideTargetMachine).then(
+      mutateAsync(variables, options?.meta).then(
         (data) => {
-          options?.onSuccess?.(data, variables);
-          options?.onSettled?.(data, null, variables);
+          options?.onSuccess?.(data, variables, options?.meta);
+          options?.onSettled?.(data, null, variables, options?.meta);
         },
         (error) => {
-          options?.onError?.(error, variables);
-          options?.onSettled?.(undefined, error, variables);
+          options?.onError?.(error, variables, options?.meta);
+          options?.onSettled?.(undefined, error, variables, options?.meta);
         }
       );
     },
@@ -222,7 +197,11 @@ export const useMutation = <TData = unknown, TError = unknown, TParams = void>(
     status,
     result,
     mutate,
-    reset: () => setStatus("idle"),
+    reset: () => {
+      setStatus("idle");
+      setError(null);
+      setResult(undefined);
+    },
     error,
   };
 };