@triggery/query

Read cached TanStack Query data from a Triggery condition.

Install

pnpm add @triggery/core @triggery/react @triggery/query @tanstack/query-core
# (or @tanstack/react-query which re-exports query-core)

Usage

import { QueryClient } from '@tanstack/query-core';
import { createTrigger } from '@triggery/core';
import { useQueryCondition } from '@triggery/query';

type User = { id: string; name: string };

const queryClient = new QueryClient();

const messageTrigger = createTrigger<{
  events: { 'new-message': { text: string; from: string } };
  conditions: { user: User };
  actions: { showToast: { body: string } };
}>({
  id: 'message-received',
  events: ['new-message'],
  required: ['user'],
  handler({ event, conditions, actions }) {
    if (event.payload.from === conditions.user.id) return;
    actions.showToast?.({ body: event.payload.text });
  },
});

function CurrentUserBridge() {
  useQueryCondition<User, typeof messageTrigger['schema'], 'user'>(
    messageTrigger,
    'user',
    queryClient,
    ['user', 'current'],
  );
  return null;
}

With a selector:

useQueryCondition(messageTrigger, 'user', queryClient, ['profile'], (p) => p?.user);

How it works

Pull-only: queryClient.getQueryData(key) runs only when a trigger fires, not on every cache update. The host component is never subscribed to the query — use useQuery / useQueryClient alongside in components that render the data.

When the cache entry is missing, the condition value is undefined, which fails a required gate cleanly and skips the handler instead of throwing.

API

useQueryCondition<T, S, K>(
  trigger: Trigger<S>,
  name: K,
  queryClient: { getQueryData<T>(key): T | undefined },
  queryKey: readonly unknown[],
  selector?: (data: T | undefined) => ConditionMap<S>[K] | undefined,
): void

Documentation

Full documentation, recipes and API reference at https://triggeryjs.github.io/packages/query/.

Related packages

• @triggery/core — Required peer.
• @triggery/react — Required peer.
• @triggery/zustand — Adapter for non-server state.
• @triggery/redux — Adapter for non-server state.

See the full package list in the repo README.

License

MIT © Aleksey Skhomenko