@iebh/tera-fy 2.0.5 → 2.0.7

package/lib/{syncro.js → syncro/syncro.js}

@@ -17,7 +17,9 @@ import {nanoid} from 'nanoid';
 
 
 /**
+* @class Syncro
 * TERA Isomorphic Syncro class
+* Slurp an entity from Supabase and hold it in Firebase/Firestore as a "floating" entity which periodically gets flushed back to Supabase and eventually completely cleaned up
 * 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 {
@@ -89,11 +91,29 @@ export default class Syncro {
 
 
 	/**
-	* Time between heartbeats
+	* Various Misc config for the Syncro instance
 	*
-	* @type {Number} Heartbeat time in milliseconds
+	* @type {Object}
+	* @property {Number} heartbeatinterval Time in milliseconds between heartbeat beacons
+	* @property {String} syncWorkerUrl The prefix Sync worker URL
+	* @property {Object} context Additional named parameters to pass to callbacks like initState
 	*/
-	heartbeatInterval = 30_000; //~= 30s
+	config = {
+		heartbeatInterval: 50_000, //~= 50s
+		syncWorkerUrl: 'https://tera-tools.com/api/sync',
+		context: {},
+	};
+
+
+	/**
+	* Whether the next heartbeat should be marked as 'dirty'
+	* This indicates that at least one change has occured since the last hearbeat and the server should perform a flush (but not a clean)
+	* This flag is only transmitted once in the next heartbeat before being reset
+	*
+	* @see markDirty()
+	* @type {Boolean}
+	*/
+	isDirty = false;
 
 
 	/**
@@ -103,18 +123,24 @@ export default class Syncro {
 	*
 	* @param {*...} [msg] The message to output
 	*/
