@iebh/tera-fy 1.15.9 → 2.0.0

package/lib/syncro.js

@@ -0,0 +1,452 @@
+import {
+	isEmpty,
+	cloneDeep,
+	throttle,
+} from 'lodash-es';
+import {
+	doc as FirestoreDocRef,
+	getDoc as FirestoreGetDoc,
+	onSnapshot as FirestoreOnSnapshot,
+	setDoc as FirestoreSetDoc,
+	updateDoc as FirestoreUpdateDoc,
+} from 'firebase/firestore';
+import marshal from '@momsfriendlydevco/marshal';
+
+
+/**
+* TERA Isomorphic Syncro class
+* This class tries to be as independent as possible to help with adapting it to various front-end TERA-fy plugin frameworks
+*/
+export default class Syncro {
+
+	/**
+	* Firebase instance in use
+	*
+	* @type {Firebase}
+	*/
+	static firebase;
+
+
+	/**
+	* Firestore instance in use
+	*
+	* @type {Firestore}
+	*/
+	static firestore;
+
+
+	/**
+	* Supabase instance in use
+	*
+	* @type {SupabaseClient}
+	*/
+	static supabase;
+
+
+	/**
+	* This instances fully formed string path
+	*
+	* @type {String}
+	*/
+	path;
+
+
+	/**
+	* The Firestore docHandle when calling various Firestore functions
+	*
+	* @type {FirestoreRef}
+	*/
+	docRef;
+
+
+	/**
+	* The reactive object managed by this Syncro instance
+	* The nature of this varies by framework and what `getReactive()` provides
+	*
+	* @type {*}
+	*/
+	value;
+
+
+	/**
+	* Default throttle to apply for writes
+	* Time in milliseconds
+	*
+	* @type {Number}
+	*/
+	throttle = 250;
+
+
+	/**
+	* @interface
+	* Debugging printer for this instance
+	* Defaults to doing nothing
+	*
+	* @param {*...} [msg] The message to output
+	*/
+	debug(...msg) {}
+
+
+	/**
+	* Instance constructor
+	*
+	* @param {String} path Mount path for the Syncro. Should be in the form `${ENTITY}::${ID}(::${RELATION})?`
+	* @param {Object} [options] Additional instance setters (mutates instance directly)
+	*/
+	constructor(path, options) {
+		this.path = path;
+		Object.assign(this, options);
+	}
+
+
+	/**
+	* Function to return whatever the local framework uses as a reactive object
+	* This should respond with an object of mandatory functions to watch for changes and remerge them
+	*
+	* @param {Object} value Initial value of the reactive
+	*
+	* @returns {Object} A reactive object prototype
+	* @property {Object} doc The reactive object
+	* @property {Function} setState Function used to overwrite the default state, called as `(newState:Object)`
+	* @property {Function} getState Function used to fetch the current snapshot state, called as `()`
+	* @property {Function} watch Function used to set up state watchers, should call its callback when a change is detected, called as `(cb:Function)`
+	*/
+	getReactive(value) {
+		console.warn('Syncro.getReactive has not been subclassed, assuming a POJO response');
+		let doc = {...value};
+		return {
+			doc,
+			setState(state) {
+				// Shallow copy all sub keys into existing object (keeping the object pointer)
+				Object.entries(state || {})
+					.forEach(([k, v]) => doc[k] = v)
+			},
+			getState() {
+				return cloneDeep(doc);
+			},
+			watch(cb) {
+				// Stub
+			},
+		};
+	};
+
+
+	/**
+	* Returns the split entity + ID relationship from a given session path
+	* This funciton checks for valid UUID format strings + that the entity is a known/supported entity (see `knownEntities`)
+	* NOTE: When used by itself (i.e. ignoring response) this function can also act as a guard that a path is valid
+	*
+	* INPUT: `widgets::UUID` -> `{entity:'widgets', id:UUID}`
+	* INPUT: `widgets::UUID::thing` -> `{entity:'widgets', id:UUID, relation:'thing'}`
+	*
+	* @param {String} path The input session path of the form `${ENTITY}::${ID}`
+	*
+	* @returns {Object} An object composed of the session path components
+	* @property {String} fbEntity The top level Firebase collection to store within
+	* @property {String} fsId The top level Firebase ID of the collection to store as, this is either just a copy of the ID or a combination of id + relation
+	* @property {String} entity A valid entity name (in plural form e.g. 'projects')
+	* @property {String} id A valid UUID ID
+	* @property {String} [relation] A string representing a sub-relationship. Usually a short string alias
+	*/
+	static pathSplit(path) {
+		let extracted = { .../^(?<entity>\w+?)::(?<id>[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})(?:::(?<relation>\w+?))?$/.exec(path)?.groups };
+
+		if (!extracted) throw new Error(`Invalid session path syntax "${path}"`);
+		if (!extracted.entity in syncEntities) throw new Error(`Unsupported entity "${path}" -> Entity="${extracted.entity}"`);
+
+		return {
+			...extracted,
+			fsCollection: extracted.entity,
+			fsId: extracted.relation
+				? `${extracted.id}::${extracted.relation}`
+				: extracted.id,
+		};
+	}
+
+
+	/**
+	* Convert local POJO -> Firestore compatible object
+	* This applies the following mutations to the incoming object:
+	*
+	* 1. Arrays are converted to Objects (Firestore cannot store nested arrays)
+	* 2. All non-POJO objects (e.g. Dates) to a symetric object
+	*
+	* @FIXME: Pretty sure we can drop the fromEntities() + key serializer in future
+	*
+	* @param {Object} snapshot The current state to convert
+	* @returns {Object} A Firebase compatible object
+	*/
+	static toFirestore(snapshot = {}) {
+		return marshal.serialize(this.cleanPojo(snapshot), {
+			clone: true, // Clone away from the original Vue Reactive so we dont mangle it while traversing
+			modules: [
+				marshalFlattenArrays,
+				...marshal.settings.modules,
+			],
+			stringify: false,
+		});
+	}
+
+
+	/**
+	* Convert local Firestore compatible object -> local POJO
+	* This reverses the mutations listed in `toFirestore()`
+	*
+	* @FIXME: Pretty sure we can drop the fromEntities() + key serializer in future
+	*
+	* @param {Object} snapshot The raw Firebase state to convert
+	* @returns {Object} A JavaScript POJO representing the converted state
+	*/
+	static fromFirestore(snapshot = {}) {
+		return marshal.deserialize(this.cleanPojo(snapshot), {
+			modules: [
+				marshalFlattenArrays,
+				...marshal.settings.modules,
+			],
+			destringify: false,
+		});
+	}
+
+
+	/**
+	* Perform a one-off fetch of a given Syncro path
+	*
+	* @param {String} path The Syncro entity + ID path. Takes the form `ENTITY::ID`
+	*
+	* @returns {Promise<Object|Null>} An eventual snapshot of the given path, if the entity doesn't exist null is returned
+	*/
+	static getSnapshot(path) {
+		let {fsCollection, fsId} = Syncro.pathSplit(path);
+
+		return Promise.resolve()
+			.then(async ()=> { // Set up binding and wait for it to come ready
+				let docRef = FirestoreDocRef(Syncro.firestore, fsCollection, fsId);
+				return FirestoreGetDoc(docRef);
+			})
+			.then(doc => doc
+				? Syncro.fromFirestore(snapshot.data())
+				: null
+			)
+	}
+
+
+	/**
+	* Perform a one-off set/merge operation against
+	*
+	* @param {String} path The Syncro entity + ID path. Takes the form `ENTITY::ID`
+	* @param {Object} state The new state to set/merge
+	*
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {'merge'|'set'} [options.method='merge'] How to apply the new state. 'merge' (merge in partial data to an existing Syncro), 'set' (overwrite the entire Syncro state)
+	*
+	* @returns {Promise<*>} The state object after it has been applied
+	*/
+	static setSnapshot(path, state, options) {
+		let settings = {
+			method: 'merge',
+			...options,
+		};
+		let {fsCollection, fsId} = Syncro.pathSplit(path);
+
+		return Promise.resolve()
+			.then(()=> // Set up binding and wait for it to come ready
+				(settings.method == 'merge' ? 'FirestoreUpdateDoc' : 'FirestoreSetDoc')(
+					FirestoreDocRef(this.firestore, fsCollection, fsId),
+					Syncro.toFirestore(state),
+				)
+			)
+			.then(()=> state)
+	}
+
+
+	static cleanPojo(state) {
+		return Object.fromEntries(
+			Object.entries(state)
+				.filter(([k]) => // Ignore top level hidden fields
+					!/^[\$_]/.test(k) // Starts with '_' or '$'
+					&& k !== 'metadata' // Is the Firestore forbidden 'metadata' key
+				)
+		);
+	}
+
+
+	/**
+	* Wrap a Supabase query so it works more like a classic-JS promise
+	*
+	* 1. Flatten non-promise responses into thennables
+	* 2. The query is forced to respond as a promise (prevents accidental query chaining)
+	* 3. The response data object is forced as a POJO (if any data is returned, otherwise void)
+	* 4. Error responses throw with a logical error message rather than a weird object return
+	* 5. Translate various error messages to something logical
+	*
+	* @param {SupabaseQuery} query A Supabase query object or method to execute
+	* @returns {Object} The data response as a plain JavaScript Object
+	*/
+	static wrapSupabase(query) {
+		return Promise.resolve(query)
+			.then(res => {
+				if (res?.error) {
+					if (/JSON object requested, multiple \(or no\) rows returned$/.test(res.error.message)) {
+						console.warn('Supabase query threw record not found against query', query.url.search);
+						console.warn('Supabase raw error', res);
+						throw new Error('NOT-FOUND');
+					} else {
+						console.warn('Supabase query threw', res.error.message);
+						throw new Error(`${res.error?.code || 'UnknownError'}: ${res.error?.message || 'Unknown Supabase error'}`);
+					}
+				} else if (res.data) { // Do we have output data
+					return res.data;
+				}
+			})
+	}
+
+
+	/**
+	* Mount the remote Firestore document against this instances local `value` getReactive
+	*
+	* @returns {Promise<Sync>} A promise which resolves as this sync instance when completed
+	*/
+	mount() {
+		let {fsCollection, fsId, entity, id, relation} = Syncro.pathSplit(this.path);
+		let reactive; // Eventual response from reactive() with the intitial value
+		let doc; // Eventual Firebase document
+
+		return Promise.resolve()
+			.then(async ()=> { // Set up binding and wait for it to come ready
+				this.docRef = FirestoreDocRef(Syncro.firestore, fsCollection, fsId);
+
+				// Initalize state
+				let initialState = Syncro.fromFirestore(
+					(await FirestoreGetDoc(this.docRef))
+						.data()
+				);
+
+				// Construct a reactive component
+				reactive = this.getReactive(initialState);
+				if (!reactive.doc || !reactive.setState || !reactive.getState || !reactive.watch) throw new Error('Syncro.getReactive() requires a returned `doc`, `setState()`, `getState()` + `watch()`');
+				this.value = doc = reactive.doc;
+
+				this.debug('Initial state', {doc});
+
+				// Subscribe to remote updates
+				FirestoreOnSnapshot(this.docRef, snapshot => {
+					let snapshotData = Syncro.fromFirestore(snapshot.data());
+					this.debug('Incoming snapshot', {snapshotData});
+					reactive.setState(snapshotData);
+				});
+			})
+			.then(()=> { // Optionally create the doc if it has no content
+				if (!isEmpty(doc)) return; // Doc already has some content at least
+
+				this.debug('Populate initial state');
+
+				// Extract base data + add document and return new hook
+				return Promise.resolve()
+					.then(()=> syncEntities[entity] || Promise.reject(`Unknown Sync entity "${entity}"`))
+					.then(()=> syncEntities[entity].initState({
+						supabase: Syncro.supabase,
+						entity,
+						id,
+						relation,
+					}))
+					.then(state => FirestoreSetDoc(
+						this.docRef,
+						Syncro.toFirestore(state),
+					)) // Send new base state to Firestore
+			})
+			.then(()=> { // Setup local state watcher
+				reactive.watch(throttle(newState => {
+					this.debug('Local change', {newState});
+					FirestoreUpdateDoc(
+						this.docRef,
+						Syncro.toFirestore(newState),
+					);
+				}, this.throttle));
+			})
+			.then(()=> this)
+	}
+
+}
+
+
+/**
+* Entities we support syncro paths on, each needs to correspond with a Firebase/Firestore collection name
+*
+* @type {Object} An object lookup of entities
+*
+* @property {String} singular The singular noun for the item
+* @property {Function} initState Function called to initialize state when Firestore has no existing document. Called as `({supabase:SupabaseClient, entity:String, id:String, relation?:string})` and expected to return the initial data object state
+*/
+export const syncEntities = {
+	projects: {
+		singular: 'project',
+		initState({supabase, id}) {
+			return Syncro.wrapSupabase(supabase.from('projects')
+				.select('data')
+				.limit(1)
+				.eq('id', id)
+			)
+				.then(rows => rows.length == 1 ? rows[0] : Promise.reject(`Syncro project "${id}" not found`))
+				.then(item => item.data); // Bind to 'data' JSONB column
+		},
+	},
+	project_namespaces: {
+		singular: 'project namespace',
+		initState({supabase, id, relation}) {
+			if (!relation) throw new Error('Project namespace relation missing, path should resemble "project_namespaces::${PROJECT}::${RELATION}"');
+			return Syncro.wrapSupabase(supabase.from('project_namespaces')
+				.select('data')
+				.limit(1)
+				.eq('project', id)
+				.eq('name', relation)
+			)
+				.then(rows => rows.length == 1 ? rows[0] : Promise.reject(`Syncro project ("${id}") namespace ("${relation}") not found`))
+				.then(item => item.data);
+		},
+	},
+	test: {
+		singular: 'test',
+		initState({supabase, id}) {
+			return Syncro.wrapSupabase(supabase.from('test')
+				.select('data')
+				.limit(1)
+				.eq('id', id)
+			)
+				.then(rows => rows.length == 1 ? rows[0] : Promise.reject(`Syncro test item "${id}" not found`))
+				.then(item => item.data);
+		},
+	},
+	users: {
+		singular: 'user',
+		initState({supabase, id}) {
+			return Syncro.wrapSupabase(supabase.from('users')
+				.select('data')
+				.limit(1)
+				.eq('id', id)
+			)
+				.then(rows => rows.length == 1 ? rows[0] : Promise.reject(`Syncro user "${id}" not found`))
+				.then(item => item.data);
+		},
+	},
+};
+
+
+/**
+* NPM:@momsfriendlydevco/marshal Compatible module for flattening arrays
+* @type {MarshalModule}
+*/
+const marshalFlattenArrays = {
+	id: `~array`,
+	recursive: true,
+	test: v => Array.isArray(v),
+	serialize: v => ({_: '~array', ...v}),
+	deserialize: v => {
+		let arr = Array.from({length: Object.keys(v).length - 1});
+
+		Object.entries(v)
+			.filter(([k]) => k !== '_')
+			.forEach(([k, v]) => arr[+k] = v);
+
+		return arr;
+	},
+};

