@hoosk/minisignals-react 1.0.3 → 1.0.5

package/README.md

@@ -0,0 +1,51 @@
+# @hoosk/minisignals-react
+
+The React 18 adapter for `@hoosk/minisignals`.
+
+This package provides custom hooks to seamlessly integrate the agnostic reactive signals with React's component lifecycle and rendering engine. It utilizes React 18's `useSyncExternalStore` for tear-free concurrent rendering.
+
+## Installation
+
+```bash
+npm install @hoosk/minisignals @hoosk/minisignals-react
+```
+
+## Basic Usage
+
+```tsx
+import { useSignal, useSignalValue } from '@hoosk/minisignals-react';
+
+function Counter() {
+  // Create a local signal that survives re-renders
+  const count = useSignal(0);
+  
+  // Connect the signal to trigger React renders on mutation
+  const value = useSignalValue(count);
+
+  return (
+    <div>
+      <p>Count: {value}</p>
+      <button onClick={() => count.value++}>Increment</button>
+    </div>
+  );
+}
+```
+
+### `useSignalValue` accepts any `ReadonlySignal`
+
+`useSignalValue` accepts both `Signal<T>` and `Computed<T>` via the shared `ReadonlySignal<T>` interface, so you can pass either directly:
+
+```tsx
+import { signal, computed } from '@hoosk/minisignals';
+import { useSignalValue } from '@hoosk/minisignals-react';
+
+const price = signal(100);
+const doubled = computed(() => price.value * 2);
+
+function Price() {
+  const value = useSignalValue(doubled); // works with Computed too
+  return <p>{value}</p>;
+}
+```
+
+For full documentation, please refer to the [main repository README](../../README.md).

package/dist/index.d.cts

@@ -1,14 +1,14 @@
-import { Signal, Computed } from '@hoosk/minisignals';
+import { ReadonlySignal, Signal } from '@hoosk/minisignals';
 
 /**
  * A hook that subscribes to a signal or computed value and triggers
  * a React re-render whenever the value changes.
  * Uses React 18's useSyncExternalStore for tear-free concurrent rendering.
  *
- * @param sig The Signal or Computed to observe.
+ * @param sig Any ReadonlySignal (Signal or Computed) to observe.
  * @returns The current value of the signal.
  */
-declare function useSignalValue<T>(sig: Signal<T> | Computed<T>): T;
+declare function useSignalValue<T>(sig: ReadonlySignal<T>): T;
 
 /**
  * Creates a signal that is tied to the component's lifecycle.

package/dist/index.d.ts

@@ -1,14 +1,14 @@
-import { Signal, Computed } from '@hoosk/minisignals';
+import { ReadonlySignal, Signal } from '@hoosk/minisignals';
 
 /**
  * A hook that subscribes to a signal or computed value and triggers
  * a React re-render whenever the value changes.
  * Uses React 18's useSyncExternalStore for tear-free concurrent rendering.
  *
- * @param sig The Signal or Computed to observe.
+ * @param sig Any ReadonlySignal (Signal or Computed) to observe.
  * @returns The current value of the signal.
  */
