@iebh/tera-fy 1.0.4 → 1.0.6

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

@@ -20,7 +20,7 @@ export default class TeraFy {
 	*/
 	settings = {
 		devMode: true,
-		siteUrl: 'http://localhost:5173/embed',
+		siteUrl: 'https://tera-tools.com/embed',
 		restrictOrigin: '*', // DEBUG: Need to restrict this to TERA site
 	};
 
@@ -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,54 +186,46 @@ export default class TeraFy {
 
 	// }}}
 
-	// Init - constructor(), toggleDevMode(), init(), injectMain(), injectStylesheet(), injectMethods() {{{
+	// Init - constructor(), init(), inject*() {{{
 
 	/**
 	* Setup the TERA-fy client singleton
 	*
-	* @param {Object} [options] Additional options to merge into `settings`
+	* @param {Object} [options] Additional options to merge into `settings` via `set`
 	*/
 	constructor(options) {
-		Object.assign(this.settings, options);
-	}
-
-
-	/**
-	* 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;
+		if (options) this.set(options);
 	}
 
 
 	/**
 	* 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);
@@ -240,12 +237,13 @@ export default class TeraFy {
 		this.dom.iframe.setAttribute('sandbox', 'allow-downloads allow-scripts allow-same-origin');
 		this.dom.iframe.addEventListener('load', ()=> {
 			this.debug('TERA 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);
-	}
+	})}
 
 
 	/**
@@ -306,20 +304,33 @@ export default class TeraFy {
 		this.methods.forEach(method =>
 			this[method] = this.rpc.bind(this, method)
 		);
+		this.debug('Remote methods installed:', this.methods);
 	}
 	// }}}
 
-	// Utility - debug(), use(), toggleFullscreen() {{{
+	// Utility - debug(), use(), mixin(), toggleDevMode(), toggleFocus() {{{
 
 	/**
 	* Debugging output function
 	* This function will only act if `settings.devMode` is truthy
 	*
+	* @param {'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,
@@ -359,24 +370,64 @@ export default class TeraFy {
 		if (typeof mod != 'function') throw new Error('Expected use() call to be provided with a class initalizer');
 
 		let singleton = new mod(this, options);
+		this.mixin(this, singleton);
+
 		this.plugins.push(singleton);
 		return this;
 	}
 
 
+	/**
+	* Internal function used by use() to merge an external declared singleton against this object
+	*
+	* @param {Object} target Initalied class instance to extend
+	* @param {Object} source Initalized source object to extend from
+	*/
+	mixin(target, source) {
+		Object.getOwnPropertyNames(Object.getPrototypeOf(source))
+			.filter(prop => !['constructor', 'prototype', 'name'].includes(prop))
+			.forEach((prop) => {
+				console.log('Merge method', prop);
+				Object.defineProperty(
+					target,
+					prop,
+					{
+						value: source[prop].bind(target),
+						enumerable: false,
+					},
+				);
+			});
+	}
+
+
+	/**
+	* 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,18 @@ 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
-		);
+			};
+			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);
+		}
+
 	}
 
 
@@ -497,7 +505,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,22 +1,27 @@
 {
   "name": "@iebh/tera-fy",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "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",
-    "lint": "eslint ./lib"
+    "build:docs": "jsdoc2md --files lib/terafy.*.js plugins/*.js >api.md",
+    "lint": "eslint ."
   },
   "type": "module",
   "imports": {
     "#terafy": "./lib/terafy.client.js"
   },
   "exports": {
-    ".": "./lib/terafy.client.js",
+    ".": {
+      "browser": "./lib/terafy.client.js",
+      "import": "./lib/terafy.client.js",
+      "require": "./dist/terafy.js",
+      "default": "./dist/terafy.js"
+    },
     "./server": "./lib/terafy.server.js",
-    "./plugins/*": "./lib/plugins/*.js"
+    "./plugins/*": "./plugins/*.js"
   },
   "repository": {
     "type": "git",

package/{lib/plugins → plugins}/vue.js

@@ -1,5 +1,5 @@
 import TeraFyPluginBase from './base.js';
-import diff from 'just-diff';
+import {diff} from 'just-diff';
 import {reactive, watch} from 'vue';
 
 /**
@@ -62,4 +62,46 @@ export default class TeraFyPluginVue extends TeraFyPluginBase {
 			})
 	}
 
+
+	/**
+	* Provide a Vue@3 compatible plugin
+	*/
+	vuePlugin() {
+		let $tera = this;
+
+		return {
+
+			/**
+			* Install into Vue as a generic Vue@3 plugin
+			*
+			* @param {Object} [options] Additional options to mutate behaviour
+			* @param {String} [options.globalName='$tera'] Globa property to allocate this service as
+			* @param {Objecct} [options.bindOptions] Options passed to `bindProjectState()`
+			*
+			* @returns {VuePlugin} A plugin matching the Vue@3 spec
+			*/
+			install(app, options) {
+				let settings = {
+					globalName: '$tera',
+					stateOptions: {
+						autoRequire: true,
+						write: true,
+					},
+					...options,
+				};
+
+				// Make this module available globally
+				app.config.globalProperties[settings.globalName] = $tera;
+
+				// Bind $tera.state to the active project
+				// TODO: context.bindProjectState(settings.stateOptions),
+				$tera.state = {
+					id: 'TERAPROJ',
+					name: 'A fake project',
+				};
+			},
+
+		};
+	}
+
 }