package/lib/terafy.client.js

@@ -105,6 +105,7 @@ export default class TeraFy {
 		// Session
 		'getUser',
 		'requireUser',
+		'getCredentials',
 
 		// Projects
 		'bindProject',
@@ -114,11 +115,17 @@ export default class TeraFy {
 		'requireProject',
 		'selectProject',
 
+		// Project namespaces
+		// 'mountNamespace', // Handled by this library
+		// 'unmountNamespace', // Handled by this library
+		'getNamespace',
+		'setNamespace',
+		'listNamespaces',
+
 		// Project State
 		'getProjectState',
 		'setProjectState',
 		'setProjectStateDefaults',
-		'setProjectStateFlush',
 		'setProjectStateRefresh',
 		'saveProjectState',
 		'replaceProjectState',
@@ -164,6 +171,16 @@ export default class TeraFy {
 	plugins = [];
 
 
+	/**
+	* Active namespaces we are subscribed to
+	* Each key is the namespace name with the value as the local reactive \ observer \ object equivelent
+	* The key string is always of the form `${ENTITY}::${ID}` e.g. `projects:1234`
+	*
+	* @type {Object<Object>}
+	*/
+	namespaces = {};
+
+
 	// Messages - send(), sendRaw(), rpc(), acceptMessage() {{{
 
 	/**
@@ -303,6 +320,68 @@ export default class TeraFy {
 
 	// }}}
 
+	// Project namespace - mountNamespace(), unmountNamespace() {{{
+	/**
+	* Make a namespace available locally
+	* This generally creates whatever framework flavoured reactive/observer/object is supported locally - generally with writes automatically synced with the master state
+	*
+	* @param {String} name The alias of the namespace, this should be alphanumeric + hyphens + underscores
+	*
+	* @returns {Promise<Reactive>} A promise which resolves to the reactive object
+	*/
+	mountNamespace(name) {
+		if (!/^[\w-]+$/.test(name)) throw new Error('Namespaces must be alphanumeric + hyphens + underscores');
+		if (this.namespaces[name]) return Promise.resolve(this.namespaces[name]); // Already mounted
+
+		return Promise.resolve()
+			.then(()=> this._mountNamespace(name))
+			.then(()=> this.namespaces[name] || Promise.reject(`teraFy.mountNamespace('${name}') resolved but no namespace has been mounted`))
+	}
+
+
+	/**
+	* @interface
+	* Actual namespace mounting function designed to be overriden by plugins
+	*
+	* @param {String} name The alias of the namespace, this should be alphanumeric + hyphens + underscores
+	*
+	* @returns {Promise} A promise which resolves when the mount operation has completed
+	*/
+	_mountNamespace(name) {
+		console.warn('teraFy._mountNamespace() has not been overriden by a TERA-fy plugin, load one to add this functionality for your preferred framework');
+		throw new Error('teraFy._mountNamespace() is not supported');
+	}
+
+
+	/**
+	* Release a locally mounted namespace
+	* This function will remove the namespace from `namespaces`, cleaning up any memory / subscription hooks
+	*
+	* @interface
+	*
+	* @param {String} name The name of the namespace to unmount
+	*
+	* @returns {Promise} A promise which resolves when the operation has completed
+	*/
+	unmountNamespace(name) {
+		if (!this.namespaces[name]) return Promise.resolve(); // Already unmounted
+		return this._unmountNamespace(name);
+	}
+
+
+	/**
+	* @interface
+	* Actual namespace unmounting function designed to be overriden by plugins
+	*
+	* @param {String} name The name of the namespace to unmount
+	*
+	* @returns {Promise} A promise which resolves when the operation has completed
+	*/
+	_unmountNamespace(name) {
+		console.warn('teraFy.unbindNamespace() has not been overriden by a TERA-fy plugin, load one to add this functionality for your preferred framework');
+	}
+	// }}}
+
 	// Project state - createProjectStatePatch(), applyProjectStatePatchLocal() {{{
 	/**
 	* Create + transmit a new project state patch base on the current and previous states
@@ -838,19 +917,35 @@ export default class TeraFy {
 	* @param {Object} source Initalized source object to extend from
 	*/
 	mixin(target, source) {
-		Object.getOwnPropertyNames(Object.getPrototypeOf(source))
-			.filter(prop => !['constructor', 'prototype', 'name'].includes(prop))
-			.filter(prop => prop != 'init') // Don't allow plugin init() to override our version - these all get called during init() anyway
-			.forEach((prop) => {
-				Object.defineProperty(
-					target,
-					prop,
-					{
-						value: source[prop].bind(target),
-						enumerable: false,
-					},
-				);
-			});
+		// Iterate through the source object upwards extracting each prototype
+		let prototypeStack = [];
+		let node = source;
+		do {
+			prototypeStack.unshift(node);
+		} while (node = Object.getPrototypeOf(node)); // Walk upwards until we hit null (no more inherited classes)
+
+		// Iterate through stacks inheriting each prop into the target
+		prototypeStack.forEach(stack =>
+			Object.getOwnPropertyNames(stack)
+				.filter(prop =>
+					!['constructor', 'init', 'prototype', 'name'].includes(prop) // Ignore forbidden properties
+					&& !prop.startsWith('__') // Ignore double underscore meta properties
+				)
+				.forEach(prop => {
+					if (typeof source[prop] == 'function') { // Inheriting function - glue onto object as non-editable, non-enumerable property
+						Object.defineProperty(
+							target,
+							prop,
+							{
+								enumerable: false,
+								value: source[prop].bind(target), // Rebind functions
+							},
+						);
+					} else { // Everything else, just glue onto the object
+						target[prop] = source[prop];
+					}
+				})
+		)
 	}
 
 
@@ -955,6 +1050,14 @@ export default class TeraFy {
 	*/
 
 
+	/**
+	* Provide an object of credentials for 3rd party services like Firebase/Supabase
+	*
+	* @functions getCredentials
+	* @returns {Object} An object containing 3rd party service credentials
+	*/
+
+
 	/**
 	* Require a user login to TERA
 	* If there is no user OR they are not logged in a prompt is shown to go and do so
@@ -1038,6 +1141,40 @@ export default class TeraFy {
 	*/
 
 
+	/**
+	* Get a one-off snapshot of a namespace without mounting it
+	* This can be used for simpler apps which don't have their own reactive / observer equivelent
+	*
+	* @function getNamespace
+	* @param {String} name The alias of the namespace, this should be alphanumeric + hyphens + underscores
+	*
+	* @returns {Promise<Object>} A promise which resolves to the namespace POJO state
+	*/
+
+
+	/**
+	* Set (or merge by default) a one-off snapshot over an existing namespace
+	* This can be used for simpler apps which don't have their own reactive / observer equivelent and just want to quickly set something
+	*
+	* @function setNamespace
+	* @param {String} name The name of the namespace
+	* @param {Object} state The state to merge
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {'merge'|'set'} [options.method='merge'] How to handle the state. 'merge' (merge a partial state over the existing namespace state), 'set' (completely overwrite the existing namespace)
+	*
+	* @returns {Promise<Object>} A promise which resolves to the namespace POJO state
+	*/
+
+
+	/**
+	* Return a list of namespaces available to the current project
+	*
+	* @function listNamespaces
+	* @returns {Promise<Array<Object>>} Collection of available namespaces for the current project
+	* @property {String} name The name of the namespace
+	*/
+
+
 	/**
 	* Return the current, full snapshot state of the active project
 	*
@@ -1081,15 +1218,6 @@ export default class TeraFy {
 	*/
 
 
-	/**
-	* Force copying local changes to the server
-	* This is only ever needed when saving large quantities of data that need to be immediately available
-	*
-	* @function setProjectStateFlush
-	* @returns {Promise} A promise which resolves when the operation has completed
-	*/
-
-
 	/**
 	* Force refetching the remote project state into local
 	* This is only ever needed when saving large quantities of data that need to be immediately available
@@ -1428,9 +1556,9 @@ export default class TeraFy {
 	*
 	* @param {Object} [options] Additional options to mutate behaviour
 	* @param {String} [options.body] Optional additional body text
+	* @param {Boolean} [options.isHtml=false] If truthy, treat the body as HTML
 	* @param {String} [options.value] Current or default value to display pre-filled
 	* @param {String} [options.title='Input required'] The dialog title to display
-	* @param {Boolean} [options.bodyHtml=false] If truthy, treat the body as HTML
 	* @param {String} [options.placeholder] Optional placeholder text
 	* @param {Boolean} [options.required=true] Treat nullish or empty inputs as a cancel operation
 	*