@everysk/apps-sdk 0.1.0 → 0.3.0-beta-20261016180126

package/src/hooks/useEntityMutation.ts

@@ -0,0 +1,70 @@
+import { useMutation, useQueryClient, type QueryKey } from "@tanstack/react-query";
+
+import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
+
+export type EntityMutationProps<TVariables, TResult> = {
+    /** Sends the write. Receives the variables passed to `mutate`, and only those. */
+    mutationFn: (variables: TVariables) => Promise<TResult>;
+    /**
+     * Invalidated after a success, so the screens reading it refetch. Pass the `queryKey` a fetch
+     * hook returned, or a prefix of it (`["datastores"]`) to refresh every list of that entity.
+     */
+    queryKey?: QueryKey;
+    /** Shown as a success alert. */
+    successMessage: string;
+    /** Shown as an error alert when the failure carries no message of its own. */
+    errorMessage: string;
+};
+
+/**
+ * useEntityMutation
+ *
+ * The write hook every SDK mutation is built on, and the one to build on for an endpoint the SDK
+ * does not cover — the counterpart of `useEntityQuery`. A hook says how to send the write and
+ * what to tell the user; this owns the cache invalidation and the alerts.
+ *
+ * It replaced nine copies of the same `useMutation` call across `useDatastoreMutations`,
+ * `useFileMutations` and `usePortfolioMutations`, which had already drifted apart in wording.
+ *
+ * The invalidation is awaited before the mutation resolves, so code after `mutateAsync` sees the
+ * refetched data rather than racing it.
+ *
+ * @returns {UseMutationResult} The `useMutation` result.
+ *
+ * Example:
+ * ```ts
+ * export const useReportMutations = ({ queryKey }: { queryKey?: QueryKey }) => {
+ *   const { api } = useAxios();
+ *
+ *   const share = useEntityMutation({
+ *     mutationFn: ({ id, workspace }: ShareReportProps) => shareReport(api, id, workspace),
+ *     queryKey,
+ *     successMessage: "Report shared successfully.",
+ *     errorMessage: "Unable to share the report. Please try again.",
+ *   });
+ *
+ *   return { share };
+ * };
+ * ```
+ */
+export function useEntityMutation<TVariables, TResult>({
+    mutationFn,
+    queryKey,
+    successMessage,
+    errorMessage,
+}: EntityMutationProps<TVariables, TResult>) {
+    const { showAlert } = useAppAlert();
+    const queryClient = useQueryClient();
+
+    return useMutation<TResult, Error, TVariables>({
+        // TanStack passes a context as a second argument; the request gets the variables alone.
+        mutationFn: (variables) => mutationFn(variables),
+        onSuccess: async () => {
+            if (queryKey?.length) await queryClient.invalidateQueries({ queryKey });
+            showAlert({ severity: "success", message: successMessage });
+        },
+        onError: (error) => {
+            showAlert({ severity: "error", message: error.message || errorMessage });
+        },
+    });
+}

package/src/hooks/useEntityQuery.ts

