@hoosk/minisignals-react 1.0.8 → 1.1.0

package/README.md

@@ -14,7 +14,6 @@ npm install @hoosk/minisignals @hoosk/minisignals-react
 
 ```tsx
 import { useSignal, useSignalValue } from '@hoosk/minisignals-react';
-
 function Counter() {
   // Create a local signal that survives re-renders
   const count = useSignal(0);
@@ -31,6 +30,40 @@ function Counter() {
 }
 ```
 
+### `useComputed(fn, deps?)`
+
+Creates a `Computed<T>` that survives re-renders and is disposed automatically on unmount or when `deps` change:
+
+```tsx
+import { signal } from '@hoosk/minisignals';
+import { useComputed, useSignalValue } from '@hoosk/minisignals-react';
+
+const price = signal(100);
+
+function Total({ quantity }: { quantity: number }) {
+  const total = useComputed(() => price.value * quantity, [quantity]);
+  return <p>{useSignalValue(total)}</p>;
+}
+```
+
+### `useSignalEffect(fn, deps?)`
+
+Runs a core `effect` bound to the component lifecycle. The callback may return a cleanup function, which runs before each re-execution and on unmount:
+
+```tsx
+import { signal } from '@hoosk/minisignals';
+import { useSignalEffect } from '@hoosk/minisignals-react';
+
+const count = signal(0);
+
+function Title() {
+  useSignalEffect(() => {
+    document.title = `Count: ${count.value}`;
+  });
+  return null;
+}
+```
+
 ### `useSignalValue` accepts any `ReadonlySignal`
 
 `useSignalValue` accepts both `Signal<T>` and `Computed<T>` via the shared `ReadonlySignal<T>` interface, so you can pass either directly:

package/dist/index.cjs

@@ -20,7 +20,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  useComputed: () => useComputed,
   useSignal: () => useSignal,
+  useSignalEffect: () => useSignalEffect,
   useSignalValue: () => useSignalValue
 });
 module.exports = __toCommonJS(index_exports);
@@ -45,9 +47,9 @@ function useSignalValue(sig) {
   );
   return (0, import_react.useSyncExternalStore)(
     subscribe,
-    () => sig.value,
+    () => sig.peek(),
     // getSnapshot
-    () => sig.value
+    () => sig.peek()
     // getServerSnapshot (SSR support)
   );
 }
@@ -62,8 +64,35 @@ function useSignal(initialValue) {
   }
   return signalRef.current;
 }
+
+// src/useComputed.ts
+var import_react3 = require("react");
+var import_minisignals3 = require("@hoosk/minisignals");
+function useComputed(fn, deps = []) {
+  const fnRef = (0, import_react3.useRef)(fn);
+  fnRef.current = fn;
+  const instance = (0, import_react3.useMemo)(
+    () => (0, import_minisignals3.computed)(() => fnRef.current()),
+    deps
+  );
+  (0, import_react3.useEffect)(() => () => instance.dispose(), [instance]);
+  return instance;
+}
+
+// src/useSignalEffect.ts
+var import_react4 = require("react");
+var import_minisignals4 = require("@hoosk/minisignals");
+function useSignalEffect(fn, deps = []) {
+  const fnRef = (0, import_react4.useRef)(fn);
+  fnRef.current = fn;
+  (0, import_react4.useEffect)(() => {
+    return (0, import_minisignals4.effect)(() => fnRef.current());
+  }, deps);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  useComputed,
   useSignal,
+  useSignalEffect,
   useSignalValue
 });

package/dist/index.d.cts

@@ -1,4 +1,5 @@
-import { ReadonlySignal, Signal } from '@hoosk/minisignals';
+import { ReadonlySignal, Signal, Computed } from '@hoosk/minisignals';
+import { DependencyList } from 'react';
 
 /**
  * A hook that subscribes to a signal or computed value and triggers
@@ -20,4 +21,29 @@ declare function useSignalValue<T>(sig: ReadonlySignal<T>): T;
  */
 declare function useSignal<T>(initialValue: T): Signal<T>;
 
