0.3.1 • Published 5 months ago

@isograph/react-disposable-state v0.3.1

Weekly downloads
-
License
MIT
Repository
github
Last release
5 months ago

@isograph/react-disposable-state

Primitives for managing disposable items in React state.

This library's purpose is to enable safely storing disposable items in React state. These hooks seek to guarantee that each disposable item is eventually destroyed when it is no longer used and that no disposable item is returned from a library hook after it has been disposed.

This library's goals do not include being ergonomic. A library built on top of react-disposable-state should expose easier-to-use hooks for common cases. Application developers can use the hooks exposed in react-disposable-state when more complicated cases arise.

This is unstable, alpha software. The API is likely to change.

Conceptual overview

What is a disposable item?

A disposable item is anything that is either explicitly created or must be explicitly cleaned up. That is, it is an item with a lifecycle.

A disposable item is safe to use as long as its destructor has not been called.

Code that manages disposable items (such as the useDisposableState hook) should also ensure that each destructor is eventually called, and should not provide access to the underlying item once the destructor has been called.

Disposable items are allowed to have side effects when created or when destroyed.

What is disposable state?

Disposable state is React state that contains a disposable item.

Examples of disposable items

  • A subscription that periodically updates a displayed stock price. When the component where the stock price is displayed is unmounted, the subscription should be disposed, so as to avoid doing unproductive work.
  • References to items that are stored externally. For example, consider a centralized store of profile photos. Photos are stored centrally to ensure consistency, meaning that every component displaying a given profile photo displays the same photo. In order to avoid the situation where no profile photo is ever garbage collected, individual components' "claims" to profile photos must be explicitly created and disposed.
  • Items which you want to create exactly once when a functional React component is first rendered, such as a network request.
    • Due to how React behaves, this state must be stored externally. Hence, this can be thought of as an example of the previous bullet point.
    • Other frameworks make different choices. For example, a SolidJS component function is called exactly once. In these cases, the network request can easily be executed once, without being stored in external state.

How does disposable state differ from regular React state?

Disposable state stands in contrast to "regular" React state (e.g. if {isVisible: boolean, currentlySelectedItem: Item} was stored in state), where

  • creating the JavaScript object is the only work done when creating the regular state, and therefore it is okay to create the state multiple times; and
  • the only necessary cleanup work is garbage collection of the underlying memory.

In particular, it is unobservable to the outside world if a piece of "regular" state is created multiple times.

Can React primitives handle disposable state?

The primitives provided by React are a poor fit for storing disposable items in state. An upcoming blog post will explore this in more detail.

This library

Guarantees

This library guarantees that:

  • First, each disposable item that is created is eventually disposed.

    React and suspense prevent this library from ensuring that each disposable item is disposed immediately when the hook unmounts. Instead, the best we can do if a component suspends is often dispose after a configurable timeout.

  • Second, no disposable item is returned from a library hook after it has been disposed.

  • Third, if a component has committed, no disposable item returned from a library hook will be disposed while it is accessible from a mounted component.

    Colloquially, this means that disposable items returned from library hooks are safe to use in event callbacks.

    This guarantee is not upheld if an item returned from a library hook is re-stored in another state hook. So, don't do that!

Supported behaviors

The hooks in this library enable the following behavior:

  • Lazily creating a disposable item. In this context, "lazily" means creating the item during the render phase of a component, before that component has committed. The item is then available in the functional component.

    Note that this is how Relay uses the term lazy. Libraries like react-query use the word lazy differently.

  • Creating a disposable item outside of the render phase and after a hook's initial commit and storing the item in React state, making it available during the next render of that functional component.

API Overview

useLazyDisposableState

A hook that:

  • Takes a mutable parent cache and a loader function, and returns a { state: T }.
  • The returned T is guaranteed to not be disposed during the tick of the render.
  • If this hook commits, the returned T will not be disposed until the component unmounts.
const { state }: { state: T } = useLazyDisposableState<T>(
  parentCache: ParentCache<T>,
  factory: Loader<T>,
  options: ?Options,
);

