@iebh/tera-fy 1.15.9 → 2.0.0

package/lib/terafy.server.js

@@ -469,6 +469,16 @@ export default class TeraFyServer {
 	}
 
 
+	/**
+	* Provide an object of credentials for 3rd party services like Firebase/Supabase
+	*
+	* @returns {Object} An object containing 3rd party service credentials
+	*/
+	getCredentials() {
+		return app.service('$auth').credentials;
+	}
+
+
 	/**
 	* In embed mode only - create a popup window and try to auth via that
 	*
@@ -736,6 +746,54 @@ export default class TeraFyServer {
 
 	// }}}
 
+	// Project namespaces - getNamespace(), setNamespace(), listNamespaces() {{{
+	/**
+	* Get a one-off snapshot of a namespace without mounting it
+	* This can be used for simpler apps which don't have their own reactive / observer equivelent
+	*
+	* @param {String} name The alias of the namespace, this should be alphanumeric + hyphens + underscores
+	*
+	* @returns {Promise<Object>} A promise which resolves to the namespace POJO state
+	*/
+	getNamespace(name) {
+		if (!/^[\w-]+$/.test(name)) throw new Error('Namespaces must be alphanumeric + hyphens + underscores');
+
+		return this.$syncro.getSnapshot(`project_namespaces::${this.$projects.active.id}::${name}`);
+	}
+
+
+	/**
+	* Set (or merge by default) a one-off snapshot over an existing namespace
+	* This can be used for simpler apps which don't have their own reactive / observer equivelent and just want to quickly set something
+	*
+	* @param {String} name The name of the namespace
+	* @param {Object} state The state to merge
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {'merge'|'set'} [options.method='merge'] How to handle the state. 'merge' (merge a partial state over the existing namespace state), 'set' (completely overwrite the existing namespace)
+	*
+	* @returns {Promise<Object>} A promise which resolves to the namespace POJO state
+	*/
+	setNamespace(name, state, options) {
+		if (!/^[\w--]+$/.test(name)) throw new Error('Namespaces must be alphanumeric + hyphens + underscores');
+		if (typeof state != 'object') throw new Error('State must be an object');
+
+		return this.$syncro.setSnapshot(`project_namespaces::${this.$projects.active.id}}::${name}`, state, {
+			method: options.method,
+		});
+	}
+
+
+	/**
+	* Return a list of namespaces available to the current project
+	*
+	* @returns {Promise<Array<Object>>} Collection of available namespaces for the current project
+	* @property {String} name The name of the namespace
+	*/
+	listNamespaces() {
+		return app.service('$projects').listNamespaces();
+	}
+	// }}}
+
 	// Project State - getProjectState(), setProjectState(), setProjectStateDefaults(), replaceProjectState(), applyProjectStatePatch() {{{
 
 	/**
@@ -819,13 +877,11 @@ export default class TeraFyServer {
 	* @param {String|Array<String>} [path] The sub-path within the project state to set, if unspecifed the entire target is used as a target and a save operation is forced
 	* @param {*} value The value to set as the default structure
 	* @param {Object} [options] Additional options to mutate behaviour, see setProjectState() for the full list of supported options
-	* @param {Boolean} [options.flush=true] Force a re-read from the server after setting, prevents race conditions with large objects. Calls `setProjectStateFlush()` after applying defaults
 	*
 	* @returns {Promise<*>} A promise which resolves to the eventual input value after defaults have been applied
 	*/
 	setProjectStateDefaults(path, value, options) {
 		let settings = {
-			flush: true,
 			...options,
 		};
 		if (!app.service('$projects').active) throw new Error('No active project');
@@ -841,7 +897,6 @@ export default class TeraFyServer {
 					...settings,
 				},
 			)
-				.then(()=> settings.flush && this.setProjectStateFlush())
 				.then(()=> pathTools.get(target, path));
 		} else { // Called as (value) - Populate entire project layout
 			pathTools.defaults(target, path);
@@ -850,26 +905,11 @@ export default class TeraFyServer {
 				newState: cloneDeep(target),
 			});
 			return this.saveProjectState()
-				.then(()=> settings.flush && this.setProjectStateFlush())
 				.then(()=> target);
 		}
 	}
 
 
