sounding 0.0.4 → 0.1.0

package/lib/create-app-manager.js

@@ -5,28 +5,93 @@ const { getDefaultConfig } = require('./default-config')
 const { mergeConfig } = require('./merge-config')
 const { normalizeUserConfig } = require('./normalize-config')
 const { buildManagedSqlitePath, resolveManagedRoot } = require('./resolve-datastore')
-
-function resolveModuleFromApp(appPath, moduleId) {
-  return require(require.resolve(moduleId, { paths: [appPath, process.cwd(), __dirname] }))
-}
-
+const { createSoundingError } = require('./create-error')
+const { loadDependencyFromApp, resolveDependencyFromApp } = require('./resolve-dependency')
+const { validateConfig } = require('./validate-config')
+
+/** @typedef {import('./types').AnyRecord} AnyRecord */
+/** @typedef {import('./types').SoundingAppManager} SoundingAppManager */
+/** @typedef {import('./types').SoundingAppManagerOptions} SoundingAppManagerOptions */
+/** @typedef {import('./types').SoundingConfig} SoundingConfig */
+/** @typedef {import('./types').SoundingRuntime} SoundingRuntime */
+/** @typedef {import('./types').SoundingSailsApp} SoundingSailsApp */
+
+/**
+ * @param {string} appPath
+ * @returns {SoundingConfig}
+ */
 function loadAppSoundingConfig(appPath) {
   const configPath = path.join(appPath, 'config', 'sounding.js')
 
   if (!fs.existsSync(configPath)) {
-    return getDefaultConfig()
+    return validateConfig(getDefaultConfig())
   }
 
   delete require.cache[require.resolve(configPath)]
   const loaded = require(configPath)
-  return mergeConfig(getDefaultConfig(), normalizeUserConfig(loaded?.sounding || {}))
+  return validateConfig(
+    /** @type {SoundingConfig} */ (
+      mergeConfig(getDefaultConfig(), normalizeUserConfig(loaded?.sounding || {}))
+    )
+  )
+}
+
+/**
+ * @param {string} appPath
+ * @param {{ resolveImplementation?: (moduleId: string, options?: { paths?: string[] }) => string }} [options]
+ * @returns {any}
+ */
+function defaultLoadSails(appPath, options = {}) {
+  return loadDependencyFromApp({
+    appPath,
+    moduleId: 'sails',
+    purpose: 'load your Sails app',
+    install: 'npm install sails',
+    resolveImplementation: options.resolveImplementation,
+  })
 }
 
