From 8f67de853210fc3ebd4865fe383ed6171360aa6c Mon Sep 17 00:00:00 2001 From: Justin Wallace Date: Sat, 16 Mar 2024 16:34:06 -0700 Subject: [PATCH] fix: docs missing from README (#19) --- README.md | 14 ++++--- use-react-workers/README.md | 14 ++++--- use-react-workers/src/useWorker.ts | 39 +++++++++++++++++- use-react-workers/src/useWorkerFunc.ts | 54 ++++++++++++++++++++----- use-react-workers/src/useWorkerState.ts | 38 +++++++++++++++-- 5 files changed, 132 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 3336a00..7d633df 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ -

- use-react-workers Reacts hooks for Web Workers -

+# Reacts hooks for Web Workers + +## 📄 Docs + +Basic functionality can be found below. But for a more in depth description/demos, see [the documentation](https://jpwallace22.github.io/use-react-workers/) ## 🎨 Features @@ -48,7 +50,7 @@ import { useWorkerState, useWorkerFunc, useWorker } from 'use-react-workers'; ## 🎬 Usage -#### useWorkerFunc +### useWorkerFunc ```tsx import React from 'react'; @@ -80,7 +82,7 @@ const MyCoolComponent = () => { }; ``` -#### useWorkerState +### useWorkerState ```tsx import React from 'react'; @@ -104,7 +106,7 @@ const MyCoolComponent = () => { }; ``` -#### useWorker +### useWorker ```tsx import React from 'react'; diff --git a/use-react-workers/README.md b/use-react-workers/README.md index 3336a00..7d633df 100644 --- a/use-react-workers/README.md +++ b/use-react-workers/README.md @@ -1,6 +1,8 @@ -

- use-react-workers Reacts hooks for Web Workers -

+# Reacts hooks for Web Workers + +## 📄 Docs + +Basic functionality can be found below. But for a more in depth description/demos, see [the documentation](https://jpwallace22.github.io/use-react-workers/) ## 🎨 Features @@ -48,7 +50,7 @@ import { useWorkerState, useWorkerFunc, useWorker } from 'use-react-workers'; ## 🎬 Usage -#### useWorkerFunc +### useWorkerFunc ```tsx import React from 'react'; @@ -80,7 +82,7 @@ const MyCoolComponent = () => { }; ``` -#### useWorkerState +### useWorkerState ```tsx import React from 'react'; @@ -104,7 +106,7 @@ const MyCoolComponent = () => { }; ``` -#### useWorker +### useWorker ```tsx import React from 'react'; diff --git a/use-react-workers/src/useWorker.ts b/use-react-workers/src/useWorker.ts index 5a70642..d22cea9 100644 --- a/use-react-workers/src/useWorker.ts +++ b/use-react-workers/src/useWorker.ts @@ -21,8 +21,43 @@ export type UseWorker = any>( }; /** - * @param {Function} func the function to run with web worker - * @param {Options} options useWorkerFunc option params + * `useWorker` is a custom React hook that creates a web worker to run a given function. + * This hook is useful for offloading computationally heavy tasks to a separate thread, preventing the main thread from blocking. + * + * @template T The type of the function to be executed in the web worker. + * @param {T} func - The function to be executed in the web worker. + * @param {Options} options - An optional parameter that includes options for the web worker such as timeout, remoteDependencies, autoTerminate, and transferable. + * @returns {Object} - An object containing methods to interact with the web worker: postMessage, onMessage, terminate, and a status property. + * + * @example + * ```jsx + * import { useWorker } from './useWorker'; + * + * function HeavyComputationComponent() { + * const heavyComputation = (num) => { + * let result = 0; + * for (let i = 0; i < num; i++) { + * result += Math.sqrt(i); + * } + * return result; + * }; + * + * const worker = useWorker(heavyComputation); + * + * const handleClick = () => { + * worker.postMessage(1e7); // Perform heavy computation with 1e7 as argument + * worker.onMessage((e) => { + * console.log(e.data); // Log the result when it's ready + * }); + * }; + * + * return ( + *
+ * + *
+ * ); + * } + * ``` */ export const useWorker: UseWorker = any>( func: T, diff --git a/use-react-workers/src/useWorkerFunc.ts b/use-react-workers/src/useWorkerFunc.ts index a59f02d..025c887 100644 --- a/use-react-workers/src/useWorkerFunc.ts +++ b/use-react-workers/src/useWorkerFunc.ts @@ -3,14 +3,15 @@ import createWorkerBlobUrl from './utils/createWorkerBlobUrl.ts'; import { useDeepCallback } from './utils/useDeepCallback.ts'; import { Options, TRANSFERABLE_TYPE, WorkerStatus } from './types.ts'; -// TODO -/** - * I might be able to wrap this with the `useWorker` and reduce the overall - * size of the library - * --- - * At the bare minimum, there is some repeated logic in here that could probably - * make separate modules. - */ +/** --TODO-- +* +* I might be able to wrap this with the `useWorker` and reduce the overall +* size of the library +* --- +* At the bare minimum, there is some repeated logic in here that could probably +* make separate modules. +* +/** --TODO-- */ export interface Controller { status: WorkerStatus; @@ -40,8 +41,41 @@ export type UseWorkerFunc = any>( ) => [(...funcArgs: Parameters) => Promise>, Controller]; /** - * @param {Function} func the function to run with web worker - * @param {Options} options useWorkerFunc option params + * `useWorkerFunc` is a custom React hook that executes a given function in a web worker and returns a promise with its result. + * This hook is useful for offloading computationally heavy tasks to a separate thread, preventing the main thread from blocking. + * + * @template T The type of the function to be executed in the web worker. + * @param {T} func - The function to be executed in the web worker. + * @param {Options} options - An optional parameter that includes options for the web worker such as timeout, remoteDependencies, autoTerminate, and transferable. + * @returns {[(...funcArgs: Parameters) => Promise>, Controller]} - An array containing a function that when called with the arguments of the original function, returns a promise with the result, and a controller object to control the web worker. + * + * @example + * ```jsx + * import { useWorkerFunc } from './useWorkerFunc'; + * + * function HeavyComputationComponent() { + * const heavyComputation = (num) => { + * let result = 0; + * for (let i = 0; i < num; i++) { + * result += Math.sqrt(i); + * } + * return result; + * }; + * + * const [compute, controller] = useWorkerFunc(heavyComputation); + * + * const handleClick = async () => { + * const result = await compute(1e7); // Perform heavy computation with 1e7 as argument + * console.log(result); + * }; + * + * return ( + *
+ * + *
+ * ); + * } + * ``` */ export const useWorkerFunc: UseWorkerFunc = any>( func: T, diff --git a/use-react-workers/src/useWorkerState.ts b/use-react-workers/src/useWorkerState.ts index 726b4f8..1fedbcd 100644 --- a/use-react-workers/src/useWorkerState.ts +++ b/use-react-workers/src/useWorkerState.ts @@ -7,10 +7,42 @@ export type UseWorkerState = , T extends (args: any) => ) => [ReturnType | null, (...args: Parameters) => Promise, Controller]; /** - * Executes a function in [useWorkerFunc](./useWorkerFunc) and retrieves its result in React state. + * `useWorkerState` is a custom React hook that executes a given function in a web worker and retrieves its result in a React state. + * This hook is useful for offloading computationally heavy tasks to a separate thread, preventing the main thread from blocking. + * + * @template R The type of the return value of the function `func`. + * @template T The type of the function to be executed in the web worker. * @param {T} func - The function to be executed in the web worker. - * @param {ReturnType} defaultState - The arguments to be passed to the function. - * @returns {[ReturnType | null, (input: Parameters) => Promise, Controller]} - An array containing the result of the function and a controller object. + * @param {R} defaultState - The initial state value. + * @returns {[ReturnType | null, (...args: Parameters) => Promise, Controller]} - An array containing the result of the function, a function to set the state, and a controller object to control the web worker. + * + * @example + * ```jsx + * import { useWorkerState } from './useWorkerState'; + * + * function HeavyComputationComponent() { + * const heavyComputation = (num) => { + * let result = 0; + * for (let i = 0; i < num; i++) { + * result += Math.sqrt(i); + * } + * return result; + * }; + * + * const [result, setResult, controller] = useWorkerState(heavyComputation, 0); + * + * const handleClick = () => { + * setResult(1e7); // Perform heavy computation with 1e7 as argument + * }; + * + * return ( + *
+ * + * {result &&

Result: {result}

} + *
+ * ); + * } + * ``` */ export const useWorkerState: UseWorkerState = < R extends ReturnType,