@iebh/tera-fy 1.13.3 → 1.14.0

package/lib/terafy.client.js

@@ -127,7 +127,7 @@ export default class TeraFy {
 		'getProjectFileContents',
 		// 'createProjectFile', - Handled below (requires return mapped to ProjectFile)
 		'deleteProjectFile',
-		'setProjectFile',
+		'setProjectFileContents',
 
 		// Project Libraries
 		'selectProjectLibrary',
@@ -145,7 +145,7 @@ export default class TeraFy {
 		'uiConfirm',
 		'uiProgress',
 		'uiPrompt',
-		'uiTrhow',
+		'uiThrow',
 		'uiSplat',
 		'uiWindow',
 	];
@@ -222,7 +222,7 @@ export default class TeraFy {
 	* Call an RPC function in the server instance
 	*
 	* @param {String} method The method name to call
-	* @param {*} [...] Optional arguments to pass to the function
+	* @param {...*} [args] Optional arguments to pass to the function
 	*
 	* @returns {Promise<*>} The resolved output of the server function
 	*/
@@ -238,7 +238,9 @@ export default class TeraFy {
 	/**
 	* Accept an incoming message
 	*
-	* @param {MessageEvent} Raw message event to process
+	* @param {MessageEvent} rawMessage Raw message event to process
+	*
+	* @returns {Promise} A promise which will resolve when the message has been processed
 	*/
 	acceptMessage(rawMessage) {
 		if (rawMessage.origin == window.location.origin) return; // Message came from us
@@ -322,7 +324,7 @@ export default class TeraFy {
 
 			if (watchedPaths.length > 0) {
 				console.info('Detected writes to', watchedPaths, '- entering debugging mode');
-				debugger;
+				debugger; // eslint-disable-line no-debugger
 			}
 		}
 
@@ -698,13 +700,14 @@ export default class TeraFy {
 
 	// Utility - debug(), use(), mixin(), toggleDevMode(), toggleFocus() {{{
 
+	/* eslint-disable jsdoc/check-param-names */
 	/**
 	* Debugging output function
 	* This function will only act if `settings.devMode` is truthy
 	*
 	* @param {'INFO'|'LOG'|'WARN'|'ERROR'} [method='LOG'] Logging method to use
 	* @param {Number} [verboseLevel=1] The verbosity level to trigger at. If `settings.verbosity` is lower than this, the message is ignored
-	* @param {String} [msg...] Output to show
+	* @param {...*} [msg] Output to show
 	*/
 	debug(...msg) {
 		if (!this.settings.devMode || this.settings.verbosity < 1) return; // Debugging is disabled
@@ -729,6 +732,7 @@ export default class TeraFy {
 			...msg,
 		);
 	}
+	/* eslint-enable */
 
 
 	/**
@@ -779,7 +783,7 @@ export default class TeraFy {
 	/**
 	* Include a TeraFy client plugin
 	*
-	* @param {Object} The module function to include. Invoked as `(teraClient:TeraFy, options:Object)`
+	* @param {Object} mod The module function to include. Invoked as `(teraClient:TeraFy, options:Object)`
 	* @param {Object} [options] Additional options to mutate behaviour during construction (pass options to init() to intialize later options)
 	*
 	* @returns {TeraFy} This chainable terafy instance
@@ -1124,6 +1128,7 @@ export default class TeraFy {
 	/**
 	* Fetch the files associated with a given project
 	*
+	* @function getProjectFiles
 	* @param {Object} options Options which mutate behaviour
 	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
 	* @param {Boolean} [options.lazy=true] If true, use the fastest method to retrieve the file list such as the cache. If false, force a refresh each time
@@ -1157,7 +1162,8 @@ export default class TeraFy {
 	/**
 	* Fetch a project file by its name
 	*
-	* @param {String} name The name + relative directory path component
+	* @function getProjectFile
+	* @param {String} id The name + relative directory path component
 	*
 	* @param {Object|String} [options] Additional options to mutate behaviour, if a string is given `options.subkey` is assumed
 	* @param {String} [options.subkey] If specified only the extracted subkey is returned rather than the full object
@@ -1181,6 +1187,7 @@ export default class TeraFy {
 	* Create a new file
 	* This creates an empty file which can then be written to
 	*
+	* @function createProjectFile
 	* @param {String} name The name + relative directory path component
 	* @returns {Promise<ProjectFile>} The eventual ProjectFile created
 	*/
@@ -1209,7 +1216,7 @@ export default class TeraFy {
 	/**
 	* Replace a project files contents
 	*
-	* @function setProjectFile
+	* @function setProjectFileContents
 	* @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
@@ -1229,7 +1236,7 @@ export default class TeraFy {
 	* @param {Boolean} [options.allowCancel=true] Allow cancelling the operation. Will throw `'CANCEL'` as the promise rejection if acationed
 	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
 	* @param {FileFilters} [options.filters] Optional file filters, defaults to citation library selection only
-	* @param {*} [options.*] Additional options - see `getProjectLibrary()`
+	* @param {...*} [options] Additional options - see `getProjectLibrary()`
 	*
 	* @returns {Promise<Array<Ref>>} A collection of references from the selected file
 	*/
@@ -1290,7 +1297,7 @@ export default class TeraFy {
 	*
 	* @function setPage
 	* @param {Object|String} options Context information about the page, if this is a string, its assumed to popupate `url`
-	* @param {String} [options.url] The URL to restore on next refresh
+	* @param {String} [options.path] The URL path segment to restore on next refresh
 	* @param {String} [options.title] The page title associated with the path
 	*/
 

package/lib/terafy.proxy.js

@@ -109,6 +109,9 @@ export class TeraProxy {
 
 /**
 * Utility function to return a new TeraProxy instance
+*
+* @param {Object} [options] Options to pass to the Proxy module
+* @returns {TeraProxy} A TeraProxy instance
 */
 export default function(options) {
 	return new TeraProxy(options);

package/lib/terafy.server.js

@@ -152,7 +152,7 @@ export default class TeraFyServer {
 	* This function only works if the context was sub-classed via `createContext()`
 	*
 	* @param {String} method The method name to call
-	* @param {*} [...] Optional arguments to pass to the function
+	* @param {...*} [args] Optional arguments to pass to the function
 	*
 	* @returns {Promise<*>} The resolved output of the server function
 	*/
@@ -213,7 +213,7 @@ export default class TeraFyServer {
 	* Unlike send() this method does not expect any response
 	*
 	* @param {Object} message Message object to send
-	* @param {Window} Window context to dispatch the message via if its not the same as the regular window
+	* @param {Window} sendVia Window context to dispatch the message via if its not the same as the regular window
 	*/
 	sendRaw(message, sendVia) {
 		let payload;
@@ -256,7 +256,7 @@ export default class TeraFyServer {
 	/**
 	* Accept a message from the parent event listener
 	*
-	* @param {MessageEvent} Raw message event to process
+	* @param {MessageEvent} rawMessage Raw message event to process
 	*/
 	acceptMessage(rawMessage) {
 		if (rawMessage.origin == window.location.origin) return; // Message came from us
@@ -326,7 +326,7 @@ export default class TeraFyServer {
 	* Note that emitted messages have no response - they are sent to clients only with no return value
 	*
 	* @param {String} event The event name to emit
-	* @param {*} [args...] Optional event payload to send
+	* @param {...*} [args] Optional event payload to send
 	* @returns {Promise} A promise which resolves when the transmission has completed
 	*/
 	emitClients(event, ...args) {
@@ -709,7 +709,7 @@ export default class TeraFyServer {
 	*
 	* @param {Object} [options] Additional options to mutate behaviour
 	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
-	* @param {Array<String>} Paths to subscribe to e.g. ['/users/'],
+	* @param {Array<String>} [options.paths] Paths to subscribe to e.g. ['/users/'],
 	*
 	* @returns {Promise<Object>} The current project state snapshot
 	*/
@@ -877,7 +877,7 @@ export default class TeraFyServer {
 	/**
 	* Apply a computed `just-diff` patch to the current project state
 	*
-	* @param {Object} Patch to apply
+	* @param {Object} patch Patch to apply
 	* @returns {Promise} A promise which resolves when the operation has completed
 	*/
 	applyProjectStatePatch(patch) {
@@ -889,7 +889,7 @@ export default class TeraFyServer {
 	}
 	// }}}
 
-	// Project files - selectProjectFile(), getProjectFiles(), getProjectFile(), createProjectFile(), deleteProjectFile(), setProjectFile() {{{
+	// Project files - selectProjectFile(), getProjectFiles(), getProjectFile(), createProjectFile(), deleteProjectFile(), setProjectFileContents() {{{
 
 	/**
 	* Data structure for a project file
@@ -1056,6 +1056,7 @@ export default class TeraFyServer {
 	* Fetch the raw contents of a file by its ID
 	*
 	* @param {String} [id] File ID to retrieve the contents of
+	*
 	* @param {Object} [options] Additioanl options to mutate behaviour
 	* @param {'blob'|'json'} [options.format='blob'] The format to retrieve the file in. If `json` the raw output is run via JSON.parse() first
 	*
@@ -1130,7 +1131,7 @@ export default class TeraFyServer {
 	*
 	* @returns {Promise} A promise which will resolve when the write operation has completed
 	*/
-	setProjectFile(id, contents, options) {
+	setProjectFileContents(id, contents, options) {
 		// Argument mangling {{{
 		// TODO: Horrible kludge to detect ID is "not a JSON blob"
 		if (typeof id == 'string' && !id.startsWith('{') && contents && options) { // Called as `(id, contents, options)`
@@ -1180,7 +1181,7 @@ export default class TeraFyServer {
 	/**
 	* Prompt the user to select a library to operate on and return a array of references in a given format
 	*
-	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {Object} [options] Additional options to mutate behaviour - see `getProjectLibrary()` for parent list of options
 	* @param {String} [options.title="Select a citation library"] The title of the dialog to display
 	* @param {String|Array<String>} [options.hint] Hints to identify the library to select in array order of preference. Generally corresponds to the previous stage - e.g. 'deduped', 'review1', 'review2', 'dedisputed'
 	* @param {Boolean} [options.allowUpload=true] Allow uploading new files
@@ -1189,7 +1190,6 @@ export default class TeraFyServer {
 	* @param {Boolean} [options.allowCancel=true] Allow cancelling the operation. Will throw `'CANCEL'` as the promise rejection if acationed
 	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
 	* @param {FileFilters} [options.filters] Optional file filters, defaults to citation library selection only
-	* @param {*} [options.*] Additional options - see `getProjectLibrary()`
 	*
 	* @returns {Promise<Array<Ref>>} A collection of references from the selected file
 	*/
@@ -1386,7 +1386,7 @@ export default class TeraFyServer {
 	* This only really makes a difference to tools within the tera-tools.com site where the tool is working as an embed
 	*
 	* @param {Object|String} options Context information about the page, if this is a string, its assumed to popupate `url`
-	* @param {String} [options.url] The URL to restore on next refresh
+	* @param {String} [options.path] The URL path segment to restore on next refresh
 	* @param {String} [options.title] The page title associated with the path
 	*/
 	setPage(options) {
@@ -1718,13 +1718,14 @@ export default class TeraFyServer {
 
 	// Utility - debug() {{{
 
+	/* eslint-disable jsdoc/check-param-names */
 	/**
 	* Debugging output function
 	* This function will only act if `settings.devMode` is truthy
 	*
 	* @param {'INFO'|'LOG'|'WARN'|'ERROR'} [method='LOG'] Logging method to use
 	* @param {Number} [verboseLevel=1] The verbosity level to trigger at. If `settings.verbosity` is lower than this, the message is ignored
-	* @param {String} [msg...] Output to show
+	* @param {...*} [msg] Output to show
 	*/
 	debug(...msg) {
 		if (!this.settings.devMode || this.settings.verbosity < 1) return; // Debugging is disabled
@@ -1749,5 +1750,6 @@ export default class TeraFyServer {
 			...msg,
 		);
 	}
+	/* eslint-enable */
 	// }}}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iebh/tera-fy",
-  "version": "1.13.3",
+  "version": "1.14.0",
   "description": "TERA website worker",
   "scripts": {
     "dev": "esbuild --platform=browser --format=esm --bundle lib/terafy.client.js --outfile=dist/terafy.js --minify --serve --servedir=.",
@@ -76,15 +76,15 @@
     "lodash-es": "^4.17.21",
     "mitt": "^3.0.1",
     "nanoid": "^5.0.7",
-    "release-it": "^17.5.0"
+    "release-it": "^17.6.0"
   },
   "devDependencies": {
-    "@momsfriendlydevco/eslint-config": "^2.0.1",
+    "@momsfriendlydevco/eslint-config": "^2.0.3",
     "@release-it/conventional-changelog": "^8.0.1",
     "concurrently": "^8.2.2",
     "documentation": "^14.0.3",
     "esbuild": "^0.23.0",
-    "eslint": "^9.6.0"
+    "eslint": "^9.7.0"
   },
   "peerDependencies": {
     "vue": "^3.0.0"
@@ -112,7 +112,7 @@
     },
     "plugins": {
       "@release-it/conventional-changelog": {
-        "preset": "angular",
+        "preset": "eslint",
         "infile": "CHANGELOG.md",
         "header": "# Changelog"
       }

package/plugins/vite.js

@@ -5,6 +5,7 @@ import TeraProxy from '../lib/terafy.proxy.js';
 *
 * @see lib/terafy.proxy.js
 *
+* @param {Object} [options] Options to pass to the Proxy module
 * @returns {VitePlugin}
 */
 export default function vitePluginTeraFy(options) {

package/plugins/vue3.js

@@ -118,6 +118,8 @@ export default class TeraFyPluginVue extends TeraFyPluginBase {
 	* 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();
 	*/
@@ -128,6 +130,8 @@ export default class TeraFyPluginVue extends TeraFyPluginBase {
 
 	/**
 	* Provide a Vue@3 compatible plugin
+	*
+	* @returns {VuePlugin} A Vue@3 plugin spec
 	*/
 	vuePlugin() {
 		let $tera = this;
@@ -137,12 +141,12 @@ export default class TeraFyPluginVue extends TeraFyPluginBase {
 			/**
 			* Install into Vue as a generic Vue@3 plugin
 			*
+			* @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()`
-			*
-			* @returns {VuePlugin} A plugin matching the Vue@3 spec
 			*/
 			install(app, options) {
 				let settings = {

package/utils/pathTools.js

@@ -11,7 +11,6 @@ import {
 * General path setters / getters for project state
 * These are _MAINLY_ wrappers for Lodash functionality such as Lodash.set() / Lodash.get(), any deviations are documented inline
 *
-* @typedef {PathTools}
 * In each case these functions work with either dotted or array notation against a target master-object
 *     - Dotted notation - e.g. `foo.bar.1.baz`
 *     - Array path segments e.g. `['foo', 'bar', 1, 'baz']`
@@ -77,8 +76,8 @@ export function set(target, path, value, options) {
 * @param {*} [fallback] Optional fallback to return if the end point does not exist
 * @returns {*} The fetched value
 */
-export function get(subject, path, fallback) {
-	return _get(subject, path, fallback);
+export function get(target, path, fallback) {
+	return _get(target, path, fallback);
 }
 
 
@@ -132,6 +131,7 @@ export function defaults(target, path, value) {
 	}
 }
 
+
 // Export all functions as a lookup object
 export default {
 	set,

package/widgets/tera-file-select.vue

@@ -55,7 +55,7 @@ export default {
 		* Trigger the file selection functionality within TERA-fy
 		* This sets the `selected` data property to the newly selected file + fires @change
 		*
-		* @fires change Fired as `(file:ProjectFile)` when the contents changes
+		* @emits change Fired as `(file:ProjectFile)` when the contents changes
 		* @returns {ProjectFile} file The selected file
 		*/
 		async choose() {