@momsfriendlydevco/supabase-reactive NPM

@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.