@tanstack/lit-query 0.0.1 → 0.2.0

package/src/QueryClientProvider.ts

@@ -0,0 +1,174 @@
+import { ContextProvider } from '@lit/context'
+import type { QueryClient } from '@tanstack/query-core'
+import type { TemplateResult } from 'lit'
+import { LitElement, html } from 'lit'
+import {
+  createMissingQueryClientError,
+  queryClientContext,
+  registerDefaultQueryClient,
+  unregisterDefaultQueryClient,
+} from './context.js'
+
+/**
+ * Lit element that provides a `QueryClient` to descendant Lit Query
+ * controllers through Lit context.
+ *
+ * The `client` is a property, not an attribute. When rendering this element in
+ * a Lit template, bind it with property binding: `.client=${queryClient}`.
+ * The provider throws if it connects without a client, or if an already
+ * connected provider has its client cleared.
+ *
+ * This class is not registered as a custom element by the package. Applications
+ * must register either a subclass or the class itself with
+ * `customElements.define`.
+ *
+ * @example
+ * ```ts
+ * import { html, LitElement } from 'lit'
+ * import { QueryClient, QueryClientProvider } from '@tanstack/lit-query'
+ *
+ * const queryClient = new QueryClient()
+ *
+ * class AppQueryProvider extends QueryClientProvider {
+ *   constructor() {
+ *     super()
+ *     this.client = queryClient
+ *   }
+ * }
+ *
+ * customElements.define('app-query-provider', AppQueryProvider)
+ *
+ * class AppRoot extends LitElement {
+ *   render() {
+ *     return html`<app-query-provider><todos-view></todos-view></app-query-provider>`
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { html } from 'lit'
+ * import { QueryClient, QueryClientProvider } from '@tanstack/lit-query'
+ *
+ * const queryClient = new QueryClient()
+ *
+ * customElements.define('query-client-provider', QueryClientProvider)
+ *
+ * const view = html`
+ *   <query-client-provider .client=${queryClient}>
+ *     <todos-view></todos-view>
+ *   </query-client-provider>
+ * `
+ * ```
+ */
+export class QueryClientProvider extends LitElement {
+  /** @internal */
+  static properties = {
+    client: { attribute: false },
+  }
+
+  /**
+   * The `QueryClient` provided to descendant controllers and global fallback
+   * helpers while this provider is connected.
+   *
+   * Bind this as a property in Lit templates with `.client=${queryClient}`.
+   */
+  declare client: QueryClient
+
+  private readonly contextProvider: ContextProvider<typeof queryClientContext>
+
+  private mountedClient: QueryClient | undefined
+
+  constructor() {
+    super()
+    this.contextProvider = new ContextProvider(this, {
+      context: queryClientContext,
+    })
+  }
+
+  /** @internal */
+  connectedCallback(): void {
+    super.connectedCallback()
+    const client = this.requireClient()
+    this.contextProvider.setValue(client)
+    this.mountClient(client)
+  }
+
+  /** @internal */
+  disconnectedCallback(): void {
+    this.unmountClient(this.mountedClient)
+    super.disconnectedCallback()
+  }
+
+  /** @internal */
+  protected willUpdate(changedProperties: Map<PropertyKey, unknown>): void {
+    if (!changedProperties.has('client')) {
+      return
+    }
+
+    const nextClient = this.client
+    if (!nextClient) {
+      if (this.isConnected) {
+        this.unmountClient(this.mountedClient)
+        // Sentinel: notify active consumers that the provider is now unbound.
+        this.contextProvider.setValue(undefined as unknown as QueryClient)
+        throw createMissingQueryClientError()
+      }
+
+      return
+    }
+
+    const previousClient = changedProperties.get('client') as
+      | QueryClient
+      | undefined
+    if (previousClient && previousClient !== nextClient && this.isConnected) {
+      this.unmountClient(previousClient)
+    }
+
+    this.contextProvider.setValue(nextClient)
+
+    if (this.isConnected) {
+      this.mountClient(nextClient)
+    }
+  }
+
+  /** @internal */
+  render(): TemplateResult {
+    return html`<slot></slot>`
+  }
+
+  private mountClient(client: QueryClient): void {
+    if (this.mountedClient === client) {
+      return
+    }
+
+    if (this.mountedClient) {
+      this.unmountClient(this.mountedClient)
+    }
+
+    client.mount()
+    registerDefaultQueryClient(client)
+    this.mountedClient = client
+  }
+
+  private unmountClient(client?: QueryClient): void {
+    if (!client) {
+      return
+    }
+
+    client.unmount()
+    unregisterDefaultQueryClient(client)
+
+    if (this.mountedClient === client) {
+      this.mountedClient = undefined
+    }
+  }
+
+  private requireClient(): QueryClient {
+    if (!this.client) {
+      throw createMissingQueryClientError()
+    }
+
+    return this.client
+  }
+}

