• Stars
    star
    119
  • Rank 297,930 (Top 6 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created over 4 years ago
  • Updated almost 2 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

馃К Run side-effects safely in React

馃К useMutation - Run side-effects safely in React

CI Publish

Specially useful to run requests against an API, and combined with SWR.

Usage

Install it:

$ yarn add use-mutation

Import it:

import useMutation from 'use-mutation';

Create a function which runs a mutation

async function createComment({
  authorId,
  comment,
}: {
  authorId: number;
  comment: string;
}) {
  const res = await fetch('/api/comments', {
    method: 'POST',
    body: JSON.stringify({ authorId, comment }),
  });
  if (!res.ok) throw new Error(res.statusText);
  return await res.json();
}

Use your function with useMutation

function CommentForm({ authorId }) {
  const [comment, setComment] = React.useState('');
  const [mutate, { status }] = useMutation(createComment, {
    onMutate({ input }) {
      // do something before the mutation run
      return () => {
        // rollback changes if the mutation failed
      };
    },
    onSuccess({ data, input }) {
      // do something once the mutation succeeded
    },
    onFailure({ error, rollback, input }) {
      // do something once the mutation failed
    },
    onSettled({ status, error, data, rollback, input }) {
      switch (status) {
        case 'success': {
          // do something if the mutation succeeded
        }
        case 'failure': {
          // do something if the mutation failed
        }
      }
    },
  });

  const handleSubmit = React.useCallback(
    function handleSubmit(event) {
      mutate({ authorId, comment });
    },
    [mutate, comment]
  );

  // render your UI
}

Usage with SWR

If you are using SWR, you can use useMutation to run your mutations to perform Optimistic UI changes.

import { cache, mutate } from 'swr';

function createComment(input) {
  // ...
}

function useCreateComment() {
  return useMutation(createComment, {
    onMutate({ input }) {
      const oldData = cache.get('comment-list');
      // optimistically update the data before your mutation is run
      mutate('comment-list', current => current.concat(input), false);
      return () => mutate('comment-list', oldData, false); // rollback if it failed
    },

    onFailure({ rollback }) {
      if (rollback) rollback();
    },
  });
}

This way when you run mutate, it will first optimistically update your SWR cache and if it fails it will rollback to the old data.

API Reference

const [mutate, { status, data, error, reset }] = useMutation<
  Input,
  Data,
  Error
>(mutationFn, {
  onMutate,
  onSuccess,
  onFailure,
  onSettled,
  throwOnFailure,
  useErrorBoundary,
});

const promise = mutate(input, {
  onSuccess,
  onSettled,
  onError,
  throwOnFailure,
});

Hook Generic

Only if you are using TypeScript

  • Input = any
    • The data your mutation function needs to run
  • Data = any
    • The data the hook will return as result of your mutation
  • Error = any
    • The error the hook will return as a failure in your mutation

Hook Options

  • mutationFn(input: Input): Promise<Data>
    • Required
    • A function to be executed before the mutation runs.
    • It receives the same input as the mutate function.
    • It can be an async or sync function, in both cases if it returns a function it will keep it as a way to rollback the changed applied inside onMutate.
  • onMutate?({ input: Input }): Promise<rollbackFn | undefined> | rollbackFn | undefined
    • Optional
    • A function to be executed before the mutation runs.
    • It receives the same input as the mutate function.
    • It can be an async or sync function, in both cases if it returns a function.
    • it will keep it as a way to rollback the changed applied inside onMutate
  • onSuccess?({ data: Data, input: Input }): Promise<void> | void
    • Optional
    • A function to be executed after the mutation resolves successfully.
    • It receives the result of the mutation.
    • If a Promise is returned, it will be awaited before proceeding.
  • onFailure?({ error: Error, rollback: rollbackFn, input: Input }): Promise<void> | void
    • Optional
    • A function to be executed after the mutation failed to execute.
    • If a Promise is returned, it will be awaited before proceeding.
  • onSettled?({ status: 'success' | 'failure', error?: Error, data?: Data, rollback?: rollbackFn, input: Input}): Promise<void> | void
    • Optional
    • A function to be executed after the mutation has resolves, either successfully or as failure.
    • This function receives the error or the result of the mutation.
    • If a Promise is returned, it will be awaited before proceeding.
  • throwOnFailure?: boolean
    • Optional
    • If defined as true, a failure in the mutation will cause the mutate function to throw. Disabled by default.
  • useErrorBoundary?: boolean (default false)
    • Optional
    • If defined as true, a failure in the mutation will cause the Hook to throw in render time, making error boundaries catch the error.

Hook Returned Value

  • mutate(input: Input, config: Omit<Options<Input, Data, Error>, 'onMutate' | 'useErrorBoundary'> = {}): Promise<Data | undefined>
    • The function you call to trigger your mutation, passing the input your mutation function needs.
    • All the lifecycle callback defined here will run after the callback defined in the Hook.
  • status: 'idle' | 'running' | 'success' | 'failure'
    • The current status of the mutation, it will be:
      • idle initial status of the hook, and the status after a reset
      • running if the mutation is currently running
      • success if the mutation resolved successfully
      • failure if the mutation failed to resolve
  • data: Data
    • The data returned as the result of the mutation.
  • error: Error
    • The error returned as the result of the mutation.
  • `reset(): void
    • A function to reset the internal state of the Hook to the orignal idle and clear any data or error.

Author

License

The MIT License.

More Repositories

1

remix-utils

A set of utility functions and types to use with Remix.run
TypeScript
1,934
star
2

remix-auth

Simple Authentication for Remix
TypeScript
1,782
star
3

remix-i18next

The easiest way to translate your Remix apps
TypeScript
520
star
4

impresionante-javascript

Recopilaci贸n de links en espa帽ol sobre JavaScript
415
star
5

flagged

Feature Flags for React made easy with hooks, HOC and Render Props
TypeScript
386
star
6

remix-hono

Hono middlewares for Remix
TypeScript
321
star
7

next-ga

Next.js HOC to integrate Google Analytics on every page change
JavaScript
232
star
8

grial

A Node.js framework for creating GraphQL API servers easily and without a lot of boilerplate.
JavaScript
189
star
9

next-nprogress

Next.js HOC to integrate NProgress inside your app
JavaScript
149
star
10

remix-auth-oauth2

A OAuth2Strategy for Remix Auth
TypeScript
129
star
11

swr-sync-storage

Synchronize SWR cache with localStorage or sessionStorage to get offline cache
TypeScript
109
star
12

react-lazy-image

Component to render images and lazyload them if are in the viewport (or near to them).
JavaScript
101
star
13

personal-site

Personal website
TypeScript
95
star
14

now-storage

Use Now static deployments to upload and store files.
JavaScript
90
star
15

remix-auth-form

A Remix Auth strategy for working with forms.
TypeScript
79
star
16

sergiodxa.com

The code behind sergiodxa.com
TypeScript
71
star
17

remix-auth-github

A GitHubStrategy for Remix Auth, based on the OAuth2Strategy
TypeScript
66
star
18

redux-in-spanish

Traducci贸n al espa帽ol de la documentaci贸n de Redux.
64
star
19

web-oidc

An OpenID Connect client built using only Web APIs
TypeScript
49
star
20

remix-auth-strategy-template

A template for creating a new Remix Auth strategy.
TypeScript
47
star
21

remix-socket.io

A Remix app using Express and Socket.io
TypeScript
45
star
22

next-socket.io

An example app with Next.js and socket.io
JavaScript
38
star
23

remix-inspector

Remix devtools to inspect your route data.
TypeScript
38
star
24

react-wordpress

Example of a React+Next.js+WordPress application.
JavaScript
36
star
25

react-lazy-memo

CRA with Suspense, lazy and memo usage demo app
JavaScript
36
star
26

swr-mutate-many

Little function to call mutate against multiple cached keys of SWR
TypeScript
26
star
27

remix-demo-infinite-scroll

A collection of infinite scroll pagination demos built with Remix
TypeScript
26
star
28

now-ab

A simple proxy server to handle Now.sh deployments AB tests
JavaScript
25
star
29

remix-on-bun

TypeScript
25
star
30

es6

Material para la clase BONUS en Comunidad Platzi sobre ECMAScript 6.
HTML
23
star
31

react-course-project

Proyecto para el curso de React.js
JavaScript
22
star
32

micro-next

Integrations between Micro and Next.js
JavaScript
20
star
33

collected-notes

A TypeScript client for the Collected Notes API
17
star
34

now-parcel

A Now v2 Parcel builder.
JavaScript
16
star
35

api-client

A strongly typed API client using Zod
TypeScript
15
star
36

remix-demo-file-upload

A simple demo on how to add a file upload that shows the image being uploaded and later replace it with the actual one
TypeScript
15
star
37

remix-vite-i18next

An example Remix + Vite app with remix-i18next setup
TypeScript
14
star
38

collected-remix

A Collected Notes client in Remix
TypeScript
12
star
39

micro-platzi-profile

Ejemplo de microservicio usando https://github.com/zeit/micro para scrappear un perf铆l de Platzi
JavaScript
12
star
40

markdown-it-mentions

markdown-it plugin to support Twitter like mentions
JavaScript
11
star
41

react-use-permissions

React hook for Permissions API
JavaScript
11
star
42

use-safe-callback

Wrap a function to ensure you never call it if a component is unmounted, useful to avoid cases where an async code could finish after a component has unmounted and it tries to update a state
TypeScript
11
star
43

redux-duck

Helper function to create Redux modules using the ducks-modular-redux proposal
TypeScript
10
star
44

use-log

Log a state or prop every time it changes
TypeScript
10
star
45

cf-bootcamp-react-router-lesson

TypeScript
9
star
46

react-simple-modal

React modal make it simple.
JavaScript
8
star
47

collected-notes-website

A Next.js based clon of the Collected Notes website
TypeScript
8
star
48

remix-mdn

A MDN clone of Remix
TypeScript
8
star
49

remix-auth-token

Token based authentication for Remix Auth
TypeScript
8
star
50

next-analytics

Next.js HOC to integrate Google Analytics and FB Pixel
JavaScript
8
star
51

personal-slides

The slides of my talks
JavaScript
7
star
52

collected-notes-next-blog

Blog example using Collected Notes as CMS
TypeScript
7
star
53

react-use-quicklink

Quicklink hook for React
JavaScript
6
star
54

use-validate-image-url

TypeScript
6
star
55

email-value

TypeScript
6
star
56

isomorphic-react-todo

Aplicaci贸n web de TODOs isom贸rfica hecha con React.js
JavaScript
6
star
57

use-consistent-value

Keep a consistent reference to an object or array based on their values.
TypeScript
6
star
58

markdown-it-codesandbox

markdown-it plugin to embed CodeSandbox editor.
JavaScript
5
star
59

remix-demo-prefetch-fetcher

Demo Remix app to prefetch the fetcher data
TypeScript
5
star
60

next-custom-query

Example Next.js app using a custom server with queries in the URLs.
JavaScript
5
star
61

yifi-search

Backbone.js WebApp for search torrents with the YIFI's API.
JavaScript
5
star
62

navBarAdaptable-mejorUX

Barra de navegaci贸n adaptable con Media Queries y JS
CSS
5
star
63

next-babel-minify

Next.js plugin to replace UglifyJS for BabelMinify
JavaScript
5
star
64

gulp-tasks-boilerplate

Plantilla de tareas de Gulp.js para distintos usos, con un package.json con todos los m贸dulos requeridos.
JavaScript
5
star
65

remix-auth-webauthn

A strategy to support WebAuthn
TypeScript
4
star
66

remix-auth-austin-demo

Remix Auth demo for the Remix Austin meetup
TypeScript
4
star
67

MarvelDB

Webapp to find characters in the Marvel database.
JavaScript
4
star
68

remix-markdoc-example

TypeScript
4
star
69

remix-define-routes

A DSL to define Remix routes with code
TypeScript
4
star
70

swr-sync-session

This is an example Next.js + SWR application using SWR revalidation on focus feature to sync session between tabs
JavaScript
4
star
71

dataset

A free to use API to get a lists of various common datasets such as languages, countries, etc.
JavaScript
3
star
72

next-credentials

Next.js example using Credential Management API
JavaScript
3
star
73

personal-cli

A CLI tool with commands for personal usage.
JavaScript
3
star
74

platzimusic

Proyecto para el diplomado de React en Platzi
JavaScript
3
star
75

cf-custom-hooks

Ejercicios de Custom Hooks para C贸digo Facilito
TypeScript
3
star
76

personal-api

An API created for my personal site usage.
JavaScript
2
star
77

cf-bootcamp-deploy

TypeScript
2
star
78

techtalks-remix-demo

Demo of Remix.run for Tech Talks.pe
TypeScript
2
star
79

react-render-service

React Render as a Service
JavaScript
1
star
80

personal-shortening

A personal URL shortening service
JavaScript
1
star
81

virtual-event-starter-kit

TypeScript
1
star
82

remix-with-sentry-sdk

A reproduction of the issue https://github.com/getsentry/sentry-javascript/issues/6294
TypeScript
1
star
83

archive-it

API to get the messages of a Slack channel
TypeScript
1
star
84

ngCreate

CLI to create AngularJS files
JavaScript
1
star
85

react-chat-app

JavaScript
1
star
86

pokedex-swr

Pokedex Application using Next.js and SWR with Tailwind for styling
TypeScript
1
star
87

swr-devtools

TypeScript
1
star
88

dice-roller

A tiny library to calculate roll dices using the classic D&D sintax: 1d20+4.
JavaScript
1
star
89

react-i18n

Ejemplo de internacionalizaci贸n con React.js y Format.js
JavaScript
1
star
90

es-query

An utilitarian library for DOM manipulation using ECMAScript 7 Function Bind Syntax
JavaScript
1
star
91

device-info

A little service to check a device information.
HTML
1
star
92

deno-md-to-html

Simple MD to HTML parser
TypeScript
1
star
93

package

A template to create new packages.
TypeScript
1
star
94

Check-userAgent

New method for JS window object that checks the userAgent and returns true if a mobile.
1
star
95

Elecalc

Webapp hecha con AngularJS para realizar distintos c谩lculos de electricidad de una manera f谩cil y r谩pida
HTML
1
star
96

tpb-app

WebApp in NodeJS to search torrents in The Pirate Bay
JavaScript
1
star
97

remix-island-demos

TypeScript
1
star