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

package/src/schema/action.hook.ts

@@ -0,0 +1,146 @@
+import type {
+  InputOf,
+  InstanceMethod,
+  OutputOf,
+  ReceiverOf,
+  RemoteCallableOf,
+} from '@astrale-os/sdk/domain'
+import type { NodeId } from '@astrale-os/sdk/graph/node'
+import type { QueryAST } from '@astrale-os/sdk/query'
+import type { schema } from '@astrale-os/sdk/schema'
+import type { DomainInvokeOptions } from '@astrale-os/shell'
+
+import { Path } from '@astrale-os/sdk/graph/path'
+import { useCallback, useMemo, useRef } from 'react'
+
+import type { Action as AsyncAction } from '../graph/action.js'
+
+import { useAction as useAsyncAction } from '../graph/action.js'
+import { useGraphStore } from '../graph/store.js'
+import { bindingFor } from './domain.hook.js'
+
+type Callable = RemoteCallableOf<schema.DomainSchema> | InstanceMethod
+
+const QUERY_REFRESH = Symbol('shell-react.query-refresh')
+
+export interface QueryRefresh {
+  readonly id: string
+  readonly [QUERY_REFRESH]: () => {
+    readonly ast: QueryAST
+    readonly page: Readonly<{ readonly size: number }>
+  }
+}
+
+type RefreshableQuery<Input, Query extends QueryAST> = {
+  readonly id: string
+  readonly page: Readonly<{ readonly size: number }>
+  prepare?(input: Input): Input
+  build(input: Input): Query
+}
+
+/** Pair one exact named Query definition with its admitted input for targeted invalidation. */
+export function queryRefresh<Input, Query extends QueryAST>(
+  definition: RefreshableQuery<Input, Query>,
+  input: Input,
+): QueryRefresh {
+  return Object.freeze({
+    id: definition.id,
+    [QUERY_REFRESH]: () => {
+      const prepared = definition.prepare?.(input) ?? input
+      return Object.freeze({ ast: definition.build(prepared), page: definition.page })
+    },
+  })
+}
+
+export type ActionRefresh =
+  | 'all'
+  | 'none'
+  | {
+      readonly queries: readonly QueryRefresh[]
+    }
+
+export interface ActionOptions extends DomainInvokeOptions {
+  readonly refresh?: ActionRefresh
+  readonly onError?: (error: unknown) => void
+}
+
+type ActionArgs<C extends Callable> = C extends InstanceMethod
+  ? [receiver: ReceiverOf<C>, input: InputOf<C>]
+  : [input: InputOf<C>]
+
+export interface DomainAction<Args extends unknown[], Result> {
+  run(...args: Args): Promise<Result>
+  readonly pending: boolean
+  readonly error: unknown
+  readonly result: Result | undefined
+  reset(): void
+}
+
+/** Invoke one schema-declared Function or Method and invalidate Store by explicit policy. */
+export function useAction<C extends Callable>(
+  callable: C,
+  options: ActionOptions = {},
+): DomainAction<ActionArgs<C>, OutputOf<C>> {
+  const binding = bindingFor(callable)
+  const store = useGraphStore()
+  const callableRef = useRef(callable)
+  callableRef.current = callable
+  const bindingRef = useRef(binding)
+  bindingRef.current = binding
+  const optionsRef = useRef(options)
+  optionsRef.current = options
+
+  const invoke = useCallback(
+    async (...args: ActionArgs<C>): Promise<OutputOf<C>> => {
+      const current = callableRef.current
+      const policy = optionsRef.current
+      const { refresh: _refresh, onError: _onError, ...request } = policy
+      try {
+        const invokeExact = bindingRef.current.$.invoke as (
+          ...values: readonly unknown[]
+        ) => Promise<OutputOf<C>>
+        const result =
+          'on' in current
+            ? await invokeExact(current, receiverPath(args[0] as ReceiverOf<C>), args[1], request)
+            : await invokeExact(current, args[0], request)
+        const refresh = policy.refresh ?? 'all'
+        if (refresh === 'all') store.invalidate()
+        else if (refresh !== 'none') {
+          refresh.queries.forEach((query) => {
+            const target = query[QUERY_REFRESH]()
+            store.invalidate(target.ast, { page: target.page })
+          })
+        }
+        return result
+      } catch (error) {
+        policy.onError?.(error)
+        throw error
+      }
+    },
+    [store],
+  )
+  const action = useAsyncAction(invoke as (...args: ActionArgs<C>) => Promise<OutputOf<C>>)
+  return useMemo(() => projectAction(action), [action])
+}
+
+function projectAction<Args extends unknown[], Result>(
+  action: AsyncAction<Args, Result>,
+): DomainAction<Args, Result> {
+  return {
+    run: (...args) => action(...args),
+    get pending() {
+      return action.pending
+    },
+    get error() {
+      return action.error
+    },
+    get result() {
+      return action.result
+    },
+    reset: action.reset,
+  }
+}
+
+function receiverPath(receiver: { readonly id: NodeId }): string {
+  return Path.id(receiver.id).raw
+}