-declare function useSignalValue<T>(sig: Signal<T> | Computed<T>): T;
+declare function useSignalValue<T>(sig: ReadonlySignal<T>): T;
 
 /**
  * Creates a signal that is tied to the component's lifecycle.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hoosk/minisignals-react",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "React adapter for @hoosk/minisignals",
   "type": "module",
   "main": "dist/index.js",

package/tests/adapter.test.tsx

@@ -1,14 +1,14 @@
-import React from 'react';
+import React, { useState } from 'react';
 import { describe, it, expect, vi } from 'vitest';
-import { render, screen, act } from '@testing-library/react';
-import { signal, computed } from '@hoosk/minisignals';
+import { render, screen, act, cleanup } from '@testing-library/react';
+import { signal, computed, batch } from '@hoosk/minisignals';
 import { useSignalValue, useSignal } from '../src/index.ts';
 
 describe('@hoosk/minisignals-react adapter', () => {
   describe('useSignalValue()', () => {
     it('should render the initial value of a signal', () => {
       const count = signal(5);
-      
+
       const TestComponent = () => {
         const val = useSignalValue(count);
         return <div>Value: {val}</div>;
@@ -20,7 +20,7 @@ describe('@hoosk/minisignals-react adapter', () => {
 
     it('should trigger a re-render when the signal mutates', () => {
       const count = signal(10);
-      
+
       const TestComponent = () => {
         const val = useSignalValue(count);
         return <div data-testid="display">{val}</div>;
@@ -30,9 +30,7 @@ describe('@hoosk/minisignals-react adapter', () => {
       const display = screen.getByTestId('display');
       expect(display.textContent).toBe('10');
 
-      act(() => {
-        count.value = 20;
-      });
+      act(() => { count.value = 20; });
 
       expect(display.textContent).toBe('20');
     });
@@ -40,7 +38,7 @@ describe('@hoosk/minisignals-react adapter', () => {
     it('should work seamlessly with computed signals', () => {
       const name = signal('A');
       const doubledName = computed(() => name.value + name.value);
-      
+
       const TestComponent = () => {
         const val = useSignalValue(doubledName);
         return <div data-testid="computed-display">{val}</div>;
@@ -50,25 +48,115 @@ describe('@hoosk/minisignals-react adapter', () => {
       const display = screen.getByTestId('computed-display');
       expect(display.textContent).toBe('AA');
 
+      act(() => { name.value = 'B'; });
+
+      expect(display.textContent).toBe('BB');
+    });
+
+    it('NEGATIVE CASE: should unsubscribe when the component unmounts (no memory leak)', () => {
+      const count = signal(0);
+      const renderSpy = vi.fn();
+
+      const TestComponent = () => {
+        renderSpy();
+        const val = useSignalValue(count);
+        return <div>{val}</div>;
+      };
+
+      const { unmount } = render(<TestComponent />);
+      expect(renderSpy).toHaveBeenCalledTimes(1);
+
+      unmount();
+
+      // Mutating after unmount must NOT trigger any render
+      act(() => { count.value = 99; });
+      expect(renderSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('should re-subscribe when the observed signal instance changes', () => {
+      const sigA = signal('A');
+      const sigB = signal('B');
+
+      const TestComponent = ({ which }: { which: 'a' | 'b' }) => {
+        const val = useSignalValue(which === 'a' ? sigA : sigB);
+        return <div data-testid="out">{val}</div>;
+      };
+
+      const { rerender } = render(<TestComponent which="a" />);
+      expect(screen.getByTestId('out').textContent).toBe('A');
+
+      rerender(<TestComponent which="b" />);
+      expect(screen.getByTestId('out').textContent).toBe('B');
+
+      // Mutating the old signal must not re-render
+      act(() => { sigA.value = 'A2'; });
+      expect(screen.getByTestId('out').textContent).toBe('B');
+
+      // Mutating the new signal must re-render
+      act(() => { sigB.value = 'B2'; });
+      expect(screen.getByTestId('out').textContent).toBe('B2');
+    });
+
+    it('should update multiple sibling components sharing the same signal independently', () => {
+      const shared = signal(0);
+      const renderCounts = { a: 0, b: 0 };
+
+      const CompA = () => {
+        renderCounts.a++;
+        return <span data-testid="a">{useSignalValue(shared)}</span>;
+      };
+      const CompB = () => {
+        renderCounts.b++;
+        return <span data-testid="b">{useSignalValue(shared)}</span>;
+      };
+
+      render(<><CompA /><CompB /></>);
+      expect(renderCounts).toEqual({ a: 1, b: 1 });
+
+      act(() => { shared.value = 42; });
+
+      expect(screen.getByTestId('a').textContent).toBe('42');
+      expect(screen.getByTestId('b').textContent).toBe('42');
+      expect(renderCounts).toEqual({ a: 2, b: 2 });
+    });
+
+    it('should only trigger one re-render when signal changes inside a batch', () => {
+      const name = signal('John');
+      const surname = signal('Doe');
+      const renderSpy = vi.fn();
+
+      const TestComponent = () => {
+        renderSpy();
+        const n = useSignalValue(name);
+        const s = useSignalValue(surname);
+        return <div data-testid="full">{n} {s}</div>;
+      };
+
+      render(<TestComponent />);
+      expect(renderSpy).toHaveBeenCalledTimes(1);
+
       act(() => {
-        name.value = 'B';
+        batch(() => {
+          name.value = 'Jane';
+          surname.value = 'Smith';
+        });
       });
 
-      expect(display.textContent).toBe('BB');
+      expect(screen.getByTestId('full').textContent).toBe('Jane Smith');
+      // 2 total: 1 initial + 1 from batch (not 3)
+      expect(renderSpy).toHaveBeenCalledTimes(2);
     });
   });
 
   describe('useSignal()', () => {
     it('should maintain state across re-renders', () => {
       let renderCount = 0;
-      
+
       const TestComponent = () => {
         renderCount++;
-        // Create local signal
         const localCount = useSignal(100);
-        // Subscribe to it to trigger re-renders
         const val = useSignalValue(localCount);
-        
+
         return (
           <div>
             <span data-testid="val">{val}</span>
@@ -78,20 +166,52 @@ describe('@hoosk/minisignals-react adapter', () => {
       };
 
       render(<TestComponent />);
-      
+
       const valSpan = screen.getByTestId('val');
       const btn = screen.getByText('Add');
 
       expect(valSpan.textContent).toBe('100');
       expect(renderCount).toBe(1);
 
-      act(() => {
-        btn.click();
-      });
+      act(() => { btn.click(); });
 
-      // The hook maintained the signal instance, and useSignalValue triggered the re-render
       expect(valSpan.textContent).toBe('101');
       expect(renderCount).toBe(2);
     });
+
+    it('should return the same signal instance across re-renders', () => {
+      let capturedSignal: ReturnType<typeof useSignal<number>> | null = null;
+      let prevSignal: typeof capturedSignal = null;
+      let instanceChanged = false;
+
+      const TestComponent = () => {
+        const sig = useSignal(0);
+        if (capturedSignal !== null && capturedSignal !== sig) instanceChanged = true;
+        capturedSignal = sig;
+        const val = useSignalValue(sig);
+        return <div data-testid="v">{val}</div>;
+      };
+
+      const { rerender } = render(<TestComponent />);
+      rerender(<TestComponent />);
+      rerender(<TestComponent />);
+
+      expect(instanceChanged).toBe(false);
+    });
+
+    it('should ignore the initialValue on subsequent renders', () => {
+      const TestComponent = ({ init }: { init: number }) => {
+        const sig = useSignal(init);
+        const val = useSignalValue(sig);
+        return <div data-testid="v">{val}</div>;
+      };
+
+      const { rerender } = render(<TestComponent init={1} />);
+      expect(screen.getByTestId('v').textContent).toBe('1');
+
+      // Passing a different initial value on re-render must have no effect
+      rerender(<TestComponent init={999} />);
+      expect(screen.getByTestId('v').textContent).toBe('1');
+    });
   });
 });

package/src/index.ts

@@ -1,2 +0,0 @@
-export * from './useSignalValue';
-export * from './useSignal';

package/src/useSignal.ts

@@ -1,20 +0,0 @@
-import { useRef } from 'react';
-import { signal, Signal } from '@hoosk/minisignals';
-
-/**
- * Creates a signal that is tied to the component's lifecycle.
- * The signal instance is preserved across re-renders.
- * NOTE: To trigger a re-render on value change, you must use `useSignalValue(sig)`.
- * 
- * @param initialValue The starting value of the signal.
- * @returns A stable Signal instance.
- */
-export function useSignal<T>(initialValue: T): Signal<T> {
-  const signalRef = useRef<Signal<T> | null>(null);
-
-  if (signalRef.current === null) {
-    signalRef.current = signal(initialValue);
-  }
-
-  return signalRef.current;
-}

package/src/useSignalValue.ts

@@ -1,36 +0,0 @@
-import { useSyncExternalStore, useCallback } from 'react';
-import { effect, Signal, Computed } from '@hoosk/minisignals';
-
-/**
- * A hook that subscribes to a signal or computed value and triggers
- * a React re-render whenever the value changes.
- * Uses React 18's useSyncExternalStore for tear-free concurrent rendering.
- * 
- * @param sig The Signal or Computed to observe.
- * @returns The current value of the signal.
- */
-export function useSignalValue<T>(sig: Signal<T> | Computed<T>): T {
-  const subscribe = useCallback(
-    (onStoreChange: () => void) => {
-      let isInitialRun = true;
-      
-      const unsubscribe = effect(() => {
-        const _val = sig.value;
-        
-        if (!isInitialRun) {
-          onStoreChange();
-        }
-        isInitialRun = false;
-      });
-
-      return unsubscribe;
-    },
-    [sig]
-  );
-
-  return useSyncExternalStore(
-    subscribe,
-    () => sig.value, // getSnapshot
-    () => sig.value  // getServerSnapshot (SSR support)
-  );
-}

package/tsconfig.json

@@ -1,7 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "outDir": "./dist"
-  },
-  "include": ["src/**/*"]
-}