@virtuoso.dev/reactive-engine-react 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -56,8 +56,16 @@ export declare interface EngineProviderProps {
     children: React_2.ReactNode;
     /**
      * Optional stable ID for storage namespacing. Use this for multi-engine apps to prevent storage key conflicts.
+     * Also registers the engine in the global registry for access via `useRemote*` hooks with a string ID.
      */
     engineId?: string;
+    /**
+     * Optional reactive ref to expose the engine instance. Created by {@link useEngineRef}.
+     * Pass to `useRemote*` hooks to access the engine from sibling or ancestor components.
+     *
+     * @remarks An `EngineRef` should only be used with a single `EngineProvider`.
+     */
+    engineRef?: EngineRef;
     /**
      * A callback invoked once when the engine is created. Use this to register nodes and set up subscriptions.
      */
@@ -76,6 +84,29 @@ export declare interface EngineProviderProps {
     updateFn?: (engine: Engine) => void;
 }
 
+/**
+ * A reactive ref that holds an engine instance. Created by {@link useEngineRef}.
+ * Pass it to {@link EngineProvider} via the `engineRef` prop, then use it with
+ * the `useRemote*` hooks to access the engine from anywhere in the component tree.
+ *
+ * @remarks An `EngineRef` should only be used with a single `EngineProvider`.
+ * Using the same ref with multiple providers is unsupported.
+ *
+ * @category React Hooks and Components
+ */
+export declare interface EngineRef {
+    /** The current engine instance, or null if not yet available. */
+    readonly current: Engine | null;
+}
+
+/**
+ * Union type for the engine source parameter accepted by `useRemote*` hooks.
+ * Can be either a string engine ID (for global registry lookup) or an {@link EngineRef}.
+ *
+ * @category React Hooks and Components
+ */
+export declare type EngineSource = EngineRef | string;
+
 /**
  * Options for the {@link useRemoteCellValues} hook.
  * @category React Hooks and Components
@@ -84,7 +115,7 @@ export declare interface RemoteCellValuesOptions<T extends unknown[]> {
     cells: {
         [K in keyof T]: Out<T[K]>;
     };
-    engineId: string;
+    engineSource: EngineSource;
 }
 
 /**
@@ -198,6 +229,29 @@ declare function useCellValueWithStore<T>(cell: Out<T>): T;
  */
 export declare function useEngine(): Engine;
 
+/**
+ * Creates a stable, memoized {@link EngineRef} for use inside a component.
+ * Pass the returned ref to an {@link EngineProvider} via the `engineRef` prop,
+ * and to `useRemote*` hooks to access the engine reactively.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const engineRef = useEngineRef()
+ *   return (
+ *     <>
+ *       <SiblingComponent engineRef={engineRef} />
+ *       <EngineProvider engineRef={engineRef} initFn={initFn}>
+ *         <NestedComponent />
+ *       </EngineProvider>
+ *     </>
+ *   )
+ * }
+ * ```
+ * @category React Hooks and Components
+ */
+export declare function useEngineRef(): EngineRef;
+
 export declare const useIsomorphicLayoutEffect: typeof React_2.useLayoutEffect;
 
 /**
@@ -225,11 +279,11 @@ export declare const useIsomorphicLayoutEffect: typeof React_2.useLayoutEffect;
 export declare function usePublisher<T>(node$: Inp<T>): (value: T) => void;
 
 /**
- * Returns a tuple of the current value and a publisher function for a cell in an engine identified by `engineId`.
+ * Returns a tuple of the current value and a publisher function for a cell in an engine identified by `engineSource`.
  * Returns `[undefined, noop]` when the engine is not available yet.
  *
  * @param cell - The cell to use.
- * @param engineId - The ID of the engine (must match the `engineId` prop of an EngineProvider).
+ * @param engineSource - A string engine ID or an {@link EngineRef}.
  * @returns A tuple of the current value (or undefined) and a publisher function.
  * @typeParam T - The type of values that the cell emits/accepts.
  *
@@ -237,22 +291,22 @@ export declare function usePublisher<T>(node$: Inp<T>): (value: T) => void;
  * ```tsx
  * const cell$ = Cell(0)
  * // ...
- * function SiblingComponent() {
- *   const [value, setValue] = useRemoteCell(cell$, 'my-engine')
+ * function SiblingComponent({ engineRef }: { engineRef: EngineRef }) {
+ *   const [value, setValue] = useRemoteCell(cell$, engineRef)
  *   if (value === undefined) return <div>Loading...</div>
  *   return <button onClick={() => setValue(value + 1)}>{value}</button>
  * }
  * ```
  * @category React Hooks and Components
  */
-export declare function useRemoteCell<T>(cell: NodeRef<T>, engineId: string): [T | undefined, (value: T) => void];
+export declare function useRemoteCell<T>(cell: NodeRef<T>, engineSource: EngineSource): [T | undefined, (value: T) => void];
 
 /**
- * Gets the current value of the cell from an engine identified by `engineId`.
+ * Gets the current value of the cell from an engine identified by `engineSource`.
  * Returns `undefined` when the engine is not available yet.
  *
  * @param cell - The cell to read from.
- * @param engineId - The ID of the engine to read from (must match the `engineId` prop of an EngineProvider).
+ * @param engineSource - A string engine ID or an {@link EngineRef} to read from.
  * @returns The current value of the cell, or `undefined` if the engine is not available.
  * @typeParam T - The type of the value that the cell carries.
  *
@@ -260,15 +314,15 @@ export declare function useRemoteCell<T>(cell: NodeRef<T>, engineId: string): [T
  * ```tsx
  * const cell$ = Cell(0)
  * // ...
- * function SiblingComponent() {
- *   const value = useRemoteCellValue(cell$, 'my-engine')
+ * function SiblingComponent({ engineRef }: { engineRef: EngineRef }) {
+ *   const value = useRemoteCellValue(cell$, engineRef)
  *   if (value === undefined) return <div>Loading...</div>
  *   return <div>{value}</div>
  * }
  * ```
  * @category React Hooks and Components
  */
-export declare function useRemoteCellValue<T>(cell: Out<T>, engineId: string): T | undefined;
+export declare function useRemoteCellValue<T>(cell: Out<T>, engineSource: EngineSource): T | undefined;
 
 /**
  * Returns the up-to-date values of the passed cells from an engine identified by `engineId`.
@@ -334,11 +388,11 @@ export declare function useRemoteCellValues<T1, T2, T3, T4, T5, T6, T7, T8, T9,
 export declare function useRemoteCellValues(options: RemoteCellValuesOptions<unknown[]>): undefined | unknown[];
 
 /**
- * Returns a function that publishes values to a node in an engine identified by `engineId`.
+ * Returns a function that publishes values to a node in an engine identified by `engineSource`.
  * Returns a no-op function when the engine is not available yet.
  *
  * @param node$ - The node to publish to.
- * @param engineId - The ID of the engine to publish to (must match the `engineId` prop of an EngineProvider).
+ * @param engineSource - A string engine ID or an {@link EngineRef} to publish to.
  * @returns A publisher function that accepts values of type T.
  * @typeParam T - The type of values that the node accepts.
  *
@@ -346,13 +400,13 @@ export declare function useRemoteCellValues(options: RemoteCellValuesOptions<unk
  * ```tsx
  * const trigger$ = Trigger()
  * // ...
- * function SiblingComponent() {
- *   const publish = useRemotePublisher(trigger$, 'my-engine')
+ * function SiblingComponent({ engineRef }: { engineRef: EngineRef }) {
+ *   const publish = useRemotePublisher(trigger$, engineRef)
  *   return <button onClick={() => publish()}>Trigger</button>
  * }
  * ```
  * @category React Hooks and Components
  */
-export declare function useRemotePublisher<T>(node$: Inp<T>, engineId: string): (value: T) => void;
+export declare function useRemotePublisher<T>(node$: Inp<T>, engineSource: EngineSource): (value: T) => void;
 
 export { }

package/dist/index.js

@@ -1,55 +1,84 @@
-import { jsx as v } from "react/jsx-runtime";
-import { Engine as S } from "@virtuoso.dev/reactive-engine-core";
+import { jsx as p } from "react/jsx-runtime";
+import { Engine as d } from "@virtuoso.dev/reactive-engine-core";
 import * as s from "react";
-import R from "tiny-invariant";
-const i = typeof document < "u" ? s.useLayoutEffect : s.useEffect, l = /* @__PURE__ */ new Map();
-function C(e) {
-  let n = l.get(e);
-  return n || (n = { engine: null, subscribers: /* @__PURE__ */ new Set() }, l.set(e, n)), n;
+import h from "tiny-invariant";
+const c = typeof document < "u" ? s.useLayoutEffect : s.useEffect, y = Symbol("engineRefInternal");
+function x() {
+  let e = null;
+  const n = /* @__PURE__ */ new Set();
+  return {
+    get current() {
+      return e;
+    },
+    [y]: {
+      set(r) {
+        e = r, n.forEach((u) => {
+          u();
+        });
+      },
+      subscribe(r) {
+        return n.add(r), () => {
+          n.delete(r);
+        };
+      }
+    }
+  };
+}
+function j() {
+  const [e] = s.useState(() => x());
+  return e;
 }
-function m(e, n) {
-  const t = C(e);
-  t.engine = n, t.subscribers.forEach((u) => {
-    u();
-  }), t.subscribers.size === 0 && n === null && l.delete(e);
+function E(e) {
+  return e[y];
 }
-function p(e, n) {
-  const t = C(e);
+const f = /* @__PURE__ */ new Map();
+function S(e) {
+  let n = f.get(e);
+  return n || (n = { engine: null, subscribers: /* @__PURE__ */ new Set() }, f.set(e, n)), n;
+}
+function R(e, n) {
+  const t = S(e);
+  t.engine = n, t.subscribers.forEach((r) => {
+    r();
+  }), t.subscribers.size === 0 && n === null && f.delete(e);
+}
+function I(e, n) {
+  const t = S(e);
   return t.subscribers.add(n), () => {
-    t.subscribers.delete(n), t.subscribers.size === 0 && t.engine === null && l.delete(e);
+    t.subscribers.delete(n), t.subscribers.size === 0 && t.engine === null && f.delete(e);
   };
 }
-function f(e) {
+function m(e) {
   var n;
-  return ((n = l.get(e)) == null ? void 0 : n.engine) ?? null;
+  return ((n = f.get(e)) == null ? void 0 : n.engine) ?? null;
 }
-const E = s.createContext(null);
+const V = s.createContext(null);
 function a() {
-  const e = s.useContext(E);
-  return R(e !== null, "useEngine must be used within an EngineProvider"), e;
+  const e = s.useContext(V);
+  return h(e !== null, "useEngine must be used within an EngineProvider"), e;
 }
-function x(e) {
+function w(e) {
   const n = a();
   n.register(e);
-  const t = s.useCallback((u) => n.sub(e, u), [n, e]);
+  const t = s.useCallback((r) => n.sub(e, r), [n, e]);
   return s.useSyncExternalStore(
     t,
     () => n.getValue(e),
     () => n.getValue(e)
   );
 }
-function h(e) {
+function P(e) {
   const n = a();
   n.register(e);
-  const [t, u] = s.useState(() => n.getValue(e));
-  return i(() => n.sub(e, u), [n, e]), t;
+  const [t, r] = s.useState(() => n.getValue(e));
+  return c(() => n.sub(e, r), [n, e]), t;
 }
-const V = "useSyncExternalStore" in s ? x : h;
-function j(...e) {
+const v = "useSyncExternalStore" in s ? w : P;
+function k(...e) {
   const n = a(), t = s.useMemo(() => n.combineCells(e), [n, ...e]);
-  return V(t);
+  return v(t);
 }
-function P(e) {
+function N(e) {
   const n = a();
   return n.register(e), s.useCallback(
     (t) => {
@@ -58,73 +87,99 @@ function P(e) {
     [n, e]
   );
 }
-function O(e) {
-  return [V(e), P(e)];
+function A(e) {
+  return [v(e), N(e)];
 }
-function b(e) {
-  const [n, t] = s.useState(() => f(e));
-  return i(() => (t(f(e)), p(e, () => {
-    t(f(e));
-  })), [e]), n;
+function C(e) {
+  const n = typeof e != "string", t = n ? null : e, r = n ? e : null, [u, l] = s.useState(() => t ? m(t) : null);
+  c(() => {
+    if (!t) {
+      l(null);
+      return;
+    }
+    return l(m(t)), I(t, () => {
+      l(m(t));
+    });
+  }, [t]);
+  const [i, o] = s.useState(() => r ? r.current : null);
+  return c(() => {
+    if (!r) {
+      o(null);
+      return;
+    }
+    const b = E(r);
+    return o(r.current), b.subscribe(() => {
+      o(r.current);
+    });
+  }, [r]), n ? i : u;
 }
-function w(e, n) {
-  const t = b(n), [u, r] = s.useState(() => t ? t.getValue(e) : void 0);
-  return i(() => {
+function L(e, n) {
+  const t = C(n), [r, u] = s.useState(() => t ? t.getValue(e) : void 0);
+  return c(() => {
     if (!t) {
-      r(void 0);
+      u(void 0);
       return;
     }
-    return t.register(e), r(t.getValue(e)), t.sub(e, r);
-  }, [t, e]), u;
+    return t.register(e), u(t.getValue(e)), t.sub(e, u);
+  }, [t, e]), r;
 }
 function M(e, n) {
-  const t = b(n);
-  return i(() => {
+  const t = C(n);
+  return c(() => {
     t && t.register(e);
   }, [t, e]), s.useCallback(
-    (u) => {
-      t && t.pub(e, u);
+    (r) => {
+      t && t.pub(e, r);
     },
     [t, e]
   );
 }
-function T(e, n) {
-  return [w(e, n), M(e, n)];
+function G(e, n) {
+  return [L(e, n), M(e, n)];
 }
-function W(e) {
-  const { cells: n, engineId: t } = e, u = b(t), r = s.useMemo(() => u ? u.combineCells(n) : null, [u, ...n]), [c, o] = s.useState(
-    () => u && r ? u.getValue(r) : void 0
+function O(e) {
+  const { cells: n, engineSource: t } = e, r = C(t), u = s.useMemo(() => r ? r.combineCells(n) : null, [r, ...n]), [l, i] = s.useState(
+    () => r && u ? r.getValue(u) : void 0
   );
-  return i(() => {
-    if (!u || !r) {
-      o(void 0);
+  return c(() => {
+    if (!r || !u) {
+      i(void 0);
       return;
     }
-    return u.register(r), o(u.getValue(r)), u.sub(r, o);
-  }, [u, r]), c;
-}
-const q = ({ children: e, engineId: n, initFn: t, initWith: u, updateDeps: r, updateFn: c }) => {
-  const [o, y] = s.useState(null);
-  return i(() => {
-    const g = new S(u, n);
-    return y(g), t == null || t(g), n && m(n, g), () => {
-      n && m(n, null), g.dispose();
+    return r.register(u), i(r.getValue(u)), r.sub(u, i);
+  }, [r, u]), l;
+}
+const W = ({
+  children: e,
+  engineId: n,
+  engineRef: t,
+  initFn: r,
+  initWith: u,
+  updateDeps: l,
+  updateFn: i
+}) => {
+  const [o, b] = s.useState(null);
+  return c(() => {
+    const g = new d(u, n);
+    return b(g), r == null || r(g), n && R(n, g), t && E(t).set(g), () => {
+      n && R(n, null), t && E(t).set(null), g.dispose();
     };
-  }, [u, n]), i(() => {
-    o && (c == null || c(o));
-  }, [o, ...r ?? []]), o && /* @__PURE__ */ v(E.Provider, { value: o, children: e });
+  }, [u, n, t]), c(() => {
+    o && (i == null || i(o));
+  }, [o, ...l ?? []]), o && /* @__PURE__ */ p(V.Provider, { value: o, children: e });
 };
 export {
-  E as EngineContext,
-  q as EngineProvider,
-  O as useCell,
-  V as useCellValue,
-  j as useCellValues,
+  V as EngineContext,
+  W as EngineProvider,
+  A as useCell,
+  v as useCellValue,
+  k as useCellValues,
   a as useEngine,
-  i as useIsomorphicLayoutEffect,
-  P as usePublisher,
-  T as useRemoteCell,
-  w as useRemoteCellValue,
-  W as useRemoteCellValues,
+  j as useEngineRef,
+  c as useIsomorphicLayoutEffect,
+  N as usePublisher,
+  G as useRemoteCell,
+  L as useRemoteCellValue,
+  O as useRemoteCellValues,
   M as useRemotePublisher
 };

package/package.json

@@ -3,7 +3,7 @@
   "private": false,
   "sideEffects": false,
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "module": "dist/index.js",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -42,8 +42,8 @@
     "vite-plugin-dts": "^4.5.4",
     "vitest": "^4.0.16",
     "vitest-browser-react": "^2.0.2",
-    "@virtuoso.dev/reactive-engine-core": "0.0.4",
-    "@virtuoso.dev/tooling": "0.1.0"
+    "@virtuoso.dev/tooling": "0.1.0",
+    "@virtuoso.dev/reactive-engine-core": "0.0.4"
   },
   "files": [
     "dist"