inventory_2 @use-gpu/state

npm install --save @use-gpu/state

yarn add @use-gpu/state

Docs: https://usegpu.live/docs/reference-live-@use-gpu-state

React/Live - State management helpers

Manipulate JS state declaratively.

Helper library for doing patch and diff-based state management.

Can be used to drive undo/redo. Includes cursor hooks for React/Live.

import { patch, diff } from '@use-gpu/state';

• JS-value patching, diffing, reversing
• JS-value hashing
• Cursor-based state

// React
import { useUpdateState, useCursor } from '@use-gpu/state/react';

// Live
import { useUpdateState, useCursor } from '@use-gpu/state/live';

Patching

patch will apply an update to a nested object, without modifying the original.

const value  = {hello: 'text', value: 2};
const update = {hello: 'world'};

expect(patch(value, update)).toEqual({hello: 'world', value: 2});

The default behavior is:

• Merge object properties from update into value recursively.
• Treat arrays as values, do not recurse, only replace them as a whole.

To adjust the behavior, e.g. to replace an object instead of merging it, use the included $op helpers:

• $apply
• $delete
• $merge
• $nop
• $patch
• $set

e.g.

const value  = {hello: {title: 'text', href: '#'}, value: 2};
const update = {hello: $set({title: 'world'});

expect(patch(values, update)).toEqual({ hello: { title: 'world' }, value: 2});

Custom $ops

You can use $apply to make custom patching ops, e.g. to append an item to a list:

const $push = <T>(item: T) => $apply((list: T[]) => [...list, item]);

const newList = patch(list, $push(item));

This can be used anywhere in a patch:

const newState = patch(state, {
  nested: {
    list: $push('hello'),
  }
});

Diff

diff is the complement to patch.

Given two values A and B, it will return an update so that:

const update = diff(A, B);
expect(patch(A, update)).toEqual(B);

...patching A with it equals the value B (though not the same object(s) as B).

If you diff(A, B) after a patch(A, ...), you get a pure update, without $apply or $patch. This can be serialized to JSON.

Note that a diff may contain empty updates such as { } if an object was cloned. Use getUpdateKeys to check whether an update contains real changes.

Revise

To reverse an update, you can diff(B, A):

const B = patch(A, update);
const reversed = diff(B, A);

expect(patch(B, reversed)).toEqual(A);

To optimize and formalize this, revise is (almost) the same operation.

It is a reverse complement to patch. Given a value A, and an update, it will patch the update so that:

// Don't need B to reverse
const reversed = revise(A, update);

const B = patch(A, update);
expect(patch(B, reversed)).toEqual(A);

...applying the reversed update will reverse the original update along the exact same boundaries.

This can be used to build an automatic undo/redo system that works with any $op.

Use getUpdateKeys to check whether a revised update is actually effectful or consists solely of $nop.

Cursors

Most UI state is simple, and consists of straight forward "set foo to bar" type actions. When this state lives inside an existing object, this requires a fair amount of boilerplate:

const [state, setState] = useState({
  foo: {
    // ...
    size: 5,
  },
  // ...
});

const {foo: {size}} = state;
const setSize = (size: number) => {
  setState((state) => {
    ...state,
    foo: {
      ...state.foo,
      size,
    },
  })
};

You can simplify this by relying on patch(…) to do all your mutating. Instead of a setState(…), you now have an updateState(…):

import { useCursor, useUpdateState } from '@use-gpu/state/react';

// Create state pair, get cursor
const [state, updateState] = useUpdateState({...});
const stateCursor = useCursor([state, updateState]);

// More compact form
const stateCursor = useCursor(useUpdateState({...}));

Cursors can be traversed just like the original value:

const sizeCursor = stateCursor.foo.size;

To extract a getter/updater pair, call it:

const [size, updateSize] = sizeCursor();

This can be written as stateCursor.foo.size().

When you call updateSize(5), this is equivalent to updateState({foo: {size: 5}}). The updater callbacks are auto-generated and all call the same central useUpdateState.

This works as expected, because useUpdateState will merge this change into the original state. The argument to updateState is an Update, i.e. the argument to patch.

The merging behavior of an Update can be precisely controlled, at the individual field level.

Cursors are also available in non-hook form via makeCursor.

Defaults

const DEFAULTS = {
  foo: { size: 10 },
  // ...
};
const stateCursor = useCursor(useUpdateState({...}), DEFAULTS);

useCursor(…) can accept defaults as a 2nd argument. When it traverses the original value, if it encounters a missing field, it will fill in the one from the default non-destructively.

When it then applies an update, it will first patch in the right default values, and then make the change. This ensures clean partial patches of missing nested fields.

Memoization

• Cursors are immutable: if the value has changed, you get a new cursor instance.

• useCursor is memoized: if the value didn't change, you get the same cursor back.

• Lookups cursor.foo.bar are stable. It's safe to use a derived cursor directly as a hook dependency.

• Cursors for unchanged values are stable (if the root updateState hasn't changed).

• i.e. Even if cursor has changed, cursor.foo.bar may be reused.

Utils

Hashing

• toHash will hash any JS value to a 10-digit base 64 string.
• toMurmur53 will hash any JS value to a 53-bit number.

Keys

• getObjectKey assigns a unique, incrementing 53-bit ID to each unique object (uses a WeakMap).
• makeKey returns a new unique ID from the same set.

Colofon

Made by Steven Wittens. Part of @use-gpu.