@iebh/tera-fy 1.15.8 → 2.0.0

package/plugins/vue2.js

@@ -1,17 +1,14 @@
-import {cloneDeep, debounce, isPlainObject} from 'lodash-es';
-import TeraFyPluginBase from './base.js';
+import {cloneDeep} from 'lodash-es';
+import TeraFyPluginFirebase from './firebase.js';
 
 /**
-* Vue2 observables plugin
-* Provides the `bindProjectState()` function for Vue based projects
+* Vue@2 observables plugin
 *
 * This function is expected to be included via the `terafy.use(MODULE, OPTIONS)` syntax rather than directly
 *
-* @class TeraFyPluginVue
-* @param {Object} options Options when initalizing
-* @param {Vue} options.Vue Vue instance to bind against
+* @class TeraFyPluginVue2
 *
-* @example Implementation within a Vue2 project `src/main.js`:
+* @example Implementation within a Vue@2 project `src/main.js`:
 * // Include the main Tera-Fy core
 * import TeraFy from '@iebh/tera-fy';
 * import TerafyVue from '@iebh/tera-fy/plugins/vue2';
@@ -27,7 +24,7 @@ import TeraFyPluginBase from './base.js';
 * app.$mount("#app");
 * await terafy.init({app});
 */
-export default class TeraFyPluginVue2 extends TeraFyPluginBase {
+export default class TeraFyPluginVue2 extends TeraFyPluginFirebase {
 
 	/**
 	* Local Vue@2 library to use, set during constuctor
@@ -37,6 +34,82 @@ export default class TeraFyPluginVue2 extends TeraFyPluginBase {
 	Vue;
 
 
+	/**
+	* The bound, reactive state of the active TERA project
+	*
+	* @type {Object}
+	*/
+	project = null;
+
+
+	/**
+	* Simple incrementor to ensure unique IDs for $watch expressions
+	*
+	* @type {Number{
+	*/
+	reactiveId = 1001;
+
+
+	/**
+	* Install into Vue@2
+	*
+	* @param {Object} options Additional options to mutate behaviour, see TeraFyPluginFirebase
+	* @param {Object} options.app Root level Vue app to bind against
+	* @param {Vue} options.Vue Vue@2 instance to bind against
+	* @param {String} [options.globalName='$tera'] Global property to allocate this service as within Vue2
+	* @param {*...} [options...] see TeraFyPluginFirebase
+	*
+	* @returns {Promise} A Promise which will resolve when the init process has completed
+	*/
+	async init(options) {
+		let settings = {
+			app: null,
+			Vue: null,
+			globalName: '$tera',
+			...options,
+		};
+
+		if (!settings.Vue) throw new Error('Vue instance to use must be specified in init options as `Vue`');
+		this.Vue = settings.Vue;
+
+		if (!settings.app) throw new Error('Vue Root / App instance to use must be specified in init options as `app`');
+		this.app = settings.app;
+
+		// Make this module available globally
+		if (settings.globalName)
+			this.Vue.prototype[settings.globalName] = this;
+
+		await super.init(settings); // Initalize parent class Firebase functionality
+
+		this.project = await this.mountNamespace('_PROJECT');
+	}
+
+
+	/** @override */
+	getReactive(value) {
+		let doc = this.Vue.observable(value);
+
+		let watcherPath = `_teraFy_${this.reactiveId++}`;
+		this.app[watcherPath] = doc; // Attach onto app so we can use $watch later on
+
+		return {
+			doc,
+			setState(state) {
+				// Shallow copy all sub-keys into existing object (keeping the object pointer)
+				Object.entries(state || {})
+					.forEach(([k, v]) => doc[k] = v)
+			},
+			getState() {
+				return cloneDeep(doc);
+			},
+			watch: cb => {
+				this.app.$watch(watcherPath, cb, {deep: true});
+			},
+		};
+	}
+
+
+
 	/**
 	* Return a Vue Observable object that can be read/written which whose changes will transparently be written back to the TERA server instance
 	*
@@ -123,10 +196,14 @@ export default class TeraFyPluginVue2 extends TeraFyPluginBase {
 					let oldVal = cloneDeep(snapshot);
 
 					// Function to handle the state update (can be debounced)
-					let watchHandle = newVal => {
+					let watchHandle = ()=> {
+						let newVal = cloneDeep(snapshot);
+
 						this.debug('INFO', 5, 'Update Vue2 Local->Remote', {new: newVal, old: oldVal});
 						this.createProjectStatePatch(newVal, oldVal);
-						oldVal = cloneDeep(snapshot);
+
+						// Set oldVal to the deep clone we just made so we can track the diff
+						oldVal = newVal;
 					};
 
 					settings.component.$watch(
@@ -171,89 +248,4 @@ export default class TeraFyPluginVue2 extends TeraFyPluginBase {
 		return target;
 	}
 
-
-
-	/**
-	* List of available projects for the current session
-	* Initalized during constructor
-	*
-	* @type {VueReactive<Array<Object>>}
-	*/
-	projects;
-
-
-	/**
-	* The bound, reactive state of a Vue project
-	* When loaded this represents the state of a project as an object
-	*
-	* @type {Object}
-	*/
-	state = null;
-
-
-	/**
-	* Install into Vue@2
-	*
-	* @param {Object} options Additional options to mutate behaviour (defaults to the main teraFy settings)
-	* @param {Object} options.app Root level Vue app to bind against
-	* @param {Vue} options.Vue Vue@2 instance to bind against
-	* @param {String} [options.globalName='$tera'] Global property to allocate this service as within Vue2
-	* @param {Boolean} [options.requireProject=true] Automatically call requireProject() prior to any operation
-	* @param {Boolean} [options.subscribeState=true] Setup `vm.$tera.state` as a live binding on init
-	* @param {Boolean} [options.subscribeList=true] Setup `vm.$tera.projects` as a list of accesible projects on init
-	* @param {Objecct} [options.stateOptions] Options passed to `bindProjectState()` when setting up the main state
-	*
-	* @returns {Promise} A Promise which will resolve when the init process has completed
-	*/
-	init(options) {
-		let settings = {
-			app: null,
-			Vue: null,
-			globalName: '$tera',
-			requireProject: true,
-			subscribeState: true,
-			subscribeProjects: true,
-			stateOptions: {
-				read: true,
-				write: true,
-			},
-			...options,
-		};
-
-		if (!settings.Vue) throw new Error('Vue instance to use must be specified in init options as `Vue`');
-		this.Vue = options.Vue;
-
-		if (!this.settings.app) throw new Error('Need to specify the root level Vue2 app during init');
-		settings.stateOptions.app = this.settings.app;
-
-		// Create observable binding for projects
-		this.projects = this.Vue.observable([])
-
-		// Make this module available globally
-		if (settings.globalName)
-			this.Vue.prototype[settings.globalName] = this;
-
-		// Bind `state` to the active project
-		// Initialize state to null
-		this.state = null;
-
-		// this.statePromisable becomes the promise we are waiting on to resolve
-		return Promise.resolve()
-			.then(()=> settings.requireProject && this.requireProject())
-			.then(()=> Promise.all([
-				// Bind available project and wait on it
-				settings.subscribeState && this.bindProjectState({
-					...settings.stateOptions,
-					component: this.settings.app.$root,
-				})
-					.then(state => this.state = state)
-					.then(()=> this.debug('INFO', 1, 'Loaded initial project state', this.state)),
-
-				// Fetch available projects
-				settings.subscribeProjects && this.getProjects()
-					.then(projects => this.projects = this.Vue.observable(projects))
-					.then(()=> this.debug('INFO', 2, 'Loaded project list', this.projects)),
-			]))
-			.then(()=> this.debug('INFO', 1, 'Ready'))
-	}
 }

package/plugins/vue3.js

@@ -1,14 +1,13 @@
-import {cloneDeep, debounce} from 'lodash-es';
-import TeraFyPluginBase from './base.js';
-import {reactive, watch} from 'vue';
+import {cloneDeep} from 'lodash-es';
+import TeraFyPluginFirebase from './firebase.js';
+import {markRaw, reactive as vueReactive, watch as vueWatch} 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
+* @class TeraFyPluginVue3
 *
 * @example Implementation within a Vue3 / Vite project within `src/main.js`:
 * import TeraFy from '@iebh/tera-fy';
@@ -23,120 +22,51 @@ import {reactive, watch} from 'vue';
 * app.use(terafy.vuePlugin({
 *   globalName: '$tera', // Install as vm.$tera into every component
 * }));
+*
+* @example Accessing project state - within a Vue component
+* this.$tera.active
 */
-export default class TeraFyPluginVue extends TeraFyPluginBase {
+export default class TeraFyPluginVue3 extends TeraFyPluginFirebase {
 
 	/**
-	* 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.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
-	* @param {Object} [options.throttle] Lodash debounce options + `wait` key used to throttle all writes, set to falsy to disable
+	* The bound, reactive state of the active TERA project
 	*
-	* @returns {Promie<Reactive<Object>>} A reactive object representing the project state
-	*/
-	bindProjectState(options) {
-		let settings = {
-			autoRequire: true,
-			read: true,
-			write: true,
-			throttle: {
-				wait: 200,
-				maxWait: 2000,
-				leading: false,
-				trailing: true,
-			},
-			...options,
-		};
-
-		return Promise.resolve()
-			.then(()=> this.getProjectState({
-				autoRequire: settings.autoRequire ,
-			}))
-			.then(snapshot => {
-				// Create initial reactive
-				let stateReactive = reactive(snapshot);
-
-				// Watch for remote changes and update
-				if (settings.read) {
-					this.events.on(`update:projects/${stateReactive.id}`, newState => {
-						if (
-							newState?.lastPatch?.session // Last state change had a session worth noting
-							&& newState.lastPatch.session == this.settings.session  // The last state update was made FROM INSIDE THE BUILDING! BUWHAHAHA!
-						)
-							return; // Discard it, we don't care
-
-						// Everything else - patch the remote state locally
-						Object.assign(stateReactive, newState);
-					});
-				}
-
-				// Watch for local writes and react
-				if (settings.write) {
-
-					// 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);
-
-					// Function to handle the state update (can be debounced)
-					let watchHandle = newVal => {
-						this.createProjectStatePatch(newVal, oldVal);
-						oldVal = cloneDeep(newVal); // Update old state the the last seen value
-					};
-
-					watch(
-						stateReactive, // State to watch
-						settings.throttle // Pointer to watchHandle which takes the new state (optionally throttled)
-							? debounce(watchHandle, settings.throttle.wait, settings.throttle)
-							: watchHandle,
-						{ // Watch options
-							deep: true,
-						},
-					);
-				}
-
-				// Return Vue Reactive
-				return stateReactive;
-			})
-	}
-
-
-	/**
-	* 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;
+	project = null;
 
 
 	/**
-	* Promise used when binding to state
-	* @type {Promise}
+	* Init the project including create a reactive mount for the active project
+	*
+	* @param {Object} options Additional options to mutate behaviour
+	* @param {*...} [options...] see TeraFyPluginFirebase
 	*/
-	statePromisable = null;
+	async init(options) {
+		await super.init(options); // Initalize parent class Firebase functionality
 
+		// Mount the project namespace
+		this.project = await this.mountNamespace('_PROJECT');
+	}
 
-	/**
-	* 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
-	*
-	* @returns {Promise} A promise representing the loading of the project state
-	*
-	* @example Await the state loading
-	* await $tera.statePromise();
-	*/
-	statePromise() {
-		return this.statePromisable;
+
+	/** @override */
+	getReactive(value) {
+		let doc = vueReactive(value);
+		return {
+			doc,
+			setState(state) {
+				// Shallow copy all sub-keys into existing object (keeping the object pointer)
+				Object.entries(state || {})
+					.forEach(([k, v]) => doc[k] = v)
+			},
+			getState() {
+				return cloneDeep(doc);
+			},
+			watch(cb) {
+				vueWatch(doc, cb, {deep: true});
+			},
+		};
 	}
 
 
@@ -156,43 +86,14 @@ export default class TeraFyPluginVue extends TeraFyPluginBase {
 			* @param {VueApp} app The Vue top-level app to install against
 			*
 			* @param {Object} [options] Additional options to mutate behaviour
-			* @param {Boolean} [options.autoInit=true] Call Init() during the `statePromiseable` cycle if its not already been called
-			* @param {String} [options.globalName='$tera'] Globa property to allocate this service as
-			* @param {Objecct} [options.bindOptions] Options passed to `bindProjectState()`
+			* @param {String} [options.globalName='$tera'] Global property to allocate this service as
 			*/
 			install(app, options) {
 				let settings = {
-					autoInit: true,
 					globalName: '$tera',
-					subscribeState: true,
-					subscribeProjects: true,
-					stateOptions: {
-						write: true,
-					},
 					...options,
 				};
 
-				// 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.resolve()
-					.then(()=> settings.autoInit && $tera.init())
-					.then(()=> Promise.all([
-						// Bind available project and wait on it
-						settings.subscribeState && $tera.bindProjectState(settings.stateOptions)
-							.then(state => $tera.state = state)
-							.then(()=> $tera.debug('INFO', 1, 'Loaded initial project state', $tera.state)),
-
-						// Fetch available projects
-						settings.subscribeProjects && $tera.getProjects()
-							.then(projects => $tera.projects = reactive(projects))
-							.then(()=> $tera.debug('INFO', 2, 'Loaded project list', $tera.projects)),
-					]))
-					.then(()=> $tera.debug('INFO', 1, 'Ready'))
-
-
 				// Make this module available globally
 				app.config.globalProperties[settings.globalName] = $tera;
 			},