adapt-authoring-core 2.5.0 → 3.0.1

package/docs/plugins/configuration.js

@@ -0,0 +1,75 @@
+import fs from 'fs'
+import path from 'path'
+
+export default class Configuration {
+  async run () {
+    const schemas = this.loadSchemas()
+    this.contents = Object.keys(schemas).sort()
+    this.manualFile = 'configuration.md'
+    this.replace = {
+      CODE_EXAMPLE: this.generateCodeExample(schemas),
+      LIST: this.generateList(schemas)
+    }
+  }
+
+  loadSchemas () {
+    const schemas = {}
+    Object.values(this.app.dependencies).forEach(c => {
+      const confDir = path.join(c.rootDir, 'conf')
+      try {
+        schemas[c.name] = JSON.parse(fs.readFileSync(path.join(confDir, 'config.schema.json')))
+      } catch (e) {}
+    })
+    return schemas
+  }
+
+  generateCodeExample (schemas) {
+    let output = '```javascript\nexport default {\n'
+    this.contents.forEach((name) => {
+      const schema = schemas[name]
+      output += `  '${name}': {\n`
+      Object.entries(schema.properties).forEach(([attr, config]) => {
+        const required = schema.required && schema.required.includes(attr)
+        if (config.description) output += `    // ${config.description}\n`
+        output += `    ${attr}: ${this.defaultToMd(config)}, // ${config.type}, ${required ? 'required' : 'optional'}\n`
+      })
+      output += '  },\n'
+    })
+    output += '};\n```'
+    return output
+  }
+
+  generateList (schemas) {
+    let output = ''
+
+    this.contents.forEach(dep => {
+      const schema = schemas[dep]
+      output += `<h3 id="${dep}" class="dep">${dep}</h3>\n\n`
+      output += '<div class="options">\n'
+      Object.entries(schema.properties).forEach(([attr, config]) => {
+        const required = schema.required && schema.required.includes(attr)
+        output += '<div class="attribute">\n'
+        output += `<div class="title"><span class="main">${attr}</span> (${config.type || ''}, ${required ? 'required' : 'optional'})</div>\n`
+        output += '<div class="inner">\n'
+        output += `<div class="description">${config.description}</div>\n`
+        if (!required) {
+          output += `<div class="default"><span class="label">Default</span>: <pre class="no-bg">${this.defaultToMd(config)}</pre></div>\n`
+        }
+        output += '</div>\n'
+        output += '</div>\n'
+      })
+      output += '</div>'
+      output += '\n\n'
+    })
+
+    return output
+  }
+
+  /**
+   * Returns a string formatted nicely for markdown
+   */
+  defaultToMd (config) {
+    const s = JSON.stringify(config.default, null, 2)
+    return s?.length < 75 ? s : s?.replaceAll('\n', '\n    ')
+  }
+}

package/docs/plugins/configuration.md

@@ -0,0 +1,14 @@
+# Configuration reference
+This page lists all configuration options supported by the [core bundle](coremodules) of Adapt authoring modules. For details on how to set up your configuration, including using environment variables, see [Configuring your environment](configure-environment).
+
+{{{TABLE_OF_CONTENTS}}}
+
+## Quick reference
+See below for an overview of all available configuration options.
+
+{{{CODE_EXAMPLE}}}
+
+## Complete reference
+See below for a full list of available configuration options.
+
+{{{LIST}}}

package/docs/plugins/errors.js

@@ -0,0 +1,22 @@
+export default class Errors {
+  async run () {
+    this.manualFile = 'errorsref.md'
+    this.contents = Object.keys(this.app.errors)
+    this.replace = { ERRORS: this.generateMd() }
+  }
+
+  generateMd () {
+    return Object.keys(this.app.errors).reduce((md, k) => {
+      const e = this.app.errors[k]
+      return `${md}\n| \`${e.code}\` | ${e.meta.description} | ${e.statusCode} | <ul>${this.dataToMd(e.meta.data)}</ul> |`
+    }, '| Error code | Description | HTTP status code | Supplemental data |\n| - | - | :-: | - |')
+  }
+
+  dataToMd (data) {
+    if (!data) return ''
+    return Object.entries(data).reduce((acc, [k, v]) => {
+      const nested = typeof v === 'object' ? this.dataToMd(v) : v
+      return `${acc}<li>\`${k}\`: ${nested}</li>`
+    }, '')
+  }
+}

package/docs/plugins/errorsref.md