-	debug(...msg) {}
+	debug(...msg) {} // eslint-disable-line no-unused-vars
 
 
 	/**
 	* 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)
+	* @param {Object} [options] Additional instance setters (mutates instance directly), note that the `config` subkey is merged with the existing config rather than assigned
 	*/
 	constructor(path, options) {
 		this.path = path;
-		Object.assign(this, options);
+		Object.assign(this, {
+			...options,
+			config: {
+				...this.config,
+				...options?.config,
+			},
+		});
 
 		if (!Syncro.session) // Assign a random session ID if we don't already have one
 			Syncro.session = `syncro_${nanoid()}`;
@@ -170,7 +196,7 @@ export default class Syncro {
 			getState() {
 				return cloneDeep(doc);
 			},
-			watch(cb) {
+			watch(cb) { // eslint-disable-line no-unused-vars
 				// Stub
 			},
 		};
@@ -186,6 +212,8 @@ export default class Syncro {
 	* INPUT: `widgets::UUID::thing` -> `{entity:'widgets', id:UUID, relation:'thing'}`
 	*
 	* @param {String} path The input session path of the form `${ENTITY}::${ID}`
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {Boolean} [options.allowAsterisk=false] Whether to allow the meta asterisk character when recognising paths, this is used by the SyncroKeyed class
 	*
 	* @returns {Object} An object composed of the session path components
 	* @property {String} fbEntity The top level Firebase collection to store within
@@ -194,8 +222,27 @@ export default class Syncro {
 	* @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 };
+	static pathSplit(path, options) {
+		let settings = {
+			allowAsterisk: false,
+			...options,
+		};
+
+		let pathMatcher = new RegExp(
+			// Compose the patch matching expression - note double escapes for backslashes to avoid encoding as raw string values
+			'^'
+			+ '(?<entity>\\w+?)' // Any alpha-numeric sequence as the entity name (non-greedy capture)
+			+ '::' // Followed by '::'
+			+ '(?<id>[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})' // Followed by a valid lower-case UUID
+			+ '(?:::(?<relation>[' // Followed by an optional ansi relation
+				+ '\\w' // Which is any alpha-numeric sequence...
+				+ '\\-' // ... Including UUID characters
+				+ (settings.allowAsterisk ? '\\*' : '') // ... and (optionally) an asterisk
+			+ ']+?))?'
+			+ '$'
+		);
+
+		let extracted = { ...pathMatcher.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}"`);
@@ -217,8 +264,6 @@ export default class Syncro {
 	* 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
 	*/
@@ -239,8 +284,6 @@ export default class Syncro {
 	* 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
 	*/
@@ -377,11 +420,18 @@ export default class Syncro {
 
 
 	/**
-	* Mount the remote Firestore document against this instances local `value` getReactive
+	* Mount the remote Firestore document against this Syncro instance
 	*
-	* @returns {Promise<Sync>} A promise which resolves as this sync instance when completed
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {Object} [options.initalState] State to use if no state is already loaded, overrides the entities own `initState` function fetcher
+	* @returns {Promise<Syncro>} A promise which resolves as this syncro instance when completed
 	*/
-	mount(tera) {
+	mount(options) {
+		let settings = {
+			initialState: null,
+			...options,
+		};
+
 		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
@@ -392,10 +442,7 @@ export default class Syncro {
 				this.docRef = FirestoreDocRef(Syncro.firestore, fsCollection, fsId);
 
 				// Initalize state
-				let initialState = Syncro.fromFirestore(
-					(await FirestoreGetDoc(this.docRef))
-						.data()
-				);
+				let initialState = await this.getFirestoreState();
 
 				// Construct a reactive component
 				reactive = this.getReactive(initialState);
@@ -414,31 +461,31 @@ export default class Syncro {
 				);
 			})
 			.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,
-						fsCollection, fsId,
-						entity, id, relation,
-						tera
-					}))
-					.then(state => FirestoreSetDoc(
-						this.docRef,
-						Syncro.toFirestore(state),
-					)) // Send new base state to Firestore
+				if (!isEmpty(doc)) { // Doc already has content - skip
+					return;
+				} else if (settings.initialState) { // Provided an intiailState - use that instead of the entities own method
+					this.debug('Populate initial Syncro state (from provided initialState)');
+					return this.setFirestoreState(settings.initialState, {method: 'set'});
+				} else {
+					this.debug(`Populate initial Syncro state (from "${entity}" entity)`);
+
+					// 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,
+							fsCollection, fsId,
+							entity, id, relation,
+							...this.config.context,
+						}))
+						.then(state => this.setFirestoreState(state, {method: 'set'})) // 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.markDirty();
+					this.setFirestoreState(newState, {method: 'merge'});
 				}, this.throttle));
 			})
 			.then(()=> this.setHeartbeat(true, {
@@ -473,7 +520,7 @@ export default class Syncro {
 
 				// If we're enabled - schedule the next heartbeat timer
 				enable && this.setHeartbeat(true);
-			}, this.heartbeatInterval);
+			}, this.config.heartbeatInterval);
 
 			if (settings.immediate) this.heartbeat();
 		}
