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

package/src/graph/query/neighbors.hook.ts

@@ -1,159 +0,0 @@
-import type { AnyBoundNode, EdgeNames } from '@astrale-os/kernel-client'
-import type { Schema } from '@astrale-os/kernel-dsl'
-
-/**
- * useOut / useIn (API §6) — the public typed traversal read hooks. Resolve
- * endpoints one-shot through `BoundNode.links.out/in` (`live: false`); become live with
- * no surface change once edge-endpoint ids land. Deviations tracked in API §6/G6.
- */
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-
-import type { EndpointResult } from '../../schema/types.js'
-import type { ReadState, ReadOptions } from '../memory/read/envelope.js'
-
-import { schemaOf, tagSchema } from '../../schema/tag.js'
-import { isIdleInput } from '../memory/read/idle.js'
-
-export function useOut<S extends Schema, E extends EdgeNames<S>>(
-  node: AnyBoundNode<S> | null | undefined,
-  edge: E,
-  opts?: ReadOptions,
-): EndpointResult<S, E, 'to'> {
-  return useEndpoint(node, edge, 'out', opts) as unknown as EndpointResult<S, E, 'to'>
-}
-
-export function useIn<S extends Schema, E extends EdgeNames<S>>(
-  node: AnyBoundNode<S> | null | undefined,
-  edge: E,
-  opts?: ReadOptions,
-): EndpointResult<S, E, 'from'> {
-  return useEndpoint(node, edge, 'in', opts) as unknown as EndpointResult<S, E, 'from'>
-}
-
-type EndpointEnvelope<S extends Schema> = ReadState & {
-  readonly node?: AnyBoundNode<S> | null
-  readonly nodes?: readonly AnyBoundNode<S>[]
-}
-
-function useEndpoint<S extends Schema>(
-  node: AnyBoundNode<S> | null | undefined,
-  edge: EdgeNames<S>,
-  side: 'out' | 'in',
-  opts?: ReadOptions,
-): EndpointEnvelope<S> {
-  const schema = isIdleInput(node) ? undefined : schemaOf(node)
-  const single = schema !== undefined && isSingleEndpoint(schema, edge, side)
-  const key = `${node?.id ?? ''}\u0000${edge}\u0000${side}`
-  const run = useCallback(async (): Promise<unknown> => {
-    if (isIdleInput(node)) return null
-    const result = await (side === 'out' ? node.links.out(edge) : node.links.in(edge))
-    if (schema !== undefined) tagEndpoints(result, schema)
-    return result
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [node?.id, edge, side])
-
-  const { data, pending, error, refetch } = useAsyncRead(
-    isIdleInput(node) ? null : run,
-    key,
-    opts?.keepPrevious === true,
-  )
-
-  return useMemo<EndpointEnvelope<S>>(() => {
-    const live: ReadState = { pending, error, live: false, seq: 0, refetch }
-    if (isIdleInput(node)) return { ...live, node: null, nodes: EMPTY }
-    if (single) {
-      const value = Array.isArray(data) ? data[0] : data
-      return { ...live, node: (value ?? null) as AnyBoundNode<S> | null }
-    }
-    const values = Array.isArray(data) ? data : data === null || data === undefined ? EMPTY : [data]
-    return { ...live, nodes: values as readonly AnyBoundNode<S>[] }
-  }, [node, data, pending, error, refetch, single])
-}
-
-// ── helpers ──────────────────────────────────────────────────────────────────
-
-const EMPTY: readonly never[] = Object.freeze([])
-
-function isSingleEndpoint(schema: Schema, edge: string, side: 'out' | 'in'): boolean {
-  const definition = schema.classes[edge] as
-    | {
-        readonly from?: { readonly cardinality?: string }
-        readonly to?: { readonly cardinality?: string }
-      }
-    | undefined
-  const cardinality = (side === 'out' ? definition?.to : definition?.from)?.cardinality
-  return cardinality === '1' || cardinality === '0..1'
-}
-
-function tagEndpoints(result: unknown, schema: Schema): void {
-  if (Array.isArray(result)) for (const r of result) tagSchema(r, schema)
-  else if (result !== null && result !== undefined) tagSchema(result, schema)
-}
-
-interface AsyncState<T> {
-  data?: T
-  pending: boolean
-  error: unknown
-  key: string | null
-}
-
-/** One-shot async read with pending/error/refetch and stale-response guarding. */
-function useAsyncRead<T>(
-  run: (() => Promise<T>) | null,
-  key: string,
-  keepPrevious: boolean,
-): AsyncState<T> & { refetch(): Promise<void> } {
-  const [state, setState] = useState<AsyncState<T>>({
-    pending: run !== null,
-    error: undefined,
-    key: run === null ? null : key,
-  })
-  const runRef = useRef(run)
-  runRef.current = run
-  const keyRef = useRef(key)
-  keyRef.current = key
-  const keepPreviousRef = useRef(keepPrevious)
-  keepPreviousRef.current = keepPrevious
-  const seq = useRef(0)
-
-  const refetch = useCallback((): Promise<void> => {
-    const current = runRef.current
-    const currentKey = keyRef.current
-    if (current === null) {
-      setState({ pending: false, error: undefined, data: undefined, key: null })
-      return Promise.resolve()
-    }
-    const my = ++seq.current
-    setState((s) => ({
-      data: s.key === currentKey || keepPreviousRef.current === true ? s.data : undefined,
-      pending: true,
-      error: undefined,
-      key: currentKey,
-    }))
-    return current().then(
-      (data) => {
-        if (my === seq.current) {
-          setState({ data, pending: false, error: undefined, key: currentKey })
-        }
-      },
-      (error: unknown) => {
-        if (my === seq.current) {
-          setState((s) => ({ data: s.data, pending: false, error, key: currentKey }))
-        }
-      },
-    )
-  }, [])
-
-  useEffect(() => {
-    void refetch()
-  }, [key, refetch])
-
-  const current = state.key === key
-  return {
-    data: current || keepPrevious ? state.data : undefined,
-    pending: run !== null && (!current || state.pending),
-    error: current ? state.error : undefined,
-    key: current ? state.key : null,
-    refetch,
-  }
-}

package/src/graph/query/node.hook.ts

@@ -1,83 +0,0 @@
-import type { NodeRefInput, TypeNames } from '@astrale-os/kernel-client'
-import type { PathLike } from '@astrale-os/kernel-client/graph'
-import type { Schema } from '@astrale-os/kernel-dsl'
-
-/**
- * useNode (API §5 + §6) — ONE public symbol, overloaded: pass a `Schema` (+ type)
- * for the typed `BoundNode` result, or a bare ref for the untyped `Node` result.
- * Both forms ride the SAME memory shape — a typed read and its untyped twin are
- * one cache entry, one liveness, one overlay. The runtime dispatches on the first
- * argument; a given call site is always one form, so hook order is stable.
- */
-import { useMemo } from 'react'
-
-import type { TypedNodeResult } from '../../schema/types.js'
-import type { ReadState, Node, ReadOptions } from '../memory/read/envelope.js'
-
-import { useNode as useNodeTyped } from '../../schema/bind-read.js'
-import { useRead } from '../memory/read/read.js'
-
-export interface NodeResult extends ReadState {
-  /** The node, or `null` when missing ≡ masked (never throws NOT_FOUND). */
-  readonly node: Node | null
-}
-
-/**
- * A `Schema` (from `defineSchema`) — its shape (`domain`/`classes`/`interfaces`)
- * is disjoint from a `PathLike` (`string | Path`), so this cleanly routes the
- * typed vs untyped overload at runtime.
- */
-function isSchema(value: unknown): value is Schema {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    'domain' in value &&
-    'classes' in value &&
-    'interfaces' in value
-  )
-}
-
-/** One node by path — live, suspense-first; `null` ref is idle (§1.3). */
-function useNodeUntyped(ref: PathLike | null | undefined, opts?: ReadOptions): NodeResult {
-  const r = useRead(ref, opts)
-  return useMemo(
-    () => ({
-      pending: r.pending,
-      error: r.error,
-      live: r.live,
-      seq: r.seq,
-      refetch: r.refetch,
-      node: r.first,
-    }),
-    [r],
-  )
-}
-
-/** Typed: one node bound under `schema` as `type`. */
-export function useNode<S extends Schema, T extends TypeNames<S>>(
-  schema: S,
-  type: T,
-  ref: NodeRefInput | null | undefined,
-  opts?: ReadOptions,
-): TypedNodeResult<S, T>
-/** Untyped: one node by ref — `null` ref is idle (§1.3). */
-export function useNode(ref: PathLike | null | undefined, opts?: ReadOptions): NodeResult
-// The implementation signature returns an erased supertype of both result
-// shapes — every overload above is assignable to it regardless of `BoundNode`
-// variance; callers only ever see the precise overload return types.
-export function useNode(
-  a: unknown,
-  b?: unknown,
-  c?: unknown,
-  d?: unknown,
-): ReadState & { readonly node: unknown } {
-  if (isSchema(a)) {
-    return useNodeTyped(
-      a,
-      b as string,
-      c as NodeRefInput | null | undefined,
-      d as ReadOptions | undefined,
-    )
-  }
-  return useNodeUntyped(a as PathLike | null | undefined, b as ReadOptions | undefined)
-}

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

