sounding 0.0.4 → 0.1.0

package/lib/create-runtime.js

@@ -3,39 +3,197 @@ const path = require('node:path')
 const { createMailbox } = require('./create-mailbox')
 const { createMailCapture } = require('./create-mail-capture')
 const { createWorldEngine } = require('./create-world-engine')
-const { loadWorldFiles } = require('./create-world-loader')
+const { createWorldLoaderCache, loadWorldFiles } = require('./create-world-loader')
 const { createHelperRunner } = require('./create-helper-runner')
 const { createRequestClient } = require('./create-request-client')
 const { createVisitClient } = require('./create-visit-client')
 const { createBrowserManager } = require('./create-browser-manager')
 const { createAuthHelpers } = require('./create-auth-helpers')
+const { createSocketManager } = require('./create-socket-manager')
 const { getDefaultConfig } = require('./default-config')
 const { mergeConfig } = require('./merge-config')
 const { normalizeUserConfig } = require('./normalize-config')
 const { resolveDatastore } = require('./resolve-datastore')
+const { createSoundingError } = require('./create-error')
+const { validateConfig } = require('./validate-config')
 
+/** @typedef {import('./types').SoundingBootResult} SoundingBootResult */
+/** @typedef {import('./types').SoundingConfig} SoundingConfig */
+/** @typedef {import('./types').SoundingRuntime} SoundingRuntime */
+/** @typedef {import('./types').SoundingSailsApp} SoundingSailsApp */
+
+/**
+ * @param {SoundingSailsApp} sails
+ * @returns {SoundingConfig}
+ */
 function resolveConfig(sails) {
-  return mergeConfig(getDefaultConfig(), normalizeUserConfig(sails.config?.sounding || {}))
+  return resolveConfigValue(sails.config?.sounding || {})
+}
+
+/**
+ * @param {any} value
+ * @returns {string}
+ */
+function getConfigSignature(value) {
+  try {
+    return JSON.stringify(value || {})
+  } catch (_error) {
+    return String(Date.now())
+  }
+}
+
+/**
+ * @param {any} userConfig
+ * @returns {SoundingConfig}
+ */
+function resolveConfigValue(userConfig) {
+  return validateConfig(
+    /** @type {SoundingConfig} */ (
+      mergeConfig(getDefaultConfig(), normalizeUserConfig(userConfig || {}))
+    )
+  )
+}
+
+/**
+ * @param {SoundingSailsApp} sails
+ * @returns {(() => SoundingConfig) & { stats: { resolutions: number }, invalidate(): void }}
+ */
+function createConfigResolver(sails) {
+  /** @type {any} */
+  let cachedInput = null
+  /** @type {string | null} */
+  let cachedSignature = null
+  /** @type {SoundingConfig | null} */
+  let cachedConfig = null
+  const stats = {
+    resolutions: 0,
+  }
+
+  const resolver = /** @type {(() => SoundingConfig) & { stats: { resolutions: number }, invalidate(): void }} */ (
+    function resolveCachedConfig() {
+      const input = sails.config?.sounding || {}
+      const signature = getConfigSignature(input)
+
+      if (cachedConfig && cachedInput === input && cachedSignature === signature) {
+        return cachedConfig
+      }
+
+      cachedInput = input
+      cachedSignature = signature
+      cachedConfig = resolveConfigValue(input)
+      stats.resolutions += 1
+      return cachedConfig
+    }
+  )
+
+  resolver.stats = stats
+  resolver.invalidate = function invalidateConfigCache() {
+    cachedInput = null
+    cachedSignature = null
+    cachedConfig = null
+    stats.resolutions = 0
+  }
+
+  return resolver
 }
 
+/**
+ * @param {SoundingSailsApp} sails
+ * @param {SoundingConfig} config
+ * @returns {string}
+ */
 function resolveAppPath(sails, config) {
   const basePath = sails?.config?.appPath || process.cwd()
   return path.resolve(basePath, config.app?.path || '.')
 }
 
