From d2698d22ea779a8e247908ca1be6833aa4fe161b Mon Sep 17 00:00:00 2001 From: Paul Copplestone Date: Thu, 9 Jan 2020 17:44:28 +0800 Subject: [PATCH] Docs reviewed with Ant. One change remains: we should be putting the REST verbs at the end of the chain for readability. --- .../src/{BaseChannel.js => Subscription.js} | 1 + libraries/supabase-js/src/index.js | 4 +- web/docs/common/CommonFilters.mdx | 44 +++--- web/docs/library/delete.mdx | 15 +- web/docs/library/get.mdx | 2 +- web/docs/library/getting-started.mdx | 4 +- web/docs/library/patch.mdx | 9 +- web/docs/library/post.mdx | 2 +- web/docs/library/subscribe.mdx | 138 +++++++++++++----- web/src/css/custom.css | 4 +- 10 files changed, 150 insertions(+), 73 deletions(-) rename libraries/supabase-js/src/{BaseChannel.js => Subscription.js} (97%) diff --git a/libraries/supabase-js/src/BaseChannel.js b/libraries/supabase-js/src/Subscription.js similarity index 97% rename from libraries/supabase-js/src/BaseChannel.js rename to libraries/supabase-js/src/Subscription.js index f2862a4004..94f232056f 100644 --- a/libraries/supabase-js/src/BaseChannel.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() diff --git a/libraries/supabase-js/src/index.js b/libraries/supabase-js/src/index.js index 82c896488b..b41eb0e45a 100644 --- 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] } diff --git a/web/docs/common/CommonFilters.mdx b/web/docs/common/CommonFilters.mdx index 6415d62b18..1a62ce3c46 100644 --- a/web/docs/common/CommonFilters.mdx +++ b/web/docs/common/CommonFilters.mdx @@ -18,7 +18,7 @@ supabase ```js {3} supabase - .patch(tableName) + .patch(tableName, data) .match(filterObject) ``` @@ -53,7 +53,7 @@ supabase ```js supabase - .patch('countries') + .patch('countries', { name: 'Middle Earth' }) .match({ 'continent': 'Asia' }) ``` @@ -94,7 +94,7 @@ supabase ```js {3} supabase - .patch(tableName) + .patch(tableName, data) .eq(columnName, filterValue) ``` @@ -129,7 +129,7 @@ supabase ```js supabase - .patch('countries') + .patch('countries', { name: 'Middle Earth' }) .eq('name', 'New Zealand') ``` @@ -172,7 +172,7 @@ supabase ```js {3} supabase - .patch(tableName) + .patch(tableName, data) .gt(columnName, filterValue) ``` @@ -207,7 +207,7 @@ supabase ```js supabase - .patch('countries') + .patch('countries', { name: 'Middle Earth' }) .gt('id', 20) ``` @@ -251,7 +251,7 @@ supabase ```js {3} supabase - .patch(tableName) + .patch(tableName, data) .lt(columnName, filterValue) ``` @@ -286,7 +286,7 @@ supabase ```js supabase - .patch('countries') + .patch('countries', { name: 'Middle Earth' }) .lt('id', 20) ``` @@ -329,7 +329,7 @@ supabase ```js {3} supabase - .patch(tableName) + .patch(tableName, data) .gte(columnName, filterValue) ``` @@ -364,7 +364,7 @@ supabase ```js supabase - .patch('countries') + .patch('countries', { name: 'Middle Earth' }) .gte('id', 20) ``` @@ -407,7 +407,7 @@ supabase ```js {3} supabase - .patch(tableName) + .patch(tableName, data) .lte(columnName, filterValue) ``` @@ -442,7 +442,7 @@ supabase ```js supabase - .patch('countries') + .patch('countries', { name: 'Middle Earth' }) .gte('id', 20) ``` @@ -485,7 +485,7 @@ supabase ```js {3} supabase - .patch(tableName) + .patch(tableName, data) .like(columnName, stringPattern) ``` @@ -520,7 +520,7 @@ supabase ```js supabase - .patch('countries') + .patch('countries', { name: 'Middle Earth' }) .like('name', '%United%') ``` @@ -565,7 +565,7 @@ supabase ```js {3} supabase - .patch(tableName) + .patch(tableName, data) .ilike(columnName, stringPattern) ``` @@ -600,7 +600,7 @@ supabase ```js supabase - .patch('countries') + .patch('countries', { name: 'Middle Earth' }) .ilike('name', '%united%') ``` @@ -645,7 +645,7 @@ supabase ```js {3} supabase - .patch(tableName) + .patch(tableName, data) .is(columnName, stringPattern) ``` @@ -680,7 +680,7 @@ supabase ```js supabase - .patch('countries') + .patch('countries', { name: 'Middle Earth' }) .is('name', null) ``` @@ -724,7 +724,7 @@ supabase ```js {3} supabase - .patch(tableName) + .patch(tableName, data) .in(columnName, filterArray) ``` @@ -759,7 +759,7 @@ supabase ```js supabase - .patch('countries') + .patch('countries', { name: 'Middle Earth' }) .in('name', ['China', 'France']) ``` @@ -803,7 +803,7 @@ supabase ```js {3} supabase - .patch(tableName) + .patch(tableName, data) .not(columnName, filterValue) ``` @@ -838,7 +838,7 @@ supabase ```js supabase - .patch('countries') + .patch('countries', { name: 'Middle Earth' }) .not('name', 'China') ``` diff --git a/web/docs/library/delete.mdx b/web/docs/library/delete.mdx index a7f35c91e3..a08a6c2e71 100644 --- 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: -```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. +} +``` ---- diff --git a/web/docs/library/get.mdx b/web/docs/library/get.mdx index d7b88116ba..099a2be09a 100644 --- 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' diff --git a/web/docs/library/getting-started.mdx b/web/docs/library/getting-started.mdx index bdf050b2ae..99434351b9 100755 --- 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 diff --git a/web/docs/library/patch.mdx b/web/docs/library/patch.mdx index d3586f2f99..e230304012 100644 --- 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. +} +``` ---- diff --git a/web/docs/library/post.mdx b/web/docs/library/post.mdx index f44e0a8dec..fa07c944ac 100644 --- a/web/docs/library/post.mdx +++ b/web/docs/library/post.mdx @@ -1,6 +1,6 @@ --- id: post -title: 'Creating data' +title: 'Creating' --- diff --git a/web/docs/library/subscribe.mdx b/web/docs/library/subscribe.mdx index bd6f7ed61b..c2f1a57e38 100644 --- 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) ```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()` - - -```js {3} -supabase - .subscribe('tableName') - .join() -``` - - ---- ### `on()` -```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()` + + +```js {4} +const mySubscription = supabase + .subscribe('tableName') + .on('eventType', callbackFunction) + .connect() +``` +Start listening to database changes. + +---- + +### `disconnect()` + + +```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()` ```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()` + + +```js {2} +supabase + .getSubscriptions() +``` +Returns an array of all your subscriptions (including disconnected subscriptions). + + + + + +```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, + } + } +] +``` + + + + + +---- + + ## 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" } ] diff --git a/web/src/css/custom.css b/web/src/css/custom.css index 6b5483b072..9a1848e62b 100755 --- 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;