@iebh/tera-fy 1.0.5 → 1.0.7

package/README.md

@@ -1,6 +1,30 @@
 TERA-fy
 =======
-TERA website worker.
+TERA website worker, intended to be embedded with TERA tools.
 
 * [API workbench](https://iebh.github.io/TERA-fy/)
 * [TERA-fy Class API](./api.md)
+
+
+TERA-fy is a component intended to be dropped into a sub-site / tool used with in the main [TERA](https://tera-tools.com) project. It provides various functionality like data sync with the parent TERA instance.
+
+
+Quick Start
+-----------
+
+```javascript
+import TeraFy from '@iebh/tera-fy';
+import TerafyVue from '@iebh/tera-fy/plugins/vue';
+let terafy = new TeraFy()
+	.set('devMode', true) // Set this option to see debugging messages
+	.use(TerafyVue); // Add the Vue plugin
+
+// Initialize everything
+await terafy.init();
+
+// Require that the active session has a project selected
+await terafy.requireProject();
+
+// Go fetch the state of the active project
+let projectState = await terafy.getProjectState(); //= Object representing the active project
+```

package/lib/terafy.client.js

@@ -105,14 +105,19 @@ export default class TeraFy {
 	* @param {Object} message Message object to send
 	*/
 	sendRaw(message) {
-		this.dom.iframe.contentWindow.postMessage(
-			{
+		let payload;
+		try {
+			payload = {
 				TERA: 1,
 				id: message.id || nanoid(),
 				...cloneDeep(message), // Need to clone to resolve promise nasties
-			},
-			this.settings.restrictOrigin
-		);
+			};
+			this.dom.iframe.contentWindow.postMessage(payload, this.settings.restrictOrigin);
+		} catch (e) {
+			this.debug('ERROR', 'Message compose client->server:', e);
+			this.debug('ERROR', 'Attempted to dispatch payload client->server', payload);
+			throw e;
+		}
 	}
 
 
@@ -181,7 +186,7 @@ export default class TeraFy {
 
 	// }}}
 
-	// Init - constructor(), toggleDevMode(), init(), injectMain(), injectStylesheet(), injectMethods() {{{
+	// Init - constructor(), init(), inject*() {{{
 
 	/**
 	* Setup the TERA-fy client singleton
@@ -193,42 +198,34 @@ export default class TeraFy {
 	}
 
 
-	/**
-	* Set or toggle devMode
-	*
-	* @param {String|Boolean} [devModeEnabled='toggle'] Optional boolean to force dev mode
-	*
-	* @returns {TeraFy} This chainable terafy instance
-	*/
-	toggleDevMode(devModeEnabled = 'toggle') {
-		this.settings.devMode = devModeEnabled === 'toggle'
-			? !this.settings.devMode
-			: devModeEnabled;
-
-		this.dom.el.classList.toggle('dev-mode', this.settings.devMode);
-		return this;
-	}
-
-
 	/**
 	* Initalize the TERA client singleton
+	*
+	* @returns {Promise<TeraFy>} An eventual promise which will resovle with this terafy instance
 	*/
 	init() {
 		window.addEventListener('message', this.acceptMessage.bind(this));
 
-		this.injectMain();
-		this.injectStylesheet();
-		this.injectMethods();
-		return Promise.all(this.plugins
-			.map(plugin => plugin.init())
-		);
+		return Promise.all([
+			// Init core functions async
+			this.injectComms(),
+			this.injectStylesheet(),
+			this.injectMethods(),
+
+			// Init all plugins
+			...this.plugins
+				.map(plugin => plugin.init()),
+		])
+			.then(()=> this)
 	}
 
 
 	/**
 	* Find an existing active TERA server OR initalize one
+	*
+	* @returns {Promise} A promise which will resolve when the loading has completed and we have found a parent TERA instance or initiallized a child
 	*/
-	injectMain() {
+	injectComms() { return new Promise(resolve => {
 		this.dom.el = document.createElement('div')
 		this.dom.el.id = 'tera-fy';
 		this.dom.el.classList.toggle('dev-mode', this.settings.devMode);
@@ -239,13 +236,14 @@ export default class TeraFy {
 		// Queue up event chain when document loads
 		this.dom.iframe.setAttribute('sandbox', 'allow-downloads allow-scripts allow-same-origin');
 		this.dom.iframe.addEventListener('load', ()=> {
-			this.debug('TERA EMBED FRAME READY');
+			this.debug('Embed frame ready');
+			resolve();
 		});
 
 		// Start document load sequence + append to DOM
 		this.dom.iframe.src = this.settings.siteUrl;
 		this.dom.el.append(this.dom.iframe);
-	}
+	})}
 
 
 	/**
@@ -309,17 +307,29 @@ export default class TeraFy {
 	}
 	// }}}
 
-	// Utility - debug(), use(), mixin(), toggleFullscreen() {{{
+	// Utility - debug(), use(), mixin(), toggleDevMode(), toggleFocus() {{{
 
 	/**
 	* Debugging output function
 	* This function will only act if `settings.devMode` is truthy
 	*
+	* @param {'VERBOSE'|'INFO'|'LOG'|'WARN'|'ERROR'} [status] Optional prefixing level to mark the message as. 'WARN' and 'ERROR' will always show reguardless of devMode being enabled
 	* @param {String} [msg...] Output to show
 	*/
 	debug(...msg) {
-		if (!this.settings.devMode) return;
-		console.log(
+		let method = 'log';
+		// Argument mangling for prefixing method {{{
+		if (typeof msg[0] == 'string' && ['INFO', 'LOG', 'WARN', 'ERROR'].includes(msg[0])) {
+			method = msg.shift().toLowerCase();
+		}
+		// }}}
+
+		if (
+			['INFO', 'LOG'].includes(method)
+			&& !this.settings.devMode
+		) return;
+
+		console[method](
 			'%c[TERA-FY CLIENT]',
 			'font-weight: bold; color: #ff5722;',
 			...msg,
@@ -389,18 +399,34 @@ export default class TeraFy {
 	}
 
 
+	/**
+	* Set or toggle devMode
+	*
+	* @param {String|Boolean} [devModeEnabled='toggle'] Optional boolean to force dev mode
+	*
+	* @returns {TeraFy} This chainable terafy instance
+	*/
+	toggleDevMode(devModeEnabled = 'toggle') {
+		this.settings.devMode = devModeEnabled === 'toggle'
+			? !this.settings.devMode
+			: devModeEnabled;
+
+		if (this.dom.el) // Have we actually set up yet?
+			this.dom.el.classList.toggle('dev-mode', this.settings.devMode);
+
+		return this;
+	}
+
+
 	/**
 	* Fit the nested TERA server to a full-screen
 	* This is usually because the server component wants to perform some user activity like calling $prompt
 	*
 	* @param {String|Boolean} [isFocused='toggle'] Whether to fullscreen the embedded component
-	*
-	* @returns {TeraFy} This chainable terafy instance
 	*/
 	toggleFocus(isFocused = 'toggle') {
 		this.debug('Request focus', {isFocused});
 		globalThis.document.body.classList.toggle('tera-fy-focus', isFocused === 'toggle' ? undefined : isFocused);
-		return this;
 	}
 	// }}}
 }

package/lib/terafy.server.js

@@ -31,18 +31,22 @@ export default class TeraFyServer {
 	* @returns {Object} A context, which is this instance extended with additional properties
 	*/
 	createContext(e) {
-		// Rather ugly shallow-copy-of instance hack from https://stackoverflow.com/a/44782052/1295040
+		// Rather ugly shallow-copy-of instancr hack from https://stackoverflow.com/a/44782052/1295040
 		return Object.assign(Object.create(Object.getPrototypeOf(this)), this, {
 			messageEvent: e,
 			sendRaw(message) { // Override sendRaw because we can't do this inline for security reasons
-				this.debug('Send to message source', e.origin, {message});
-				e.source.postMessage(
-					{
+				let payload;
+				try {
+					payload = {
 						TERA: 1,
 						...cloneDeep(message), // Need to clone to resolve promise nasties
-					},
-					this.settings.restrictOrigin
-				);
+					};
+					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);
+					throw e;
+				}
 			},
 		});
 	}
@@ -124,14 +128,19 @@ export default class TeraFyServer {
 	* @param {Object} message Message object to send
 	*/
 	sendRaw(message) {
-		this.debug('SendRaw', {message});
-		globalThis.parent.postMessage(
-			{
+		let payload;
+		try {
+			payload = {
 				TERA: 1,
 				...cloneDeep(message), // Need to clone to resolve promise nasties
-			},
-			this.settings.restrictOrigin
-		);
+			};
+			this.debug('INFO', 'Parent reply', message, '<=>', payload);
+			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);
+		}
+
 	}
 
 
@@ -161,10 +170,10 @@ export default class TeraFyServer {
 					throw new Error('Unknown message format');
 				}
 			})
-			.then(res => this.sendRaw({
+			.then(response => this.sendRaw({
 				id: message.id,
 				action: 'response',
-				response: res,
+				response,
 			}))
 			.catch(e => {
 				console.warn(`TERA-FY server threw on RPC:${message.method}:`, e);
@@ -497,7 +506,18 @@ export default class TeraFyServer {
 	* @param {String} [msg...] Output to show
 	*/
 	debug(...msg) {
-		if (!this.settings.devMode) return;
+		let method = 'log';
+		// Argument mangling for prefixing method {{{
+		if (typeof msg[0] == 'string' && ['INFO', 'LOG', 'WARN', 'ERROR'].includes(msg[0])) {
+			method = msg.shift().toLowerCase();
+		}
+		// }}}
+
+		if (
+			['INFO', 'LOG'].includes(method)
+			&& !this.settings.devMode
+		) return;
+
 		console.log(
 			'%c[TERA-FY SERVER]',
 			'font-weight: bold; color: #4d659c;',

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@iebh/tera-fy",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "TERA website worker",
   "scripts": {
     "dev": "esbuild --platform=browser --format=esm --bundle lib/terafy.client.js --outfile=dist/terafy.js --minify --sourcemap --serve --servedir=.",
     "build": "concurrently 'npm:build:*'",
     "build:client": "esbuild --platform=browser --format=esm --bundle lib/terafy.client.js --outfile=dist/terafy.js --minify --sourcemap",
-    "build:docs": "jsdoc2md --files lib/terafy.*.js lib/plugins/*.js >api.md",
+    "build:docs": "jsdoc2md --files lib/terafy.*.js plugins/*.js >api.md",
     "lint": "eslint ."
   },
   "type": "module",

package/plugins/vue.js

@@ -20,7 +20,7 @@ export default class TeraFyPluginVue extends TeraFyPluginBase {
 	* @param {Boolean} [options.write=true] Allow local reactivity to writes - send these to the server
 	* @param {Array<String>} Paths to subscribe to e.g. ['/users/'],
 	*
-	* @returns {Promies<Reactive<Object>>} A reactive object representing the project state
+	* @returns {Promie<Reactive<Object>>} A reactive object representing the project state
 	*/
 	bindProjectState(options) {
 		let settings = {
@@ -36,6 +36,8 @@ export default class TeraFyPluginVue extends TeraFyPluginBase {
 				paths: settings.paths,
 			}))
 			.then(snapshot => {
+				this.debug('Got project snapshot', snapshot);
+
 				// Create initial reactive
 				let stateReactive = reactive(snapshot);
 
@@ -63,11 +65,45 @@ export default class TeraFyPluginVue extends TeraFyPluginBase {
 	}
 
 
+	/**
+	* List of available projects for the current session
+	* @type {VueReactive<Array<Object>>}
+	*/
+	projects = reactive([]);
+
+
+	/**
+	* The bound, reactive state of a Vue project
+	* When loaded this represents the state of a project as an object
+	* @type {Object}
+	*/
+	state = null;
+
+
+	/**
+	* Promise used when binding to state
+	* @type {Promise}
+	*/
+	statePromisable = null;
+
+
+	/**
+	* Utility function which returns an awaitable promise when the state is loading or being refreshed
+	* This is used in place of `statePromisable` as it has a slightly more logical syntax as a function
+	*
+	* @example Await the state loading
+	* await $tera.statePromise();
+	*/
+	statePromise() {
+		return this.statePromisable;
+	}
+
+
 	/**
 	* Provide a Vue@3 compatible plugin
 	*/
 	vuePlugin() {
-		let context = this;
+		let $tera = this;
 
 		return {
 
@@ -90,10 +126,28 @@ export default class TeraFyPluginVue extends TeraFyPluginBase {
 					...options,
 				};
 
-				app.config.globalProperties[settings.globalName] = {
-					// Create project binding
-					// state: context.bindProjectState(settings.stateOptions),
-				};
+				// Bind $tera.state to the active project
+				// Initialize state to null
+				$tera.state = null;
+
+				// $tera.statePromisable becomes the promise we are waiting on to resolve
+				$tera.statePromisable = Promise.all([
+
+					// Bind available project and wait on it
+					$tera.bindProjectState(settings.stateOptions)
+						.then(state => $tera.state = state)
+						.then(()=> $tera.debug('INFO', 'Loaded project state', $tera.state)),
+
+					// Fetch available projects
+					// TODO: It would be nice if this was responsive to remote changes
+					$tera.getProjects()
+						.then(projects => $tera.projects = projects)
+						.then(()=> $tera.debug('INFO', 'Loaded projects', $tera.list)),
+				])
+
+
+				// Make this module available globally
+				app.config.globalProperties[settings.globalName] = $tera;
 			},
 
 		};