@pixotope/query 0.6.0 → 0.8.0

package/dist/index.d.cts

@@ -31,80 +31,34 @@ type UseQueryResult<TData = unknown, TError = unknown, TParams = void, TSelectDa
 } & (Stateless extends true ? {} : WithData$1<TSelectData>);
 declare const useQuery: <TData = unknown, TError = unknown, TParams = void, TSelected = TData, Stateless extends true | undefined = undefined>({ queryFn, ...options }: QueryOptions<TData, TError, TParams, TSelected, Stateless>) => UseQueryResult<TSelected, TError, TParams, TSelected, Stateless>;
 
-type MutationFunction<TData = unknown, TParams = unknown> = (params: TParams, overrideTargetMachine?: string) => Promise<TData>;
-interface MutationOptions<TData = unknown, TError = unknown, TParams = void> {
-    mutationFn: MutationFunction<TData, TParams>;
+type MutationFunction<TData = unknown, TParams = unknown, TMetadata = unknown> = (params: TParams, meta?: TMetadata) => Promise<TData>;
+interface MutationOptions<TData = unknown, TError = unknown, TParams = void, TMetadata = unknown> {
+    mutationFn: MutationFunction<TData, TParams, TMetadata>;
     params?: TParams;
-    onSuccess?: (data: TData, variables: TParams) => Promise<unknown> | unknown;
-    onError?: (error: TMutationError<TError>, variables: TParams) => Promise<unknown> | unknown;
-    onSettled?: (data: TData | undefined, error: TMutationError<TError> | null, 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: 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;
-interface MutateOptions<TData = unknown, TError = unknown, TParams = void> {
-    onSuccess?: (data: TData, variables: TParams) => void;
-    onError?: (error: TMutationError<TError>, variables: TParams) => void;
-    onSettled?: (data: TData | undefined, error: TMutationError<TError> | null, variables: TParams) => void;
+interface MutateOptions<TData = unknown, TError = unknown, TParams = void, TMetadata = unknown> {
+    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, meta?: TMetadata) => void;
 }
 type MutationStatus = "idle" | "loading" | "success" | "error";
 declare class ComparisonFailError<TPayload = unknown> extends Error {
     readonly payload: TPayload;
     constructor(message: string, payload: TPayload);
 }
-/**
- * `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
- * });
- * ```
- */
-declare const useMutation: <TData = unknown, TError = unknown, TParams = void>(options: MutationOptions<TData, TError, TParams>) => {
-    mutateAsync: (params: TParams, overrideTargetMachine?: string) => Promise<TData>;
+declare const useMutation: <TData = unknown, TError = unknown, TParams = void, TMetadata = unknown>(options: MutationOptions<TData, TError, TParams, TMetadata>) => {
+    mutateAsync: (params: TParams, meta?: TMetadata) => Promise<TData>;
     status: MutationStatus;
     result: TData | undefined;
-    mutate: (variables: TParams, options?: MutateOptions<TData, TError, TParams> & {
-        overrideTargetMachine?: string;
+    mutate: (variables: TParams, options?: MutateOptions<TData, TError, TParams, TMetadata> & {
+        meta?: TMetadata;
     }) => void;
     reset: () => void;
     error: TMutationError<TError>;
@@ -116,36 +70,38 @@ type MutationInfo<TData, TError, TParams> = {
     params: TParams;
 };
 type FnToParamsBase = Record<string, MutationInfo<unknown, unknown, unknown>>;
-type TPromiseFunction<TResponse, TParams> = (args: Omit<ZMQClient.Call<TResponse, {
+type TPromiseFunction<TResponse, TParams, TExtraParams> = (args: Omit<ZMQClient.Call<TResponse, {
     functionName: string;
     parameters: TParams;
     options?: Omit<TSocketServerCallOptions, "toCallIfNoResponse">;
-}>, "id">) => Promise<TResponse>;
-declare const useCallMutationBase: <TFnToParams extends FnToParamsBase, TData = unknown, TError = unknown, TParams = unknown>(promiseFunc: TPromiseFunction<TData, TParams>, functionName: keyof TFnToParams, service: string, options?: Omit<MutationOptions<TData, TError, TParams>, "mutationFn">) => {
-    mutateAsync: (params: TParams, overrideTargetMachine?: string) => Promise<TData>;
+}>, "id"> & {
+    meta?: TExtraParams;
+}) => Promise<TResponse>;
+declare const useCallMutationBase: <TFnToParams extends FnToParamsBase, TData = unknown, TError = unknown, TParams = unknown, TMetadata = unknown>(promiseFunc: TPromiseFunction<TData, TParams, TMetadata>, functionName: keyof TFnToParams, service: (meta?: TMetadata) => string, options?: Omit<MutationOptions<TData, TError, TParams, TMetadata>, "mutationFn">) => {
+    mutateAsync: (params: TParams, meta?: TMetadata | undefined) => Promise<TData>;
     status: "idle" | "loading" | "success" | "error";
     result: TData | undefined;
-    mutate: (variables: TParams, options?: (MutateOptions<TData, TError, TParams> & {
-        overrideTargetMachine?: string;
+    mutate: (variables: TParams, options?: (MutateOptions<TData, TError, TParams, TMetadata> & {
+        meta?: TMetadata | undefined;
     }) | undefined) => void;
     reset: () => void;
     error: Error | TError | null;
 };
-declare function buildMutationHook<TFnToParams extends FnToParamsBase>(promiseFunc: TPromiseFunction<unknown, unknown>, genTargetService: (machine: string | undefined) => string): <TFn extends keyof TFnToParams>(func: TFn, options?: Parameters<typeof useCallMutationBase<TFnToParams, TFnToParams[TFn]["data"], TFnToParams[TFn]["error"], TFnToParams[TFn]["params"]>>[3] & {
-    machine?: string;
-}) => {
-    mutateAsync: (params: TFnToParams[TFn]["params"], overrideTargetMachine?: string) => Promise<TFnToParams[TFn]["data"]>;
+declare function buildMutationHook<TFnToParams extends FnToParamsBase, TMetadata = unknown>(promiseFunc: TPromiseFunction<unknown, unknown, unknown>, genTargetService: (meta?: TMetadata) => string): <TFn extends keyof TFnToParams>(func: TFn, options?: Parameters<typeof useCallMutationBase<TFnToParams, TFnToParams[TFn]["data"], TFnToParams[TFn]["error"], TFnToParams[TFn]["params"], TMetadata>>[3]) => {
+    mutateAsync: (params: TFnToParams[TFn]["params"], meta?: TMetadata | undefined) => Promise<TFnToParams[TFn]["data"]>;
     status: "idle" | "loading" | "success" | "error";
     result: TFnToParams[TFn]["data"] | undefined;
-    mutate: (variables: TFnToParams[TFn]["params"], options?: (MutateOptions<TFnToParams[TFn]["data"], TFnToParams[TFn]["error"], TFnToParams[TFn]["params"]> & {
-        overrideTargetMachine?: string;
+    mutate: (variables: TFnToParams[TFn]["params"], options?: (MutateOptions<TFnToParams[TFn]["data"], TFnToParams[TFn]["error"], TFnToParams[TFn]["params"], TMetadata> & {
+        meta?: TMetadata | undefined;
     }) | undefined) => void;
     reset: () => void;
     error: Error | TFnToParams[TFn]["error"] | null;
 };
-declare const useCallQueryBase: <TFnToParams extends FnToParamsBase, TData = unknown, TError = unknown, TParams = unknown, TSelect = TData>(promiseFunction: TPromiseFunction<TData, TParams>, functionName: keyof TFnToParams, params: TParams, service: string, options?: Omit<QueryOptions<TData, TError, TParams, TSelect>, "queryFn">) => UseQueryResult<TSelect, TError, TParams, TSelect, undefined>;
-declare function buildQueryHook<TFnToParams extends FnToParamsBase>(promiseFunction: TPromiseFunction<unknown, unknown>, getTargetService: (machine: string | undefined) => string): <TFn extends keyof TFnToParams, TSelect = TFnToParams[TFn]["data"]>(func: TFn, params: TFnToParams[TFn]["params"], options?: Parameters<typeof useCallQueryBase<TFnToParams, TFnToParams[TFn]["data"], TFnToParams[TFn]["error"], TFnToParams[TFn]["params"], TSelect>>[4] & {
-    machine?: string;
+declare const useCallQueryBase: <TFnToParams extends FnToParamsBase, TData = unknown, TError = unknown, TParams = unknown, TSelect = TData, TMetadata = unknown>(promiseFunction: TPromiseFunction<TData, TParams, TMetadata>, functionName: keyof TFnToParams, params: TParams, service: (meta?: TMetadata) => string, options?: Omit<QueryOptions<TData, TError, TParams, TSelect>, "queryFn"> & {
+    meta?: TMetadata;
+}) => UseQueryResult<TSelect, TError, TParams, TSelect, undefined>;
+declare function buildQueryHook<TFnToParams extends FnToParamsBase, TMetadata = unknown>(promiseFunction: TPromiseFunction<unknown, unknown, unknown>, getTargetService: (meta?: TMetadata) => string): <TFn extends keyof TFnToParams, TSelect = TFnToParams[TFn]["data"]>(func: TFn, params: TFnToParams[TFn]["params"], options?: Parameters<typeof useCallQueryBase<TFnToParams, TFnToParams[TFn]["data"], TFnToParams[TFn]["error"], TFnToParams[TFn]["params"], TSelect, TMetadata>>[4] & {
+    meta?: TMetadata;
 }) => UseQueryResult<TSelect, TFnToParams[TFn]["error"], TFnToParams[TFn]["params"], TSelect, undefined>;
 
 /**
@@ -154,7 +110,7 @@ declare function buildQueryHook<TFnToParams extends FnToParamsBase>(promiseFunct
  * @description useSubscriptionCore | This hook handle core subscription logic
  * and provides a way to subscribe and unsubscribe to a topic via any callback
  */
-type SubscriptionState = "idle" | "subscribed" | "subscribing";
+type SubscriptionState = "idle" | "subscribed" | "subscribing" | "error";
 type MessageHandler<TMessage> = (message: TMessage) => void;
 type Connection = {
     acknowledge: () => void;
@@ -178,8 +134,9 @@ type SubscriptionCoreOptions<TData, TMessage = TData, Stateless extends true | u
      */
     enabled?: boolean;
     /**
-     * @description Function that will be called to compare the message with the
-     * previous message. If the function returns true, the message will be ignored.
+     * @description Function that will be called before the message is processed.
+     * Returning `true` will cause the message to not be set to state and call {@link onError} if provided.
+     * Status will be set to `error`.
      */
     compareOrThrow?: (data: TMessage) => boolean;
     /**
@@ -230,32 +187,34 @@ type SubscriptionCoreReturnType<TData, Stateless extends true | undefined> = {
  */
 declare function useSubscriptionCore<TData = unknown, TMessage = TData, Stateless extends true | undefined = undefined>(options: SubscriptionCoreOptions<TData, TMessage, Stateless>): SubscriptionCoreReturnType<TData, Stateless>;
 
-type SubscriptionOptions<TData, TMessage = unknown, Stateless extends true | undefined = undefined> = Omit<SubscriptionCoreOptions<TData, TMessage, Stateless>, "subscriberFn"> & {
+type SubscriptionOptions<TData, TMessage = unknown, Stateless extends true | undefined = undefined, TMetadata extends {} = {}> = Omit<SubscriptionCoreOptions<TData, TMessage, Stateless>, "subscriberFn"> & {
     service: string;
     topic: string;
     maxDownwardDepth?: number;
+} & {
+    meta?: TMetadata;
 };
-type TSubscriptionHandlerFunction<TMessage> = (opts: {
+type TSubscriptionHandlerFunction<TMessage, TMetadata extends {} = {}> = (opts: {
     service: string;
     name: string;
     callback: (message: TMessage) => void;
     maxDownwardDepth?: number;
+} & {
+    meta?: TMetadata;
 }) => () => void;
-declare function useSubscription<TData = unknown, TMessage = TData, Stateless extends true | undefined = undefined>(subscriptionHandler: TSubscriptionHandlerFunction<TMessage>, options: SubscriptionOptions<TData, TMessage, Stateless>): SubscriptionCoreReturnType<TData, Stateless>;
-declare function buildServiceSubscriptionHook(subscriptionHandler: TSubscriptionHandlerFunction<unknown>, targetMachine: (machine: string | undefined) => string): <TData, TMessage = TData, Stateless extends true | undefined = undefined>(options: Omit<SubscriptionOptions<TData, TMessage, Stateless>, "service"> & {
+declare function useSubscription<TData = unknown, TMessage = TData, Stateless extends true | undefined = undefined, TMetadata extends {} = {}>(subscriptionHandler: TSubscriptionHandlerFunction<TMessage, TMetadata>, options: SubscriptionOptions<TData, TMessage, Stateless, TMetadata>): SubscriptionCoreReturnType<TData, Stateless>;
+declare function buildServiceSubscriptionHook<TMetadata extends {} = {}>(subscriptionHandler: TSubscriptionHandlerFunction<unknown, TMetadata>, targetMachine: (machine: string | undefined) => string): <TData, TMessage = TData, Stateless extends true | undefined = undefined>(options: Omit<SubscriptionOptions<TData, TMessage, Stateless, TMetadata>, "service"> & {
     machine?: string;
 }) => SubscriptionCoreReturnType<TData, Stateless>;
 
-declare function bindClientSocketProxy(socketClientProxy: ZMQProxyWSClient): (opts: {
-    service: string;
-    name: string;
-    callback: (message: unknown) => void;
-    maxDownwardDepth?: number;
-}) => () => void;
+type TProxySubscriptionHandlerParams<TMetadata extends {} = {}> = Parameters<Parameters<typeof buildServiceSubscriptionHook<TMetadata>>[0]>[0];
+declare function bindClientSocketProxy(socketClientProxy: ZMQProxyWSClient): (args: TProxySubscriptionHandlerParams) => () => void;
 declare function bindPromiseFunction(clientSocketProxy: ZMQProxyWSClient): (args: Omit<_pixotope_zmq_client.ZMQClient.Call<unknown, {
     functionName: string;
     parameters: unknown;
     options?: Omit<_pixotope_zmq_client.TSocketServerCallOptions, "toCallIfNoResponse">;
-}>, "id">) => Promise<unknown>;
+}>, "id"> & {
+    meta?: unknown;
+}) => Promise<unknown>;
 
-export { ComparisonFailError, type Connection, type MessageHandler, type MutateOptions, type MutationFunction, type MutationInfo, type MutationOptions, type QueryOptions, type SubscriptionCoreOptions, type SubscriptionCoreReturnType, type SubscriptionOptions, type TPromiseFunction, type TSubscriptionHandlerFunction, type UseQueryResult, bindClientSocketProxy, bindPromiseFunction, buildMutationHook, buildQueryHook, buildServiceSubscriptionHook, useMutation, useQuery, useSubscription, useSubscriptionCore };
+export { ComparisonFailError, type Connection, type MessageHandler, type MutateOptions, type MutationFunction, type MutationInfo, type MutationOptions, type QueryOptions, type SubscriptionCoreOptions, type SubscriptionCoreReturnType, type SubscriptionOptions, type TPromiseFunction, type TProxySubscriptionHandlerParams, type TSubscriptionHandlerFunction, type UseQueryResult, bindClientSocketProxy, bindPromiseFunction, buildMutationHook, buildQueryHook, buildServiceSubscriptionHook, useMutation, useQuery, useSubscription, useSubscriptionCore };

package/dist/index.d.ts

@@ -31,80 +31,34 @@ type UseQueryResult<TData = unknown, TError = unknown, TParams = void, TSelectDa
 } & (Stateless extends true ? {} : WithData$1<TSelectData>);
 declare const useQuery: <TData = unknown, TError = unknown, TParams = void, TSelected = TData, Stateless extends true | undefined = undefined>({ queryFn, ...options }: QueryOptions<TData, TError, TParams, TSelected, Stateless>) => UseQueryResult<TSelected, TError, TParams, TSelected, Stateless>;
 
-type MutationFunction<TData = unknown, TParams = unknown> = (params: TParams, overrideTargetMachine?: string) => Promise<TData>;
-interface MutationOptions<TData = unknown, TError = unknown, TParams = void> {
-    mutationFn: MutationFunction<TData, TParams>;
+type MutationFunction<TData = unknown, TParams = unknown, TMetadata = unknown> = (params: TParams, meta?: TMetadata) => Promise<TData>;
+interface MutationOptions<TData = unknown, TError = unknown, TParams = void, TMetadata = unknown> {
+    mutationFn: MutationFunction<TData, TParams, TMetadata>;
     params?: TParams;
-    onSuccess?: (data: TData, variables: TParams) => Promise<unknown> | unknown;
-    onError?: (error: TMutationError<TError>, variables: TParams) => Promise<unknown> | unknown;
-    onSettled?: (data: TData | undefined, error: TMutationError<TError> | null, 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: 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;
-interface MutateOptions<TData = unknown, TError = unknown, TParams = void> {
-    onSuccess?: (data: TData, variables: TParams) => void;
-    onError?: (error: TMutationError<TError>, variables: TParams) => void;
-    onSettled?: (data: TData | undefined, error: TMutationError<TError> | null, variables: TParams) => void;
+interface MutateOptions<TData = unknown, TError = unknown, TParams = void, TMetadata = unknown> {
+    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, meta?: TMetadata) => void;
 }
 type MutationStatus = "idle" | "loading" | "success" | "error";
 declare class ComparisonFailError<TPayload = unknown> extends Error {
     readonly payload: TPayload;
     constructor(message: string, payload: TPayload);
 }
-/**
- * `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
- * });
- * ```
- */
-declare const useMutation: <TData = unknown, TError = unknown, TParams = void>(options: MutationOptions<TData, TError, TParams>) => {
-    mutateAsync: (params: TParams, overrideTargetMachine?: string) => Promise<TData>;
+declare const useMutation: <TData = unknown, TError = unknown, TParams = void, TMetadata = unknown>(options: MutationOptions<TData, TError, TParams, TMetadata>) => {
+    mutateAsync: (params: TParams, meta?: TMetadata) => Promise<TData>;
     status: MutationStatus;
     result: TData | undefined;
-    mutate: (variables: TParams, options?: MutateOptions<TData, TError, TParams> & {
-        overrideTargetMachine?: string;
+    mutate: (variables: TParams, options?: MutateOptions<TData, TError, TParams, TMetadata> & {
+        meta?: TMetadata;
     }) => void;
     reset: () => void;
     error: TMutationError<TError>;
@@ -116,36 +70,38 @@ type MutationInfo<TData, TError, TParams> = {
     params: TParams;
 };
 type FnToParamsBase = Record<string, MutationInfo<unknown, unknown, unknown>>;
-type TPromiseFunction<TResponse, TParams> = (args: Omit<ZMQClient.Call<TResponse, {
+type TPromiseFunction<TResponse, TParams, TExtraParams> = (args: Omit<ZMQClient.Call<TResponse, {
     functionName: string;
     parameters: TParams;
     options?: Omit<TSocketServerCallOptions, "toCallIfNoResponse">;
-}>, "id">) => Promise<TResponse>;
-declare const useCallMutationBase: <TFnToParams extends FnToParamsBase, TData = unknown, TError = unknown, TParams = unknown>(promiseFunc: TPromiseFunction<TData, TParams>, functionName: keyof TFnToParams, service: string, options?: Omit<MutationOptions<TData, TError, TParams>, "mutationFn">) => {
-    mutateAsync: (params: TParams, overrideTargetMachine?: string) => Promise<TData>;
+}>, "id"> & {
+    meta?: TExtraParams;
+}) => Promise<TResponse>;
+declare const useCallMutationBase: <TFnToParams extends FnToParamsBase, TData = unknown, TError = unknown, TParams = unknown, TMetadata = unknown>(promiseFunc: TPromiseFunction<TData, TParams, TMetadata>, functionName: keyof TFnToParams, service: (meta?: TMetadata) => string, options?: Omit<MutationOptions<TData, TError, TParams, TMetadata>, "mutationFn">) => {
+    mutateAsync: (params: TParams, meta?: TMetadata | undefined) => Promise<TData>;
     status: "idle" | "loading" | "success" | "error";
     result: TData | undefined;
-    mutate: (variables: TParams, options?: (MutateOptions<TData, TError, TParams> & {
-        overrideTargetMachine?: string;
+    mutate: (variables: TParams, options?: (MutateOptions<TData, TError, TParams, TMetadata> & {
+        meta?: TMetadata | undefined;
     }) | undefined) => void;
     reset: () => void;
     error: Error | TError | null;
 };
-declare function buildMutationHook<TFnToParams extends FnToParamsBase>(promiseFunc: TPromiseFunction<unknown, unknown>, genTargetService: (machine: string | undefined) => string): <TFn extends keyof TFnToParams>(func: TFn, options?: Parameters<typeof useCallMutationBase<TFnToParams, TFnToParams[TFn]["data"], TFnToParams[TFn]["error"], TFnToParams[TFn]["params"]>>[3] & {
-    machine?: string;
-}) => {
-    mutateAsync: (params: TFnToParams[TFn]["params"], overrideTargetMachine?: string) => Promise<TFnToParams[TFn]["data"]>;
+declare function buildMutationHook<TFnToParams extends FnToParamsBase, TMetadata = unknown>(promiseFunc: TPromiseFunction<unknown, unknown, unknown>, genTargetService: (meta?: TMetadata) => string): <TFn extends keyof TFnToParams>(func: TFn, options?: Parameters<typeof useCallMutationBase<TFnToParams, TFnToParams[TFn]["data"], TFnToParams[TFn]["error"], TFnToParams[TFn]["params"], TMetadata>>[3]) => {
+    mutateAsync: (params: TFnToParams[TFn]["params"], meta?: TMetadata | undefined) => Promise<TFnToParams[TFn]["data"]>;
     status: "idle" | "loading" | "success" | "error";
     result: TFnToParams[TFn]["data"] | undefined;
-    mutate: (variables: TFnToParams[TFn]["params"], options?: (MutateOptions<TFnToParams[TFn]["data"], TFnToParams[TFn]["error"], TFnToParams[TFn]["params"]> & {
-        overrideTargetMachine?: string;
+    mutate: (variables: TFnToParams[TFn]["params"], options?: (MutateOptions<TFnToParams[TFn]["data"], TFnToParams[TFn]["error"], TFnToParams[TFn]["params"], TMetadata> & {
+        meta?: TMetadata | undefined;
     }) | undefined) => void;
     reset: () => void;
     error: Error | TFnToParams[TFn]["error"] | null;
 };
-declare const useCallQueryBase: <TFnToParams extends FnToParamsBase, TData = unknown, TError = unknown, TParams = unknown, TSelect = TData>(promiseFunction: TPromiseFunction<TData, TParams>, functionName: keyof TFnToParams, params: TParams, service: string, options?: Omit<QueryOptions<TData, TError, TParams, TSelect>, "queryFn">) => UseQueryResult<TSelect, TError, TParams, TSelect, undefined>;
-declare function buildQueryHook<TFnToParams extends FnToParamsBase>(promiseFunction: TPromiseFunction<unknown, unknown>, getTargetService: (machine: string | undefined) => string): <TFn extends keyof TFnToParams, TSelect = TFnToParams[TFn]["data"]>(func: TFn, params: TFnToParams[TFn]["params"], options?: Parameters<typeof useCallQueryBase<TFnToParams, TFnToParams[TFn]["data"], TFnToParams[TFn]["error"], TFnToParams[TFn]["params"], TSelect>>[4] & {
-    machine?: string;
+declare const useCallQueryBase: <TFnToParams extends FnToParamsBase, TData = unknown, TError = unknown, TParams = unknown, TSelect = TData, TMetadata = unknown>(promiseFunction: TPromiseFunction<TData, TParams, TMetadata>, functionName: keyof TFnToParams, params: TParams, service: (meta?: TMetadata) => string, options?: Omit<QueryOptions<TData, TError, TParams, TSelect>, "queryFn"> & {
+    meta?: TMetadata;
+}) => UseQueryResult<TSelect, TError, TParams, TSelect, undefined>;
+declare function buildQueryHook<TFnToParams extends FnToParamsBase, TMetadata = unknown>(promiseFunction: TPromiseFunction<unknown, unknown, unknown>, getTargetService: (meta?: TMetadata) => string): <TFn extends keyof TFnToParams, TSelect = TFnToParams[TFn]["data"]>(func: TFn, params: TFnToParams[TFn]["params"], options?: Parameters<typeof useCallQueryBase<TFnToParams, TFnToParams[TFn]["data"], TFnToParams[TFn]["error"], TFnToParams[TFn]["params"], TSelect, TMetadata>>[4] & {
+    meta?: TMetadata;
 }) => UseQueryResult<TSelect, TFnToParams[TFn]["error"], TFnToParams[TFn]["params"], TSelect, undefined>;
 
 /**
@@ -154,7 +110,7 @@ declare function buildQueryHook<TFnToParams extends FnToParamsBase>(promiseFunct
  * @description useSubscriptionCore | This hook handle core subscription logic
  * and provides a way to subscribe and unsubscribe to a topic via any callback
  */
-type SubscriptionState = "idle" | "subscribed" | "subscribing";
+type SubscriptionState = "idle" | "subscribed" | "subscribing" | "error";
 type MessageHandler<TMessage> = (message: TMessage) => void;
 type Connection = {
     acknowledge: () => void;
@@ -178,8 +134,9 @@ type SubscriptionCoreOptions<TData, TMessage = TData, Stateless extends true | u
      */
     enabled?: boolean;
     /**
-     * @description Function that will be called to compare the message with the
-     * previous message. If the function returns true, the message will be ignored.
+     * @description Function that will be called before the message is processed.
+     * Returning `true` will cause the message to not be set to state and call {@link onError} if provided.
+     * Status will be set to `error`.
      */
     compareOrThrow?: (data: TMessage) => boolean;
     /**
@@ -230,32 +187,34 @@ type SubscriptionCoreReturnType<TData, Stateless extends true | undefined> = {
  */
 declare function useSubscriptionCore<TData = unknown, TMessage = TData, Stateless extends true | undefined = undefined>(options: SubscriptionCoreOptions<TData, TMessage, Stateless>): SubscriptionCoreReturnType<TData, Stateless>;
 
-type SubscriptionOptions<TData, TMessage = unknown, Stateless extends true | undefined = undefined> = Omit<SubscriptionCoreOptions<TData, TMessage, Stateless>, "subscriberFn"> & {
+type SubscriptionOptions<TData, TMessage = unknown, Stateless extends true | undefined = undefined, TMetadata extends {} = {}> = Omit<SubscriptionCoreOptions<TData, TMessage, Stateless>, "subscriberFn"> & {
     service: string;
     topic: string;
     maxDownwardDepth?: number;
+} & {
+    meta?: TMetadata;
 };
-type TSubscriptionHandlerFunction<TMessage> = (opts: {
+type TSubscriptionHandlerFunction<TMessage, TMetadata extends {} = {}> = (opts: {
     service: string;
     name: string;
     callback: (message: TMessage) => void;
     maxDownwardDepth?: number;
+} & {
+    meta?: TMetadata;
 }) => () => void;
-declare function useSubscription<TData = unknown, TMessage = TData, Stateless extends true | undefined = undefined>(subscriptionHandler: TSubscriptionHandlerFunction<TMessage>, options: SubscriptionOptions<TData, TMessage, Stateless>): SubscriptionCoreReturnType<TData, Stateless>;
-declare function buildServiceSubscriptionHook(subscriptionHandler: TSubscriptionHandlerFunction<unknown>, targetMachine: (machine: string | undefined) => string): <TData, TMessage = TData, Stateless extends true | undefined = undefined>(options: Omit<SubscriptionOptions<TData, TMessage, Stateless>, "service"> & {
+declare function useSubscription<TData = unknown, TMessage = TData, Stateless extends true | undefined = undefined, TMetadata extends {} = {}>(subscriptionHandler: TSubscriptionHandlerFunction<TMessage, TMetadata>, options: SubscriptionOptions<TData, TMessage, Stateless, TMetadata>): SubscriptionCoreReturnType<TData, Stateless>;
+declare function buildServiceSubscriptionHook<TMetadata extends {} = {}>(subscriptionHandler: TSubscriptionHandlerFunction<unknown, TMetadata>, targetMachine: (machine: string | undefined) => string): <TData, TMessage = TData, Stateless extends true | undefined = undefined>(options: Omit<SubscriptionOptions<TData, TMessage, Stateless, TMetadata>, "service"> & {
     machine?: string;
 }) => SubscriptionCoreReturnType<TData, Stateless>;
 
-declare function bindClientSocketProxy(socketClientProxy: ZMQProxyWSClient): (opts: {
-    service: string;
-    name: string;
-    callback: (message: unknown) => void;
-    maxDownwardDepth?: number;
-}) => () => void;
+type TProxySubscriptionHandlerParams<TMetadata extends {} = {}> = Parameters<Parameters<typeof buildServiceSubscriptionHook<TMetadata>>[0]>[0];
+declare function bindClientSocketProxy(socketClientProxy: ZMQProxyWSClient): (args: TProxySubscriptionHandlerParams) => () => void;
 declare function bindPromiseFunction(clientSocketProxy: ZMQProxyWSClient): (args: Omit<_pixotope_zmq_client.ZMQClient.Call<unknown, {
     functionName: string;
     parameters: unknown;
     options?: Omit<_pixotope_zmq_client.TSocketServerCallOptions, "toCallIfNoResponse">;
-}>, "id">) => Promise<unknown>;
+}>, "id"> & {
+    meta?: unknown;
+}) => Promise<unknown>;
 
-export { ComparisonFailError, type Connection, type MessageHandler, type MutateOptions, type MutationFunction, type MutationInfo, type MutationOptions, type QueryOptions, type SubscriptionCoreOptions, type SubscriptionCoreReturnType, type SubscriptionOptions, type TPromiseFunction, type TSubscriptionHandlerFunction, type UseQueryResult, bindClientSocketProxy, bindPromiseFunction, buildMutationHook, buildQueryHook, buildServiceSubscriptionHook, useMutation, useQuery, useSubscription, useSubscriptionCore };
+export { ComparisonFailError, type Connection, type MessageHandler, type MutateOptions, type MutationFunction, type MutationInfo, type MutationOptions, type QueryOptions, type SubscriptionCoreOptions, type SubscriptionCoreReturnType, type SubscriptionOptions, type TPromiseFunction, type TProxySubscriptionHandlerParams, type TSubscriptionHandlerFunction, type UseQueryResult, bindClientSocketProxy, bindPromiseFunction, buildMutationHook, buildQueryHook, buildServiceSubscriptionHook, useMutation, useQuery, useSubscription, useSubscriptionCore };