@iebh/tera-fy 1.5.0 → 1.6.1

package/lib/terafy.client.js

@@ -101,6 +101,8 @@ export default class TeraFy {
 		'getProjectState',
 		'setProjectState',
 		'setProjectStateDefaults',
+		'setProjectStateFlush',
+		'setProjectStateRefresh',
 		'saveProjectState',
 		'replaceProjectState',
 		'applyProjectStatePatch',
@@ -331,25 +333,34 @@ export default class TeraFy {
 
 		const context = this;
 		return this.init.promise = Promise.resolve()
+			.then(()=> this.debug('INFO', 4, '[0/5] Init using server', this.settings.siteUrl))
 			.then(()=> this.detectMode())
-			.then(mode => this.settings.mode = mode)
+			.then(mode => {
+				this.debug('INFO', 4, '[1/5] Setting client mode to', mode);
+				this.settings.mode = mode;
+			})
+			.then(()=> this.debug('INFO', 4, '[2/5] Injecting comms + styles + methods'))
 			.then(()=> Promise.all([
 				// Init core functions async
 				this.injectComms(),
 				this.injectStylesheet(),
 				this.injectMethods(),
 			]))
+			.then(()=> this.debug('INFO', 4, '[3/5] Set server mode'))
 			.then(()=> this.rpc('setServerMode', // Tell server what mode its in
 				this.settings.mode == 'child' ? 'embedded'
 				: this.settings.mode == 'parent' ? 'frame'
 				: this.settings.mode == 'popup' ? 'popup'
 				: (()=> { throw(`Unknown server mode "${this.settings.mode}"`) })()
 			))
+			.then(()=> this.debug('INFO', 4, '[4/5] Run client plugins'))
 			.then(()=> Promise.all( // Init all plugins (with this outer module as the context)
 				this.plugins.map(plugin =>
 					plugin.init.call(context, this.settings)
 				)
 			))
+			.then(()=> this.debug('INFO', 4, '[5/5] Init complete'))
+			.catch(e => this.debug('WARN', 0, 'Init caught error', e))
 	}
 
 
@@ -816,6 +827,24 @@ 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
+	*
+	* @function setProjectStateRefresh
+	* @returns {Promise} A promise which resolves when the operation has completed
+	*/
+
+
 	/**
 	* Force-Save the currently active project state
 	*
@@ -918,11 +947,11 @@ export default class TeraFy {
 	/**
 	* Fetch a project file
 	*
-	* @param {String} path File path to read
+	* @param {String} id File ID to read
 	* @returns {Promise<Blob>} The eventual fetched file as a blob
 	*/
-	getProjectFile(path) {
-		return this.rpc('getProjectFile', path)
+	getProjectFile(id) {
+		return this.rpc('getProjectFile', id)
 			.then(file => file
 				? new ProjectFile({
 					tera: this,
@@ -937,7 +966,7 @@ export default class TeraFy {
 	* Replace a project files contents
 	*
 	* @function setProjectFile
-	* @param {String} path File path to write
+	* @param {String} id File to overwrite
 	* @param {File|Blob|FormData|Object|Array} contents The new file contents
 	* @returns {Promise} A promise which will resolve when the write operation has completed
 	*/
@@ -966,7 +995,7 @@ export default class TeraFy {
 	* Fetch + convert a project file into a library of citations
 	*
 	* @function getProjectLibrary
-	* @param {String} path File path to read, if omitted the contents of `options` are used to guess at a suitable file
+	* @param {String} id File ID to read
 	*
 	* @param {Object} [options] Additional options to mutate behaviour
 	* @param {String} [options.format='json'] Format for the file. ENUM: 'pojo' (return a parsed JS collection), 'blob' (raw JS Blob object), 'file' (named JS File object)
@@ -982,17 +1011,17 @@ export default class TeraFy {
 	* Save back a citation library from some input
 	*
 	* @function setProjectLibrary
-	* @param {String} [path] File path to save back to, if omitted one will be prompted for
+	* @param {String} [id] File ID to save back to, if omitted a file will be prompted for
 	* @param {Array<RefLibRef>|Blob|File} [refs] Collection of references for the selected library or the raw Blob/File
 	*
 	* @param {Object} [options] Additional options to mutate behaviour
-	* @param {String} [options.path] Alternate method to specify the path to save as, if omitted one will be prompted for
+	* @param {String} [options.id] Alternate method to specify the file ID to save as, if omitted one will be prompted for
 	* @param {Array<RefLibRef>|Blob|File} [options.refs] Alternate method to specify the refs to save as an array or raw Blob/File
 	* @param {String} [options.format='json'] Input format used. ENUM: 'pojo' (return a parsed JS collection), 'blob' (raw JS Blob object), 'file' (named JS File object)
 	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
 	* @param {String} [options.hint] Hint to store against the library. Generally corresponds to the current operation being performed - e.g. 'deduped'
-	* @param {String} [options.filename] Suggested filename if path is unspecified
-	* @param {String} [options.title='Save citation library'] Dialog title if path is unspecified and we need to prompt
+	* @param {String} [options.filename] Suggested filename if `id` is unspecified
+	* @param {String} [options.title='Save citation library'] Dialog title if `id` is unspecified and a prompt is necessary
 	* @param {Boolean} [options.overwrite=true] Allow existing file upsert
 	* @param {Object} [options.meta] Optional meta data to merge into the file data
 	*

package/lib/terafy.server.js

@@ -757,10 +757,15 @@ 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');
 
 		let target = app.service('$projects').active;
@@ -771,18 +776,52 @@ export default class TeraFyServer {
 				value,
 				{
 					strategy: 'defaults',
-					...options,
+					...settings,
 				},
 			)
+				.then(()=> settings.flush && this.setProjectStateFlush())
 				.then(()=> pathTools.get(target, path));
 		} else { // Called as (value) - Populate entire project layout
 			pathTools.defaults(target, path);
+			this.debug('INFO', 1, 'setProjectStateDefaults', {
+				defaults: path,
+				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
+	*
+	* @returns {Promise} A promise which resolves when the operation has completed
+	*/
+	setProjectStateRefresh() {
+		this.debug('INFO', 1, 'Force project state refresh!');
+		if (!app.service('$projects').active) throw new Error('No active project');
+		return app.service('$projects').active.$read({force: true})
+			.then(()=> this.debug('INFO', 2, 'Forced project state refresh!', {state: app.service('$projects').active}))
+			.then(()=> null)
+	}
+
+
 	/**
 	* Force-Save the currently active project state
 	*
@@ -951,11 +990,11 @@ export default class TeraFyServer {
 
 	/**
 	* Fetch a project file
-	* @param {String} path File path to read
+	* @param {String} id File ID to read
 	* @returns {Promise<Blob>} The eventual fetched file as a blob
 	*/
-	getProjectFile(path) {
-		return app.service('$supabase').fileGet(path, {
+	getProjectFile(id) {
+		return app.service('$supabase').fileGet(app.service('$projects').decodeFilePath(id), {
 			toast: false,
 		});
 	}
@@ -964,12 +1003,12 @@ export default class TeraFyServer {
 	/**
 	* Replace a project files contents
 	*
-	* @param {String} path File path to write
+	* @param {String} id File to overwrite
 	* @param {File|Blob|FormData|Object|Array} contents The new file contents
 	* @returns {Promise} A promise which will resolve when the write operation has completed
 	*/
-	setProjectFile(path, contents) {
-		return app.service('$supabase').fileSet(path, contents, {
+	setProjectFile(id, contents) {
+		return app.service('$supabase').fileSet(app.service('$projects').decodeFilePath(id), contents, {
 			overwrite: true,
 			toast: false,
 		});
@@ -1019,7 +1058,7 @@ export default class TeraFyServer {
 	/**
 	* Fetch + convert a project file into a library of citations
 	*
-	* @param {String} path File path to read, if omitted the contents of `options` are used to guess at a suitable file
+	* @param {String} id File ID to read
 	*
 	* @param {Object} [options] Additional options to mutate behaviour
 	* @param {String} [options.format='json'] Format for the file. ENUM: 'pojo' (return a parsed JS collection), 'blob' (raw JS Blob object), 'file' (named JS File object)
@@ -1029,7 +1068,7 @@ export default class TeraFyServer {
 	*
 	* @returns {Promise<Array<Ref>>|Promise<*>} A collection of references (default bevahiour) or a whatever format was requested
 	*/
-	getProjectLibrary(path, options) {
+	getProjectLibrary(id, options) {
 		let settings = {
 			format: 'pojo',
 			autoRequire: true,
@@ -1038,9 +1077,11 @@ export default class TeraFyServer {
 			...options,
 		};
 
+		let filePath = app.service('$projects').decodeFilePath(id);
+
 		return Promise.resolve()
 			.then(()=> settings.autoRequire && this.requireProject())
-			.then(()=> app.service('$supabase').fileGet(path, {
+			.then(()=> app.service('$supabase').fileGet(filePath, {
 				toast: false,
 			}))
 			.then(blob => {
@@ -1050,7 +1091,7 @@ export default class TeraFyServer {
 						return Reflib.uploadFile({
 							file: new File(
 								[blob],
-								app.service('$supabase')._parsePath(path).basename,
+								app.service('$supabase')._parsePath(filePath).basename,
 							),
 						});
 					case 'blob':
@@ -1058,7 +1099,7 @@ export default class TeraFyServer {
 					case 'file':
 						return new File(
 							[blob],
-							app.service('$supabase')._parsePath(path).basename,
+							app.service('$supabase')._parsePath(filePath).basename,
 						);
 					default:
 						throw new Error(`Unsupported library format "${settings.format}"`);
@@ -1070,23 +1111,23 @@ export default class TeraFyServer {
 	/**
 	* Save back a citation library from some input
 	*
-	* @param {String} [path] File path to save back to, if omitted one will be prompted for
+	* @param {String} [id] File ID to save back to, if omitted a file will be prompted for
 	* @param {Array<RefLibRef>|Blob|File} [refs] Collection of references for the selected library or the raw Blob/File
 	*
 	* @param {Object} [options] Additional options to mutate behaviour
-	* @param {String} [options.path] Alternate method to specify the path to save as, if omitted one will be prompted for
+	* @param {String} [options.id] Alternate method to specify the file ID to save as, if omitted one will be prompted for
 	* @param {Array<RefLibRef>|Blob|File} [options.refs] Alternate method to specify the refs to save as an array or raw Blob/File
 	* @param {String} [options.format='auto'] Input format used. ENUM: 'auto' (try to figure it out from context), 'pojo' (JS array of RefLib references), 'blob' (raw JS Blob object), 'file' (named JS File object)
 	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
 	* @param {String|Array<String>} [options.hint] Hint(s) to store against the library. Generally corresponds to the current operation being performed - e.g. 'deduped'
-	* @param {String} [options.filename] Suggested filename if path is unspecified
-	* @param {String} [options.title='Save citation library'] Dialog title if path is unspecified and we need to prompt
+	* @param {String} [options.filename] Suggested filename if `id` is unspecified
+	* @param {String} [options.title='Save citation library'] Dialog title if `id` is unspecified and a prompt is necessary
 	* @param {Boolean} [options.overwrite=true] Allow existing file upsert
 	* @param {Object} [options.meta] Optional meta data to merge into the file data
 	*
 	* @returns {Promise} A promise which resolves when the save operation has completed
 	*/
-	setProjectLibrary(path, refs, options) {
+	setProjectLibrary(id, refs, options) {
 		let settings = {
 			format: 'auto',
 			autoRequire: true,
@@ -1096,17 +1137,18 @@ export default class TeraFyServer {
 			overwrite: true,
 			meta: null,
 			...(
-				typeof path == 'string' && Array.isArray(refs) ? {path, refs, ...options} // Called as (path, refs, options?)
-				: Array.isArray(path) || refs instanceof Blob || refs instanceof File ? {refs: path, ...refs} // Called as (refs, options?)
-				: path // Called as (options?)
+				typeof id == 'string' && Array.isArray(refs) ? {id, refs, ...options} // Called as (id, refs, options?)
+				: Array.isArray(id) || refs instanceof Blob || refs instanceof File ? {refs: id, ...refs} // Called as (refs, options?)
+				: id // Called as (options?)
 			)
 		};
 		if (!settings.refs) throw new Error('No refs to save');
 
+		let filePath; // Eventual Supabase path to use
 		return Promise.resolve()
 			.then(()=> settings.autoRequire && this.requireProject())
 			.then(()=> {
-				if (settings.path) return; // We already have a file path specified - skip
+				if (settings.id) return; // We already have a file ID specified - skip
 
 				// Prompt for a save filename
 				return this.selectProjectFile({
@@ -1119,14 +1161,11 @@ export default class TeraFyServer {
 					},
 					autoRequire: false, // Handled above anyway
 				})
-					.then(path => settings.path = path)
+					.then(file => settings.id = file.id)
 			})
-			.then(()=> { // Correct filename to a full path if needed
-				if (!/^\/.+\/.+/.test(settings.path)) { // Not already a qualified full path for a project
-					settings.path = `/projects/${app.service('$projects').active.id}/${settings.path}`;
-				}
-
-				this.debug('INFO', 2, 'Save citation library as', path);
+			.then(()=> { // Compute filePath
+				filePath = app.service('$projects').decodeFilePath(settings.id);
+				debugger; // FIXME: Untested
 			})
 			.then(()=> {
 				// Mutate settings.ref -> Blob or File format needed by Supabase
@@ -1145,12 +1184,12 @@ export default class TeraFyServer {
 
 						// Get Reflib to encode the POJO into a Blob/File
 						return Reflib.downloadFile(settings.refs, {
-							filename: settings.path,
+							filename: app.service('$supabase')._parsePath(filePath).filename,
 							promptDownload: false, // Just return the fileBlob we hand to Supabase
 						})
 					case 'blob':
 						if (!(settings.refs instanceof Blob)) throw new Error("setProjectLibrary({format: 'blob'} but non-Blob provided as `refs`");
-						return new File([settings.refs], app.service('$supabase')._parsePath(settings.path).basename);
+						return new File([settings.refs], app.service('$supabase')._parsePath(filePath).basename);
 					case 'file':
 						if (!(settings.ref instanceof File)) throw new Error("setProjectLibrary({format: 'file'} but non-File provided as `refs`");
 						return settings.refs;
@@ -1158,13 +1197,7 @@ export default class TeraFyServer {
 						throw new Error(`Unsupported library format "${settings.format}"`);
 				}
 			})
-			.then(fileBlob => app.service('$supabase').fileUpload(settings.path, {
-				file: fileBlob,
-				mode: 'encoded',
-				overwrite: true,
-				meta: settings.meta,
-				transcoders: false, // We can skip transcoders as we are supplying the meta information above anyway
-			}))
+			.then(fileBlob => app.service('$supabase').fileUpload(filePath))
 	}
 
 	// }}}
@@ -1183,7 +1216,7 @@ export default class TeraFyServer {
 	}
 	// }}}
 
-	// Webpages - setPageUrl() {{{
+	// Webpages - setPageUrl(), setPageTitle {{{
 
 	/**
 	* Set an active tools URL (or path) so that it survives a refresh
@@ -1196,7 +1229,8 @@ export default class TeraFyServer {
 
 		let $routeMatched = app.service('$route').matched[0];
 		if (!$routeMatched?.name) throw new Error('No active route');
-		if (!$routeMatched?.path.endsWith('/:toolPath(.*)?')) throw new Error('No tool active');
+		if ($routeMatched?.path == '/embed') return this.debug('INFO', 2, 'Ignoring setPageUrl(', url, ') on when in embed mode');
+		if (!$routeMatched?.path.endsWith('/:toolPath(.*)?')) return this.debug('INFO', 2, 'Ignoring setPageUrl(', url, ') - no active tool anyway');
 
 		app.router.push({
 			path: $routeMatched.path.replace(/\/:toolPath\(\.\*\)\?$/, url),
@@ -1390,6 +1424,5 @@ export default class TeraFyServer {
 			...msg,
 		);
 	}
-
 	// }}}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iebh/tera-fy",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "TERA website worker",
   "scripts": {
     "dev": "esbuild --platform=browser --format=esm --bundle lib/terafy.client.js --outfile=dist/terafy.js --minify --serve --servedir=.",
@@ -12,7 +12,7 @@
     "build:docs:markdown": "documentation build lib/terafy.client.js lib/projectFile.js --format md --markdown-toc --output api.md",
     "lint": "eslint lib plugins utils widgets",
     "release": "release-it",
-    "watch": "nodemon --watch lib --exec npm run build"
+    "watch": "nodemon --watch lib --watch plugins --exec npm run build"
   },
   "type": "module",
   "imports": {
@@ -109,7 +109,10 @@
     },
     "hooks": {
       "before:init": "git reset HEAD -- api.md docs/ dist/",
-      "after:bump": "npm run build && git add api.md docs/ dist/"
+      "before:bump": [
+        "npm run build",
+        "git add api.md docs/ dist/"
+      ]
     },
     "plugins": {
       "@release-it/conventional-changelog": {

package/plugins/vue2.js

@@ -1,4 +1,4 @@
-import {cloneDeep} from 'lodash-es';
+import {cloneDeep, isPlainObject} from 'lodash-es';
 import TeraFyPluginBase from './base.js';
 
 /**
@@ -93,6 +93,7 @@ export default class TeraFyPluginVue2 extends TeraFyPluginBase {
 				if (settings.read) {
 					this.events.on(`update:projects/${stateObservable.id}`, newState => {
 						skipUpdate++; // Skip next update as we're updating our own state anyway
+						this.debug('INFO', 5, 'Update Vue2 Remote->Local', {new: newState, old: stateObservable});
 						this.merge(stateObservable, newState);
 					});
 				}
@@ -114,6 +115,7 @@ export default class TeraFyPluginVue2 extends TeraFyPluginBase {
 								return;
 							}
 
+							this.debug('INFO', 5, 'Update Vue2 Local->Remote', {new: newVal, old: oldVal});
 							this.createProjectStatePatch(newVal, oldVal);
 							oldVal = cloneDeep(snapshot);
 						},
@@ -140,9 +142,9 @@ export default class TeraFyPluginVue2 extends TeraFyPluginBase {
 		payload.forEach(pl =>
 			Object.keys(pl)
 				.forEach(k => {
-					if (typeof pl[k] == 'object') { // Setting sub-objects - need to recurse these in Vue2
+					if (isPlainObject(pl[k])) { // Setting sub-objects - we need to recurse these in Vue2 in case a sub-key gets glued on
 						if (!(k in target)) // Destination to merge doesn't exist yet - create it
-							this.Vue.set(target, k, Array.isArray(pl[k]) ? [] : {});
+							this.Vue.set(target, k, {});
 
 						this.merge(target[k], pl[k]);
 					} else {