+/**
+ * @param {unknown} error
+ * @returns {string}
+ */
+function formatCleanupError(error) {
+  if (error instanceof Error) {
+    return error.message
+  }
+
+  return String(error)
+}
+
+/**
+ * @param {{ resource: string, cleanup: () => void | Promise<void> }[]} steps
+ * @returns {Promise<void>}
+ */
+async function runCleanupSteps(steps) {
+  const failures = []
+
+  for (const step of steps) {
+    try {
+      await step.cleanup()
+    } catch (error) {
+      failures.push({
+        resource: step.resource,
+        error,
+      })
+    }
+  }
+
+  if (failures.length === 0) {
+    return
+  }
+
+  const resources = failures.map((failure) => failure.resource).join(', ')
+  const errors = failures.map(
+    (failure) =>
+      createSoundingError({
+        code: 'E_SOUNDING_CLEANUP_RESOURCE_FAILED',
+        message: `${failure.resource}: ${formatCleanupError(failure.error)}`,
+        details: {
+          resource: failure.resource,
+        },
+        cause: failure.error,
+      })
+  )
+
+  const error = /** @type {AggregateError & { code: string, resources: string[], details: { resources: string[] } }} */ (
+    new AggregateError(errors, `Sounding cleanup failed for ${resources}.`)
+  )
+  error.name = 'SoundingCleanupError'
+  error.code = 'E_SOUNDING_CLEANUP_FAILED'
+  error.resources = failures.map((failure) => failure.resource)
+  error.details = {
+    resources: error.resources,
+  }
+
+  throw error
+}
+
+/**
+ * Create a Sounding runtime bound to a loaded Sails app.
+ *
+ * @param {SoundingSailsApp} sails
+ * @returns {SoundingRuntime}
+ */
 function createRuntime(sails) {
   const mailbox = createMailbox()
   const world = createWorldEngine({ sails })
   const helpers = createHelperRunner({ sails })
+  const getConfig = createConfigResolver(sails)
+  const worldLoaderCache = createWorldLoaderCache()
   const request = createRequestClient({
     sails,
-    getConfig: () => resolveConfig(sails),
+    getConfig,
+    world,
   })
   const visit = createVisitClient({ request })
+  const sockets = createSocketManager({
+    sails,
+    getConfig,
+    world,
+  })
   const browser = createBrowserManager({
     sails,
-    getConfig: () => resolveConfig(sails),
-    appPathResolver: () => resolveAppPath(sails, resolveConfig(sails)),
+    getConfig,
+    appPathResolver: () => resolveAppPath(sails, getConfig()),
   })
   const auth = createAuthHelpers({
     sails,
@@ -46,14 +204,14 @@ function createRuntime(sails) {
   const mailCapture = createMailCapture({
     sails,
     mailbox,
-    getConfig: () => resolveConfig(sails),
+    getConfig,
   })
   let bootState = null
   let datastoreState = null
 
   return {
     get config() {
-      return resolveConfig(sails)
+      return getConfig()
     },
 
     get appPath() {
@@ -72,11 +230,6 @@ function createRuntime(sails) {
       return helpers
     },
 
-    // Temporary compatibility alias while the DX settles.
-    get helper() {
-      return helpers
-    },
-
     get request() {
       return request
     },
@@ -85,6 +238,10 @@ function createRuntime(sails) {
       return visit
     },
 
+    get sockets() {
+      return sockets
+    },
+
     get browser() {
       return browser
     },
@@ -96,7 +253,7 @@ function createRuntime(sails) {
     configure() {
       datastoreState = resolveDatastore({
         sails,
-        soundingConfig: this.config,
+        soundingConfig: getConfig(),
       })
 
       return datastoreState
@@ -106,27 +263,34 @@ function createRuntime(sails) {
       return datastoreState
     },
 
+    /**
+     * @param {{ mode?: string }} [options]
+     * @returns {Promise<SoundingBootResult>}
+     */
     async boot(options = {}) {
       if (!datastoreState) {
         datastoreState = this.configure()
       }
 
+      const config = getConfig()
+      const appPath = resolveAppPath(sails, config)
       world.reset({ preserveSequences: true })
       const loadedWorldFiles = await loadWorldFiles({
         world,
-        appPath: this.appPath,
-        config: this.config,
+        appPath,
+        config,
         sails,
+        cache: worldLoaderCache,
       })
       const captureInstalled = mailCapture.install()
 
       bootState = {
         bootedAt: new Date().toISOString(),
         mode: options.mode || 'unit',
-        config: this.config,
+        config,
         datastore: datastoreState,
         mail: {
-          captureEnabled: this.config.mail?.capture !== false,
+          captureEnabled: config.mail?.capture !== false,
           captureInstalled,
         },
         world: {
@@ -142,6 +306,7 @@ function createRuntime(sails) {
         world,
         request,
         visit,
+        sockets,
         browser,
         auth,
         login: auth.login,
@@ -151,20 +316,56 @@ function createRuntime(sails) {
     async lower() {
       bootState = null
       datastoreState = null
-      await browser.close()
-      mailCapture.uninstall()
-      mailbox.clear()
-      world.reset({ preserveSequences: true })
+
+      await runCleanupSteps([
+        {
+          resource: 'sockets',
+          cleanup: () => sockets.closeAll(),
+        },
+        {
+          resource: 'request session',
+          cleanup: () => request.clearSession(),
+        },
+        {
+          resource: 'browser',
+          cleanup: () => browser.close(),
+        },
+        {
+          resource: 'mail capture',
+          cleanup: () => mailCapture.uninstall(),
+        },
+        {
+          resource: 'mailbox',
+          cleanup: () => mailbox.clear(),
+        },
+        {
+          resource: 'world',
+          cleanup: () => world.reset({ preserveSequences: true }),
+        },
+      ])
     },
 
     get state() {
       return bootState
     },
+
+    get cacheStats() {
+      return {
+        config: { ...getConfig.stats },
+        worldLoader: { ...worldLoaderCache.stats },
+      }
+    },
+
+    invalidateCaches() {
+      getConfig.invalidate()
+      worldLoaderCache.clear()
+    },
   }
 }
 
 module.exports = {
   createRuntime,
+  createConfigResolver,
   resolveConfig,
   resolveAppPath,
 }