feat: adds rv.infer and useRvEffect functions

Author: rasulomaroff

eslint.config.ts

@@ -15,6 +15,7 @@ export default [
             '@typescript-eslint/consistent-type-definitions': 'off',
             '@typescript-eslint/consistent-type-assertions': 'off',
             '@typescript-eslint/unbound-method': 'off',
+            '@typescript-eslint/no-namespace': 'off',
         },
     },
     {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-rv",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "react-rv is a lightweight and efficient state management library for React that allows you to create reactive variables and subscribe to them with minimal overhead.",
   "files": [
     "dist"

readme.md

@@ -9,6 +9,7 @@ react-rv is a lightweight and efficient state management library for React that
 - **Efficient**: Only re-renders components that are subscribed to reactive variables.
 - **Flexible**: Works inside and outside React components.
 - **Custom equality checks**: Define your own comparison logic to avoid redundant updates.
+- **Stateless update subscriptions**: If you only need to read state updates without updating your component.
 - **TypeScript Support**: Fully typed for better developer experience.
 
 ##  Installation
@@ -80,13 +81,35 @@ const Component = () => {
 }
 ```
 
+- Listening to a state change without updating current component
+
+```tsx
+const Component = () => {
+    // the callback is going to be called when a variable changes,
+    // but this component won't be rerendered
+    useRvEffect(darkTheme, isEnabled => {
+        console.log(isEnabled)
+    })
+
+    return ...
+}
+```
+
+- Infer the type of the reactive variable
+
+```ts
+const darkTheme = rv(false)
+type DarkTheme = rv.infer<typeof darkTheme> // boolean
+```
+
 ## Why `react-rv` Over React Context?
 
 - **More granual state splitting**: React Context would require to create a separate context for every piece of state you'd use, which would also force you to wrap the app with providers for each react context.
 If you don't do that and decide to create one big state, it would involve unnecessary re-renders in components that only need one field of the state.
 - **Simpler API**: No need for providers, reducers, or complex state logic.
 - **No need for state setters**: The variable that's returned by `rv()` function is already a getter/setter itself.
 - **Usage outside React component tree**: Since the variable itself is a setter as well, you can use it outside react component tree. For example in your util functions that's defined outside react components.
+- **State listeners**: Allows you to listen to state changes without rerendering a current component. Useful for side-effects.
 
 #### React Context example
 

src/index.ts

@@ -2,5 +2,6 @@
 
 export { rv } from './rv'
 export { useRv } from './use-rv'
+export { useRvEffect } from './use-rv-effect'
 
 export type * from './types'

src/rv.spec-d.ts

@@ -157,3 +157,34 @@ describe('rv function', () => {
         val(3)
     })
 })
+
+describe('rv.infer method', () => {
+    it('infers a primitive type of rv', () => {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const num = rv(3)
+
+        type Inferred = rv.infer<typeof num>
+
+        expectTypeOf<Inferred>().toBeNumber()
+    })
+
+    it('infers a complex type of rv', () => {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const obj = rv({ name: '', age: 0, data: {} })
+
+        type Inferred = rv.infer<typeof obj>
+
+        // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+        expectTypeOf<Inferred>().toMatchObjectType<{ name: string; age: number; data: {} }>()
+    })
+
+    it('infers as never and throws a type error if it is not a reactive variable', () => {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const justNumber = 30
+
+        // @ts-expect-error should throw an error since it's not a reactive variable
+        type Inferred = rv.infer<typeof justNumber>
+
+        expectTypeOf<Inferred>().toBeNever()
+    })
+})

src/rv.spec.ts

@@ -52,6 +52,17 @@ describe('rv function', () => {
         expect(listener).toHaveBeenCalledExactlyOnceWith(3, 2)
     })
 
+    it('unsubscribes a listener', () => {
+        const val = rv(2)
+        const listener = vi.fn()
+
+        val.on(listener)
+        val.off(listener)
+
+        val(3)
+        expect(listener).not.toHaveBeenCalled()
+    })
+
     it('allows to pass the default listener', () => {
         const listener = vi.fn(() => {})
 

src/rv.ts

@@ -108,3 +108,18 @@ export function rv<T>(val: T, opts?: RvInitOptions<T>): Rv<T> {
  */
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 rv.fn = <T>(init: () => T, options?: RvInitOptions<T>) => rv(init(), options)
+
+export namespace rv {
+    /**
+     * Infers the type of the reactive variable.
+     *
+     * @example
+     * ```ts
+     * const darkMode = rv(false)
+     *
+     * type DarkMode = rv.infer<typeof darkMode> // infers as boolean
+     * ```
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    export type infer<T extends Rv<any>> = T extends Rv<infer X> ? X : never
+}

src/use-rv-effect.spec-d.ts

@@ -0,0 +1,25 @@
+import { renderHook } from '@testing-library/react'
+import { useRvEffect } from './use-rv-effect'
+import { rv } from './rv'
+
+describe('useRvEffect hook', () => {
+    it('should infer payload type correctly', () => {
+        const counter = rv(0)
+
+        renderHook(() => {
+            useRvEffect(counter, (newVal, oldVal) => {
+                expectTypeOf(newVal).toBeNumber()
+                expectTypeOf(oldVal).toBeNumber()
+            })
+        })
+
+        const stringVar = rv<'one' | 'two'>('one')
+
+        renderHook(() => {
+            useRvEffect(stringVar, (newVal, oldVal) => {
+                expectTypeOf(newVal).toEqualTypeOf<'one' | 'two'>()
+                expectTypeOf(oldVal).toEqualTypeOf<'one' | 'two'>()
+            })
+        })
+    })
+})

src/use-rv-effect.spec.ts

@@ -0,0 +1,98 @@
+import { renderHook, act } from '@testing-library/react'
+import { useRvEffect } from './use-rv-effect'
+import { rv } from './rv'
+
+describe('useRvEffect hook', () => {
+    it('should listen to rv updates', () => {
+        const handler = vi.fn()
+        const counter = rv(0)
+
+        renderHook(() => {
+            useRvEffect(counter, handler)
+        })
+
+        act(() => {
+            counter(1)
+        })
+
+        expect(handler).toHaveBeenCalledWith(1, 0)
+        expect(handler).toHaveBeenCalledTimes(1)
+    })
+
+    it(`should not be triggered if state didn't change`, () => {
+        const handler = vi.fn()
+        const counter = rv(0)
+
+        renderHook(() => {
+            useRvEffect(counter, handler)
+        })
+
+        // no change
+        act(() => {
+            counter(0)
+        })
+
+        expect(handler).not.toHaveBeenCalled()
+    })
+
+    it('always has the most recent scope', () => {
+        const counter = rv(0)
+        const values: number[] = []
+
+        const { rerender } = renderHook(
+            ({ multiplier }: { multiplier: number }) => {
+                useRvEffect(counter, v => {
+                    values.push(v * multiplier)
+                })
+            },
+            { initialProps: { multiplier: 1 } },
+        )
+
+        act(() => {
+            counter(2)
+        })
+
+        rerender({ multiplier: 10 })
+
+        act(() => {
+            counter(3)
+        })
+
+        expect(values).toEqual([2, 30])
+    })
+
+    it('should unsubscribe on unmount', () => {
+        const handler = vi.fn()
+        const counter = rv(0)
+
+        const { unmount } = renderHook(() => {
+            useRvEffect(counter, handler)
+        })
+
+        unmount()
+
+        act(() => {
+            counter(1)
+        })
+
+        expect(handler).not.toHaveBeenCalled()
+    })
+
+    it("doesn't trigger re-render when rv updates", () => {
+        const counter = rv(0)
+        const renderSpy = vi.fn()
+
+        renderHook(() => {
+            renderSpy()
+            useRvEffect(counter, () => {})
+        })
+
+        expect(renderSpy).toHaveBeenCalledTimes(1)
+
+        act(() => {
+            counter(1)
+        })
+
+        expect(renderSpy).toHaveBeenCalledTimes(1) // no re-render
+    })
+})

src/use-rv-effect.ts

@@ -0,0 +1,27 @@
+import { useEffect, useRef } from 'react'
+import type { Listener, Rv } from './types'
+
+/**
+ * React hook to subscribe to updates of a reactive variable.
+ *
+ * Note: callback is always using current scope.
+ *
+ * @example
+ * ```ts
+ * const counter = rv(0)
+ *
+ * useRvEffect(counter, (newVal, oldVal) => {
+ *     console.table({ newVal, oldVal })
+ * })
+ * ```
+ *
+ * @param rv - The reactive variable to subscribe to.
+ * @param f - A callback function triggered whenever the reactive variable is updated.
+ *            The first and second arguments are the new and the old value of this `rv`.
+ */
+export function useRvEffect<T>(rv: Rv<T>, f: Listener<T>): void {
+    const fnRef = useRef(f)
+    fnRef.current = f
+
+    useEffect(() => rv.on((...args) => fnRef.current(...args)), [rv])
+}