Merge pull request #26 from alevnyacow/docs/tsdoc-and-rerenders-list-refactor

Addad TSDoc and made some refactoring in RerendersList class

Author: alevnyacow

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alevnyacow/shared-react-variables",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "description": "Easy and comfortable React state manager",
   "main": "transpiled/index.js",
   "scripts": {

sources/index.ts

@@ -9,13 +9,24 @@ type ReactVariableRewriteHook<T> = () => (
     generator: (oldState: T) => T
 ) => void;
 
+/**
+ * Generates a tuple of two hooks: first hook is a React variable generator,
+ * second hook can be used to rewrite a whole variable (you don't need this most likely).
+ *
+ * @param initialState Initial state of shared React variable.
+ */
 function createUseSharedVariable<T extends object>(initialState: T) {
     const variableIdentifier = v4();
     let sharedVariable = deepProxy(
         [rerenderersList.fire],
         variableIdentifier
     )(initialState);
 
+    /**
+     * React hook returning shared React variable.
+     *
+     * @param rerenderOnChange Flag can be used to prevent a rerender on React variable changes, when set to true.
+     */
     const useSharedVariable: ReactVariableHook<T> = (
         rerenderOnChange = true
     ) => {
@@ -39,6 +50,9 @@ function createUseSharedVariable<T extends object>(initialState: T) {
         return sharedVariable;
     };
 
+    /**
+     * React hook returning function can be used to rewrite whole associated variable.
+     */
     const useSharedVariableRewrite: ReactVariableRewriteHook<T> =
         () => (generator: (oldState: T) => T) => {
             sharedVariable = deepProxy(

sources/rerenderers-list.ts

@@ -1,23 +1,56 @@
+import { Rerenderer } from "./use-rerenderer";
+
+type RerenderersData = {
+    [variableId: string]: { [rerendererId: string]: Rerenderer };
+};
+
+/**
+ * Describes a list of rerenders can be used to register/delete/fire rerenderers.
+ */
 class RerenderersList {
-    private _rerenderersData: Record<string, Record<string, () => void>>;
+    private _rerenderersData: RerenderersData;
 
     constructor() {
         this._rerenderersData = {};
     }
 
-    private addForVariable = (variableId: string) => {
-        this._rerenderersData[variableId] =
-            this._rerenderersData[variableId] || {};
-    };
-
+    /**
+     * Checks if rerenderers data has a section associated with given variable.
+     *
+     * @param variableId Variable identifier.
+     */
     private existsForVariable = (variableId: string) => {
         return this._rerenderersData[variableId] !== undefined;
     };
 
+    /**
+     * Adds a section for a given variable.
+     *
+     * @param variableId Variable identifier.
+     *
+     * @throws {@link Error} When tried to add a section for a variable that already exists.
+     */
+    private addForVariable = (variableId: string) => {
+        if (this.existsForVariable(variableId)) {
+            throw new Error(
+                "Tried to add a section for a variable that already exists."
+            );
+        }
+
+        this._rerenderersData[variableId] = {};
+    };
+
+    /**
+     * Registers new rerenderer for a given variable.
+     *
+     * @param variableId Variable identifier.
+     * @param rerendererId Rerenderer identifier.
+     * @param rerenderer Rerenderer logic.
+     */
     public add = (
         variableId: string,
         rerendererId: string,
-        rerenderer: () => void
+        rerenderer: Rerenderer
     ) => {
         if (!this.existsForVariable(variableId)) {
             this.addForVariable(variableId);
@@ -26,19 +59,37 @@ class RerenderersList {
         this._rerenderersData[variableId][rerendererId] = rerenderer;
     };
 
+    /**
+     * Unregisters a rerender from variable by an identifier.
+     *
+     * @param variableId Variable identifier.
+     * @param rerendererId Rerenderer identifier.
+     *
+     * @throws {@link Error} When tried to remove variable data that does not exist.
+     */
     public remove = (variableId: string, rerendererId: string) => {
-        const variableRerendersData = this._rerenderersData[variableId];
-
-        if (!variableRerendersData) {
-            return;
+        if (!this.existsForVariable(variableId)) {
+            throw new Error(
+                "Tried to remove variable data that does not exist."
+            );
         }
 
+        const variableRerendersData = this._rerenderersData[variableId];
         delete variableRerendersData[rerendererId];
     };
 
+    /**
+     * Fires every rerenderer associated with a given variable.
+     *
+     * @param variableId Variable identifier.
+     *
+     * @throws {@link Error} When tried to fire rerenders for a variable that does not exist.
+     */
     public fire = (variableId: string) => {
         if (!this.existsForVariable(variableId)) {
-            return;
+            throw new Error(
+                "Tried to fire rerenders for a variable that does not exist."
+            );
         }
 
         Object.values(this._rerenderersData[variableId]).forEach((rerender) => {

sources/use-rerenderer.ts

@@ -1,6 +1,12 @@
 import { useState } from "react";
 
-export function useRerenderer() {
+type Rerenderer = () => void;
+
+/**
+ * React hook returning a function that causes a rerender when called.
+ */
+function useRerenderer() {
     const [, setNewDummyObject] = useState({});
-    return () => setNewDummyObject({});
+    return (() => setNewDummyObject({})) as Rerenderer;
 }
+export { useRerenderer, Rerenderer };

tests/test-application/package.json

@@ -3,7 +3,7 @@
   "version": "0.1.0",
   "private": true,
   "dependencies": {
-    "@alevnyacow/shared-react-variables": "file:../../alevnyacow-shared-react-variables-2.0.2.tgz",
+    "@alevnyacow/shared-react-variables": "file:../../alevnyacow-shared-react-variables-2.0.3.tgz",
     "@testing-library/jest-dom": "^5.16.2",
     "@testing-library/react": "^12.1.4",
     "@testing-library/user-event": "^13.5.0",