feat: hooks to use reactive values in react

Author: Wroud

packages/@wroud/react-reactive-value/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Aleksei Potsetsuev (Wroud)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/@wroud/react-reactive-value/README.md

@@ -0,0 +1,138 @@
+# @wroud/react-reactive-value
+
+[![ESM-only package][package]][esm-info-url]
+[![NPM version][npm]][npm-url]
+
+[package]: https://img.shields.io/badge/package-ESM--only-ffe536.svg
+[esm-info-url]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+[npm]: https://img.shields.io/npm/v/@wroud/react-reactive-value.svg
+[npm-url]: https://npmjs.com/package/@wroud/react-reactive-value
+
+@wroud/react-reactive-value is a lightweight library for managing reactive values in React applications. It provides a simple and efficient way to create and use reactive state that automatically triggers re-renders when values change.
+
+## Features
+
+- **React Integration**: Seamlessly integrates with React components for automatic updates.
+- **Performance Optimized**: Minimizes unnecessary re-renders through smart dependency tracking.
+- **TypeScript**: Written in TypeScript for type safety.
+- **Lightweight**: Small bundle size with zero dependencies.
+- [Pure ESM package][esm-info-url]
+
+## Installation
+
+Install via npm:
+
+```sh
+npm install @wroud/react-reactive-value
+```
+
+Install via yarn:
+
+```sh
+yarn add @wroud/react-reactive-value
+```
+
+## Documentation
+
+For detailed usage and API reference, visit the [documentation site](https://wroud.dev).
+
+## Example
+
+```tsx
+import { useCreateReactiveValue, useReactiveValue } from "@wroud/react-reactive-value";
+import { useState, createContext, useContext } from "react";
+
+// Create a counter store outside of components
+function createCounterStore() {
+  // Private state
+  let count = 0;
+  const listeners = new Set<() => void>();
+  
+  // Notify listeners when state changes
+  const notifyListeners = () => {
+    listeners.forEach(listener => listener());
+  };
+  
+  // Public API
+  return {
+    getValue: () => count,
+    increment: () => {
+      count++;
+      notifyListeners();
+    },
+    subscribe: (onValueChange: () => void) => {
+      listeners.add(onValueChange);
+      return () => {
+        listeners.delete(onValueChange);
+      };
+    }
+  };
+}
+
+// Create a context to share the reactive value
+const CounterContext = createContext(null);
+
+// Provider component that creates the reactive value
+function CounterProvider({ children }) {
+  // Create a singleton store
+  const counterStore = useState(() => createCounterStore())[0];
+  
+  // Create reactive value from the store
+  const counter = useCreateReactiveValue(
+    // Getter function
+    () => counterStore.getValue(),
+    // Subscribe function
+    (onValueChange) => counterStore.subscribe(onValueChange),
+    [counterStore] // Dependencies
+  );
+  
+  return (
+    <CounterContext.Provider value={{ counter, counterStore }}>
+      {children}
+    </CounterContext.Provider>
+  );
+}
+
+// Consumer component that uses the reactive value
+function CounterDisplay() {
+  // Get the reactive value from context
+  const { counter } = useContext(CounterContext);
+  
+  // Use the reactive value in the component
+  const count = useReactiveValue(counter);
+  
+  return <p>Count: {count}</p>;
+}
+
+// Consumer component that updates the value
+function CounterControls() {
+  // Get the store from context
+  const { counterStore } = useContext(CounterContext);
+  
+  return (
+    <button onClick={() => counterStore.increment()}>
+      Increment
+    </button>
+  );
+}
+
+// Main component that composes the application
+function CounterApp() {
+  return (
+    <CounterProvider>
+      <div>
+        <CounterDisplay />
+        <CounterControls />
+      </div>
+    </CounterProvider>
+  );
+}
+```
+
+## Changelog
+
+All notable changes to this project will be documented in the [CHANGELOG](./CHANGELOG.md) file.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details. 

packages/@wroud/react-reactive-value/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@wroud/react-reactive-value",
+  "version": "0.0.1",
+  "type": "module",
+  "sideEffects": [],
+  "license": "MIT",
+  "author": "Wroud",
+  "homepage": "https://wroud.dev/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Wroud/foundation",
+    "directory": "packages/@wroud/react-reactive-value"
+  },
+  "description": "A lightweight library for managing reactive values in React applications that efficiently triggers re-renders when values change",
+  "keywords": [
+    "react",
+    "reactive",
+    "state",
+    "hooks",
+    "performance",
+    "typescript",
+    "esm"
+  ],
+  "exports": {
+    ".": "./lib/index.js",
+    "./*": "./lib/*.js"
+  },
+  "scripts": {
+    "ci:release": "ci release --prefix react-reactive-value-v",
+    "ci:git-tag": "ci git-tag --prefix react-reactive-value-v",
+    "ci:release-github": "ci release-github --prefix react-reactive-value-v",
+    "test": "tests-runner",
+    "test:ci": "CI=true yarn run test",
+    "build": "tsc -b",
+    "watch:tsc": "tsc -b -w",
+    "dev": "concurrently \"npm:watch:*\"",
+    "clear": "rimraf lib"
+  },
+  "files": [
+    "package.json",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "lib",
+    "!lib/**/*.d.ts.map",
+    "!lib/**/*.test.js",
+    "!lib/**/*.test.d.ts",
+    "!lib/**/*.test.d.ts.map",
+    "!lib/**/*.test.js.map",
+    "!lib/tests",
+    "!.tsbuildinfo"
+  ],
+  "packageManager": "yarn@4.6.0",
+  "devDependencies": {
+    "@types/react": "^18.0.0 || ^19.0.0",
+    "@vitest/coverage-v8": "^2",
+    "@wroud/ci": "workspace:*",
+    "@wroud/tests-runner": "workspace:*",
+    "@wroud/tsconfig": "workspace:^",
+    "react": "^18.0.0 || ^19.0.0",
+    "rimraf": "^6",
+    "typescript": "^5",
+    "vitest": "^2"
+  },
+  "peerDependencies": {
+    "react": "^17.0.0 || ^18.0.0 || ^19.0.0"
+  }
+}

