npm - @iebh/tera-fy - Versions diffs - 1.0.9 → 1.0.10 - Mend

@iebh/tera-fy 1.0.9 → 1.0.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (36) hide show

package/README.md +9 -4
package/api.md +445 -431
package/dist/terafy.js +2 -2
package/dist/terafy.js.map +4 -4
package/docs/assets/anchor.js +350 -0
package/docs/assets/bass-addons.css +12 -0
package/docs/assets/bass.css +544 -0
package/docs/assets/fonts/EOT/SourceCodePro-Bold.eot +0 -0
package/docs/assets/fonts/EOT/SourceCodePro-Regular.eot +0 -0
package/docs/assets/fonts/LICENSE.txt +93 -0
package/docs/assets/fonts/OTF/SourceCodePro-Bold.otf +0 -0
package/docs/assets/fonts/OTF/SourceCodePro-Regular.otf +0 -0
package/docs/assets/fonts/TTF/SourceCodePro-Bold.ttf +0 -0
package/docs/assets/fonts/TTF/SourceCodePro-Regular.ttf +0 -0
package/docs/assets/fonts/WOFF/OTF/SourceCodePro-Bold.otf.woff +0 -0
package/docs/assets/fonts/WOFF/OTF/SourceCodePro-Regular.otf.woff +0 -0
package/docs/assets/fonts/WOFF/TTF/SourceCodePro-Bold.ttf.woff +0 -0
package/docs/assets/fonts/WOFF/TTF/SourceCodePro-Regular.ttf.woff +0 -0
package/docs/assets/fonts/WOFF2/OTF/SourceCodePro-Bold.otf.woff2 +0 -0
package/docs/assets/fonts/WOFF2/OTF/SourceCodePro-Regular.otf.woff2 +0 -0
package/docs/assets/fonts/WOFF2/TTF/SourceCodePro-Bold.ttf.woff2 +0 -0
package/docs/assets/fonts/WOFF2/TTF/SourceCodePro-Regular.ttf.woff2 +0 -0
package/docs/assets/fonts/source-code-pro.css +23 -0
package/docs/assets/github.css +123 -0
package/docs/assets/site.js +168 -0
package/docs/assets/split.css +15 -0
package/docs/assets/split.js +782 -0
package/docs/assets/style.css +147 -0
package/docs/index.html +3636 -0
package/{index.html → docs/playground.html} +48 -12
package/documentation.yml +12 -0
package/lib/terafy.client.js +227 -6
package/lib/terafy.server.js +107 -5
package/package.json +7 -6
package/plugins/vue2.js +173 -0
package/plugins/{vue.js → vue3.js} +20 -11

package/{index.html → docs/playground.html} RENAMED Viewed

@@ -20,7 +20,7 @@
 	</style>
 	<script type="module">
