@iebh/tera-fy 1.0.2 → 1.0.4

package/index.html

@@ -225,10 +225,10 @@
 						<div class="card-body">
 							<div class="list-group">
 								<a
-									@click="run('getProjectStateSnapshot')"
+									@click="run('getProjectState')"
 									class="list-group-item list-group-item-action"
 								>
-									terafy.getProjectStateSnapshot()
+									terafy.getProjectState()
 								</a>
 								<a
 									@click="run('bindProjectState')"

package/lib/plugins/base.js

@@ -0,0 +1,24 @@
+/**
+* Base TeraFy plugin interface
+* This is included as a documentation exanple only
+*
+* @class TeraFyPlugin
+*/
+export default class TeraFyPlugin {
+
+	/**
+	* Optional function to be included when the main TeraFyClient is initalized
+	*/
+	init() {
+	}
+
+
+	/**
+	* Instance constructor
+	*
+	* @param {TeraFy} terafy The TeraFy client this plugin is being initalized against
+	* @param {Object} [options] Additional options to mutate behaviour
+	*/
+	constructor(terafy, options) {
+	}
+}

package/lib/plugins/vue.js

@@ -0,0 +1,65 @@
+import TeraFyPluginBase from './base.js';
+import diff from 'just-diff';
+import {reactive, watch} from 'vue';
+
+/**
+* Vue observables plugin
+* Provides the `bindProjectState()` function for Vue based projects
+*
+* This function is expected to be included via the `terafy.use(MODULE, OPTIONS)` syntax rather than directly
+*
+* @class TeraFyPluginVue
+*/
+export default class TeraFyPluginVue extends TeraFyPluginBase {
+
+	/**
+	* Return a Vue reactive object that can be read/written which whose changes will transparently be written back to the TERA server instance
+	*
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
+	* @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
+	*/
+	bindProjectState(options) {
+		let settings = {
+			autoRequire: true,
+			write: true,
+			...options,
+		};
+
+		return Promise.resolve()
+			.then(()=> settings.autoRequire && this.requireProject())
+			.then(()=> this.getProjectState({
+				autoRequire: false, // already handled this
+				paths: settings.paths,
+			}))
+			.then(snapshot => {
+				// Create initial reactive
+				let stateReactive = reactive(snapshot);
+
+				// Watch for remote changes and update
+				// FIXME: Not yet supported
+
+				// Watch for local writes and react
+				if (settings.write) {
+					watch(
+						stateReactive,
+						(newVal, oldVal) => {
+							let diff = diff(newVal, oldVal);
+							this.debug('APPLY DIFF', diff);
+							this.applyProjectStatePatch(diff);
+						},
+						{
+							deep: true,
+						},
+					);
+				}
+
+				// Return Vue Reactive
+				return stateReactive;
+			})
+	}
+
+}

package/lib/terafy.client.js

@@ -1,7 +1,5 @@
 import {cloneDeep} from 'lodash-es';
 import {nanoid} from 'nanoid';
-import {reactive, watch} from 'vue';
-import diff from 'just-diff';
 
 /* globals globalThis */
 