@@ -0,0 +1,9 @@
+# Errors Reference
+
+This page documents all errors which are likely to be thrown in the system, along with the appropriate HTTP status code and any supplemental data which is stored with the error.
+
+Supplemental data can be used at the point that errors are translated to provide more context to a specific error. All data stored with an error can be assumed to be a primitive type for easy printing.
+
+{{{TABLE_OF_CONTENTS}}}
+
+{{{ERRORS}}}

package/errors/errors.json

@@ -1,4 +1,84 @@
 {
+  "FILE_SYNTAX_ERROR": {
+    "data": {
+      "path": "Path to the invalid file",
+      "message": "The error message"
+    },
+    "description": "File contains a syntax error",
+    "statusCode": 500
+  },
+  "DEP_ALREADY_LOADED": {
+    "data": { "module": "The module name" },
+    "description": "Module has already been loaded",
+    "statusCode": 500
+  },
+  "DEP_FAILED": {
+    "data": { "module": "The module name" },
+    "description": "Required dependency failed to load",
+    "statusCode": 500,
+    "isFatal": true
+  },
+  "DEP_INVALID_EXPORT": {
+    "data": { "module": "The module name" },
+    "description": "Module must export a class as its default export",
+    "statusCode": 500
+  },
+  "DEP_MISSING": {
+    "data": { "module": "The module name" },
+    "description": "Required module is not installed",
+    "statusCode": 500,
+    "isFatal": true
+  },
+  "DEP_NO_ONREADY": {
+    "data": { "module": "The module name" },
+    "description": "Module must define an onReady function",
+    "statusCode": 500
+  },
+  "DEP_TIMEOUT": {
+    "data": { "module": "The module name", "timeout": "The timeout in ms" },
+    "description": "Module load exceeded timeout",
+    "statusCode": 500
+  },
+  "FUNC_DISABLED": {
+    "data": {
+      "name": "The name of the function"
+    },
+    "description": "Function has been disabled",
+    "statusCode": 500
+  },
+  "FUNC_NOT_OVERRIDDEN": {
+    "data": {
+      "name": "The name of the function"
+    },
+    "description": "Function must be overridden in child class",
+    "statusCode": 500
+  },
+  "INVALID_PARAMS": {
+    "data": {
+      "params": "The invalid params"
+    },
+    "description": "Invalid parameters have been provided",
+    "statusCode": 400
+  },
+  "LOAD_ERROR": {
+    "description": "Config failed to load",
+    "statusCode": 500
+  },
+  "NOT_FOUND": {
+    "data": {
+      "id": "An identifier for the missing item",
+      "type": "Type of the missing item"
+    },
+    "description": "Requested item could not be found",
+    "statusCode": 404
+  },
+  "SERVER_ERROR": {
+    "description": "Generic server error",
+    "statusCode": 500,
+    "data": {
+      "error": "The original error"
+    }
+  },
   "SPAWN": {
     "data": {
       "cmd": "The command",
@@ -7,5 +87,12 @@
     },
     "description": "Error occurred spawning command",
     "statusCode": 500
+  },
+  "UNKNOWN_LANG": {
+    "data": {
+      "lang": "language"
+    },
+    "description": "unknown language",
+    "statusCode": 400
   }
 }

package/errors/node-core.json

@@ -0,0 +1,39 @@
+{
+  "EACCES": {
+    "description": "An attempt was made to access a file in a way forbidden by its file access permissions",
+    "statusCode": 500
+  },
+  "EADDRINUSE": {
+    "description": "An attempt to bind a server to a local address failed due to another server on the local system already occupying that address",
+    "statusCode": 500
+  },
+  "ECONNREFUSED": {
+    "description": "No connection could be made because the target machine actively refused it",
+    "statusCode": 500
+  },
+  "EEXIST": {
+    "description": "An existing file was the target of an operation that required that the target not exist",
+    "statusCode": 500,
+    "data": {
+      "path": "Path to target file or directory"
+    }
+  },
+  "ENOENT": {
+    "description": "No entity (file or directory) could be found by the given path",
+    "statusCode": 500,
+    "data": {
+      "path": "Path to target file or directory"
+    }
+  },
+  "ENOTEMPTY": {
+    "description": "A directory with entries was the target of an operation that requires an empty directory",
+    "statusCode": 500,
+    "data": {
+      "path": "Path to target file or directory"
+    }
+  },
+  "MODULE_NOT_FOUND": {
+    "description": "A module file could not be resolved while attempting a require() or import operation",
+    "statusCode": 500
+  }
+}