useUpdatableDisposableState

A hook that:

  • Returns a { state, setState } object.
  • setState throws if called before the initial commit.
  • The state (a disposable item) is guaranteed to be undisposed during the tick in which it is returned from the hook. It will not be disposed until after it can no longer be returned from this hook, even in the presence of concurrent rendering.
  • Every time the hook commits, a given disposable item is currently exposed in the state. All items previously passed to setState are guaranteed to never be returned from the hook, so they are disposed at that time.
  • When the hook unmounts, all disposable items passed to setState are disposed.
const {
  state,
  setState,
}: {
  state: T | null,
  setState: (ItemCleanupPair<T>) => void,
} = useUpdatableDisposableState<T>(
  options: ?Options,
);

useDisposableState

This could properly be called useLazyUpdatableDisposableState, but that's quite long!

A hook that combines the behavior of the previous two hooks:

const {
  state,
  setState,
}: {
  state: T,
  setState: (ItemCleanupPair<T>) => void,
} = useDisposableState<T>(
  parentCache: ParentCache<T>,
  factory: Loader<T>,
  options: ?Options,
);

Miscellaneous notes

Runtime overhead

  • The hooks in this library are generic, and the type of the disposable items T is mostly as unconstrained as possible.
    • The only constraint we impose on T is to disallow T from including the value UNASSIGNED_STATE. This is for primarily for ergonomic purposes. However, it does prevent some runtime overhead.
  • This incurs some runtime overhead. In particular, it means we need to keep track of an index (and create a new short-lived object) to distinguish items that can overthise be === to each other. Consider, a component that uses useDisposableState or useUpdatableDiposableState. If we execute setState([1, cleanup1]) followed by setState([1, cleanup2]), we would expect cleanup1 to be called when the hook commits. This index is required to distinguish those two, otherwise indistinguishable items.
    • This problem also occurs if disposable items are re-used, but their cleanup functions are distinct. That can occur if items are shared references held in a reference counted wrapper!
  • However, client libraries may not require this flexbility! For example, if every disposable item is a newly-created object, then all disposable items are !== to each other!
  • A future version of this library should expose alternative hooks that disallow null and do away with the above check. They may be
0.0.0-main-72f66445

10 months ago

0.0.0-main-7075e43e

10 months ago

0.0.0-main-a05acfa1

10 months ago

0.0.0-main-1e6efe41

10 months ago

0.0.0-main-4941e5bf

12 months ago

0.0.0-main-2643f64b

10 months ago

0.0.0-main-316cfb6b

12 months ago

0.0.0-main-bc0ecdf0

12 months ago

0.0.0-main-2838e9ec

12 months ago

0.0.0-main-dc7beaea

12 months ago

0.0.0-main-e22dda26

12 months ago

0.0.0-main-beecd3bf

12 months ago

0.0.0-main-8bd434d5

12 months ago

0.0.0-main-082770b7

12 months ago

0.0.0-main-134dea28

11 months ago

0.0.0-main-ff1975f2

12 months ago

0.0.0-main-9c01b96f

12 months ago

0.0.0-main-a8ea88c3

12 months ago

0.0.0-main-b4a46142

12 months ago

0.0.0-main-8a2ecd05

10 months ago

0.0.0-main-b18976db

10 months ago

0.0.0-main-63adc9b6

10 months ago

0.0.0-main-c15ae0a0

12 months ago

0.0.0-main-13bfbd39

12 months ago

0.0.0-main-2f36db3f

12 months ago

0.0.0-main-a5a03d46

12 months ago

0.0.0-main-79847bdd

12 months ago

0.0.0-main-db590bbf

12 months ago

0.0.0-main-1ee228e6

10 months ago

0.0.0-main-93dbf1b1

10 months ago

0.0.0-main-58e38cf9

12 months ago

0.0.0-main-a28a4a47

10 months ago

0.0.0-main-1b5359e2

12 months ago

0.0.0-main-ed8f1aa9

10 months ago

0.0.0-main-c13fba57