-export { useSignal, useSignalValue };
+/**
+ * Creates a computed signal tied to the component's lifecycle.
+ *
+ * The instance is stable across re-renders unless `deps` changes. It is
+ * automatically disposed when the component unmounts, preventing the source
+ * signals from retaining subscriptions to unmounted components.
+ *
+ * @param fn The derivation function. The latest closure is always used.
+ * @param deps Optional dependency list that recreates the computed instance.
+ * @returns A stable Computed instance.
+ */
+declare function useComputed<T>(fn: () => T, deps?: DependencyList): Computed<T>;
+
+/**
+ * Runs a reactive effect tied to the component's lifecycle.
+ *
+ * The effect is created on mount, re-created when `deps` change, and stopped
+ * on unmount. The callback may return a cleanup function, which runs before
+ * each re-execution and when the effect is stopped.
+ *
+ * @param fn The effect callback. The latest closure is always used.
+ * @param deps Optional dependency list that recreates the effect.
+ */
+declare function useSignalEffect(fn: () => void | (() => void), deps?: DependencyList): void;
+
+export { useComputed, useSignal, useSignalEffect, useSignalValue };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { ReadonlySignal, Signal } from '@hoosk/minisignals';
+import { ReadonlySignal, Signal, Computed } from '@hoosk/minisignals';
+import { DependencyList } from 'react';
 
 /**
  * A hook that subscribes to a signal or computed value and triggers
@@ -20,4 +21,29 @@ declare function useSignalValue<T>(sig: ReadonlySignal<T>): T;
  */
 declare function useSignal<T>(initialValue: T): Signal<T>;
 
-export { useSignal, useSignalValue };
+/**
+ * Creates a computed signal tied to the component's lifecycle.
+ *
+ * The instance is stable across re-renders unless `deps` changes. It is
+ * automatically disposed when the component unmounts, preventing the source
+ * signals from retaining subscriptions to unmounted components.
+ *
+ * @param fn The derivation function. The latest closure is always used.
+ * @param deps Optional dependency list that recreates the computed instance.
+ * @returns A stable Computed instance.
+ */
+declare function useComputed<T>(fn: () => T, deps?: DependencyList): Computed<T>;
+
+/**
+ * Runs a reactive effect tied to the component's lifecycle.
+ *
+ * The effect is created on mount, re-created when `deps` change, and stopped
+ * on unmount. The callback may return a cleanup function, which runs before
+ * each re-execution and when the effect is stopped.
+ *
+ * @param fn The effect callback. The latest closure is always used.
+ * @param deps Optional dependency list that recreates the effect.
+ */
+declare function useSignalEffect(fn: () => void | (() => void), deps?: DependencyList): void;
+
+export { useComputed, useSignal, useSignalEffect, useSignalValue };

package/dist/index.js

@@ -18,9 +18,9 @@ function useSignalValue(sig) {
   );
   return useSyncExternalStore(
     subscribe,
-    () => sig.value,
+    () => sig.peek(),
     // getSnapshot
-    () => sig.value
+    () => sig.peek()
     // getServerSnapshot (SSR support)
   );
 }
@@ -35,7 +35,34 @@ function useSignal(initialValue) {
   }
   return signalRef.current;
 }
+
+// src/useComputed.ts
+import { useEffect, useMemo, useRef as useRef2 } from "react";
+import { computed } from "@hoosk/minisignals";
+function useComputed(fn, deps = []) {
+  const fnRef = useRef2(fn);
+  fnRef.current = fn;
+  const instance = useMemo(
+    () => computed(() => fnRef.current()),
+    deps
+  );
+  useEffect(() => () => instance.dispose(), [instance]);
+  return instance;
+}
+
+// src/useSignalEffect.ts
+import { useEffect as useEffect2, useRef as useRef3 } from "react";
+import { effect as effect2 } from "@hoosk/minisignals";
+function useSignalEffect(fn, deps = []) {
+  const fnRef = useRef3(fn);
+  fnRef.current = fn;
+  useEffect2(() => {
+    return effect2(() => fnRef.current());
+  }, deps);
+}
 export {
+  useComputed,
   useSignal,
+  useSignalEffect,
   useSignalValue
 };

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@hoosk/minisignals-react",
-  "version": "1.0.8",
+  "version": "1.1.0",
   "description": "React adapter for @hoosk/minisignals",
   "type": "module",
+  "sideEffects": false,
   "main": "dist/index.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,7 +19,7 @@
     "react": ">=18.0.0"
   },
   "dependencies": {
-    "@hoosk/minisignals": "^1.1.0"
+    "@hoosk/minisignals": "^1.2.0"
   },
   "devDependencies": {
     "@testing-library/react": "^14.2.1",
@@ -35,6 +36,21 @@
     "prepare": "npm run build",
     "test": "vitest run"
   },
+  "keywords": [
+    "signals",
+    "reactive",
+    "reactivity",
+    "state",
+    "react",
+    "hooks",
+    "signal",
+    "useSyncExternalStore"
+  ],
   "author": "Hoosk",
-  "license": "MIT"
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hoosk/minisignals.git",
+    "directory": "packages/react"
+  }
 }

package/tests/adapter.test.tsx

@@ -1,8 +1,8 @@
 import React, { useState } from 'react';
 import { describe, it, expect, vi } from 'vitest';
 import { render, screen, act, cleanup } from '@testing-library/react';
