diff --git a/spec/common-client-libs-sections.json b/spec/common-client-libs-sections.json index 732d85b169b..517dad7a6fa 100644 --- a/spec/common-client-libs-sections.json +++ b/spec/common-client-libs-sections.json @@ -677,7 +677,7 @@ }, { "id": "subscribe", - "title": "Subscribe to database changes", + "title": "Subscribe to channel", "slug": "subscribe", "product": "realtime", "type": "function" diff --git a/spec/examples/examples.yml b/spec/examples/examples.yml index f1be15db868..c3689d3a111 100644 --- a/spec/examples/examples.yml +++ b/spec/examples/examples.yml @@ -5010,8 +5010,8 @@ functions: }) .subscribe() ``` - - id: listening-to-a-specific-table - name: Listening to a specific table + - id: listen-to-a-specific-table + name: Listen to a specific table js: | ```js supabase @@ -5021,8 +5021,8 @@ functions: }) .subscribe() ``` - - id: listening-to-inserts - name: Listening to inserts + - id: listen-to-inserts + name: Listen to inserts js: | ```js supabase @@ -5032,8 +5032,8 @@ functions: }) .subscribe() ``` - - id: listening-to-updates - name: Listening to updates + - id: listen-to-updates + name: Listen to updates description: | By default, Supabase will send only the updated record. If you want to receive the previous values as well you can enable full replication for the table you are listening to: @@ -5050,8 +5050,8 @@ functions: }) .subscribe() ``` - - id: listening-to-deletes - name: Listening to deletes + - id: listen-to-deletes + name: Listen to deletes description: | By default, Supabase does not send deleted records. If you want to receive the deleted record you can enable full replication for the table you are listening too: @@ -5068,8 +5068,8 @@ functions: }) .subscribe() ``` - - id: listening-to-multiple-events - name: Listening to multiple events + - id: listen-to-multiple-events + name: Listen to multiple events description: You can chain listeners if you want to listen to multiple events for each table. js: | ```js @@ -5080,7 +5080,7 @@ functions: .subscribe() ``` - id: listening-to-row-level-changes - name: Listening to row level changes + name: Listen to row level changes description: You can listen to individual rows using the format `{table}:{col}=eq.{val}` - where `{col}` is the column name, and `{val}` is the value which you want to match. notes: | - ``eq`` filter works with all database types as under the hood, it's casting both the filter value and the database value to the correct type and then comparing them. diff --git a/spec/supabase_dart_v0.yml b/spec/supabase_dart_v0.yml index e60394fc656..618e39f26af 100644 --- a/spec/supabase_dart_v0.yml +++ b/spec/supabase_dart_v0.yml @@ -700,8 +700,8 @@ functions: }) .subscribe(); ``` - - id: listening-to-a-specific-table - name: Listening to a specific table + - id: listen-to-a-specific-table + name: Listen to a specific table code: | ```dart final mySubscription = supabase @@ -711,8 +711,8 @@ functions: }) .subscribe(); ``` - - id: listening-to-inserts - name: Listening to inserts + - id: listen-to-inserts + name: Listen to inserts code: | ```dart final mySubscription = supabase @@ -722,8 +722,8 @@ functions: }) .subscribe(); ``` - - id: listening-to-updates - name: Listening to updates + - id: listen-to-updates + name: Listen to updates description: | By default, Supabase will send only the updated record. If you want to receive the previous values as well you can enable full replication for the table you are listening too: @@ -740,8 +740,8 @@ functions: }) .subscribe(); ``` - - id: listening-to-deletes - name: Listening to deletes + - id: listen-to-deletes + name: Listen to deletes description: | By default, Supabase does not send deleted records. If you want to receive the deleted record you can enable full replication for the table you are listening too: @@ -758,8 +758,8 @@ functions: }) .subscribe(); ``` - - id: listening-to-multiple-events - name: Listening to multiple events + - id: listen-to-multiple-events + name: Listen to multiple events description: You can chain listeners if you want to listen to multiple events for each table. code: | ```dart @@ -770,7 +770,7 @@ functions: .subscribe(); ``` - id: listening-to-row-level-changes - name: Listening to row level changes + name: Listen to row level changes description: You can listen to individual rows using the format `{table}:{col}=eq.{val}` - where `{col}` is the column name, and `{val}` is the value which you want to match. code: | ```dart @@ -816,8 +816,8 @@ functions: - `stream()` will emit the initial data as well as any further change on the database as `Stream` of `List>` by combining Postgrest and Realtime. - Takes a list of primary key columns as its argument. examples: - - id: listening-to-a-specific-table - name: Listening to a specific table + - id: listen-to-a-specific-table + name: Listen to a specific table isSpotlight: true code: | ```dart diff --git a/spec/supabase_dart_v1.yml b/spec/supabase_dart_v1.yml index 862f07e6b77..333147b6b49 100644 --- a/spec/supabase_dart_v1.yml +++ b/spec/supabase_dart_v1.yml @@ -696,8 +696,8 @@ functions: }, ).subscribe(); ``` - - id: listening-to-a-specific-table - name: Listening to a specific table + - id: listen-to-a-specific-table + name: Listen to a specific table code: | ```dart supabase.channel('public:countries').on( @@ -708,8 +708,8 @@ functions: }, ).subscribe(); ``` - - id: listening-to-inserts - name: Listening to inserts + - id: listen-to-inserts + name: Listen to inserts code: | ```dart supabase.channel('public:countries').on( @@ -720,8 +720,8 @@ functions: }, ).subscribe(); ``` - - id: listening-to-updates - name: Listening to updates + - id: listen-to-updates + name: Listen to updates description: | By default, Supabase will send only the updated record. If you want to receive the previous values as well you can enable full replication for the table you are listening too: @@ -739,8 +739,8 @@ functions: }, ).subscribe(); ``` - - id: listening-to-deletes - name: Listening to deletes + - id: listen-to-deletes + name: Listen to deletes description: | By default, Supabase does not send deleted records. If you want to receive the deleted record you can enable full replication for the table you are listening too: @@ -758,8 +758,8 @@ functions: }, ).subscribe(); ``` - - id: listening-to-multiple-events - name: Listening to multiple events + - id: listen-to-multiple-events + name: Listen to multiple events description: You can chain listeners if you want to listen to multiple events for each table. code: | ```dart @@ -774,7 +774,7 @@ functions: }).subscribe(); ``` - id: listening-to-row-level-changes - name: Listening to row level changes + name: Listen to row level changes description: You can listen to individual rows using the format `{table}:{col}=eq.{val}` - where `{col}` is the column name, and `{val}` is the value which you want to match. code: | ```dart @@ -841,8 +841,8 @@ functions: - `stream()` will emit the initial data as well as any further change on the database as `Stream` of `List>` by combining Postgrest and Realtime. - Takes a list of primary key columns as its argument. examples: - - id: listening-to-a-specific-table - name: Listening to a specific table + - id: listen-to-a-specific-table + name: Listen to a specific table isSpotlight: true code: | ```dart diff --git a/spec/supabase_js_v1.yml b/spec/supabase_js_v1.yml index 810e46d2036..546f9adeb9d 100644 --- a/spec/supabase_js_v1.yml +++ b/spec/supabase_js_v1.yml @@ -1138,8 +1138,8 @@ functions: }) .subscribe() ``` - - id: listening-to-a-specific-table - name: Listening to a specific table + - id: listen-to-a-specific-table + name: Listen to a specific table code: | ```js const mySubscription = supabase @@ -1149,8 +1149,8 @@ functions: }) .subscribe() ``` - - id: listening-to-inserts - name: Listening to inserts + - id: listen-to-inserts + name: Listen to inserts code: | ```js const mySubscription = supabase @@ -1160,8 +1160,8 @@ functions: }) .subscribe() ``` - - id: listening-to-updates - name: Listening to updates + - id: listen-to-updates + name: Listen to updates description: | By default, Supabase will send only the updated record. If you want to receive the previous values as well you can enable full replication for the table you are listening too: @@ -1178,8 +1178,8 @@ functions: }) .subscribe() ``` - - id: listening-to-deletes - name: Listening to deletes + - id: listen-to-deletes + name: Listen to deletes description: | By default, Supabase does not send deleted records. If you want to receive the deleted record you can enable full replication for the table you are listening too: @@ -1196,8 +1196,8 @@ functions: }) .subscribe() ``` - - id: listening-to-multiple-events - name: Listening to multiple events + - id: listen-to-multiple-events + name: Listen to multiple events description: You can chain listeners if you want to listen to multiple events for each table. code: | ```js @@ -1208,7 +1208,7 @@ functions: .subscribe() ``` - id: listening-to-row-level-changes - name: Listening to row level changes + name: Listen to row level changes description: You can listen to individual rows using the format `{table}:{col}=eq.{val}` - where `{col}` is the column name, and `{val}` is the value which you want to match. notes: | - ``eq`` filter works with all database types as under the hood, it's casting both the filter value and the database value to the correct type and then comparing them. diff --git a/spec/supabase_js_v2.yml b/spec/supabase_js_v2.yml index 0cd16c93dbd..425ad812fc4 100644 --- a/spec/supabase_js_v2.yml +++ b/spec/supabase_js_v2.yml @@ -3980,42 +3980,111 @@ functions: - When a delete occurs, the contents of old_record will be broadcast to all subscribers to that table so ensure that each table's replica identity only contains information that is safe to expose publicly. - The channel name must exactly match the schema/table/filter you want to listen to separated by colons. See below examples for additional context. examples: + - id: listen-to-broadcast + name: Listen to broadcast messages + isSpotlight: true + code: | + ```js + supabase + .channel('any') + .on('broadcast', { event: 'cursor-pos' }, payload => { + console.log('Cursor position received!', payload) + }) + .subscribe((status) => { + if (status === 'SUBSCRIBED') { + channel.send({ + type: 'broadcast', + event: 'cursor-pos', + payload: { x: Math.random(), y: Math.random() }, + }) + } + }) + ``` + - id: listen-to-presence-sync + name: Listen to presence sync + isSpotlight: true + code: | + ```js + const channel = supabase.channel('any') + channel + .on('presence', { event: 'sync' }, () => { + console.log('Synced presence state: ', channel.presenceState()) + }) + .subscribe(async (status) => { + if (status === 'SUBSCRIBED') { + await channel.track({ online_at: new Date().toISOString() }) + } + }) + ``` + - id: listen-to-presence-join + name: Listen to presence join + isSpotlight: true + code: | + ```js + const channel = supabase.channel('any') + channel + .on('presence', { event: 'join' }, ({ newPresences }) => { + console.log('Newly joined presences: ', newPresences) + }) + .subscribe(async (status) => { + if (status === 'SUBSCRIBED') { + await channel.track({ online_at: new Date().toISOString() }) + } + }) + ``` + - id: listen-to-presence-leave + name: Listen to presence leave + isSpotlight: true + code: | + ```js + const channel = supabase.channel('any') + channel + .on('presence', { event: 'leave' }, ({ leftPresences }) => { + console.log('Newly left presences: ', leftPresences) + }) + .subscribe(async (status) => { + if (status === 'SUBSCRIBED') { + await channel.track({ online_at: new Date().toISOString() }) + await channel.untrack() + } + }) + ``` - id: listen-to-all-database-changes name: Listen to all database changes isSpotlight: true code: | ```js supabase - .channel('*') + .channel('any') .on('postgres_changes', { event: '*', schema: '*' }, payload => { console.log('Change received!', payload) }) .subscribe() ``` - - id: listening-to-a-specific-table - name: Listening to a specific table + - id: listen-to-a-specific-table + name: Listen to a specific table code: | ```js supabase - .channel('public:countries') + .channel('any') .on('postgres_changes', { event: '*', schema: 'public', table: 'countries' }, payload => { console.log('Change received!', payload) }) .subscribe() ``` - - id: listening-to-inserts - name: Listening to inserts + - id: listen-to-inserts + name: Listen to inserts code: | ```js supabase - .channel('public:countries') + .channel('any') .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'countries' }, payload => { console.log('Change received!', payload) }) .subscribe() ``` - - id: listening-to-updates - name: Listening to updates + - id: listen-to-updates + name: Listen to updates description: | By default, Supabase will send only the updated record. If you want to receive the previous values as well you can enable full replication for the table you are listening to: @@ -4026,14 +4095,14 @@ functions: code: | ```js supabase - .channel('public:countries') + .channel('any') .on('postgres_changes', { event: 'UPDATE', schema: 'public', table: 'countries' }, payload => { console.log('Change received!', payload) }) .subscribe() ``` - - id: listening-to-deletes - name: Listening to deletes + - id: listen-to-deletes + name: Listen to deletes description: | By default, Supabase does not send deleted records. If you want to receive the deleted record you can enable full replication for the table you are listening too: @@ -4044,32 +4113,32 @@ functions: code: | ```js supabase - .channel('public:countries') + .channel('any') .on('postgres_changes', { event: 'DELETE', schema: 'public', table: 'countries' }, payload => { console.log('Change received!', payload) }) .subscribe() ``` - - id: listening-to-multiple-events - name: Listening to multiple events + - id: listen-to-multiple-events + name: Listen to multiple events description: You can chain listeners if you want to listen to multiple events for each table. code: | ```js supabase - .channel('public:countries') + .channel('any') .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'countries' }, handleRecordInserted) .on('postgres_changes', { event: 'DELETE', schema: 'public', table: 'countries' }, handleRecordDeleted) .subscribe() ``` - id: listening-to-row-level-changes - name: Listening to row level changes + name: Listen to row level changes description: You can listen to individual rows using the format `{table}:{col}=eq.{val}` - where `{col}` is the column name, and `{val}` is the value which you want to match. notes: | - ``eq`` filter works with all database types as under the hood, it's casting both the filter value and the database value to the correct type and then comparing them. code: | ```js supabase - .channel('public:countries:id=eq.200') + .channel('any') .on('postgres_changes', { event: 'UPDATE', schema: 'public', table: 'countries', filter: 'id=eq.200' }, handleRecordUpdated) .subscribe() ```