@iebh/tera-fy 1.0.16 → 1.0.17

package/hints.md

@@ -0,0 +1,26 @@
+TERA-fy Hints
+=============
+Hints are a single string attached to file uploads to provide some context as to where it fits within the overall process. They are usually past-tense single-words indicating the output from each stage.
+
+When attached to files they indicate that the generated file is an output from a stage. e.g. if a file is noted with the hint 'deduped' it indicates it is the product of a de-duplication stage.
+
+They are used in multiple places:
+
+* Calls to most project library handling functions - `selectProjectLibrary()`, `setProjectLibrary()`
+* Within the UI to indicate what library is used during what process
+
+
+Hint Reference
+--------------
+The following is a non-definitive list of hints that can be associated with files. In all cases the hint should be a lower-case single, past-tense word. Upper-case indicates a variable.
+
+This list should also be mirrored in the main tera-tools.com/api/tools.json meta-list.
+
+
+| Hint         | Description                                                                                                                                                  |
+|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `search`     | The product of a search design stage                                                                                                                         |
+| `deduped`    | One or more files, that are the product of a deduplication stage                                                                                             |
+| `screened-X` | One or more files from the screening stage, generally there will be one file per reviewer where `X` indicates the reviewer number starting with the number 1 |
+| `disputed`   | Generally a single file which is the product of a resolved dispute stage which merges in multiple `screened-X` files                                         |
+| `snowballed` | A file which has been through the snowballing stage                                                                                                          |

package/lib/terafy.client.js