@@ -1,42 +0,0 @@
-import type { GatherBuilder, QueryASTInput, QuerySource } from '@astrale-os/kernel-client/graph'
-
-/**
- * useQuery (API §5) — a structured read: a builder callback or an AST value;
- * `null` is idle (§1.3). Rides the §1 envelope over the shared memory, projecting
- * roots/first/nodes and the gathered-alias arms.
- */
-import { useMemo } from 'react'
-
-import type { ReadState, Node, ReadOptions, Windowed } from '../memory/read/envelope.js'
-
-import { useRead } from '../memory/read/read.js'
-
-export interface QueryResult extends ReadState, Windowed {
-  readonly nodes: readonly Node[]
-  readonly roots: readonly Node[]
-  readonly first: Node | null
-  gathered(alias: string): { readonly nodes: readonly Node[]; readonly first: Node | null }
-}
-
-/** A structured read — builder callback or AST value; `null` is idle (§1.3). */
-export function useQuery(
-  build: ((q: QuerySource) => GatherBuilder) | QueryASTInput | null | undefined,
-  opts?: ReadOptions,
-): QueryResult {
-  const r = useRead(build ?? null, opts)
-  return useMemo(
-    () => ({
-      pending: r.pending,
-      error: r.error,
-      live: r.live,
-      seq: r.seq,
-      refetch: r.refetch,
-      nodes: r.nodes,
-      roots: r.roots,
-      first: r.first,
-      gathered: r.gathered,
-      more: r.more,
-    }),
-    [r],
-  )
-}

