adapt-authoring-core 3.1.0 → 3.2.0

package/adapt-authoring.json

@@ -7,17 +7,21 @@
     "sourceIndex": "docs/index-backend.md",
     "manualPages": {
       "binscripts.md": "reference",
+      "configure-environment.md": "getting-started",
       "contributing.md": "contributing",
       "contributing-code.md": "contributing",
       "coremodules.md": "reference",
       "customising.md": "development",
+      "developer-workflow.md": "contributing",
+      "error-handling.md": "concepts",
       "folder-structure.md": "getting-started",
       "hooks.md": "concepts",
       "licensing.md": "reference",
       "releasing.md": "contributing",
       "request-response.md": "concepts",
       "run.md": "getting-started",
-      "writing-a-module.md": "development"
+      "writing-a-module.md": "development",
+      "writing-tests.md": "development"
     },
     "manualPlugins": [
       "docs/plugins/binscripts.js",

package/docs/writing-a-module.md

@@ -98,6 +98,17 @@ export default class MyModule extends AbstractModule {
 }
 ```
 
+`waitForModule` rejects if the module isn't installed, so it's for **required** dependencies. For an **optional** integration, probe first with `App#isModuleAvailable` (which never throws) and only wait when it's present — don't `try/catch` `waitForModule`, as that conflates "not installed" with "installed but failed to load":
+
+```javascript
+if (this.app.isModuleAvailable('websocket')) {
+  const websocket = await this.app.waitForModule('websocket');
+  // wire up the optional integration
+}
+```
+
+Both accept short names (without the `adapt-authoring-` prefix).
+
 ### _Optional task: add a configuration schema_
 
 If you plan to add user-configurable settings to your module, you can add a `config.schema.json` to define which settings users need to add. See [this page](defining-config) for more information.

package/lib/AbstractModule.js

@@ -1,4 +1,5 @@
 import Hook from './Hook.js'
+import { toShortName } from './utils/toShortName.js'
 /**
  * Abstract class for authoring tool modules. All custom modules must extend this class.
  * @memberof core
@@ -114,7 +115,7 @@ class AbstractModule {
    * @param {...*} rest Arguments to log
    */
   log (level, ...rest) {
-    this.app.logger?.log(level, this.name.replace(/^adapt-authoring-/, ''), ...rest)
+    this.app.logger?.log(level, toShortName(this.name), ...rest)
   }
 }
 

package/lib/App.js

@@ -146,6 +146,15 @@ class App extends AbstractModule {
     const results = await Promise.all(modNames.map(m => this.dependencyloader.waitForModule(m)))
     return results.length > 1 ? results : results[0]
   }
+
+  /**
+   * Whether a dependency is installed and loadable as an Adapt module. Use to guard optional integrations without throwing (`waitForModule` rejects when a module is missing).
+   * @param {string} modName Name of the module (short or full)
+   * @return {boolean}
+   */
+  isModuleAvailable (modName) {
+    return this.dependencyloader.isAvailable(modName)
+  }
 }
 
 export default App

package/lib/DependencyLoader.js

@@ -1,7 +1,7 @@
 import { glob } from 'glob'
 import path from 'path'
 import Hook from './Hook.js'
