adapt-authoring-core 2.5.0 → 3.0.1

package/lib/Config.js

@@ -0,0 +1,226 @@
+import { Schemas } from 'adapt-schemas'
+import fs from 'fs/promises'
+import path from 'path'
+
+/**
+ * Loads, validates, and provides access to application configuration.
+ * Configuration is sourced from user settings files, environment variables, and module schema defaults.
+ * @memberof core
+ */
+class Config {
+  /**
+   * @param {Object} options
+   * @param {String} options.rootDir Application root directory
+   * @param {String} options.configFilePath Path to the user configuration file
+   * @param {Object} options.dependencies Key/value map of dependency configs
+   * @param {String} options.appName The core module name (for sorting)
+   * @param {Function} options.log Logging function (level, id, ...args)
+   */
+  constructor ({ rootDir, configFilePath, dependencies = {}, appName = '', log = () => {} } = {}) {
+    /** @ignore */
+    this._config = {}
+    /**
+     * Application root directory
+     * @type {String}
+     */
+    this.rootDir = rootDir
+    /**
+     * Path to the user configuration file
+     * @type {String}
+     */
+    this.configFilePath = configFilePath
+    /**
+     * The keys for all attributes marked as public
+     * @type {Array<String>}
+     */
+    this.publicAttributes = []
+    /** @ignore */
+    this._dependencies = dependencies
+    /** @ignore */
+    this._appName = appName
+    /** @ignore */
+    this.log = log
+  }
+
+  /**
+   * Loads configuration from all sources
+   * @returns {Promise}
+   */
+  async load () {
+    await this.storeUserSettings()
+    this.storeEnvSettings()
+    this.storeSchemaSettings(this._dependencies, this._appName)
+    this.log('info', 'config', `using config at ${this.configFilePath}`)
+    return this
+  }
+
+  /**
+   * Determines whether an attribute has a set value
+   * @param {String} attr Attribute key name
+   * @return {Boolean}
+   */
+  has (attr) {
+    return Object.hasOwn(this._config, attr)
+  }
+
+  /**
+   * Returns a value for a given attribute
+   * @param {String} attr Attribute key name
+   * @return {*}
+   */
+  get (attr) {
+    return this._config[attr]
+  }
+
+  /**
+   * Retrieves all config options marked as 'public'
+   * @return {Object}
+   */
+  getPublicConfig () {
+    return this.publicAttributes.reduce((m, a) => {
+      m[a] = this.get(a)
+      return m
+    }, {})
+  }
+
+  /**
+   * Loads the relevant config file into memory
+   * @return {Promise}
+   */
+  async storeUserSettings () {
+    let config
+    try {
+      await fs.readFile(this.configFilePath)
+      config = (await import(this.configFilePath)).default
+    } catch (e) {
+      this.log('warn', 'config', `Failed to load config at ${this.configFilePath}: ${e}. Will attempt to run with defaults.`)
+      return
+    }
+    Object.entries(config).forEach(([name, c]) => {
+      Object.entries(c).forEach(([key, val]) => {
+        this._config[`${name}.${key}`] = val
+      })
+    })
+  }
+
+  /**
+   * Copy env values to config
+   */
+  storeEnvSettings () {
+    Object.entries(process.env).forEach(([key, val]) => {
+      try {
+        val = JSON.parse(val)
+      } catch {} // ignore parse errors for non-JSON values
+      this._config[Config.envVarToConfigKey(key)] = val
+    })
+  }
+
+  /**
+   * Processes all module config schema files
+   * @param {Object} dependencies Key/value map of dependency configs
+   * @param {String} appName The core module name (for sorting)
+   */
+  storeSchemaSettings (dependencies, appName) {
+    const schemas = new Schemas().init()
+    const isCore = d => d.name === appName
+    const deps = Object.values(dependencies).sort((a, b) => {
+      if (isCore(a)) return -1
+      if (isCore(b)) return 1
+      return a.name.localeCompare(b.name)
+    })
+    const coreDep = deps.find(d => isCore(d))
+    if (coreDep) this.processModuleSchema(coreDep, schemas)
+
+    const errors = []
+    for (const d of deps.filter(d => !isCore(d))) {
+      try {
+        this.processModuleSchema(d, schemas)
+      } catch (e) {
+        errors.push(e?.data?.errors ? { modName: e.modName, message: e.data.errors } : { message: String(e) })
+      }
+    }
+    if (errors.length) {
+      errors.forEach(e => {
+        this.log('error', 'config', `${e.modName ? e.modName + ': ' : ''}${e.message}`)
+      })
+      throw new Error('Config validation failed')
+    }
+  }
+
+  /**
+   * Processes and validates a single module config schema
+   * @param {Object} pkg Package.json data
+   * @param {Schemas} schemas Schemas library instance
+   */
+  processModuleSchema (pkg, schemas) {
+    if (!pkg.name || !pkg.rootDir) return
+    const schemaPath = path.resolve(pkg.rootDir, 'conf/config.schema.json')
+    let schema
+    try {
+      // TODO config schemas should define $id, remove this workaround once they do
+      schema = schemas.createSchema(schemaPath)
+      schema.raw.$id = pkg.name
+      schema.build({ compile: false })
+      schema.built.$id = pkg.name
+      schema.compiledWithDefaults = schemas.validatorWithDefaults.compile(schema.built)
+      schema.compiled = schemas.validator.compile(schema.built)
+    } catch (e) {
+      if (e.code !== 'SCHEMA_LOAD_FAILED') {
+        this.log('warn', 'config', `${pkg.name}: ${e.message}`)
+      }
+      return
+    }
+    const dirKeys = new Set()
+    let data = Object.entries(schema.raw.properties).reduce((m, [k, v]) => {
+      if (v?._adapt?.isPublic) this.publicAttributes.push(`${pkg.name}.${k}`)
+      if (v?.isDirectory) dirKeys.add(k)
+      return { ...m, [k]: this.get(`${pkg.name}.${k}`) }
+    }, {})
+    try {
+      data = schema.validate(data)
+    } catch (e) {
+      e.modName = pkg.name
+      throw e
+    }
+    Object.entries(data).forEach(([key, val]) => {
+      if (dirKeys.has(key) && typeof val === 'string') {
+        val = this.resolveDirectory(val)
+      }
+      this._config[`${pkg.name}.${key}`] = val
+    })
+  }
+
+  /**
+   * Resolves directory path variables ($ROOT, $DATA, $TEMP)
+   * @param {String} value The path string to resolve
+   * @return {String}
+   */
+  resolveDirectory (value) {
+    const vars = [
+      ['$ROOT', this.rootDir],
+      ['$DATA', this._config['adapt-authoring-core.dataDir']],
+      ['$TEMP', this._config['adapt-authoring-core.tempDir']]
+    ]
+    for (const [key, replacement] of vars) {
+      if (value.startsWith(key) && replacement && !replacement.startsWith('$')) {
+        return path.resolve(replacement, value.replace(key, '').slice(1))
+      }
+    }
+    return value
+  }
+
+  /**
+   * Parses an environment variable key into a format expected by Config
+   * @param {String} envVar
+   * @return {String}
+   */
+  static envVarToConfigKey (envVar) {
+    if (envVar.startsWith('ADAPT_AUTHORING_')) {
+      const [modPrefix, key] = envVar.split('__')
+      return `${modPrefix.replace(/_/g, '-').toLowerCase()}.${key}`
+    }
+    return `env.${envVar}`
+  }
+}
+
+export default Config