12 months ago

0.0.0-main-581bb44b

10 months ago

0.0.0-main-a6d48388

10 months ago

0.0.0-main-d57fb7f5

11 months ago

0.0.0-main-647cb530

12 months ago

0.0.0-main-5aa231c1

12 months ago

0.0.0-main-f31f329f

10 months ago

0.0.0-main-54f5b7f2

11 months ago

0.3.0

11 months ago

0.3.1

8 months ago

0.0.0-main-e58b8ba0

12 months ago

0.0.0-main-94aca6ab

10 months ago

0.0.0-main-50b13a7f

12 months ago

0.0.0-main-36c759db

10 months ago

0.0.0-main-6714b0ba

10 months ago

0.0.0-main-92419f97

10 months ago

0.0.0-main-3a405a0b

10 months ago

0.0.0-main-5ca02015

12 months ago

0.0.0-main-91d3020f

12 months ago

0.0.0-main-1b52dc3f

12 months ago

0.0.0-main-3a36e9fb

12 months ago

0.0.0-main-bc162b7f

10 months ago

0.0.0-main-91dd3221

10 months ago

0.0.0-main-0a63b51d

10 months ago

0.0.0-main-2b77d9bb

12 months ago

0.0.0-main-23ce4670

11 months ago

0.0.0-main-535b2302

12 months ago

0.0.0-main-ad45b5a6

12 months ago

0.0.0-main-a5fe3b68

12 months ago

0.0.0-main-71ffc760

12 months ago

0.0.0-main-a319b5da

12 months ago

0.0.0-main-9a69a0ec

10 months ago

0.0.0-main-b7f42058

12 months ago

0.0.0-main-d8e1c851

10 months ago

0.0.0-main-c8c7d9f2

11 months ago

0.0.0-main-b8fe0aa9

10 months ago

0.0.0-main-77d745e6

10 months ago

0.0.0-main-0503387b

10 months ago

0.0.0-main-82dba327

12 months ago

0.0.0-main-8928eb1a

10 months ago

0.0.0-main-b9ec7bd6

10 months ago

0.0.0-main-ac41ff11

10 months ago

0.0.0-main-9897848c

10 months ago

0.0.0-main-7b5447e9

11 months ago

0.0.0-main-58085cb8

10 months ago

0.0.0-main-a8143b3f

10 months ago

0.0.0-main-995311c8

12 months ago

0.0.0-main-1ffc99e4

12 months ago

0.0.0-main-e970ef76

10 months ago

0.0.0-main-47d46523

10 months ago

0.0.0-main-a156409d

12 months ago

0.0.0-main-0f5d95a2

12 months ago

0.0.0-main-de7554c5

10 months ago

0.0.0-main-db101241

10 months ago

0.0.0-main-37c3574c

10 months ago

0.0.0-main-609cdfe4

12 months ago

0.0.0-main-8c61c095

12 months ago

0.0.0-main-be0441b1

10 months ago

0.0.0-main-259e9baf

12 months ago

0.0.0-main-e7ae4c32

12 months ago

0.0.0-main-d85dbeaa

12 months ago

0.0.0-main-21275f7c

10 months ago

0.0.0-main-796c8e6d

12 months ago

0.0.0-main-1e3f3965

10 months ago

0.0.0-main-4deff5f0

11 months ago

0.0.0-main-b586c45f

10 months ago

0.0.0-main-9c6824bf

12 months ago

0.0.0-main-27c54dfe

12 months ago

0.0.0-main-e3e8bd35

12 months ago

0.0.0-main-f967d0d8

12 months ago

0.0.0-main-a779c3fa

12 months ago

0.0.0-main-7e518adc

12 months ago

0.0.0-main-5786fd9a

12 months ago

0.0.0-main-312396ca

12 months ago

0.0.0-main-bc3a4c4e

12 months ago

0.0.0-main-2d80240d

12 months ago

0.2.0

1 year ago

0.1.1

2 years ago

0.1.0

2 years ago

0.0.4

2 years ago