package/index.js

@@ -1,6 +1,11 @@
 export { default as AbstractModule } from './lib/AbstractModule.js'
+export { default as AdaptError } from './lib/AdaptError.js'
 export { default as App } from './lib/App.js'
+export { default as Config } from './lib/Config.js'
 export { default as DataCache } from './lib/DataCache.js'
 export { default as DependencyLoader } from './lib/DependencyLoader.js'
+export { default as Errors } from './lib/Errors.js'
 export { default as Hook } from './lib/Hook.js'
+export { default as Lang } from './lib/Lang.js'
+export { default as Logger } from './lib/Logger.js'
 export { metadataFileName, packageFileName, isObject, getArgs, spawn, readJson, writeJson, toBoolean, ensureDir, escapeRegExp, stringifyValues, loadDependencyFiles } from './lib/Utils.js'

package/lib/AbstractModule.js

@@ -105,26 +105,16 @@ class AbstractModule {
    * @return {*}
    */
   getConfig (key) {
-    try {
-      return this.app.config.get(`${this.name}.${key}`)
-    } catch (e) {
-      return undefined
-    }
+    return this.app.config?.get(`${this.name}.${key}`)
   }
 
   /**
-   * Log a message using the Logger module
+   * Log a message using the Logger
    * @param {String} level Log level of message
    * @param {...*} rest Arguments to log
    */
   log (level, ...rest) {
-    const _log = (e, instance) => {
-      if (!this.app.logger || (instance && instance.name !== this.app.logger.name)) return false
-      this.app.dependencyloader.moduleLoadedHook.untap(_log)
-      this.app.logger.log(level, this.name.replace(/^adapt-authoring-/, ''), ...rest)
-      return true
-    }
-    if (!_log()) this.app.dependencyloader.moduleLoadedHook.tap(_log)
+    this.app.logger?.log(level, this.name.replace(/^adapt-authoring-/, ''), ...rest)
   }
 }
 

package/lib/AdaptError.js

@@ -0,0 +1,57 @@
+/**
+ * A generic error class for use in Adapt applications
+ * @memberof core
+ */
+class AdaptError extends Error {
+  /**
+   * @constructor
+   * @param {string} code The human-readable error code
+   * @param {number} statusCode The HTTP status code
+   * @param {object} metadata Metadata describing the error
+   */
+  constructor (code, statusCode = 500, metadata = {}) {
+    super(code)
+    /**
+     * The error code
+     * @type {String}
+     */
+    this.code = code
+    /**
+     * The HTTP status code
+     * @type {String}
+     */
+    this.statusCode = statusCode
+    /**
+     * Whether this error should halt the application
+     * @type {Boolean}
+     */
+    this.isFatal = metadata.isFatal ?? false
+    /**
+     * Metadata describing the error
+     * @type {Object}
+     */
+    this.meta = metadata
+  }
+
+  /**
+   * Chainable function to allow setting of data for use in user-friendly error messages later on.
+   * @param {object} data
+   * @returns {AdaptError}
+   * @example
+   * // note calling this function will also return
+   * // the error itself to allow for easy error throwing
+   * throw this.app.errors.MY_ERROR
+   *   .setData({ hello: 'world' })
+   */
+  setData (data) {
+    this.data = data
+    return this
+  }
+
+  /** @override */
+  toString () {
+    return `${this.constructor.name}: ${this.code} ${this.data ? JSON.stringify(this.data) : ''}`
+  }
+}
+
+export default AdaptError

package/lib/App.js

@@ -1,7 +1,12 @@
 import AbstractModule from './AbstractModule.js'
+import Config from './Config.js'
 import DependencyLoader from './DependencyLoader.js'
+import Errors from './Errors.js'
+import Lang from './Lang.js'
+import Logger from './Logger.js'
 import fs from 'fs'
 import path from 'path'
+import { runMigrations } from 'adapt-authoring-migrations'
 import { metadataFileName, packageFileName, getArgs } from './Utils.js'
 
 let instance
