Docs reviewed with Ant. One change remains: we should be putting the REST verbs at the end of the chain for readability.

2020-01-09 17:44:28 +08:00
parent f3ee93fd45
commit d2698d22ea
10 changed files with 150 additions and 73 deletions
--- a/libraries/supabase-js/src/Subscription.js
+++ b/libraries/supabase-js/src/Subscription.js
@@ -4,6 +4,7 @@ export default class BaseChannel {
    constructor(tableName, apiSocket, uuid){
        this.socket = new Socket(apiSocket)
        this.uuid = uuid
+        this.tableName = tableName
        this.channel = this.socket.channel(tableName)

        this.start()
--- a/libraries/supabase-js/src/index.js
+++ b/libraries/supabase-js/src/index.js
@@ -1,5 +1,5 @@
 import BaseRequest from './BaseRequest'
-import BaseChannel from './BaseChannel'
+import Subscription from './Subscription'
 import { uuid } from './utils/Helpers'

 class SupabaseClient {
@@ -20,7 +20,7 @@ class SupabaseClient {
  subscribe(tableName) {
    let uuid = uuid()

-    this.subscriptions[uuid] = new BaseChannel(tableName, this.apiSocket, uuid)
+    this.subscriptions[uuid] = new Subscription(tableName, this.apiSocket, uuid)
    return this.subscriptions[uuid]
  }

--- a/web/docs/common/CommonFilters.mdx
+++ b/web/docs/common/CommonFilters.mdx
@@ -18,7 +18,7 @@ supabase
 <!-- prettier-ignore -->
 ```js {3} 
 supabase
-  .patch(tableName)
+  .patch(tableName, data)
  .match(filterObject)
 ```

@@ -53,7 +53,7 @@ supabase
 <!-- prettier-ignore -->
 ```js
 supabase
-  .patch('countries')
+  .patch('countries', { name: 'Middle Earth' })
  .match({ 'continent': 'Asia' })
 ```

@@ -94,7 +94,7 @@ supabase
 <!-- prettier-ignore -->
 ```js {3}
 supabase
-  .patch(tableName)
+  .patch(tableName, data)
  .eq(columnName, filterValue)
 ```

@@ -129,7 +129,7 @@ supabase
 <!-- prettier-ignore -->
 ```js
 supabase
-  .patch('countries')
+  .patch('countries', { name: 'Middle Earth' })
  .eq('name', 'New Zealand')
 ```

@@ -172,7 +172,7 @@ supabase
 <!-- prettier-ignore -->
 ```js {3}
 supabase
-  .patch(tableName)
+  .patch(tableName, data)
  .gt(columnName, filterValue)
 ```

@@ -207,7 +207,7 @@ supabase
 <!-- prettier-ignore -->
 ```js
 supabase
-  .patch('countries')
+  .patch('countries', { name: 'Middle Earth' })
  .gt('id', 20)
 ```

@@ -251,7 +251,7 @@ supabase
 <!-- prettier-ignore -->
 ```js {3}
 supabase
-  .patch(tableName)
+  .patch(tableName, data)
  .lt(columnName, filterValue)
 ```

@@ -286,7 +286,7 @@ supabase
 <!-- prettier-ignore -->
 ```js
 supabase
-  .patch('countries')
+  .patch('countries', { name: 'Middle Earth' })
  .lt('id', 20)
 ```

@@ -329,7 +329,7 @@ supabase
 <!-- prettier-ignore -->
 ```js {3}
 supabase
-  .patch(tableName)
+  .patch(tableName, data)
  .gte(columnName, filterValue)
 ```

@@ -364,7 +364,7 @@ supabase
 <!-- prettier-ignore -->
 ```js
 supabase
-  .patch('countries')
+  .patch('countries', { name: 'Middle Earth' })
  .gte('id', 20)
 ```

@@ -407,7 +407,7 @@ supabase
 <!-- prettier-ignore -->
 ```js {3}
 supabase
-  .patch(tableName)
+  .patch(tableName, data)
  .lte(columnName, filterValue)
 ```

@@ -442,7 +442,7 @@ supabase
 <!-- prettier-ignore -->
 ```js
 supabase
-  .patch('countries')
+  .patch('countries', { name: 'Middle Earth' })
  .gte('id', 20)
 ```

@@ -485,7 +485,7 @@ supabase
 <!-- prettier-ignore -->
 ```js {3}
 supabase
-  .patch(tableName)
+  .patch(tableName, data)
  .like(columnName, stringPattern)
 ```

@@ -520,7 +520,7 @@ supabase
 <!-- prettier-ignore -->
 ```js
 supabase
-  .patch('countries')
+  .patch('countries', { name: 'Middle Earth' })
  .like('name', '%United%')
 ```

@@ -565,7 +565,7 @@ supabase
 <!-- prettier-ignore -->
 ```js {3}
 supabase
-  .patch(tableName)
+  .patch(tableName, data)
  .ilike(columnName, stringPattern)
 ```

@@ -600,7 +600,7 @@ supabase
 <!-- prettier-ignore -->
 ```js
 supabase
-  .patch('countries')
+  .patch('countries', { name: 'Middle Earth' })
  .ilike('name', '%united%')
 ```

@@ -645,7 +645,7 @@ supabase
 <!-- prettier-ignore -->
 ```js {3}
 supabase
-  .patch(tableName)
+  .patch(tableName, data)
  .is(columnName, stringPattern)
 ```

@@ -680,7 +680,7 @@ supabase
 <!-- prettier-ignore -->
 ```js
 supabase
-  .patch('countries')
+  .patch('countries', { name: 'Middle Earth' })
  .is('name', null)
 ```

@@ -724,7 +724,7 @@ supabase
 <!-- prettier-ignore -->
 ```js {3}
 supabase
-  .patch(tableName)
+  .patch(tableName, data)
  .in(columnName, filterArray)
 ```

@@ -759,7 +759,7 @@ supabase
 <!-- prettier-ignore -->
 ```js
 supabase
-  .patch('countries')
+  .patch('countries', { name: 'Middle Earth' })
  .in('name', ['China', 'France'])
 ```

@@ -803,7 +803,7 @@ supabase
 <!-- prettier-ignore -->
 ```js {3}
 supabase
-  .patch(tableName)
+  .patch(tableName, data)
  .not(columnName, filterValue)
 ```

@@ -838,7 +838,7 @@ supabase
 <!-- prettier-ignore -->
 ```js
 supabase
-  .patch('countries')
+  .patch('countries', { name: 'Middle Earth' })
  .not('name', 'China')
 ```

--- a/web/docs/library/delete.mdx
+++ b/web/docs/library/delete.mdx
@@ -1,6 +1,6 @@
 ---
 id: delete
-title: 'Deleting your data'
+title: 'Deleting'
 ---


@@ -21,7 +21,7 @@ We will be using these tables as reference for our examples:
 This example how to delete a city:

 <!-- prettier-ignore -->
-```js {8-10}
+```js {8-9}
 import { createClient } from '@supabase/supabase-js'

 const supabase = createClient('https://world.supabase.io', '1a2b-3c4d-5e6f-7g8h')
@@ -29,8 +29,8 @@ const supabase = createClient('https://world.supabase.io', '1a2b-3c4d-5e6f-7g8h'
 const updateCountryName = async () => {
  try {
    let values = await supabase
-      .delete('cities', { name: 'Mordor' })
      .match({ id: 666 })
+      .delete('cities', { name: 'Mordor' })

    return values
  } catch (error) {
@@ -52,14 +52,19 @@ const updateCountryName = async () => {
 ### `delete()`
 ```js
 supabase
-  .post(tableName, options?)
+  .delete(tableName, options?)
 ```

 ##### tableName `:string`  
 Name of table in the database with the data that should be deleted.

 ##### options `:object?`   
-@todo
+
+```js
+const options = {
+  bulk: false // Protects against bulk updates. Set to true if you intend to perform a bulk change.
+}
+```

 ----

--- a/web/docs/library/get.mdx
+++ b/web/docs/library/get.mdx
@@ -1,6 +1,6 @@
 ---
 id: get
-title: 'Reading your data'
+title: 'Reading'
 ---

 import Tabs from '@theme/Tabs'
--- a/web/docs/library/getting-started.mdx
+++ b/web/docs/library/getting-started.mdx
@@ -33,10 +33,10 @@ createClient('supabaseURL', 'supabaseKey', OPTIONS)
 ```

 ###### supabaseURL `:string` 
-Your unique Supabase URL.
+The unique Supabase URL which is supplied when you create a new project in [your project Dashboard](https://app.supabase.io).

 ###### supabaseKey `:string`
-Your unique Supabase Key.
+The unique Supabase Key which is supplied when you create a new project in [your project Dashboard](https://app.supabase.io).

 ###### OPTIONS `:object?`
@todo
--- a/web/docs/library/patch.mdx
+++ b/web/docs/library/patch.mdx
@@ -1,6 +1,6 @@
 ---
 id: patch
-title: 'Updating your data'
+title: 'Updating'
 ---


@@ -63,7 +63,12 @@ New record values.


 ##### options `:object?`   
-@todo
+
+```js
+const options = {
+  bulk: false // Protects against bulk updates. Set to true if you intend to perform a bulk change.
+}
+```

 ----

--- a/web/docs/library/post.mdx
+++ b/web/docs/library/post.mdx
@@ -1,6 +1,6 @@
 ---
 id: post
-title: 'Creating data'
+title: 'Creating'
 ---


--- a/web/docs/library/subscribe.mdx
+++ b/web/docs/library/subscribe.mdx
@@ -1,11 +1,12 @@
 ---
 id: subscribe
-title: 'Listen for realtime changes'
+title: 'Subscribing'
 ---

 import DummyData from '../common/DummyData.mdx'
+import Collapsable from '../../src/components/Collapsable'

-Our library makes it simple to listen to changes in your database in realtime.
+Subscribe to realtime changes in your own database.

 We will be using these tables as reference for our examples.

@@ -21,12 +22,12 @@ import { createClient } from '@supabase/supabase-js'
 const supabase = createClient('https://world.supabase.io', '1a2b-3c4d-5e6f-7g8h')

 // Listen to changes
-const listener = supabase
+const mySubscription = supabase
  .subscribe('*')
  .on('*', payload => {
    console.log('Change received!', payload)
  })
-  .join()
+  .connect()
 ```

 ### Listening to a specific table
@@ -39,12 +40,12 @@ import { createClient } from '@supabase/supabase-js'
 const supabase = createClient('https://world.supabase.io', '1a2b-3c4d-5e6f-7g8h')

 // Listen to changes
-const listener = supabase
+const mySubscription = supabase
  .subscribe('countries')
  .on('*', payload => {
    console.log('Change received!', payload)
  })
-  .join()
+  .connect()
 ```

 ### Listening only to INSERTS
@@ -57,12 +58,12 @@ import { createClient } from '@supabase/supabase-js'
 const supabase = createClient('https://world.supabase.io', '1a2b-3c4d-5e6f-7g8h')

 // Listen to changes
-const listener = supabase
+const mySubscription = supabase
  .subscribe('countries')
  .on('INSERT', payload => {
    console.log('Change received!', payload)
  })
-  .join()
+  .connect()
 ```

 ### Listening only to UPDATES
@@ -75,12 +76,12 @@ import { createClient } from '@supabase/supabase-js'
 const supabase = createClient('https://world.supabase.io', '1a2b-3c4d-5e6f-7g8h')

 // Listen to changes
-const listener = supabase
+const mySubscription = supabase
  .subscribe('countries')
  .on('UPDATE', payload => {
    console.log('Change received!', payload)
  })
-  .join()
+  .connect()
 ```

 ### Listening only to DELETES
@@ -93,12 +94,12 @@ import { createClient } from '@supabase/supabase-js'
 const supabase = createClient('https://world.supabase.io', '1a2b-3c4d-5e6f-7g8h')

 // Listen to changes
-const listener = supabase
+const mySubscription = supabase
  .subscribe('countries')
  .on('DELETE', payload => {
    console.log('Change received!', payload)
  })
-  .join()
+  .connect()
 ```

 ### Listening to multiple events
@@ -111,11 +112,11 @@ import { createClient } from '@supabase/supabase-js'
 const supabase = createClient('https://world.supabase.io', '1a2b-3c4d-5e6f-7g8h')

 // Listen to changes
-const listener = supabase
+const mySubscription = supabase
  .subscribe('countries')
  .on('INSERT', handleRecordInserted)
  .on('DELETE', handleRecordDeleted)
-  .join()
+  .connect()
 ```

 ### Unsubscribing
@@ -128,10 +129,10 @@ import { createClient } from '@supabase/supabase-js'
 const supabase = createClient('https://world.supabase.io', '1a2b-3c4d-5e6f-7g8h')

 // Listen to changes
-const myListener = supabase.subscribe('countries')
+const mySubscription = supabase.subscribe('countries')

 // Unsubscribe from changes
-supabase.unsubscribe(myListener)
+supabase.unsubscribe(mySubscription)
 ```


@@ -143,7 +144,7 @@ supabase.unsubscribe(myListener)

 <!-- prettier-ignore -->
 ```js {2}
-supabase
+const mySubscription = supabase
  .subscribe('tableName')
 ```

@@ -151,27 +152,14 @@ supabase
 The database table that you want to subscribe to. Using the wildcard `"*"` will listen all tables in your database.


----
-
-### `join()`
-
-<!-- prettier-ignore -->
-```js {3}
-supabase
-  .subscribe('tableName')
-  .join()
-```
-
-
 ----

 ### `on()`

 <!-- prettier-ignore -->
-```js {4}
-supabase
+```js {3}
+const mySubscription = supabase
  .subscribe('tableName')
-  .join()
  .on('eventType', callbackFunction)
 ```

@@ -185,20 +173,95 @@ A callback that will handle the payload that is sent whenever your database chan
 ----


+### `connect()`
+
+<!-- prettier-ignore -->
+```js {4}
+const mySubscription = supabase
+  .subscribe('tableName')
+  .on('eventType', callbackFunction)
+  .connect()
+```
+Start listening to database changes.
+
+----
+
+### `disconnect()`
+
+<!-- prettier-ignore -->
+```js {2}
+mySubscription
+  .disconnect()
+```
+Stop listening to changes. At any point you can call `connect()` on the subscription to restart the listeners. 
+If you don't need to connect again in the future, use `unsubscribe()` instead.
+
+----
+
+
 ### `unsubscribe()`

 <!-- prettier-ignore -->
 ```js {2}
 supabase
-  .unsubscribe(yourSubscription)
+  .unsubscribe(mySubscription)
 ```

-###### yourSubscription `:subscription`  
-A listener that was previously created.
+Disconnects and destroys a subscription. This is the preferred method for cleaning up subscriptions which you no longer require. 
+
+###### mySubscription `:subscription`  
+A subscription that was previously created. If you don't have access to the subscription, you can always call `getSubscriptions()`.


 ----

+### `getSubscriptions()`
+
+<!-- prettier-ignore -->
+```js {2}
+supabase
+  .getSubscriptions()
+```
+Returns an array of all your subscriptions (including disconnected subscriptions).
+
+
+<Collapsable title="Toggle Example Response">
+
+<!-- prettier-ignore -->
+```js
+[
+  {
+    uuid: 'xxxx-xxxx-xxxx-xxxx',
+    state: 'CONNECTED',
+    tableName: 'users',
+    eventListeners: {
+      '*': null,
+      'INSERT': null,
+      'UPDATE': null,
+      'DELETE': null,
+    }
+  },
+  {
+    uuid: 'yyyy-yyyy-yyyy-yyyy',
+    state: 'DISCONNECTED',
+    tableName: 'messages',
+    eventListeners: {
+      '*': null,
+      'INSERT': null,
+      'UPDATE': null,
+      'DELETE': null,
+    }
+  }
+]
+```
+
+
+</Collapsable>
+
+
+----
+
+
 ## Change Events

@TODO what happens on bulk insert/update/delete?
@@ -209,6 +272,7 @@ Upon inserting or creating a new row, the following will be returned by our list

 ```json
 {
+  "eventType": "INSERT",
  "new": [
    { "name": "Middle Earth", "country_id": "554" }
  ]
@@ -219,9 +283,10 @@ Upon inserting or creating a new row, the following will be returned by our list


 Upon updating a row, the following will be returned by our listener:
-
+`
 ```json
 {
+  "eventType": "UPDATE",
  "old": [
    { "name": "Middle Earth", "country_id": "554" }
  ],
@@ -238,6 +303,7 @@ Upon deleting a row, the following will be returned by our listener:

 ```json
 {
+  "eventType": "DELETE",
  "old": [
    { "name": "Mordor", "country_id": "554" }
  ]
--- a/web/src/css/custom.css
+++ b/web/src/css/custom.css
@@ -459,8 +459,8 @@ div[class^='sidebar_'] .menu__link.menu__link--active:not(.menu__link--sublist)
  display: flex;
  overflow-x: auto;
 }
-.DummyData  div{
-  padding-right: 10px;
+.DummyData div {
+  padding-right: 30px;
 }
 .Collapsable summary {
  font-size: 0.9rem;