Release(Beta): See Changelog for details

Author: Hussseinkizz

CHANGELOG.md

@@ -0,0 +1,26 @@
+# 🧤 React Hands
+
+React's Own Hands Touching State The Easiest Way!
+
+> By Hussein Kizz, Beta Release
+
+## React Hands, 29-Mar-2023 (v1.0.0)
+
+- Added: typescript naming convention, $typeName
+- Added: main reactState hook can be called without providing initialState and actions, useful when only interested in dispatch and retrieving state
+- Added: Now users will import types from main library itself
+- Fix: Store provider has a typescript error!
+- Todo: Explore Middleware Concept!
+- Todo: Add More Stuff, Persistent State etc
+
+## React Hands, 30-Mar-2023 (v1.0.0)
+
+- Fixed: Store provider has a typescript error!
+- Chore: Changed state record type from string and unknown to any!
+- Boost: Removed Spread operator in middleware implementation to improve code performance
+- Todo: Add better error handler to let user know when action function name differs from dispatched one, at line with flag --line 1.0 in codebase!
+- Boost: Used useCallback hook in compose function implementation to improve performance
+- Done: Fixed Tsc Errors
+- Done: Set development environment for compiling and packaging
+- Done: Test package installation and usage locally before publishing to npm!
+- Done: published first beta version, via Js Kampala Open Source!

README.md

@@ -0,0 +1,154 @@
+# 🧤 React Hands
+
+> By Hussein Kizz, First Beta Release v1.0.0
+
+React's Own Hands Touching State The Easiest Way!
+
+Unlike others, react hands focuses on easiness and takes a shorthand approach to managing state in your react applications by using react's built in hooks mainly useContext and useReducer which are pretty handy by the way, and also emphasize a single source of truth or global state philosophy to allow managing state at scale a breeze, though local state approach is also supported intuitively. And with that said, `react-hands` is a lightweight, simple and easiest to use state management library to help you manage your application's state without having to learn that much anything new, as the library provides a `StoreProvider` wrapper component and a `useStore` hook for accessing and updating the state just as you would almost do it with react itself, resulting into a simillar and easy to use state management pattern.
+
+## Installation
+
+You can install the `react-hands` library using npm or yarn:
+
+```bash
+npm install react-hands
+# or
+yarn add react-hands
+```
+
+## Usage
+
+### Creating the Store
+
+To create the store, use the `reactState` function. It takes three arguments:
+
+1. `initialState`: an object representing the initial state of your application's state.
+2. `actions`: an object containing functions that update the state in response to dispatched actions.
+3. `middlewares` (optional): an array of middleware functions that modifies the dispatch behavior.
+
+> 💡Middlewares basically help you mutate state with a custom fucntion or an array of functions in given order, before the dispatched action takes place, this will be available in next release.
+
+Meanwhile here is how to create a store:
+
+``` jsx
+// App.jsx
+
+import { reactState } from "react-hands";
+
+const initialState = { count: 0 };
+
+const actions = {
+  increment: (state, action) => ({ count: state.count + 1 }),
+  decrement: (state, action) => ({ count: state.count - 1 }),
+};
+
+```
+
+### Providing the Store
+
+Wrap your top-level component, app or layout with the `StoreProvider` component to provide the store to your app and to all it's child components.
+
+```jsx
+// App.jsx
+
+const { StoreProvider } = reactState(initialState, actions);
+
+function App() {
+  return (
+    <StoreProvider>
+      <MyComponent />
+    </StoreProvider>
+  );
+}
+```
+
+### Accessing the State
+
+To access the state in your components, use the `useStore` hook. It returns an array with the current state and the dispatch function, simillar to useState hook in react!
+
+```jsx
+// MyComponent.jsx
+
+import { reactState } from "react-hands";
+
+const { useStore } = reactState();
+
+function MyComponent() {
+  const [state, dispatch] = useStore();
+
+  return (
+    <div>
+      <p>Count: {state.count}</p>
+      <button onClick={() => dispatch({ type: "increment" })}>+</button>
+      <button onClick={() => dispatch({ type: "decrement" })}>-</button>
+    </div>
+  );
+}
+```
+
+💡 Notice: The dispatch type such as `increment` should match the same state name in store such as `increment`  exactly, otherwise react hands will blow an error in console, so watchout and let's continue!
+
+### Updating the State
+
+To update the state, dispatch an action to the store. The action is an object with a `type` property that corresponds to one of the functions in the `actions` object. For example here both the increment and decrement actions increase and decrease the count in store respectively!
+
+```jsx
+const actions = {
+  increment: (state, action) => ({ count: state.count + 1 }),
+  decrement: (state, action) => ({ count: state.count - 1 }),
+};
+
+// dispatching action...
+dispatch({ type: "increment" });
+```
+
+### Handling Errors
+
+If an action with an unrecognized type is dispatched, `react hands` will log some error to the console and return the current state as is. The error message will usually be reminding you to use the same name as the state in your dispatch action. And more error handlers are being worked on!
+
+### 🔥 Bonus
+
+Did you know, react-hands supports typescript out of the box, it also provides types for state and dispatch, you just have to import a type like `$typeName` from react hands like this for example:
+
+```jsx
+// MyApp.tsx
+
+import { $Action, $State, reactState } from "react-hands";
+
+export default function MyApp() {
+  const initialState = {
+    isDarkMode: false,
+    count: 0,
+  };
+
+  const actions = {
+    toggleDarkMode: (state: $State) => ({
+      ...state,
+      isDarkMode: !state.isDarkMode,
+    }),
+    increment: (state: $State) => ({
+      ...state,
+      count: state.count + 1,
+    }),
+    decrement: (state: $State) => ({
+      ...state,
+      count: state.count - 1,
+    }),
+  };
+
+  const { StoreProvider } = reactState(initialState, actions);
+
+  return (
+      <StoreProvider>
+          <MyComponent/>
+      </StoreProvider>
+  );
+}
+
+```
+
+## Conclusion
+
+The `react-hands` library provides a simple way to manage state in your React applications. It's easy to use, and its lightweight nature makes it a great option for react projects small or complex. It's still work in progress, therefore contributions are welcomed, we will be updating this documentation to explore other patterns such as adding items to store from any component other than main or top level component, persisting state depsite page reloads etc.
+
+😇 Pro Tip: If it works don't tocuh it, or break that comfort zone and give this a try!!!