@@ -59,7 +57,7 @@ export default class TeraFy {
 		'bindProject', 'getProject', 'getProjects', 'setActiveProject', 'requireProject', 'selectProject',
 
 		// Project state
-		'getProjectStateSnapshot', 'applyProjectStatePatch',
+		'getProjectState', 'applyProjectStatePatch',
 		// bindProjectState() - See below
 
 		// Project Libraries
@@ -67,6 +65,13 @@ export default class TeraFy {
 	];
 
 
+	/**
+	* Loaded plugins via Use()
+	* @type {Array<TeraFyPlugin>}
+	*/
+	plugins = [];
+
+
 	// Messages - send(), sendRaw(), rpc(), acceptMessage() {{{
 
 	/**
@@ -214,6 +219,9 @@ export default class TeraFy {
 		this.injectMain();
 		this.injectStylesheet();
 		this.injectMethods();
+		return Promise.all(this.plugins
+			.map(plugin => plugin.init())
+		);
 	}
 
 
@@ -301,7 +309,7 @@ export default class TeraFy {
 	}
 	// }}}
 
-	// Utility - debug(), bindProjectState(), toggleFullscreen() {{{
+	// Utility - debug(), use(), toggleFullscreen() {{{
 
 	/**
 	* Debugging output function
@@ -320,64 +328,54 @@ export default class TeraFy {
 
 
 	/**
-	* Return a Vue reactive object that can be read/written which whose changes will transparently be written back to the TERA server instance
+	* Set or merge settings
+	* This function also routes 'special' keys like `devMode` to their internal handlers
+	*
+	* @param {String|Object} key Either a single setting key to set or an object to merge
+	* @param {*} value The value to set if `key` is a string
 	*
+	* @returns {TeraFy} This chainable terafy instance
+	*/
+	set(key, value) {
+		if (typeof key == 'string') {
+			this.settings[key] = value;
+		} else {
+			Object.assign(this.settings, key);
+		}
+
+		return this.toggleDevMode(this.settings.devMode);
+	}
+
+
+	/**
+	* Include a TeraFy client plugin
+	*
+	* @param {Object} The module function to include. Invoked as `(teraClient:TeraFy, options:Object)`
 	* @param {Object} [options] Additional options to mutate behaviour
-	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
-	* @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 {TeraFy} This chainable terafy instance
 	*/
-	bindProjectState(options) {
-		let settings = {
-			autoRequire: true,
-			write: true,
-			...options,
-		};
-
-		return Promise.resolve()
-			.then(()=> settings.autoRequire && this.requireProject())
-			.then(()=> this.getProjectStateSnapshot({
-				autoRequire: false, // already handled this
-				paths: settings.paths,
-			}))
-			.then(snapshot => {
-				// Create initial reactive
-				let stateReactive = reactive(snapshot);
-
-				// Watch for remote changes and update
-				// FIXME: Not yet supported
-
-				// Watch for local writes and react
-				if (settings.write) {
-					watch(
-						stateReactive,
-						(newVal, oldVal) => {
-							let diff = diff(newVal, oldVal);
-							this.debug('APPLY DIFF', diff);
-							this.applyProjectStatePatch(diff);
-						},
-						{
-							deep: true,
-						},
-					);
-				}
-
-				// Return Vue Reactive
-				return stateReactive;
-			})
+	use(mod, options) {
+		if (typeof mod != 'function') throw new Error('Expected use() call to be provided with a class initalizer');
+
+		let singleton = new mod(this, options);
+		this.plugins.push(singleton);
+		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

@@ -384,7 +384,7 @@ export default class TeraFyServer {
 
 	// }}}
 
-	// Project State - getProjectStateSnapshot(), applyProjectStatePatch() {{{
+	// Project State - getProjectState(), applyProjectStatePatch() {{{
 
 	/**
 	* Return the current, full snapshot state of the active project
@@ -395,7 +395,7 @@ export default class TeraFyServer {
 	*
 	* @returns {Promise<Object>} The current project state snapshot
 	*/
-	getProjectStateSnapshot(options) {
+	getProjectState(options) {
 		let settings = {
 			autoRequire: true,
 			paths: null,
@@ -404,6 +404,7 @@ export default class TeraFyServer {
 
 		return Promise.resolve()
 			.then(()=> settings.autoRequire && this.requireProject())
+			.then(()=> app.service('$projects').active)
 	}
 
 

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@iebh/tera-fy",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "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:client": "jsdoc2md --files lib/terafy.client.js >docs/terafy.client.md",
-    "build:docs:server": "jsdoc2md --files lib/terafy.server.js >docs/terafy.server.md"
+    "build:docs": "jsdoc2md --files lib/terafy.*.js lib/plugins/*.js >api.md",
+    "lint": "eslint ./lib"
   },
   "type": "module",
   "imports": {
@@ -15,7 +15,8 @@
   },
   "exports": {
     ".": "./lib/terafy.client.js",
-    "./server": "./lib/terafy.server.js"
+    "./server": "./lib/terafy.server.js",
+    "./plugins/*": "./lib/plugins/*.js"
   },
   "repository": {
     "type": "git",
@@ -53,9 +54,11 @@
     "node": ">=18"
   },
   "peerDependencies": {
-    "lodash-es": "^4.17.21",
     "just-diff": "^6.0.2",
-    "nanoid": "^5.0.2",
+    "lodash-es": "^4.17.21",
+    "nanoid": "^5.0.2"
+  },
+  "optionalDependencies": {
     "vue": "^3.3.7"
   },
   "devDependencies": {

package/docs/terafy.client.md

@@ -1,183 +0,0 @@
-## Classes
-
-<dl>
-<dt><a href="#TeraFy">TeraFy</a></dt>
-<dd></dd>
-</dl>
-
-## Functions
-
-<dl>
-<dt><a href="#send">send(message)</a> ⇒ <code>Promise.&lt;*&gt;</code></dt>
-<dd><p>Send a message + wait for a response object</p>
-</dd>
-<dt><a href="#sendRaw">sendRaw(message)</a></dt>
-<dd><p>Send raw message content to the server
-This function does not return or wait for a reply - use <code>send()</code> for that</p>
-</dd>
-<dt><a href="#rpc">rpc(method)</a> ⇒ <code>Promise.&lt;*&gt;</code></dt>
-<dd><p>Call an RPC function in the server instance</p>
-</dd>
-<dt><a href="#acceptMessage">acceptMessage(Raw)</a></dt>
-<dd><p>Accept an incoming message</p>
-</dd>
-<dt><a href="#toggleDevMode">toggleDevMode([devModeEnabled])</a> ⇒ <code><a href="#TeraFy">TeraFy</a></code></dt>
-<dd><p>Set or toggle devMode</p>
-</dd>
-<dt><a href="#init">init()</a></dt>
-<dd><p>Initalize the TERA client singleton</p>
-</dd>
-<dt><a href="#injectMain">injectMain()</a></dt>
-<dd><p>Find an existing active TERA server OR initalize one</p>
-</dd>
-<dt><a href="#injectStylesheet">injectStylesheet()</a></dt>
-<dd><p>Inject a local stylesheet to handle TERA server functionality</p>
-</dd>
-<dt><a href="#injectMethods">injectMethods()</a></dt>
-<dd><p>Inject all server methods defined in <code>methods</code> as local functions wrapped in the <code>rpc</code> function</p>
-</dd>
-<dt><a href="#debug">debug()</a></dt>
-<dd><p>Debugging output function
-This function will only act if <code>settings.devMode</code> is truthy</p>
-</dd>
-<dt><a href="#bindProjectState">bindProjectState([options], Paths)</a> ⇒ <code>Promies.&lt;Reactive.&lt;Object&gt;&gt;</code></dt>
-<dd><p>Return a Vue reactive object that can be read/written which whose changes will transparently be written back to the TERA server instance</p>
-</dd>
-<dt><a href="#toggleFocus">toggleFocus([isFocused])</a></dt>
-<dd><p>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</p>
-</dd>
-</dl>
-
-<a name="TeraFy"></a>
-
-## TeraFy
-**Kind**: global class  
-<a name="new_TeraFy_new"></a>
-
-### new TeraFy()
-Main Tera-Fy Client (class singleton) to be used in a frontend browser
-
-<a name="send"></a>
-
-## send(message) ⇒ <code>Promise.&lt;\*&gt;</code>
-Send a message + wait for a response object
-
-**Kind**: global function  
-**Returns**: <code>Promise.&lt;\*&gt;</code> - A promise which resolves when the operation has completed with the remote reply  
-
-| Param | Type | Description |
-| --- | --- | --- |
-| message | <code>Object</code> | Message object to send |
-
-<a name="sendRaw"></a>
-
-## sendRaw(message)
-Send raw message content to the server
-This function does not return or wait for a reply - use `send()` for that
-
-**Kind**: global function  
-
-| Param | Type | Description |
-| --- | --- | --- |
-| message | <code>Object</code> | Message object to send |
-
-<a name="rpc"></a>
-
-## rpc(method) ⇒ <code>Promise.&lt;\*&gt;</code>
-Call an RPC function in the server instance
-
-**Kind**: global function  
-**Returns**: <code>Promise.&lt;\*&gt;</code> - The resolved output of the server function  
-
-| Param | Type | Description |
-| --- | --- | --- |
-| method | <code>String</code> | The method name to call |
-| [...] | <code>\*</code> | Optional arguments to pass to the function |
-
-<a name="acceptMessage"></a>
-
-## acceptMessage(Raw)
-Accept an incoming message
-
-**Kind**: global function  
-
-| Param | Type | Description |
-| --- | --- | --- |
-| Raw | <code>MessageEvent</code> | message event to process |
-
-<a name="toggleDevMode"></a>
-
-## toggleDevMode([devModeEnabled]) ⇒ [<code>TeraFy</code>](#TeraFy)
-Set or toggle devMode
-
-**Kind**: global function  
-**Returns**: [<code>TeraFy</code>](#TeraFy) - This chainable terafy instance  
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| [devModeEnabled] | <code>String</code> \| <code>Boolean</code> | <code>&#x27;toggle&#x27;</code> | Optional boolean to force dev mode |
-
-<a name="init"></a>
-
-## init()
-Initalize the TERA client singleton
-
-**Kind**: global function  
-<a name="injectMain"></a>
-
-## injectMain()
-Find an existing active TERA server OR initalize one
-
-**Kind**: global function  
-<a name="injectStylesheet"></a>
-
-## injectStylesheet()
-Inject a local stylesheet to handle TERA server functionality
-
-**Kind**: global function  
-<a name="injectMethods"></a>
-
-## injectMethods()
-Inject all server methods defined in `methods` as local functions wrapped in the `rpc` function
-
-**Kind**: global function  
-<a name="debug"></a>
-
-## debug()
-Debugging output function
-This function will only act if `settings.devMode` is truthy
-
-**Kind**: global function  
-
-| Param | Type | Description |
-| --- | --- | --- |
-| [msg...] | <code>String</code> | Output to show |
-
-<a name="bindProjectState"></a>
-
-## bindProjectState([options], Paths) ⇒ <code>Promies.&lt;Reactive.&lt;Object&gt;&gt;</code>
-Return a Vue reactive object that can be read/written which whose changes will transparently be written back to the TERA server instance
-
-**Kind**: global function  
-**Returns**: <code>Promies.&lt;Reactive.&lt;Object&gt;&gt;</code> - A reactive object representing the project state  
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| [options] | <code>Object</code> |  | Additional options to mutate behaviour |
-| [options.autoRequire] | <code>Boolean</code> | <code>true</code> | Run `requireProject()` automatically before continuing |
-| [options.write] | <code>Boolean</code> | <code>true</code> | Allow local reactivity to writes - send these to the server |
-| Paths | <code>Array.&lt;String&gt;</code> |  | to subscribe to e.g. ['/users/'], |
-
-<a name="toggleFocus"></a>
-
-## toggleFocus([isFocused])
-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
-
-**Kind**: global function  
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| [isFocused] | <code>String</code> \| <code>Boolean</code> | <code>&#x27;toggle&#x27;</code> | Whether to fullscreen the embedded component |
-