项目作者: karolis-sh

项目描述 :
Optimistic UI utilities
高级语言: TypeScript
项目地址: git://github.com/karolis-sh/use-optimistic-update.git
创建时间: 2020-04-14T18:55:33Z
项目社区:https://github.com/karolis-sh/use-optimistic-update

开源协议:MIT License

下载


use-optimistic-update

npm version
gzip size
Node.js CI
License: MIT
code style: prettier

Improve perceived performance by predicting the future outcome

A set of utilities to achieve Optimistic UI effect. Helps to bridge the gap
between async state changes.

Example

Converting async counter to optimistic component that reacts to user actions instantly:

  1. import React, { useState } from 'react';
  2. + import { useOptimisticUpdate } from "use-optimistic-update";
  3. export default function UpTo3Counter() {
  4. const [counter, setCounter] = useState(0);
  5. + const { value, onUpdate } = useOptimisticUpdate("count3r", counter);
  6. const increment = (value) =>
  7. new Promise((resolve) => {
  8. setTimeout(() => {
  9. if (value <= 3) setCounter(value);
  10. resolve();
  11. }, 1000);
  12. });
  13. return (
  14. <button
  15. onClick={() => {
  16. const newValue = counter + 1;
  17. - increment(newValue);
  18. + onUpdate(() => increment(newValue), newValue);
  19. }}
  20. >
  21. - Likes: {counter}
  22. + Likes: {value}
  23. </button>
  24. );
  25. }

Installation

npm i use-optimistic-update

or

yarn add use-optimistic-update

Features

  • shareable state between multiple components
  • hooks
  • direct event emitter access
  • typescript support

API

useOptimisticUpdate

useOptimisticUpdate is a hook that let’s you sync and update the optimistic state.

  1. import { useOptimisticUpdate } from 'use-optimistic-update';
  2. const { value, onUpdate, isUpdating } = useOptimisticUpdate(
  3. stateKey,
  4. realValue,
  5. );

Options

  • stateKey: string
    • Required
  • realValue: string | number | boolean | undefined
    • Required

Returns

  • value: string | number | boolean | undefined

    • The optimistic value
    1. onUpdate: (
    2. updater: () => Promise<void>,
    3. newValue: string | number | boolean | undefined,
    4. ) => Promise<void>;
    • Updater function that should be called when you want to update real and optimistic
      values
    • updater
      • Async function that should perform the real value change
      • While this function is executing the optimistic value is perceived
    • newValue
      • The new optimistic value
  • isUpdating: boolean

    • Is an update being performed for given stateKey

Using onUpdate function

  1. <button
  2. className={}
  3. onClick={() => {
  4. onUpdate(async () => {
  5. await incrementCounter();
  6. }, counter + 1);
  7. }}
  8. >
  9. {counter}
  10. </button>

useOptimisticState

useOptimisticState is a hook that let’s you retrieve the optimistic state.

  1. import { useOptimisticState } from 'use-optimistic-update';
  2. const { value, isUpdating } = useOptimisticState(stateKey);

Options

  • stateKey: string
    • Required

Returns

  • value: string | number | boolean | undefined
    • The optimistic value
  • isUpdating: boolean
    • Is an update being performed for given stateKey

optimist

optimist is the underlying event emitter used by the hooks. It is responsible
for updating / syncing of optimistic / real values.

optimist.sync

Synchronize the real value with optimist instance.

  1. import { optimist } from 'use-optimistic-update';
  2. optimist.sync(stateKey, realValue);

Options

  • stateKey: string
    • Required
  • realValue: string | number | boolean | undefined
    • Required

optimist.update

Update optimistic value inside the optimist instance.

  1. import { optimist } from 'use-optimistic-update';
  2. optimist.update(stateKey, updater, optimisticValue);

Options

  • stateKey: string
    • Required
  • updater: () => Promise<void>
    • Required
  • optimisticValue: string | number | boolean | undefined
    • Required
Using optimist.update
  1. import { optimist } from 'use-optimistic-update';
  2. optimist.update(
  3. 'count3r',
  4. async () => {
  5. await incrementCounter();
  6. },
  7. counter + 1,
  8. );

optimist.getState

Retrieve the optimistic state.

  1. import { optimist } from 'use-optimistic-update';
  2. const { value, isUpdating } = optimist.getState(stateKey);

Options

  • stateKey: string
    • Required

Returns

  • value: string | number | boolean | undefined
    • The optimistic value
  • isUpdating: boolean
    • Is an update being performed for given stateKey

optimist.onUpdate

Retrieve the optimistic state.

  1. import { optimist } from 'use-optimistic-update';
  2. const unbind = optimist.onUpdate(stateKey, listener);

Options

  • stateKey: string

    • Required
    1. listener: ({
    2. value: string | number | boolean | undefined;
    3. isUpdating: boolean;
    4. }) => void
    • Required
    • The function that will be called every time the optimistic state changes

Returns

  • unbind: () => void
    • A function to remove the event listener
Using optimist.onUpdate
  1. import { useEffect } from 'react';
  2. import { optimist } from 'use-optimistic-update';
  3. useEffect(() => {
  4. const unbind = optimist.onUpdate('count3r', ({ value, isUpdating }) => {
  5. console.log('count3r changes:', value, isUpdating);
  6. });
  7. return unbind;
  8. }, []);

FAQ

  • What is Optimistic UI?

Optimistic UI is a pattern that you can use to simulate the results of a mutation
and update the UI even before receiving a response from the server.

License

MIT