@@ -488,25 +535,71 @@ export default class Syncro {
 	*/
 	async heartbeat() {
 		this.debug('heartbeat!');
-		let timestamp = (new Date()).toISOString();
-
-		let docRef = FirestoreDocRef(Syncro.firestore, 'presence', this.path);
-		let doc = await FirestoreGetDoc(docRef);
-
-		await FirestoreSetDoc(
-			docRef,
-			{
-				latest: timestamp,
-				...(!doc.exists() && { // New doc - populate some base fields
-					created: timestamp,
-					lastFlush: null,
-				}),
-				sessions: {
-					[Syncro.session]: timestamp,
-				},
+
+		await fetch(`${this.config.syncWorkerUrl}/${this.path}/heartbeat`, {
+			method: 'post',
+			headers: {
+				'Content-Type': 'application/json'
 			},
-			{merge: true},
-		);
+			body: JSON.stringify({
+				session: Syncro.session,
+				...(this.isDirty && {dirty: true}),
+			}),
+		})
+			.then(response => response.ok
+				? null
+				: console.warn(this.path, `Heartbeat failed - ${response.statusText}`, {response})
+			)
+			.then(()=> this.isDirty = false) // Reset the dirty flag if it is set
+	}
+
+
+	/**
+	* Utility function to directly set this documents firestore state
+	*
+	* @param {Object} state The 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} A promise which resolves when the operation has completed
+	*/
+	setFirestoreState(state, options) {
+		let settings = {
+			method: 'merge',
+			...options,
+		};
+		if (!this.docRef) throw new Error('mount() must be called before setting Firestore state');
+
+		return (settings.method == 'set' ? FirestoreSetDoc : FirestoreUpdateDoc)(
+			this.docRef,
+			Syncro.toFirestore(state),
+		)
+	}
+
+
+	/**
+	* Utility method to fetch the Firestore state for this Syncro
+	* NOTE: This directly extracts the state of the Firestore, not its wrapping doc object returned by `FirestoreGetDoc`
+	*
+	* @returns {Promise<Object>} A promise which resolves to the Firestore state
+	*/
+	getFirestoreState() {
+		if (!this.docRef) throw new Error('mount() must be called before getting Firestore state');
+
+		return FirestoreGetDoc(this.docRef)
+			.then(doc => Syncro.fromFirestore(doc.data()))
+	}
+
+
+	/**
+	* Set the Syncro dirty flag which gets passed to the server on the next heartbeat
+	*
+	* @see isDirty
+	* @returns {Syncro} This chainable Syncro instance
+	*/
+	markDirty() {
+		this.isDirty = true;
+		return this;
 	}
 
 
@@ -525,9 +618,7 @@ export default class Syncro {
 			...options,
 		};
 
-		return fetch(`https://tera-tools.com/api/sync/${this.path}/flush` + (settings.destroy ? '?destroy=1' : ''), {
-			method: 'post',
-		})
+		return fetch(`${this.config.syncWorkerUrl}/${this.path}/flush` + (settings.destroy ? '?destroy=1' : ''))
 			.then(response => response.ok ? null : Promise.reject(response.statusText || 'An error occured'))
 	}
 
@@ -574,149 +665,6 @@ export function randomBranch(depth = 0) {
 }
 
 
-/**
-* 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
-* @property {Function} flushState Function called to flush state from Firebase to Supabase. Called the same as `initState` + `{state:Object}`
-*/
-export const syncEntities = {
-	projects: {
-		singular: 'project',
-		async initState({supabase, id, tera}) {
-			const result = await Syncro.wrapSupabase(supabase.from('projects')
-				.select('data')
-				.limit(1)
-				.eq('id', id)
-			);
-
-			if (result.length !== 1) {
-				throw new Error(`Syncro project "${id}" not found`);
-			}
-
-			const data = result[0].data;
-			console.log('[MIGRATION] State of temp at start:', data.temp);
-
-			// Check if temp variable exists
-			if (!data.temp) return data;
-
-			let shownAlert = false;
-			for (const toolKey in data.temp) {
-				// Check if temp has already been set to file path
-				if (typeof data.temp[toolKey] !== 'object') {
-					console.log(`[MIGRATION] Skipping conversion of ${toolKey}, not an object:`, data.temp[toolKey])
-					return;
-				}
-
-				if (!shownAlert) {
-					shownAlert = true;
-					console.log('[MIGRATION] showing alert');
-					alert('Data found that will be migrated to new TERA file storage system. This may take a few minutes, please do not close your browser or refresh.');
-				}
-
-				// Create filename based on existing key
-				const toolName = toolKey.split('-')[0];
-				const fileName = `data-${toolName}-${nanoid()}.json`;
-				console.log('[MIGRATION] Creating filename:', fileName);
-
-				// Create file, set contents and overwrite key
-				const projectFile = await tera.createProjectFile(fileName);
-				console.log('[MIGRATION] Setting file contents:', projectFile, 'to:', data.temp[toolKey]);
-				await projectFile.setContents(data.temp[toolKey])
-				console.log('[MIGRATION] Overwriting temp key with filepath:', fileName);
-				data.temp[toolKey] = fileName;
-			}
-
-			console.log("[MIGRATION] State of temp at end:", data.temp)
-
-			return data;
-		},
-		flushState({supabase, state, fsId}) {
-			return Syncro.wrapSupabase(supabase.rpc('syncro_merge_data', {
-				table_name: 'projects',
-				entity_id: fsId,
-				new_data: state,
-			}))
-		},
-	},
-	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]
-					: Syncro.wrapSupabase(supabase.from('project_namespaces') // Doesn't exist - create it
-						.insert({
-							project: id,
-							name: relation,
-							data: {},
-						})
-						.select('data')
-					)
-				)
-				.then(item => item.data);
-		},
-		flushState({supabase, state, id, relation}) {
-			return Syncro.wrapSupabase(supabase.from('project_namespaces')
-				.update({
-					edited_at: new Date(),
-					data: state,
-				})
-				.eq('project', id)
-				.eq('name', relation)
-			)
-		},
-	},
-	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);
-		},
-		flushState({supabase, state, fsId}) {
-			return Syncro.wrapSupabase(supabase.rpc('syncro_merge_data', {
-				table_name: 'test',
-				entity_id: fsId,
-				new_data: state,
-			}))
-		},
-	},
-	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);
-		},
-		flushState({supabase, state, fsId}) {
-			return Syncro.wrapSupabase(supabase.rpc('syncro_merge_data', {
-				table_name: 'users',
-				entity_id: fsId,
-				new_data: state,
-			}))
-		},
-	},
-};
-
-
 /**
 * NPM:@momsfriendlydevco/marshal Compatible module for flattening arrays
 * @type {MarshalModule}

package/lib/terafy.client.js

@@ -1,4 +1,3 @@
-import {diff} from 'just-diff';
 import {cloneDeep} from 'lodash-es';
 import Mitt from 'mitt';
 import {nanoid} from 'nanoid';
@@ -61,8 +60,8 @@ export default class TeraFy {
 			'allow-scripts',
 			'allow-top-navigation',
 		],
-		handshakeInterval: 1000, // ~1s
-		handshakeTimeout: 10000, // ~10s
+		handshakeInterval: 1_000, // ~1s
+		handshakeTimeout: 10_000, // ~10s
 		debugPaths: null, // Transformed into a Array<String> (in Lodash dotted notation) on init()
 	};
 
@@ -127,10 +126,6 @@ export default class TeraFy {
 		'setProjectState',
 		'setProjectStateDefaults',
 		'setProjectStateRefresh',
-		'saveProjectState',
-		'replaceProjectState',
-		// 'applyProjectStatePatch', - Handled below (applies behaviour to watch for `settings.debugPaths`)
-		// For bindProjectState() - See individual plugins
 
 		// Project files
 		// 'selectProjectFile', - Handled below (requires return collection mapped to ProjectFile)
@@ -348,7 +343,7 @@ export default class TeraFy {
 	*
 	* @returns {Promise} A promise which resolves when the mount operation has completed
 	*/