@@ -0,0 +1,117 @@
+import { useEffect } from "react";
+import { useQuery, type QueryKey } from "@tanstack/react-query";
+
+import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
+import { failWithConfigError } from "@/hooks/useEntityInfiniteQuery";
+import type { EntityQueryOptions } from "@/types/entityQuery";
+
+export type EntityQueryProps<TEntity, TData> = {
+    /** Must describe everything that changes the response: the entity's ids and workspace. */
+    queryKey: QueryKey;
+    /**
+     * Requests the entity. `signal` aborts when no screen wants it any more — pass it to the
+     * request (`api.get(url, { signal })`) to cancel it in flight.
+     */
+    fetchEntity: (signal: AbortSignal) => Promise<TEntity>;
+    select?: (entity: TEntity) => TData;
+    /**
+     * Your hook's own precondition for something legitimately not there yet — an id from a
+     * selection the user has not made — ANDed with the caller's `queryOptions.enabled`. Unmet,
+     * the query stays idle rather than send an empty id, which reaches another endpoint entirely.
+     */
+    enabled?: boolean;
+    /**
+     * Why the request cannot be right, when it cannot — `missingWorkspaceError(hookName)` in the
+     * SDK's hooks. Set, the query fails at once with it, without a request or a retry, logs it once
+     * with `console.error` and shows it as the error alert. See `useEntityInfiniteQuery`.
+     * It is reported even while `enabled` is unmet, so an empty id cannot hide a misconfigured
+     * workspace; only the caller's `queryOptions.enabled: false` holds it back.
+     */
+    configError?: string;
+    /** Replaces the SDK's defaults for this hook, as the profile does. */
+    defaultQueryOptions?: EntityQueryOptions<TEntity, TData>;
+    queryOptions?: EntityQueryOptions<TEntity, TData>;
+};
+
+/**
+ * The entity hooks read data the platform keeps changing, so by default nothing is cached:
+ * refetched on every mount, dropped as soon as no screen reads it.
+ */
+const sdkDefaultQueryOptions = {
+    refetchOnMount: "always",
+    staleTime: 0,
+    gcTime: 0,
+} as const;
+
+/**
+ * useEntityQuery
+ *
+ * The single-entity hook every SDK single-entity hook is built on, and the one to build on for
+ * an endpoint the SDK does not cover — the counterpart of `useEntityInfiniteQuery`. A hook says
+ * how to request the entity; this owns the defaults, the idle precondition, `select` and the
+ * error alert.
+ *
+ * It replaced eight copies of the same `useQuery` call, which is how one defect had reached all
+ * eight: each declared `queryOptions = defaultQueryOptions`, so passing any option replaced the
+ * defaults and the query fell back to TanStack's own (a 5-minute cache instead of none). Here
+ * the caller's options are merged over the defaults.
+ *
+ * A failure is shown through `useAppAlert`, as the entity hooks always have.
+ *
+ * @returns {UseQueryResult} The `useQuery` result; `data` is the entity, or what `select` makes
+ *   of it. The SDK's hooks spread it and add `queryKey`.
+ *
+ * Example:
+ * ```ts
+ * export const useFetchReport = <TData = Report>({ id, workspace, select, queryOptions }: Props<TData>) => {
+ *   const { api } = useAxios();
+ *   const queryKey = ["report", id, workspace];
+ *
+ *   const query = useEntityQuery<Report, TData>({
+ *     queryKey,
+ *     fetchEntity: (signal) => getReport(api, id, workspace, signal),
+ *     select,
+ *     enabled: Boolean(id),
+ *     configError: workspace ? undefined : missingWorkspaceError("useFetchReport"),
+ *     queryOptions,
+ *   });
+ *
+ *   return { ...query, queryKey };
+ * };
+ * ```
+ */
+export function useEntityQuery<TEntity, TData = TEntity>({
+    queryKey,
+    fetchEntity,
+    select,
+    enabled = true,
+    configError,
+    defaultQueryOptions = sdkDefaultQueryOptions,
+    queryOptions,
+}: EntityQueryProps<TEntity, TData>) {
+    const { showAlert } = useAppAlert();
+
+    const query = useQuery<TEntity, Error, TData>({
+        ...defaultQueryOptions,
+        ...queryOptions,
+
+        queryKey,
+        queryFn: async ({ signal }) =>
+            configError ? failWithConfigError(configError) : fetchEntity(signal),
+        // A retry would rerun the same check and delay an error that cannot resolve itself.
+        ...(configError ? { retry: false } : {}),
+        select,
+        // A config error runs past the hook's own precondition, so that an empty id cannot hide a
+        // misconfigured workspace; the caller's `enabled` still wins. Kept as the caller wrote it,
+        // so a function still works.
+        enabled: configError || enabled ? (queryOptions?.enabled ?? true) : false,
+    });
+
+    useEffect(() => {
+        if (!query.error) return;
+
+        showAlert({ severity: "error", message: query.error.message });
+    }, [query.error, showAlert]);
+
+    return query;
+}

