@iebh/tera-fy 1.0.10 → 1.0.11

package/lib/terafy.client.js

@@ -1,5 +1,6 @@
 import {diff, jsonPatchPathConverter as jsPatchConverter} from 'just-diff';
 import {cloneDeep} from 'lodash-es';
+import Mitt from 'mitt';
 import {nanoid} from 'nanoid';
 
 /* globals globalThis */
@@ -30,6 +31,13 @@ export default class TeraFy {
 	};
 
 
+	/**
+	* Event emitter subscription endpoint
+	* @type {Mitt}
+	*/
+	events = Mitt();
+
+
 	/**
 	* DOMElements for this TeraFy instance
 	*
@@ -61,9 +69,12 @@ export default class TeraFy {
 		// Projects
 		'bindProject', 'getProject', 'getProjects', 'setActiveProject', 'requireProject', 'selectProject',
 
-		// Project state
-		'getProjectState', 'applyProjectStatePatch', 'subscribeProjectState',
-		// bindProjectState() - See below
+		// Project State
+		'getProjectState', 'setProjectState', 'saveProjectState', 'replaceProjectState',
+
+		// Project State Patching + Subscribing
+		'applyProjectStatePatch', 'subscribeProjectState',
+		// bindProjectState() - See individual plugins
 
 		// Project files
 		'getProjectFiles',
@@ -190,6 +201,13 @@ export default class TeraFy {
 						response: e.toString(),
 					});
 				})
+		} else if (message?.action == 'event') {
+			return Promise.resolve()
+				.then(()=> this.events.emit(message.event, ...message.payload))
+				.catch(e => {
+					console.warn(`TERA-FY client threw while handling emitted event "${message.event}"`, {message});
+					throw e;
+				})
 		} else if (message?.id) {
 			this.debug(`Ignoring message ID ${message.id} - was meant for someone else?`);
 		} else {
@@ -273,6 +291,11 @@ export default class TeraFy {
 				this.injectStylesheet(),
 				this.injectMethods(),
 			]))
+			.then(()=> this.rpc('setServerMode', // Tell server what mode its in
+				this.settings.mode == 'child' ? 'embedded'
+				: this.settings.mode == 'parent' ? 'window'
+				: (()=> { throw(`Unknown server mode "${this.settings.mode}"`) })()
+			))
 			.then(()=> Promise.all( // Init all plugins (with this outer module as the context)
 				this.plugins.map(plugin =>
 					plugin.init.call(context)
@@ -317,6 +340,8 @@ export default class TeraFy {
 	injectComms() { return new Promise(resolve => {
 		switch (this.settings.mode) {
 			case 'child':
+				this.debug('Injecting TERA site as iFrame child');
+
 				this.dom.el = document.createElement('div')
 				this.dom.el.id = 'tera-fy';
 				this.dom.el.classList.toggle('dev-mode', this.settings.devMode);
@@ -336,6 +361,7 @@ export default class TeraFy {
 				this.dom.el.append(this.dom.iframe);
 				break;
 			case 'parent':
+				this.debug('Using TERA site stack parent');
 				resolve();
 				break;
 			default:
@@ -637,6 +663,45 @@ export default class TeraFy {
 	*/
 
 
+	/**
+	* Set a nested value within the project state
+	* Paths can be any valid Lodash.set() value such as:
+	*
+	*     - Dotted notation - e.g. `foo.bar.1.baz`
+	*     - Array path segments e.g. `['foo', 'bar', 1, 'baz']`
+	*
+	*
+	* @function setProjectState
+	* @param {String|Array<String>} path The sub-path within the project state to set
+	* @param {*} value The value to set
+	*
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {Boolean} [options.save=true] Save the changes to the server immediately, disable to queue up multiple writes
+	* @param {Boolean} [options.sync=false] Wait for the server to acknowledge the write, you almost never need to do this
+	*
+	* @returns {Promise} A promise which resolves when the operation has synced with the server
+	*/
+
+
+	/**
+	* 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
 	*

package/lib/terafy.server.js

@@ -1,6 +1,7 @@
 import {cloneDeep, set as pathSet} from 'lodash-es';
 import {diffApply, jsonPatchPathConverter as jsPatchConverter} from 'just-diff-apply';
 import {nanoid} from 'nanoid';
+import mixin from '#utils/mixin';
 
 /**
 * Server-side functions available to the Tera-Fy client library
@@ -19,15 +20,22 @@ export default class TeraFyServer {
 	* @property {Number} subscribeTimeout Acceptable timeout period for subscribers to acklowledge a project change event, failing to respond will result in the subscriber being removed from the available subscriber list
 	* @property {String} restrictOrigin URL to restrict communications to
 	* @property {String} projectId The project to use as the default reference when calling various APIs
+	* @property {Number} The current server mode matching `SERVERMODE_*`
 	*/
 	settings = {
 		devMode: false,
 		restrictOrigin: '*',
 		subscribeTimeout: 2000,
 		projectId: null,
+		serverMode: 0,
 	};
 