@@ -87,10 +87,10 @@ export default class TeraFy {
 		// For bindProjectState() - See individual plugins
 
 		// Project files
-		'getProjectFiles',
+		'selectProjectFile', 'getProjectFiles',
 
 		// Project Libraries
-		'getProjectLibrary', 'setProjectLibrary',
+		'selectProjectLibrary', 'parseProjectLibrary', 'setProjectLibrary',
 
 		// UI
 		'uiAlert',
@@ -798,6 +798,35 @@ export default class TeraFy {
 	* @property {String} mime The associated mime type for the file
 	*/
 
+	/**
+	* Data structure for a file filter
+	* @name FileFilters
+	*
+	* @property {Boolean} [library=false] Restrict to library files only
+	* @property {String} [filename] CSV of @momsfriendlydevco/match expressions to filter the filename by (filenames are the basename sans extension)
+	* @property {String} [basename] CSV of @momsfriendlydevco/match expressions to filter the basename by
+	* @property {String} [ext] CSV of @momsfriendlydevco/match expressions to filter the file extension by
+	*/
+
+
+	/**
+	* Prompt the user to select a library to operate on
+	*
+	* @function selectProjectFile
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {String} [options.title="Select a file"] The title of the dialog to display
+	* @param {String|Array<String>} [options.hint] Hints to identify the file to select in array order of preference
+	* @param {FileFilters} [options.filters] Optional file filters
+	* @param {Boolean} [options.allowUpload=true] Allow uploading new files
+	* @param {Boolean} [options.allowRefresh=true] Allow the user to manually refresh the file list
+	* @param {Boolean} [options.allowDownloadZip=true] Allow the user to download a Zip of all files
+	* @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.filter] Optional file filters
+	*
+	* @returns {Promise<ProjectFile>} The eventually selected file
+	*/
+
 
 	/**
 	* Fetch the files associated with a given project
@@ -807,25 +836,60 @@ export default class TeraFy {
 	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
 	* @param {Boolean} [options.meta=true] Pull meta information for each file entity
 	*
-	* @returns {Promise<ProjectFile>} A collection of project files for the given project
+	* @returns {Promise<Array<ProjectFile>>} A collection of project files for the given project
 	*/
 
 
 	/**
-	* Fetch the active projects citation library
+	* Prompt the user to select a library to operate on and return a array of references in a given format
 	*
-	* @function getProjectLibrary
-	* @param {String} [path] Optional file path to use, if omitted the contents of `options` are used to guess at a suitable file
+	* @function selectProjectLibrary
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @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
+	* @param {Boolean} [options.allowRefresh=true] Allow the user to manually refresh the file list
+	* @param {Boolean} [options.allowDownloadZip=true] Allow the user to download a Zip of all files
+	* @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 `parseProjectLibrary()`
+	*
+	* @returns {Promise<Array<Ref>>} A collection of references from the selected file
+	*/
+
+
+	/**
+	* Convert a project file into a library of citations
+	*
+	* @function parseProjectLibrary
+	* @param {String} path File path to read, if omitted the contents of `options` are used to guess at a suitable file
 	*
 	* @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)
 	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
-	* @param {Boolean} [options.multiple=false] Allow selection of multiple libraries
 	* @param {Function} [options.filter] Optional async file filter, called each time as `(File:ProjectFile)`
 	* @param {Function} [options.find] Optional async final stage file filter to reduce all candidates down to one subject file
-	* @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'
 	*
-	* @returns {Promise<Array<ProjectFile>>} Collection of references for the selected library matching the given hint + filter, this could be a zero length array
+	* @returns {Promise<Array<Ref>>|Promise<*>} A collection of references (default bevahiour) or a whatever format was requested
+	*/
+
+
+	/**
+	* Save back a citation library from some input
+	*
+	* @function setProjectLibrary
+	* @param {String} [path] File path to save back to
+	* @param {Array<RefLibRef>} Collection of references for the selected library
+	*
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @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 {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
 	*/
 
 

package/lib/terafy.server.js

@@ -495,7 +495,7 @@ export default class TeraFyServer {
 	*
 	* @param {Object} [options] Additional options to mutate behaviour
 	* @param {String} [options.title="Select a project to work with"] The title of the dialog to display
-	* @param {Boolean} [options.allowCancel=true] Advertise cancelling the operation, the dialog can still be cancelled by closing it
+	* @param {Boolean} [options.allowCancel=true] Allow cancelling the operation, will throw `'CANCEL'` if actioned
 	* @param {Boolean} [options.setActive=false] Also set the project as active when selected
 	*
 	* @returns {Promise<Project>} The active project
@@ -526,7 +526,7 @@ export default class TeraFyServer {
 
 	// }}}
 
-	// Project State - getProjectState(), setProjectState(), saveProjectState(), replaceProjectState(), applyProjectStatePatch {{{
+	// Project State - getProjectState(), setProjectState(), saveProjectState(), replaceProjectState(), applyProjectStatePatch() {{{
 
 	/**
 	* Return the current, full snapshot state of the active project
@@ -654,7 +654,7 @@ export default class TeraFyServer {
 	}
 	// }}}
 
-	// Project files - getProjectFiles() {{{
+	// Project files - selectProjectFile(), getProjectFiles() {{{
 
 	/**
 	* Data structure for a project file
@@ -674,6 +674,72 @@ export default class TeraFyServer {
 	* @property {String} mime The associated mime type for the file
 	*/
 
+	/**
+	* Data structure for a file filter
+	* @class FileFilters
+	*
+	* @property {Boolean} [library=false] Restrict to library files only
+	* @property {String} [filename] CSV of @momsfriendlydevco/match expressions to filter the filename by (filenames are the basename sans extension)
+	* @property {String} [basename] CSV of @momsfriendlydevco/match expressions to filter the basename by
+	* @property {String} [ext] CSV of @momsfriendlydevco/match expressions to filter the file extension by
+	*/
+
+	/**
+	* Prompt the user to select a library to operate on
+	*
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {String} [options.title="Select a file"] The title of the dialog to display
+	* @param {String|Array<String>} [options.hint] Hints to identify the file to select in array order of preference
+	* @param {FileFilters} [options.filters] Optional file filters
+	* @param {Boolean} [options.allowUpload=true] Allow uploading new files
+	* @param {Boolean} [options.allowRefresh=true] Allow the user to manually refresh the file list
+	* @param {Boolean} [options.allowDownloadZip=true] Allow the user to download a Zip of all files
+	* @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.filter] Optional file filters
+	*
+	* @returns {Promise<ProjectFile>} The eventually selected file
+	*/
+	selectProjectFile(options) {
+		let settings = {
+			title: 'Select a file',
+			hint: null,
+			filters: {},
+			allowUpload: true,
+			allowRefresh: true,
+			allowDownloadZip: true,
+			allowCancel: true,
+			autoRequire: true,
+			...options,
+		};
+
+		return app.service('$projects').promise()
+			.then(()=> settings.autoRequire && this.requireProject())
+			.then(files => this.requestFocus(()=>
+				app.service('$prompt').dialog({
+					title: settings.title,
+					component: 'filesSelect',
+					componentProps: {
+						hint: settings.hint,
+						allowNavigate: false,
+						allowUpload: settings.allowUpload,
+						allowRefresh: settings.allowRefresh,
+						allowDownloadZip: settings.allowDownloadZip,
+						allowVerbs: false,
+						cardStyle: false,
+						filters: settings.filters,
+					},
+					componentEvents: {
+						fileSelect(file) {
+							app.service('$prompt').close(true, file);
+						},
+					},
+					modalDialogClass: 'modal-dialog-lg',
+					buttons: settings.allowCancel && ['cancel'],
+				})
+			))
+	}
+
 
 	/**
 	* Fetch the files associated with a given project
@@ -682,7 +748,7 @@ export default class TeraFyServer {
 	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
 	* @param {Boolean} [options.meta=true] Pull meta information for each file entity
 	*
-	* @returns {Promise<ProjectFile>} A collection of project files for the given project
+	* @returns {Promise<Array<ProjectFile>>} A collection of project files for the given project
 	*/
 	getProjectFiles(options) {
 		let settings = {
@@ -700,61 +766,81 @@ export default class TeraFyServer {
 	}
 	// }}}
 
-	// Project Libraries - getProjectLibrary(), setProjectLibrary() {{{
+	// Project Libraries - selectProjectLibrary(), parseProjectLibrary(), setProjectLibrary() {{{
+
+	/**
+	* 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 {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
+	* @param {Boolean} [options.allowRefresh=true] Allow the user to manually refresh the file list
+	* @param {Boolean} [options.allowDownloadZip=true] Allow the user to download a Zip of all files
+	* @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 `parseProjectLibrary()`
+	*
+	* @returns {Promise<Array<Ref>>} A collection of references from the selected file
+	*/
+	selectProjectLibrary(options) {
+		let settings = {
+			title: 'Select a citation library',
+			hint: null,
+			allowUpload: true,
+			allowRefresh: true,
+			allowDownloadZip: true,
+			allowCancel: true,
+			autoRequire: true,
+			filters: {
+				library: true,
+				...options?.filter,
+			},
+			...options,
+		};
+
+		return app.service('$projects').promise()
+			.then(()=> this.selectProjectFile(settings))
+			.then(selectedFile => this.parseProjectLibrary(selectedFile.path, settings))
+	}
+
 
 	/**
-	* Fetch the active projects citation library
+	* Convert a project file into a library of citations
 	*
-	* @param {String} [path] Optional file path to use, if omitted the contents of `options` are used to guess at a suitable file
+	* @param {String} path File path to read, if omitted the contents of `options` are used to guess at a suitable file
 	*
 	* @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)
 	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
-	* @param {Boolean} [options.multiple=false] Allow selection of multiple libraries
 	* @param {Function} [options.filter] Optional async file filter, called each time as `(File:ProjectFile)`
 	* @param {Function} [options.find] Optional async final stage file filter to reduce all candidates down to one subject file
-	* @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'
 	*
-	* @returns {Promise<Array<ProjectFile>>} Collection of references for the selected library matching the given hint + filter, this could be a zero length array
+	* @returns {Promise<Array<Ref>>|Promise<*>} A collection of references (default bevahiour) or a whatever format was requested
 	*/
-	getProjectLibrary(path, options) {
+	parseProjectLibrary(path, options) {
 		let settings = {
-			path,
 			format: 'pojo',
 			autoRequire: true,
-			multiple: false,
-			hint: null,
 			filter: file => true,
 			find: files => files.at(0),
-			...(typeof path == 'string' ? {path, ...options} : path),
+			...options,
 		};
 
 		return Promise.resolve()
-			.then(()=> {
-				if (settings.path) { // Already have a file name picked
-					if (!settings.path.startsWith('/')) throw new Error('All file names must start with a forward slash');
-					return settings.path;
-				} else { // Try to guess the file from the options structure
-					return this.getProjectFiles({
-						autoRequire: settings.autoRequire,
-					})
-					.then(files => files.filter(file =>
-						settings.filter(file)
-					))
-					.then(files => settings.find(files))
-					.then(file => file.path)
-				}
-			})
-			.then(filePath => app.service('$supabase').fileGet(filePath, {
+			.then(()=> settings.autoRequire && this.requireProject())
+			.then(()=> app.service('$supabase').fileGet(path, {
 				toast: false,
 			}))
 			.then(blob => {
 				switch (settings.format) {
+					// NOTE: Any updates to the format list should also extend setProjectLibrary()
 					case 'pojo':
 						return Reflib.uploadFile({
 							file: new File(
 								[blob],
-								app.service('$supabase')._parsePath(settings.path).basename,
+								app.service('$supabase')._parsePath(path).basename,
 							),
 						});
 					case 'blob':
@@ -762,7 +848,7 @@ export default class TeraFyServer {
 					case 'file':
 						return new File(
 							[blob],
-							app.service('$supabase')._parsePath(settings.path).basename,
+							app.service('$supabase')._parsePath(path).basename,
 						);
 					default:
 						throw new Error(`Unsupported library format "${settings.format}"`);
@@ -772,26 +858,59 @@ export default class TeraFyServer {
 
 
 	/**
-	* Save back a projects citation library
+	* Save back a citation library from some input
 	*
+	* @param {String} [path] File path to save back to
 	* @param {Array<RefLibRef>} Collection of references for the selected library
 	*
 	* @param {Object} [options] Additional options to mutate behaviour
+	* @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 {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(refs, options) {
+	setProjectLibrary(path, refs, options) {
 		let settings = {
 			autoRequire: true,
 			hint: null,
+			overwrite: true,
+			meta: null,
 			...options,
 		};
 
 		return Promise.resolve()
 			.then(()=> settings.autoRequire && this.requireProject())
-		// FIXME: Stub
+			.then(()=> {
+				switch (settings.format) {
+					// NOTE: Any updates to the format list should also extend parseProjectLibrary()
+					case 'pojo': // Use as is
+						if (!Array.isArray(refs)) throw new Error('setProjectLibrary() with format=pojo requires an array of references');
+						return refs;
+					case 'blob':
+					case 'file':
+						return refs; // Following functions should pass thru these formats anyway
+					default:
+						throw new Error(`Unsupported library format "${settings.format}"`);
+				}
+			})
+			.then(refs =>
+				refs instanceof Blob ? new File([refs], app.service('$supabase')._parsePath(path).basename)
+				: refs instanceof File ? refs
+				: Reflib.downloadFile(refs, { // Get Reflib to encode for us
+					filename: path,
+					promptDownload: false, // Just return the fileBlob we hand to Supabase
+				})
+			)
+			.then(fileBlob => this.$supabase.fileUpload(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
+			}))
 	}
 
 	// }}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iebh/tera-fy",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "description": "TERA website worker",
   "scripts": {
     "dev": "esbuild --platform=browser --format=esm --bundle lib/terafy.client.js --outfile=dist/terafy.js --minify --sourcemap --serve --servedir=.",