@iebh/tera-fy 1.15.8 → 2.0.0

package/lib/terafy.client.js

@@ -105,6 +105,7 @@ export default class TeraFy {
 		// Session
 		'getUser',
 		'requireUser',
+		'getCredentials',
 
 		// Projects
 		'bindProject',
@@ -114,11 +115,17 @@ export default class TeraFy {
 		'requireProject',
 		'selectProject',
 
+		// Project namespaces
+		// 'mountNamespace', // Handled by this library
+		// 'unmountNamespace', // Handled by this library
+		'getNamespace',
+		'setNamespace',
+		'listNamespaces',
+
 		// Project State
 		'getProjectState',
 		'setProjectState',
 		'setProjectStateDefaults',
-		'setProjectStateFlush',
 		'setProjectStateRefresh',
 		'saveProjectState',
 		'replaceProjectState',
@@ -164,6 +171,16 @@ export default class TeraFy {
 	plugins = [];
 
 
+	/**
+	* Active namespaces we are subscribed to
+	* Each key is the namespace name with the value as the local reactive \ observer \ object equivelent
+	* The key string is always of the form `${ENTITY}::${ID}` e.g. `projects:1234`
+	*
+	* @type {Object<Object>}
+	*/
+	namespaces = {};
+
+
 	// Messages - send(), sendRaw(), rpc(), acceptMessage() {{{
 
 	/**
@@ -303,6 +320,68 @@ export default class TeraFy {
 
 	// }}}
 
+	// Project namespace - mountNamespace(), unmountNamespace() {{{
+	/**
+	* Make a namespace available locally
+	* This generally creates whatever framework flavoured reactive/observer/object is supported locally - generally with writes automatically synced with the master state
+	*
+	* @param {String} name The alias of the namespace, this should be alphanumeric + hyphens + underscores
+	*
+	* @returns {Promise<Reactive>} A promise which resolves to the reactive object
+	*/
+	mountNamespace(name) {
+		if (!/^[\w-]+$/.test(name)) throw new Error('Namespaces must be alphanumeric + hyphens + underscores');
+		if (this.namespaces[name]) return Promise.resolve(this.namespaces[name]); // Already mounted
+
+		return Promise.resolve()
+			.then(()=> this._mountNamespace(name))
+			.then(()=> this.namespaces[name] || Promise.reject(`teraFy.mountNamespace('${name}') resolved but no namespace has been mounted`))
+	}
+
+
+	/**
+	* @interface
+	* Actual namespace mounting function designed to be overriden by plugins
+	*
+	* @param {String} name The alias of the namespace, this should be alphanumeric + hyphens + underscores
+	*
+	* @returns {Promise} A promise which resolves when the mount operation has completed
+	*/
+	_mountNamespace(name) {
+		console.warn('teraFy._mountNamespace() has not been overriden by a TERA-fy plugin, load one to add this functionality for your preferred framework');
+		throw new Error('teraFy._mountNamespace() is not supported');
+	}
+
+
+	/**
+	* Release a locally mounted namespace
+	* This function will remove the namespace from `namespaces`, cleaning up any memory / subscription hooks
+	*
+	* @interface
+	*
+	* @param {String} name The name of the namespace to unmount
+	*
+	* @returns {Promise} A promise which resolves when the operation has completed
+	*/
+	unmountNamespace(name) {
+		if (!this.namespaces[name]) return Promise.resolve(); // Already unmounted
+		return this._unmountNamespace(name);
+	}
+
+
+	/**
+	* @interface
+	* Actual namespace unmounting function designed to be overriden by plugins
+	*
+	* @param {String} name The name of the namespace to unmount
+	*
+	* @returns {Promise} A promise which resolves when the operation has completed
+	*/
+	_unmountNamespace(name) {
+		console.warn('teraFy.unbindNamespace() has not been overriden by a TERA-fy plugin, load one to add this functionality for your preferred framework');
+	}
+	// }}}
+
 	// Project state - createProjectStatePatch(), applyProjectStatePatchLocal() {{{
 	/**
 	* Create + transmit a new project state patch base on the current and previous states
@@ -316,8 +395,13 @@ export default class TeraFy {
 	*/
 	createProjectStatePatch(newState, oldState) {
 		let patch = diff(oldState, newState);
-		this.debug('INFO', 3, 'Created project patch', {patch, newState, oldState});
-		return this.applyProjectStatePatch(patch);
+		if (patch.length == 0) {
+			this.debug('INFO', 4, 'Skipping empty project patch', {patch, newState, oldState});
+			return Promise.resolve();
+		} else {
+			this.debug('INFO', 3, 'Created project patch', {patch, newState, oldState});
+			return this.applyProjectStatePatch(patch);
+		}
 	}
 
 
@@ -329,6 +413,7 @@ export default class TeraFy {
 	* @returns {Promise} A promise which resolves when the operation has completed
 	*/
 	applyProjectStatePatch(patch) {
+		// watchedPaths guards {{{
 		if (this.settings.devMode && this.settings.debugPaths) {
 			if (!Array.isArray(this.settings.debugPaths)) throw new Error('teraFyClient.settings.debugPaths should be either null or an Array<String>');
 
@@ -343,6 +428,7 @@ export default class TeraFy {
 				debugger; // eslint-disable-line no-debugger
 			}
 		}
+		// }}}
 
 		return this.rpc('applyProjectStatePatch', patch, {
 			session: this.settings.session,
@@ -831,19 +917,35 @@ export default class TeraFy {
 	* @param {Object} source Initalized source object to extend from
 	*/
 	mixin(target, source) {
-		Object.getOwnPropertyNames(Object.getPrototypeOf(source))
-			.filter(prop => !['constructor', 'prototype', 'name'].includes(prop))
-			.filter(prop => prop != 'init') // Don't allow plugin init() to override our version - these all get called during init() anyway
-			.forEach((prop) => {
-				Object.defineProperty(
-					target,
-					prop,
-					{
-						value: source[prop].bind(target),
-						enumerable: false,
-					},
-				);
-			});
+		// Iterate through the source object upwards extracting each prototype
+		let prototypeStack = [];
+		let node = source;
+		do {
+			prototypeStack.unshift(node);
+		} while (node = Object.getPrototypeOf(node)); // Walk upwards until we hit null (no more inherited classes)
+
+		// Iterate through stacks inheriting each prop into the target
+		prototypeStack.forEach(stack =>
+			Object.getOwnPropertyNames(stack)
+				.filter(prop =>
+					!['constructor', 'init', 'prototype', 'name'].includes(prop) // Ignore forbidden properties
+					&& !prop.startsWith('__') // Ignore double underscore meta properties
+				)
+				.forEach(prop => {
+					if (typeof source[prop] == 'function') { // Inheriting function - glue onto object as non-editable, non-enumerable property
+						Object.defineProperty(
+							target,
+							prop,
+							{
+								enumerable: false,
+								value: source[prop].bind(target), // Rebind functions
+							},
+						);
+					} else { // Everything else, just glue onto the object
+						target[prop] = source[prop];
+					}
+				})
+		)
 	}
 
 
@@ -948,6 +1050,14 @@ export default class TeraFy {
 	*/
 
 
+	/**
+	* Provide an object of credentials for 3rd party services like Firebase/Supabase
+	*
+	* @functions getCredentials
+	* @returns {Object} An object containing 3rd party service credentials
+	*/
+
+
 	/**
 	* Require a user login to TERA
 	* If there is no user OR they are not logged in a prompt is shown to go and do so
@@ -1031,6 +1141,40 @@ export default class TeraFy {
 	*/
 
 
+	/**
+	* 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
+	*
+	* @function getNamespace
+	* @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
+	*/
+
+
+	/**
+	* 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
+	*
+	* @function setNamespace
+	* @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
+	*/
+
+
+	/**
+	* Return a list of namespaces available to the current project
+	*
+	* @function listNamespaces
+	* @returns {Promise<Array<Object>>} Collection of available namespaces for the current project
+	* @property {String} name The name of the namespace
+	*/
+
+
 	/**
 	* Return the current, full snapshot state of the active project
 	*
@@ -1074,15 +1218,6 @@ export default class TeraFy {
 	*/
 
 
-	/**
-	* Force copying local changes to the server
-	* This is only ever needed when saving large quantities of data that need to be immediately available
-	*
-	* @function setProjectStateFlush
-	* @returns {Promise} A promise which resolves when the operation has completed
-	*/
-
-
 	/**
 	* Force refetching the remote project state into local
 	* This is only ever needed when saving large quantities of data that need to be immediately available
@@ -1421,9 +1556,9 @@ export default class TeraFy {
 	*
 	* @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
 	*

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
 	*
@@ -928,6 +968,11 @@ export default class TeraFyServer {
 	*/
 	applyProjectStatePatch(patch, options) {
 		if (!app.service('$projects').active) throw new Error('No active project to patch');
+		if (patch.length == 0) {
+			this.debug('INFO', 4, 'Skipping empty project state patch', patch);
+			return Promise.resolve();
+		}
+
 		this.debug('INFO', 1, 'Applying', patch.length, 'project state patch', patch);
 
 		let $projects = app.service('$projects');
@@ -1639,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
 	*
@@ -1650,7 +1695,7 @@ export default class TeraFyServer {
 	uiPrompt(text, options) {
 		let settings = {
 			body: '',
-			bodyHtml: false,
+			isHtml: false,
 			title: 'Input required',
 			value: '',
 			placeholder: '',
@@ -1669,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.8",
+  "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",
@@ -82,15 +83,17 @@
     "release-it": "^17.6.0"
   },
   "devDependencies": {
-    "@momsfriendlydevco/eslint-config": "^2.0.3",
+    "@momsfriendlydevco/eslint-config": "^2.1.0",
     "@release-it/conventional-changelog": "^8.0.1",
     "concurrently": "^8.2.2",
     "documentation": "^14.0.3",
     "esbuild": "^0.23.0",
-    "eslint": "^9.7.0",
+    "eslint": "^9.18.0",
     "nodemon": "^3.1.7"
   },
   "peerDependencies": {
+    "@supabase/supabase-js": "^2.48.1",
+    "firebase": "^11.3.1",
     "vue": "^3.0.0"
   },
   "optionalDependencies": {

package/plugins/base.js

@@ -9,8 +9,7 @@ export default class TeraFyPlugin {
 	/**
 	* Optional function to be included when the main TeraFyClient is initalized
 	*/
-	init() {
-	}
+	init() {}
 
 
 	/**
@@ -19,6 +18,6 @@ export default class TeraFyPlugin {
 	* @param {TeraFy} terafy The TeraFy client this plugin is being initalized against
 	* @param {Object} [options] Additional options to mutate behaviour
 	*/
-	constructor(terafy, options) { // eslint-disable-line
+	constructor(terafy, options) { // eslint-disable-line no-unused-vars
 	}
 }

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
+	}
+}