@pixotope/query

React hooks for fetching, mutating and subscribing to data over Pixotope's ZMQ transport layer, react-query-style.

Install

pnpm add @pixotope/query

@pixotope/query has a peer dependency on react (>=17.0.0), which must be installed in the consuming app. It also relies on @pixotope/utils and @pixotope/zmq-client internally — these are resolved automatically as part of the workspace and you don't need to install them yourself, but you do need a ZMQClient (or a ZMQProxyWSClient wrapping one) to actually talk to a service, since that's the transport the hooks in this package send calls and subscriptions over.

Quick start

useQuery

Fetches data on mount, and refetches when its key changes or refetch is called explicitly.

import { useQuery } from "@pixotope/query";

function UserProfile({ userId }: { userId: string }) {
  const { data, status, error, refetch } = useQuery({
    key: ["user", userId],
    queryFn: () => fetchUser(userId),
  });

  if (status === "loading") return <p>Loading...</p>;
  if (status === "error") return <p>Failed to load: {String(error)}</p>;

  return (
    <div>
      <p>{data?.name}</p>
      <button onClick={() => refetch()}>Refresh</button>
    </div>
  );
}

useMutation

Triggers an async side effect on demand and tracks its status/result/error.

import { useMutation } from "@pixotope/query";

function CreateUserForm() {
  const { mutate, status } = useMutation({
    mutationFn: (vars: { name: string }) => createUser(vars),
  });

  return (
    <button
      disabled={status === "loading"}
      onClick={() =>
        mutate(
          { name: "Ada" },
          { onSuccess: (user) => console.log("created", user.id) }
        )
      }
    >
      Create user
    </button>
  );
}

useSubscription

Subscribes to a service/topic pair for as long as the component is mounted, exposing the latest message as data.

import { useSubscription } from "@pixotope/query";
import { bindClientSocketProxy } from "@pixotope/query";

function LiveStatus({ proxyClient }) {
  const { data, status } = useSubscription(bindClientSocketProxy(proxyClient), {
    service: "MyService",
    topic: "MyTopic",
  });

  return <p>[{status}] {JSON.stringify(data)}</p>;
}

API overview

• useQuery — fetch data on mount/key-change/interval/window-focus, with select, initialData, timeout and refetch support.
• useMutation — trigger an async side effect on demand and track its status/result/error, via mutate (fire-and-forget) or mutateAsync (awaitable).
• useSubscription — subscribe to a service/topic pair through a pluggable transport handler, managing subscribe/unsubscribe across the component lifecycle.
• useSubscriptionCore — the lower-level hook behind useSubscription; useful when building a subscription hook around a custom transport rather than a service/topic pair.
• buildServiceSubscriptionHook — builds a useSubscription-like hook pre-bound to a transport and machine/service resolver, for exposing a typed per-domain subscription hook.
• buildMutationHook / buildQueryHook — build typed useMutation/useQuery-like hooks for calling remote ZMQ functions by name, with data/error/params inferred per function from a TFnToParams map.
• bindClientSocketProxy / bindPromiseFunction — adapt a ZMQProxyWSClient (from @pixotope/zmq-client) into the transport functions expected by the subscription and factory hooks above.

See the generated API reference (pnpm typedoc) for full type signatures.