package/src/schema/domain.hook.ts

@@ -1,16 +1,132 @@
+import type { DomainBinding, KernelClient } from '@astrale-os/shell'
+
+import { schema } from '@astrale-os/sdk/schema'
+
+import { useSessionKernel } from '../auth/session-kernel.js'
+
+type Resource<T> =
+  | { readonly status: 'pending'; readonly promise: Promise<void> }
+  | { readonly status: 'ready'; readonly value: T }
+  | { readonly status: 'failed'; readonly error: unknown }
+
+const typed = new WeakMap<KernelClient, WeakMap<object, Resource<DomainBinding>>>()
+const dynamic = new WeakMap<KernelClient, Resource<DomainBinding>>()
+const aggregates = new WeakMap<
+  KernelClient,
+  Map<string, Resource<Readonly<Record<string, DomainBinding>>>>
+>()
+const bindingByValue = new WeakMap<object, DomainBinding>()
+
 /**
- * useDomain(schema) (API §6) — the typed domain binding, `kernel.withSchema(schema)`,
- * memoized per (effective session, schema). The BoundNodes it mints ride the
- * shared scoped memory, so typed writes are optimistic and revalidate (§6).
+ * Resolve an exact verified DomainBinding. The first render suspends while Session snapshot and schema
+ * revision checks complete; later renders return the retained binding synchronously.
  */
-import type { FnMap, SchemaBoundView } from '@astrale-os/kernel-client'
-import type { Schema } from '@astrale-os/kernel-dsl'
+export function useDomain<const S extends schema.DomainSchema>(schema: S): DomainBinding<S> {
+  const kernel = useSessionKernel()
+  let bySchema = typed.get(kernel)
+  if (bySchema === undefined) {
+    bySchema = new WeakMap()
+    typed.set(kernel, bySchema)
+  }
+  let resource = bySchema.get(schema)
+  if (resource === undefined) {
+    resource = createResource(kernel.domain(schema)) as Resource<DomainBinding>
+    bySchema.set(schema, resource)
+  }
+  const binding = read(resource) as unknown as DomainBinding<S>
+  registerBinding(binding as unknown as DomainBinding)
+  return binding
+}
 