packages/@wroud/react-reactive-value/src/IReactiveValue.ts

@@ -0,0 +1,9 @@
+export type IReactiveValueSubscribe<TArgs extends any[]> = (
+  onValueChange: () => void,
+  ...args: TArgs
+) => () => void;
+
+export interface IReactiveValue<T, TArgs extends any[]> {
+  get(...args: TArgs): T;
+  subscribe: IReactiveValueSubscribe<TArgs>;
+}

packages/@wroud/react-reactive-value/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./useCreateReactiveValue.js";
+export * from "./useReactiveValue.js";
+export * from "./useReactiveValues.js";
+export * from "./IReactiveValue.js";

packages/@wroud/react-reactive-value/src/useCreateReactiveValue.ts

@@ -0,0 +1,22 @@
+import { useMemo } from "react";
+import type {
+  IReactiveValue,
+  IReactiveValueSubscribe,
+} from "./IReactiveValue.js";
+
+type NoInfer<T> = intrinsic;
+export function useCreateReactiveValue<T, TArgs extends any[]>(
+  get: (...args: TArgs) => T,
+  subscribe: NoInfer<IReactiveValueSubscribe<TArgs>> | null,
+  deps: React.DependencyList,
+): IReactiveValue<T, TArgs> {
+  const value = useMemo<IReactiveValue<T, TArgs>>(
+    () => ({
+      get,
+      subscribe: subscribe ?? (() => () => {}),
+    }),
+    deps,
+  );
+
+  return value;
+}

packages/@wroud/react-reactive-value/src/useReactiveValue.ts

@@ -0,0 +1,42 @@
+import { useMemo, useSyncExternalStore } from "react";
+import type { IReactiveValue } from "./IReactiveValue.js";
+
+export function useReactiveValue<
+  P extends IReactiveValue<any, any[]> | undefined,
+>(
+  value: P,
+  ...args: P extends IReactiveValue<any, infer T> ? T : never
+): P extends IReactiveValue<infer T, any[]> ? T : undefined {
+  const mappedValue = useMemo(
+    () => ({
+      cache: null as any,
+      cacheInvalidated: true,
+      subscribe: (onValueChange: () => void) => {
+        if (value) {
+          return value.subscribe(
+            () => {
+              mappedValue.cacheInvalidated = true;
+              return onValueChange();
+            },
+            ...args,
+          );
+        }
+
+        return () => {};
+      },
+      get: () => {
+        if (mappedValue.cacheInvalidated) {
+          mappedValue.cache = value?.get(...args);
+          mappedValue.cacheInvalidated = false;
+        }
+        return mappedValue.cache;
+      },
+    }),
+    [value, ...args],
+  );
+  return useSyncExternalStore(
+    mappedValue.subscribe,
+    mappedValue.get,
+    mappedValue.get,
+  );
+}

packages/@wroud/react-reactive-value/src/useReactiveValues.ts

@@ -0,0 +1,72 @@
+import { useCallback, useMemo, useRef, useSyncExternalStore } from "react";
+import type { IReactiveValue } from "./IReactiveValue.js";
+
+export function useReactiveValues<
+  P extends IReactiveValue<any, any[]> | undefined,
+>(
+  value: P,
+  onChange?: (
+    ...args: P extends IReactiveValue<any, infer T> ? T : never[]
+  ) => void,
+) {
+  const onChangeRef = useRef(onChange);
+  const valueChangeRef = useRef(() => {});
+  const subscribeRef = useRef<Array<() => void>>([]);
+
+  onChangeRef.current = onChange;
+
+  for (const unsubscribe of subscribeRef.current) {
+    unsubscribe();
+  }
+  subscribeRef.current = [];
+
+  const mappedValue = useMemo(
+    () => ({
+      cache: null as any,
+      cacheInvalidated: true,
+      subscribe: (onValueChange: () => void) => {
+        valueChangeRef.current = onValueChange;
+
+        return () => {
+          for (const unsubscribe of subscribeRef.current) {
+            unsubscribe();
+          }
+        };
+      },
+      get: () => {
+        if (mappedValue.cacheInvalidated) {
+          mappedValue.cache = {};
+          mappedValue.cacheInvalidated = false;
+        }
+        return mappedValue.cache;
+      },
+    }),
+    [value],
+  );
+
+  useSyncExternalStore(mappedValue.subscribe, mappedValue.get, mappedValue.get);
+
+  return useCallback(
+    (
+      ...args: P extends IReactiveValue<any, infer T> ? T : never[]
+    ): P extends IReactiveValue<infer T, any[]> ? T : undefined => {
+      if (value) {
+        subscribeRef.current.push(
+          value.subscribe(
+            () => {
+              mappedValue.cacheInvalidated = true;
+              valueChangeRef.current();
+              onChangeRef.current?.(...args);
+            },
+            ...args,
+          ),
+        );
+
+        return value.get(...args);
+      }
+
+      return undefined as any;
+    },
+    [value],
+  );
+}