Update tests and readme

Author: edingroot

jest.setup.js

@@ -1,7 +1,7 @@
 import 'regenerator-runtime/runtime';
 import {isDone, isLoading, isReloading, LState, useLoadingSteps} from "../index";
 import React, {useMemo} from "react";
-import {createTestComponent, noop, wait} from "../test_util";
+import {createTestComponent, neverCalled, wait} from "../test_util";
 
 describe('no delay', () => {
     it('initial loaded = true', async () =>  {
@@ -37,7 +37,7 @@ describe('no delay', () => {
 
     it('single step', async () =>  {
         let expectedState: LState;
-        let setStepDoneCb: (s: string) => void = noop;
+        let setStepDoneCb: (s: string) => void = neverCalled;
 
         // Do before creating test component
         const doSteps = async () => {
@@ -58,12 +58,13 @@ describe('no delay', () => {
     it('multiple steps', async () =>  {
         const stepCnt = 3;
         let expectedState: LState;
-        let setStepDoneCb: (s: string) => void = noop;
+        let setStepDoneCb: (s: string) => void = neverCalled;
 
         // Do before creating test component
         const doSteps = async () => {
             expectedState = LState.LOADING;
 
+            await wait(10);
             for (let i = 0; i < stepCnt; i++) {
                 if (i == stepCnt - 1) {
                     expectedState = LState.DONE;
@@ -80,6 +81,39 @@ describe('no delay', () => {
             useMemo(() => expect(loadingState).toEqual(expectedState), [loadingState]);
         });
     });
+
+    it('multiple steps: skip step', async () =>  {
+        const stepCnt = 3;
+        let expectedState: LState;
+        let setStepDoneCb: (s: string) => void = neverCalled;
+        let skipStepCb: (s: string) => void = neverCalled;
+
+        // Do before creating test component
+        const doSteps = async () => {
+            expectedState = LState.LOADING;
+
+            await wait(10);
+            for (let i = 0; i < stepCnt; i++) {
+                if (i == stepCnt - 1) {
+                    expectedState = LState.DONE;
+                }
+                if (i % 2 === 0) {
+                    setStepDoneCb(`step${i + 1}`);
+                } else {
+                    skipStepCb(`step${i + 1}`);
+                }
+                await wait(10); // pause shortly for event loop to run component logics
+            }
+        }
+        doSteps().then();
+
+        await createTestComponent(() => {
+            const [loadingState, setStepDone, _, skipStep] = useLoadingSteps(stepCnt, false);
+            setStepDoneCb = setStepDone;
+            skipStepCb = skipStep;
+            useMemo(() => expect(loadingState).toEqual(expectedState), [loadingState]);
+        });
+    });
 });
 
 describe('with render delay', () => {
@@ -96,7 +130,7 @@ describe('with render delay', () => {
 
     it('single step', async () => {
         let expectedState: LState;
-        let setStepDoneCb: (s: string) => void = noop;
+        let setStepDoneCb: (s: string) => void = neverCalled;
 
         // Do before creating test component
         const doSteps = async () => {
@@ -122,7 +156,7 @@ describe('with render delay', () => {
 
     it('multiple steps', async () => {
         let expectedState: LState;
-        let setStepDoneCb: (s: string) => void = noop;
+        let setStepDoneCb: (s: string) => void = neverCalled;
 
         // Do before creating test component
         const doSteps = async () => {
@@ -151,7 +185,7 @@ describe('with render delay', () => {
 
     it('multiple steps: done before render delay timeout', async () => {
         let expectedState: LState;
-        let setStepDoneCb: (s: string) => void = noop;
+        let setStepDoneCb: (s: string) => void = neverCalled;
 
         // Do before creating test component
         const doSteps = async () => {
@@ -183,8 +217,8 @@ describe('with reset delay', () => {
 
     it('multiple steps', async () => {
         let expectedState: LState;
-        let setStepDoneCb: (s: string) => void = noop;
-        let resetLoadingCb: () => void = noop;
+        let setStepDoneCb: (s: string) => void = neverCalled;
+        let resetLoadingCb: () => void = neverCalled;
 
         // Do before creating test component
         const doSteps = async () => {
@@ -228,8 +262,8 @@ describe('with render delay + reset delay', () => {
 
     it('multiple steps', async () => {
         let expectedState: LState;
-        let setStepDoneCb: (s: string) => void = noop;
-        let resetLoadingCb: () => void = noop;
+        let setStepDoneCb: (s: string) => void = neverCalled;
+        let resetLoadingCb: () => void = neverCalled;
 
         // Do before creating test component
         const doSteps = async () => {
@@ -276,7 +310,7 @@ describe('with done delay', () => {
 
     it('multiple steps', async () => {
         let expectedState: LState;
-        let setStepDoneCb: (s: string) => void = noop;
+        let setStepDoneCb: (s: string) => void = neverCalled;
 
         // Do before creating test component
         const doSteps = async () => {

lib/__tests__/test.tsx

@@ -6,7 +6,9 @@ export async function wait(period: number): Promise<void> {
     return period > 0 ? new Promise(resolve => setTimeout(resolve, period)) : Promise.resolve();
 }
 
-export function noop() {}
+export function neverCalled() {
+    throw new Error('This function should not be called');
+}
 
 export async function createTestComponent(logic: () => void, waitToFinish = 100) {
     const Component = ({}): React.ReactElement | null => {

lib/test_util.tsx

@@ -8,7 +8,7 @@
   ],
   "author": "@edingroot",
   "repository": "edingroot/use-loading-steps",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "module": "dist/index.modern.js",

package.json

@@ -1,6 +1,90 @@
 # use-loading-steps
-
 [![npm version](https://badge.fury.io/js/use-loading-steps.svg)](https://www.npmjs.com/package/use-loading-steps)
 
-Tutorial work in progress...
+A simple state management library for smooth react page loading experience.
+
+
+## Install
+```bash
+yarn add use-loading-steps
+# or
+npm install --save use-loading-steps
+```
+
+
+## Usage
+```javascript
+const [loadingState, setStepDone, resetLoading, skipStep] = useLoadingSteps(taskCount, initLoaded, options);
+```
+*useLoadingSteps* hook params
+- `taskCount`: the number of steps should be done before the page is loaded.
+- `initLoaded`: set to true to skip all state transitions, loadingState = `DONE`.
+- `options`: see below.
+
+Hook returns
+- `loadingState`: the state, type: `LState` enum (string).
+- `setStepDone('step_name')`: to be called when a step is finished, step_name should be a unique string.
+- `resetLoading()`: to be called when reloading resources.
+- `skipStep('step_name)`: same effect as setStepDone, but prints different debug log.
+
+Options
+```typescript
+interface Options {
+    renderDelay?: number; // timeout of SILENT_LOADING state after started
+    resetDelay?: number;  // timeout of SILENT_LOADING state after reset
+    doneDelay?: number;   // timeout of DELAY_DONE state
+    name?: string;        // for debug log (useful if there are multiple pages / components use this hook)
+}
+```
+The debug log is printed by `console.debug`, and is skipped in production build. 
+
+
+## Loading States
+```typescript
+export enum LState {
+    SILENT_LOADING = 'SILENT_LOADING',  // for: do loading but not to show loading animation
+    LOADING = 'LOADING',                // for: show loading animation
+    DELAY_DONE = 'DELAY_DONE',          // for: loading finished but keep showing loading animation
+    DONE = 'DONE',                      // for: all ready
+}
+```
+
+Utility functions
+```typescript
+export const isLoading = (state: LState) => LState.LOADING === state;
+export const isReloading = (state: LState) => [LState.SILENT_LOADING, LState.LOADING].includes(state);
+export const isDone = (state: LState) => LState.DONE === state;
+```
+
+
+## Example
+
+```javascript
+// Number of steps: 2, loaded: false, renderDelay: 100ms
+const [loadingState, setStepDone] = useLoadingSteps(2, false, {renderDelay: 100});
+const [rows, setRows] = useState([]);
+
+useEffect(async () => {
+  const data = await fetchData();
+  setStepDone('fetch');
+  
+  const rows = await transformData(data);
+  setStepDone('transform');
+}, []);
+
+if (isLoading(loadingState)) {
+  return <div>(Loading animation)</div>; 
+}
+return (
+  <div>
+    {data.map((item) => <div>row: {item}</div>)}
+  </div>
+);
+```
+Explanation 
+- Initialize, if loaded = false, state => `SILENT_LOADING`, isLoading(loadingState) = false
+- After 100ms, if not finished, state => `LOADING`, isLoading(loadingState) = true
+- After the two `setStepDone('step name')` are called, state => `DONE`, isLoading(loadingState) = false
 
+More examples
+- Please refer to unit tests in `lib/__test__`.