package/lib/DataCache.js

@@ -13,6 +13,8 @@ class DataCache {
     this.isEnabled = enable === true
     this.lifespan = lifespan
     this.cache = {}
+    this.hits = 0
+    this.misses = 0
   }
 
   /**
@@ -26,8 +28,12 @@ class DataCache {
     const key = JSON.stringify(query) + JSON.stringify(options) + JSON.stringify(mongoOptions)
     this.prune()
     if (this.isEnabled && this.cache[key]) {
+      this.hits++
+      App.instance.logger?.log('verbose', 'datacache', 'hit', options.collectionName, query)
       return this.cache[key].data
     }
+    this.misses++
+    App.instance.logger?.log('verbose', 'datacache', 'miss', options.collectionName, query)
     const mongodb = await App.instance.waitForModule('mongodb')
     const data = await mongodb.find(options.collectionName, query, mongoOptions)
     this.cache[key] = { data, timestamp: Date.now() }

package/lib/DependencyLoader.js

@@ -1,10 +1,8 @@
-/* eslint no-console: 0 */
-import _ from 'lodash'
-import fs from 'fs-extra'
 import { glob } from 'glob'
 import path from 'path'
 import Hook from './Hook.js'
-import { metadataFileName, packageFileName, stripScope } from './Utils.js'
+import { metadataFileName, packageFileName, stripScope, readJson } from './Utils.js'
+
 /**
  * Handles the loading of Adapt authoring tool module dependencies.
  * @memberof core
@@ -59,47 +57,21 @@ class DependencyLoader {
     this.moduleLoadedHook.tap(this.logProgress, this)
   }
 
-  /**
-   * Loads all Adapt module dependencies. Essential modules are loaded first, then non-essential modules (with force mode).
-   * @return {Promise<void>}
-   * @throws {Error} When any essential module fails to load
-   */
-  async load () {
-    await this.loadConfigs()
-
-    const configValues = Object.values(this.configs)
-    // sort dependencies into priority
-    const { essential, theRest } = configValues.reduce((m, c) => {
-      this.app.pkg.essentialApis.includes(c.essentialType) ? m.essential.push(c.name) : m.theRest.push(c.name)
-      return m
-    }, { essential: [], theRest: [] })
-    // load each set of deps
-    await this.loadModules(essential)
-    await this.loadModules(theRest, { force: true })
-
-    if (this.failedModules.length) {
-      throw new Error(`Failed to load modules ${this.failedModules.join(', ')}`)
-    }
-  }
-
   /**
    * Loads configuration files for all Adapt dependencies found in node_modules.
    * @return {Promise<void>}
    */
   async loadConfigs () {
     /** @ignore */ this._configsLoaded = false
+    const corePathSegment = `/${this.app.name}/`
     const files = await glob(`${this.app.rootDir}/node_modules/**/${metadataFileName}`)
     const deps = files
       .map(d => d.replace(`${metadataFileName}`, ''))
-      .sort((a, b) => a.length < b.length ? -1 : 1)
-
-    // sort so that core is loaded first, as other modules may use its config values
-    const corePathSegment = `/${this.app.name}/`
-    deps.sort((a, b) => {
-      if (a.endsWith(corePathSegment)) return -1
-      if (b.endsWith(corePathSegment)) return 1
-      return 0
-    })
+      .sort((a, b) => {
+        if (a.endsWith(corePathSegment)) return -1
+        if (b.endsWith(corePathSegment)) return 1
+        return a.length - b.length
+      })
     for (const d of deps) {
       try {
         const c = await this.loadModuleConfig(d)
@@ -112,8 +84,8 @@ class DependencyLoader {
           }
         }
       } catch (e) {
-        this.logError(`Failed to load config for '${d}', module will not be loaded`)
-        this.logError(e)
+        this.log('error', `Failed to load config for '${d}', module will not be loaded`)
+        this.log('error', e)
       }
     }
     this._configsLoaded = true