-import { useSessionKernel } from '../auth/session-kernel.js'
-import { useMemory } from '../graph/memory/scope.js'
-import { bindingFor } from './binding.js'
+/** Dynamic verified root binding used by tools that intentionally do not carry a schema witness. */
+export function useDynamicDomain(): DomainBinding {
+  const kernel = useSessionKernel()
+  let resource = dynamic.get(kernel)
+  if (resource === undefined) {
+    resource = createResource(kernel.domain())
+    dynamic.set(kernel, resource)
+  }
+  const binding = read(resource)
+  registerBinding(binding)
+  return binding
+}
+
+/** Bind several exact installed schemas behind one Suspense boundary and stable named result. */
+export function useDomains<const Schemas extends Readonly<Record<string, schema.DomainSchema>>>(
+  schemas: Schemas,
+): { readonly [Name in keyof Schemas]: DomainBinding<Schemas[Name]> } {
+  const kernel = useSessionKernel()
+  const names = Object.keys(schemas).sort()
+  if (names.length === 0) return Object.freeze({}) as never
+  const key = names
+    .map((name) => `${name}\u0000${schemas[name]!.origin}\u0000${schema.revision(schemas[name]!)}`)
+    .join('\u0001')
+  let bySet = aggregates.get(kernel)
+  if (bySet === undefined) {
+    bySet = new Map()
+    aggregates.set(kernel, bySet)
+  }
+  let resource = bySet.get(key)
+  if (resource === undefined) {
+    resource = createResource(
+      Promise.all(
+        names.map(async (name) => [name, await kernel.domain(schemas[name]!)] as const),
+      ).then((entries) => Object.freeze(Object.fromEntries(entries))),
+    )
+    bySet.set(key, resource)
+  }
+  const values = read(resource)
+  Object.values(values).forEach(registerBinding)
+  return values as { readonly [Name in keyof Schemas]: DomainBinding<Schemas[Name]> }
+}
+
+export function bindingFor(value: object): DomainBinding {
+  const binding = bindingByValue.get(value)
+  if (binding === undefined) {
+    throw new Error('The definition is not owned by a Domain bound in this React runtime.')
+  }
+  return binding
+}
+
+function registerBinding(binding: DomainBinding): void {
+  const seen = new WeakSet<object>()
+  const visit = (value: unknown, depth: number): void => {
+    if (depth > 4 || value === null || typeof value !== 'object' || seen.has(value)) return
+    seen.add(value)
+    bindingByValue.set(value, binding)
+    for (const [key, child] of Object.entries(value)) {
+      if (key === 'schema' || key === 'publication' || key === 'session') continue
+      visit(child, depth + 1)
+    }
+  }
+  visit(binding, 0)
+}
+
+function createResource<T>(promise: Promise<T>): Resource<T> {
+  const cell: {
+    status: 'pending' | 'ready' | 'failed'
+    promise: Promise<void>
+    value?: T
+    error?: unknown
+  } = {
+    status: 'pending',
+    promise: Promise.resolve(),
+  }
+  cell.promise = promise.then(
+    (value) => {
+      cell.status = 'ready'
+      cell.value = value
+    },
+    (error: unknown) => {
+      cell.status = 'failed'
+      cell.error = error
+    },
+  )
+  return cell as Resource<T>
+}
 
