query

Import

Import

import * as api from "@fungi.computer/agar/query";

Exports

Kind	Export	Description
Ttype alias	FeedSnapshot	A feed can lose its connection without losing its last owner snapshot.
Ttype alias	FeedWatch	Start a live feed, calling onChange with each snapshot until signal aborts; the returned (or resolved) Disposer tears it down.
Ttype alias	QueryApp	The App-owned identity and grants needed by the query integration.
constconstant	queryKeys	Cache identity belongs to an App surface and its selected Computer.
fnfunction	useFeedQuery()	Query owns sharing and teardown; Effect supplies a bounded latest-snapshot queue.
fnfunction	createQueryClient()	App defaults and grant lifetime binding, using the host’s ordinary cache.
fnfunction	capabilityQuery()	Decode capabilities through their owner; Query owns cancellation and retries.
fnfunction	optimisticMutation()	Optimistic writes for one cache entry, followed by owner reconciliation. Apply must return new data. Concurrent writes to this key run in order; queued writes wait for reconciliation instead of stacking rollback snapshots.
fnfunction	useMemberInbox()	One shared inbox watch; reloads and stream failures retain the last live rows.

FeedSnapshotTtype alias

Signature

type FeedSnapshot<T> =
  | Readonly<{
      status: "live";
      data: T;
    }>
  | Readonly<{
      status: "loading" | "error";
      data?: T;
    }>;

A feed can lose its connection without losing its last owner snapshot.

Type Parameters

Type Parameter
T

---

FeedWatchTtype alias

Signature

type FeedWatch<T> = (onChange, signal) => Disposer | Promise<Disposer>;

Start a live feed, calling onChange with each snapshot until signal aborts; the returned (or resolved) Disposer tears it down.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
onChange	(snapshot) => void
signal	AbortSignal

Returns

| Disposer | Promise<Disposer>

---

QueryAppTtype alias

Signature

type QueryApp = Pick<AppRoot, "identity" | "context" | "capabilities">;

The App-owned identity and grants needed by the query integration.

queryKeysconstconstant

Signature

const queryKeys: object;

Cache identity belongs to an App surface and its selected Computer.

Type Declaration

Name	Type	Description
of()	(app, …parts) => readonly [string | null, string | null, unknown]	Build a cache key scoped to this App’s surface and its currently selected Computer, followed by the given key parts.

useFeedQuery()fnfunction

Signature

function useFeedQuery<T>(
  queryKey,
  watch,
  options?,
): UseQueryResult<FeedSnapshot<T>, AppError>;

Query owns sharing and teardown; Effect supplies a bounded latest-snapshot queue.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
queryKey	readonly unknown[]
watch	FeedWatch<T>
options	{ enabled?: boolean; meta?: Record<string, unknown>; }
options.enabled?	boolean
options.meta?	Record<string, unknown>

Returns

UseQueryResult<FeedSnapshot<T>, AppError>

---

createQueryClient()fnfunction

Signature

function createQueryClient(): QueryClient;

App defaults and grant lifetime binding, using the host’s ordinary cache.

Returns

QueryClient

---

capabilityQuery()fnfunction

Signature

function capabilityQuery<H, T>(
  app,
  contract,
  queryKey,
  run,
): OmitKeyof<UseQueryOptions<T, AppError, T, readonly unknown[]>, "queryFn"> &
  object &
  QueryKeyWithDataTag<readonly unknown[], T, AppError>;

Decode capabilities through their owner; Query owns cancellation and retries.

Type Parameters

Type Parameter
H
T

Parameters

Parameter	Type
app	QueryApp | null
contract	CapabilityContract<H>
queryKey	readonly unknown[]
run	(handle, signal) => Promise<T>

Returns

OmitKeyof<UseQueryOptions<T, AppError, T, readonly unknown[]>, "queryFn"> & object & QueryKeyWithDataTag<readonly unknown[], T, AppError>

---

optimisticMutation()fnfunction

Signature

function optimisticMutation<TData, TVars, TResult>(
  options,
): WithRequired<
  UseMutationOptions<
    TResult,
    AppError,
    TVars,
    | {
        previous: TData;
        optimistic: TData | undefined;
      }
    | undefined
  >,
  "mutationKey"
>;

Optimistic writes for one cache entry, followed by owner reconciliation. Apply must return new data. Concurrent writes to this key run in order; queued writes wait for reconciliation instead of stacking rollback snapshots.

Type Parameters

Type Parameter	Default type
TData	-
TVars	-
TResult	unknown

Parameters

Parameter	Type
options	{ queryKey: readonly unknown[]; mutationFn: MutationFunction<TResult, TVars>; apply: (previous, variables) => TData; }
options.queryKey	readonly unknown[]
options.mutationFn	MutationFunction<TResult, TVars>
options.apply	(previous, variables) => TData

Returns

WithRequired<UseMutationOptions<TResult, AppError, TVars, | { previous: TData; optimistic: TData | undefined; } | undefined>, "mutationKey">

---

useMemberInbox()fnfunction

Signature

function useMemberInbox(app): object;

One shared inbox watch; reloads and stream failures retain the last live rows.

Parameters

Parameter	Type
app	QueryApp | null

Returns

Name	Type	Default value	Description
items	readonly ( | { agentId: string; sessionId: string; title: string; triggerId?: string; createdAt: number; lastActivityAt: number; settledAt?: number; visitedAt?: number; state: "running" | "done" | "needs_you" | "errored"; } | { agentId: string; sessionId: string; state: "unavailable"; } | { kind: "workflow-review"; key: { runId: string; nodeId: string; iteration: string; }; installationId: string; workflowId: string | null; workflowTitle: string; reviewTitle: string; reviewers: "runner" | "owners"; show: readonly Json[]; choices?: readonly string[]; openedAt: number; expiresAt: number; state: "pending" | "answered" | "closed" | "delivered" | "timed_out"; })[]	-	-
status	"error" | "loading" | "live"	-	-
error	AppError | null	query.error	-
refresh()	() => void	-	Restart the inbox watch; use after a change that the live feed would not otherwise observe.
visit()	(agentId, sessionId) => Promise<void>	-	Record that the member visited one agent session, so the inbox can clear its unread state for it.