-	_mountNamespace(name) {
+	_mountNamespace(name) { // eslint-disable-line no-unused-vars
 		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');
 	}
@@ -378,80 +373,11 @@ export default class TeraFy {
 	*
 	* @returns {Promise} A promise which resolves when the operation has completed
 	*/
-	_unmountNamespace(name) {
+	_unmountNamespace(name) { // eslint-disable-line no-unused-vars
 		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
-	* The transmitted patch follows the [JSPatch](http://jsonpatch.com) standard
-	* This function accepts an entire projectState instance, computes the delta and transmits that to the server for merging
-	*
-	* @param {Object} newState The local projectState to accept
-	* @param {Object} oldState The previous projectState to examine against
-	*
-	* @returns {Promise} A promise which will resolve when the operation has completed
-	*/
-	createProjectStatePatch(newState, oldState) {
-		let patch = diff(oldState, newState);
-		if (patch.length == 0) {
-			this.debug('INFO', 4, 'Skipping empty project patch', {patch, newState, oldState});
-			return Promise.resolve();
-		} else {
-			this.debug('INFO', 3, 'Created project patch', {patch, newState, oldState});
-			return this.applyProjectStatePatch(patch);
-		}
-	}
-
-
-	/**
-	* Transmit a patch to the remote server
-	* This function also enters debugging mode if any of the `settings.debugPaths` are operated on
-	*
-	* @param {Array} patch Patch to apply
-	* @returns {Promise} A promise which resolves when the operation has completed
-	*/
-	applyProjectStatePatch(patch) {
-		// watchedPaths guards {{{
-		if (this.settings.devMode && this.settings.debugPaths) {
-			if (!Array.isArray(this.settings.debugPaths)) throw new Error('teraFyClient.settings.debugPaths should be either null or an Array<String>');
-
-			let watchedPaths = patch
-				.filter(patch => this.settings.debugPaths.some(debugPath =>
-					patch.path.join('.').slice(0, debugPath.length) == debugPath
-				))
-				.map(patch => patch.path.join('.'));
-
-			if (watchedPaths.length > 0) {
-				console.info('Detected writes to', watchedPaths, '- entering debugging mode');
-				debugger; // eslint-disable-line no-debugger
-			}
-		}
-		// }}}
-
-		return this.rpc('applyProjectStatePatch', patch, {
-			session: this.settings.session,
-		});
-	}
-
-
-	// eslint-disable-next-line jsdoc/require-returns-check
-	/**
-	* Client function which accepts a patch from the server and applies it to local project state
-	* The patch should follow the [JSPatch](http://jsonpatch.com) standard
-	* This function is expected to be sub-classed by a plugin
-	*
-	* @param {Array} patch A JSPatch patch to apply
-	*
-	* @returns {Promise} A promise which will resolve when the operation has completed
-	*/
-	applyProjectStatePatchLocal(patch) { // eslint-disable-line
-		throw new Error('applyProjectStatePatchLocal() has not been sub-classed by a plugin');
-	}
-	// }}}
-
 	// Init - constructor(), init(), inject*() {{{
 
 	/**
@@ -1228,44 +1154,6 @@ export default class TeraFy {
 	*/
 
 
-	/**
-	* Force-Save the currently active project state
-	*
-	* @function saveProjectState
-	* @returns {Promise} A promise which resolves when the operation has completed
-	*/
-
-
-	/**
-	* Overwrite the entire project state with a new object
-	* You almost never want to use this function directly, see `setProjectState(path, value)` for a nicer wrapper
-	*
-	* @function replaceProjectState
-	* @see setProjectState()
-	* @param {Object} newState The new state to replace the current state with
-	* @returns {Promise} A promise which resolves when the operation has completed
-	*/
-
-
-	/**
-	* Apply a computed `just-diff` patch to the current project state
-	*
-	* @function applyProjectStatePatch
-	* @param {Object} Patch to apply
-	* @returns {Promise} A promise which resolves when the operation has completed
-	*/
-
-
-	/**
-	* Subscribe to project state changes
-	* This will dispatch an RPC call to the source object `applyProjectStatePatchLocal()` function with the patch
-	* If the above call fails the subscriber is assumed as dead and unsubscribed from the polling list
-	*
-	* @function subscribeProjectState
-	* @returns {Promise<Function>} A promise which resolves when a subscription has been created, call the resulting function to unsubscribe
-	*/
-
-
 	/**
 	* Data structure for a file filter
 	* @name FileFilters