-/** The typed domain binding — `kernel.withSchema(schema)`, memoized per (session, schema). */
-export function useDomain<S extends Schema>(schema: S): SchemaBoundView<S, FnMap> {
-  return bindingFor(useSessionKernel(), schema, useMemory())
+function read<T>(resource: Resource<T>): T {
+  if (resource.status === 'pending') throw resource.promise
+  if (resource.status === 'failed') throw resource.error
+  return resource.value
 }

package/src/schema/index.ts

@@ -1,31 +1,10 @@
-// schema — the typing substrate (API §6). Typed kernel/domain bindings, typed
-// reads, method/function dispatch. See SHELL_REACT_API.md.
 export { useKernel } from './kernel.hook.js'
-export { useDomain } from './domain.hook.js'
-export {
-  useNode,
-  useChildren,
-  useBoundNode,
-  useBoundNodes,
-  useBoundEndpoints,
-} from './bind-read.js'
-export { useOut, useIn } from '../graph/query/neighbors.hook.js'
-export { useMethod } from './method.hook.js'
-export type { MethodOptions } from './method.hook.js'
-export { useFunction } from './function.hook.js'
-export type { FunctionOptions } from './function.hook.js'
-export type {
-  AutoMethodAction,
-  BoundMethodAction,
-  EndpointResult,
-  FunctionNames,
-  FunctionParams,
-  FunctionResult,
-  MethodIsStatic,
-  MethodNames,
-  MethodParams,
-  MethodResult,
-  TargetedMethodAction,
-  TypedChildrenResult,
-  TypedNodeResult,
-} from './types.js'
+export { useDomain, useDomains, useDynamicDomain } from './domain.hook.js'
+export { queryRefresh, useAction } from './action.hook.js'
+export type { ActionOptions, ActionRefresh, DomainAction, QueryRefresh } from './action.hook.js'
+export { useMutation } from './mutation.hook.js'
+export type { MutationOptions } from './mutation.hook.js'
+export { useDynamicObject, useObject } from './object.hook.js'
+export type { RichReadOptions } from './object.hook.js'
+export { RelationUnavailableError, useRelation } from './relation.hook.js'
+export type { RelationOptions, RelationResource, RelationUnavailable } from './relation.hook.js'

package/src/schema/kernel.hook.ts

@@ -1,17 +1,10 @@
-/**
- * useKernel (API §6) — the typed kernel, `kernel.withSchema(KernelSchema)`,
- * memoized per (effective) session. The kernel's own schema baked in; dispatch
- * and reads run as the subtree's principal over its scoped memory (§4).
- */
-import type { FnMap, SchemaBoundView } from '@astrale-os/kernel-client'
+import type { DomainBinding } from '@astrale-os/shell'
 
-import { KernelSchema } from '@astrale-os/kernel-core'
+import { KernelSchema } from '@astrale-os/sdk/schema/kernel'
 
-import { useSessionKernel } from '../auth/session-kernel.js'
-import { useMemory } from '../graph/memory/scope.js'
-import { bindingFor } from './binding.js'
+import { useDomain } from './domain.hook.js'
 
-/** The typed kernel — `kernel.withSchema(KernelSchema)`, memoized (§4-scoped). */
-export function useKernel(): SchemaBoundView<typeof KernelSchema, FnMap> {
-  return bindingFor(useSessionKernel(), KernelSchema, useMemory())
+/** The verified, exactly typed Kernel Domain binding. */
+export function useKernel(): DomainBinding<typeof KernelSchema> {
+  return useDomain(KernelSchema)
 }

package/src/schema/mutation.hook.ts

@@ -0,0 +1,63 @@
+import type { MutationDefinition } from '@astrale-os/sdk/mutation'
+
+import { bindMutations } from '@astrale-os/sdk/mutation'
+import { useCallback, useMemo, useRef } from 'react'
+
+import type { Action as AsyncAction } from '../graph/action.js'
+import type { DomainAction } from './action.hook.js'
+
+import { useAction as useAsyncAction } from '../graph/action.js'
+import { useGraphStore } from '../graph/store.js'
+
+export interface MutationOptions {
+  readonly optimistic?: boolean
+  readonly onError?: (error: unknown) => void
+}
+
+/** Execute one named SDK Mutation definition through GraphStore optimism/invalidation. */
+export function useMutation<Input, Output>(
+  definition: MutationDefinition<Input, Output>,
+  options: MutationOptions = {},
+): DomainAction<[Input], Output> {
+  const store = useGraphStore()
+  const definitionRef = useRef(definition)
+  definitionRef.current = definition
+  const optionsRef = useRef(options)
+  optionsRef.current = options
+  const run = useCallback(
+    async (input: Input): Promise<Output> => {
+      const execute = bindMutations((ast) =>
+        store.mutate(ast, {
+          optimistic: optionsRef.current.optimistic ?? true,
+        }),
+      )
+      try {
+        return await execute(definitionRef.current, input)
+      } catch (error) {
+        optionsRef.current.onError?.(error)
+        throw error
+      }
+    },
+    [store],
+  )
+  const action = useAsyncAction(run)
+  return useMemo(() => project(action), [action])
+}
+
+function project<Input, Output>(
+  action: AsyncAction<[Input], Output>,
+): DomainAction<[Input], Output> {
+  return {
+    run: (input) => action(input),
+    get pending() {
+      return action.pending
+    },
+    get error() {
+      return action.error
+    },
+    get result() {
+      return action.result
+    },
+    reset: action.reset,
+  }
+}

package/src/schema/object.hook.ts

@@ -0,0 +1,85 @@
+import type { StoreQueryResponse } from '@astrale-os/kernel-client/store'
+import type { BoundInstanceOf, Definition } from '@astrale-os/sdk/domain'
+import type { Node } from '@astrale-os/sdk/graph/node'
+import type { PathLike } from '@astrale-os/sdk/graph/path'
+
+import { Path } from '@astrale-os/sdk/graph/path'
+import { Query } from '@astrale-os/sdk/query'
+import { useCallback, useMemo } from 'react'
+
+import type { GraphResource } from '../graph/resource.js'
+
+import { useStoreResource } from '../graph/resource.js'
+import { bindingFor } from './domain.hook.js'
+
+export interface RichReadOptions {
+  readonly pageSize?: number
+}
+
+type ObjectDefinition = Pick<
+  Definition<'class' | 'interface'>,
+  'kind' | 'origin' | 'name' | 'key' | 'schemaRef' | 'definition'
+> & { readonly family: 'node' }
+
+/** Read and bind one exact rich object definition exclusively through GraphStore. */
+export function useObject<RichDefinition extends ObjectDefinition>(
+  definition: RichDefinition,
+  target: PathLike | null | undefined,
+  options: RichReadOptions = {},
+): GraphResource<BoundInstanceOf<RichDefinition> | null> {
+  const binding = bindingFor(definition)
+  const path = target === null || target === undefined ? null : Path.from(target)
+  const query = useMemo(
+    () =>
+      path === null
+        ? null
+        : Query.from({ kind: 'node', paths: [path], binding: 'object' })
+            .filter({ satisfies: definition.schemaRef })
+            .select({ kind: 'graph' }),
+    [definition, path?.raw],
+  )
+  const project = useCallback(
+    (response: StoreQueryResponse<NonNullable<typeof query>>) => {
+      const result = response.result
+      if (result.kind !== 'graph' || result.selection.kind !== 'node') return null
+      const id = result.selection.ids[0]
+      const node =
+        id === undefined
+          ? undefined
+          : result.graph.nodes.find((candidate: { readonly id: unknown }) => candidate.id === id)
+      const bind = binding.$.bind as unknown as (
+        expected: RichDefinition,
+        value: Node,
+      ) => BoundInstanceOf<RichDefinition>
+      return node === undefined ? null : bind(definition, node)
+    },
+    [binding, definition],
+  )
+  return useStoreResource(query, options.pageSize ?? 1, project)
+}
+
+/** Explicitly untyped point read for inspectors; it never impersonates `useObject`. */
+export function useDynamicObject(
+  target: PathLike | null | undefined,
+  options: RichReadOptions = {},
+): GraphResource<Node | null> {
+  const path = target === null || target === undefined ? null : Path.from(target)
+  const query = useMemo(
+    () =>
+      path === null
+        ? null
+        : Query.from({ kind: 'node', paths: [path], binding: 'dynamic_object' }).select({
+            kind: 'graph',
+          }),
+    [path?.raw],
+  )
+  const project = useCallback((response: StoreQueryResponse<NonNullable<typeof query>>) => {
+    const result = response.result
+    if (result.kind !== 'graph' || result.selection.kind !== 'node') return null
+    const id = result.selection.ids[0]
+    return id === undefined
+      ? null
+      : (result.graph.nodes.find((candidate) => candidate.id === id) ?? null)
+  }, [])
+  return useStoreResource(query, options.pageSize ?? 1, project)
+}