v0.4.2 - see changelog

README.md

@@ -72,6 +72,7 @@ Not in any particular order
   * Test consumer (we only test useContext right now)
 4. Misc hooks
   * Test useEffect/useLayoutEffect are fired at the correct stage
+  * Test useEffectOnce/useLayoutEffectOnce are fired once
   * Test useMemo/useCallback
   * Test useImperativeHandle
   * Test useDebugValue
@@ -88,6 +89,17 @@ Not in any particular order
 <!-- * `R.React.provide` - provider a value through a `Provider` -->
 <!-- * `R.React.consume` - consume a value through a `Consumer` -->
 
+### 0.4.2
+
+New:
+
+* `useEffectOnce` (+ layout and prime variants) - effects which run
+  once at component mount and cleanup once at component dismount.
+* `unsafeUseEffect`, `unsafeUseLayoutEffect`, `unsafeUseMemo`,
+  `unsafeUseCallback`, `unsafeUseImperativeHandle` - unsafe hook
+  variants where you pass an array-like object of memo values without
+  any help from the type system to assert such likeness to an array.
+
 ### 0.4.1
 
 New:

src/Reactix/Hooks.purs

@@ -5,23 +5,29 @@ module Reactix.Hooks
   , useRef
   , useDebugValue, useDebugValue'
   , nothing, thenNothing
+  , useEffectOnce, useEffectOnce'
   , useEffect,  useEffect'
   , useEffect1, useEffect1', useEffectFn1, useEffectFn1'
   , useEffect2, useEffect2', useEffectFn2, useEffectFn2'
   , useEffect3, useEffect3', useEffectFn3, useEffectFn3'
   , useEffect4, useEffect4', useEffectFn4, useEffectFn4'
   , useEffect5, useEffect5', useEffectFn5, useEffectFn5'
+  , unsafeUseEffect
   , useLayoutEffect,  useLayoutEffect'
   , useLayoutEffect1, useLayoutEffect1', useLayoutEffectFn1, useLayoutEffectFn1'
   , useLayoutEffect2, useLayoutEffect2', useLayoutEffectFn2, useLayoutEffectFn2'
   , useLayoutEffect3, useLayoutEffect3', useLayoutEffectFn3, useLayoutEffectFn3'
   , useLayoutEffect4, useLayoutEffect4', useLayoutEffectFn4, useLayoutEffectFn4'
   , useLayoutEffect5, useLayoutEffect5', useLayoutEffectFn5, useLayoutEffectFn5'
+  , unsafeUseLayoutEffect
   , useMemo, useMemo1, useMemo2, useMemo3, useMemo4, useMemo5
+  , unsafeUseMemo
   , useCallback,  useCallback1, useCallback2
   , useCallback3, useCallback4, useCallback5
+  , unsafeUseCallback
   , useImperativeHandle,  useImperativeHandle1, useImperativeHandle2
   , useImperativeHandle3, useImperativeHandle4, useImperativeHandle5
+  , unsafeUseImperativeHandle
   )
  where
 
@@ -105,32 +111,45 @@ thenNothing e = e *> pure nothing
 useEffect :: Effect (Effect Unit) -> Hooks Unit
 useEffect e = hook $ \_ -> pure $ react ... "useEffect" $ [e]
 
+-- | Like useEffect, but runs only once in the lifecycle of the
+-- | component The initial effect will be fired at mount and the
+-- | cleanup effect will be fired at unmount
+useEffectOnce :: Effect (Effect Unit) -> Hooks Unit
+useEffectOnce e = unsafeUseEffect e []
+
 -- | Like useEffect, but with a memo value
 useEffect1 :: forall a. a -> Effect (Effect Unit) -> Hooks Unit
-useEffect1 a e = _useEffect e [a]
+useEffect1 a e = unsafeUseEffect e [a]
 
 -- | Like useEffect, but with 2 memo values
 useEffect2 :: forall a b. a -> b -> Effect (Effect Unit) -> Hooks Unit