package/src/accessor.ts

@@ -0,0 +1,43 @@
+/**
+ * A value that can be passed directly or read from a zero-argument getter.
+ *
+ * Lit Query APIs read function accessors during host updates, so the getter can
+ * depend on reactive host state.
+ *
+ * @example
+ * ```ts
+ * const staticKey: Accessor<readonly unknown[]> = ['todos']
+ * const reactiveKey: Accessor<readonly unknown[]> = () => ['todos', this.userId]
+ * ```
+ */
+export type Accessor<T> = T | (() => T)
+
+export function readAccessor<T>(value: Accessor<T>): T {
+  return typeof value === 'function' ? (value as () => T)() : value
+}
+
+/**
+ * A callable accessor with a `current` property for reading the latest
+ * controller result.
+ *
+ * Controller creators and cache state helpers return this shape so render code
+ * can use either `result()` or `result.current`.
+ *
+ * @example
+ * ```ts
+ * const query = this.todos()
+ * const sameQuery = this.todos.current
+ * ```
+ */
+export type ValueAccessor<T> = (() => T) & {
+  readonly current: T
+}
+
+export function createValueAccessor<T>(getter: () => T): ValueAccessor<T> {
+  const accessor = (() => getter()) as ValueAccessor<T>
+  Object.defineProperty(accessor, 'current', {
+    get: getter,
+    enumerable: true,
+  })
+  return accessor
+}

package/src/context.ts

@@ -0,0 +1,120 @@
+import { createContext } from '@lit/context'
+import type { QueryClient } from '@tanstack/query-core'
+
+/**
+ * Lit context key used by `QueryClientProvider` and host-bound APIs to share a
+ * `QueryClient` through the DOM tree.
+ *
+ * Most applications use `QueryClientProvider` instead of interacting with this
+ * context directly.
+ */
+export const queryClientContext = createContext<QueryClient>(
+  Symbol.for('tanstack-query-client'),
+)
+
+const missingQueryClientMessage =
+  'No QueryClient available. Pass one explicitly or render within QueryClientProvider.'
+const ambiguousQueryClientMessage =
+  'Multiple QueryClients are mounted. Pass one explicitly instead of relying on global QueryClient helpers.'
+
+const registeredClients = new Map<QueryClient, number>()
+let defaultClient: QueryClient | undefined
+
+/**
+ * Registers a `QueryClient` as a process-local fallback for APIs that resolve a
+ * client without an explicit argument.
+ *
+ * `QueryClientProvider` calls this automatically while it is connected. Prefer
+ * passing an explicit client or rendering under a provider when possible.
+ *
+ * @param client - The query client to register as the current default.
+ */
+export function registerDefaultQueryClient(client: QueryClient): void {
+  registeredClients.set(client, (registeredClients.get(client) ?? 0) + 1)
+  defaultClient = client
+}
+
+/**
+ * Unregisters a client previously registered with
+ * `registerDefaultQueryClient`.
+ *
+ * `QueryClientProvider` calls this automatically when it disconnects.
+ *
+ * @param client - The query client registration to release.
+ */
+export function unregisterDefaultQueryClient(client: QueryClient): void {
+  const count = registeredClients.get(client)
+  if (count === undefined) {
+    return
+  }
+
+  if (count > 1) {
+    registeredClients.set(client, count - 1)
+    return
+  }
+
+  registeredClients.delete(client)
+  if (defaultClient !== client) {
+    return
+  }
+
+  const remaining = [...registeredClients.keys()]
+  defaultClient = remaining.at(-1)
+}
+
+/**
+ * Returns the registered default `QueryClient`, if exactly one default client is
+ * available.
+ *
+ * @returns The default query client, or `undefined` when there is no registered
+ * client or more than one registered client.
+ */
+export function getDefaultQueryClient(): QueryClient | undefined {
+  if (registeredClients.size > 1) {
+    return undefined
+  }
+
+  return defaultClient
+}
+
+export function createMissingQueryClientError(): Error {
+  return new Error(missingQueryClientMessage)
+}
+
+function createAmbiguousQueryClientError(): Error {
+  return new Error(ambiguousQueryClientMessage)
+}
+
+/**
+ * Resolves the current default `QueryClient` registered by a connected
+ * `QueryClientProvider`.
+ *
+ * This helper is useful outside a Lit reactive controller when a single
+ * provider is mounted. It throws if no client is registered or if multiple
+ * clients are mounted and the default would be ambiguous.
+ *
+ * @returns The single registered query client.
+ */
+export function useQueryClient(): QueryClient {
+  const client = getDefaultQueryClient()
+  if (client) {
+    return client
+  }
+
+  if (registeredClients.size > 1) {
+    throw createAmbiguousQueryClientError()
+  }
+
+  throw createMissingQueryClientError()
+}
+
+/**
+ * Resolves an explicit `QueryClient` or falls back to `useQueryClient`.
+ *
+ * @param explicit - Optional client supplied by the caller.
+ * @returns The explicit client when provided, otherwise the current default
+ * client.
+ */
+export function resolveQueryClient(explicit?: QueryClient): QueryClient {
+  return explicit ?? useQueryClient()
+}