package/src/hooks/workflow/useFetchWorkerExecution.ts

@@ -1,78 +1,49 @@
-import { useEffect } from "react";
-
-import { useQuery } from "@tanstack/react-query";
-
 import { useAxios } from "@/hooks/useAxios";
-import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
+import { useEntityQuery } from "@/hooks/useEntityQuery";
+import { missingWorkspaceError } from "@/api/entityQuery";
 import { getWorkerExecution } from "@/api/workflow";
 import type { WorkerExecution } from "@/types/workflow";
-import type { EntityQueryOptions } from "@/types/entityQuery";
+import type { FetchEntityProps } from "@/types/entityQuery";
 
-export type FetchWorkerExecutionProps<TData = WorkerExecution, TSelected = TData> = {
+export type FetchWorkerExecutionProps<
+    TData = WorkerExecution,
+    TSelected = TData,
+> = FetchEntityProps<TData, TSelected> & {
     workflowId: string;
     workerExecutionId: string;
     workspace: string;
-    queryOptions?: EntityQueryOptions<TData, TSelected>;
-};
-
-const defaultQueryOptions: EntityQueryOptions<WorkerExecution> = {
-    refetchOnMount: "always",
-    staleTime: 0,
-    gcTime: 0,
 };
 
 /**
  * useFetchWorkerExecution
  *
- * Data-fetching hook built on TanStack Query to retrieve a single worker execution.
- *
- * It also:
- * - builds a stable React Query `queryKey` that can be reused by mutation hooks for cache invalidation
- * - triggers an error alert via `useAppAlert` whenever `query.error` is present
- *
- * @param workflowId - Workflow identifier the worker execution belongs to (required).
- * @param workerExecutionId - Worker execution identifier (required).
- * @param workspace - Workspace the workflow belongs to (required).
- * @param queryOptions - TanStack Query options passed through to `useQuery` (e.g., enabled, staleTime, gcTime, etc.).
+ * Fetches one worker execution; `data` is the execution, or whatever `select` makes of it. Idle
+ * while an id is empty; fails loudly, without a request, while `workspace` is. A failure is shown as an error alert.
  *
- * @returns TanStack Query result extended with `queryKey`.
- *
- * Example:
- * ```ts
- * const { data, isLoading } = useFetchWorkerExecution({
- *   workflowId: "wf-123",
- *   workerExecutionId: "wkex-456",
- *   workspace: "main",
- * });
- * // data -> WorkerExecution
- * ```
+ * @param {FetchWorkerExecutionProps} props - `workflowId`, `workerExecutionId`, `workspace`,
+ *   `select` and TanStack `queryOptions`.
+ * @returns {object} The `useQuery` result, plus `queryKey`.
  */
-export const useFetchWorkerExecution = ({ workflowId, workerExecutionId, workspace, queryOptions = defaultQueryOptions }: FetchWorkerExecutionProps) => {
-
+export const useFetchWorkerExecution = <TSelected = WorkerExecution>({
+    workflowId,
+    workerExecutionId,
+    workspace,
+    select,
+    queryOptions,
+}: FetchWorkerExecutionProps<WorkerExecution, TSelected>) => {
     const { api } = useAxios();
-    const { showAlert } = useAppAlert();
 
     const queryKey = ["worker_execution", workflowId, workerExecutionId, workspace];
 
-    const query = useQuery<WorkerExecution>({
+    const query = useEntityQuery<WorkerExecution, TSelected>({
         queryKey,
-        queryFn: async () => {
-            return await getWorkerExecution(api, workflowId, workerExecutionId, workspace);
-        },
-        ...queryOptions ?? {}
+        fetchEntity: (signal) =>
+            getWorkerExecution(api, workflowId, workerExecutionId, workspace, signal),
+        select,
+        enabled: Boolean(workflowId) && Boolean(workerExecutionId),
+        configError: workspace ? undefined : missingWorkspaceError("useFetchWorkerExecution"),
+        queryOptions,
     });
 
-    useEffect(() => {
-        if (!query.error) return;
-
-        showAlert({
-            severity: "error",
-            message: query.error.message,
-        });
-    }, [query.error, showAlert]);
-
-    return {
-        ...query,
-        queryKey,
-    };
+    return { ...query, queryKey };
 };

package/src/hooks/workflow/useFetchWorkerExecutions.ts

@@ -1,98 +1,73 @@
-import { useMemo } from "react";
-import { useInfiniteQuery, type UseInfiniteQueryOptions, type QueryKey } from "@tanstack/react-query";
-
 import { useAxios } from "@/hooks/useAxios";
+import { useEntityQuery } from "@/hooks/useEntityQuery";
 import { listWorkerExecutions } from "@/api/workflow";
-import type { FetchEntitiesParams } from "@/types/entityQuery";
-import { buildQueryKey, buildQueryObject } from "@/api/entityQuery";
-import type { WorkerExecution, WorkerExecutionListResponse } from "@/types/workflow";
-
-type PageToken = string | null;
+import { missingWorkspaceError } from "@/api/entityQuery";
+import type { FetchEntityProps } from "@/types/entityQuery";
+import type { WorkerExecutionGroup } from "@/types/workflow";
 
-type InfiniteOptions<TData> = Omit<UseInfiniteQueryOptions<WorkerExecutionListResponse, Error, TData, QueryKey, PageToken>, "queryKey" | "queryFn" | "initialPageParam" | "getNextPageParam">;
-
-export type FetchInfiniteWorkerExecutionProps = FetchEntitiesParams<WorkerExecution[], InfiniteOptions<WorkerExecution[]>> & {
+export type FetchWorkerExecutionsProps<
+    TData = WorkerExecutionGroup[],
+    TSelected = TData,
+> = FetchEntityProps<TData, TSelected> & {
     workflowId: string;
     workflowExecutionId: string;
-    pageSize?: number;
-};
-
-const defaultQueryOptions: InfiniteOptions<WorkerExecution[]> = {
-    refetchOnMount: "always",
-    staleTime: 0,
-    gcTime: 0,
+    workspace: string;
+    /** Include each run's `result` and `input_params`. The API leaves them out by default. */
+    withResult?: boolean;
 };
 
 /**
  * useFetchWorkerExecutions
  *
- * Data-fetching hook built on TanStack Query's `useInfiniteQuery` to retrieve
- * worker executions for a given workflow with cursor-based pagination.
- *
- * Automatically flattens all pages into a single `WorkerExecution[]` via `select`.
- *
- * Note: `query.data` returns a flat `WorkerExecution[]` with all fetched items merged across pages.
- *
- * @param workflowId - Workflow identifier whose worker executions to fetch (required).
- * @param workflowExecutionId - Workflow execution identifier to filter worker executions (required).
- * @param filters - Filters applied to every page request. Must include a `workspace` filter.
- * @param order - Sorting applied to every page request.
- * @param projection - Single field to project: `"field"` returns only that field (others come
- *   back null), `"-field"` returns every field except that one. One field only — lists 500. Omitted when empty.
- * @param pageSize - Number of executions to fetch per page. Defaults to `10`.
- * @param queryOptions - TanStack Query options passed through to `useInfiniteQuery`.
+ * Fetches every worker execution of one workflow execution, grouped by worker; `data` is the
+ * groups, or whatever `select` makes of them. Narrow a group on `is_parallel_execution`: a
+ * worker that ran in parallel carries every run under `executions`, any other one its run as
+ * `execution`. Idle while an id is empty; fails loudly, without a request, while `workspace` is.
+ * A failure is shown as an error alert.
  *
- * @returns
- *   - `query`: the full `useInfiniteQuery` result (data, isLoading, hasNextPage, fetchNextPage, etc.)
- *   - `queryKey`: the cache key used by React Query
+ * A plain query, not an infinite one, and so shaped like the single-entity hooks: the endpoint
+ * returns the whole set at once, with no cursor to page by. It used to be paged, over a JSON
+ * query the endpoint ignores, and typed as a flat list of worker executions.
  *
- * @example
- * ```ts
- * const { query } = useFetchWorkerExecutions({
- *   workflowId: "wf-123",
- *   workflowExecutionId: "wfex-456",
- *   filters: [{ field: "workspace", value: "main" }],
- *   pageSize: 20,
- * });
- *
- * // Flat list of all fetched worker executions
- * const workerExecutions = query.data ?? [];
- * ```
+ * @param {FetchWorkerExecutionsProps} props - Workflow and execution ids, workspace,
+ *   `withResult`, `select` and TanStack `queryOptions`.
+ * @returns {object} The `useQuery` result, plus `queryKey`.
  */
-export function useFetchWorkerExecutions({ workflowId, workflowExecutionId, filters = [], order = [], projection = "", pageSize = 10, queryOptions }: FetchInfiniteWorkerExecutionProps) {
+export const useFetchWorkerExecutions = <TSelected = WorkerExecutionGroup[]>({
+    workflowId,
+    workflowExecutionId,
+    workspace,
+    withResult,
+    select,
+    queryOptions,
+}: FetchWorkerExecutionsProps<WorkerExecutionGroup[], TSelected>) => {
     const { api } = useAxios();
 
-    const queryKey = buildQueryKey(["worker_executions", workflowId, workflowExecutionId], filters);
-
-    const mergedQueryOptions = useMemo<InfiniteOptions<WorkerExecution[]>>(() => ({
-        ...defaultQueryOptions,
-        ...(queryOptions ?? {}),
-    }), [queryOptions]);
+    const queryKey = [
+        "worker_executions",
+        workflowId,
+        workflowExecutionId,
+        workspace,
+        withResult ?? null,
+    ];
 
-    const query = useInfiniteQuery<WorkerExecutionListResponse, Error, WorkerExecution[], QueryKey, PageToken>({
+    const query = useEntityQuery<WorkerExecutionGroup[], TSelected>({
         queryKey,
-        initialPageParam: null,
-        getNextPageParam: (lastPage) => lastPage.next_page_token ?? undefined,
-
-        queryFn: async ({ pageParam }) => {
-            const queryFilter = buildQueryObject({
-                filters,
-                order,
-                projection,
-                pageSize,
-                pageToken: pageParam ?? undefined,
-            });
-
-            return await listWorkerExecutions(api, workflowId, workflowExecutionId, queryFilter);
-        },
-
-        select: (data) => data.pages.flatMap((p) => p.worker_executions),
-
-        ...mergedQueryOptions,
+        fetchEntity: async (signal) =>
+            (
+                await listWorkerExecutions(
+                    api,
+                    workflowId,
+                    workflowExecutionId,
+                    { workspace, withResult },
+                    signal,
+                )
+            ).worker_executions,
+        select,
+        enabled: Boolean(workflowId) && Boolean(workflowExecutionId),
+        configError: workspace ? undefined : missingWorkspaceError("useFetchWorkerExecutions"),
+        queryOptions,
     });
 
-    return {
-        query,
-        queryKey,
-    };
-}
+    return { ...query, queryKey };
+};

package/src/hooks/workflow/useFetchWorkflow.ts

@@ -1,76 +1,42 @@
-import { useEffect } from "react";
-
-import { useQuery } from "@tanstack/react-query";
-
 import { useAxios } from "@/hooks/useAxios";
-import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
+import { useEntityQuery } from "@/hooks/useEntityQuery";
+import { missingWorkspaceError } from "@/api/entityQuery";
 import { getWorkflow } from "@/api/workflow";
 import type { Workflow } from "@/types/workflow";
-import type { EntityQueryOptions, FetchEntityParams } from "@/types/entityQuery";
-
-export type FetchWorkflowProps<TData = Workflow, TSelected = TData> = FetchEntityParams<TData, TSelected>;
+import type { FetchEntityByIdProps } from "@/types/entityQuery";
 
-const defaultQueryOptions: EntityQueryOptions<Workflow> = {
-    refetchOnMount: "always",
-    staleTime: 0,
-    gcTime: 0
-}
+export type FetchWorkflowProps<TData = Workflow, TSelected = TData> = FetchEntityByIdProps<
+    TData,
+    TSelected
+>;
 
 /**
  * useFetchWorkflow
  *
- * Data-fetching hook built on TanStack Query to retrieve a single workflow by ID.
- *
- * It also:
- * - builds a stable React Query `queryKey` that can be reused by mutation hooks for cache invalidation
- * - triggers an error alert via `useAppAlert` whenever `query.error` is present
- *
- * @param id - Workflow identifier (required).
- * @param workspace - Workspace the workflow belongs to (required).
- * @param queryOptions - TanStack Query options passed through to `useQuery` (e.g., enabled, staleTime, gcTime, etc.).
- *
- * @returns TanStack Query result extended with `queryKey`.
+ * Fetches one workflow; `data` is the workflow, or whatever `select` makes of it. Idle while
+ * `id` is empty; fails loudly, without a request, while `workspace` is. A failure is shown as an error alert.
  *
- * Tip:
- * - The returned `queryKey` can be reused by mutation hooks for cache invalidation:
- *   ```ts
- *   const fetch = useFetchWorkflow({ id: "wf-123", workspace: "main" });
- *   useWorkflowMutations({ queryKey: fetch.queryKey });
- *   ```
- *
- * Example:
- * ```ts
- * const { data, isLoading } = useFetchWorkflow({ id: "wf-123", workspace: "main" });
- * // data -> Workflow
- * ```
+ * @param {FetchWorkflowProps} props - `id`, `workspace`, `select` and TanStack `queryOptions`.
+ * @returns {object} The `useQuery` result, plus `queryKey`.
  */
-export const useFetchWorkflow = ({ id, workspace, queryOptions = defaultQueryOptions }: FetchWorkflowProps) => {
-
+export const useFetchWorkflow = <TSelected = Workflow>({
+    id,
+    workspace,
+    select,
+    queryOptions,
+}: FetchWorkflowProps<Workflow, TSelected>) => {
     const { api } = useAxios();
-    const { showAlert } = useAppAlert();
 
     const queryKey = ["workflow", id, workspace];
 
-    const query = useQuery<Workflow>({
+    const query = useEntityQuery<Workflow, TSelected>({
         queryKey,
-        queryFn: async () => {
-            const workflow = await getWorkflow(api, id, workspace);
-            return workflow;
-        },
-        ...queryOptions ?? {}
+        fetchEntity: (signal) => getWorkflow(api, id, workspace, signal),
+        select,
+        enabled: Boolean(id),
+        configError: workspace ? undefined : missingWorkspaceError("useFetchWorkflow"),
+        queryOptions,
     });
 
-    useEffect(() => {
-        if (!query.error) return;
-
-        showAlert({
-            severity: "error",
-            message: query.error.message,
-        });
-    }, [query.error, showAlert]);
-
-    return {
-        ...query,
-        queryKey,
-    };
+    return { ...query, queryKey };
 };

package/src/hooks/workflow/useFetchWorkflowExecution.ts

@@ -1,79 +1,49 @@
-import { useEffect } from "react";
-
-import { useQuery } from "@tanstack/react-query";
-
 import { useAxios } from "@/hooks/useAxios";
-import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
+import { useEntityQuery } from "@/hooks/useEntityQuery";
+import { missingWorkspaceError } from "@/api/entityQuery";
 import { getWorkflowExecution } from "@/api/workflow";
 import type { WorkflowExecution } from "@/types/workflow";
-import type { EntityQueryOptions } from "@/types/entityQuery";
+import type { FetchEntityProps } from "@/types/entityQuery";
 
-export type FetchWorkflowExecutionProps<TData = WorkflowExecution, TSelected = TData> = {
+export type FetchWorkflowExecutionProps<
+    TData = WorkflowExecution,
+    TSelected = TData,
+> = FetchEntityProps<TData, TSelected> & {
     workflowId: string;
     workflowExecutionId: string;
     workspace: string;
-    queryOptions?: EntityQueryOptions<TData, TSelected>;
-};
-
-const defaultQueryOptions: EntityQueryOptions<WorkflowExecution> = {
-    refetchOnMount: "always",
-    staleTime: 0,
-    gcTime: 0,
 };
 
 /**
  * useFetchWorkflowExecution
  *
- * Data-fetching hook built on TanStack Query to retrieve a single workflow execution.
- *
- * It also:
- * - builds a stable React Query `queryKey` that can be reused by mutation hooks for cache invalidation
- * - triggers an error alert via `useAppAlert` whenever `query.error` is present
- *
- * @param workflowId - Workflow identifier the execution belongs to (required).
- * @param workflowExecutionId - Workflow execution identifier (required).
- * @param workspace - Workspace the workflow belongs to (required).
- * @param queryOptions - TanStack Query options passed through to `useQuery` (e.g., enabled, staleTime, gcTime, etc.).
+ * Fetches one execution of a workflow; `data` is the execution, or whatever `select` makes of
+ * it. Idle while an id is empty; fails loudly, without a request, while `workspace` is. A failure is shown as an error alert.
  *
- * @returns TanStack Query result extended with `queryKey`.
- *
- * Example:
- * ```ts
- * const { data, isLoading } = useFetchWorkflowExecution({
- *   workflowId: "wf-123",
- *   workflowExecutionId: "exec-456",
- *   workspace: "main",
- * });
- * // data -> WorkflowExecution
- * ```
+ * @param {FetchWorkflowExecutionProps} props - `workflowId`, `workflowExecutionId`, `workspace`,
+ *   `select` and TanStack `queryOptions`.
+ * @returns {object} The `useQuery` result, plus `queryKey`.
  */
-export const useFetchWorkflowExecution = ({ workflowId, workflowExecutionId, workspace, queryOptions = defaultQueryOptions }: FetchWorkflowExecutionProps) => {
-
+export const useFetchWorkflowExecution = <TSelected = WorkflowExecution>({
+    workflowId,
+    workflowExecutionId,
+    workspace,
+    select,
+    queryOptions,
+}: FetchWorkflowExecutionProps<WorkflowExecution, TSelected>) => {
     const { api } = useAxios();
-    const { showAlert } = useAppAlert();
 
     const queryKey = ["workflow_execution", workflowId, workflowExecutionId, workspace];
 
-    const query = useQuery<WorkflowExecution>({
+    const query = useEntityQuery<WorkflowExecution, TSelected>({
         queryKey,
-        queryFn: async () => {
-            const execution = await getWorkflowExecution(api, workflowId, workflowExecutionId, workspace);
-            return execution;
-        },
-        ...queryOptions ?? {}
+        fetchEntity: (signal) =>
+            getWorkflowExecution(api, workflowId, workflowExecutionId, workspace, signal),
+        select,
+        enabled: Boolean(workflowId) && Boolean(workflowExecutionId),
+        configError: workspace ? undefined : missingWorkspaceError("useFetchWorkflowExecution"),
+        queryOptions,
     });
 
-    useEffect(() => {
-        if (!query.error) return;
-
-        showAlert({
-            severity: "error",
-            message: query.error.message,
-        });
-    }, [query.error, showAlert]);
-
-    return {
-        ...query,
-        queryKey,
-    };
+    return { ...query, queryKey };
 };