@@ -126,10 +98,10 @@ class DependencyLoader {
    * @return {Promise<Object>} Resolves with configuration object
    */
   async loadModuleConfig (modDir) {
-    const pkg = await fs.readJson(path.join(modDir, packageFileName))
+    const pkg = await readJson(path.join(modDir, packageFileName))
     return {
       ...pkg,
-      ...await fs.readJson(path.join(modDir, metadataFileName)),
+      ...await readJson(path.join(modDir, metadataFileName)),
       name: stripScope(pkg.name),
       packageName: pkg.name,
       rootDir: modDir
@@ -144,7 +116,7 @@ class DependencyLoader {
    */
   async loadModule (modName) {
     if (this.instances[modName]) {
-      throw new Error('Module already exists')
+      throw this.app.errors.DEP_ALREADY_LOADED.setData({ module: modName })
     }
     const config = this.configs[modName]
 
@@ -153,54 +125,48 @@ class DependencyLoader {
     }
     const { default: ModClass } = await import(config.packageName)
 
-    if (!_.isFunction(ModClass)) {
-      throw new Error('Expected class to be exported')
+    if (typeof ModClass !== 'function') {
+      throw this.app.errors.DEP_INVALID_EXPORT.setData({ module: modName })
     }
     const instance = new ModClass(this.app, config)
 
-    if (!_.isFunction(instance.onReady)) {
-      throw new Error('Module must define onReady function')
+    if (typeof instance.onReady !== 'function') {
+      throw this.app.errors.DEP_NO_ONREADY.setData({ module: modName })
     }
     try {
-      // all essential modules will use hard-coded value, as config won't be loaded yet
-      const timeout = this.getConfig('moduleLoadTimeout') ?? 10000
+      const timeout = this.app.getConfig('moduleLoadTimeout') ?? 10000
       await Promise.race([
         instance.onReady(),
-        new Promise((resolve, reject) => setTimeout(() => reject(new Error(`${modName} load exceeded timeout (${timeout})`)), timeout))
+        new Promise((resolve, reject) => setTimeout(() => reject(this.app.errors.DEP_TIMEOUT.setData({ module: modName, timeout })), timeout))
       ])
       this.instances[modName] = instance
       await this.moduleLoadedHook.invoke(null, instance)
       return instance
     } catch (e) {
-      await this.moduleLoadedHook.invoke(e)
+      await this.moduleLoadedHook.invoke(e, { name: modName })
       throw e
     }
   }
 
   /**
-   * Loads a list of Adapt modules. Should not need to be called directly.
-   * @param {Array<string>} modules Module names to load
-   * @param {Object} [options] Loading options
-   * @param {boolean} [options.force=false] If true, logs errors and continues loading other modules when a module fails. If false, throws a DependencyError on first failure.
-   * @return {Promise<void>} Resolves when all modules have loaded (or failed to load in force mode)
-   * @throws {DependencyError} When a module fails to load and options.force is not true
+   * Loads Adapt modules. If no list is provided, loads all configured dependencies.
+   * @param {Array<string>} [modules] Module names to load (defaults to all dependencies)
+   * @return {Promise<void>} Resolves when all modules have loaded or failed
+   * @throws {Error} When any module throws a fatal error (error.isFatal or error.cause.isFatal)
    */
-  async loadModules (modules, options = {}) {
+  async loadModules (modules = Object.values(this.configs).map(c => c.name)) {
     await Promise.all(modules.map(async m => {
       try {
         await this.loadModule(m)
       } catch (e) {
-        if (options.force !== true) {
-          const error = new Error(`Failed to load '${m}'`)
-          error.name = 'DependencyError'
-          error.cause = e
-          throw error
+        if (e.isFatal || e.cause?.isFatal) {
+          throw e
         }
-        this.logError(`Failed to load '${m}',`, e)
+        this.log('error', `Failed to load '${m}',`, e)
         const deps = this.peerDependencies[m]
-        if (deps && deps.length) {
-          this.logError('The following modules are peer dependencies, and may not work:')
-          deps.forEach(d => this.logError(`- ${d}`))
+        if (deps?.length) {
+          this.log('error', 'The following modules are peer dependencies, and may not work:')
+          deps.forEach(d => this.log('error', `- ${d}`))
         }
         this.failedModules.push(m)
       }
@@ -217,14 +183,12 @@ class DependencyLoader {
     if (!this._configsLoaded) {
       await this.configsLoadedHook.onInvoke()
     }
-    const longPrefix = 'adapt-authoring-'
-    if (!modName.startsWith(longPrefix)) modName = `adapt-authoring-${modName}`
+    if (!modName.startsWith('adapt-authoring-')) modName = `adapt-authoring-${modName}`
     if (!this.configs[modName]) {
-      throw new Error(`Missing required module '${modName}'`)
+      throw this.app.errors.DEP_MISSING.setData({ module: modName })
     }
-    const DependencyError = new Error(`Dependency '${modName}' failed to load`)
     if (this.failedModules.includes(modName)) {
-      throw DependencyError
+      throw this.app.errors.DEP_FAILED.setData({ module: modName })
     }
     const instance = this.instances[modName]
     if (instance) {
@@ -232,8 +196,9 @@ class DependencyLoader {
     }
     return new Promise((resolve, reject) => {
       this.moduleLoadedHook.tap((error, instance) => {
-        if (error) return reject(DependencyError)
-        if (instance?.name === modName) resolve(instance)
+        if (instance?.name !== modName) return
+        if (error) return reject(this.app.errors.DEP_FAILED.setData({ module: modName }))
+        resolve(instance)
       })
     })
   }
@@ -243,9 +208,8 @@ class DependencyLoader {
    * @param {AbstractModule} instance The last loaded instance
    */
   logProgress (error, instance) {
-    if (error) {
-      return
-    }
+    if (error) return
+
     const toShort = names => names.map(n => n.replace('adapt-authoring-', '')).join(', ')
     const loaded = []
     const notLoaded = []
@@ -264,42 +228,21 @@ class DependencyLoader {
     ].filter(Boolean).join(', '))
 
     if (progress === 100) {
-      const initTimes = Object.entries(this.instances)
-        .sort((a, b) => a[1].initTime < b[1].initTime ? -1 : a[1].initTime > b[1].initTime ? 1 : 0)
-        .reduce((memo, [modName, instance]) => Object.assign(memo, { [modName]: instance.initTime }), {})
+      const initTimes = Object.fromEntries(
+        Object.entries(this.instances)
+          .sort(([, a], [, b]) => a.initTime - b.initTime)
+          .map(([name, inst]) => [name, inst.initTime])
+      )
       this.log('verbose', initTimes)
     }
   }
 
   /**
-   * Logs a message using the app logger if available, otherwise falls back to console.log
+   * Logs a message using the app logger
    * @param {...*} args Arguments to be logged
    */
   log (level, ...args) {
-    if (this.app.logger?._isReady) {
-      this.app.logger.log(level, this.name, ...args)
-    } else {
-      console.log(...args)
-    }
-  }
-
-  /**
-   * Logs an error message using the app logger if available, otherwise falls back to console.log
-   * @param {...*} args Arguments to be logged
-   */
-  logError (...args) {
-    this.log('error', ...args)
-  }
-
-  /**
-   * Retrieves a configuration value from this module's config
-   * @param {string} key - The configuration key to retrieve
-   * @returns {*|undefined} The configuration value if config is ready, undefined otherwise
-   */
-  getConfig (key) {
-    if (this.app.config?._isReady) {
-      return this.app.config.get(`adapt-authoring-core.${key}`)
-    }
+    this.app.logger?.log(level, this.name, ...args)
   }
 }
 

package/lib/Errors.js

@@ -0,0 +1,50 @@
+import AdaptError from './AdaptError.js'
+import fs from 'node:fs'
+import { globSync } from 'glob'
+
+/**
+ * Loads and stores all error definitions for the application. Errors are accessed via human-readable error codes for better readability when thrown in code.
+ * @memberof core
+ */
+class Errors {
+  /**
+   * @param {Object} options
+   * @param {Object} options.dependencies Key/value map of dependency configs (each with a rootDir)
+   * @param {Function} [options.log] Optional logging function (level, id, ...args)
+   */
+  constructor ({ dependencies, log } = {}) {
+    const errorDefs = {}
+    for (const d of Object.values(dependencies)) {
+      const files = globSync('errors/*.json', { cwd: d.rootDir, absolute: true })
+      for (const f of files) {
+        try {
+          const contents = JSON.parse(fs.readFileSync(f))
+          Object.entries(contents).forEach(([k, v]) => {
+            if (errorDefs[k]) {
+              log?.('warn', 'errors', `error code '${k}' already defined`)
+              return
+            }
+            errorDefs[k] = v
+          })
+        } catch (e) {
+          log?.('warn', 'errors', e.message)
+        }
+      }
+    }
+    Object.entries(errorDefs)
+      .sort()
+      .forEach(([k, { description, statusCode, isFatal, data }]) => {
+        Object.defineProperty(this, k, {
+          get: () => {
+            const metadata = { description }
+            if (isFatal) metadata.isFatal = true
+            if (data) metadata.data = data
+            return new AdaptError(k, statusCode, metadata)
+          },
+          enumerable: true
+        })
+      })
+  }
+}
+
+export default Errors

package/lib/Hook.js

@@ -1,4 +1,3 @@
-import _ from 'lodash'
 /**
  * Allows observers to tap into to a specific piece of code, and execute their own arbitrary code
  * @memberof core
@@ -43,7 +42,7 @@ class Hook {
    * @param {*} scope Sets the scope of the observer
    */
   tap (observer, scope) {
-    if (_.isFunction(observer)) this._hookObservers.push(observer.bind(scope))
+    if (typeof observer === 'function') this._hookObservers.push(observer.bind(scope))
   }
 
   /**
@@ -78,7 +77,7 @@ class Hook {
         data = await Promise.all(this._hookObservers.map(o => o(...args)))
       } else {
         // if not mutable, send a deep copy of the args to avoid any meddling
-        for (const o of this._hookObservers) data = await o(...this._options.mutable ? args : args.map(a => _.cloneDeep(a)))
+        for (const o of this._hookObservers) data = await o(...this._options.mutable ? args : args.map(a => structuredClone(a)))
       }
     } catch (e) {
       error = e