-		import TeraFy from './dist/terafy.js';
+		import TeraFy from 'https://esm.run/@iebh/tera-fy';
 		Vue.createApp({
 			data() { return {
@@ -97,6 +97,32 @@
 </head>
 <body>
 	<div id="app">
+		<!-- Nav header {{{ -->
+		<nav class="navbar navbar-expand-lg navbar-light bg-light px-4">
+			<a href="https://github.com/IEBH/TERA-fy" class="navbar-brand">TERA-fy</a>
+			<button type="button" data-toggle="collapse" data-target="#navbarAreas" class="navbar-toggler">
+				<span class="navbar-toggler-icon"></span>
+			</button>
+			<div id="navbarAreas" class="collapse navbar-collapse">
+				<ul class="navbar-nav">
+					<li class="navbar-item me-1">
+						<a href="https://iebh.github.io/TERA-fy" class="btn btn-light">API docs</a>
+					</li>
+					<li class="navbar-item mr-1">
+						<a href="https://iebh.github.io/TERA-fy/playground.html" class="btn btn-primary text-white">Playground</a>
+					</li>
+				</ul>
+			</div>
+			<ul class="navbar-nav">
+				<li class="navbar-item">
+					<a href="https://github.com/IEBH/TERA-fy" class="btn btn-light">
+						GitHub
+					</a>
+				</li>
+			</ul>
+		</nav>
+		<!-- }}} -->
 		<div class="container pt-4">
 			<div class="row">
 				<div class="col-sm-12 col-md-6">
@@ -161,12 +187,6 @@
 						<div class="card-header">Projects</div>
 						<div class="card-body">
 							<div class="list-group">
-								<a
-									@click="run('bindProject')"
-									class="list-group-item list-group-item-action disabled"
-								>
-									terafy.bindProject()
-								</a>
 								<a
 									@click="run('getProject')"
 									class="list-group-item list-group-item-action"
@@ -186,7 +206,7 @@
 								>
 									<div>terafy.setActiveProject(</div>
 									<select
-										v-if="projects"
+										v-if="projects && projects.length > 0"
 										v-model="project"
 										class="form-control"
 										placeholder="Select project..."
@@ -231,16 +251,32 @@
 									terafy.getProjectState()
 								</a>
 								<a
-									@click="run('bindProjectState')"
+									@click="run('applyProjectStatePatch')"
 									class="list-group-item list-group-item-action disabled"
 								>
-									terafy.bindProjectState()
+									terafy.applyProjectStatePatch()
 								</a>
 								<a
-									@click="run('applyProjectStatePatch')"
+									@click="run('subscribeProjectState')"
 									class="list-group-item list-group-item-action disabled"
 								>
-									terafy.applyProjectStatePatch()
+									terafy.subscribeProjectState()
+								</a>
+							</div>
+						</div>
+					</div>
+					<!-- }}} -->
+					<!-- Project Files {{{ -->
+					<div class="card mb-2">
+						<div class="card-header">Project Files</div>
+						<div class="card-body">
+							<div class="list-group">
+								<a
+									@click="run('getProjectFiles')"
+									class="list-group-item list-group-item-action"
+								>
+									terafy.getProjectFiles()
 								</a>
 							</div>
 						</div>

package/documentation.yml ADDED Viewed

@@ -0,0 +1,12 @@
+toc:
+  - name: TeraFy Playground
+    description: |
+      See [the TeraFy Playground](./playground.html) to expriment with the various TeraFy API calls.
+  - name: Data entities
+    children:
+      - User
+      - Project
+      - ProjectFile
+  - name: TeraFy
+    description: |
+      API reference for all methods exposed by the TeraFy client library.

package/lib/terafy.client.js CHANGED Viewed

@@ -1,3 +1,4 @@
+import {diff, jsonPatchPathConverter as jsPatchConverter} from 'just-diff';
 import {cloneDeep} from 'lodash-es';
 import {nanoid} from 'nanoid';
@@ -61,7 +62,7 @@ export default class TeraFy {
 		'bindProject', 'getProject', 'getProjects', 'setActiveProject', 'requireProject', 'selectProject',
 		// Project state
-		'getProjectState', 'applyProjectStatePatch',
+		'getProjectState', 'applyProjectStatePatch', 'subscribeProjectState',
 		// bindProjectState() - See below
 		// Project files
@@ -204,6 +205,39 @@ export default class TeraFy {
 	// }}}
+	// Project state - createProjectStatePatch(), applyProjectStatePatchLocal() {{{
+	/**
+	* Create + transmit a new project state patch base on the current and previous states
+	* The transmitted patch follows the [JSPatch](http://jsonpatch.com) standard
+	* This function accepts an entire projectState instance, computes the delta and transmits that to the server for merging
+	*
+	* @param {Object} newState The local projectState to accept
+	* @param {Object} oldState The previous projectState to examine against
+	*
+	* @returns {Promise} A promise which will resolve when the operation has completed
+	*/
+	createProjectStatePatch(newState, oldState) {
+		let patch = diff(oldState, newState, jsPatchConverter);
+		this.debug('INFO', 'Created project patch', {newState, oldState});
+		return this.applyProjectStatePatch(patch);
+	}
+	/**
+	* Client function which accepts a patch from the server and applies it to local project state
+	* The patch should follow the [JSPatch](http://jsonpatch.com) standard
+	* This function is expected to be sub-classed by a plugin
+	*
+	* @param {Array} patch A JSPatch patch to apply
+	*
+	* @returns {Promise} A promise which will resolve when the operation has completed
+	*/
+	applyProjectStatePatchLocal(patch) {
+		this.debug('WARN', 'Accepted project patch', patch, 'but applyProjectStatePatchLocal() has not been sub-classed');
+		return Promise.resolve();
+	}
+	// }}}
 	// Init - constructor(), init(), inject*() {{{
 	/**
@@ -220,13 +254,16 @@ export default class TeraFy {
 	* Initalize the TERA client singleton
 	* This function can only be called once and will return the existing init() worker Promise if its called againt
 	*
+	* @param {Object} [options] Additional options to merge into `settings` via `set`
 	* @returns {Promise<TeraFy>} An eventual promise which will resovle with this terafy instance
 	*/
-	init() {
+	init(options) {
+		if (options) this.set(options);
 		if (this.init.promise) return this.init.promise; // Aleady been called - return init promise
 		window.addEventListener('message', this.acceptMessage.bind(this));
+		const context = this;
 		return this.init.promise = Promise.resolve()
 			.then(()=> this.detectMode())
 			.then(mode => this.settings.mode = mode)
@@ -235,11 +272,12 @@ export default class TeraFy {
 				this.injectComms(),
 				this.injectStylesheet(),
 				this.injectMethods(),
-				// Init all plugins
-				...this.plugins
-					.map(plugin => plugin.init()),
 			]))
+			.then(()=> Promise.all( // Init all plugins (with this outer module as the context)
+				this.plugins.map(plugin =>
+					plugin.init.call(context)
+				)
+			))
 	}
@@ -453,6 +491,7 @@ export default class TeraFy {
 	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,
@@ -496,4 +535,186 @@ export default class TeraFy {
 		globalThis.document.body.classList.toggle('tera-fy-focus', isFocused === 'toggle' ? undefined : isFocused);
 	}
 	// }}}
+	// Stub documentation carried over from ./terafy.server.js {{{
+	/**
+	* Return basic server information as a form of validation
+	*
+	* @function handshake
+	* @returns {Promise<Object>} Basic promise result
+	* @property {Date} date Server date
+	*/
+	/**
+	* User / active session within TERA
+	*
+	* @name User
+	* @property {String} id Unique identifier of the user
+	* @property {String} email The email address of the current user
+	* @property {String} name The provided full name of the user
+	* @property {Boolean} isSubscribed Whether the active user has a TERA subscription
+	*/
+	/**
+	* Fetch the current session user
+	*
+	* @function getUser
+	* @returns {Promise<User>} The current logged in user or null if none
+	*/
+	/**
+	* Project entry within TERA
+	*
+	* @name Project
+	* @url https://tera-tools.com/help/api/schema
+	*/
+	/**
+	* Get the currently active project, if any
+	*
+	* @function getProject
+	* @returns {Promise<Project|null>} The currently active project, if any
+	*/
+	/**
+	* Get a list of projects the current session user has access to
+	*
+	* @function getProjects
+	* @returns {Promise<Array<Project>>} Collection of projects the user has access to
+	*/
+	/**
+	* Set the currently active project within TERA
+	*
+	* @function setActiveProject
+	* @param {Object|String} project The project to set as active - either the full Project object or its ID
+	*/
+	/**
+	* Ask the user to select a project from those available - if one isn't already active
+	* Note that this function will percist in asking the uesr even if they try to cancel
+	*
+	* @function requireProject
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {Boolean} [options.autoSetActiveProject=true] After selecting a project set that project as active in TERA
+	* @param {String} [options.title="Select a project to work with"] The title of the dialog to display
+	* @param {String} [options.noSelectTitle='Select project'] Dialog title when warning the user they need to select something
+	* @param {String} [options.noSelectBody='A project needs to be selected to continue'] Dialog body when warning the user they need to select something
+	*
+	* @returns {Promise<Project>} The active project
+	*/
+	/**
+	* Prompt the user to select a project from those available
+	*
+	* @function selectProject
+	* @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.setActive=false] Also set the project as active when selected
+	*
+	* @returns {Promise<Project>} The active project
+	*/
+	/**
+	* Return the current, full snapshot state of the active project
+	*
+	* @function getProjectState
+	* @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/'],
+	*
+	* @returns {Promise<Object>} The current project state snapshot
+	*/
+	/**
+	* Apply a computed `just-diff` patch to the current project state
+	*
+	* @function applyProjectStatePatch
+	* @param {Object} Patch to apply
+	* @returns {Promise} A promise which resolves when the operation has completed
+	*/
+	/**
+	* Subscribe to project state changes
+	* This will dispatch an RPC call to the source object `applyProjectStatePatchLocal()` function with the patch
+	* If the above call fails the subscriber is assumed as dead and unsubscribed from the polling list
+	*
+	* @function subscribeProjectState
+	* @returns {Promise<Function>} A promise which resolves when a subscription has been created, call the resulting function to unsubscribe
+	*/
+	/**
+	* Data structure for a project file
+	*
+	* @name ProjectFile
+	*
+	* @property {String} id A UUID string representing the unique ID of the file
+	* @property {String} name Relative name path (can contain prefix directories) for the human readable file name
+	* @property {Object} parsedName An object representing meta file parts of a file name
+	* @property {String} parsedName.basename The filename + extention (i.e. everything without directory name)
+	* @property {String} parsedName.filename The file portion of the name (basename without the extension)
+	* @property {String} parsedName.ext The extension portion of the name (always lower case)
+	* @property {String} parsedName.dirName The directory path portion of the name
+	* @property {Date} created A date representing when the file was created
+	* @property {Date} modified A date representing when the file was created
+	* @property {Date} accessed A date representing when the file was last accessed
+	* @property {Number} size Size, in bytes, of the file
+	* @property {String} mime The associated mime type for the file
+	*/
+	/**
+	* 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.meta=true] Pull meta information for each file entity
+	*
+	* @returns {Promise<ProjectFile>} A collection of project files for the given project
+	*/
+	/**
+	* Fetch the active projects citation library
+	*
+	* @function getProjectLibrary
+	* @param {String} [path] Optional file path to use, if omitted the contents of `options` are used to guess at a suitable file
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @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
+	*/
+	/**
+	* Save back a projects citation library
+	*
+	* @function setProjectLibrary
+	* @param {Array<RefLibRef>} Collection of references for the selected library
+	*
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @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'
+	*
+	* @returns {Promise} A promise which resolves when the save operation has completed
+	*/
+	// }}}
 }

package/lib/terafy.server.js CHANGED Viewed

@@ -1,4 +1,5 @@
-import {cloneDeep} from 'lodash-es';
+import {cloneDeep, set as pathSet} from 'lodash-es';
+import {diffApply, jsonPatchPathConverter as jsPatchConverter} from 'just-diff-apply';
 import {nanoid} from 'nanoid';
 /**
@@ -15,10 +16,15 @@ export default class TeraFyServer {
 	*
 	* @type {Object}
 	* @property {Boolean} devMode Operate in devMode - i.e. force outer refresh when encountering an existing TeraFy instance
+	* @property {Number} subscribeTimeout Acceptable timeout period for subscribers to acklowledge a project change event, failing to respond will result in the subscriber being removed from the available subscriber list
 	* @property {String} restrictOrigin URL to restrict communications to
+	* @property {String} projectId The project to use as the default reference when calling various APIs
 	*/
 	settings = {
+		devMode: false,
 		restrictOrigin: '*',
+		subscribeTimeout: 2000,
+		projectId: null,
 	};
 	// Contexts - createContext(), messageEvent, senderRpc() {{{
@@ -237,7 +243,7 @@ export default class TeraFyServer {
 			$auth.promise(),
 			$subscriptions.promise(),
 		])
-			.then(()=> ({
+			.then(()=> $auth.user.id ? {
 				id: $auth.user.id,
 				email: $auth.user.email,
 				name: [
@@ -245,7 +251,7 @@ export default class TeraFyServer {
 					$auth.user.family_name,
 				].filter(Boolean).join(' '),
 				isSubscribed: $subscriptions.isSubscribed,
-			}))
+			} : null)
 	}
 	// }}}
@@ -403,7 +409,7 @@ export default class TeraFyServer {
 	// }}}
-	// Project State - getProjectState(), applyProjectStatePatch() {{{
+	// Project State - getProjectState(), setProjectState(), saveProjectState(), applyProjectStatePatch(), subscribeProjectState() {{{
 	/**
 	* Return the current, full snapshot state of the active project
@@ -427,14 +433,110 @@ export default class TeraFyServer {
 	}
+	/**
+	* Set a nested value within the project state
+	* Paths can be any valid Lodash.set() value such as:
+	*
+	*     - Dotted notation - e.g. `foo.bar.1.baz`
+	*     - Array path segments e.g. `['foo', 'bar', 1, 'baz']`
+	*
+	*
+	* @param {String|Array<String>} path The sub-path within the project state to set
+	* @param {*} value The value to set
+	*
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {Boolean} [options.save=true] Save the changes to the server immediately, disable to queue up multiple writes
+	* @param {Boolean} [options.sync=false] Wait for the server to acknowledge the write, you almost never need to do this
+	*
+	* @returns {Promise} A promise which resolves when the operation has synced with the server
+	*/
+	setProjectState(path, value, options) {
+		let settings = {
+			save: true,
+			sync: false,
+			...options,
+		};
+		if (!app.service('$projects').active) throw new Error('No active project');
+		pathSet(app.service('$projects').active, path, value)
+		return (
+			this.save && this.sync ? this.saveProjectState()
+			: this.save ? void this.saveProjectState()
+			: (()=> { throw new Error('setProjectState({sync: true, save: false}) makes no sense') })()
+		);
+	}
+	/**
+	* Force-Save the currently active project state
+	*
+	* @returns {Promise} A promise which resolves when the operation has completed
+	*/
+	saveProjectState() {
+		if (!app.service('$projects').active) throw new Error('No active project');
+		// TODO: Would be nice if we compared against a sanity hash or something before just clobbering
+		this.debug('FIXME: Force saving projects is not yet supported - this should occur in realtime anyway');
+		return Promise.resolve();
+	}
 	/**
 	* Apply a computed `just-diff` patch to the current project state
+	*
+	* @param {Object} Patch to apply
+	* @returns {Promise} A promise which resolves when the operation has completed
 	*/
 	applyProjectStatePatch(patch) {
-		this.debug('Applying sever state patch', {patch});
+		if (!app.service('$projects').active) throw new Error('No active project to patch');
+		this.debug('Applying', patch.length, 'project state patches', {patch});
+		diffApply(app.service('$projects').active, patch, jsPatchConverter);
+		return Promise.resolve();
 	}
+	/**
+	* Subscribe to project state changes
+	* This will dispatch an RPC call to the source object `applyProjectStatePatchLocal()` function with the patch
+	* If the above call fails the subscriber is assumed as dead and unsubscribed from the polling list
+	*
+	* @returns {Promise<Function>} A promise which resolves when a subscription has been created, call the resulting function to unsubscribe
+	*/
+	subscribeProjectState() {
+		if (!this.messageEvent) throw new Error('senderRpc() can only be used if given a context from `createContext()`');
+		let subscriber = {
+			id: nanoid(),
+			origin: this.messageEvent.origin,
+			sendPatch: patch => new Promise((resolve, reject) => {
+				let senderTimeout = setTimeout(()=> {
+					reject(`Timed out sending to project-state subscriber "${subscriber.origin}"`);
+				}, this.subscribeTimeout);
+				return this.senderRpc.call(this, 'applyProjectStatePatchLocal', patch)
+					.then(()=> {
+						clearTimeout(senderTimeout);
+						resolve()
+					})
+					.catch(e => {
+						subscriber.unsubscribe();
+						reject(`Rejected calling RPC:applyProjectStatePatchLocal() with project-state subscriber "${subscriber.origin}" -`, e)
+					})
+			}),
+			unsubscribe: ()=> {
+				this.debug('Unsubscribing project-state subscriber', subscriber.origin);
+				this.projectStateSubscribers = this.projectStateSubscribers.filter(ps => ps.id != subscriber.id);
+			},
+		};
+		// Append to subscriber list
+		this.projectStateSubscribers.push(subscriber)
+	}
 	/**
 	* Subscribers to server project state changes

package/package.json CHANGED Viewed

@@ -1,12 +1,13 @@
 {
   "name": "@iebh/tera-fy",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "description": "TERA website worker",
   "scripts": {
     "dev": "esbuild --platform=browser --format=esm --bundle lib/terafy.client.js --outfile=dist/terafy.js --minify --sourcemap --serve --servedir=.",
     "build": "concurrently 'npm:build:*'",
     "build:client": "esbuild --platform=browser --format=esm --bundle lib/terafy.client.js --outfile=dist/terafy.js --minify --sourcemap",
-    "build:docs": "jsdoc2md --files lib/terafy.*.js plugins/*.js >api.md",
+    "build:docs:api": "documentation build lib/terafy.client.js --format html --config documentation.yml --output docs/",
+    "build:docs:markdown": "documentation build lib/terafy.client.js --format md --markdown-toc --output api.md",
     "lint": "eslint ."
   },
   "type": "module",
@@ -59,19 +60,19 @@
     "node": ">=18"
   },
   "peerDependencies": {
-    "just-diff": "^6.0.2",
     "lodash-es": "^4.17.21",
     "nanoid": "^5.0.2"
   },
   "optionalDependencies": {
+    "just-diff": "^6.0.2",
+    "just-diff-apply": "^5.5.0",
     "vue": "^3.3.7"
   },
   "devDependencies": {
     "@momsfriendlydevco/eslint-config": "^1.0.7",
     "concurrently": "^8.2.2",
-    "esbuild": "^0.19.5",
-    "eslint": "^8.47.0",
-    "jsdoc-to-markdown": "^8.0.0"
+    "documentation": "^14.0.2",
+    "esbuild": "^0.19.5"
   },
   "eslintConfig": {
     "extends": "@momsfriendlydevco",