From 87b874ffe7dfe54fffdbe0df92623bc7ae6ab151 Mon Sep 17 00:00:00 2001 From: Angelico Date: Mon, 6 Jan 2020 14:22:12 +0800 Subject: [PATCH] Refinement of Documentation The following were done: - Begin writing documentation under subscribe.mdx (WIP) - Refine documentation for get.mdx, patch.mdx and delete.mdx to match the standard of post.mdx --- web/docs/library/delete.mdx | 24 +++-- web/docs/library/get.mdx | 49 ++++++--- web/docs/library/patch.mdx | 23 ++++- web/docs/library/post.mdx | 4 +- web/docs/library/subscribe.mdx | 181 +++++++++++++++++++++++++++++---- 5 files changed, 230 insertions(+), 51 deletions(-) diff --git a/web/docs/library/delete.mdx b/web/docs/library/delete.mdx index d5ab1e64a18..43114431dfd 100644 --- a/web/docs/library/delete.mdx +++ b/web/docs/library/delete.mdx @@ -60,15 +60,19 @@ They can be found [here](../library/filters). ### Mass delete Updating employeeCount for all companies. ```js -supabase.delete("companies") +const deleteCompanies = async () => { + try{ + let company = await supabase.delete("companies") + return company + } catch (error) { + console.log("Error: ", error) + } +} ``` -Upon a successful deletion, the status code `204 Accepted` will be returned. - -```js -supabase.get("companies") -``` -When getting all companies again, as shown above, the following will be returned with the status code `200 OK`: +Upon a successful deletion, the status code `204 Accepted` will be returned. +When getting all companies again, as shown [by this example](../library/get#generic), +the following will be returned with the status code `200 OK`: ```json [] ``` @@ -80,10 +84,8 @@ supabase.delete("companies").eq("name", "See Food App") ``` Upon a successful deletion, the status code `204 Accepted` will be returned. -```js -supabase.get("companies") -``` -When getting all companies again, as shown above, the following will be returned with the status code `200 OK`: +When getting all companies again, as shown [by this example](../library/get#generic), +the following will be returned with the status code `200 OK`: ```json [ { "Id": 1, "name": "Pied Piper", "employeeCount": 10 }, diff --git a/web/docs/library/get.mdx b/web/docs/library/get.mdx index b755beb686d..c52950069e5 100644 --- a/web/docs/library/get.mdx +++ b/web/docs/library/get.mdx @@ -91,7 +91,7 @@ Instead of stating the column name with the foreign key constraint, the name of along with the desired column names from that table. ##### Example -Click [here](../library/get#using-select) view some examples. +Click [here](../library/get#using-select) to view some examples. ### Common Filters @@ -101,8 +101,15 @@ Other common filters can be found [here](../library/filters). ### Generic Get all companies and return all columns available -```js -supabase.get("companies") +```js {3} +const getCompanies = async () => { + try { + let companies = await supabase.get("companies") + return companies + } catch (error) { + console.log("Error: ", error) + } +} ``` The following will be returned with status code `200 OK`: ```json @@ -116,8 +123,15 @@ The following will be returned with status code `200 OK`: ### Using Select Get all users but only return the column fullName. -```js -supabase.get("users").select(`fullName`) +```js {3} +const getUsers = async () => { + try { + let users = await supabase.get("users").select("fullName") + return users + } catch (error) { + console.log("Error: ", error) + } +} ``` The following will be returned with the status code `200 OK`: ```json @@ -130,15 +144,22 @@ The following will be returned with the status code `200 OK`: ### Using Select with Foreign Key Constraints Get all users and return all information about them and the companies they belong to. -```js -supabase.get("users") - .select(` - fullName, - companies { - name, - employeeCount - } - `) +```js {3-10} +const getUsers = async () => { + try { + let users = await supabase.get("users") + .select(` + fullName, + companies { + name, + employeeCount + } + `) + return users + } catch (error) { + console.log("Error: ", error) + } +} ``` The following will be returned with the status code `200 OK`: ```json diff --git a/web/docs/library/patch.mdx b/web/docs/library/patch.mdx index 528447cd24f..d27efd1fbc5 100644 --- a/web/docs/library/patch.mdx +++ b/web/docs/library/patch.mdx @@ -91,7 +91,16 @@ They can be found [here](../library/filters). ### Mass update Updating employeeCount for all companies. -```js +```js {3} +const updateCompanies = async () => { + try{ + let companies = await supabse.patch("companies", { employeeCount: 50 }) + return companies + } catch (error) { + console.log("Error: ", error) + } +} + supabase.patch("companies", { employeeCount: 50 }) ``` @@ -107,8 +116,16 @@ The following will be returned with the status code `200 OK`: ### Using filters Updating employeeCount for companies where its columnName "name" is equal to "See Food App". -```js -supabase.patch("companies", { employeeCount: 50 }).eq("name", "See Food App") +```js {3-4} +const updateCompany = async () => { + try{ + let company = await supabase.patch("companies", {employeeCount: 25 }) + .eq("name", "See Food App") + return company + } catch (error) { + console.log("Error: ", error) + } +} ``` The following will be returned with the status code `200 OK`: diff --git a/web/docs/library/post.mdx b/web/docs/library/post.mdx index 59a5aba3af4..2ce8c0db5a3 100644 --- a/web/docs/library/post.mdx +++ b/web/docs/library/post.mdx @@ -56,7 +56,7 @@ All available options and examples it their usage can be found [here](../library }> -```js {6-8} +```js {4-9} const postUsers = async () => { try { let users = await supabase @@ -93,7 +93,7 @@ const postUsers = async () => { }> -```js {6-9} +```js {4-10} const postUsers = async () => { try { let users = await supabase diff --git a/web/docs/library/subscribe.mdx b/web/docs/library/subscribe.mdx index 1d81ea5b0b8..ddc733c3b9c 100644 --- a/web/docs/library/subscribe.mdx +++ b/web/docs/library/subscribe.mdx @@ -1,39 +1,178 @@ --- id: subscribe -title: "Subscribe to Realtime Changes" +title: "Subscribe to Realtime" --- -Our library makes it simple to listen to changes in your database. +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -## The basics +Our library makes it simple to listen to changes in your database in realtime. + +We will be using these tables as reference for our examples: +```json +{ + "companies": [ + { "Id": 1, "name": "Pied Piper", "employeeCount": 10 }, + { "Id": 2, "name": "Hooli", "employeeCount": 1000 }, + { "Id": 3, "name": "Yao Net", "employeeCount": 100 }, + { "Id": 4, "name": "See Food App", "employeeCount": null } + ], +} +``` + + + ```js -import { createClient } from "@supabase/supabase-js"; +supabase.subscribe(channel) -// Connect to Supabase -const base = createClient(process.env.SUPABASE_URL, { - apikey: process.env.SUPABASE_KEY -}); - -// Subscribe to realtime updates -const todoListener = base.subscribe("todos").on("INSERT", todo => { - console.log("New todo!", todo); -}) ``` +Supabase subscribes to a specified `channel` to listen to. + + + + +```py +# TODO +``` + + + +## Method arguments +### channel +`required` string +Channel for Supabase to listen to. The channel can either subscribe to the pre-determined schema (`public` by default) +or a specific table within that schema. Indicating `"*"` will subscribe the channel to the pre-determined schema. + +## Hooks + +```js +on(event, callback) +``` +Call a specified `callback` function once a specified event occurs. + +### Method arguments +#### event +`required` string +The event to hook will listen for. This could either be: +- CREATE +- UPDATE +- DELETE + +Alternatively, indicating `"*"` will let the hook listen for everything. + +#### callback +`required` function +A function that will be called when an event that the hook is subscribed to occurs. ## Examples -@todo +### Listening to the entire schema +```js +supabase.subscribe("*") +``` -## Options +### Listening to a specific table +```js +supabase.subscribe("companies") +``` -| Parameter | Default | Description | -| --------- | ------- | ------------------------------------------- | -| @todo | | All options | +### Adding hooks +```js +supabase.subscribe("companies").on("INSERT", company => { + console.log("New company: ", company) +}) +``` -## Returns +## Responses -#### 200: Success +### CREATE +```js +const postCompany = async () => { + try { + let company = await supabase + .post( + "companies", + [ + { name: "Galloo Games", employeeCount: 25 } + ], + ) + return company + } catch (error) { + console.log('Error: ', error) + } +} +``` +... will be returned by our listener: + +```json +{ + "new": [ + { "name": "Galloo Games", "employeeCount": 25 } + ] +} +``` + +### UPDATE +```js +const updateCompany = async () => { + try { + let company = await supabase + .patch( + "companies", + [ + { employeeCount: 75 } + ] + ) + .eq("name", "See Food App") + return company + } catch (error) { + console.log('Error: ', error) + } +} +``` + +... insert description here + +```json +{ + "old": [ + { "name": "See Food App", "employeeCount": null } + ], + "new": [ + { "name": "See Food App", "employeeCount": 75 } + ] +} +``` + +### DELETE +```js +const deleteCompany = async () => { + try { + let company = await supabase + .delete("companies",) + .eq("name", "Hooli") + return company + } catch (error) { + console.log('Error: ', error) + } +} +``` + +... insert description here + +```json +{ + "old": [ + { "name": "Hooli", "employeeCount": 1000 } + ] +} +``` -@todo: all return scenarios