-useEffect2 a b e = _useEffect e $ args2 a b
+useEffect2 a b e = unsafeUseEffect e $ args2 a b
 
 -- | Like useEffect, but with 3 memo values
 useEffect3 :: forall a b c. a -> b -> c -> Effect (Effect Unit) -> Hooks Unit
-useEffect3 a b c e = _useEffect e $ args3 a b c
+useEffect3 a b c e = unsafeUseEffect e $ args3 a b c
 
 -- | Like useEffect, but with 4 memo values
 useEffect4 :: forall a b c d. a -> b -> c -> d -> Effect (Effect Unit) -> Hooks Unit
-useEffect4 a b c d e = _useEffect e $ args4 a b c d
+useEffect4 a b c d e = unsafeUseEffect e $ args4 a b c d
 
 -- | Like useEffect, but with 5 memo values
 useEffect5 :: forall a b c d e. a -> b -> c -> d -> e -> Effect (Effect Unit) -> Hooks Unit
-useEffect5 a b c d f e = _useEffect e $ args5 a b c d f
+useEffect5 a b c d f e = unsafeUseEffect e $ args5 a b c d f
 
-_useEffect :: forall a. Effect (Effect Unit) -> a -> Hooks Unit
-_useEffect e a =
+-- | Call React.useEffect passing an array-like object (arguments is
+-- | acceptable) for memo values without any help from the type system
+-- | to guarantee the memo value is in fact array-like.
+unsafeUseEffect :: forall a. Effect (Effect Unit) -> a -> Hooks Unit
+unsafeUseEffect e a =
   hook $ \_ ->
     pure $ react ... "useEffect" $
       args2 e (Array.from a)
 
+-- | Like useEffectOnce, but the provided Effect fn does not return a cleanup handler
+useEffectOnce' :: forall a. Effect a -> Hooks Unit
+useEffectOnce' = useEffectOnce <<< thenNothing
+
 -- | Like useEffect, but the provided Effect fn does not return a cleanup handler
 useEffect' :: forall a. Effect a -> Hooks Unit
 useEffect' = useEffect <<< thenNothing
@@ -206,23 +225,23 @@ useLayoutEffect e = hook $ \_ -> pure $ react ... "useLayoutEffect" $ [ e ]
 
 -- | Like useLayoutEffect, but with a memo value
 useLayoutEffect1 :: forall a. a -> Effect (Effect Unit) -> Hooks Unit
-useLayoutEffect1 a e = _useLayoutEffect e [a]
+useLayoutEffect1 a e = unsafeUseLayoutEffect e [a]
 
 -- | Like useLayoutEffect, but with 2 memo values
 useLayoutEffect2 :: forall a b. a -> b -> Effect (Effect Unit) -> Hooks Unit
-useLayoutEffect2 a b e = _useLayoutEffect e $ args2 a b
+useLayoutEffect2 a b e = unsafeUseLayoutEffect e $ args2 a b
 
 -- | Like useLayoutEffect, but with 3 memo values
 useLayoutEffect3 :: forall a b c. a -> b -> c -> Effect (Effect Unit) -> Hooks Unit
-useLayoutEffect3 a b c e = _useLayoutEffect e $ args3 a b c
+useLayoutEffect3 a b c e = unsafeUseLayoutEffect e $ args3 a b c
 
 -- | Like useLayoutEffect, but with 4 memo values
 useLayoutEffect4 :: forall a b c d. a -> b -> c -> d -> Effect (Effect Unit) -> Hooks Unit
-useLayoutEffect4 a b c d e = _useLayoutEffect e $ args4 a b c d
+useLayoutEffect4 a b c d e = unsafeUseLayoutEffect e $ args4 a b c d
 
 -- | Like useLayoutEffect, but with 5 memo values
 useLayoutEffect5 :: forall a b c d e. a -> b -> c -> d -> e -> Effect (Effect Unit) -> Hooks Unit
-useLayoutEffect5 a b c d f e = _useLayoutEffect e $ args5 a b c d f
+useLayoutEffect5 a b c d f e = unsafeUseLayoutEffect e $ args5 a b c d f
 
 -- | Like useLayoutEffect, but the provided Effect fn does not return a cleanup handler
 useLayoutEffect' :: forall a. Effect a -> Hooks Unit