package/src/controllers/BaseController.ts

@@ -0,0 +1,284 @@
+import { ContextEvent } from '@lit/context'
+import type { QueryClient } from '@tanstack/query-core'
+import type { ReactiveController, ReactiveControllerHost } from 'lit'
+import {
+  createMissingQueryClientError,
+  queryClientContext,
+} from '../context.js'
+
+type QueryClientResolutionState =
+  | 'pre-connect'
+  | 'awaiting-context'
+  | 'bound'
+  | 'missing'
+
+export abstract class BaseController<TResult> implements ReactiveController {
+  protected result: TResult
+
+  private readonly explicitClient?: QueryClient
+  private contextClient: QueryClient | undefined
+  private contextUnsubscribe: (() => void) | undefined
+
+  private connected = false
+  private destroyed = false
+  private updateQueued = false
+  private clientChangeQueued = false
+  private connectionAttempt = 0
+  private queryClientResolutionState: QueryClientResolutionState
+
+  protected constructor(
+    protected readonly host: ReactiveControllerHost,
+    initialResult: TResult,
+    queryClient?: QueryClient,
+  ) {
+    this.explicitClient = queryClient
+    this.result = initialResult
+    this.queryClientResolutionState = queryClient ? 'bound' : 'pre-connect'
+
+    host.addController(this)
+  }
+
+  hostConnected(): void {
+    if (this.connected || this.destroyed) {
+      return
+    }
+
+    this.connected = true
+    let contextResolutionAttempt: number | undefined
+
+    if (this.explicitClient) {
+      this.queryClientResolutionState = 'bound'
+    } else {
+      contextResolutionAttempt = ++this.connectionAttempt
+      this.beginContextResolution()
+    }
+
+    // Defer onConnected to ensure subclass constructors complete before
+    // lifecycle callbacks access subclass state. This handles the case where
+    // addController is called on an already-connected host (e.g., during
+    // willUpdate), which synchronously triggers hostConnected before
+    // subclass field initialization.
+    queueMicrotask(() => {
+      if (this.connected && !this.destroyed) {
+        this.onConnected()
+      }
+    })
+
+    if (contextResolutionAttempt !== undefined) {
+      // Provider-backed controllers on already-connected hosts should finish
+      // their deferred onConnected pass before a context client binds.
+      this.queueContextResolution(contextResolutionAttempt)
+    }
+  }
+
+  hostDisconnected(): void {
+    if (!this.connected) {
+      return
+    }
+
+    this.connected = false
+
+    if (!this.explicitClient) {
+      this.connectionAttempt += 1
+      this.clearContextClient()
+      this.updateQueryClientResolutionState('pre-connect')
+    }
+
+    this.onDisconnected()
+  }
+
+  hostUpdate(): void {
+    if (this.destroyed) {
+      return
+    }
+
+    this.onHostUpdate()
+  }
+
+  destroy(): void {
+    if (this.destroyed) {
+      return
+    }
+
+    this.destroyed = true
+    this.connected = false
+    this.connectionAttempt += 1
+    this.clearContextClient()
+    this.queryClientResolutionState = this.explicitClient
+      ? 'bound'
+      : 'pre-connect'
+    this.onDisconnected()
+
+    if ('removeController' in this.host) {
+      this.host.removeController(this)
+    }
+  }
+
+  protected tryGetQueryClient(): QueryClient | undefined {
+    return this.explicitClient ?? this.contextClient
+  }
+
+  protected getQueryClient(): QueryClient {
+    const client = this.tryGetQueryClient()
+    if (!client) {
+      throw createMissingQueryClientError()
+    }
+
+    return client
+  }
+
+  protected setResult(next: TResult): void {
+    if (Object.is(this.result, next)) {
+      return
+    }
+
+    this.result = next
+    this.queueUpdate()
+  }
+
+  get current(): TResult {
+    if (this.queryClientResolutionState === 'missing') {
+      throw createMissingQueryClientError()
+    }
+
+    return this.result
+  }
+
+  protected get connectedState(): boolean {
+    return this.connected
+  }
+
+  protected queueUpdate(): void {
+    if (this.updateQueued) {
+      return
+    }
+
+    this.updateQueued = true
+    queueMicrotask(() => {
+      this.updateQueued = false
+      if (!this.destroyed) {
+        this.host.requestUpdate()
+      }
+    })
+  }
+
+  private queueQueryClientChanged(): void {
+    if (this.clientChangeQueued) {
+      return
+    }
+
+    this.clientChangeQueued = true
+    queueMicrotask(() => {
+      this.clientChangeQueued = false
+      if (!this.destroyed) {
+        this.onQueryClientChanged()
+      }
+    })
+  }
+
+  private beginContextResolution(): void {
+    this.clearContextClient()
+    this.updateQueryClientResolutionState('awaiting-context')
+  }
+
+  private queueContextResolution(attempt: number): void {
+    queueMicrotask(() => {
+      if (
+        this.destroyed ||
+        !this.connected ||
+        attempt !== this.connectionAttempt ||
+        this.queryClientResolutionState !== 'awaiting-context'
+      ) {
+        return
+      }
+
+      this.dispatchContextRequest(attempt)
+      this.queueInitialContextResolutionCompletion(attempt)
+    })
+  }
+
+  private dispatchContextRequest(attempt: number): void {
+    if (!('dispatchEvent' in this.host)) {
+      return
+    }
+
+    const contextTarget = this.host as ReactiveControllerHost & EventTarget
+    contextTarget.dispatchEvent(
+      new ContextEvent(
+        queryClientContext,
+        contextTarget as unknown as Element,
+        (value, unsubscribe) => {
+          if (
+            this.destroyed ||
+            !this.connected ||
+            attempt !== this.connectionAttempt
+          ) {
+            unsubscribe?.()
+            return
+          }
+
+          if (
+            this.contextUnsubscribe &&
+            this.contextUnsubscribe !== unsubscribe
+          ) {
+            this.contextUnsubscribe()
+          }
+
+          const resolutionChanged = this.updateQueryClientResolutionState(
+            value === undefined ? 'missing' : 'bound',
+          )
+          const clientChanged = this.contextClient !== value
+
+          this.contextClient = value
+          this.contextUnsubscribe = unsubscribe
+
+          if (resolutionChanged || clientChanged) {
+            this.queueUpdate()
+            this.queueQueryClientChanged()
+          }
+        },
+        true,
+      ),
+    )
+  }
+
+  private queueInitialContextResolutionCompletion(attempt: number): void {
+    queueMicrotask(() => {
+      if (
+        this.destroyed ||
+        !this.connected ||
+        attempt !== this.connectionAttempt ||
+        this.queryClientResolutionState !== 'awaiting-context'
+      ) {
+        return
+      }
+
+      if (this.updateQueryClientResolutionState('missing')) {
+        this.queueUpdate()
+        this.queueQueryClientChanged()
+      }
+    })
+  }
+
+  private clearContextClient(): void {
+    this.contextUnsubscribe?.()
+    this.contextUnsubscribe = undefined
+    this.contextClient = undefined
+  }
+
+  private updateQueryClientResolutionState(
+    nextState: QueryClientResolutionState,
+  ): boolean {
+    if (this.queryClientResolutionState === nextState) {
+      return false
+    }
+
+    this.queryClientResolutionState = nextState
+    return true
+  }
+
+  protected abstract onConnected(): void
+  protected abstract onDisconnected(): void
+  protected abstract onHostUpdate(): void
+  protected abstract onQueryClientChanged(): void
+}