@astrale-os/shell-react 0.2.2 → 0.2.4

package/dist/graph/query/neighbors.hook.js

@@ -12,8 +12,10 @@ export function useOut(node, edge, opts) {
 export function useIn(node, edge, opts) {
     return useEndpoint(node, edge, 'in', opts);
 }
-function useEndpoint(node, edge, side, _opts) {
+function useEndpoint(node, edge, side, opts) {
     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 () => {
         if (isIdleInput(node))
             return null;
@@ -23,22 +25,26 @@ function useEndpoint(node, edge, side, _opts) {
         return result;
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [node?.id, edge, side]);
-    const { data, pending, error, refetch } = useAsyncRead(isIdleInput(node) ? null : run, [
-        node?.id ?? null,
-        edge,
-        side,
-    ]);
+    const { data, pending, error, refetch } = useAsyncRead(isIdleInput(node) ? null : run, key, opts?.keepPrevious === true);
     return useMemo(() => {
         const live = { pending, error, live: false, seq: 0, refetch };
         if (isIdleInput(node))
             return { ...live, node: null, nodes: EMPTY };
-        if (Array.isArray(data))
-            return { ...live, nodes: data };
-        return { ...live, node: (data ?? null) };
-    }, [node, data, pending, error, refetch]);
+        if (single) {
+            const value = Array.isArray(data) ? data[0] : data;
+            return { ...live, node: (value ?? null) };
+        }
+        const values = Array.isArray(data) ? data : data === null || data === undefined ? EMPTY : [data];
+        return { ...live, nodes: values };
+    }, [node, data, pending, error, refetch, single]);
 }
 // ── helpers ──────────────────────────────────────────────────────────────────
 const EMPTY = Object.freeze([]);
+function isSingleEndpoint(schema, edge, side) {
+    const definition = schema.classes[edge];
+    const cardinality = (side === 'out' ? definition?.to : definition?.from)?.cardinality;
+    return cardinality === '1' || cardinality === '0..1';
+}
 function tagEndpoints(result, schema) {
     if (Array.isArray(result))
         for (const r of result)
@@ -47,30 +53,52 @@ function tagEndpoints(result, schema) {
         tagSchema(result, schema);
 }
 /** One-shot async read with pending/error/refetch and stale-response guarding. */
-function useAsyncRead(run, deps) {
-    const [state, setState] = useState({ pending: run !== null, error: undefined });
+function useAsyncRead(run, key, keepPrevious) {
+    const [state, setState] = useState({
+        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(() => {
         const current = runRef.current;
+        const currentKey = keyRef.current;
         if (current === null) {
-            setState({ pending: false, error: undefined, data: undefined });
+            setState({ pending: false, error: undefined, data: undefined, key: null });
             return Promise.resolve();
         }
         const my = ++seq.current;
-        setState((s) => ({ ...s, pending: true, error: undefined }));
+        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 });
+            if (my === seq.current) {
+                setState({ data, pending: false, error: undefined, key: currentKey });
+            }
         }, (error) => {
-            if (my === seq.current)
-                setState((s) => ({ data: s.data, pending: false, error }));
+            if (my === seq.current) {
+                setState((s) => ({ data: s.data, pending: false, error, key: currentKey }));
+            }
         });
     }, []);
     useEffect(() => {
         void refetch();
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, deps);
-    return { ...state, 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/shell-react",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Astrale shell-react — the React face of the shell (provider, hooks, view components)",
   "license": "Apache-2.0",
   "repository": {
@@ -26,8 +26,8 @@
   },
   "dependencies": {
     "@astrale-domains/shell-schema": ">=0.3.2 <1.0.0",
-    "@astrale-os/kernel-client": ">=0.4.5 <1.0.0",
-    "@astrale-os/kernel-core": ">=0.7.4 <1.0.0",
+    "@astrale-os/kernel-client": ">=0.4.6 <1.0.0",
+    "@astrale-os/kernel-core": ">=0.7.5 <1.0.0",
     "@astrale-os/kernel-dsl": ">=0.1.4 <1.0.0",
     "jose": "^6.2.3",
     "zod": "^4.3.6"
@@ -44,7 +44,7 @@
     "react-dom": "^19.2.0",
     "typescript": "~6.0.1-rc",
     "vitest": "^3.2.4",
-    "@astrale-os/shell": "0.3.2"
+    "@astrale-os/shell": "0.3.3"
   },
   "peerDependencies": {
     "@astrale-os/shell": ">=0.2.0 <1.0.0",

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

@@ -39,9 +39,11 @@ function useEndpoint<S extends Schema>(
   node: AnyBoundNode<S> | null | undefined,
   edge: EdgeNames<S>,
   side: 'out' | 'in',
-  _opts?: ReadOptions,
+  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))
@@ -50,24 +52,39 @@ function useEndpoint<S extends Schema>(
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [node?.id, edge, side])
 
-  const { data, pending, error, refetch } = useAsyncRead(isIdleInput(node) ? null : run, [
-    node?.id ?? null,
-    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 (Array.isArray(data)) return { ...live, nodes: data as readonly AnyBoundNode<S>[] }
-    return { ...live, node: (data ?? null) as AnyBoundNode<S> | null }
-  }, [node, data, pending, error, refetch])
+    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)
@@ -77,40 +94,66 @@ 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,
-  deps: readonly unknown[],
+  key: string,
+  keepPrevious: boolean,
 ): AsyncState<T> & { refetch(): Promise<void> } {
-  const [state, setState] = useState<AsyncState<T>>({ pending: run !== null, error: undefined })
+  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 })
+      setState({ pending: false, error: undefined, data: undefined, key: null })
       return Promise.resolve()
     }
     const my = ++seq.current
-    setState((s) => ({ ...s, pending: true, error: undefined }))
+    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 })
+        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 }))
+        if (my === seq.current) {
+          setState((s) => ({ data: s.data, pending: false, error, key: currentKey }))
+        }
       },
     )
   }, [])
 
   useEffect(() => {
     void refetch()
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, deps)
-
-  return { ...state, 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,
+  }
 }