@modernpoacher/halacious 7.0.3 → 7.0.4

package/src/plugin.mjs

@@ -1,59 +1,77 @@
+/**
+ * @typedef {import('@modernpoacher/halacious').HalaciousTypes.Representation} Representation
+ */
+
 import joi from 'joi'
 import * as boom from '@hapi/boom'
 import * as hoek from '@hapi/hoek'
-import _ from 'lodash'
-import fs from 'node:fs'
+import {
+  readdirSync,
+  readFileSync
+} from 'node:fs'
 import path from 'node:path'
+import util from 'node:util'
+import url from 'node:url'
+import _ from 'lodash'
 import pug from 'pug'
-import util from 'util'
 import async from 'async'
 import {
   marked
 } from 'marked'
-import url from 'url'
+import debug from 'debug'
 import URI from 'urijs'
 import * as urlTemplate from 'url-template'
-import Negotiator from 'negotiator'
 import URITemplate from 'urijs/src/URITemplate.js'
-import IAM from '#where-am-i'
-import RepresentationFactory from './representation.mjs'
 
-const HAL_MIME_TYPE = 'application/hal+json'
-
-const REG = /{([^{}]+)}|([^{}]+)/g
-
-const PKG = JSON.parse(fs.readFileSync(path.join(IAM, './package.json')))
-
-function reach (object, path) {
-  const parts = path ? path.split('.') : []
+import PKG from '#package' assert { type: 'json' }
+import IAM from '#where-am-i'
 
-  for (let i = 0; i < parts.length && !_.isUndefined(object); i++) {
-    object = object[parts[i]]
-  }
+import RepresentationFactory from './representation.mjs'
 
-  return object
+import {
+  getRepresentationEntity,
+  getRepresentationSelfHref,
+  getRepresentationRequest,
+  getRepresentationRequestPath,
+  getRouteSettingsPluginsHal,
+  getRouteSettingsPluginsHalApi,
+  getRouteSettingsPluginsHalQuery,
+  getRouteSettingsIsInternal,
+  getRequestRoute,
+  getRequestHeadersAccept,
+  getRequestServer,
+  getRequestResponse,
+  getRequestResponseSource,
+  getRequestResponseHeadersLocation,
+  getResponseVariety,
+  getResponseStatusCode,
+  isResponseStatusCodeInSuccessRange,
+  getPath,
+  hasPath,
+  getName,
+  hasName,
+  getPrefix,
+  getRels,
+  hasRels,
+  getAbsolute,
+  getQuery,
+  getIgnore,
+  getMediaType,
+  getTemplateContext,
+  isRelativePath
+} from './utils.mjs'
+
+function sortByName ({ name: alpha }, { name: omega }) {
+  return (
+    alpha.localeCompare(omega)
+  )
 }
 
-/**
- * evaluates and flattens deep expressions (e.g. '/{foo.a.b}') into a single level context object: {'foo.a.b': value}
- * so that it may be used by url-template library
- * @param template
- * @param ctx
- * @return {{}}
- */
-function flattenContext (template, ctx) {
-  let arr
-  const result = {}
+const HAL_MIME_TYPE = 'application/hal+json'
 
-  while ((arr = REG.exec(template)) !== null) {
-    if (arr[1]) {
-      const value = reach(ctx, arr[1])
-      result[arr[1]] = value && value.toString()
-    }
-  }
+const log = debug('@modernpoacher/halacious')
 
-  return result
-}
+log('`@modernpoacher/halacious` is awake')
 
 const optionsSchema = joi.object({
   absolute: joi.boolean().default(false),
@@ -80,268 +98,164 @@ const optionsSchema = joi.object({
   marked: joi.object().default({})
 })
 
-/**
- * Registers plugin routes and an "api" object with the hapi server.
- * @param server
- * @param opts
- * @param next
- */
-export const plugin = {
-  pkg: PKG,
-
-  async register (server, opts) {
-    let settings = opts
-
-    const { error, value } = optionsSchema.validate(opts)
-
-    if (error) throw error
-
-    settings = value
-
-    marked.setOptions(settings.marked)
-
-    const selection = settings.apiServerLabel
-      ? server.select(settings.apiServerLabel)
-      : server
-
-    const internals = {}
-
-    // for tracking down namespaces
-    internals.byName = {}
-    internals.byPrefix = {}
-
-    // valid rel options
-    internals.relSchema = joi.object({
-      // the rel name, will default to file's basename if available
-      name: joi.string().required(),
-
-      // a path to the rel's documentation in html or markdown
-      file: joi.string().optional(),
-
-      // a short textual description
-      description: joi.string().optional(),
-
-      // returns the qualified name of the rel (including the namespace)
-      qname: joi
-        .function()
-        .optional()
-        .default(function () {
-          return function () {
-            return this.namespace
-              ? util.format('%s:%s', this.namespace.prefix, this.name)
-              : this.name
-          }
-        })
-    }).unknown()
-
-    // valid namespace options
-    internals.nsSchema = joi.object({
-      // the namespace name, will default to dir basename if available
-      name: joi.string().required(),
-
-      // a path to a directory containing rel descriptors. all rels will automatically be added
-      dir: joi.string().optional(),
-
-      // the namespace prefix for shorthand rel addressing (e.g. 'prefix:relname')
-      prefix: joi.string().optional().default(joi.ref('name')),
-
-      // a short description
-      description: joi.string().optional(),
-
-      // a map of rel objects, keyed by name
-      rels: joi.object().optional(),
+// valid rel options
+const relSchema = joi.object({
+  // the rel name, will default to file's basename if available
+  name: joi.string().required(),
+
+  // a path to the rel's documentation in html or markdown
+  file: joi.string().optional(),
+
+  // a short textual description
+  description: joi.string().optional(),
+
+  // returns the qualified name of the rel (including the namespace)
+  qname: joi
+    .function()
+    .optional()
+    .default(function getQName () {
+      return function qname () {
+        return this.namespace
+          ? util.format('%s:%s', getPrefix(this.namespace), this.name)
+          : this.name
+      }
+    })
+}).unknown()
 
-      // validates and adds a rel to the namespace
-      rel: joi
-        .function()
-        .optional()
-        .default(function () {
-          return function (rel) {
-            this.rels = this.rels || {}
+// valid namespace options
+const namespaceSchema = joi.object({
+  // the namespace name, will default to dir basename if available
+  name: joi.string().required(),
 
-            if (_.isString(rel)) rel = { name: rel }
+  // a path to a directory containing rel descriptors. all rels will automatically be added
+  dir: joi.string().optional(),
 
-            rel.name =
-              rel.name ||
-              (rel.file && path.basename(rel.file, path.extname(rel.file)))
+  // the namespace prefix for shorthand rel addressing (e.g. 'prefix:relname')
+  prefix: joi.string().optional().default(joi.ref('name')),
 
-            const { error, value } = internals.relSchema.validate(rel)
-            if (error) throw error
+  // a short description
+  description: joi.string().optional(),
 
-            rel = value
+  // a map of rel objects, keyed by name
+  rels: joi.object().optional(),
 
-            this.rels[rel.name] = rel
-            rel.namespace = this
-            return this
-          }
-        }),
-
-      // synchronously scans a directory for rel descriptors and adds them to the namespace
-      scanDirectory: joi
-        .function()
-        .optional()
-        .default(function () {
-          return function (directory) {
-            const files = fs.readdirSync(directory)
-            files.forEach(function (file) {
-              this.rel({ file: path.join(directory, file) })
-            }, this)
-
-            return this
-          }
-        })
-    })
+  // validates and adds a rel to the namespace
+  rel: joi
+    .function()
+    .optional()
+    .default(function getRel () {
+      return function rel (rel) {
+        if (!hasRels(this)) this.rels = {}
 
-    internals.filter = function (request) {
-      return _.get(request.route.settings, 'plugins.hal', true)
-    }
+        if (_.isString(rel)) rel = { name: rel }
 
-    /**
-     * Returns a list of all registered namespaces sorted by name
-     * @return {*}
-     */
-    internals.namespaces = function () {
-      return _.sortBy(_.values(internals.byName), 'name')
-    }
+        if (!hasName(rel)) rel.name = (rel.file && path.basename(rel.file, path.extname(rel.file)))
 
-    /**
-     * Validates and adds a new namespace configuration
-     * @param namespace the namespace config
-     * @return {*} a new namespace object
-     */
-    internals.namespaces.add = function (namespace) {
-      // if only dir is specified
-      namespace.name =
-        namespace.name || (namespace.dir && path.basename(namespace.dir))
+        const { error, value } = relSchema.validate(rel)
+        if (error) throw error
 
-      // fail fast if the namespace isnt valid
-      const { error, value } = internals.nsSchema.validate(namespace)
+        rel = value
 
-      if (error) throw error
+        const relName = getName(rel)
+        const rels = getRels(this)
 
-      namespace = value
+        Reflect.set(rels, relName, rel)
 
-      // would prefer to initialize w/ joi but it keeps a static reference to the value for some reason
-      namespace.rels = {}
+        rel.namespace = this
 
-      if (namespace.dir) {
-        namespace.scanDirectory(namespace.dir)
+        return this
       }
+    }),
+
+  // synchronously scans a directory for rel descriptors and adds them to the namespace
+  scanDirectory: joi
+    .function()
+    .optional()
+    .default(function getScanDirectory () {
+      return function scanDirectory (directory) {
+        const files = readdirSync(directory)
+
+        files
+          .forEach((file) => {
+            this.rel({ file: path.join(directory, file) })
+          })
 
-      // index and return
-      internals.byName[namespace.name] = namespace
-      internals.byPrefix[namespace.prefix] = namespace
-
-      return namespace
-    }
+        return this
+      }
+    })
+})
 
-    /**
-     * Removes one or all registered namespaces. Mainly used for testing
-     * @param {String=} namespace the namespace to remove. a falsy value will remove all namespaces
-     */
-    internals.namespaces.remove = function (namespace) {
-      let ns
+// see http://tools.ietf.org/html/draft-kelly-json-hal-06#section-8.2
+const linkSchema = joi.object({
+  href: joi.alternatives([joi.string(), joi.function()]).required(),
+  templated: joi.boolean().optional(),
+  title: joi.string().optional(),
+  type: joi.string().optional(),
+  deprecation: joi.string().optional(),
+  name: joi.string().optional(),
+  profile: joi.string().optional(),
+  hreflang: joi.string().optional()
+})
 
-      if (!namespace) {
-        internals.byName = {}
-        internals.byPrefix = {}
-      } else {
-        ns = internals.byName[namespace]
-        if (ns) {
-          delete internals.byName[namespace]
-          delete internals.byPrefix[namespace.prefix]
-        }
-      }
+/**
+ * Wraps callback functions
+ *
+ * @param {(err: Error | null, any) => void} done
+ * @return {(err: Error | null, any) => void}
+ */
+function wrap (done, representation) {
+  return function wrap (err, result) {
+    if (err instanceof Error) {
+      done(err)
+    } else {
+      done(null, result || representation)
     }
+  }
+}
 
-    /**
-     * Looks up a specific namespace
-     * @param namespace
-     * @return {*}
-     */
-    internals.namespace = function (namespace) {
-      return internals.byName[namespace]
-    }
+/**
+ * Registers plugin routes and an "api" object with the hapi server
+ *
+ * @param server
+ * @param opts
+ * @param {(err: Error | null, any) => void} done
+ */
+export const plugin = {
+  pkg: PKG,
 
-    /**
-     * Sorts and returns all rels by namespace
-     * @return {*}
-     */
-    internals.rels = function () {
-      let rels = []
-      _.values(internals.byName).forEach((ns) => {
-        rels = rels.concat(_.values(ns.rels) || [])
-      })
-      return _.sortBy(rels, 'name')
-    }
+  async register (server, opts) {
+    const { error, value: settings } = optionsSchema.validate(opts)
 
-    /**
-     * Adds a new rel configuration to a namespace
-     * @param {String} namespace the namespace name
-     * @param rel the rel configuration
-     * @return the new rel
-     */
-    internals.rels.add = function (namespace, rel) {
-      const ns = internals.byName[namespace]
-      if (!ns) throw new Error(`Invalid namespace ${namespace}`)
-      ns.rel(rel)
-      return ns.rels[rel.name]
-    }
+    if (error) throw error
 
-    /**
-     * Looks up a rel under a given namespace
-     * @param {String} namespace the namespace name
-     * @param {String} name the rel name
-     * @return {*} the rel or undefined if not found
-     */
-    internals.rel = function (namespace, name) {
-      let parts, ns, rel
+    marked.setOptions(settings.marked)
 
-      if (!name) {
-        // for shorthand namespace:rel notation
-        if (namespace.indexOf(':') > 0) {
-          parts = namespace.split(':')
-          ns = internals.byPrefix[parts[0]]
-          name = parts[1]
-        }
-      } else {
-        ns = internals.byName[namespace]
-      }
+    const selection = settings.apiServerLabel
+      ? server.select(settings.apiServerLabel)
+      : server
 
-      // namespace is valid, check for rel
-      if (ns) {
-        if (ns.rels[name]) {
-          // rel has been defined
-          rel = ns.rels[name]
-        } else if (!settings.strict) {
-          // lazily create the rel
-          ns.rel({ name })
-          rel = ns.rels[name]
-        } else {
-          // could be a typo, fail fast to let the developer know
-          throw new Error(`No such rel: "${namespace}"`)
-        }
-      } else {
-        // could be globally qualified (e.g. 'self')
-        const { error, value } = internals.relSchema.validate({ name: namespace })
-        if (error) throw error
+    const byName = new Map()
+    const byPrefix = new Map()
 
-        rel = value
-      }
+    // keeps found routes in a cache
+    const routeCache = new Map()
 
-      return rel
+    const internals = {
+      byName,
+      byPrefix
     }
 
     /**
      * Route handler for /rels
+     *
      * @type {{handler: handler}}
      */
-    internals.namespacesRoute = function (relsAuth) {
+    function getRelsRouteConfig (auth) {
       return {
-        auth: relsAuth,
-        handler (req, h) {
+        auth,
+        handler ({ path }, h) {
           return h.view('namespaces', {
-            path: req.path,
+            path,
             namespaces: internals.namespaces()
           })
         }
@@ -350,432 +264,322 @@ export const plugin = {
 
     /**
      * Route handler for /rels/{namespace}/{rel}
+     *
      * @type {{handler: handler}}
      */
-    internals.relRoute = function (relsAuth) {
+    function getRelRouteConfig (auth) {
       return {
-        auth: relsAuth,
-        handler (req, h) {
-          const rel = internals.rel(req.params.namespace, req.params.rel)
+        auth,
+        handler ({ params: { namespace: namespaceName, rel: relName } }, h) {
+          const rel = internals.rel(namespaceName, relName)
+
           if (!rel) {
-            console.warn('rel not found!')
+            log(`Invalid rel "${namespaceName}" ("${relName}")`)
             throw boom.notFound()
           }
 
-          if (rel.file) {
-            const data = fs.readFileSync(rel.file)
+          const {
+            file
+          } = rel
+
+          if (file) {
+            const buffer = readFileSync(file)
+
             if (settings.relsTemplate) {
               return h.view('rel', {
                 rel,
-                relData: marked(data.toString())
+                relData: marked(buffer.toString())
               })
             }
-            return marked(data.toString())
-          }
-          return h.view('rel', { rel })
-        }
-      }
-    }
-
-    // see http://tools.ietf.org/html/draft-kelly-json-hal-06#section-8.2
-    internals.linkSchema = joi.object({
-      href: joi.alternatives([joi.string(), joi.function()]).required(),
-      templated: joi.boolean().optional(),
-      title: joi.string().optional(),
-      type: joi.string().optional(),
-      deprecation: joi.string().optional(),
-      name: joi.string().optional(),
-      profile: joi.string().optional(),
-      hreflang: joi.string().optional()
-    })
-
-    internals.isRelativePath = function (path) {
-      return (
-        path &&
-        (path.substring(0, 2) === './' || path.substring(0, 3) === '../')
-      )
-    }
 
-    /**
-     * Resolves a name
-     * @param link
-     * @param relativeTo
-     */
-    internals.link = function (link, relativeTo) {
-      relativeTo = relativeTo && relativeTo.split('?')[0]
-      link =
-        _.isFunction(link) || _.isString(link)
-          ? { href: link }
-          : hoek.clone(link)
-      const { error, value } = internals.linkSchema.validate(link)
-
-      if (error) throw error
-      link = value
+            return marked(buffer.toString())
+          }
 
-      if (
-        relativeTo &&
-        (internals.isRelativePath(link.href) || settings.absolute)
-      ) {
-        try {
-          link.href = new URI(link.href)
-            .absoluteTo(`${relativeTo}/`)
-            .toString()
-        } catch (e) {
-          console.warn(e)
-          return link
+          return h.view('rel', { rel })
         }
       }
-      return link
     }
 
-    // keeps found routes in a cache
-    internals.routeCache = {}
-
     /**
      * Locates a named route. This feature may not belong here
+     *
      * @param routeName
      * @return {*}
      */
-    internals.locateRoute = function (routeName) {
-      if (internals.routeCache[routeName]) {
-        return internals.routeCache[routeName].path
+    function getRouteFromRouteCache (routeName) {
+      if (!routeCache.has(routeName)) {
+        routeCache.set(routeName, (
+          server
+            .table()
+            .find((route) => (
+              getName(getRouteSettingsPluginsHal(route)) === routeName
+            ))
+        ))
       }
 
-      const routes = server.table()
-
-      routes.forEach((route) => {
-        if (
-          route.settings.plugins.hal &&
-          route.settings.plugins.hal.name === routeName
-        ) {
-          internals.routeCache[routeName] = route
-        }
-      })
-
-      return internals.routeCache[routeName]
-    }
-
-    /**
-     * Locates a named route and expands templated parameters
-     * @param routeId
-     * @param params
-     * @return String the expanded path to the named route
-     */
-    internals.route = function (routeId, params) {
-      const route = server.lookup(routeId) || internals.locateRoute(routeId)
-      if (!route) throw new Error(`No route found with id or name ${routeId}`)
-      const href = _.template(route.path, {
-        interpolate: /{([\s\S]+?)(?:\?|\*\d*)??}/g
-      })(
-        _.mapValues(params, (val) =>
-          typeof val !== 'object' ? encodeURIComponent(val) : val
-        )
+      return (
+        routeCache.get(routeName)
       )
-      const query = hoek.reach(route.settings, 'plugins.hal.query')
-      return query ? href + query : href
-    }
-
-    /**
-     * Returns the documentation link to a namespace
-     * @param request
-     * @param namespace
-     * @return {*}
-     */
-    internals.namespaceUrl = function (request, namespace) {
-      const path = [settings.relsPath, namespace.name].join('/')
-
-      if (settings.absolute) {
-        return internals.buildUrl(request, path)
-      }
-
-      return path
     }
 
     /**
      * Configures a representation with parameters specified by a hapi route config. The configuration object may
      * include 'links', 'embedded', and 'prepare' properties.
-     * @param {Representation} rep the representation to configure
-     * @param {{}} config the config object
-     * @param callback
+     *
+     * @param {Record<string, any>} config the config object
+     * @param {Representation} representation the representation to configure
+     * @param {(err: Error | null, any) => void} done
      */
-    internals.configureRepresentation = function configureRepresentation (
-      rep,
+    function configureRepresentation (
       config,
-      callback
+      representation,
+      done
     ) {
-      const resolveHref = function (href, ctx) {
+      function getHref (href, context) {
         return _.isFunction(href)
-          ? href(rep, ctx)
-          : urlTemplate.parseTemplate(href).expand(flattenContext(href, ctx))
+          ? href(representation, context)
+          : urlTemplate.parseTemplate(href).expand(getTemplateContext(href, context))
       }
 
-      try {
-        const { entity } = rep
+      /**
+       * @param {Record<string, any>} config the config object
+       * @param {Representation} representation the representation to configure
+       * @param {(err: Error | null, any) => void} done
+       */
+      function prepareEntity (representation, done) {
+        const { prepare } = config
+
+        if (_.isFunction(prepare)) {
+          prepare(representation, wrap(done, representation))
+        } else {
+          done(null, representation)
+        }
+      }
 
+      /**
+       * @param {Record<string, any>} config the config object
+       * @param {Representation} representation the representation to configure
+       * @param {(err: Error | null, any) => void} done
+       */
+      function cascadeEntity (config, representation, done) {
+        representation.ignore(getIgnore(config))
+
+        // cascade the async config functions
+        prepareEntity(representation, done)
+      }
+
+      try {
         // shorthand prepare function
         if (_.isFunction(config)) config = { prepare: config }
 
-        // configure links
-        _.forEach(config.links, (link, rel) => {
-          const repLink = internals.link(link, rep.self.href)
-          repLink.href = resolveHref(repLink.href, entity)
-          rep.link(rel, repLink)
+        if (Reflect.has(config, 'links')) {
+          const links = Reflect.get(config, 'links')
 
-          // grab query options
-          if (config.query) {
-            repLink.href += config.query
-          }
-        })
+          const entity = getRepresentationEntity(representation)
 
-        /**
-         * Wraps callback functions to support next(rep) instead of next(null, rep)
-         * @param callback
-         * @return {Function}
-         */
-        const wrap = function (callback) {
-          return function (err, result) {
-            if (err instanceof Error) {
-              callback(err)
-            } else {
-              callback(null, result || rep)
-            }
-          }
-        }
+          Object.entries(links)
+            .forEach(([rel, link]) => {
+              const representationLink = internals.link(link, getRepresentationSelfHref(representation))
+              representationLink.href = getHref(representationLink.href, entity)
+              representation.link(rel, representationLink)
 
-        /**
-         * Looks for an asynchronous prepare method for programmatic configuration of the outbound hal entity. As with
-         * toHal(), the prepare method can modify the existing rep or create an entirely new one.
-         * @param rep
-         * @param callback
-         */
-        const prepareEntity = function (rep, callback) {
-          if (_.isFunction(config.prepare)) {
-            config.prepare(rep, wrap(callback))
-          } else {
-            callback(null, rep)
-          }
+              // grab query options
+              if (config.query) {
+                representationLink.href += config.query
+              }
+            })
         }
 
-        // configure embedded declarations. each rel entry is also a representation config object
-        async.each(
-          Object.keys(config.embedded || {}),
-          (rel, cb) => {
-            const embed = config.embedded[rel]
+        if (Reflect.has(config, 'embedded')) {
+          // configure embedded declarations. each rel entry is also a representation config object
+          const embedded = Reflect.get(config, 'embedded')
 
-            // assume that arrays should be embedded as a collection
-            if (!embed.path) {
-              throw new Error(
-                `Error in route ${rep.request.path}: "embedded" route configuration property requires a path`
-              )
-            }
-            let embedded = hoek.reach(entity, embed.path)
-            if (!embedded) return cb()
+          const entity = getRepresentationEntity(representation)
 
-            // force the embed array to be inialized. no self rel is necessary
-            if (_.isArray(embedded)) rep.embed(rel, null, [])
+          async.each(
+            Object.entries(embedded),
+            ([rel, route], done) => {
+              // assume that arrays should be embedded as a collection
+              if (!hasPath(route)) {
+                throw new Error(
+                    `Invalid route "${getRepresentationRequestPath(representation)}": "embedded" route configuration property requires a path`
+                )
+              }
 
-            // force into an array for iterating
-            embedded = [].concat(embedded)
+              let embedded = hoek.reach(entity, getPath(route))
 
-            // embedded reps probably also shouldnt appear in the object payload
-            rep.ignore(embed.path)
+              if (!embedded) return done()
 
-            async.each(
-              embedded,
-              (item, acb) => {
-                const link = internals.link(
-                  resolveHref(embed.href, { self: entity, item }),
-                  rep.self.href
-                )
+              // force the embed array to be inialized. no self rel is necessary
+              if (_.isArray(embedded)) representation.embed(rel, null, [])
 
-                // create the embedded representation from the possibly templated href
-                let embeddedRep = rep.embed(rel, link, item)
-
-                embeddedRep = _.isArray(embeddedRep)
-                  ? embeddedRep
-                  : [embeddedRep]
-                // recursively process its links/embedded declarations
-                async.each(
-                  embeddedRep,
-                  (e, bcb) => {
-                    internals.halifyAndConfigure(e, embed, bcb)
-                  },
-                  acb
-                )
-              },
-              cb
-            )
-          },
-          (err) => {
-            if (err) return callback(err)
+              // force into an array for iterating
+              embedded = [].concat(embedded)
 
-            rep.ignore(config.ignore)
+              // embedded reps probably also shouldnt appear in the object payload
+              representation.ignore(getPath(route))
 
-            // cascade the async config functions
-            prepareEntity(rep, callback)
-          }
-        )
-      } catch (e) {
-        callback(e)
-      }
-    }
+              async.each(
+                embedded,
+                (item, done) => {
+                  const link = internals.link(
+                    getHref(route.href, { self: entity, item }),
+                    getRepresentationSelfHref(representation)
+                  )
 
-    internals.halifyAndConfigure = function (rep, config, callback) {
-      /**
-       * Wraps callback functions to support next(rep) instead of next(null, rep)
-       * @param callback
-       * @return {Function}
-       */
-      const wrap = function (callback) {
-        return function (err, result) {
-          if (err instanceof Error) {
-            callback(err)
-          } else {
-            callback(null, result || rep)
-          }
+                  // create the embedded representation from the possibly templated href
+                  let embedded = representation.embed(rel, link, item)
+
+                  // force into an array for iterating
+                  embedded = [].concat(embedded)
+
+                  // recursively process its links/embedded declarations
+                  async.each(
+                    embedded,
+                    (representation, done) => {
+                      transformRepresentationEntity(route, representation, done)
+                    },
+                    done
+                  )
+                },
+                done
+              )
+            },
+            (err) => {
+              if (err) return done(err)
+
+              return (
+                cascadeEntity(config, representation, done)
+              )
+            }
+          )
+        } else {
+          return (
+            cascadeEntity(config, representation, done)
+          )
         }
+      } catch (e) {
+        done(e)
       }
+    }
 
+    function transformRepresentationEntity (
+      config,
+      representation,
+      done
+    ) {
       /**
-       * Looks for a toHal(representation, next) method on the entity. If found, it is called asynchronously. The method may modify the
-       * representation or pass back a completely new representation by calling next(newRep)
-       * @param callback
+       * Looks for a toHal(representation, done) method on the entity. If found, it is called asynchronously. The method may modify the
+       * representation or pass back a completely new representation by calling done(newRep)
+       *
+       * @param {(err: Error | null, any) => void} done
        */
-      const convertEntity = function (callback) {
-        if (_.isFunction(rep.entity.toHal)) {
-          rep.entity.toHal(rep, wrap(callback))
+      function transformEntity (done) {
+        const { toHal } = getRepresentationEntity(representation)
+
+        if (_.isFunction(toHal)) {
+          toHal(representation, wrap(done, representation))
         } else {
-          callback(null, rep)
+          done(null, representation)
         }
       }
 
-      const configureEntity = function (rep, callback) {
-        internals.configureRepresentation(rep, config, callback)
-      }
-
-      async.waterfall([convertEntity, configureEntity], callback)
-    }
-
-    /**
-     * Selects the media type based on the request's Accept header and a ranked ordering of configured
-     * media types.
-     * @param mediaTypes
-     * @param request
-     * @return {*}
-     */
-    internals.getMediaType = function (mediaTypes, request) {
-      return new Negotiator(request).mediaType(
-        _.isArray(mediaTypes) ? mediaTypes : [mediaTypes]
+      async.waterfall(
+        [
+          transformEntity,
+          (representation, done) => {
+            configureRepresentation(config, representation, done)
+          }
+        ],
+        done
       )
     }
 
     /**
-     * Expands the url path to include protocol://server:port
-     * @param request
-     * @param path
-     * @param search
-     * @return {*}
-     */
-    internals.buildUrl = function (request, path, search) {
-      return url.format({
-        host: settings.host || request.headers.host,
-        hostname: settings.hostname || request.info.host,
-        port: settings.port || request.info.port,
-        pathname: path,
-        protocol: settings.protocol || request.info.protocol || 'http',
-        search
-      })
-    }
-
-    /**
-     * Expands the query string template, if present, using query parameter values in the request.
+     * Expands the query string template, if present, using query parameter values in the request
+     *
      * @param request
      * @param queryTemplate
-     * @param { boolean } absolute whether the link should be expanded to include the server
+     * @param {boolean} isAbsolute whether the link should be expanded to include the server
      * @return {*}
      */
-    internals.getRequestPath = function (request, queryTemplate, absolute) {
-      let uriTemplate
-
-      const path = absolute
-        ? internals.buildUrl(request, request.path)
-        : request.path
+    function getRequestPath (request, queryTemplate, isAbsolute) {
+      const path = isAbsolute
+        ? internals.buildUrl(request, getPath(request))
+        : getPath(request)
 
       if (queryTemplate) {
-        uriTemplate = new URITemplate(path + queryTemplate)
-        return uriTemplate.expand(request.query)
+        const uriTemplate = new URITemplate(path + queryTemplate)
+        return (
+          uriTemplate.expand(request.query)
+        )
       }
+
       return path
     }
 
     /**
-     * Resolves a relative url. Borrowed from hapi
+     * Resolves to a relative URL
+     *
      * @param request
-     * @param uri
-     * @param absolute
+     * @param {string} uri
+     * @param {boolean} isAbsolute
      * @return {*}
      */
-    internals.location = function (request, uri, absolute) {
-      const isAbsolute = uri.match(/^\w+:\/\//)
+    function getRelativeUrl (request, uri, isAbsolute) {
+      let relativeUrl = null
+      let queryParams = null
 
-      let path = isAbsolute ? uri : (uri.charAt(0) === '/' ? '' : '/') + uri
-      let search = null
-
-      if (isAbsolute) {
-        path = uri
+      if (uri.match(/^\w+:\/\//)) {
+        relativeUrl = uri
       } else {
-        const parts = uri.split('?')
-        path = (parts[0].charAt(0) === '/' ? '' : '/') + parts[0]
-        if (parts.length > 1) {
-          // eslint-disable-next-line prefer-destructuring
-          search = parts[1]
-        }
-      }
+        const [
+          route = '',
+          query = null
+        ] = uri.split('?')
 
-      if (absolute) {
-        path = internals.buildUrl(request, path, search)
+        relativeUrl = route.startsWith('/') ? route : '/' + route
+        queryParams = query || queryParams
       }
-      return path
-    }
 
-    internals.successfulResponseCode = function (statusCode) {
-      return statusCode >= 200 && statusCode < 300
-    }
+      if (isAbsolute) {
+        relativeUrl = internals.buildUrl(request, relativeUrl, queryParams)
+      }
 
-    internals.isSourceEligible = function (source) {
-      return _.isObject(source) && !_.isArray(source)
+      return relativeUrl
     }
 
-    internals.isAcceptHeaderValid = function (request) {
-      const accept = request.headers.accept || ''
-
+    function isAcceptHeaderValid (request) {
       return (
         !settings.requireHalJsonAcceptHeader ||
-        accept.toLowerCase().indexOf(HAL_MIME_TYPE) >= 0
+        (getRequestHeadersAccept(request) ?? '').toLowerCase().includes(HAL_MIME_TYPE)
       )
     }
 
-    internals.isRequestEligible = function (request) {
-      // hapi 9/10 routes can be marked internal only
+    function isSourceEligible (source) {
+      return _.isObject(source) && !_.isArray(source)
+    }
+
+    function isRequestEligible (request) {
       return (
-        !request.route.settings.isInternal &&
-        internals.isAcceptHeaderValid(request) &&
+        !getRouteSettingsIsInternal(getRequestRoute(request)) && // hapi 9/10 routes can be marked internal only
+        isAcceptHeaderValid(request) &&
         internals.filter(request)
       )
     }
 
-    internals.isResponseEligible = function (response) {
+    function isResponseEligible (response) {
       return (
-        response.variety === 'plain' &&
-        internals.successfulResponseCode(response.statusCode)
+        getResponseVariety(response) === 'plain' &&
+        isResponseStatusCodeInSuccessRange(getResponseStatusCode(response))
       )
     }
 
-    internals.shouldHalify = function (request) {
+    function isEligible (request) {
       return (
-        internals.isRequestEligible(request) &&
-        internals.isResponseEligible(request.response) &&
-        internals.isSourceEligible(request.response.source)
+        isRequestEligible(request) &&
+        isResponseEligible(getRequestResponse(request)) &&
+        isSourceEligible(getRequestResponseSource(request))
       )
     }
 
@@ -784,85 +588,367 @@ export const plugin = {
      * the plugins.hal.api configuration settings. This function is exported for convenience if the developer wishes to
      * define his or her own api handler in order to include metadata in the payload
      *
-     * @param absolute
-     * @param rep
-     * @param next
+     * @param {boolean} isAbsolute
+     * @param {Representation} representation
+     * @param {(err: Error | null, any) => void} done
      */
-    internals.apiLinker = function (absolute, rep, next) {
+    function toHal (isAbsolute, representation, done) {
+      const request = getRepresentationRequest(representation)
+
       // grab the routing table and iterate
-      const req = rep.request
+      const server = getRequestServer(request)
 
-      const routes = req.server.table()
+      server.table()
+        .forEach((route) => {
+          const api = getRouteSettingsPluginsHalApi(route)
 
-      for (let i = 0; i < routes.length; i++) {
-        const route = routes[i]
+          if (api) {
+            let {
+              path: uri = ''
+            } = route
 
-        const halConfig = route.settings.plugins.hal || {}
+            if (isAbsolute) {
+              uri = internals.buildUrl(request, uri)
+            }
 
-        if (halConfig.api) {
-          const rel = halConfig.api
-          let href = routes[i].path
+            const query = getRouteSettingsPluginsHalQuery(route)
 
-          if (absolute) {
-            href = internals.buildUrl(rep.request, href)
-          }
+            // grab query options
+            if (query) {
+              uri += query
+            }
 
-          // grab query options
-          if (halConfig.query) {
-            href += halConfig.query
+            representation.link(api, uri)
           }
+        })
 
-          rep.link(rel, href)
-        }
-      }
-      next()
+      done()
     }
 
     /**
      * Creates an auto api route configuration
-     * @param absolute
-     * @param apiAuth
-     * @return {{auth: *, handler: handler, plugins: {hal: apiLinker}}}
+     *
+     * @param auth
+     * @param {boolean} isAbsolute
+     * @return {{auth: *, handler: handler, plugins: {hal: toHal}}}
      */
-    internals.apiRouteConfig = function (absolute, apiAuth) {
+    function getApiRouteConfig (auth, isAbsolute) {
       return {
-        auth: apiAuth,
+        auth,
         handler (req, h) {
           return h.response({}).type(HAL_MIME_TYPE)
         },
         plugins: {
-          hal: internals.apiLinker.bind(null, absolute)
+          hal: toHal.bind(null, isAbsolute)
         }
       }
     }
 
     /**
      * Creates a redirector to redirect the browser from /api to /api/
-     * @param apiUrl
-     * @param apiAuth
+     *
+     * @param auth
+     * @param {string} url
      * @return {{auth: *, handler: handler}}
      */
-    internals.apiRedirectConfig = function (apiUrl, apiAuth) {
+    function getApiRedirectConfig (auth, url) {
       return {
-        auth: apiAuth,
+        auth,
         handler (req, h) {
-          return h.redirect(`${apiUrl}/`)
+          return h.redirect(url.concat('/'))
+        }
+      }
+    }
+
+    /**
+     * Returns namespaces sorted by name
+     *
+     * @return {*}
+     */
+    internals.namespaces = function namespaces () {
+      return (
+        Array
+          .from(byName.values())
+          .sort(sortByName)
+      )
+    }
+
+    /**
+     * Validates and adds a new namespace configuration
+     *
+     * @param namespace the namespace config
+     * @return {*} a new namespace object
+     */
+    internals.namespaces.add = function add (namespace) {
+      // if only dir is specified
+      if (!hasName(namespace)) namespace.name = (namespace.dir && path.basename(namespace.dir))
+
+      // fail fast if the namespace isnt valid
+      const { error, value } = namespaceSchema.validate(namespace)
+
+      if (error) throw error
+
+      namespace = value
+
+      // would prefer to initialize w/ joi but it keeps a static reference to the value for some reason
+      namespace.rels = {}
+
+      if (namespace.dir) {
+        namespace.scanDirectory(namespace.dir)
+      }
+
+      // index and return
+      const name = getName(namespace)
+      const prefix = getPrefix(namespace)
+
+      byName
+        .set(name, namespace)
+      byPrefix
+        .set(prefix, namespace)
+
+      return namespace
+    }
+
+    /**
+     * Removes one or all registered namespaces. Mainly used for testing
+     *
+     * @param {string} name the namespace to remove. a falsy value will remove all namespaces
+     */
+    internals.namespaces.remove = function remove (name) {
+      if (!name) {
+        byName
+          .clear()
+        byPrefix
+          .clear()
+      } else {
+        if (byName.has(name)) {
+          const namespace = byName.get(name)
+
+          const prefix = getPrefix(namespace)
+
+          byName
+            .delete(name)
+          byPrefix
+            .delete(prefix)
+        }
+      }
+    }
+
+    /**
+     * Looks up a specific namespace
+     *
+     * @param namespace
+     * @return {*}
+     */
+    internals.namespace = function namespace (name) {
+      return (
+        byName.get(name)
+      )
+    }
+
+    /**
+     * Returns namespace rels sorted by name
+     *
+     * @return {*}
+     */
+    internals.rels = function rels () {
+      return (
+        Array
+          .from(byName.values())
+          .reduce((accumulator, { rels = {} }) => accumulator.concat(Object.values(rels)), [])
+          .sort(sortByName)
+      )
+    }
+
+    /**
+     * Adds a new rel configuration to a namespace
+     *
+     * @param {string} name the namespace name
+     * @param rel the rel configuration
+     * @return the new rel
+     */
+    internals.rels.add = function add (name, rel) {
+      if (!byName.has(name)) throw new Error(`Invalid namespace "${name}"`)
+
+      const namespace = byName.get(name)
+
+      namespace.rel(rel)
+
+      const relName = getName(rel)
+      const rels = getRels(namespace)
+
+      return (
+        Reflect.get(rels, relName)
+      )
+    }
+
+    /**
+     * Looks up a rel under a given namespace
+     * @param {string} namespaceName the namespace name
+     * @param {string} relName the rel name
+     * @return {*} the rel or undefined if not found
+     */
+    internals.rel = function rel (namespaceName, relName) {
+      if (!namespaceName) throw new Error(`Invalid rel "${namespaceName}"`)
+
+      let namespace
+      let rel
+
+      if (!relName) {
+        // for shorthand namespace:rel notation
+        if (namespaceName.includes(':')) {
+          const [prefix, name] = namespaceName.split(':')
+          namespace = byPrefix.get(prefix)
+          relName = name
+        }
+      } else {
+        namespace = byName.get(namespaceName)
+      }
+
+      // namespace is valid, check for rel
+      if (namespace) {
+        const rels = getRels(namespace)
+
+        if (!Reflect.has(rels, relName)) {
+          if (!settings.strict) {
+            // lazily create the rel
+            namespace.rel({ name: relName })
+          } else {
+            // could be a typo, fail fast to let the developer know
+            throw new Error(`Invalid rel "${namespaceName}" ("${relName}")`)
+          }
+        }
+
+        rel = Reflect.get(rels, relName)
+      } else {
+        // could be globally qualified (e.g. 'self')
+        const { error, value } = relSchema.validate({ name: namespaceName })
+        if (error) throw error
+
+        rel = value
+      }
+
+      return rel
+    }
+
+    /**
+     * Resolves a name
+     *
+     * @param link
+     * @param relativeTo
+     */
+    internals.link = function link (link, relativeTo) {
+      link = (
+        _.isFunction(link) || _.isString(link)
+          ? { href: link }
+          : hoek.clone(link)
+      )
+
+      const { error, value } = linkSchema.validate(link)
+
+      if (error) throw error
+
+      link = value
+
+      relativeTo = (relativeTo ?? '').split('?').shift().trim()
+
+      if (
+        relativeTo &&
+        (isRelativePath(link.href) || settings.absolute)
+      ) {
+        try {
+          link.href = (
+            new URI(link.href)
+              .absoluteTo(relativeTo.concat('/'))
+              .toString()
+          )
+        } catch (e) {
+          log(`Invalid URL "${link.href}"`)
+          return link
         }
       }
+
+      return link
+    }
+
+    /**
+     * Locates a named route and expands templated parameters
+     *
+     * @param routeName
+     * @param params
+     * @return String the expanded path to the named route
+     */
+    internals.route = function route (routeName, params) {
+      const route = server.lookup(routeName) || getRouteFromRouteCache(routeName)
+      if (!route) throw new Error(`Invalid route "${routeName}"`)
+
+      const i = /{([\s\S]+?)(?:\?|\*\d*)??}/g
+      const c = Object.fromEntries(Object.entries(params).map(([key, value]) => [key, typeof value !== 'object' ? encodeURIComponent(value) : value]))
+
+      const href = _.template(getPath(route), { interpolate: i })(c)
+
+      const query = getRouteSettingsPluginsHalQuery(route) // hoek.reach(route.settings, 'plugins.hal.query')
+
+      if (query) {
+        return href + query
+      }
+
+      return href
+    }
+
+    /**
+     * Returns the documentation link to a namespace
+     *
+     * @param request
+     * @param namespace
+     * @return {*}
+     */
+    internals.namespaceUrl = function namespaceUrl (request, namespace) {
+      const path = [settings.relsPath, getName(namespace)].join('/')
+
+      if (settings.absolute) {
+        return internals.buildUrl(request, path)
+      }
+
+      return path
+    }
+
+    internals.filter = function filter (request) {
+      return getRouteSettingsPluginsHal(getRequestRoute(request)) // _.get(getRouteSettings(getRequestRoute(request)), 'plugins.hal', true)
+    }
+
+    /**
+     * Expands the url path to include protocol://server:port
+     *
+     * @param request
+     * @param {string} pathname
+     * @param {string | void} search
+     * @return {*}
+     */
+    internals.buildUrl = function buildUrl (request, pathname, search) {
+      return url.format({
+        protocol: settings.protocol || request.info.protocol || 'http',
+        hostname: settings.hostname || request.info.host,
+        pathname,
+        host: settings.host || request.headers.host,
+        port: settings.port || request.info.port,
+        search
+      })
     }
 
     /**
-     * Assigns a filter function to test routes before applying the hal interceptor.
-     * @param filterFn
+     * Assigns a filter function to test routes before applying the hal interceptor
+     *
+     * @param filter
      */
-    internals.setFilter = function (filterFn) {
-      const { error } = joi.function().validate(filterFn)
+    internals.setFilter = function setFilter (filter) {
+      const { error } = joi.function().validate(filter)
       if (error) throw error
 
-      internals.filter = filterFn
+      internals.filter = filter
     }
 
-    internals.setUrlBuilder = function (urlBuilder) {
+    internals.setUrlBuilder = function setUrlBuilder (urlBuilder) {
       const { error } = joi.function().validate(urlBuilder)
       if (error) throw error
 
@@ -876,58 +962,61 @@ export const plugin = {
       link: internals.link,
       rels: internals.rels,
       rel: internals.rel,
-      resolve: internals.resolve,
       route: internals.route,
-      apiLinker: internals.apiLinker,
+      toHal,
       filter: internals.setFilter,
       urlBuilder: internals.setUrlBuilder,
-      configureRepresentation: internals.configureRepresentation
+      configureRepresentation
     }
 
     /**
-     * A hapi lifecycle method that looks for the application/hal+json accept header and wraps the response entity into a
+     * A Hapi lifecycle method that looks for the application/hal+json accept header and wraps the response entity into a
      * HAL representation
+     *
      * @param request
      * @param h
      */
-    internals.postHandler = function (request, h) {
-      let rf, halConfig, entity, rep, self
-      const mediaType = internals.getMediaType(settings.mediaTypes, request)
-      let absolute
-
-      if (mediaType && internals.shouldHalify(request)) {
-        halConfig = request.route.settings.plugins.hal || {}
-
-        // all new representations for the request will be built by this guy
-        rf = new RepresentationFactory(api, request)
-
-        entity = request.response.source
-
-        absolute = halConfig.absolute || settings.absolute
+    internals.postHandler = function postHandler (request, h) {
+      if (isEligible(request)) {
+        const mediaType = getMediaType(request, settings.mediaTypes)
+        if (mediaType) {
+          const config = getRouteSettingsPluginsHal(getRequestRoute(request))
+
+          // e.g. honor the location header if it has been set using response.created(...) or response.location(...)
+          const location = getRequestResponseHeadersLocation(request)
+          const isAbsolute = Boolean(getAbsolute(config) || getAbsolute(settings))
+
+          const self = (
+            location
+              ? getRelativeUrl(request, location, isAbsolute)
+              : getRequestPath(request, getQuery(config), isAbsolute)
+          )
 
-        // e.g. honor the location header if it has been set using response.created(...) or response.location(...)
-        const { location } = request.response.headers
-        self = location
-          ? internals.location(request, location, absolute)
-          : internals.getRequestPath(request, halConfig.query, absolute)
+          // all new representations for the request will be built by this guy
+          const representationFactory = new RepresentationFactory(api, request)
+          const representation = representationFactory.create(getRequestResponseSource(request), self)
 
-        rep = rf.create(entity, self)
+          return (
+            new Promise((resolve, reject) => {
+              transformRepresentationEntity(config, representation, (err, representation) => {
+                if (err) return reject(err)
 
-        return new Promise((resolve, reject) => {
-          internals.halifyAndConfigure(rep, halConfig, (err, rep) => {
-            if (err) {
-              return reject(err)
-            }
+                const response = getRequestResponse(request)
 
-            // send back what they asked for, as plain object
-            // so validation can be done correctly
-            request.response.source = rep.toJSON()
-            request.response.type(mediaType)
+                // send back what they asked for (as plain object
+                // so validation can be done correctly)
+                response.source = representation.toJSON()
+                response.type(mediaType)
 
-            return resolve(h.continue)
-          })
-        })
+                return (
+                  resolve(h.continue)
+                )
+              })
+            })
+          )
+        }
       }
+
       return h.continue
     }
 
@@ -940,24 +1029,27 @@ export const plugin = {
       // bind the API handler to api root + '/'. Ending with '/' is necessary for resolving relative links on the client
       selection.route({
         method: 'GET',
-        path: `${settings.apiPath}/`,
-        config: internals.apiRouteConfig(settings.absolute, settings.apiAuth)
+        path: settings.apiPath.concat('/'),
+        config: getApiRouteConfig(
+          settings.apiAuth,
+          settings.absolute
+        )
       })
 
       // set up a redirect to api root + '/'
-      if (settings.apiPath.length > 0) {
+      if (settings.apiPath) {
         selection.route({
           method: 'GET',
           path: settings.apiPath,
-          config: internals.apiRedirectConfig(
-            settings.apiPath,
-            settings.apiAuth
+          config: getApiRedirectConfig(
+            settings.apiAuth,
+            settings.apiPath
           )
         })
       }
     }
 
-    internals.preStart = function (server) {
+    internals.preStart = function preStart (server) {
       if (_.isFunction(server.views)) {
         server.views({
           engines: {
@@ -966,15 +1058,17 @@ export const plugin = {
           path: path.join(IAM, './views'),
           isCached: false
         })
+
         server.route({
-          method: 'get',
+          method: 'GET',
           path: settings.relsPath,
-          config: internals.namespacesRoute(settings.relsAuth)
+          config: getRelsRouteConfig(settings.relsAuth)
         })
+
         server.route({
-          method: 'get',
+          method: 'GET',
           path: `${settings.relsPath}/{namespace}/{rel}`,
-          config: internals.relRoute(settings.relsAuth)
+          config: getRelRouteConfig(settings.relsAuth)
         })
       }
     }