@astrale-os/shell-react 0.2.9 → 0.2.10-beta.2

package/src/graph/query-definition.hook.ts

@@ -0,0 +1,270 @@
+import type { GraphStore, StoreQueryResponse, StoreSnapshot } from '@astrale-os/kernel-client/store'
+import type {
+  QueryAstExecutionOptions,
+  QueryDefinition,
+  QueryValueBinder,
+} from '@astrale-os/sdk/query'
+import type { QueryAST } from '@astrale-os/sdk/query'
+import type { DomainBinding } from '@astrale-os/shell'
+
+import { bindQueries } from '@astrale-os/sdk/query'
+import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from 'react'
+
+import type { GraphResource, GraphResourceState } from './resource.js'
+
+import { useDynamicDomain } from '../schema/domain.hook.js'
+import { retainRefreshScheduler } from './resource.js'
+import { useGraphStore } from './store.js'
+
+export interface QueryResourceOptions {
+  readonly keepPrevious?: boolean
+  readonly refreshInterval?: number
+  readonly refreshWhen?: 'always' | 'visible'
+}
+
+interface TouchedShape {
+  readonly ast: QueryAST
+  readonly options: QueryAstExecutionOptions
+}
+
+interface DefinitionSnapshot<Output> {
+  readonly state: GraphResourceState
+  readonly data?: Output
+  readonly error?: unknown
+}
+
+class DefinitionObserver<Input, Output, Query extends QueryAST> {
+  private readonly listeners = new Set<() => void>()
+  private subscriptions: readonly (() => void)[] = Object.freeze([])
+  private touched: readonly TouchedShape[] = Object.freeze([])
+  private current: DefinitionSnapshot<Output> = Object.freeze({ state: 'loading' })
+  private generation = 0
+  private pending: Promise<void> | null = null
+  private started = false
+  private rerunQueued = false
+
+  constructor(
+    private readonly store: GraphStore,
+    private readonly binding: DomainBinding,
+    private readonly definition: QueryDefinition<Input, Output, Query>,
+    private readonly input: Input,
+  ) {}
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener)
+    return () => this.listeners.delete(listener)
+  }
+
+  getSnapshot = (): DefinitionSnapshot<Output> => this.current
+
+  start(): () => void {
+    this.started = true
+    void this.run('cached')
+    return () => {
+      this.started = false
+      this.generation += 1
+      this.subscriptions.forEach((unsubscribe) => unsubscribe())
+      this.subscriptions = Object.freeze([])
+    }
+  }
+
+  refresh = async (): Promise<void> => {
+    await this.run('refresh')
+  }
+
+  private run(freshness: 'cached' | 'refresh'): Promise<void> {
+    if (this.pending !== null && freshness === 'cached') return this.pending
+    const generation = ++this.generation
+    const touched: TouchedShape[] = []
+    this.update({
+      state: this.current.data === undefined ? 'loading' : 'refreshing',
+      ...(this.current.data === undefined ? {} : { data: this.current.data }),
+    })
+    const execute = async <Ast extends QueryAST>(
+      ast: Ast,
+      options: QueryAstExecutionOptions,
+    ): Promise<StoreQueryResponse<Ast>> => {
+      touched.push(Object.freeze({ ast, options }))
+      return this.store.read(ast, { ...options, freshness })
+    }
+    const bind = this.binding.$.bind as unknown as QueryValueBinder
+    const query = bindQueries(execute, { bind })
+    const running = query(this.definition, this.input)
+      .then((data) => {
+        if (!this.started || generation !== this.generation) return
+        this.touched = dedupeShapes(touched)
+        this.bindShapes()
+        this.update({ state: this.storeState(), data })
+      })
+      .catch((error: unknown) => {
+        if (!this.started || generation !== this.generation) return
+        this.touched = dedupeShapes(touched)
+        this.bindShapes()
+        this.update({
+          state: 'failed',
+          ...(this.current.data === undefined ? {} : { data: this.current.data }),
+          error,
+        })
+      })
+      .finally(() => {
+        if (this.pending === running) this.pending = null
+      })
+    this.pending = running
+    return running
+  }
+
+  private bindShapes(): void {
+    this.subscriptions.forEach((unsubscribe) => unsubscribe())
+    this.subscriptions = Object.freeze(
+      this.touched.map(({ ast, options }) =>
+        this.store.subscribe(ast, this.onStoreChange, options),
+      ),
+    )
+  }
+
+  private onStoreChange = (): void => {
+    const state = this.storeState()
+    this.update({
+      state,
+      ...(this.current.data === undefined ? {} : { data: this.current.data }),
+      ...(this.current.error === undefined ? {} : { error: this.current.error }),
+    })
+    if ((state === 'ready' || state === 'optimistic') && !this.rerunQueued) {
+      this.rerunQueued = true
+      queueMicrotask(() => {
+        this.rerunQueued = false
+        if (this.started) void this.run('cached')
+      })
+    }
+  }
+
+  private storeState(): GraphResourceState {
+    const snapshots = this.touched.map(({ ast, options }) => this.store.getSnapshot(ast, options))
+    if (snapshots.length === 0) return this.current.state
+    return combine(snapshots)
+  }
+
+  private update(next: DefinitionSnapshot<Output>): void {
+    if (
+      next.state === this.current.state &&
+      next.data === this.current.data &&
+      next.error === this.current.error
+    )
+      return
+    this.current = Object.freeze(next)
+    this.listeners.forEach((listener) => listener())
+  }
+}
+
+/** Execute one named SDK Query definition exclusively through the current GraphStore. */
+export function useQuery<Input, Output, Query extends QueryAST>(
+  definition: QueryDefinition<Input, Output, Query> | null,
+  input: Input,
+  options: QueryResourceOptions = {},
+): GraphResource<Output> {
+  const store = useGraphStore()
+  const binding = useDynamicDomain()
+  const inputIdentity = stableIdentity(input)
+  const observer = useMemo(
+    () => (definition === null ? null : new DefinitionObserver(store, binding, definition, input)),
+    [store, binding, definition, inputIdentity],
+  )
+  const idle = useMemo<DefinitionSnapshot<Output>>(() => Object.freeze({ state: 'idle' }), [])
+  const subscribe = useCallback(
+    (listener: () => void) => observer?.subscribe(listener) ?? (() => {}),
+    [observer],
+  )
+  const snapshot = useCallback(() => observer?.getSnapshot() ?? idle, [observer, idle])
+  const current = useSyncExternalStore(subscribe, snapshot, snapshot)
+  useEffect(() => observer?.start(), [observer])
+
+  const identity = definition === null ? 'idle' : `${definition.id}\u0000${inputIdentity}`
+  useEffect(() => {
+    if (observer === null || options.refreshInterval === undefined) return
+    return retainRefreshScheduler(
+      store,
+      identity,
+      observer.refresh,
+      options.refreshInterval,
+      options.refreshWhen ?? 'visible',
+    )
+  }, [store, observer, identity, options.refreshInterval, options.refreshWhen])
+
+  const previousRef = useRef<{ readonly identity: string; readonly data: Output } | undefined>(
+    undefined,
+  )
+  const previous =
+    options.keepPrevious && previousRef.current?.identity !== identity
+      ? previousRef.current
+      : undefined
+  useEffect(() => {
+    if (current.data !== undefined) {
+      previousRef.current = Object.freeze({ identity, data: current.data })
+    }
+  }, [identity, current.data])
+
+  return useMemo(
+    () =>
+      Object.freeze({
+        state: current.state,
+        data: current.data,
+        error: current.error,
+        ...(previous === undefined ? {} : { previous }),
+        transitioning: current.state === 'loading' || current.state === 'refreshing',
+        live: false as const,
+        sequence: 0 as const,
+        refresh: observer?.refresh ?? (() => Promise.resolve()),
+        more: Object.freeze({ has: false, pending: false, load: () => Promise.resolve() }),
+      }),
+    [current, previous, observer],
+  )
+}
+
+function dedupeShapes(input: readonly TouchedShape[]): readonly TouchedShape[] {
+  const seen = new Set<string>()
+  return Object.freeze(
+    input.filter(({ ast, options }) => {
+      const key = `${JSON.stringify(ast)}\u0000${JSON.stringify(options.page)}`
+      if (seen.has(key)) return false
+      seen.add(key)
+      return true
+    }),
+  )
+}
+
+function combine(snapshots: readonly StoreSnapshot[]): GraphResourceState {
+  if (snapshots.some((snapshot) => snapshot.state === 'cold')) return 'loading'
+  for (const state of ['failed', 'loading', 'refreshing', 'optimistic', 'stale'] as const) {
+    if (snapshots.some((snapshot) => snapshot.state === state)) return state
+  }
+  return 'ready'
+}
+
+function stableIdentity(value: unknown): string {
+  const seen = new WeakSet<object>()
+  const encode = (input: unknown): unknown => {
+    if (input === null) return ['null']
+    if (typeof input !== 'object') {
+      if (typeof input === 'function' || typeof input === 'symbol' || typeof input === 'bigint') {
+        throw new TypeError('Query input must be portable and serializable.')
+      }
+      if (input === undefined) return ['undefined']
+      if (typeof input === 'number' && !Number.isFinite(input)) {
+        throw new TypeError('Query input numbers must be finite.')
+      }
+      return [typeof input, input]
+    }
+    if (seen.has(input)) throw new TypeError('Query input cannot contain cycles.')
+    seen.add(input)
+    if (Array.isArray(input)) return ['array', input.map(encode)]
+    return [
+      'object',
+      Object.fromEntries(
+        Object.keys(input as Record<string, unknown>)
+          .sort()
+          .map((key) => [key, encode((input as Record<string, unknown>)[key])]),
+      ),
+    ]
+  }
+  return JSON.stringify(encode(value))
+}

