@virtuoso.dev/reactive-engine-react 0.0.2

package/dist/index.d.ts

@@ -0,0 +1,197 @@
+import { Engine } from '@virtuoso.dev/reactive-engine-core';
+import { Inp } from '@virtuoso.dev/reactive-engine-core';
+import { NodeRef } from '@virtuoso.dev/reactive-engine-core';
+import { Out } from '@virtuoso.dev/reactive-engine-core';
+import * as React_2 from 'react';
+
+/**
+ * The context that provides an engine instance used by the built-in hooks. Instantiated by {@link EngineProvider}.
+ *
+ * @category React Hooks and Components
+ * @function
+ */
+export declare const EngineContext: React_2.Context<Engine | null>;
+
+/**
+ * A provider that instantiates and provides an {@link Engine} instance that's used by the built-in hooks.
+ *
+ * @example
+ * ```tsx
+ * import { Cell, useCellValue, e, EngineProvider } from '@virtuoso.dev/reactive-engine'
+ * const cell$ = Cell(0)
+ *
+ * function MyComponent() {
+ *   const cell = useCellValue(cell$)
+ *   return <div>{cell}</div>
+ * }
+ *
+ * export default function App() {
+ *   return <EngineProvider><MyComponent /></EngineProvider>
+ * }
+ * ```
+ *
+ * @category React Hooks and Components
+ * @function
+ */
+export declare const EngineProvider: React_2.FC<EngineProviderProps>;
+
+/**
+ * @inline
+ * @category React Hooks and Components
+ */
+export declare interface EngineProviderProps {
+    /**
+     * The children to render.
+     */
+    children: React_2.ReactNode;
+    /**
+     * Optional stable ID for storage namespacing. Use this for multi-engine apps to prevent storage key conflicts.
+     */
+    engineId?: string;
+    /**
+     * The initial values to set in the engine.
+     */
+    initWith?: Record<symbol, unknown>;
+    /**
+     * The values to update in the engine on each render.
+     */
+    updateWith?: Record<symbol, unknown>;
+}
+
+/**
+ * Returns a tuple of the current value of a cell and a publisher function (similar to `useState`).
+ * The component re-renderes when the cell value changes.
+ *
+ * @remarks The reactive engine state management allows you to keep your state logic outside of your React components.
+ * Be careful not to use this hook too often alongside `useEffect` for example, as this means that you're losing the benefits of the reactive engine design.
+ *
+ * @param cell - The cell to use.
+ * @returns A tuple of the current value of the cell and a publisher function.
+ * @typeParam T - The type of values that the cell emits/accepts.
+ * @category React Hooks and Components
+ */
+export declare function useCell<T>(cell: NodeRef<T>): [T, (value: T) => void];
+
+/**
+ * Gets the current value of the cell. The component is re-rendered when the cell value changes.
+ *
+ * @remarks If you need the values of multiple nodes from the engine and those nodes might change in the same computiation, you can {@link useCellValues} to reduce re-renders.
+ *
+ * @returns The current value of the cell.
+ * @typeParam T - the type of the value that the cell caries.
+ * @param cell - The cell to use.
+ *
+ * @example
+ * ```tsx
+ * const cell$ = Cell(0)
+ * //...
+ * function MyComponent() {
+ *   const cell = useCellValue(cell$)
+ *   return <div>{cell}</div>
+ * }
+ * ```
+ * @category React Hooks and Components
+ * @function
+ */
+export declare const useCellValue: typeof useCellValueWithStore;
+
+/**
+ * Returns the up-to-date values of the passed cells.
+ * The component is re-rendered each time any of the cells emits a new value.
+ * @category React Hooks and Components
+ * @returns Correclty typed array with the current values of the passed cells.
+ *
+ * @remarks This hook works only with cells, don't pass streams or triggers.
+ *
+ * @example
+ * ```tsx
+ * import { Cell, useCellValues }
+ * const foo$ = Cell('foo')
+ * const bar$ = Cell('bar')
+ * // ...
+ * // The component should be wrapped in an EngineProvider.
+ * function MyComponent() {
+ *   const [foo, bar] = useCellValues(foo$, bar$)
+ *   return <div>{foo} - {bar}</div>
+ * }
+ * ```
+ */
+export declare function useCellValues(...cells: Out[]): unknown[];
+
+/** @hidden */
+export declare function useCellValues<T1>(...cells: [Out<T1>]): [T1];
+
+/** @hidden */
+export declare function useCellValues<T1, T2>(...cells: [Out<T1>, Out<T2>]): [T1, T2];
+
+/** @hidden */
+export declare function useCellValues<T1, T2, T3>(...cells: [Out<T1>, Out<T2>, Out<T3>]): [T1, T2, T3];
+
+/** @hidden */
+export declare function useCellValues<T1, T2, T3, T4>(...cells: [Out<T1>, Out<T2>, Out<T3>, Out<T4>]): [T1, T2, T3, T4];
+
+/** @hidden */
+export declare function useCellValues<T1, T2, T3, T4, T5>(...cells: [Out<T1>, Out<T2>, Out<T3>, Out<T4>, Out<T5>]): [T1, T2, T3, T4, T5];
+
+/** @hidden */
+export declare function useCellValues<T1, T2, T3, T4, T5, T6>(...cells: [Out<T1>, Out<T2>, Out<T3>, Out<T4>, Out<T5>, Out<T6>]): [T1, T2, T3, T4, T5, T6];
+
+/** @hidden */
+export declare function useCellValues<T1, T2, T3, T4, T5, T6, T7>(...cells: [Out<T1>, Out<T2>, Out<T3>, Out<T4>, Out<T5>, Out<T6>, Out<T7>]): [T1, T2, T3, T4, T5, T6, T7];
+
+/** @hidden */
+export declare function useCellValues<T1, T2, T3, T4, T5, T6, T7, T8>(...cells: [Out<T1>, Out<T2>, Out<T3>, Out<T4>, Out<T5>, Out<T6>, Out<T7>, Out<T8>]): [T1, T2, T3, T4, T5, T6, T7, T8];
+
+/** @hidden */
+export declare function useCellValues<T1, T2, T3, T4, T5, T6, T7, T8, T9>(...cells: [Out<T1>, Out<T2>, Out<T3>, Out<T4>, Out<T5>, Out<T6>, Out<T7>, Out<T8>, Out<T9>]): [T1, T2, T3, T4, T5, T6, T7, T8, T9];
+
+/** @hidden */
+export declare function useCellValues<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10>(...cells: [Out<T1>, Out<T2>, Out<T3>, Out<T4>, Out<T5>, Out<T6>, Out<T7>, Out<T8>, Out<T9>, Out<T10>]): [T1, T2, T3, T4, T5, T6, T7, T8, T9, T10];
+
+/** @hidden */
+export declare function useCellValues<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11>(...cells: [Out<T1>, Out<T2>, Out<T3>, Out<T4>, Out<T5>, Out<T6>, Out<T7>, Out<T8>, Out<T9>, Out<T10>, Out<T11>]): [T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11];
+
+/** @hidden */
+export declare function useCellValues<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12>(...cells: [Out<T1>, Out<T2>, Out<T3>, Out<T4>, Out<T5>, Out<T6>, Out<T7>, Out<T8>, Out<T9>, Out<T10>, Out<T11>, Out<T12>]): [T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12];
+
+/** @hidden */
+export declare function useCellValues<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13>(...cells: [Out<T1>, Out<T2>, Out<T3>, Out<T4>, Out<T5>, Out<T6>, Out<T7>, Out<T8>, Out<T9>, Out<T10>, Out<T11>, Out<T12>, Out<T13>]): [T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13];
+
+declare function useCellValueWithStore<T>(cell: Out<T>): T;
+
+/**
+ * Returns a reference to the current engine instance created in the {@link EngineProvider}.
+ *
+ * @remarks Accessing the engine instance directly in React is rarely needed.
+ * Use {@link useCellValue} and {@link usePublisher} to interact with the nodes.
+ * @category React Hooks and Components
+ */
+export declare function useEngine(): Engine;
+
+export declare const useIsomorphicLayoutEffect: typeof React_2.useLayoutEffect;
+
+/**
+ * Returns a function that publishes its passed argument into the specified node.
+ * @param node$ - the node to publish in.
+ * @typeParam T - The type of values that the node accepts.
+ * @returns The publisher function for the passed `node$`.
+ *
+ * @example
+ * ```tsx
+ * import {Stream, e, usePublisher} from '@virtuoso.dev/reactive-engine'
+ *
+ * const stream$ = Stream<number>()
+ * e.sub(stream, (value) => console.log(`${value} was published in the stream`))
+ *
+ * //...
+ * function MyComponent() {
+ *  const pub = usePublisher(stream);
+ *  return <button onClick={() => pub(2)}>Push a value into the stream</button>
+ * }
+ * ```
+ *
+ * @category React Hooks and Components
+ */
+export declare function usePublisher<T>(node$: Inp<T>): (value: T) => void;
+
+export { }