-import { signal, computed, batch } from '@hoosk/minisignals';
-import { useSignalValue, useSignal } from '../src/index.ts';
+import { signal, computed, batch, type Computed } from '@hoosk/minisignals';
+import { useSignalValue, useSignal, useComputed, useSignalEffect } from '../src/index.ts';
 
 describe('@hoosk/minisignals-react adapter', () => {
   describe('useSignalValue()', () => {
@@ -214,4 +214,142 @@ describe('@hoosk/minisignals-react adapter', () => {
       expect(screen.getByTestId('v').textContent).toBe('1');
     });
   });
+
+  describe('useComputed()', () => {
+    it('should derive values and stay in sync with source signals', () => {
+      const price = signal(100);
+
+      const TestComponent = () => {
+        const doubled = useComputed(() => price.value * 2);
+        const value = useSignalValue(doubled);
+        return <div data-testid="computed">{value}</div>;
+      };
+
+      render(<TestComponent />);
+      expect(screen.getByTestId('computed').textContent).toBe('200');
+
+      act(() => { price.value = 150; });
+      expect(screen.getByTestId('computed').textContent).toBe('300');
+    });
+
+    it('should dispose the computed instance on unmount', () => {
+      const source = signal(1);
+      let captured: Computed<number> | null = null;
+
+      const TestComponent = () => {
+        const instance = useComputed(() => source.value * 10);
+        captured = instance;
+        useSignalValue(instance);
+        return <div>{instance.value}</div>;
+      };
+
+      const { unmount } = render(<TestComponent />);
+      expect(captured!.value).toBe(10);
+
+      unmount();
+      source.value = 2;
+
+      // Disposed computeds are frozen at their last value.
+      expect(captured!.value).toBe(10);
+    });
+
+    it('should dispose and recreate the computed when deps change', () => {
+      const source = signal(1);
+      const instances: Computed<number>[] = [];
+
+      const TestComponent = ({ factor }: { factor: number }) => {
+        const instance = useComputed(() => source.value * factor, [factor]);
+        instances.push(instance);
+        const value = useSignalValue(instance);
+        return <div data-testid="v">{value}</div>;
+      };
+
+      const { rerender } = render(<TestComponent factor={2} />);
+      expect(screen.getByTestId('v').textContent).toBe('2');
+
+      rerender(<TestComponent factor={3} />);
+      expect(screen.getByTestId('v').textContent).toBe('3');
+
+      const first = instances[0];
+      const last = instances[instances.length - 1];
+      expect(first).not.toBe(last);
+
+      source.value = 2;
+
+      // The old instance was disposed by the deps change.
+      expect(first.value).toBe(2);
+      expect(last.value).toBe(6);
+    });
+  });
+
+  describe('useSignalEffect()', () => {
+    it('should run the effect and react to signal changes', () => {
+      const count = signal(0);
+      const spy = vi.fn();
+
+      const TestComponent = () => {
+        useSignalEffect(() => {
+          spy(count.value);
+        });
+        return <div />;
+      };
+
+      render(<TestComponent />);
+      expect(spy).toHaveBeenCalledTimes(1);
+      expect(spy).toHaveBeenLastCalledWith(0);
+
+      act(() => { count.value = 1; });
+      expect(spy).toHaveBeenCalledTimes(2);
+      expect(spy).toHaveBeenLastCalledWith(1);
+    });
+
+    it('should run cleanup before a re-run and on unmount', () => {
+      const count = signal(0);
+      const cleanup = vi.fn();
+
+      const TestComponent = () => {
+        useSignalEffect(() => {
+          count.value;
+          return cleanup;
+        });
+        return <div />;
+      };
+
+      const { unmount } = render(<TestComponent />);
+      expect(cleanup).toHaveBeenCalledTimes(0);
+
+      act(() => { count.value = 1; });
+      expect(cleanup).toHaveBeenCalledTimes(1);
+
+      unmount();
+      expect(cleanup).toHaveBeenCalledTimes(2);
+
+      act(() => { count.value = 2; });
+      expect(cleanup).toHaveBeenCalledTimes(2);
+    });
+
+    it('should recreate the effect when deps change', () => {
+      const count = signal(0);
+      const spy = vi.fn();
+
+      const TestComponent = ({ id }: { id: number }) => {
+        useSignalEffect(() => {
+          spy(id, count.value);
+        }, [id]);
+        return <div />;
+      };
+
+      const { rerender } = render(<TestComponent id={1} />);
+      expect(spy).toHaveBeenCalledTimes(1);
+
+      rerender(<TestComponent id={2} />);
+      // Cleanup of the old effect + initial run of the new one.
+      expect(spy).toHaveBeenCalledTimes(2);
+      expect(spy).toHaveBeenLastCalledWith(2, 0);
+
+      act(() => { count.value = 5; });
+      expect(spy).toHaveBeenCalledTimes(3);
+      expect(spy).toHaveBeenLastCalledWith(2, 5);
+    });
+  });
 });