package/src/graph/resource.ts

@@ -0,0 +1,358 @@
+import type { GraphStore, StoreQueryResponse, StoreSnapshot } from '@astrale-os/kernel-client/store'
+import type { QueryAST } from '@astrale-os/sdk/query'
+
+import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from 'react'
+
+import { useGraphStore } from './store.js'
+
+export type GraphResourceState =
+  | 'idle'
+  | 'loading'
+  | 'ready'
+  | 'stale'
+  | 'refreshing'
+  | 'optimistic'
+  | 'failed'
+
+export interface GraphResource<T> {
+  readonly state: GraphResourceState
+  /** Current-scope data only. Previous-scope data is never substituted here. */
+  readonly data: T | undefined
+  readonly error: unknown
+  readonly previous?: { readonly identity: string; readonly data: T }
+  readonly transitioning: boolean
+  readonly live: false
+  readonly sequence: 0
+  refresh(): Promise<void>
+  readonly more: {
+    readonly has: boolean
+    readonly pending: boolean
+    load(): Promise<void>
+  }
+}
+
+export interface StoreResourceOptions<Output> {
+  readonly identity?: string
+  readonly keepPrevious?: boolean
+  readonly window?: 'page' | 'append'
+  readonly merge?: (pages: readonly Output[]) => Output
+  readonly refreshInterval?: number
+  readonly refreshWhen?: 'always' | 'visible'
+}
+
+interface PageRef {
+  readonly after?: string
+}
+
+interface ObserverSnapshot<Query extends QueryAST> {
+  readonly snapshots: readonly StoreSnapshot<Query>[]
+  readonly pendingMore: boolean
+}
+
+class StoreObserver<Query extends QueryAST> {
+  private readonly listeners = new Set<() => void>()
+  private pages: readonly PageRef[] = Object.freeze([Object.freeze({})])
+  private unsubs: readonly (() => void)[] = Object.freeze([])
+  private current: ObserverSnapshot<Query> | undefined
+  private morePromise: Promise<void> | null = null
+  private started = false
+
+  constructor(
+    private readonly store: GraphStore,
+    private readonly query: Query,
+    private readonly size: number,
+  ) {}
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener)
+    return () => this.listeners.delete(listener)
+  }
+
+  getSnapshot = (): ObserverSnapshot<Query> => {
+    if (this.current !== undefined) return this.current
+    this.current = Object.freeze({
+      snapshots: Object.freeze(
+        this.pages.map((page) => this.store.getSnapshot(this.query, this.pageOptions(page))),
+      ),
+      pendingMore: this.morePromise !== null,
+    })
+    return this.current
+  }
+
+  start(): () => void {
+    if (!this.started) {
+      this.started = true
+      this.bindPages()
+      void this.store
+        .read(this.query, {
+          ...this.pageOptions(this.pages[0]!),
+          freshness: 'cached',
+        })
+        .catch(() => {})
+    }
+    return () => {
+      this.started = false
+      this.unsubs.forEach((unsubscribe) => unsubscribe())
+      this.unsubs = Object.freeze([])
+    }
+  }
+
+  async refresh(): Promise<void> {
+    await Promise.all(
+      this.pages.map((page) =>
+        this.store.read(this.query, { ...this.pageOptions(page), freshness: 'refresh' }),
+      ),
+    )
+  }
+
+  hasMore(): boolean {
+    const snapshots = this.getSnapshot().snapshots
+    const last = snapshots[snapshots.length - 1]
+    const response = last === undefined ? undefined : responseOf(last)
+    return response?.page.next !== undefined
+  }
+
+  loadMore(): Promise<void> {
+    if (this.morePromise !== null) return this.morePromise
+    const snapshots = this.getSnapshot().snapshots
+    const last = snapshots[snapshots.length - 1]
+    const after = last === undefined ? undefined : responseOf(last)?.page.next
+    if (after === undefined) return Promise.resolve()
+    if (this.pages.some((page) => page.after === after)) return Promise.resolve()
+
+    this.pages = Object.freeze([...this.pages, Object.freeze({ after })])
+    this.bindPages()
+    this.morePromise = this.store
+      .read(this.query, { ...this.pageOptions({ after }), freshness: 'cached' })
+      .then(() => {})
+      .finally(() => {
+        this.morePromise = null
+        this.publish()
+      })
+    this.publish()
+    return this.morePromise
+  }
+
+  private pageOptions(page: PageRef) {
+    return Object.freeze({
+      page: Object.freeze({
+        size: this.size,
+        ...(page.after === undefined ? {} : { after: page.after }),
+      }),
+    })
+  }
+
+  private bindPages(): void {
+    this.unsubs.forEach((unsubscribe) => unsubscribe())
+    this.unsubs = Object.freeze(
+      this.pages.map((page) =>
+        this.store.subscribe(this.query, this.publish, this.pageOptions(page)),
+      ),
+    )
+    this.publish()
+  }
+
+  private publish = (): void => {
+    this.current = undefined
+    this.listeners.forEach((listener) => listener())
+  }
+}
+
+interface PollSubscriber {
+  readonly interval: number
+  readonly when: 'always' | 'visible'
+  readonly refresh: () => Promise<void>
+}
+
+interface PollScheduler {
+  readonly subscribers: Map<symbol, PollSubscriber>
+  timer: ReturnType<typeof setTimeout> | undefined
+  onVisibility?: () => void
+}
+
+const pollers = new WeakMap<GraphStore, Map<string, PollScheduler>>()
+
+/** Adapt exact Store pages into a tear-free React resource without a parallel entity cache. */
+export function useStoreResource<Query extends QueryAST, Output>(
+  query: Query | null,
+  pageSize: number,
+  project: (response: StoreQueryResponse<Query>) => Output,
+  options: StoreResourceOptions<Output> = {},
+): GraphResource<Output> {
+  const store = useGraphStore()
+  const observer = useMemo(
+    () => (query === null ? null : new StoreObserver(store, query, positivePage(pageSize))),
+    [store, query, pageSize],
+  )
+  const subscribe = useCallback(
+    (listener: () => void) => (observer === null ? () => {} : observer.subscribe(listener)),
+    [observer],
+  )
+  const idle = useMemo<ObserverSnapshot<Query>>(
+    () => Object.freeze({ snapshots: Object.freeze([]), pendingMore: false }),
+    [],
+  )
+  const getSnapshot = useCallback(() => observer?.getSnapshot() ?? idle, [observer, idle])
+  const current = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+
+  useEffect(() => observer?.start(), [observer])
+
+  const pollIdentity =
+    query === null ? null : `${options.identity ?? JSON.stringify(query)}\u0000${pageSize}`
+  useEffect(() => {
+    if (query === null || observer === null || options.refreshInterval === undefined) return
+    return retainRefreshScheduler(
+      store,
+      pollIdentity!,
+      () => observer.refresh(),
+      options.refreshInterval,
+      options.refreshWhen ?? 'visible',
+    )
+  }, [store, query, observer, pollIdentity, options.refreshInterval, options.refreshWhen])
+
+  const refresh = useCallback(async (): Promise<void> => observer?.refresh(), [observer])
+  const loadMore = useCallback(async (): Promise<void> => observer?.loadMore(), [observer])
+  const identity = options.identity ?? pollIdentity ?? 'idle'
+  const projected = useMemo(() => {
+    const responses: StoreQueryResponse<Query>[] = current.snapshots.flatMap((snapshot) => {
+      const response = responseOf(snapshot)
+      return response === undefined ? [] : [response]
+    })
+    if (responses.length === 0) return undefined
+    const pages = responses.map(project)
+    if ((options.window ?? 'page') === 'page') return pages[0]
+    return options.merge?.(pages) ?? mergeAppendPages(pages)
+  }, [current, project, options.window, options.merge])
+  const previousRef = useRef<{ readonly identity: string; readonly data: Output } | undefined>(
+    undefined,
+  )
+  const prior = previousRef.current
+  const previous =
+    options.keepPrevious && prior !== undefined && prior.identity !== identity ? prior : undefined
+  useEffect(() => {
+    if (projected !== undefined) previousRef.current = Object.freeze({ identity, data: projected })
+  }, [identity, projected])
+
+  return useMemo(() => {
+    const snapshots = current.snapshots
+    const state = query === null ? 'idle' : combinedState(snapshots)
+    const failed = snapshots.find((snapshot) => snapshot.state === 'failed')
+    return Object.freeze({
+      state,
+      data: projected,
+      ...(failed?.state === 'failed' ? { error: failed.error } : { error: undefined }),
+      ...(previous === undefined ? {} : { previous }),
+      transitioning: state === 'loading' || state === 'refreshing',
+      live: false as const,
+      sequence: 0 as const,
+      refresh,
+      more: Object.freeze({
+        has: observer?.hasMore() ?? false,
+        pending: current.pendingMore,
+        load: loadMore,
+      }),
+    })
+  }, [current, query, projected, previous, refresh, observer, loadMore])
+}
+
+function combinedState(snapshots: readonly StoreSnapshot[]): GraphResourceState {
+  if (snapshots.length === 0 || snapshots.some((snapshot) => snapshot.state === 'cold'))
+    return 'loading'
+  for (const state of ['failed', 'loading', 'refreshing', 'optimistic', 'stale'] as const) {
+    if (snapshots.some((snapshot) => snapshot.state === state)) return state
+  }
+  return 'ready'
+}
+
+function responseOf<Query extends QueryAST>(
+  snapshot: StoreSnapshot<Query>,
+): StoreQueryResponse<Query> | undefined {
+  return 'response' in snapshot ? snapshot.response : undefined
+}
+
+function mergeAppendPages<Output>(pages: readonly Output[]): Output {
+  const first = pages[0]
+  if (!Array.isArray(first)) return pages[pages.length - 1] as Output
+  const seen = new Set<unknown>()
+  const merged: unknown[] = []
+  for (const page of pages as readonly (readonly unknown[])[]) {
+    for (const value of page) {
+      const identity =
+        value !== null && typeof value === 'object' && 'id' in value
+          ? (value as { readonly id: unknown }).id
+          : value
+      if (seen.has(identity)) continue
+      seen.add(identity)
+      merged.push(value)
+    }
+  }
+  return Object.freeze(merged) as Output
+}
+
+export function retainRefreshScheduler(
+  store: GraphStore,
+  identity: string,
+  refresh: () => Promise<void>,
+  interval: number,
+  when: 'always' | 'visible',
+): () => void {
+  if (!Number.isSafeInteger(interval) || interval < 250) {
+    throw new TypeError('refreshInterval must be an integer of at least 250ms.')
+  }
+  let byIdentity = pollers.get(store)
+  if (byIdentity === undefined) {
+    byIdentity = new Map()
+    pollers.set(store, byIdentity)
+  }
+  let scheduler = byIdentity.get(identity)
+  if (scheduler === undefined) {
+    scheduler = { subscribers: new Map(), timer: undefined }
+    byIdentity.set(identity, scheduler)
+  }
+  const token = Symbol(identity)
+  scheduler.subscribers.set(token, { interval, when, refresh })
+  schedulePoll(scheduler)
+  if (typeof document !== 'undefined' && scheduler.onVisibility === undefined) {
+    scheduler.onVisibility = () => schedulePoll(scheduler!, true)
+    document.addEventListener('visibilitychange', scheduler.onVisibility)
+  }
+  return () => {
+    scheduler!.subscribers.delete(token)
+    if (scheduler!.subscribers.size !== 0) {
+      schedulePoll(scheduler!)
+      return
+    }
+    if (scheduler!.timer !== undefined) clearTimeout(scheduler!.timer)
+    if (typeof document !== 'undefined' && scheduler!.onVisibility !== undefined) {
+      document.removeEventListener('visibilitychange', scheduler!.onVisibility)
+    }
+    byIdentity!.delete(identity)
+    if (byIdentity!.size === 0) pollers.delete(store)
+  }
+}
+
+function schedulePoll(scheduler: PollScheduler, immediate = false): void {
+  if (scheduler.timer !== undefined) clearTimeout(scheduler.timer)
+  const subscribers = [...scheduler.subscribers.values()]
+  if (subscribers.length === 0) return
+  const interval = Math.min(...subscribers.map((subscriber) => subscriber.interval))
+  scheduler.timer = setTimeout(
+    () => {
+      scheduler.timer = undefined
+      const visible = typeof document === 'undefined' || document.visibilityState !== 'hidden'
+      const eligible = [...scheduler.subscribers.values()].filter(
+        (subscriber) => subscriber.when === 'always' || visible,
+      )
+      eligible.forEach((subscriber) => void subscriber.refresh().catch(() => {}))
+      schedulePoll(scheduler)
+    },
+    immediate ? 0 : interval,
+  )
+}
+
+function positivePage(input: number): number {
+  if (!Number.isSafeInteger(input) || input < 1) {
+    throw new TypeError('Graph resource page size must be a positive safe integer.')
+  }
+  return input
+}