package/dist/index.js

@@ -0,0 +1,63 @@
+import { jsx as g } from "react/jsx-runtime";
+import { Engine as m } from "@virtuoso.dev/reactive-engine-core";
+import * as t from "react";
+import C from "tiny-invariant";
+const i = typeof document < "u" ? t.useLayoutEffect : t.useEffect, c = t.createContext(null);
+function o() {
+  const e = t.useContext(c);
+  return C(e !== null, "useEngine must be used within an EngineProvider"), e;
+}
+function E(e) {
+  const n = o();
+  n.register(e);
+  const u = t.useCallback((r) => n.sub(e, r), [n, e]);
+  return t.useSyncExternalStore(
+    u,
+    () => n.getValue(e),
+    () => n.getValue(e)
+  );
+}
+function b(e) {
+  const n = o();
+  n.register(e);
+  const [u, r] = t.useState(() => n.getValue(e));
+  return i(() => n.sub(e, r), [n, e]), u;
+}
+const l = "useSyncExternalStore" in t ? E : b;
+function d(...e) {
+  const n = o(), u = t.useMemo(() => n.combineCells(e), [n, ...e]);
+  return l(u);
+}
+function p(e) {
+  const n = o();
+  return n.register(e), t.useCallback(
+    (u) => {
+      n.pub(e, u);
+    },
+    [n, e]
+  );
+}
+function v(e) {
+  return [l(e), p(e)];
+}
+const y = ({ children: e, engineId: n, initWith: u, updateWith: r = {} }) => {
+  const [s, f] = t.useState(null);
+  return i(() => {
+    const a = new m(u, n);
+    return f(a), () => {
+      a.dispose();
+    };
+  }, [u, n]), i(() => {
+    s == null || s.pubIn(r);
+  }, [r, s]), s && /* @__PURE__ */ g(c.Provider, { value: s, children: e });
+};
+export {
+  c as EngineContext,
+  y as EngineProvider,
+  v as useCell,
+  l as useCellValue,
+  d as useCellValues,
+  o as useEngine,
+  i as useIsomorphicLayoutEffect,
+  p as usePublisher
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@virtuoso.dev/reactive-engine-react",
+  "private": false,
+  "sideEffects": false,
+  "type": "module",
+  "version": "0.0.2",
+  "module": "dist/index.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/petyosi/react-virtuoso.git",
+    "directory": "packages/reactive-engine-react"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "tiny-invariant": "^1.3.3"
+  },
+  "peerDependencies": {
+    "@virtuoso.dev/reactive-engine-core": ">=0.0.2",
+    "react": ">= 18",
+    "react-dom": ">= 18"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.0",
+    "@types/node": "^22.10.1",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitest/browser": "^4.0.16",
+    "@vitest/browser-playwright": "^4.0.16",
+    "@vitejs/plugin-react": "^4.5.0",
+    "eslint": "^9.24.0",
+    "jsdom": "^27.4.0",
+    "playwright": "^1.33.0",
+    "prettier": "^3.5.3",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "typescript": "~5.9.3",
+    "vite": "^6.4.1",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.16",
+    "vitest-browser-react": "^2.0.2",
+    "@virtuoso.dev/reactive-engine-core": "0.0.2",
+    "@virtuoso.dev/tooling": "0.1.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc && vite build",
+    "test": "vitest --run --passWithNoTests --browser.headless",
+    "lint": "eslint",
+    "typecheck": "tsgo --noEmit",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  }
+}