Skip to content

Latest commit

 

History

History
210 lines (166 loc) · 9.51 KB

README.md

File metadata and controls

210 lines (166 loc) · 9.51 KB
Raw

use-quantum-state • Docs

project-logo

use-quantum-state

High performance cross-component state management.

Contents

Overview

use-quantum-state is a specialized React hook designed to facilitate efficient state management in scenarios where components need to subscribe to specific values within a shared context. The core of this library relies on an EventEmitter and useState / useEffect hooks to manage listeners during a component's lifecycle.

See here for full documentation.

When a component in a render tree consumes context, it rerender when the provider's value is replaced. With this library, the provider's value IS NOT replaced when a subscriber emits updates, thus limiting the number of components that will be rendered to only those that also subscribe to the same property within state.

This library is particularly useful in niche cases, such as within the cells of a table, where it can dramatically reduce render cycles and simplify the management of state. However, it is not intended to serve as a general-purpose state management solution.

Repository Structure

└── ./
    ├── src
    │   ├── __tests__
    │   └── index.tsx
    ├── LICENSE
    ├── README.md
    ├── api-extractor.json
    ├── eslint.config.mts
    ├── jest.config.js
    ├── package.json
    ├── tsconfig.build.json
    ├── tsconfig.json
    ├── turbo.json
    └── typedoc.json

System Requirements:

Minimum Version

node

20.10.0

pnpm

9.7.0

Installation

$ npm install use-quantum-state

OR

$ yarn add use-quantum-state

OR

$ pnpm add use-quantum-state

Useful Scripts

If you don't use turbo, you can still run the scripts via you package manager instead.

Run the test suite:

$ turbo test

Compile the library (this will also regenerate /docs):

$ turbo build

Generate an API report

$ turbo report

Contributing

Contributions are welcome! Here are several ways you can contribute:

Contributing Guidelines
  1. Fork the Repository: Start by forking the project repository to your local account.
  2. Clone Locally: Clone the forked repository to your local machine using a git client. 
    git clone ../.
  3. Create a New Branch: Always work on a new branch, giving it a descriptive name. 
    git checkout -b new-feature-x
  4. Make Your Changes: Develop and test your changes locally.
  5. Regenerate The API Report: This makes sure any breaking changes are easy to spot during review. 
    turbo report
  6. Commit Your Changes: Commit with a clear message describing your updates following the conventional commit spec. 
    git commit -m 'feat: implemented new feature x.'
  7. Push to local: Push the changes to your forked repository. 
    git push origin new-feature-x
  8. Submit a Pull Request: Create a PR against the original project repository. Clearly describe the changes and their motivations.
  9. Review: Once your PR is reviewed and approved, it will be merged into the main branch. Congratulations on your contribution!

License

This project is protected under the MIT License. For more details, refer to the LICENSE file.

Interfaces

Interface Description
QuantumEmitter A QuantumEmitter is an object that can emit events and listen for events.
QuantumProviderProps Quantum context provider can optionally take a value to override the default value.

Type Aliases

Type alias Description
AccessorFn A callback function that is called with a path capturing proxy object.
Obj Alias for any string keyed object.
QuantumPath A type that represents a path to a property in an object or an array of objects.
QuantumProvider A special context provider that exposes its emitter via a ref. This allows for emitting events from either direction in the component tree.
QuantumStateHook Subscribe to changes in a property in state. The subscription is automatically removed when the component unmounts. The second element in the tuple is a function that can be used to emit a new value to all subscribers.
QuantumStateHookReturn The return type of the useQuantumState hook.
SplitString Recursively split a string by periods.
Tail Get the tail of a tuple.
Unsubscribe The unsubscribe callback returned by the on and once methods of the QuantumEmitter.
ValueAtPath Get the value type of a property at a given path in an object or an array of objects. The path is represented as a tuple of strings.
ValueAtPathStr Get the value type of a property at a given path in an object or an array of objects. The path is represented as a period delimited string.

Functions

Function Description
createQuantumContext Define a special context provider that allows for reactive state management and a hook to setup the subscription within a component.
isCallable Check if a value is a function. This type guard is intentionally loose to allow for more flexibility.