-function buildManagedDatastoreOverrides(config, appPath) {
+/**
+ * @param {SoundingConfig} config
+ * @param {string} appPath
+ * @param {{ resolveImplementation?: (moduleId: string, options?: { paths?: string[] }) => string }} [options]
+ * @returns {void}
+ */
+function assertManagedDatastoreDependency(config, appPath, options = {}) {
+  if (config.datastore?.mode !== 'managed') {
+    return
+  }
+
+  const adapter = config.datastore.adapter || 'sails-sqlite'
+
+  if (adapter !== 'sails-sqlite') {
+    return
+  }
+
+  resolveDependencyFromApp({
+    appPath,
+    moduleId: adapter,
+    purpose: 'run managed datastore trials',
+    install: 'npm install -D sails-sqlite',
+    suggestion:
+      'Or set `sounding.datastore` to `inherit` or configure an external datastore if this app should reuse its own test database.',
+    resolveImplementation: options.resolveImplementation,
+  })
+}
+
+/**
+ * @param {SoundingConfig} config
+ * @param {string} appPath
+ * @param {{ resolveImplementation?: (moduleId: string, options?: { paths?: string[] }) => string }} [options]
+ * @returns {AnyRecord}
+ */
+function buildManagedDatastoreOverrides(config, appPath, options = {}) {
   if (config.datastore?.mode !== 'managed') {
     return {}
   }
 
+  assertManagedDatastoreDependency(config, appPath, options)
+
   const identity = config.datastore.identity || 'default'
 
   return {
@@ -49,6 +114,10 @@ function buildManagedDatastoreOverrides(config, appPath) {
   }
 }
 
+/**
+ * @param {Partial<SoundingConfig>} [config]
+ * @returns {{ install(): void, uninstall(): void }}
+ */
 function createOutputFilter(config = {}) {
   if (config.app?.quiet === false) {
     return {
@@ -121,6 +190,76 @@ function createOutputFilter(config = {}) {
   }
 }
 
+/**
+ * @param {'load' | 'lift'} mode
+ * @returns {import('./types').SoundingAppLifecycleState}
+ */
+function createLifecycleState(mode) {
+  return {
+    mode,
+    status: 'idle',
+    runs: 0,
+    reuses: 0,
+    reloads: 0,
+    durationMs: null,
+    startedAt: null,
+    readyAt: null,
+    error: null,
+  }
+}
+
+/**
+ * @returns {boolean}
+ */
+function shouldReportLifecycle() {
+  return (
+    process.env.SOUNDING_LIFECYCLE === 'verbose' ||
+    process.env.SOUNDING_DIAGNOSTICS === 'verbose'
+  )
+}
+
+/**
+ * @param {string} message
+ * @returns {void}
+ */
+function reportLifecycle(message) {
+  if (!shouldReportLifecycle()) {
+    return
+  }
+
+  process.stderr.write(`[sounding] ${message}\n`)
+}
+
+/**
+ * @param {string} method
+ * @param {Record<string, any>} options
+ * @param {string[]} allowed
+ * @returns {void}
+ */
+function assertKnownAppManagerOptions(method, options, allowed) {
+  const unknown = Object.keys(options || {}).filter((key) => !allowed.includes(key))
+
+  if (unknown.length === 0) {
+    return
+  }
+
+  throw createSoundingError({
+    code: 'E_SOUNDING_APP_MANAGER_OPTION_UNKNOWN',
+    name: 'SoundingAppLifecycleError',
+    message: `Sounding app manager option \`${unknown[0]}\` is not supported for ${method}().`,
+    details: {
+      option: unknown[0],
+      allowed,
+      method,
+    },
+  })
+}
+
+/**
+ * @param {SoundingConfig} config
+ * @param {string} appPath
+ * @returns {string | null}
+ */
 function resolveManagedDatastoreFile(config, appPath) {
   if (config.datastore?.mode !== 'managed') {
     return null
@@ -138,11 +277,16 @@ function resolveManagedDatastoreFile(config, appPath) {
   })
 }
 
+/**
+ * @param {SoundingAppManagerOptions} [options]
+ * @returns {SoundingAppManager}
+ */
 function createAppManager({
   appPath = process.cwd(),
   environment = 'test',
   liftOptions = {},
   SailsConstructor,
+  loadSails = defaultLoadSails,
 } = {}) {
   let loadedApp = null
   let liftedApp = null
@@ -150,6 +294,10 @@ function createAppManager({
   let liftPromise = null
   const managedArtifacts = new Set()
   let outputFilter = null
+  const lifecycle = {
+    load: createLifecycleState('load'),
+    lift: createLifecycleState('lift'),
+  }
 
   function resolveAppPath() {
     return path.resolve(appPath)
@@ -164,7 +312,7 @@ function createAppManager({
       return SailsConstructor
     }
 
-    return resolveModuleFromApp(resolveAppPath(), 'sails').constructor
+    return loadSails(resolveAppPath()).constructor
   }
 
   function buildOptions(mode) {
@@ -176,7 +324,9 @@ function createAppManager({
       managedArtifacts.add(managedFile)
     }
 
+    /** @type {AnyRecord} */
     const appConfig = config.app || {}
+    /** @type {AnyRecord} */
     const baseOptions = {
       appPath: resolveAppPath(),
       environment: appConfig.environment || environment,
@@ -194,6 +344,7 @@ function createAppManager({
             appConfig.loadOptions || {}
           )
         : mergeConfig(appConfig.liftOptions || {}, liftOptions)
+    /** @type {AnyRecord} */
     const nextOptions = mergeConfig(baseOptions, modeOptions)
 
     if (mode === 'load' && nextOptions.datastores?.content) {
@@ -218,33 +369,199 @@ function createAppManager({
     }
   }
 
-  async function load() {
+  /**
+   * @param {SoundingSailsApp} app
+   * @returns {void}
+   */
+  function activateGlobalApp(app) {
+    globalThis.sails = app
+    globalThis.sounding = app.sounding || app.hooks?.sounding
+  }
+
+  /**
+   * @returns {void}
+   */
+  function syncGlobalApp() {
+    const activeApp = liftedApp || loadedApp
+
+    if (activeApp) {
+      activateGlobalApp(activeApp)
+      return
+    }
+
+    delete globalThis.sails
+    delete globalThis.sounding
+    outputFilter?.uninstall()
+  }
+
+  /**
+   * @param {'load' | 'lift'} mode
+   * @returns {void}
+   */
+  function recordLifecycleStart(mode) {
+    const entry = lifecycle[mode]
+    entry.status = 'loading'
+    entry.runs += 1
+    entry.error = null
+    entry.startedAt = new Date().toISOString()
+    entry.readyAt = null
+    entry.durationMs = null
+  }
+
+  /**
+   * @param {'load' | 'lift'} mode
+   * @param {number} startedAt
+   * @returns {void}
+   */
+  function recordLifecycleReady(mode, startedAt) {
+    const entry = lifecycle[mode]
+    entry.status = 'ready'
+    entry.durationMs = Date.now() - startedAt
+    entry.readyAt = new Date().toISOString()
+    reportLifecycle(`app ${mode} ready in ${entry.durationMs}ms`)
+  }
+
+  /**
+   * @param {'load' | 'lift'} mode
+   * @param {unknown} error
+   * @returns {void}
+   */
+  function recordLifecycleError(mode, error) {
+    const entry = lifecycle[mode]
+    entry.status = 'error'
+    entry.error = error instanceof Error ? error.message : String(error)
+    reportLifecycle(`app ${mode} failed: ${entry.error}`)
+  }
+
+  /**
+   * @param {'load' | 'lift'} mode
+   * @returns {void}
+   */
+  function recordLifecycleReuse(mode) {
+    const entry = lifecycle[mode]
+    entry.reuses += 1
+    reportLifecycle(`app ${mode} reused warm instance`)
+  }
+
+  /**
+   * @param {'load' | 'lift'} mode
+   * @returns {void}
+   */
+  function recordLifecycleReload(mode) {
+    lifecycle[mode].reloads += 1
+    reportLifecycle(`app ${mode} reload requested`)
+  }
+
+  /**
+   * @param {'load' | 'lift'} mode
+   * @returns {void}
+   */
+  function recordLifecycleIdle(mode) {
+    lifecycle[mode].status = 'idle'
+  }
+
+  /**
+   * @param {SoundingSailsApp} app
+   * @returns {Promise<void>}
+   */
+  async function lowerApp(app) {
+    await new Promise((resolve) => {
+      app.lower(() => resolve())
+    })
+  }
+
+  /**
+   * @param {'load' | 'lift'} mode
+   * @returns {Promise<void>}
+   */
+  async function lowerMode(mode) {
+    const app = mode === 'load' ? loadedApp : liftedApp
+
+    if (mode === 'load') {
+      loadedApp = null
+      loadPromise = null
+    } else {
+      liftedApp = null
+      liftPromise = null
+    }
+
+    if (app) {
+      await lowerApp(app)
+    }
+
+    recordLifecycleIdle(mode)
+    syncGlobalApp()
+  }
+
+  /**
+   * @param {'load' | 'lift'} mode
+   * @param {{ reload?: boolean }} [options]
+   * @returns {Promise<void>}
+   */
+  async function prepareReload(mode, options = {}) {
+    if (!options.reload) {
+      return
+    }
+
+    recordLifecycleReload(mode)
+
+    if (mode === 'load' && loadPromise) {
+      await loadPromise.catch(() => {})
+    }
+
+    if (mode === 'lift' && liftPromise) {
+      await liftPromise.catch(() => {})
+    }
+
+    await lowerMode(mode)
+  }
+
+  /**
+   * @returns {SoundingAppManager['lifecycle']}
+   */
+  function getLifecycleSnapshot() {
+    return {
+      load: { ...lifecycle.load },
+      lift: { ...lifecycle.lift },
+    }
+  }
+
+  async function load(options = {}) {
+    assertKnownAppManagerOptions('load', options, ['reload'])
+    await prepareReload('load', options)
+
     if (loadedApp) {
+      activateGlobalApp(loadedApp)
+      recordLifecycleReuse('load')
       return loadedApp
     }
 
     if (loadPromise) {
+      recordLifecycleReuse('load')
       return loadPromise
     }
 
     const Sails = resolveSailsConstructor()
     const sailsApp = new Sails()
     const nextLoadOptions = buildOptions('load')
+    const startedAt = Date.now()
+    recordLifecycleStart('load')
     outputFilter?.install()
 
     loadPromise = new Promise((resolve, reject) => {
       sailsApp.load(nextLoadOptions, (error, loadedSails) => {
         if (error) {
           loadPromise = null
+          recordLifecycleError('load', error)
           cleanupManagedArtifacts().catch(() => {})
-          outputFilter?.uninstall()
+          syncGlobalApp()
           reject(error)
           return
         }
 
         loadedApp = loadedSails
-        globalThis.sails = loadedSails
-        globalThis.sounding = loadedSails.sounding
+        activateGlobalApp(loadedSails)
+        recordLifecycleReady('load', startedAt)
         resolve(loadedSails)
       })
     })
@@ -252,33 +569,42 @@ function createAppManager({
     return loadPromise
   }
 
-  async function lift() {
+  async function lift(options = {}) {
+    assertKnownAppManagerOptions('lift', options, ['reload'])
+    await prepareReload('lift', options)
+
     if (liftedApp) {
+      activateGlobalApp(liftedApp)
+      recordLifecycleReuse('lift')
       return liftedApp
     }
 
     if (liftPromise) {
+      recordLifecycleReuse('lift')
       return liftPromise
     }
 
     const Sails = resolveSailsConstructor()
     const sailsApp = new Sails()
     const nextLiftOptions = buildOptions('lift')
+    const startedAt = Date.now()
+    recordLifecycleStart('lift')
     outputFilter?.install()
 
     liftPromise = new Promise((resolve, reject) => {
       sailsApp.lift(nextLiftOptions, (error, liftedSails) => {
         if (error) {
           liftPromise = null
+          recordLifecycleError('lift', error)
           cleanupManagedArtifacts().catch(() => {})
-          outputFilter?.uninstall()
+          syncGlobalApp()
           reject(error)
           return
         }
 
         liftedApp = liftedSails
-        globalThis.sails = liftedSails
-        globalThis.sounding = liftedSails.sounding
+        activateGlobalApp(liftedSails)
+        recordLifecycleReady('lift', startedAt)
         resolve(liftedSails)
       })
     })
@@ -286,8 +612,35 @@ function createAppManager({
     return liftPromise
   }
 
+  function resolveRuntimeMode(options = {}) {
+    if (options.app !== undefined) {
+      if (options.app === 'load' || options.app === 'lift') {
+        return options.app
+      }
+
+      throw createSoundingError({
+        code: 'E_SOUNDING_APP_MODE_UNKNOWN',
+        name: 'SoundingAppLifecycleError',
+        message: `Sounding app lifecycle mode must be \`load\` or \`lift\`. Received \`${options.app}\`.`,
+        details: {
+          app: options.app,
+          allowed: ['load', 'lift'],
+        },
+      })
+    }
+
+    if (options.transport === 'http') {
+      return 'lift'
+    }
+
+    return 'load'
+  }
+
   async function runtime(options = {}) {
-    const app = options.http ? await lift() : await load()
+    assertKnownAppManagerOptions('runtime', options, ['app', 'transport', 'reload'])
+    const mode = resolveRuntimeMode(options)
+    const lifecycleOptions = { reload: options.reload }
+    const app = mode === 'lift' ? await lift(lifecycleOptions) : await load(lifecycleOptions)
     return app.sounding || app.hooks?.sounding
   }
 
@@ -299,18 +652,13 @@ function createAppManager({
     loadPromise = null
     liftPromise = null
 
-    await Promise.all(
-      apps.map(
-        (app) =>
-          new Promise((resolve) => {
-            app.lower(() => resolve())
-          })
-      )
-    )
+    await Promise.all(apps.map((app) => lowerApp(app)))
 
     delete globalThis.sails
     delete globalThis.sounding
     outputFilter?.uninstall()
+    recordLifecycleIdle('load')
+    recordLifecycleIdle('lift')
     await cleanupManagedArtifacts()
   }
 
@@ -320,10 +668,16 @@ function createAppManager({
     runtime,
     lower,
     resolveConfig,
+    get lifecycle() {
+      return getLifecycleSnapshot()
+    },
   }
 }
 
 module.exports = {
+  assertManagedDatastoreDependency,
+  buildManagedDatastoreOverrides,
   createAppManager,
+  defaultLoadSails,
   loadAppSoundingConfig,
 }