sounding 0.0.4 → 0.1.0

package/lib/init-project.js

@@ -0,0 +1,403 @@
+const fs = require('node:fs')
+const path = require('node:path')
+
+const packageJson = require('../package.json')
+
+const TEST_COMMAND = 'sounding test'
+const SOUNDING_VERSION = `^${packageJson.version}`
+const SQLITE_VERSION = packageJson.devDependencies?.['sails-sqlite'] || '^0.2.6'
+
+/**
+ * @typedef {{
+ *   type: 'created' | 'updated' | 'skipped',
+ *   path?: string,
+ *   message: string,
+ * }} InitProjectAction
+ */
+
+/**
+ * @typedef {{
+ *   appPath?: string,
+ *   config?: boolean,
+ * }} InitProjectOptions
+ */
+
+/**
+ * @typedef {{
+ *   appPath: string,
+ *   auth: {
+ *     identity: string,
+ *     modelName: string,
+ *     collection: string,
+ *     scenario: string,
+ *     detected: boolean,
+ *   },
+ *   actions: InitProjectAction[],
+ * }} InitProjectResult
+ */
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function titleCase(value) {
+  return `${value[0].toUpperCase()}${value.slice(1)}`
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function pluralize(value) {
+  if (value.endsWith('s')) {
+    return value
+  }
+
+  return `${value}s`
+}
+
+/**
+ * @param {string} appPath
+ * @returns {InitProjectResult['auth']}
+ */
+function detectAuthConvention(appPath) {
+  const candidates = ['user', 'creator']
+
+  for (const identity of candidates) {
+    const modelName = titleCase(identity)
+    const modelPaths = [
+      path.join(appPath, 'api', 'models', `${modelName}.js`),
+      path.join(appPath, 'api', 'models', `${identity}.js`),
+    ]
+
+    if (modelPaths.some((modelPath) => fs.existsSync(modelPath))) {
+      return {
+        identity,
+        modelName,
+        collection: pluralize(identity),
+        scenario: `signed-in-${identity}`,
+        detected: true,
+      }
+    }
+  }
+
+  return {
+    identity: 'user',
+    modelName: 'User',
+    collection: 'users',
+    scenario: 'signed-in-user',
+    detected: false,
+  }
+}
+
+/**
+ * @param {string} filePath
+ * @returns {any}
+ */
+function readJsonFile(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'))
+}
+
+/**
+ * @param {string} filePath
+ * @param {any} value
+ * @returns {void}
+ */
+function writeJsonFile(filePath, value) {
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`)
+}
+
+/**
+ * @param {string} appPath
+ * @param {string} targetPath
+ * @returns {string}
+ */
+function formatPath(appPath, targetPath) {
+  return path.relative(appPath, targetPath) || path.basename(targetPath)
+}
+
+/**
+ * @param {InitProjectAction[]} actions
+ * @param {string} appPath
+ * @param {string} directory
+ * @returns {void}
+ */
+function ensureDirectory(actions, appPath, directory) {
+  if (fs.existsSync(directory)) {
+    actions.push({
+      type: 'skipped',
+      path: directory,
+      message: `Kept existing ${formatPath(appPath, directory)}`,
+    })
+    return
+  }
+
+  fs.mkdirSync(directory, { recursive: true })
+  actions.push({
+    type: 'created',
+    path: directory,
+    message: `Created ${formatPath(appPath, directory)}`,
+  })
+}
+
+/**
+ * @param {InitProjectAction[]} actions
+ * @param {string} appPath
+ * @param {string} filePath
+ * @param {string} contents
+ * @returns {void}
+ */
+function writeFileIfMissing(actions, appPath, filePath, contents) {
+  if (fs.existsSync(filePath)) {
+    actions.push({
+      type: 'skipped',
+      path: filePath,
+      message: `Kept existing ${formatPath(appPath, filePath)}`,
+    })
+    return
+  }
+
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, contents)
+  actions.push({
+    type: 'created',
+    path: filePath,
+    message: `Created ${formatPath(appPath, filePath)}`,
+  })
+}
+
+/**
+ * @param {any} pkg
+ * @param {string} name
+ * @returns {boolean}
+ */
+function hasDependency(pkg, name) {
+  return Boolean(pkg.dependencies?.[name] || pkg.devDependencies?.[name])
+}
+
+/**
+ * @param {any} pkg
+ * @param {string} name
+ * @param {string} version
+ * @returns {boolean}
+ */
+function ensureDevDependency(pkg, name, version) {
+  if (hasDependency(pkg, name)) {
+    return false
+  }
+
+  pkg.devDependencies ||= {}
+  pkg.devDependencies[name] = version
+  return true
+}
+
+/**
+ * @param {InitProjectAction[]} actions
+ * @param {string} appPath
+ * @returns {void}
+ */
+function updatePackageJson(actions, appPath) {
+  const packagePath = path.join(appPath, 'package.json')
+  const packageExisted = fs.existsSync(packagePath)
+  const pkg = packageExisted ? readJsonFile(packagePath) : {}
+  let changed = false
+  const details = []
+
+  pkg.scripts ||= {}
+
+  if (!pkg.scripts.test) {
+    pkg.scripts.test = TEST_COMMAND
+    changed = true
+    details.push('added `npm test`')
+  } else if (pkg.scripts.test !== TEST_COMMAND && !pkg.scripts['test:sounding']) {
+    pkg.scripts['test:sounding'] = TEST_COMMAND
+    changed = true
+    details.push('added `npm run test:sounding`')
+  }
+
+  if (ensureDevDependency(pkg, 'sounding', SOUNDING_VERSION)) {
+    changed = true
+    details.push('added `sounding` devDependency')
+  }
+
+  if (ensureDevDependency(pkg, 'sails-sqlite', SQLITE_VERSION)) {
+    changed = true
+    details.push('added `sails-sqlite` devDependency')
+  }
+
+  if (!changed) {
+    actions.push({
+      type: 'skipped',
+      path: packagePath,
+      message: 'Kept existing package.json Sounding setup',
+    })
+    return
+  }
+
+  writeJsonFile(packagePath, pkg)
+  actions.push({
+    type: packageExisted ? 'updated' : 'created',
+    path: packagePath,
+    message: `${packageExisted ? 'Updated' : 'Created'} package.json (${details.join(', ')})`,
+  })
+}
+
+/**
+ * @param {InitProjectResult['auth']} auth
+ * @returns {string}
+ */
+function buildFactoryTemplate(auth) {
+  return `module.exports = ({ defineFactory }) =>
+  defineFactory('${auth.identity}', ({ sequence }) => ({
+    email: sequence('${auth.identity}-email', (next) => \`${auth.identity}-\${next}@example.com\`),
+    fullName: 'Test ${auth.modelName}'
+  }))
+`
+}
+
+/**
+ * @param {InitProjectResult['auth']} auth
+ * @returns {string}
+ */
+function buildScenarioTemplate(auth) {
+  return `module.exports = ({ defineScenario }) =>
+  defineScenario('${auth.scenario}', async ({ create }) => {
+    const member = await create('${auth.identity}')
+
+    return {
+      ${auth.collection}: {
+        member
+      }
+    }
+  })
+`
+}
+
+/**
+ * @param {InitProjectResult['auth']} auth
+ * @returns {string}
+ */
+function buildExamplesTemplate(auth) {
+  return `const { test } = require('sounding')
+
+test('Sounding boots this Sails app', async ({ sails, expect }) => {
+  expect(sails.config.environment).toBe('test')
+})
+
+test('virtual request example reaches Sails', async ({ get, expect }) => {
+  const response = await get('/')
+
+  expect(response.status).toBeDefined()
+})
+
+test('helper trial example has access to Sails helpers', async ({ sails, expect }) => {
+  expect(sails.helpers).toBeDefined()
+})
+
+test.skip('authenticated request example', { world: '${auth.scenario}' }, async ({ request, world, expect }) => {
+  const response = await request.as('member').get('/account')
+
+  expect(response).toHaveStatus(200)
+  expect(response).toHaveSession('${auth.identity}Id', world.current.${auth.collection}.member.id)
+})
+
+test.skip('Inertia page contract example', async ({ visit, expect }) => {
+  const page = await visit('/dashboard')
+
+  expect(page).toBeInertiaPage('dashboard/index')
+  expect(page).toHaveNoInertiaErrors()
+})
+
+test.skip('captured mail example', async ({ sails, mailbox, expect }) => {
+  await sails.helpers.mail.send.with({
+    to: 'reader@example.com',
+    subject: 'Welcome',
+    template: 'welcome'
+  })
+
+  expect(mailbox).toHaveSentMail({ to: 'reader@example.com' })
+})
+
+test.skip('browser journey example', { browser: true }, async ({ page, expect }) => {
+  await page.goto('/')
+
+  await expect(page).toBeDefined()
+})
+`
+}
+
+/**
+ * @returns {string}
+ */
+function buildConfigTemplate() {
+  return `module.exports.sounding = {
+  // Defaults are enough for most apps. Keep app-specific overrides here.
+  environments: ['test']
+}
+`
+}
+
+/**
+ * @param {InitProjectOptions} [options]
+ * @returns {InitProjectResult}
+ */
+function initProject(options = {}) {
+  const appPath = path.resolve(options.appPath || process.cwd())
+  /** @type {InitProjectAction[]} */
+  const actions = []
+  const auth = detectAuthConvention(appPath)
+
+  updatePackageJson(actions, appPath)
+
+  const testsPath = path.join(appPath, 'tests')
+  const factoriesPath = path.join(testsPath, 'factories')
+  const scenariosPath = path.join(testsPath, 'scenarios')
+  const examplesPath = path.join(testsPath, 'sounding')
+
+  ensureDirectory(actions, appPath, testsPath)
+  ensureDirectory(actions, appPath, factoriesPath)
+  ensureDirectory(actions, appPath, scenariosPath)
+  ensureDirectory(actions, appPath, examplesPath)
+
+  writeFileIfMissing(
+    actions,
+    appPath,
+    path.join(factoriesPath, `${auth.identity}.js`),
+    buildFactoryTemplate(auth)
+  )
+  writeFileIfMissing(
+    actions,
+    appPath,
+    path.join(scenariosPath, `${auth.scenario}.js`),
+    buildScenarioTemplate(auth)
+  )
+  writeFileIfMissing(
+    actions,
+    appPath,
+    path.join(examplesPath, 'examples.test.js'),
+    buildExamplesTemplate(auth)
+  )
+
+  const configPath = path.join(appPath, 'config', 'sounding.js')
+  if (options.config) {
+    writeFileIfMissing(actions, appPath, configPath, buildConfigTemplate())
+  } else {
+    actions.push({
+      type: 'skipped',
+      path: configPath,
+      message: 'Skipped config/sounding.js because Sounding defaults are enough',
+    })
+  }
+
+  return {
+    appPath,
+    auth,
+    actions,
+  }
+}
+
+module.exports = {
+  TEST_COMMAND,
+  detectAuthConvention,
+  initProject,
+}

package/lib/merge-config.js

@@ -1,7 +1,18 @@
+/** @typedef {import('./types').AnyRecord} AnyRecord */
+
+/**
+ * @param {any} value
+ * @returns {value is AnyRecord}
+ */
 function isPlainObject(value) {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
 }
 
+/**
+ * @param {AnyRecord} base
+ * @param {AnyRecord} override
+ * @returns {AnyRecord}
+ */
 function mergeConfig(base, override) {
   const output = { ...base }
 

package/lib/normalize-config.js

@@ -1,7 +1,18 @@
+/** @typedef {import('./types').AnyRecord} AnyRecord */
+/** @typedef {import('./types').SoundingUserConfig} SoundingUserConfig */
+
+/**
+ * @param {any} value
+ * @returns {value is AnyRecord}
+ */
 function isPlainObject(value) {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
 }
 
+/**
+ * @param {any} datastore
+ * @returns {any}
+ */
 function normalizeDatastore(datastore) {
   if (typeof datastore === 'string') {
     return {
@@ -13,27 +24,13 @@ function normalizeDatastore(datastore) {
     return datastore
   }
 
-  const normalized = { ...datastore }
-  const legacyManaged = isPlainObject(normalized.managed) ? normalized.managed : {}
-
-  if (normalized.adapter == null && legacyManaged.adapter != null) {
-    normalized.adapter = legacyManaged.adapter
-  }
-
-  if (normalized.root == null) {
-    normalized.root = legacyManaged.root ?? legacyManaged.directory
-  }
-
-  if (normalized.isolation == null && legacyManaged.isolation != null) {
-    normalized.isolation = legacyManaged.isolation
-  }
-
-  delete normalized.managed
-  delete normalized.directory
-
-  return normalized
+  return { ...datastore }
 }
 
+/**
+ * @param {any} [config]
+ * @returns {SoundingUserConfig}
+ */
 function normalizeUserConfig(config = {}) {
   if (!isPlainObject(config)) {
     return {}

package/lib/resolve-auth-config.js

@@ -1,7 +1,18 @@
+/** @typedef {import('./types').AnyRecord} AnyRecord */
+/** @typedef {import('./types').SoundingSailsApp} SoundingSailsApp */
+
+/**
+ * @param {any} value
+ * @returns {value is AnyRecord}
+ */
 function isPlainObject(value) {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
 }
 
+/**
+ * @param {any} value
+ * @returns {string | null}
+ */
 function normalizeIdentity(value) {
   if (typeof value !== 'string') {
     return null
@@ -11,6 +22,10 @@ function normalizeIdentity(value) {
   return normalized || null
 }
 
+/**
+ * @param {string | null} value
+ * @returns {string | null}
+ */
 function titleCase(value) {
   if (!value) {
     return value
@@ -19,10 +34,19 @@ function titleCase(value) {
   return `${value[0].toUpperCase()}${value.slice(1)}`
 }
 
+/**
+ * @param {{ sails?: SoundingSailsApp, getConfig?: () => AnyRecord }} [input]
+ * @returns {AnyRecord}
+ */
 function resolveSoundingConfig({ sails, getConfig } = {}) {
   return (typeof getConfig === 'function' ? getConfig() : null) || sails?.config?.sounding || {}
 }
 
+/**
+ * @param {SoundingSailsApp} sails
+ * @param {string | null} identity
+ * @returns {AnyRecord | null}
+ */
 function getModelByIdentity(sails, identity) {
   const normalizedIdentity = normalizeIdentity(identity)
 
@@ -33,6 +57,10 @@ function getModelByIdentity(sails, identity) {
   return sails?.models?.[normalizedIdentity] || sails?.models?.[titleCase(normalizedIdentity)] || null
 }
 
+/**
+ * @param {SoundingSailsApp} sails
+ * @returns {string}
+ */
 function detectModelIdentity(sails) {
   for (const candidate of ['user', 'creator']) {
     if (getModelByIdentity(sails, candidate)) {
@@ -43,6 +71,10 @@ function detectModelIdentity(sails) {
   return 'user'
 }
 
+/**
+ * @param {AnyRecord} [authConfig]
+ * @returns {AnyRecord}
+ */
 function resolvePasswordConfig(authConfig = {}) {
   const passwordConfig = isPlainObject(authConfig.password) ? authConfig.password : {}
   const formConfig = isPlainObject(passwordConfig.form) ? passwordConfig.form : {}
@@ -71,6 +103,10 @@ function resolvePasswordConfig(authConfig = {}) {
   }
 }
 
+/**
+ * @param {{ sails?: SoundingSailsApp, getConfig?: () => AnyRecord }} [input]
+ * @returns {AnyRecord}
+ */
 function resolveAuthConfig({ sails, getConfig } = {}) {
   const soundingConfig = resolveSoundingConfig({ sails, getConfig })
   const authConfig = isPlainObject(soundingConfig.auth) ? soundingConfig.auth : {}

package/lib/resolve-datastore.js

@@ -1,5 +1,15 @@
 const path = require('node:path')
+const { createSoundingError } = require('./create-error')
 
+/** @typedef {import('./types').AnyRecord} AnyRecord */
+/** @typedef {import('./types').SoundingConfig} SoundingConfig */
+/** @typedef {import('./types').SoundingDatastoreState} SoundingDatastoreState */
+/** @typedef {import('./types').SoundingSailsApp} SoundingSailsApp */
+
+/**
+ * @param {NodeJS.ProcessEnv | AnyRecord} [env]
+ * @returns {string}
+ */
 function getWorkerToken(env = process.env) {
   return (
     env.SOUNDING_WORKER_INDEX ||
@@ -9,6 +19,15 @@ function getWorkerToken(env = process.env) {
   )
 }
 
+/**
+ * @param {{
+ *   root?: string,
+ *   identity?: string,
+ *   isolation?: string,
+ *   env?: NodeJS.ProcessEnv | AnyRecord,
+ * }} options
+ * @returns {string}
+ */
 function buildManagedSqlitePath({
   root = path.join(process.cwd(), '.tmp', 'db'),
   identity = 'default',
@@ -19,6 +38,10 @@ function buildManagedSqlitePath({
   return path.join(root, identity, `${workerToken}.db`)
 }
 
+/**
+ * @param {{ sails?: SoundingSailsApp, datastore?: AnyRecord, appPath?: string }} options
+ * @returns {string}
+ */
 function resolveManagedRoot({ sails, datastore = {}, appPath } = {}) {
   const configuredRoot = datastore.root || path.join('.tmp', 'db')
 
@@ -29,7 +52,12 @@ function resolveManagedRoot({ sails, datastore = {}, appPath } = {}) {
   return path.resolve(appPath || sails?.config?.appPath || process.cwd(), configuredRoot)
 }
 
+/**
+ * @param {{ sails: SoundingSailsApp, soundingConfig: SoundingConfig }} input
+ * @returns {SoundingDatastoreState & { managed: boolean, filePath?: string }}
+ */
 function resolveDatastore({ sails, soundingConfig }) {
+  /** @type {AnyRecord} */
   const datastoreConfig = soundingConfig.datastore || {}
   const mode = datastoreConfig.mode || 'managed'
   const identity = datastoreConfig.identity || 'default'
@@ -39,9 +67,14 @@ function resolveDatastore({ sails, soundingConfig }) {
     const configuredDatastore = datastores[identity]
 
     if (!configuredDatastore) {
-      throw new Error(
-        `Sounding could not find datastore \`${identity}\` in sails.config.datastores for mode \`${mode}\`.`
-      )
+      throw createSoundingError({
+        code: 'E_SOUNDING_DATASTORE_CONFIG_MISSING',
+        message: `Sounding could not find datastore \`${identity}\` in sails.config.datastores for mode \`${mode}\`.`,
+        details: {
+          mode,
+          identity,
+        },
+      })
     }
 
     return {
@@ -56,9 +89,13 @@ function resolveDatastore({ sails, soundingConfig }) {
     const adapter = datastoreConfig.adapter || 'sails-sqlite'
 
     if (adapter !== 'sails-sqlite') {
-      throw new Error(
-        `Sounding only supports managed adapter \`sails-sqlite\` in v0.0.1. Received \`${adapter}\`.`
-      )
+      throw createSoundingError({
+        code: 'E_SOUNDING_DATASTORE_ADAPTER_UNSUPPORTED',
+        message: `Sounding only supports managed adapter \`sails-sqlite\` in v0.0.1. Received \`${adapter}\`.`,
+        details: {
+          adapter,
+        },
+      })
     }
 
     const filePath = buildManagedSqlitePath({
@@ -87,7 +124,13 @@ function resolveDatastore({ sails, soundingConfig }) {
     }
   }
 
-  throw new Error(`Unknown Sounding datastore mode: ${mode}`)
+  throw createSoundingError({
+    code: 'E_SOUNDING_DATASTORE_MODE_UNKNOWN',
+    message: `Unknown Sounding datastore mode: ${mode}`,
+    details: {
+      mode,
+    },
+  })
 }
 
 module.exports = {