feat: Hook for remote mutations

examples/axios-typescript/libs/useRequest.ts

@@ -24,10 +24,12 @@ export default function useRequest<Data = unknown, Error = unknown>(
   request: GetRequest,
   { fallbackData, ...config }: Config<Data, Error> = {}
 ): Return<Data, Error> {
-  const { data: response, error, isValidating, mutate } = useSWR<
-    AxiosResponse<Data>,
-    AxiosError<Error>
-  >(
+  const {
+    data: response,
+    error,
+    isValidating,
+    mutate
+  } = useSWR<AxiosResponse<Data>, AxiosError<Error>>(
     request && JSON.stringify(request),
     /**
      * NOTE: Typescript thinks `request` can be `null` here, but the fetcher

jest.config.js

@@ -6,7 +6,8 @@ module.exports = {
   moduleNameMapper: {
     '^swr$': '<rootDir>/src',
     '^swr/infinite$': '<rootDir>/infinite/index.ts',
-    '^swr/immutable$': '<rootDir>/immutable/index.ts'
+    '^swr/immutable$': '<rootDir>/immutable/index.ts',
+    '^swr/mutation$': '<rootDir>/mutation/index.ts'
   },
   transform: {
     '^.+\\.(t|j)sx?$': [

mutation/index.ts

@@ -0,0 +1,125 @@
+import { useCallback, useRef } from 'react'
+import useSWR, { useSWRConfig, Middleware, Key } from 'swr'
+
+import { serialize } from '../src/utils/serialize'
+import { useStateWithDeps } from '../src/utils/state'
+import { withMiddleware } from '../src/utils/with-middleware'
+import { useIsomorphicLayoutEffect } from '../src/utils/env'
+import { UNDEFINED } from '../src/utils/helper'
+import { getTimestamp } from '../src/utils/timestamp'
+
+import {
+  SWRMutationConfiguration,
+  SWRMutationResponse,
+  SWRMutationHook,
+  MutationFetcher
+} from './types'
+
+const mutation =
+  <Data, Error>() =>
+  (
+    key: Key,
+    fetcher: MutationFetcher<Data>,
+    config: SWRMutationConfiguration<Data, Error> = {}
+  ) => {
+    const { mutate } = useSWRConfig()
+
+    const keyRef = useRef(key)
+    // Ditch all mutation results that happened earlier than this timestamp.
+    const ditchMutationsTilRef = useRef(0)
+
+    const [stateRef, stateDependencies, setState] = useStateWithDeps(
+      {
+        data: UNDEFINED,
+        error: UNDEFINED,
+        isMutating: false
+      },
+      true
+    )
+    const currentState = stateRef.current
+
+    // Similar to the global mutate, but bound to the current cache and key.
+    // `cache` isn't allowed to change during the lifecycle.
+    const boundMutate = useCallback(
+      (arg0, arg1) => mutate(serialize(keyRef.current)[0], arg0, arg1),
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      []
+    )
+
+    const trigger = useCallback(async (extraArg, opts) => {
+      if (!fetcher) {
+        throw new Error('Can’t trigger the mutation: missing fetcher.')
+      }
+
+      const [serializedKey, args] = serialize(keyRef.current)
+
+      // Disable cache population by default.
+      const options = Object.assign({ populateCache: false }, config, opts)
+
+      // Trigger a mutation, also track the timestamp. Any mutation that happened
+      // earlier this timestamp should be ignored.
+      const mutationStartedAt = getTimestamp()
+      ditchMutationsTilRef.current = mutationStartedAt
+
+      setState({ isMutating: true })
+      args.push(extraArg)
+
+      try {
+        const data = await mutate(
+          serializedKey,
+          (fetcher as any)(...args),
+          options
+        )
+
+        // If it's reset after the mutation, we don't broadcast any state change.
+        if (ditchMutationsTilRef.current <= mutationStartedAt) {
+          setState({ data, isMutating: false })
+          options.onSuccess && options.onSuccess(data, serializedKey, options)
+        }
+        return data
+      } catch (error) {
+        // If it's reset after the mutation, we don't broadcast any state change.
+        if (ditchMutationsTilRef.current <= mutationStartedAt) {
+          setState({ error: error as Error, isMutating: false })
+          options.onError && options.onError(error, serializedKey, options)
+        }
+        throw error
+      }
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [])
+
+    const reset = useCallback(() => {
+      ditchMutationsTilRef.current = getTimestamp()
+      setState({ data: UNDEFINED, error: UNDEFINED, isMutating: false })
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [])
+
+    useIsomorphicLayoutEffect(() => {
+      keyRef.current = key
+    })
+
+    return {
+      mutate: boundMutate,
+      trigger,
+      reset,
+      get data() {
+        stateDependencies.data = true
+        return currentState.data
+      },
+      get error() {
+        stateDependencies.error = true
+        return currentState.error
+      },
+      get isMutating() {
+        stateDependencies.isMutating = true
+        return currentState.isMutating
+      }
+    }
+  }
+
+export default withMiddleware(
+  useSWR,
+  mutation as unknown as Middleware
+) as unknown as SWRMutationHook
+
+export { SWRMutationConfiguration, SWRMutationResponse }

mutation/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "swr-mutation",
+  "version": "0.0.1",
+  "main": "./dist/index.js",
+  "module": "./dist/index.esm.js",
+  "types": "./dist/mutation",
+  "peerDependencies": {
+    "swr": "*",
+    "react": "*"
+  }
+}

mutation/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "..",
+    "outDir": "./dist"
+  },
+  "include": ["./*.ts"]
+}

mutation/types.ts

@@ -0,0 +1,79 @@
+import { SWRResponse, SWRConfiguration, Key, MutatorOptions } from 'swr'
+
+type Async<Data> = Data | Promise<Data>
+
+export type MutationFetcher<
+  Data = unknown,
+  SWRKey extends Key = Key,
+  ExtraArg = any
+> =
+  /**
+   * () => [{ foo: string }, { bar: number }] | null
+   * () => ( [{ foo: string }, { bar: number } ] as const | null )
+   */
+  SWRKey extends () => readonly [...infer Args] | null
+    ? (...args: [...Args, ExtraArg]) => Async<Data>
+    : /**
+     * [{ foo: string }, { bar: number } ] | null
+     * [{ foo: string }, { bar: number } ] as const | null
+     */
+    SWRKey extends readonly [...infer Args]
+    ? (...args: [...Args, ExtraArg]) => Async<Data>
+    : /**
+     * () => string | null
+     * () => Record<any, any> | null
+     */
+    SWRKey extends () => infer Arg | null
+    ? (...args: [Arg, ExtraArg]) => Async<Data>
+    : /**
+     *  string | null | Record<any,any>
+     */
+    SWRKey extends null
+    ? never
+    : SWRKey extends infer Arg
+    ? (...args: [Arg, ExtraArg]) => Async<Data>
+    : never
+
+export type SWRMutationConfiguration<
+  Data,
+  Error,
+  SWRMutationKey extends Key = Key,
+  ExtraArg = any
+> = Pick<
+  SWRConfiguration<
+    Data,
+    Error,
+    MutationFetcher<Data, SWRMutationKey, ExtraArg>
+  >,
+  'fetcher' | 'onSuccess' | 'onError'
+> &
+  MutatorOptions<Data>
+
+export interface SWRMutationResponse<
+  Data = any,
+  Error = any,
+  SWRMutationKey extends Key = Key,
+  ExtraArg = any
+> extends Omit<SWRResponse<Data, Error>, 'isValidating'> {
+  isMutating: boolean
+  trigger: (
+    extraArgument?: ExtraArg,
+    options?: SWRMutationConfiguration<Data, Error, SWRMutationKey, ExtraArg>
+  ) => Promise<Data | undefined>
+  reset: () => void
+}
+
+export type SWRMutationHook = <
+  Data = any,
+  Error = any,
+  SWRMutationKey extends Key = Key,
+  ExtraArg = any
+>(
+  ...args:
+    | readonly [SWRMutationKey, MutationFetcher<Data, SWRMutationKey, ExtraArg>]
+    | readonly [
+        SWRMutationKey,
+        MutationFetcher<Data, SWRMutationKey, ExtraArg>,
+        SWRMutationConfiguration<Data, Error, SWRMutationKey, ExtraArg>
+      ]
+) => SWRMutationResponse<Data, Error, SWRMutationKey, ExtraArg>

package.json

@@ -20,6 +20,11 @@
       "import": "./immutable/dist/index.esm.js",
       "require": "./immutable/dist/index.js",
       "types": "./immutable/dist/immutable/index.d.ts"
+    },
+    "./mutation": {
+      "import": "./mutation/dist/index.esm.js",
+      "require": "./mutation/dist/index.js",
+      "types": "./mutation/dist/mutation/index.d.ts"
     }
   },
   "react-native": "./dist/index.esm.js",
@@ -28,22 +33,26 @@
     "dist/**",
     "infinite/dist/**",
     "immutable/dist/**",
+    "mutation/dist/**",
     "infinite/package.json",
-    "immutable/package.json"
+    "immutable/package.json",
+    "mutation/package.json"
   ],
   "repository": "vercel/swr",
   "homepage": "https://swr.vercel.app",
   "license": "MIT",
   "scripts": {
-    "clean": "rimraf dist infinite/dist immutable/dist",
-    "build": "yarn build:core && yarn build:infinite && yarn build:immutable",
+    "clean": "rimraf dist infinite/dist immutable/dist mutation/dist",
+    "build": "yarn build:core && yarn build:infinite && yarn build:immutable && yarn build:mutation",
     "watch": "yalc publish && node scripts/watch.js",
     "watch:core": "node scripts/watch.js core",
     "watch:infinite": "node scripts/watch.js infinite",
     "watch:immutable": "node scripts/watch.js immutable",
+    "watch:mutation": "node scripts/watch.js mutation",
     "build:core": "bunchee src/index.ts --no-sourcemap",
     "build:infinite": "bunchee index.ts --cwd infinite --no-sourcemap",
     "build:immutable": "bunchee index.ts --cwd immutable --no-sourcemap",
+    "build:mutation": "bunchee index.ts --cwd mutation --no-sourcemap",
     "prepublishOnly": "yarn clean && yarn build",
     "publish-beta": "yarn publish --tag beta",
     "types:check": "tsc --noEmit --project tsconfig.check.json && tsc --noEmit -p test",

scripts/watch.js

@@ -19,6 +19,10 @@ const entryMap = {
   immutable: {
     entry: 'index.ts',
     cwd: 'immutable'
+  },
+  mutation: {
+    entry: 'index.ts',
+    cwd: 'mutation'
   }
 }
 

src/types.ts

@@ -149,6 +149,11 @@ export type MutatorOptions<Data = any> = {
   rollbackOnError?: boolean
 }
 
+export type MutatorConfig = {
+  revalidate?: boolean
+  populateCache?: boolean
+}
+
 export type Broadcaster<Data = any, Error = any> = (
   cache: Cache<Data>,
   key: string,

src/use-swr.ts

@@ -110,14 +110,11 @@ export const useSWRHandler = <Data = any, Error = any>(
   }
   const isValidating = resolveValidating()
 
-  const [stateRef, stateDependencies, setState] = useStateWithDeps<Data, Error>(
-    {
-      data,
-      error,
-      isValidating
-    },
-    unmountedRef
-  )
+  const [stateRef, stateDependencies, setState] = useStateWithDeps({
+    data,
+    error,
+    isValidating
+  })
 
   // The revalidation function is a carefully crafted wrapper of the original
   // `fetcher`, to correctly handle the many edge cases.

src/utils/env.ts

@@ -5,7 +5,9 @@ export const IS_SERVER = !hasWindow() || 'Deno' in window
 
 // Polyfill requestAnimationFrame
 export const rAF = (f: (...args: any[]) => void) =>
-  hasRequestAnimationFrame() ? window['requestAnimationFrame'](f) : setTimeout(f, 1)
+  hasRequestAnimationFrame()
+    ? window['requestAnimationFrame'](f)
+    : setTimeout(f, 1)
 
 // React currently throws a warning when using useLayoutEffect on the server.
 // To get around it, we can conditionally useEffect on the server (no-op) and
@@ -15,12 +17,14 @@ export const useIsomorphicLayoutEffect = IS_SERVER ? useEffect : useLayoutEffect
 // This assignment is to extend the Navigator type to use effectiveType.
 const navigatorConnection =
   typeof navigator !== 'undefined' &&
-  (navigator as Navigator & {
-    connection?: {
-      effectiveType: string
-      saveData: boolean
+  (
+    navigator as Navigator & {
+      connection?: {
+        effectiveType: string
+        saveData: boolean
+      }
     }
-  }).connection
+  ).connection
 
 // Adjust the config based on slow connection status (<= 70Kbps).
 export const slowConnection =

src/utils/helper.ts

@@ -15,4 +15,5 @@ export const mergeObjects = (a: any, b: any) => OBJECT.assign({}, a, b)
 const STR_UNDEFINED = 'undefined'
 export const hasWindow = () => typeof window != STR_UNDEFINED
 export const hasDocument = () => typeof document != STR_UNDEFINED
-export const hasRequestAnimationFrame = () => (hasWindow() && (typeof window['requestAnimationFrame'] != STR_UNDEFINED))
+export const hasRequestAnimationFrame = () =>
+  hasWindow() && typeof window['requestAnimationFrame'] != STR_UNDEFINED

src/utils/resolve-args.ts

@@ -5,7 +5,7 @@ import { useSWRConfig } from './use-swr-config'
 // It's tricky to pass generic types as parameters, so we just directly override
 // the types here.
 export const withArgs = <SWRType>(hook: any) => {
-  return (((...args: any) => {
+  return ((...args: any) => {
     // Get the default and inherited configuration.
     const fallbackConfig = useSWRConfig()
 
@@ -25,5 +25,5 @@ export const withArgs = <SWRType>(hook: any) => {
     }
 
     return next(key, fn || config.fetcher, config)
-  }) as unknown) as SWRType
+  }) as unknown as SWRType
 }