sounding 0.0.3 → 0.1.0

package/lib/create-visit-client.js

@@ -1,13 +1,30 @@
+const { createSoundingError } = require('./create-error')
+
 const DEFAULT_HEADERS = {
   'x-inertia': 'true',
   'x-requested-with': 'XMLHttpRequest',
   accept: 'text/html, application/xhtml+xml',
 }
 
+/** @typedef {import('./types').AnyRecord} AnyRecord */
+/** @typedef {import('./types').SoundingRequestClient} SoundingRequestClient */
+/** @typedef {import('./types').SoundingRequestOptions} SoundingRequestOptions */
+/** @typedef {import('./types').SoundingTransport} SoundingTransport */
+/** @typedef {import('./types').SoundingVisitClient} SoundingVisitClient */
+/** @typedef {import('./types').SoundingVisitOptions} SoundingVisitOptions */
+
+/**
+ * @param {string | string[]} value
+ * @returns {string}
+ */
 function joinHeaderValue(value) {
   return Array.isArray(value) ? value.join(',') : value
 }
 
+/**
+ * @param {SoundingVisitOptions} [options]
+ * @returns {AnyRecord}
+ */
 function buildVisitHeaders(options = {}) {
   const headers = {
     ...(options.headers || {}),
@@ -23,7 +40,13 @@ function buildVisitHeaders(options = {}) {
 
   if (options.only?.length) {
     if (!options.component) {
-      throw new Error('Sounding visit() requires `component` when using `only`.')
+      throw createSoundingError({
+        code: 'E_SOUNDING_VISIT_COMPONENT_REQUIRED',
+        message: 'Sounding visit() requires `component` when using `only`.',
+        details: {
+          partialReload: 'only',
+        },
+      })
     }
 
     headers['x-inertia-partial-component'] = options.component
@@ -32,7 +55,13 @@ function buildVisitHeaders(options = {}) {
 
   if (options.except?.length) {
     if (!options.component) {
-      throw new Error('Sounding visit() requires `component` when using `except`.')
+      throw createSoundingError({
+        code: 'E_SOUNDING_VISIT_COMPONENT_REQUIRED',
+        message: 'Sounding visit() requires `component` when using `except`.',
+        details: {
+          partialReload: 'except',
+        },
+      })
     }
 
     headers['x-inertia-partial-component'] = options.component
@@ -46,6 +75,10 @@ function buildVisitHeaders(options = {}) {
   return headers
 }
 
+/**
+ * @param {SoundingVisitOptions} [options]
+ * @returns {SoundingRequestOptions}
+ */
 function buildRequestOptions(options = {}) {
   const {
     component,
@@ -78,6 +111,10 @@ function buildRequestOptions(options = {}) {
   return output
 }
 
+/**
+ * @param {{ request: SoundingRequestClient }} input
+ * @returns {SoundingVisitClient}
+ */
 function createVisitClient({ request }) {
   const client = request.withHeaders(DEFAULT_HEADERS)
 
@@ -95,6 +132,7 @@ function createVisitClient({ request }) {
     client.delete(target, payload, buildRequestOptions(options))
   visit.del = visit.delete
   visit.using = (transport) => createVisitClient({ request: request.using(transport) })
+  visit.as = (actor) => createVisitClient({ request: request.as(actor) })
 
   Object.defineProperty(visit, 'transport', {
     enumerable: true,

package/lib/create-world-engine.js

@@ -2,10 +2,27 @@ const {
   isFactoryDefinition,
   isScenarioDefinition,
 } = require('./define-world')
-
+const { createSoundingError } = require('./create-error')
+
+/** @typedef {import('./types').AnyRecord} AnyRecord */
+/** @typedef {import('./types').SoundingBuilder} SoundingBuilder */
+/** @typedef {import('./types').SoundingFactoryDefinition} SoundingFactoryDefinition */
+/** @typedef {import('./types').SoundingFactoryRegistration} SoundingFactoryRegistration */
+/** @typedef {import('./types').SoundingSailsApp} SoundingSailsApp */
+/** @typedef {import('./types').SoundingScenarioDefinition} SoundingScenarioDefinition */
+/** @typedef {import('./types').SoundingWorldEngine} SoundingWorldEngine */
+
+/**
+ * @param {AnyRecord} base
+ * @param {AnyRecord | ((base: AnyRecord) => AnyRecord)} patch
+ * @returns {AnyRecord}
+ */
 function mergeValue(base, patch) {
   if (typeof patch === 'function') {
-    return patch(base)
+    return {
+      ...base,
+      ...(patch(base) || {}),
+    }
   }
 
   return {
@@ -14,6 +31,10 @@ function mergeValue(base, patch) {
   }
 }
 
+/**
+ * @param {{ sequence: Function }} input
+ * @returns {import('./types').SoundingFactoryHelpers['fake']}
+ */
 function createFakeHelpers({ sequence }) {
   return {
     person: {
@@ -37,6 +58,11 @@ function createFakeHelpers({ sequence }) {
   }
 }
 
+/**
+ * @param {(overrides: AnyRecord, options: { traits: string[] }) => any} executor
+ * @param {AnyRecord} [initialOverrides]
+ * @returns {SoundingBuilder}
+ */
 function createThenableBuilder(executor, initialOverrides = {}) {
   const state = {
     overrides: initialOverrides,
@@ -61,6 +87,14 @@ function createThenableBuilder(executor, initialOverrides = {}) {
     },
 
     with(overrides = {}) {
+      state.overrides = {
+        ...state.overrides,
+        ...overrides,
+      }
+      return builder
+    },
+
+    withOnly(overrides = {}) {
       state.overrides = overrides
       return builder
     },
@@ -85,6 +119,18 @@ function createThenableBuilder(executor, initialOverrides = {}) {
   return builder
 }
 
+/**
+ * @param {string[]} values
+ * @returns {string}
+ */
+function formatAvailable(values) {
+  return values.length ? values.join(', ') : 'none'
+}
+
+/**
+ * @param {{ sails?: SoundingSailsApp }} input
+ * @returns {SoundingWorldEngine}
+ */
 function createWorldEngine({ sails }) {
   const factories = new Map()
   const scenarios = new Map()
@@ -104,7 +150,15 @@ function createWorldEngine({ sails }) {
     const entry = factories.get(name)
 
     if (!entry) {
-      throw new Error(`Unknown Sounding factory: ${name}`)
+      const availableFactories = Array.from(factories.keys()).sort()
+      throw createSoundingError({
+        code: 'E_SOUNDING_WORLD_FACTORY_UNKNOWN',
+        message: `Unknown Sounding factory: ${name}. Available factories: ${formatAvailable(availableFactories)}.`,
+        details: {
+          factory: name,
+          availableFactories,
+        },
+      })
     }
 
     return entry
@@ -126,7 +180,16 @@ function createWorldEngine({ sails }) {
 
     for (const traitName of options.traits || []) {
       if (!entry.traits.has(traitName)) {
-        throw new Error(`Unknown Sounding trait \`${traitName}\` for factory \`${name}\``)
+        const availableTraits = Array.from(entry.traits.keys()).sort()
+        throw createSoundingError({
+          code: 'E_SOUNDING_WORLD_TRAIT_UNKNOWN',
+          message: `Unknown Sounding trait \`${traitName}\` for factory \`${name}\`. Available traits for \`${name}\`: ${formatAvailable(availableTraits)}.`,
+          details: {
+            factory: name,
+            trait: traitName,
+            availableTraits,
+          },
+        })
       }
 
       value = mergeValue(value, entry.traits.get(traitName))
@@ -150,6 +213,10 @@ function createWorldEngine({ sails }) {
     return value
   }
 
+  /**
+   * @param {any} entry
+   * @returns {SoundingFactoryRegistration}
+   */
   function registerFactoryDefinition(entry) {
     const nextEntry = {
       definition: entry.definition,
@@ -166,11 +233,20 @@ function createWorldEngine({ sails }) {
     }
   }
 
+  /**
+   * @param {any} entry
+   * @returns {SoundingScenarioDefinition}
+   */
   function registerScenarioDefinition(entry) {
     scenarios.set(entry.name, entry.definition)
     return entry
   }
 
+  /**
+   * @param {string | any} nameOrEntry
+   * @param {any} [definition]
+   * @returns {SoundingFactoryRegistration}
+   */
   function defineFactory(nameOrEntry, definition) {
     if (isFactoryDefinition(nameOrEntry)) {
       return registerFactoryDefinition(nameOrEntry)
@@ -185,6 +261,11 @@ function createWorldEngine({ sails }) {
     return registerFactoryDefinition(entry)
   }
 
+  /**
+   * @param {string | any} nameOrEntry
+   * @param {any} [definition]
+   * @returns {SoundingScenarioDefinition}
+   */
   function defineScenario(nameOrEntry, definition) {
     if (isScenarioDefinition(nameOrEntry)) {
       return registerScenarioDefinition(nameOrEntry)
@@ -200,7 +281,15 @@ function createWorldEngine({ sails }) {
     const definition = scenarios.get(name)
 
     if (!definition) {
-      throw new Error(`Unknown Sounding scenario: ${name}`)
+      const availableScenarios = Array.from(scenarios.keys()).sort()
+      throw createSoundingError({
+        code: 'E_SOUNDING_WORLD_SCENARIO_UNKNOWN',
+        message: `Unknown Sounding scenario: ${name}. Available scenarios: ${formatAvailable(availableScenarios)}.`,
+        details: {
+          scenario: name,
+          availableScenarios,
+        },
+      })
     }
 
     currentWorld = await definition({
@@ -237,7 +326,14 @@ function createWorldEngine({ sails }) {
     },
 
     create(name, overrides = {}, options = {}) {
-      return createOne(name, overrides, options)
+      return createThenableBuilder(
+        (nextOverrides, nextOptions) =>
+          createOne(name, nextOverrides, {
+            ...options,
+            traits: [...(options.traits || []), ...(nextOptions.traits || [])],
+          }),
+        overrides
+      )
     },
 
     async createMany(name, count, overrides = {}, options = {}) {
@@ -260,7 +356,10 @@ function createWorldEngine({ sails }) {
         return defineScenario(definition)
       }
 
-      throw new Error('Sounding could not register an unknown world definition.')
+      throw createSoundingError({
+        code: 'E_SOUNDING_WORLD_DEFINITION_UNKNOWN',
+        message: 'Sounding could not register an unknown world definition.',
+      })
     },
 
     get current() {

package/lib/create-world-loader.js

@@ -8,17 +8,29 @@ const {
   isFactoryDefinition,
   isScenarioDefinition,
 } = require('./define-world')
+const { createSoundingError } = require('./create-error')
+
+/** @typedef {import('./types').AnyRecord} AnyRecord */
+/** @typedef {import('./types').SoundingConfig} SoundingConfig */
+/** @typedef {import('./types').SoundingSailsApp} SoundingSailsApp */
+/** @typedef {import('./types').SoundingWorldEngine} SoundingWorldEngine */
 
 const WORLD_EXTENSIONS = new Set(['.js', '.cjs', '.mjs'])
 
-function listDefinitionFiles(directory) {
+/**
+ * @param {string} directory
+ * @param {{ directories?: string[] }} [options]
+ * @returns {string[]}
+ */
+function listDefinitionFiles(directory, options = {}) {
   const output = []
+  options.directories?.push(directory)
 
   for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
     const nextPath = path.join(directory, entry.name)
 
     if (entry.isDirectory()) {
-      output.push(...listDefinitionFiles(nextPath))
+      output.push(...listDefinitionFiles(nextPath, options))
       continue
     }
 
@@ -30,6 +42,91 @@ function listDefinitionFiles(directory) {
   return output.sort()
 }
 
+/**
+ * @param {string} entryPath
+ * @returns {{ path: string, mtimeMs: number, size: number }}
+ */
+function getFileSignature(entryPath) {
+  const stat = fs.statSync(entryPath)
+
+  return {
+    path: entryPath,
+    mtimeMs: stat.mtimeMs,
+    size: stat.size,
+  }
+}
+
+/**
+ * @returns {{
+ *   directories: Map<string, { signatures: Array<{ path: string, mtimeMs: number, size: number }>, files: string[] }>,
+ *   modules: Map<string, { signature: { path: string, mtimeMs: number, size: number }, value: any }>,
+ *   stats: { directoryScans: number, moduleLoads: number },
+ *   clear(): void,
+ * }}
+ */
+function createWorldLoaderCache() {
+  const stats = {
+    directoryScans: 0,
+    moduleLoads: 0,
+  }
+
+  return {
+    directories: new Map(),
+    modules: new Map(),
+    stats,
+    clear() {
+      this.directories.clear()
+      this.modules.clear()
+      stats.directoryScans = 0
+      stats.moduleLoads = 0
+    },
+  }
+}
+
+/**
+ * @param {{ path: string, mtimeMs: number, size: number }} expected
+ * @returns {boolean}
+ */
+function signatureMatches(expected) {
+  if (!fs.existsSync(expected.path)) {
+    return false
+  }
+
+  const actual = getFileSignature(expected.path)
+  return actual.mtimeMs === expected.mtimeMs && actual.size === expected.size
+}
+
+/**
+ * @param {string} directory
+ * @param {ReturnType<typeof createWorldLoaderCache> | undefined} cache
+ * @returns {string[]}
+ */
+function getDefinitionFiles(directory, cache) {
+  if (!cache) {
+    return listDefinitionFiles(directory)
+  }
+
+  const cached = cache.directories.get(directory)
+
+  if (cached && cached.signatures.every(signatureMatches)) {
+    return cached.files
+  }
+
+  const directories = []
+  const files = listDefinitionFiles(directory, { directories })
+  cache.stats.directoryScans += 1
+  cache.directories.set(directory, {
+    signatures: directories.map(getFileSignature),
+    files,
+  })
+
+  return files
+}
+
+/**
+ * @param {string} filePath
+ * @returns {Promise<any>}
+ */
 async function loadModule(filePath) {
   try {
     delete require.cache[require.resolve(filePath)]
@@ -43,6 +140,42 @@ async function loadModule(filePath) {
   }
 }
 
+/**
+ * @param {string} filePath
+ * @param {ReturnType<typeof createWorldLoaderCache> | undefined} cache
+ * @returns {Promise<any>}
+ */
+async function loadCachedModule(filePath, cache) {
+  if (!cache) {
+    return loadModule(filePath)
+  }
+
+  const signature = getFileSignature(filePath)
+  const cached = cache.modules.get(filePath)
+
+  if (
+    cached &&
+    cached.signature.mtimeMs === signature.mtimeMs &&
+    cached.signature.size === signature.size
+  ) {
+    return cached.value
+  }
+
+  const value = await loadModule(filePath)
+  cache.stats.moduleLoads += 1
+  cache.modules.set(filePath, {
+    signature,
+    value,
+  })
+  return value
+}
+
+/**
+ * @param {any} value
+ * @param {AnyRecord} api
+ * @param {string} source
+ * @returns {Promise<void>}
+ */
 async function registerExport(value, api, source) {
   const entry = value?.default ?? value
 
@@ -84,12 +217,20 @@ async function registerExport(value, api, source) {
     return
   }
 
-  throw new Error(
-    `Sounding could not understand the world definition exported from ${source}.`
-  )
+  throw createSoundingError({
+    code: 'E_SOUNDING_WORLD_DEFINITION_UNKNOWN',
+    message: `Sounding could not understand the world definition exported from ${source}.`,
+    details: {
+      source,
+    },
+  })
 }
 
-async function loadWorldFiles({ world, appPath, config, sails }) {
+/**
+ * @param {{ world: SoundingWorldEngine, appPath: string, config: SoundingConfig, sails?: SoundingSailsApp, cache?: ReturnType<typeof createWorldLoaderCache> }} input
+ * @returns {Promise<string[]>}
+ */
+async function loadWorldFiles({ world, appPath, config, sails, cache }) {
   const directories = [config.world?.factories, config.world?.scenarios]
     .filter(Boolean)
     .map((relativePath) => path.resolve(appPath, relativePath))
@@ -111,8 +252,8 @@ async function loadWorldFiles({ world, appPath, config, sails }) {
       continue
     }
 
-    for (const filePath of listDefinitionFiles(directory)) {
-      const loaded = await loadModule(filePath)
+    for (const filePath of getDefinitionFiles(directory, cache)) {
+      const loaded = await loadCachedModule(filePath, cache)
       await registerExport(loaded, api, filePath)
       loadedFiles.push(filePath)
     }
@@ -122,6 +263,7 @@ async function loadWorldFiles({ world, appPath, config, sails }) {
 }
 
 module.exports = {
+  createWorldLoaderCache,
   loadWorldFiles,
   listDefinitionFiles,
   loadModule,

package/lib/default-config.js

@@ -1,3 +1,6 @@
+/** @typedef {import('./types').SoundingConfig} SoundingConfig */
+
+/** @type {Readonly<SoundingConfig>} */
 const DEFAULT_CONFIG = Object.freeze({
   // Sails environments where the Sounding hook should boot.
   // Keep this test-only by default so non-test processes stay dark.
@@ -27,13 +30,29 @@ const DEFAULT_CONFIG = Object.freeze({
     launchOptions: {
       headless: true,
     },
+    artifacts: {
+      outputDir: '.tmp/sounding/artifacts',
+      screenshot: true,
+      trace: false,
+      video: false,
+      currentUrl: true,
+    },
   },
   mail: {
     capture: true,
+    layout: 'mail',
   },
   request: {
     transport: 'virtual',
   },
+  sockets: {
+    enabled: true,
+    timeout: 1000,
+    transports: ['websocket'],
+    path: '/socket.io',
+    headers: {},
+    initialConnectionHeaders: {},
+  },
   auth: {
     defaultActor: 'guest',
     modelIdentity: null,
@@ -54,6 +73,10 @@ const DEFAULT_CONFIG = Object.freeze({
   },
 })
 
+/**
+ * @param {any} value
+ * @returns {any}
+ */
 function cloneValue(value) {
   if (Array.isArray(value)) {
     return value.map(cloneValue)
@@ -68,6 +91,9 @@ function cloneValue(value) {
   return value
 }
 
+/**
+ * @returns {SoundingConfig}
+ */
 function getDefaultConfig() {
   return cloneValue(DEFAULT_CONFIG)
 }

package/lib/define-world.js

@@ -1,6 +1,16 @@
+/** @typedef {import('./types').SoundingFactoryDefinition} SoundingFactoryDefinition */
+/** @typedef {import('./types').SoundingScenarioDefinition} SoundingScenarioDefinition */
+
+/**
+ * Define a reusable record factory for Sounding worlds.
+ *
+ * @param {string} name
+ * @param {SoundingFactoryDefinition['definition']} definition
+ * @returns {SoundingFactoryDefinition}
+ */
 function defineFactory(name, definition) {
   const entry = {
-    __soundingType: 'factory',
+    __soundingType: /** @type {'factory'} */ ('factory'),
     name,
     definition,
     traits: [],
@@ -13,18 +23,33 @@ function defineFactory(name, definition) {
   return entry
 }
 
+/**
+ * Define a named scenario that can seed a trial with product-language data.
+ *
+ * @param {string} name
+ * @param {SoundingScenarioDefinition['definition']} definition
+ * @returns {SoundingScenarioDefinition}
+ */
 function defineScenario(name, definition) {
   return {
-    __soundingType: 'scenario',
+    __soundingType: /** @type {'scenario'} */ ('scenario'),
     name,
     definition,
   }
 }
 
+/**
+ * @param {any} value
+ * @returns {value is SoundingFactoryDefinition}
+ */
 function isFactoryDefinition(value) {
   return value?.__soundingType === 'factory'
 }
 
+/**
+ * @param {any} value
+ * @returns {value is SoundingScenarioDefinition}
+ */
 function isScenarioDefinition(value) {
   return value?.__soundingType === 'scenario'
 }