package/src/schema/bind-read.ts

@@ -1,319 +0,0 @@
-import type { GatherBuilder, OrderInput, QuerySource } from '@astrale-os/kernel-client/graph'
-import type {
-  LiveResult,
-  ReadOptions as StoreReadOptions,
-  ShapeInput,
-} from '@astrale-os/kernel-client/store'
-import type { Node } from '@astrale-os/kernel-core'
-import type { Schema } from '@astrale-os/kernel-dsl'
-
-import {
-  BindTypeMismatchError,
-  normalizeRef,
-  type AnyBoundNode,
-  type BoundNode,
-  type DefOf,
-  type NodeRefInput,
-  type SchemaBoundView,
-  type TypeNames,
-} from '@astrale-os/kernel-client'
-import { shapeInputToAST, stableStringify, stripCursors } from '@astrale-os/kernel-client/store'
-import { compileDomain } from '@astrale-os/kernel-core/domain'
-/**
- * Binder-over-memory composition (API §6, §1.7) — consumed by the `graph/query/`
- * overloads. Binds wire `Node`s from the shared memory to stable `BoundNode`s
- * (an unchanged wire node re-binds to the SAME instance), and composes those
- * binders with a `useSyncExternalStore` read substrate (`useShape`) into the typed
- * `useNode`/`useChildren` reads. A typed read and its untyped twin ride the SAME
- * memory shape, so they are one cache entry, one liveness, one overlay.
- */
-import { useCallback, useMemo, useRef, useSyncExternalStore } from 'react'
-
-import type { ReadState, ReadOptions } from '../graph/memory/read/envelope.js'
-import type { TypedChildrenResult, TypedNodeResult } from './types.js'
-
-import { useSessionKernel } from '../auth/session-kernel.js'
-import { idleReadState, isIdleInput } from '../graph/memory/read/idle.js'
-import { useMemory } from '../graph/memory/scope.js'
-import { bindingFor } from './binding.js'
-import { schemaOf, tagSchema } from './tag.js'
-
-// ── binder hooks ────────────────────────────────────────────────────────────────
-
-interface OneCache<S extends Schema> {
-  wire: Node | null
-  binding: SchemaBoundView<S>
-  type: string
-  bound: BoundNode<unknown, S> | null
-}
-
-/** Bind one wire node as `type`; stable while the wire node, binding, and type hold. */
-export function useBoundNode<S extends Schema, T extends TypeNames<S>>(
-  binding: SchemaBoundView<S>,
-  type: T,
-  wire: Node | null | undefined,
-): BoundNode<DefOf<S, T>, S> | null {
-  const ref = useRef<OneCache<S> | null>(null)
-  const node = wire ?? null
-  let entry = ref.current
-  if (entry === null || entry.wire !== node || entry.binding !== binding || entry.type !== type) {
-    entry = {
-      wire: node,
-      binding,
-      type,
-      bound: node === null ? null : (binding.bind(type, node) as BoundNode<unknown, S>),
-    }
-    ref.current = entry
-  }
-  return entry.bound as BoundNode<DefOf<S, T>, S> | null
-}
-
-interface ManyCache<S extends Schema> {
-  binding: SchemaBoundView<S>
-  type: string
-  perNode: WeakMap<Node, BoundNode<unknown, S>>
-  last: readonly BoundNode<unknown, S>[]
-}
-
-/**
- * Bind many wire nodes as `type`; per-node identity + a stable array on no
- * change. `skipMismatch` drops nodes whose class is not `type` (a mixed-class
- * child set) instead of throwing.
- */
-export function useBoundNodes<S extends Schema, T extends TypeNames<S>>(
-  binding: SchemaBoundView<S>,
-  type: T,
-  wires: readonly Node[],
-  skipMismatch = false,
-): readonly BoundNode<DefOf<S, T>, S>[] {
-  const ref = useRef<ManyCache<S> | null>(null)
-  if (ref.current === null || ref.current.binding !== binding || ref.current.type !== type) {
-    ref.current = { binding, type, perNode: new WeakMap(), last: [] }
-  }
-  const cache = ref.current
-  const next: BoundNode<unknown, S>[] = []
-  for (const w of wires) {
-    let b = cache.perNode.get(w)
-    if (b === undefined) {
-      try {
-        b = binding.bind(type, w) as BoundNode<unknown, S>
-      } catch (error) {
-        if (skipMismatch && error instanceof BindTypeMismatchError) continue
-        throw error
-      }
-      cache.perNode.set(w, b)
-    }
-    next.push(b)
-  }
-  if (sameArray(cache.last, next)) return cache.last as readonly BoundNode<DefOf<S, T>, S>[]
-  cache.last = next
-  return next as readonly BoundNode<DefOf<S, T>, S>[]
-}
-
-interface EndpointCache<S extends Schema> {
-  binding: SchemaBoundView<S>
-  perNode: WeakMap<Node, AnyBoundNode<S>>
-  last: readonly AnyBoundNode<S>[]
-}
-
-/** Bind many wire nodes classlessly (traversal endpoints); per-node + stable array. */
-export function useBoundEndpoints<S extends Schema>(
-  binding: SchemaBoundView<S>,
-  wires: readonly Node[],
-): readonly AnyBoundNode<S>[] {
-  const ref = useRef<EndpointCache<S> | null>(null)
-  if (ref.current === null || ref.current.binding !== binding) {
-    ref.current = { binding, perNode: new WeakMap(), last: [] }
-  }
-  const cache = ref.current
-  const next = wires.map((w) => {
-    let b = cache.perNode.get(w)
-    if (b === undefined) {
-      b = binding.bindAny(w)
-      cache.perNode.set(w, b)
-    }
-    return b
-  })
-  if (sameArray(cache.last, next)) return cache.last
-  cache.last = next
-  return next
-}
-
-function sameArray<A>(a: readonly A[], b: readonly A[]): boolean {
-  return a.length === b.length && a.every((x, i) => x === b[i])
-}
-
-// ── read substrate ────────────────────────────────────────────────────────────
-
-/** Base read options plus the window growth mode (a `useChildren`-specific extra). */
-export type ShapeOptions = ReadOptions & { window?: 'append' | 'paged' }
-
-/** Store-facing options — render-time concerns (`suspend`/`keepPrevious`) stay here. */
-function toStoreOptions(opts?: ShapeOptions): StoreReadOptions | undefined {
-  if (opts === undefined) return undefined
-  const out: StoreReadOptions = {}
-  if (opts.live !== undefined) out.live = opts.live
-  if (opts.window !== undefined) out.window = opts.window
-  if (opts.with !== undefined) out.with = opts.with as unknown as StoreReadOptions['with']
-  return out
-}
-
-/** A stable string identity for a (shape, options) pair — the subscription key. */
-function keyOf(shape: ShapeInput, opts?: ShapeOptions): string {
-  const ast = stripCursors(shapeInputToAST(shape))
-  return `${stableStringify(ast)}|${opts?.live === false ? '0' : '1'}|${opts?.window ?? ''}|${opts?.with ?? ''}`
-}
-
-/**
- * Subscribe to a memory shape. `null` shape → idle (`null`, no I/O). A cold
- * shape suspends unless `suspend: false`. The returned `LiveResult` is the
- * unified read envelope — callers project `node`/`children`/`nodes`.
- */
-export function useShape(
-  shape: ShapeInput | null | undefined,
-  opts?: ShapeOptions,
-): LiveResult | null {
-  const memory = useMemory()
-  const storeOpts = toStoreOptions(opts)
-  const key = isIdleInput(shape) ? null : keyOf(shape, opts)
-
-  const subscribe = useCallback(
-    (onChange: () => void): (() => void) => {
-      if (isIdleInput(shape)) return () => {}
-      return memory.subscribe(shape, onChange, storeOpts)
-    },
-    // The shape's canonical identity is `key`; the captured `shape` is equivalent.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [memory, key],
-  )
-  const getSnapshot = useCallback(
-    (): LiveResult | null => (isIdleInput(shape) ? null : memory.getSnapshot(shape, storeOpts)),
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [memory, key],
-  )
-
-  const snapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
-
-  if (!isIdleInput(shape) && opts?.suspend !== false && memory.peek(shape, storeOpts) === null) {
-    // Cold FAILURE (§1.4): a rejected fetch with no data throws to the boundary;
-    // re-throwing the promise would re-arm a fetch each retry (infinite loop).
-    if (snapshot !== null && snapshot.error !== undefined) throw snapshot.error
-    throw memory.promise(shape, storeOpts)
-  }
-  return snapshot
-}
-
-// ── typed reads (schema-first useNode, BoundNode-first useChildren) ──────────────
-
-export function useNode<S extends Schema, T extends TypeNames<S>>(
-  schema: S,
-  type: T,
-  ref: NodeRefInput | null | undefined,
-  opts?: ReadOptions,
-): TypedNodeResult<S, T> {
-  const binding = bindingFor(useSessionKernel(), schema, useMemory())
-  const shape = isIdleInput(ref) ? null : normalizeRef(ref)
-  const snap = useShape(shape, opts)
-  const wire = snap?.node ?? null
-  const bound = useBoundNode(binding, type, wire)
-  if (bound !== null) tagSchema(bound, schema)
-  const live = snap === null ? idleReadState() : readStateOf(snap)
-  return useMemo(
-    () => ({ ...live, node: bound }),
-    [bound, live.pending, live.error, live.live, live.seq],
-  )
-}
-
-export function useChildren<S extends Schema, T extends TypeNames<S>>(
-  parent: AnyBoundNode<S> | null | undefined,
-  opts: ReadOptions & {
-    type: T
-    order?: OrderInput
-    limit?: number
-    window?: 'append' | 'paged'
-  },
-): TypedChildrenResult<S, T> {
-  const kernel = useSessionKernel()
-  const memory = useMemory()
-  const schema = isIdleInput(parent) ? null : requireSchema(parent)
-  const binding = schema === null ? null : bindingFor(kernel, schema, memory)
-
-  const parentRef = isIdleInput(parent) ? null : `@${parent.id}`
-  const classRef = schema === null ? undefined : classRefFor(schema, opts.type)
-  const shape =
-    parentRef === null
-      ? null
-      : (q: QuerySource): GatherBuilder =>
-          q.from(parentRef).children({
-            ...(classRef !== undefined ? { classes: [classRef] } : {}),
-            ...(opts.order !== undefined ? { order: opts.order } : {}),
-            ...(opts.limit !== undefined ? { limit: opts.limit } : {}),
-          })
-
-  const snap = useShape(shape, opts)
-  const wires = snap?.children ?? EMPTY
-  const bound = useBoundNodes(
-    (binding ?? UNBOUND) as unknown as SchemaBoundView<S>,
-    opts.type,
-    binding === null ? EMPTY : wires,
-    true,
-  )
-  if (schema !== null) for (const b of bound) tagSchema(b, schema)
-
-  const live = snap === null ? idleReadState() : readStateOf(snap)
-  const more = snap?.more ?? IDLE_MORE
-  return useMemo(
-    () => ({ ...live, more, children: bound }),
-    [bound, more, live.pending, live.error, live.live, live.seq],
-  )
-}
-
-// ── helpers ──────────────────────────────────────────────────────────────────
-
-const EMPTY: readonly never[] = Object.freeze([])
-const IDLE_MORE = { has: false, load: () => Promise.resolve(), pending: false } as const
-const UNBOUND = {} as never
-
-function readStateOf(snap: {
-  pending: boolean
-  error: unknown
-  live: boolean
-  seq: number
-  refetch(): Promise<void>
-}): ReadState {
-  return {
-    pending: snap.pending,
-    error: snap.error,
-    live: snap.live,
-    seq: snap.seq,
-    refetch: snap.refetch,
-  }
-}
-
-/** Recover the schema a BoundNode was bound under; a clear error if it is untagged. */
-export function requireSchema(node: object): Schema {
-  const schema = schemaOf(node)
-  if (schema === undefined) {
-    throw new Error(
-      'useChildren: the parent was not produced by a shell-react typed binding — ' +
-        'obtain it from useNode / useDomain(schema).bind() so its schema is known.',
-    )
-  }
-  return schema
-}
-
-const compiledCache = new WeakMap<Schema, ReturnType<typeof compileDomain>>()
-
-/** The descent class ref for a type name (class or interface), or undefined. */
-function classRefFor(schema: Schema, type: string): string | undefined {
-  let compiled = compiledCache.get(schema)
-  if (compiled === undefined) {
-    compiled = compileDomain(schema)
-    compiledCache.set(schema, compiled)
-  }
-  const accessor = compiled.$ as unknown as {
-    c(name: string): { path?: { class?: { raw: string } } } | undefined
-    i(name: string): { path?: { class?: { raw: string } } } | undefined
-  }
-  return accessor.c(type)?.path?.class?.raw ?? accessor.i(type)?.path?.class?.raw
-}