@@ -248,8 +267,11 @@ useLayoutEffect4' a b c d = useLayoutEffect4 a b c d <<< thenNothing
 useLayoutEffect5' :: forall a b c d e f. a -> b -> c -> d -> e -> Effect f -> Hooks Unit
 useLayoutEffect5' a b c d f = useLayoutEffect5 a b c d f <<< thenNothing
 
-_useLayoutEffect :: forall a. Effect (Effect Unit) -> a -> Hooks Unit
-_useLayoutEffect e a =
+-- | Call React.useLayoutEffect passing an array-like object
+-- | (arguments is acceptable) for memo values without any help from
+-- | the type system to guarantee the memo value is in fact array-like.
+unsafeUseLayoutEffect :: forall a. Effect (Effect Unit) -> a -> Hooks Unit
+unsafeUseLayoutEffect e a =
   hook $ \_ ->
     pure $ react ... "useLayoutEffect" $
       args2 e (Array.from a)
@@ -304,26 +326,29 @@ useMemo f = hook $ \_ -> pure $ react ... "useMemo" $ [ delay unit (\_ -> pure (
 
 -- | Like `useMemo` but takes a memo value
 useMemo1 :: forall a t. a -> (Unit -> t) -> Hooks t
-useMemo1 a f = _useMemo f [a]
+useMemo1 a f = unsafeUseMemo f [a]
 
 -- | Like `useMemo` but takes 2 memo values
 useMemo2 :: forall a b t. a -> b -> (Unit -> t) -> Hooks t
-useMemo2 a b f = _useMemo f $ args2 a b
+useMemo2 a b f = unsafeUseMemo f $ args2 a b
 
 -- | Like `useMemo` but takes 3 memo values
 useMemo3 :: forall a b c t. a -> b -> c -> (Unit -> t) -> Hooks t
-useMemo3 a b c f = _useMemo f $ args3 a b c
+useMemo3 a b c f = unsafeUseMemo f $ args3 a b c
 
 -- | Like `useMemo` but takes 4 memo values
 useMemo4 :: forall a b c d t. a -> b -> c -> d -> (Unit -> t) -> Hooks t
-useMemo4 a b c d f = _useMemo f $ args4 a b c d
+useMemo4 a b c d f = unsafeUseMemo f $ args4 a b c d
 
 -- | Like `useMemo` but takes 5 memo values
 useMemo5 :: forall a b c d e t. a -> b -> c -> d -> e -> (Unit -> t) -> Hooks t
-useMemo5 a b c d e f = _useMemo f $ args5 a b c d e
+useMemo5 a b c d e f = unsafeUseMemo f $ args5 a b c d e
 
-_useMemo :: forall t a. (Unit -> t) -> a -> Hooks t
-_useMemo f a =
+-- | Call React.useMemo passing an array-like object (arguments is
+-- | acceptable) for memo values without any help from the type system
+-- | to guarantee the memo value is in fact array-like.
+unsafeUseMemo :: forall t a. (Unit -> t) -> a -> Hooks t
+unsafeUseMemo f a =
   hook $ \_ ->
     pure $ react ... "useMemo" $
       args2 (delay unit (\_ -> pure (f unit))) (Array.from a)
@@ -336,26 +361,29 @@ useCallback f = hook $ \_ -> pure $ react ... "useCallback" $ [ delay unit (\_ -
 
 -- | Like `useCallback` but takes a memo value
 useCallback1 :: forall a t. a -> (Unit -> t) -> Hooks (Effect t)
-useCallback1 a f = _useCallback f [a]
+useCallback1 a f = unsafeUseCallback f [a]
 
 -- | Like `useCallback` but takes 2 memo values
 useCallback2 :: forall a b t. a -> b -> (Unit -> t) -> Hooks (Effect t)
-useCallback2 a b f = _useCallback f $ args2 a b
+useCallback2 a b f = unsafeUseCallback f $ args2 a b
 
 -- | Like `useCallback` but takes 3 memo values
 useCallback3 :: forall a b c t. a -> b -> c -> (Unit -> t) -> Hooks (Effect t)
-useCallback3 a b c f = _useCallback f $ args3 a b c
+useCallback3 a b c f = unsafeUseCallback f $ args3 a b c
 
 -- | Like `useCallback` but takes 4 memo values
 useCallback4 :: forall a b c d t. a -> b -> c -> d -> (Unit -> t) -> Hooks (Effect t)
-useCallback4 a b c d f = _useCallback f $ args4 a b c d
+useCallback4 a b c d f = unsafeUseCallback f $ args4 a b c d
 
 -- | Like `useCallback` but takes 5 memo values
 useCallback5 :: forall a b c d e t. a -> b -> c -> d -> e -> (Unit -> t) -> Hooks (Effect t)
-useCallback5 a b c d e f = _useCallback f $ args5 a b c d e
+useCallback5 a b c d e f = unsafeUseCallback f $ args5 a b c d e
 
-_useCallback :: forall t a. (Unit -> t) -> a -> Hooks (Effect t)
-_useCallback f a =
+-- | Call React.useCallback passing an array-like object (arguments is
+-- | acceptable) for memo values without any help from the type system
+-- | to guarantee the memo value is in fact array-like.
+unsafeUseCallback :: forall t a. (Unit -> t) -> a -> Hooks (Effect t)
+unsafeUseCallback f a =
   hook $ \_ ->
     pure $ react ... "useCallback" $
       args2 f (Array.from a)
@@ -368,29 +396,32 @@ useImperativeHandle r f =
     pure $ react ... "useImperativeHandle" $ args2 r f
 
 useImperativeHandle1 :: forall a r r'.  a -> Ref r -> Effect r' -> Hooks Unit
-useImperativeHandle1 a r f = _useImperativeHandle r f [a]
+useImperativeHandle1 a r f = unsafeUseImperativeHandle r f [a]
 
 useImperativeHandle2
   :: forall a b r r'
   .  a -> b -> Ref r -> Effect r' -> Hooks Unit
-useImperativeHandle2 a b r f = _useImperativeHandle r f (args2 a b)
+useImperativeHandle2 a b r f = unsafeUseImperativeHandle r f (args2 a b)
 
 useImperativeHandle3
   :: forall a b c r r'
   .  a -> b -> c -> Ref r -> Effect r' -> Hooks Unit
-useImperativeHandle3 a b c r f = _useImperativeHandle r f (args3 a b c)
+useImperativeHandle3 a b c r f = unsafeUseImperativeHandle r f (args3 a b c)
 
 useImperativeHandle4
   :: forall a b c d r r'
   .  a -> b -> c -> d -> Ref r -> Effect r' -> Hooks Unit
-useImperativeHandle4 a b c d r f = _useImperativeHandle r f (args4 a b c d)
+useImperativeHandle4 a b c d r f = unsafeUseImperativeHandle r f (args4 a b c d)
 
 useImperativeHandle5
   :: forall a b c d e r r'
   .  a -> b -> c -> d -> e -> Ref r -> Effect r' -> Hooks Unit
-useImperativeHandle5 a b c d e r f = _useImperativeHandle r f (args5 a b c d e)
+useImperativeHandle5 a b c d e r f = unsafeUseImperativeHandle r f (args5 a b c d e)
 
-_useImperativeHandle :: forall r r' a. Ref r -> Effect r' -> a -> Hooks Unit
-_useImperativeHandle r f a = hook $ \_ ->
+-- | Call React.useImperativeHandle passing an array-like object (arguments is
+-- | acceptable) for memo values without any help from the type system
+-- | to guarantee the memo value is in fact array-like.
+unsafeUseImperativeHandle :: forall r r' a. Ref r -> Effect r' -> a -> Hooks Unit
+unsafeUseImperativeHandle r f a = hook $ \_ ->
   pure $ react ... "useImperativeHandle" $
     args3 r f (Array.from a)