-	// Contexts - createContext(), messageEvent, senderRpc() {{{
+	static SERVERMODE_NONE = 0;
+	static SERVERMODE_EMBEDDED = 1;
+	static SERVERMODE_WINDOW = 2;
+
+
+	// Contexts - createContext(), getClientContext(), messageEvent, senderRpc() {{{
 	/**
 	* Create a context based on a shallow copy of this instance + additional functionality for the incoming MessageEvent
 	* This is used by acceptMessage to provide a means to reply / send messages to the originator
@@ -37,10 +45,10 @@ export default class TeraFyServer {
 	* @returns {Object} A context, which is this instance extended with additional properties
 	*/
 	createContext(e) {
-		// Rather ugly shallow-copy-of instancr hack from https://stackoverflow.com/a/44782052/1295040
-		return Object.assign(Object.create(Object.getPrototypeOf(this)), this, {
+		// Construct wrapper for sendRaw for this client
+		return mixin(this, {
 			messageEvent: e,
-			sendRaw(message) { // Override sendRaw because we can't do this inline for security reasons
+			sendRaw(message) {
 				let payload;
 				try {
 					payload = {
@@ -49,8 +57,7 @@ export default class TeraFyServer {
 					};
 					e.source.postMessage(payload, this.settings.restrictOrigin);
 				} catch (e) {
-					this.debug('ERROR', 'Message compose/reply via server->cient:', e);
-					this.debug('ERROR', 'Attempted to dispatch payload server(via reply)->client', payload);
+					this.debug('ERROR', 'Attempted to dispatch payload server(via reply)->client', {payload, e});
 					throw e;
 				}
 			},
@@ -58,6 +65,58 @@ export default class TeraFyServer {
 	}
 
 
+	/**
+	* Create a new client context from the server to the client even if the client hasn't requested the communication
+	* This function is used to send unsolicited communications from the server->client in contrast to createContext() which _replies_ from client->server->client
+	*
+	* @returns {Object} A context, which is this instance extended with additional properties
+	*/
+	getClientContext() {
+		switch (this.settings.serverMode) {
+			case TeraFyServer.SERVERMODE_NONE:
+				throw new Error('Client has not yet initiated communication');
+			case TeraFyServer.SERVERMODE_EMBEDDED:
+				// Server is inside an iFrame so we need to send messages to the window parent
+				return mixin(this, {
+					sendRaw(message) {
+						let payload;
+						try {
+							payload = {
+								TERA: 1,
+								...cloneDeep(message), // Need to clone to resolve promise nasties
+							};
+							window.parent.postMessage(payload, this.settings.restrictOrigin);
+						} catch (e) {
+							this.debug('ERROR', 'Attempted to dispatch payload server(iframe)->cient(top level window)', {payload, e});
+							throw e;
+						}
+					},
+				});
+			case TeraFyServer.SERVERMODE_WINDOW:
+				// Server is the top-level window so we need to send messages to an embedded iFrame
+				debugger; // FIXME: THIS IS ALL UNTESTED
+				let iFrame = document.querySelector('iframe#tera-fy');
+				if (!iFrame) throw new Error('Cannot locate TERA-FY client iFrame');
+
+				return mixin(this, {
+					sendRaw(message) {
+						let payload;
+						try {
+							payload = {
+								TERA: 1,
+								...cloneDeep(message), // Need to clone to resolve promise nasties
+							};
+							iFrame.postMessage(payload, this.settings.restrictOrigin);
+						} catch (e) {
+							this.debug('ERROR', 'Attempted to dispatch payload server(top level window)->cient(iframe)', {payload, e});
+							throw e;
+						}
+					},
+				});
+		}
+	}
+
+
 	/**
 	* MessageEvent context
 	* Only available if the context was created via `createContext()`
@@ -87,7 +146,7 @@ export default class TeraFyServer {
 	}
 	// }}}
 
-	// Messages - handshake(), sendRaw(), acceptMessage(), requestFocus() {{{
+	// Messages - handshake(), send(), sendRaw(), setServerMode(), acceptMessage(), requestFocus(), emitClients() {{{
 
 	/**
 	* Return basic server information as a form of validation
@@ -130,6 +189,7 @@ export default class TeraFyServer {
 
 	/**
 	* Send raw message content to the client
+	* Unlike send() this method does not expect any response
 	*
 	* @param {Object} message Message object to send
 	* @param {Window} Window context to dispatch the message via if its not the same as the regular window
@@ -141,13 +201,31 @@ export default class TeraFyServer {
 				TERA: 1,
 				...cloneDeep(message), // Need to clone to resolve promise nasties
 			};
-			this.debug('INFO', 'Parent reply', message, '<=>', payload);
+			this.debug('INFO', 'Parent send', message, '<=>', payload);
 			(sendVia || globalThis.parent).postMessage(payload, this.settings.restrictOrigin);
 		} catch (e) {
 			this.debug('ERROR', 'Attempted to dispatch payload server->client', payload);
 			this.debug('ERROR', 'Message compose server->client:', e);
 		}
+	}
+
 
+	/**
+	* Setter to translate between string inputs and the server modes in SERVERMODE_*
+	*
+	* @param {String} mode The server mode to set to
+	*/
+	setServerMode(mode) {
+		switch (mode) {
+			case 'embedded':
+				this.settings.serverMode = TeraFyServer.SERVERMODE_EMBEDDED;
+				break;
+			case 'window':
+				this.settings.serverMode = TeraFyServer.SERVERMODE_WINDOW;
+				break;
+			default:
+				throw new Error(`Unsupported server mode "${mode}"`);
+		}
 	}
 
 
@@ -217,6 +295,24 @@ export default class TeraFyServer {
 			.then(()=> cb.call(this))
 			.finally(()=> this.senderRpc('toggleFocus', false))
 	}
+
+
+	/**
+	* Emit messages down into all connected clients
+	* Note that emitted messages have no response - they are sent to clients only with no return value
+	*
+	* @param {String} event The event name to emit
+	* @param {*} [args...] Optional event payload to send
+	* @returns {Promise} A promise which resolves when the transmission has completed
+	*/
+	emitClients(event, ...args) {
+		return this.getClientContext().sendRaw({
+			action: 'event',
+			id: nanoid(),
+			event,
+			payload: args,
+		});
+	}
 	// }}}
 
 	// Session / User - getUser() {{{
@@ -409,7 +505,7 @@ export default class TeraFyServer {
 
 	// }}}
 
-	// Project State - getProjectState(), setProjectState(), saveProjectState(), applyProjectStatePatch(), subscribeProjectState() {{{
+	// Project State - getProjectState(), setProjectState(), saveProjectState(), replaceProjectState() {{{
 
 	/**
 	* Return the current, full snapshot state of the active project
@@ -483,6 +579,24 @@ export default class TeraFyServer {
 	}
 
 
+	/**
+	* 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
+	*
+	* @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
+	*/
+	replaceProjectState(newState) {
+		if (!app.service('$projects').active) throw new Error('No active project');
+		if (typeof newState != 'object') throw new Error('Only project state objects are accepted');
+
+		Object.assign(app.service('$projects').active, newState);
+		return this.saveProjectState();
+	}
+	// }}}
+
+	// Project State Patching + Subscribing - applyProjectStatePatch(), subscribeProjectState() {{{
 	/**
 	* Apply a computed `just-diff` patch to the current project state
 	*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iebh/tera-fy",
-  "version": "1.0.10",
+  "version": "1.0.11",
   "description": "TERA website worker",
   "scripts": {
     "dev": "esbuild --platform=browser --format=esm --bundle lib/terafy.client.js --outfile=dist/terafy.js --minify --sourcemap --serve --servedir=.",
@@ -12,7 +12,8 @@
   },
   "type": "module",
   "imports": {
-    "#terafy": "./lib/terafy.client.js"
+    "#terafy": "./lib/terafy.client.js",
+    "#utils/*": "./utils/*.js"
   },
   "exports": {
     ".": {
@@ -84,5 +85,9 @@
       "ecmaVersion": 13,
       "sourceType": "module"
     }
+  },
+  "dependencies": {
+    "@momsfriendlydevco/supabase-reactive": "^1.0.7",
+    "mitt": "^3.0.1"
   }
 }

package/plugins/vue2.js

@@ -78,19 +78,31 @@ export default class TeraFyPluginVue2 extends TeraFyPluginBase {
 				settings.component[settings.componentKey] = stateObservable;
 
 				// Watch for remote changes and update
-				// FIXME: Not yet supported
+				let skipUpdate = 0; // How many subsequent WRITE operations to ignore (set when reading)
+				if (settings.read) {
+					this.events.on(`update:projects/${stateReactive.id}`, newState => {
+						skipUpdate++; // Skip next update as we're updating our own state anyway
+						Object.assign(stateReactive, newState);
+					});
+				}
 
 				// Watch for local writes and react
 				if (settings.write) {
 					if (!settings.component) throw new Error('bindProjectState requires a VueComponent specified as `component`');
 
-					// NOTE: The below $watch function returns two copies of the new value of the observed so we have to keep track
-					//       of what changed ourselves by initalizing against the snapshot
+					// NOTE: The below $watch function returns two copies of the new value of the observed
+					//       so we have to keep track of what changed ourselves by initalizing against the
+					//       snapshot
 					let oldVal = cloneDeep(snapshot);
 
 					settings.component.$watch(
 						settings.componentKey,
 						newVal => {
+							if (skipUpdate > 0) {
+								skipUpdate--;
+								return;
+							}
+
 							this.createProjectStatePatch(newVal, oldVal);
 							oldVal = cloneDeep(snapshot);
 						},

package/plugins/vue3.js

@@ -30,6 +30,7 @@ export default class TeraFyPluginVue extends TeraFyPluginBase {
 	*
 	* @param {Object} [options] Additional options to mutate behaviour
 	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
+	* @param {Boolean} [options.read=true] Allow remote reactivity - update the local state when the server changes
 	* @param {Boolean} [options.write=true] Allow local reactivity to writes - send these to the server
 	*
 	* @returns {Promie<Reactive<Object>>} A reactive object representing the project state
@@ -37,6 +38,7 @@ export default class TeraFyPluginVue extends TeraFyPluginBase {
 	bindProjectState(options) {
 		let settings = {
 			autoRequire: true,
+			read: true,
 			write: true,
 			...options,
 		};
@@ -46,19 +48,30 @@ export default class TeraFyPluginVue extends TeraFyPluginBase {
 				autoRequire: settings.autoRequire ,
 			}))
 			.then(snapshot => {
-				this.debug('Got project snapshot', snapshot);
+				this.debug('Fetched project snapshot', snapshot);
 
 				// Create initial reactive
 				let stateReactive = reactive(snapshot);
 
 				// Watch for remote changes and update
-				// FIXME: Not yet supported
+				let skipUpdate = 0; // How many subsequent WRITE operations to ignore (set when reading)
+				if (settings.read) {
+					this.events.on(`update:projects/${stateReactive.id}`, newState => {
+						skipUpdate++; // Skip next update as we're updating our own state anyway
+						Object.assign(stateReactive, newState);
+					});
+				}
 
 				// Watch for local writes and react
 				if (settings.write) {
 					watch(
 						stateReactive,
 						(newVal, oldVal) => {
+							if (skipUpdate > 0) {
+								skipUpdate--;
+								return;
+							}
+
 							this.createProojectStatePatch(newVal, oldVal);
 						},
 						{

package/utils/mixin.js

@@ -0,0 +1,18 @@
+/**
+* Shallow-copy a object instance and inject new properties into the result
+*
+* Rather ugly shallow-copy-of instance hack from https://stackoverflow.com/a/44782052/1295040
+* Keeps the original object instance and overrides the given object of assignments
+*
+* @param {Object} instance Original object class instance to mixin
+* @param {Object} assignments Additional object properties to mix
+* @returns {Object} A shallow copy of the input instance extended with the assignments
+*/
+export default function mixin(instance, assignments) {
+	let output = Object.assign(
+		Object.create(Object.getPrototypeOf(instance)),
+		instance,
+		assignments,
+	);
+	return output;
+}