@pixotope/query 0.6.0 → 0.8.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,25 +32,30 @@ 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">
+  service: (meta?: TMetadata) => string,
+  options?: Omit<
+    MutationOptions<TData, TError, TParams, TMetadata>,
+    "mutationFn"
+  >
 ) => {
   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: !timeout,
             customTimeout: timeout,
           },
+          meta,
         });
       } catch (e) {
         if (e instanceof Error) {
@@ -60,15 +67,18 @@ const useCallMutationBase = <
     [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,
@@ -77,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);
   };
 }
 
@@ -98,26 +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,
-  options?: Omit<QueryOptions<TData, TError, TParams, TSelect>, "queryFn">
+  service: (meta?: TMetadata) => string,
+  options?: Omit<QueryOptions<TData, TError, TParams, TSelect>, "queryFn"> & {
+    meta?: TMetadata;
+  }
 ) => {
   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: !timeout,
             customTimeout: timeout,
           },
+          meta: options?.meta,
         });
       } catch (e) {
         if (e instanceof Error) {
@@ -135,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,
@@ -151,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.test.ts

@@ -0,0 +1,42 @@
+import { vi, describe, expect, it, beforeEach } from "vitest";
+import { bindClientSocketProxy, bindPromiseFunction } from "./proxyBinders";
+import type { ZMQProxyWSClient } from "@pixotope/zmq-client";
+
+describe("proxyBinders", () => {
+  let clientSocketProxy: ZMQProxyWSClient;
+
+  beforeEach(() => {
+    clientSocketProxy = {
+      callAsync: vi.fn().mockResolvedValue({ message: { Result: "test" } }),
+      mirror: vi.fn().mockReturnValue([vi.fn(), "testID"]),
+    } as unknown as ZMQProxyWSClient;
+  });
+
+  describe("bindClientSocketProxy", () => {
+    it("should correctly bind mirror function", () => {
+      bindClientSocketProxy(clientSocketProxy)({
+        name: "test",
+        service: "test",
+        callback: vi.fn(),
+        maxDownwardDepth: 1000,
+      });
+      expect(clientSocketProxy.mirror).toHaveBeenCalledWith(
+        expect.objectContaining({
+          name: "test",
+          service: "test",
+          maxDownwardDepth: 1000,
+        })
+      );
+    });
+  });
+
+  describe("bindPromiseFunction", () => {
+    it("should correctly bind callAsync function", () => {
+      bindPromiseFunction(clientSocketProxy)({
+        functionName: "test",
+        parameters: { test: "test" },
+        service: "test",
+      });
+    });
+  });
+});

package/src/proxyBinders.ts

@@ -2,11 +2,12 @@ import type { ZMQProxyWSClient } from "@pixotope/zmq-client";
 import type { TPromiseFunction } from "./factories";
 import type { buildServiceSubscriptionHook } from "./useSubscription";
 
+export type TProxySubscriptionHandlerParams<TMetadata extends {} = {}> =
+  Parameters<Parameters<typeof buildServiceSubscriptionHook<TMetadata>>[0]>[0];
+
 export function bindClientSocketProxy(socketClientProxy: ZMQProxyWSClient) {
-  return (
-    ...args: Parameters<Parameters<typeof buildServiceSubscriptionHook>[0]>
-  ) => {
-    const { callback: cbHook, ...rest } = args[0];
+  return (args: TProxySubscriptionHandlerParams) => {
+    const { callback: cbHook, ...rest } = args;
     return socketClientProxy.mirror({
       ...rest,
       callback: (message) => {
@@ -17,7 +18,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,30 +1,42 @@
 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;
+  onSuccess?: (
+    data: TData,
+    variables: TParams,
+    meta?: TMetadata
+  ) => Promise<unknown> | unknown;
   onError?: (
     error: TMutationError<TError>,
-    variables: TParams
+    variables: TParams,
+    meta?: TMetadata
   ) => Promise<unknown> | unknown;
   onSettled?: (
     data: TData | undefined,
     error: TMutationError<TError> | null,
-    variables: TParams
+    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;
@@ -33,13 +45,19 @@ export interface MutateOptions<
   TData = unknown,
   TError = unknown,
   TParams = void,
+  TMetadata = unknown,
 > {
-  onSuccess?: (data: TData, variables: TParams) => void;
-  onError?: (error: TMutationError<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: TMutationError<TError> | null,
-    variables: TParams
+    variables: TParams,
+    meta?: TMetadata
   ) => void;
 }
 
@@ -61,58 +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 = TMutationError<unknown>,
   TParams = void,
+  TMetadata = unknown,
 >(
-  options: MutationOptions<TData, TError, TParams>
+  options: MutationOptions<TData, TError, TParams, TMetadata>
 ) => {
   const {
     mutationFn,
@@ -142,79 +115,77 @@ export const useMutation = <
   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");
 
-        internalCallbackRef.current.onError?.(error, params);
-        internalCallbackRef.current.onSettled?.(undefined, error, params);
+      internalCallbackRef.current.onSuccess?.(res, params, meta);
+      internalCallbackRef.current.onSettled?.(res, null, params, meta);
 
-        throw error;
-      }
-    },
-    []
-  );
+      return res;
+    } catch (error: any) {
+      setError(error);
+      setStatus("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);
         }
       );
     },