GARFIO
Garfio is a module composed of several submodules that try to facilitate the use of the hookletons. A hookleton is a globalized React Hook, this means that once declared its namespace it is linked to a single state.
The Hookleton
library includes only the minimum core code needed to maintain state synchronization between "the users" of the hookleton, but was designed to be fully extensible. The submodules of Garfio
are extensions of this code to be able to use the same hookleton namespace with different states.
Garfio solves the problem of namespaces using several user-selectable approaches. In the future, more approaches could be added if relevant.
It is recommend take a look first to Hookleton package Doc
Benefits
- Small size
- Zero dependencies (only Hookleton that depends on React Hook)
- 👉 without using React Context
- 👉 not complex user memoizations needed. Out of the box performance
- Works in any environment that supports React Hook: React Native, React Server-Side Rendering (next.js), Proto Native, ...
Installation
# NPM npm i garfio # Yarn yarn add garfio
External resources
included subModules
Hookleton API
Garfio re-export the Hookleton API. You do not need to install hookleton module explicitly if you want to use it. Just:
// createHook from Hookleton module;
Container
module
+ Container
HookletonContainer create different state scopes within the enclosing tags and without using React Context
API
createHook(useHook, ...initial?): useHookleton
Parameters
useHook
is the user provide Hookinitial
any number of params that useHook will accept
Returns
useHookleton
returned Hookleton. Called by non-host componentsuseHookleton.Container
Container component for enclosing tags scopesuseHookleton.get
function that get the current output of the Hookleton. For standalone use
usage Example
; { const count setCount = ; const increment = ; return count increment;} const useCounter = ;const CounterContainer = useCounterContainer; { const increment = ; return <button onClick=increment>+</button>;} { const count = ; return <p>count</p>;} <CounterContainer initialArg=1> <Count /> <Button /> <CounterContainer initialArg=3> <Count /> <Button /> </CounterContainer> </CounterContainer>;
initial arguments API
Containers can be initialized in two ways:
initialArg
prop
initialArg is an array of arguments which is spread
to the Hook provided by the user. If the value is not an array then it is converted. To pass an array as a start element, it must be enclosed in an array too.
Below are examples of usage and automatic conversions.
Single argument example:
; const useValue = ;const Container = useValueContainer; { return <Container initialArg=3> /* output number 3 */ 0 <Container initialArg="three"> /* output string "three" */ 0 </Container> <Container initialArg=1 2 3> /* output array [1,2,3] in JSX */ 0 </Container> </Container> ;};
Multiple arguments example:
; const useReduced = ;const Container = useReducedContainer; const reducer = s;const initial = 0; { return <Container initialArg=reducer initial> /* output number 0(initial) */ 0 </Container> ;};
object properties
like props
initial When initializing hooks that use an initialization object it is possible to declare object properties
as props of the Container.
Example:
; const useReduced = ;const Container = useReducedContainer; { return <Container reducer= s initial=0> /* output number 0(initial) */ 0 </Container> ;};
The Container API and its functionality is inspired by the constante package although React Context has not been used for its implementation
Store
module
+ Simple + Store
HookletonIf in Container we use the enclosing tags to define different hookleton scopes, with Store
the scope is linked to a single object
API
Store creation
createStore(hook, ...initial?): Store
Parameters
hook
is the user provide Hookinitial
any number of params that hook will accept
initial
parameters from Store creation step has priority overinitial
parameters from Store use.- Do not pass any parameters in the Store creation if you want to initialize it within some Component (when you
use
the hookleton).- Remember that hookletons are global, so they are only initialized once, in the first component rendered. The other initializations will be ignored.
Returns
Store
sigle object (unique), with this interface:
{
get(): any;
delete(): boolean;
}
get()
for standalone store usage
Standalone refers to obtaining the current state of the hookleton from any part of the application, including outside the React components. This state is not updated automatically
delete()
for store delete. Returntrue
on sucess
use
Store useStore(store, ...initial?): any
Parameters
store
already exist storeinitial
any number of params that provided hook will accept
Returns
Return value is any value returned by the hook
usage Example
; const one = ;const two = ;const three = ; const reducer = s; const Values = { const v1 set = ; ; const v2 = two; const v3 dispatch = ; // output: 1,2,3 return <span> v1v2v3 </span> ;}; <Values />;
The Store API and its functionality is inspired in packages like: shared-state-hook, react-hook-shared-state, reactn, react-shared-hooks, react-hookstore
Simple
module
+ Simple
HookletonSimple
module does not add anything new. It simply allows you to use a hookleton without being explicit about the component that will act as the host of the hookleton. In other words, you do not need to use the useHookleton.use()
API, just useHookleton()
API
createHook(useHook, ...initial): useHookleton
Parameters
useHook
is the user provide Hookinitial
any number of params that useHook will accept
initial params are required. Any param used in
useHookleton
are ignored.
Returns
useHookleton
returned Hookleton. Called by non-host componentsuseHookleton.get
function that get the current output of the Hookleton. For standalone use
usage Example
; // useCounter is a useState but globalconst useCounter = ; const Increment = { const update = ; const increment = ; return <button onClick=increment>+</button>;}; // The host componentconst Value = { const count = ; return <span>count</span>;}; <div> <Value /> <Increment /> </div>;
more Examples
Examples page include:
- Nested Counters with "Container" page | source
- Counters 10x40 with "Store" page | source
- Counter with "Simple" page | source
for a deeper insight ...
Please read Hookleton Doc
Credits
author
- Félix A.A. <> @bySabi
Contributing
- Documentation improvement
- Feel free to send any PR