QueryExplanation

interface · packages/remote/src/why.ts:61

interface QueryExplanation {
  readonly domain: string
  readonly query: string
  readonly input: unknown
  readonly identity: string
  readonly window: QueryWindow
  readonly select: RelationRequirement
  readonly body?: string | undefined
  readonly dependencies?: ExplainedDependencies | undefined
  readonly state: RemoteData<unknown>['_tag']
  readonly surfaces?: ReadonlyArray<string> | undefined
  readonly activation?:
    | ReadonlyArray<{
        readonly surface: string
        readonly path: readonly string[]
        readonly tag: string
      }>
    | undefined
}

What one query read is, and what it currently is — data-query-DESIGN §29.1.

Every member is gathered from something that already existed: the read was always this many pieces, and nothing had ever been asked to put them in one place. It is plain serializable data, so a DevTools panel, a log line and a test assert on the same value.

Two members of §29.1's sketch are not here, and their absence is the finding rather than an omission:

• Surface. A Projection does not know which Surface reads it, and often several do — so it is not a property of the read, and explain cannot recover it alone. Given the active Surfaces (the same record subscriptions takes), it reports every Surface reading the connection rather than guessing one, and omits the member entirely when it was not given them.
• Executor. The thing that answers a query is a RemoteClient Layer in the runtime, not a value in the Model, and a pure read of the Model cannot see it. That is the same boundary that makes this function pure and replayable, so it is worth more than the line of text.

And one that the design proposed and this does not want: expectation (required versus optional). §11 left it unbuilt for want of a consumer, and the explanation was the likeliest consumer. It turns out not to need it — a query's result is a connection, so the shape is a Page, decided by the definition rather than by the read. Nothing here has an opinion about whether an empty one is an error, because nothing here has to have one.

Members

readonly domain: string

readonly query: string

readonly input: unknown

readonly identity: string

readonly window: QueryWindow

readonly select: RelationRequirement

readonly body?: string | undefined

readonly dependencies?: ExplainedDependencies | undefined

readonly state: RemoteData<unknown>['_tag']

readonly surfaces?: ReadonlyArray<string> | undefined

readonly activation?:
  | ReadonlyArray<{
      readonly surface: string
      readonly path: readonly string[]
      readonly tag: string
    }>
  | undefined