-	/**
-	* Force copying local changes to the server
-	* This is only ever needed when saving large quantities of data that need to be immediately available
-	*
-	* @returns {Promise} A promise which resolves when the operation has completed
-	*/
-	setProjectStateFlush() {
-		this.debug('INFO', 1, 'Force project state flush!');
-		if (!app.service('$projects').active) throw new Error('No active project');
-		return app.service('$projects').active.$touchLocal()
-			.then(()=> null)
-	}
-
-
 	/**
 	* Force refetching the remote project state into local
 	*
@@ -1644,9 +1684,9 @@ export default class TeraFyServer {
 	*
 	* @param {Object} [options] Additional options to mutate behaviour
 	* @param {String} [options.body] Optional additional body text
+	* @param {Boolean} [options.isHtml=false] If truthy, treat the body as HTML
 	* @param {String} [options.value] Current or default value to display pre-filled
 	* @param {String} [options.title='Input required'] The dialog title to display
-	* @param {Boolean} [options.bodyHtml=false] If truthy, treat the body as HTML
 	* @param {String} [options.placeholder] Optional placeholder text
 	* @param {Boolean} [options.required=true] Treat nullish or empty inputs as a cancel operation
 	*
@@ -1655,7 +1695,7 @@ export default class TeraFyServer {
 	uiPrompt(text, options) {
 		let settings = {
 			body: '',
-			bodyHtml: false,
+			isHtml: false,
 			title: 'Input required',
 			value: '',
 			placeholder: '',
@@ -1674,7 +1714,7 @@ export default class TeraFyServer {
 				component: 'UiPrompt',
 				componentProps: {
 					body: settings.body,
-					bodyHtml: settings.bodyHtml,
+					isHtml: settings.isHtml,
 					placeholder: settings.placeholder,
 					value: settings.value,
 				},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iebh/tera-fy",
-  "version": "1.15.9",
+  "version": "2.0.0",
   "description": "TERA website worker",
   "scripts": {
     "dev": "esbuild --platform=browser --format=esm --bundle lib/terafy.client.js --outfile=dist/terafy.js --minify --serve --servedir=.",
@@ -72,6 +72,7 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@momsfriendlydevco/marshal": "^2.1.1",
     "detect-port": "^1.6.1",
     "filesize": "^10.1.4",
     "http-proxy": "^1.18.1",
@@ -91,6 +92,8 @@
     "nodemon": "^3.1.7"
   },
   "peerDependencies": {
+    "@supabase/supabase-js": "^2.48.1",
+    "firebase": "^11.3.1",
     "vue": "^3.0.0"
   },
   "optionalDependencies": {

package/plugins/firebase.js

@@ -0,0 +1,122 @@
+import {initializeApp as Firebase} from 'firebase/app';
+import {getFirestore as Firestore} from 'firebase/firestore';
+import {createClient as Supabase} from '@supabase/supabase-js'
+import Syncro from '../lib/syncro.js';
+import TeraFyPluginBase from './base.js';
+
+/**
+* Plugin which adds Firebase / Firestore support for namespace mounts
+*
+* @class TeraFyPluginFirebase
+*/
+export default class TeraFyPluginFirebase extends TeraFyPluginBase {
+
+	/**
+	* Lookup object of mounted Syncro objects by path
+	*
+	* @type {Object<Syncro>}
+	*/
+	syncros = {};
+
+
+	/**
+	* @interface
+	* The Syncro#reactive option to use when creating new Syncro instances
+	* This is expected to be overriden by other plugins
+	* If falsy the Syncro module will fall back to its internal (POJO only) getReactive() function
+	*
+	* @name getReactive
+	* @type {Function} A reactive function as defined in Syncro
+	*/
+
+
+	/**
+	* Setup Firebase + Firestore + Supabase
+	* Default credentials (Firebase + Supabase) will be retrieved from `getCredentials()` unless overriden here
+	*
+	* @param {Object} options Additional options to mutate behaviour (defaults to the main teraFy settings)
+	* @param {String} [options.firebaseApiKey] Firebase API key
+	* @param {String} [options.firebaseAuthDomain] Firebase authorized domain
+	* @param {String} [options.firebaseProjectId] Firebase project ID
+	* @param {String} [options.firebaseAppId] Firebase App ID
+	* @param {String} [options.supabaseUrl] Supabase URL
+	* @param {String} [options.supabaseKey] Supabase client key
+	*
+	* @returns {Promise} A Promise which will resolve when the init process has completed
+	*/
+	async init(options) {
+		let settings = {
+			firebaseApiKey: null,
+			firebaseAuthDomain: null,
+			firebaseProjectId: null,
+			firebaseAppId: null,
+			supabaseUrl: null,
+			supabaseKey: null,
+			...await this.getCredentials(),
+			...options,
+		};
+
+		let emptyValues = Object.keys(settings).filter(k => k === null);
+		if (emptyValues.length > 0)
+			throw new Error('Firebase plugin requires mandatory options: ' + emptyValues.join(', '));
+
+		Syncro.firebase = Firebase({
+			apiKey: settings.firebaseApiKey,
+			authDomain: settings.firebaseAuthDomain,
+			projectId: settings.firebaseProjectId,
+			appId: settings.firebaseAppId,
+		});
+		Syncro.firestore = Firestore(this.firebase);
+
+		Syncro.supabase = Supabase(settings.supabaseUrl, settings.supabaseKey);
+	}
+
+
+	/**
+	* Mount the given namespace against `namespaces[name]`
+	*
+	* @param {'_PROJECT'|String} name The name/Syncro path of the namespace to mount (or '_PROJECT' for the project mountpoint)
+	*
+	* @returns {Promise} A promise which resolves when the operation has completed
+	*/
+	_mountNamespace(name) {
+		let syncro; // The eventually bootstrapped Syncro object
+
+		return Promise.resolve()
+			.then(()=> this.requireProject())
+			.then(project => {
+				let path = name == '_PROJECT'
+					? `projects::${project.id}`
+					: `project_namespaces::${project.id}::${name}`;
+
+				syncro = this.syncros[name] = new Syncro(path, {
+					debug: (...msg) => this.debug(`SYNCRO://${path}`, ...msg),
+					getReactive: this.getReactive, // Try to inherit this instances getReactive prop, otherwise Syncro will fall back to its default
+				});
+
+				// Perform the mount action
+				return syncro.mount();
+			})
+			.then(()=> { // Assign local state
+				this.namespaces[name] = syncro.value;
+			})
+	}
+
+
+	/**
+	* Unmount the given namespace from `namespaces[name]`
+	*
+	* @param {String} name The name/Syncro path of the namespace to unmount
+	*
+	* @returns {Promise} A promise which resolves when the operation has completed
+	*/
+	_unmountNamespace(name) {
+		let syncro = this.syncros[name]; // Create local alias for Syncro before we detach it
+
+		// Detach local state
+		delete this.namespaces[name];
+		delete this.syncros[name];
+
+		return syncro.destroy(); // Trigger Syncro distruction
+	}
+}

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
 	*
@@ -175,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'))
-	}
 }