Add useUpsert hook (#6)

Author: kachar

docs/pages/documentation/data/meta.json

@@ -3,5 +3,6 @@
     "use-filter": "useFilter",
     "use-insert": "useInsert",
     "use-select": "useSelect",
-    "use-update": "useUpdate"
+    "use-update": "useUpdate",
+    "use-upsert": "useUpsert"
 }

docs/pages/documentation/data/use-upsert.md

@@ -0,0 +1,58 @@
+# useUpsert
+
+Performs `INSERT` or `UPDATE` on table.
+
+```js highlight=4
+import { useUpsert } from 'react-supabase'
+
+function Page() {
+  const [{ count, data, error, fetching }, execute] = useUpsert('users')
+
+  async function onClickMarkAllComplete() {
+    const { count, data, error } = await execute(
+      { completed: true },
+      { onConflict: 'username' },
+      (query) => query.eq('completed', false),
+    )
+  }
+
+  return ...
+}
+```
+
+## Notes
+
+- By specifying the `onConflict` option, you can make `UPSERT` work on a column(s) that has a `UNIQUE` constraint.
+- Primary keys should to be included in the data payload in order for an update to work correctly.
+- Primary keys must be natural, not surrogate. There are however, workarounds for surrogate primary keys.
+- Param `filter` makes sense only when operation is update
+- Upsert supports sending array of elements, just like `useInsert`
+
+## Passing options
+
+During hook initialization:
+
+```js
+const [{ count, data, error, fetching }, execute] = useUpsert('users', {
+  filter: (query) => query.eq('completed', false),
+  options: {
+    returning: 'represenation',
+    onConflict: 'username',
+    count: 'exact',
+  },
+})
+```
+
+Or execute function:
+
+```js
+const { count, data, error } = await execute(
+  { completed: true },
+  {
+    count: 'estimated',
+    onConflict: 'username',
+    returning: 'minimal',
+  },
+  (query) => query.eq('completed', false),
+)
+```

src/hooks/data/index.ts

@@ -3,3 +3,4 @@ export * from './use-filter'
 export * from './use-insert'
 export * from './use-select'
 export * from './use-update'
+export * from './use-upsert'

src/hooks/data/use-upsert.ts

@@ -0,0 +1,75 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import { Count, Filter, PostgrestError, Returning } from '../../types'
+import { useClient } from '../use-client'
+import { initialState } from './state'
+
+export type UseUpsertState<Data = any> = {
+    count?: number | null
+    data?: Data | Data[] | null
+    error?: PostgrestError | null
+    fetching: boolean
+}
+
+export type UseUpsertResponse<Data = any> = [
+    UseUpsertState<Data>,
+    (
+        values: Partial<Data> | Partial<Data>[],
+        options?: UseUpsertOptions,
+        filter?: Filter<Data>,
+    ) => Promise<Pick<UseUpsertState<Data>, 'count' | 'data' | 'error'>>,
+]
+
+export type UseUpsertOptions = {
+    count?: null | Count
+    onConflict?: string
+    returning?: Returning
+}
+
+export type UseUpsertConfig<Data = any> = {
+    filter?: Filter<Data>
+    options?: UseUpsertOptions
+}
+
+export function useUpsert<Data = any>(
+    table: string,
+    config: UseUpsertConfig<Data> = { options: {} },
+): UseUpsertResponse<Data> {
+    const client = useClient()
+    const isMounted = useRef(false)
+    const [state, setState] = useState<UseUpsertState>(initialState)
+
+    /* eslint-disable react-hooks/exhaustive-deps */
+    const execute = useCallback(
+        async (
+            values: Partial<Data> | Partial<Data>[],
+            options?: UseUpsertOptions,
+            filter?: Filter<Data>,
+        ) => {
+            const refine = filter ?? config.filter
+            setState({ ...initialState, fetching: true })
+            const source = client
+                .from<Data>(table)
+                .upsert(values, options ?? config.options)
+
+            const { count, data, error } = await (refine
+                ? refine(source)
+                : source)
+
+            const res = { count, data, error }
+            if (isMounted.current) setState({ ...res, fetching: false })
+            return res
+        },
+        [client],
+    )
+    /* eslint-enable react-hooks/exhaustive-deps */
+
+    useEffect(() => {
+        isMounted.current = true
+        return () => {
+            isMounted.current = false
+        }
+    }, [])
+
+    return [state, execute]
+}

test/hooks/data/__snapshots__/use-upsert.test.tsx.snap

@@ -0,0 +1,3 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`useUpsert should throw when not inside Provider 1`] = `"No client has been specified using Provider."`;

test/hooks/data/use-upsert.test.tsx

@@ -0,0 +1,10 @@
+import { renderHook } from '@testing-library/react-hooks'
+
+import { useUpsert } from '../../../src'
+
+describe('useUpsert', () => {
+    it('should throw when not inside Provider', () => {
+        const { result } = renderHook(() => useUpsert('todos'))
+        expect(() => result.current).toThrowErrorMatchingSnapshot()
+    })
+})