@@ -26,54 +31,85 @@ class App extends AbstractModule {
 
   /** @override */
   constructor () {
+    process.env.NODE_ENV ??= 'production'
     const rootDir = process.env.ROOT_DIR ?? process.cwd()
     const adaptJson = JSON.parse(fs.readFileSync(path.join(rootDir, metadataFileName)))
     const packageJson = JSON.parse(fs.readFileSync(path.join(rootDir, packageFileName)))
     super(null, { ...packageJson, ...adaptJson, name: 'adapt-authoring-core', rootDir })
-    this.git = this.getGitInfo()
   }
 
   /** @override */
   async init () {
-    /**
-     * Reference to the passed arguments (parsed for easy reference)
-     * @type {Object}
-     */
-    this.args = getArgs()
-    /**
-     * Instance of App instance (required by all AbstractModules)
-     * @type {App}
-     */
-    this.app = this
-    /**
-     * Reference to the DependencyLoader instance
-     * @type {DependencyLoader}
-     */
-    this.dependencyloader = new DependencyLoader(this)
+    try {
+      /**
+       * Instance of App instance (required by all AbstractModules)
+       * @type {App}
+       */
+      this.app = this
+      /**
+       * Reference to the passed arguments (parsed for easy reference)
+       * @type {Object}
+       */
+      this.args = getArgs()
+      /**
+       * Reference to the Config instance
+       * @type {Config}
+       */
+      this.config = undefined
+      /**
+       * Reference to the error registry
+       * @type {Errors}
+       */
+      this.errors = undefined
+      /**
+       * Reference to the Lang instance
+       * @type {Lang}
+       */
+      this.lang = undefined
+      /**
+       * Reference to the Logger instance
+       * @type {Logger}
+       */
+      this.logger = new Logger()
+      /**
+       * Reference to the DependencyLoader instance
+       * @type {DependencyLoader}
+       */
+      this.dependencyloader = new DependencyLoader(this)
+      /**
+       * Git metadata for the application (branch and commit hash)
+       * @type {Object}
+       */
+      this.git = this.getGitInfo()
 
-    /** @ignore */ this._isStarting = false
+      await this.dependencyloader.loadConfigs()
 
-    const configRootDir = this.getConfig('rootDir')
-    if (configRootDir) /** @ignore */this.rootDir = configRootDir
+      const options = {
+        dependencies: this.dependencies,
+        configFilePath: path.join(this.rootDir, 'conf', `${process.env.NODE_ENV}.config.js`),
+        rootDir: this.rootDir,
+        log: (...args) => this.logger.log(...args)
+      }
+
+      await runMigrations({ ...options, dryRun: this.args['dry-run'] === true })
+
+      this.config = await new Config({ ...options, appName: this.name }).load()
+      this.logger = new Logger({ levels: this.getConfig('logLevels'), showTimestamp: this.getConfig('showLogTimestamp') })
+      this.errors = new Errors(options)
+      this.lang = new Lang({ ...options, defaultLang: this.getConfig('defaultLang') })
+
+      await this.dependencyloader.loadModules()
 
-    let startError
-    try {
-      await this.start()
       this.log('verbose', 'GIT', 'INFO', this.git)
       this.log('verbose', 'DIR', 'rootDir', this.rootDir)
       this.log('verbose', 'DIR', 'dataDir', this.getConfig('dataDir'))
       this.log('verbose', 'DIR', 'tempDir', this.getConfig('tempDir'))
-    } catch (e) {
-      startError = e
+    } catch (cause) {
+      await this.setReady(new Error('Failed to start App', { cause }))
+      process.exit(1)
     }
     const failedMods = this.dependencyloader.failedModules
     if (failedMods.length) this.log('warn', `${failedMods.length} module${failedMods.length === 1 ? '' : 's'} failed to load: ${failedMods}. See above for details`)
-    if (startError) {
-      process.exitCode = 1
-      const e = new Error('Failed to start App')
-      e.cause = startError
-      throw e
-    }
   }
 
   /**
@@ -101,21 +137,6 @@ class App extends AbstractModule {
     }
   }
 
-  /**
-   * Starts the app
-   * @return {Promise} Resolves when the app has started
-   */
-  async start () {
-    if (this._isReady) throw new Error('warn', 'cannot start app, already started')
-    if (this._isStarting) throw new Error('warn', 'cannot start app, already initialising')
-
-    this._isStarting = true
-
-    await this.dependencyloader.load()
-
-    this._isStarting = false
-  }
-
   /**
    * Enables waiting for other modules to load
    * @param {...String} modNames Names of modules to wait for
@@ -125,12 +146,6 @@ class App extends AbstractModule {
     const results = await Promise.all(modNames.map(m => this.dependencyloader.waitForModule(m)))
     return results.length > 1 ? results : results[0]
   }
-
-  /** @override */
-  setReady (error) {
-    this._isStarting = false
-    super.setReady(error)
-  }
 }
 
 export default App