-import { metadataFileName, packageFileName, stripScope, readJson } from './Utils.js'
+import { metadataFileName, packageFileName, stripScope, toShortName, readJson } from './Utils.js'
 
 /**
  * Handles the loading of Adapt authoring tool module dependencies.
@@ -179,6 +179,25 @@ class DependencyLoader {
     }))
   }
 
+  /**
+   * Resolves a module name to the canonical key used in {@link DependencyLoader#configs}: short names (without the `adapt-authoring-` prefix) are expanded to the full form. Config keys are scope-stripped at load time, so a scoped package is reached by its unscoped name.
+   * @param {string} modName Module name (short or full)
+   * @return {string} The canonical config key
+   */
+  resolveModuleName (modName) {
+    return modName.startsWith('adapt-authoring-') ? modName : `adapt-authoring-${modName}`
+  }
+
+  /**
+   * Whether a dependency is installed and loadable as an Adapt module. Lets callers guard optional integrations without throwing — unlike {@link DependencyLoader#waitForModule}, which rejects when a module is missing.
+   * @param {string} modName Module name (short or full)
+   * @return {boolean} `true` when the module is present and not declared `module: false`
+   */
+  isAvailable (modName) {
+    const config = this.configs[this.resolveModuleName(modName)]
+    return Boolean(config) && config.module !== false
+  }
+
   /**
    * Waits for a single module to load. Returns the instance (if loaded), or hooks into moduleLoadedHook to wait for it.
    * @param {string} modName Name of module to wait for (accepts short names without 'adapt-authoring-' prefix)
@@ -189,7 +208,7 @@ class DependencyLoader {
     if (!this._configsLoaded) {
       await this.configsLoadedHook.onInvoke()
     }
-    if (!modName.startsWith('adapt-authoring-')) modName = `adapt-authoring-${modName}`
+    modName = this.resolveModuleName(modName)
     if (!this.configs[modName]) {
       throw this.app.errors.DEP_MISSING.setData({ module: modName })
     }
@@ -216,7 +235,7 @@ class DependencyLoader {
   logProgress (error, instance) {
     if (error) return
 
-    const toShort = names => names.map(n => n.replace('adapt-authoring-', '')).join(', ')
+    const toShort = names => names.map(toShortName).join(', ')
     const loaded = []
     const notLoaded = []
     let totalCount = 0

package/lib/Utils.js

@@ -9,4 +9,5 @@ export { ensureDir } from './utils/ensureDir.js'
 export { escapeRegExp } from './utils/escapeRegExp.js'
 export { stringifyValues } from './utils/stringifyValues.js'
 export { stripScope } from './utils/stripScope.js'
+export { toShortName } from './utils/toShortName.js'
 export { loadDependencyFiles } from './utils/loadDependencyFiles.js'

package/lib/utils/toShortName.js

@@ -0,0 +1,9 @@
+/**
+ * Strips the `adapt-authoring-` prefix from a module name to give its short, display form (e.g. 'adapt-authoring-server' becomes 'server'). Inverse of the canonicalisation in {@link DependencyLoader#resolveModuleName}.
+ * @param {string} name - The module name
+ * @returns {string} The name without the prefix
+ */
+export function toShortName (name) {
+  if (typeof name !== 'string') return name
+  return name.replace(/^adapt-authoring-/, '')
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-core",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "A bundle of reusable 'core' functionality",
   "homepage": "https://github.com/adapt-security/adapt-authoring-core",
   "license": "GPL-3.0",

package/tests/DependencyLoader.spec.js

@@ -506,6 +506,38 @@ describe('DependencyLoader', () => {
     })
   })
 
+  describe('#resolveModuleName()', () => {
+    it('should expand a short name to the canonical key', () => {
+      const loader = new DependencyLoader({ rootDir: '/test' })
+      assert.equal(loader.resolveModuleName('server'), 'adapt-authoring-server')
+    })
+
+    it('should leave a full name unchanged', () => {
+      const loader = new DependencyLoader({ rootDir: '/test' })
+      assert.equal(loader.resolveModuleName('adapt-authoring-server'), 'adapt-authoring-server')
+    })
+  })
+
+  describe('#isAvailable()', () => {
+    it('should return true for a present loadable module (short name)', () => {
+      const loader = new DependencyLoader({ rootDir: '/test' })
+      loader.configs = { 'adapt-authoring-server': { name: 'adapt-authoring-server', module: true } }
+      assert.equal(loader.isAvailable('server'), true)
+    })
+
+    it('should return false for a missing module', () => {
+      const loader = new DependencyLoader({ rootDir: '/test' })
+      loader.configs = {}
+      assert.equal(loader.isAvailable('server'), false)
+    })
+
+    it('should return false for a dependency declared module: false', () => {
+      const loader = new DependencyLoader({ rootDir: '/test' })
+      loader.configs = { 'adapt-authoring-docs': { name: 'adapt-authoring-docs', module: false } }
+      assert.equal(loader.isAvailable('docs'), false)
+    })
+  })
+
   describe('#logProgress()', () => {
     it('should not throw when called with valid instance', () => {
       const mockApp = { rootDir: '/test' }

package/tests/utils-toShortName.spec.js

@@ -0,0 +1,30 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { toShortName } from '../lib/utils/toShortName.js'
+
+describe('toShortName()', () => {
+  it('should strip the adapt-authoring- prefix', () => {
+    assert.equal(toShortName('adapt-authoring-server'), 'server')
+  })
+
+  it('should only strip an anchored prefix', () => {
+    assert.equal(toShortName('x-adapt-authoring-y'), 'x-adapt-authoring-y')
+  })
+
+  it('should return a name without the prefix unchanged', () => {
+    assert.equal(toShortName('server'), 'server')
+  })
+
+  it('should return an empty string unchanged', () => {
+    assert.equal(toShortName(''), '')
+  })
+
+  it('should return undefined unchanged', () => {
+    assert.equal(toShortName(undefined), undefined)
+  })
+
+  it('should return null unchanged', () => {
+    assert.equal(toShortName(null), null)
+  })
+})