dist/index.tsx

@@ -0,0 +1,106 @@
+// React Hands
+// All exportable tpypes have naming convention $typeName
+import * as React from 'react';
+
+const { createContext, useContext, useReducer, useMemo, useCallback } = React;
+
+export type $State = Record<string, any>;
+export type $Action = { type: string; payload?: unknown };
+export type $Actions = Record<
+  string,
+  (state: $State, action: $Action) => $State
+>;
+
+export type $Middleware = (store: $Store) => (next: $Dispatch) => $Dispatch;
+export type $Store = { state: $State; dispatch: $Dispatch };
+export type $Dispatch = (action: $Action) => void;
+
+type StoreType = {
+  StoreProvider: React.FC<{ children: React.ReactNode }>;
+  useStore: () => [$State, $Dispatch];
+};
+
+const StoreContext = createContext<$State | undefined>(undefined);
+
+export function reactState(
+  initialState: $State = {},
+  actions: $Actions = {},
+  middlewares: $Middleware[] = []
+): StoreType {
+  function reducer(state: $State, action: $Action) {
+    const handler = actions[action.type];
+    if (handler) {
+      return handler(state, action);
+    } else {
+      // handle error then return state as is -- line 1.0
+      console.log(
+        `Bad Hands: Your probably passed a different reference to dispatch, "${action.type}" should match the same state name referenced in state!`
+      );
+      return state;
+    }
+  }
+
+  function applyMiddlewares(
+    middlewares: $Middleware[],
+    store: $Store
+  ): $Dispatch {
+    const middlewareAPI = {
+      state: store.state,
+      dispatch: (action: $Action) => newDispatch(action),
+    };
+    const functionsChainArray = middlewares.map((middleware) =>
+      middleware(middlewareAPI)
+    );
+    const newDispatch = compose(functionsChainArray)(store.dispatch);
+    return newDispatch;
+  }
+
+  function compose(funcs: ((arg: any) => any)[]) {
+    return useCallback(
+      function composed(arg: any) {
+        let result = arg;
+        for (let i = funcs.length - 1; i >= 0; i--) {
+          result = funcs[i](result);
+        }
+        return result;
+      },
+      [funcs]
+    );
+  }
+
+  const StoreProvider: React.FC<{ children: React.ReactNode }> = ({
+    children,
+  }) => {
+    const [state, dispatch] = useReducer(reducer, initialState);
+    const enhancedDispatch = applyMiddlewares(middlewares, {
+      state,
+      dispatch,
+    });
+    const memorizedValue = useMemo(
+      () => ({ state, dispatch: enhancedDispatch }),
+      [state]
+    );
+
+    return (
+      <StoreContext.Provider value={memorizedValue}>
+        {children}
+      </StoreContext.Provider>
+    );
+  };
+
+  function useStore(): [$State, $Dispatch] {
+    const context = useContext<$State | undefined>(StoreContext);
+
+    // tell user to wrap their app in store provider
+    if (context === undefined) {
+      throw new Error(
+        'Bad Hands: Your top level component or app must be wrapped within the StoreProvider!'
+      );
+    }
+
+    const { state, dispatch } = context;
+    return [state as $State, dispatch as $Dispatch];
+  }
+
+  return { StoreProvider, useStore };
+}