@MomsFriendlyDevCo/Supabase-Reactive

Supabase plugin for reactive read/write against local objects.

Extends the existing Supabase JavaScript functionality by adding a bi-directional, bound object which syncs with the server when its state changes. Changes on the server (or from another client) similarly update local state across all clients.

import Reactive from '@momsfriendlydevco/supabase-reactive';
import {createClient} from '@supabase/supabase-js'

// Create a Supabase client
let supabase = creatClient('https://MY-SUPABASE-DOMAIN.supabase.co', 'big-long-key');

// Create a reactive
let state = Reactive('my-table/id-to-sync', {supabase});

// Changes to state are now synced bi-directionally
state.foo = 1;
state.bar = [1, 2, 3];
state.baz = {key1: {subkey1: [4, 5, 6]}};
delete state.bar;

API

Supabase Table Structure

Ideally the data structure within Supabase should be made up of these columns:

• id - a UUID is recommended
• created_at - optional timestamp to indicate when the row was created
• edited_at - timestamp to track changes
• version - optional numeric to indicate the version offset of the row
• data - the main JSONB data entity storage

An example Postgres data command is:

create table
  public.test (
    id uuid not null default gen_random_uuid (),
    created_at timestamp with time zone not null default now(),
    edited_at timestamp with time zone null,
    data jsonb null,
    version bigint null,
    constraint test_pkey primary key (id),
    constraint test_id_key unique (id)
  ) tablespace pg_default;

SupabaseReactive(path, options)

The main exported function which returns a Reactive object.

The resulting reactive object also has a series of non-enumerable utility functions which all start with a single dollar sign. See below for their purpose and documentation.

This can take an optional shorthand path and/or an options structure.

Valid options are:

Option	Type	Default	Description
supbase	Supabase		Supabase instance to use
table	String		Supabase table to store data within if path is not specified
id	String		ID of the table row to sync data with
isArray	Boolean	false	Specifies if the data entity is an Array rather than an object
read=true	Boolean	true	Allow reading from the remote Supabase server, disabling this makes the data transfer transmit only
watch=true	Boolean	true	Allow watching for local changes and write them to the remote server if enabled
write=true	Boolean	true	Allow writing back local changes to the Supabase server
attachReactives	Boolean	true	Expose all utility functions as '$' prefixed functions to control the local state
throttle	Object		Lodash debounce options + wait key used to throttle all writes, set to falsy to disable
idColumn='id'	String	'id'	Row ID column to sync with
filter	Object		Query filter to use when accessing multiple rows
dataColumn	String	'data'	Data / JSONB column to sync data with
timestampColumn	String	'edited_at'	Timezone+TZ column to use when syncing data
versionColumn	String		Optional version column, this increments on each write and is only really useful for debugging purposes
reactiveCreate	Function		Async function used to create an observable / reactive data entity from its input. Defaults to Vue's reactive function
reactiveWatch	Function		Async function used to create a watch on the created reactive. Defaults to Vue's watch function
onInit	Function		Async function when first populating data from the remote. Called as (data)
onRead	Function		Async function called on subsequent reads when populating data from the remote. Called as (data)
onChange	Function		Async function called when a detected local write is about to be sent to the remote. Called as (dataPayload)
onDestroy	Function		Async function called when destroying state. Called as (data:Reactive)
debug	Function / Boolean		Optional debugging function callback. Called as (...msg:Any)
splitPath	Function		Path parser, expected to decorate the settings object. Called as (path: String, settings: Object) and expected to mutate the settings state

defaults

Storage object for all defaults used by SupabaseReactive.

Reactive.$meta

Meta information about the current row. This only really exists because we can't assign scalars in Javascript without it resetting the pointer later.

This object is made up of:

Key	Type	Description
id	String	The ID of the current row
table	String	The active table for the current row
timestamp	Null / Date	The last known timestamp of data from the server (or NULL if no data has been pulled yet)
If	Null / Number	a versioning column is enabled this represents the last known version of the data, similar to $meta.timestamp
Whether	Boolean	the state is being updated locally - indicates that local watchers should ignore incoming change detection

Reactive.$set(state, options)

Sets the content of the current reactive.

Valid options are:

Option	Type	Default	Description
markUpdating	Boolean	true	Mark the object as within an update to prevent recursion + disable local observers
removeKeys	Boolean	true	Clean out dead reactive keys if the new state doesn't also contain them
timestamp	Date		Set the reactive timestamp if provided
version	Number		Set the reactive version if provided

Reactive.$toObject()

Tidy JSON field data so that is safe from private methods (anything starting with '$' or '_', proxies or other non POJO slush. Returns a POJO.

Reactive.$refresh()

Alias of Reactive.$read().

Reactive.$getQuery()

Generate a Supabase object representing a query for the current configuration. Returns a Supabase promise which resolves when the operation has completed

Reactive.$init()

Initial operaton to wait on data from service + return reactable This function is the default response when calling the outer SupabaseReactive() function.

Reactive.$read()

Fetch the current data state from the server and update the reactive. Returns a promise.

Reactive.$fetch()

Fetch the current data state from the server but don't update the local state. This function is only really useful for snapshotting server state. Returns a promise which resolves with the snapshot data.

Reactive.$watch(isWatching=true)

Watch local data for changes and push to the server as needed. Returns a promise.

Reactive.$flush()

Wait for all local writes to complete. NOTE: This only promises that local writes complete, not that a subsequent read is required. Returns a promise.

Reactive.$subscribe(isSubscribed=true)

Toggle subscription to the realtime datafeed. Returns a promise.

Reactive.$destroy()

Release all watchers and subscriptions, local and remote. Returns a promise.