@platformatic/foundation 3.0.0-alpha.2

package/lib/file-system.js

@@ -0,0 +1,188 @@
+import generateName from 'boring-name-generator'
+import { EventEmitter } from 'node:events'
+import { existsSync } from 'node:fs'
+import { access, glob, mkdir, rm, watch } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, matchesGlob, resolve } from 'node:path'
+import { setTimeout as sleep } from 'node:timers/promises'
+import { PathOptionRequiredError } from './errors.js'
+
+let tmpCount = 0
+const ALLOWED_FS_EVENTS = ['change', 'rename']
+
+export function removeDotSlash (path) {
+  return path.replace(/^\.[/\\]/, '')
+}
+
+export function generateDashedName () {
+  return generateName().dashed.replace(/\s+/g, '')
+}
+
+export async function isFileAccessible (filename, directory) {
+  try {
+    const filePath = directory ? resolve(directory, filename) : filename
+    await access(filePath)
+    return true
+  } catch (err) {
+    return false
+  }
+}
+
+export async function createDirectory (path, empty = false) {
+  if (empty) {
+    await safeRemove(path)
+  }
+
+  return mkdir(path, { recursive: true, maxRetries: 10, retryDelay: 1000 })
+}
+
+export async function createTemporaryDirectory (prefix) {
+  const directory = join(tmpdir(), `plt-utils-${prefix}-${process.pid}-${tmpCount++}`)
+
+  return createDirectory(directory)
+}
+
+export async function safeRemove (path) {
+  let i = 0
+  while (i++ < 10) {
+    if (!existsSync(path)) {
+      return
+    }
+
+    /* c8 ignore start - Hard to test */
+    try {
+      await rm(path, { force: true, recursive: true })
+      break
+    } catch {
+      // This means that we might not delete the folder at all.
+      // This is ok as we can't really trust Windows to behave.
+    }
+
+    await sleep(1000)
+    /* c8 ignore end - Hard to test */
+  }
+}
+
+export async function searchFilesWithExtensions (root, extensions, globOptions = {}) {
+  const globSuffix = Array.isArray(extensions) ? `{${extensions.join(',')}}` : extensions
+  return Array.fromAsync(glob(`**/*.${globSuffix}`, { ...globOptions, cwd: root }))
+}
+
+export async function searchJavascriptFiles (projectDir, globOptions = {}) {
+  return searchFilesWithExtensions(projectDir, ['js', 'mjs', 'cjs', 'ts', 'mts', 'cts'], {
+    ...globOptions,
+    ignore: ['node_modules', '**/node_modules/**']
+  })
+}
+
+export async function hasFilesWithExtensions (root, extensions, globOptions = {}) {
+  const files = await searchFilesWithExtensions(root, extensions, globOptions)
+  return files.length > 0
+}
+
+export async function hasJavascriptFiles (projectDir, globOptions = {}) {
+  const files = await searchJavascriptFiles(projectDir, globOptions)
+  return files.length > 0
+}
+
+export class FileWatcher extends EventEmitter {
+  constructor (opts) {
+    super()
+
+    if (typeof opts.path !== 'string') {
+      throw new PathOptionRequiredError()
+    }
+    this.path = opts.path
+    this.allowToWatch = opts.allowToWatch?.map(removeDotSlash) || null
+    this.watchIgnore = opts.watchIgnore?.map(removeDotSlash) || null
+    this.handlePromise = null
+    this.abortController = null
+
+    if (this.allowToWatch) {
+      this.allowToWatch = Array.from(new Set(this.allowToWatch))
+    }
+
+    if (this.watchIgnore) {
+      this.watchIgnore = Array.from(new Set(this.watchIgnore))
+    }
+
+    this.isWatching = false
+  }
+
+  startWatching () {
+    if (this.isWatching) return
+    this.isWatching = true
+
+    this.abortController = new AbortController()
+    const signal = this.abortController.signal
+
+    // Recursive watch is unreliable on platforms besides macOS and Windows.
+    // See: https://github.com/nodejs/node/issues/48437
+    const fsWatcher = watch(this.path, {
+      signal,
+      recursive: true
+    })
+
+    let updateTimeout = null
+
+    this.on('update', () => {
+      clearTimeout(updateTimeout)
+      updateTimeout = null
+    })
+
+    const eventHandler = async () => {
+      for await (const { eventType, filename } of fsWatcher) {
+        /* c8 ignore next */
+        if (filename === null) return
+        const isTimeoutSet = updateTimeout === null
+        const isTrackedEvent = ALLOWED_FS_EVENTS.includes(eventType)
+        const isTrackedFile = this.shouldFileBeWatched(filename)
+
+        if (isTimeoutSet && isTrackedEvent && isTrackedFile) {
+          updateTimeout = setTimeout(() => this.emit('update', filename), 100)
+          updateTimeout.unref()
+        }
+      }
+    } /* c8 ignore next */
+    this.handlePromise = eventHandler()
+  }
+
+  async stopWatching () {
+    if (!this.isWatching) return
+    this.isWatching = false
+
+    this.abortController.abort()
+    await this.handlePromise.catch(() => {})
+  }
+
+  shouldFileBeWatched (fileName) {
+    return this.isFileAllowed(fileName) && !this.isFileIgnored(fileName)
+  }
+
+  isFileAllowed (fileName) {
+    if (this.allowToWatch === null) {
+      return true
+    }
+
+    return this.allowToWatch.some(allowedFile => matchesGlob(fileName, allowedFile))
+  }
+
+  isFileIgnored (fileName) {
+    // Always ignore the node_modules folder - This can be overriden by the allow list
+    if (fileName.startsWith('node_modules')) {
+      return true
+    }
+
+    if (this.watchIgnore === null) {
+      return false
+    }
+
+    for (const ignoredFile of this.watchIgnore) {
+      if (matchesGlob(fileName, ignoredFile)) {
+        return true
+      }
+    }
+
+    return false
+  }
+}

package/lib/logger.js

@@ -0,0 +1,180 @@
+import { createRequire } from 'node:module'
+import { hostname } from 'node:os'
+import path from 'node:path'
+import pino from 'pino'
+
+// Utilities to build pino options from a config object
+// There are many variants to fit better the different use cases
+
+export function setPinoFormatters (options) {
+  const r = createRequire(path.dirname(options.formatters.path))
+  const formatters = loadFormatters(r, options.formatters.path)
+  if (formatters.bindings) {
+    if (typeof formatters.bindings === 'function') {
+      options.formatters.bindings = formatters.bindings
+    } else {
+      throw new Error('logger.formatters.bindings must be a function')
+    }
+  }
+  if (formatters.level) {
+    if (typeof formatters.level === 'function') {
+      options.formatters.level = formatters.level
+    } else {
+      throw new Error('logger.formatters.level must be a function')
+    }
+  }
+}
+
+export function buildPinoFormatters (formatters) {
+  const r = createRequire(path.dirname(formatters.path))
+  const f = loadFormatters(r, formatters.path)
+  const pinoFormatters = {}
+  if (f.bindings) {
+    if (typeof f.bindings === 'function') {
+      pinoFormatters.bindings = f.bindings
+    } else {
+      throw new Error('logger.formatters.bindings must be a function')
+    }
+  }
+  if (f.level) {
+    if (typeof f.level === 'function') {
+      pinoFormatters.level = f.level
+    } else {
+      throw new Error('logger.formatters.level must be a function')
+    }
+  }
+  return pinoFormatters
+}
+
+export function setPinoTimestamp (options) {
+  options.timestamp = stdTimeFunctions[options.timestamp]
+}
+
+export function buildPinoTimestamp (timestamp) {
+  return stdTimeFunctions[timestamp]
+}
+
+export function buildPinoOptions (loggerConfig, serverConfig, serviceId, workerId, context, root) {
+  const pinoOptions = {
+    level: loggerConfig?.level ?? serverConfig?.level ?? 'trace'
+  }
+
+  if (serviceId) {
+    pinoOptions.name = serviceId
+  }
+
+  if (loggerConfig?.base) {
+    for (const [key, value] of Object.entries(loggerConfig.base)) {
+      if (typeof value !== 'string') {
+        throw new Error(`logger.base.${key} must be a string`)
+      }
+    }
+    /* c8 ignore next - else */
+  } else if (loggerConfig?.base === null) {
+    pinoOptions.base = undefined
+  }
+
+  if (typeof context.worker?.index !== 'undefined' && loggerConfig?.base !== null) {
+    pinoOptions.base = {
+      ...(pinoOptions.base ?? {}),
+      pid: process.pid,
+      hostname: hostname(),
+      worker: workerId
+    }
+  }
+
+  if (loggerConfig?.formatters) {
+    pinoOptions.formatters = {}
+    const formatters = loadFormatters(createRequire(root), loggerConfig.formatters.path)
+    if (formatters.bindings) {
+      if (typeof formatters.bindings === 'function') {
+        pinoOptions.formatters.bindings = formatters.bindings
+      } else {
+        throw new Error('logger.formatters.bindings must be a function')
+      }
+    }
+    if (formatters.level) {
+      if (typeof formatters.level === 'function') {
+        pinoOptions.formatters.level = formatters.level
+      } else {
+        throw new Error('logger.formatters.level must be a function')
+      }
+    }
+  }
+
+  if (loggerConfig?.timestamp !== undefined) {
+    pinoOptions.timestamp = stdTimeFunctions[loggerConfig.timestamp]
+  }
+
+  if (loggerConfig?.redact) {
+    pinoOptions.redact = {
+      paths: loggerConfig.redact.paths,
+      censor: loggerConfig.redact.censor
+    }
+  }
+
+  if (loggerConfig?.messageKey) {
+    pinoOptions.messageKey = loggerConfig.messageKey
+  }
+
+  if (loggerConfig?.customLevels) {
+    for (const [key, value] of Object.entries(loggerConfig.customLevels)) {
+      if (typeof value !== 'number') {
+        throw new Error(`logger.customLevels.${key} must be a number`)
+      }
+    }
+    pinoOptions.customLevels = loggerConfig.customLevels
+  }
+
+  // This is used by standalone CLI like start-platformatic-node in @platformatic/node
+  if (loggerConfig?.pretty) {
+    pinoOptions.transport = { target: 'pino-pretty' }
+  }
+
+  return pinoOptions
+}
+
+export function loadFormatters (require, file) {
+  try {
+    // Check if the file is a valid path
+    const resolvedPath = require.resolve(file)
+
+    // Load the module
+    const loaded = require(resolvedPath)
+
+    return loaded?.default ?? loaded
+  } catch (error) {
+    throw new Error(`Failed to load function from ${file}: ${error.message}`)
+  }
+}
+
+// This is needed so that pino detects a tampered stdout and avoid writing directly to the FD.
+// Writing directly to the FD would bypass worker.stdout, which is currently piped in the parent process.
+// See: https://github.com/pinojs/pino/blob/ad864b7ae02b314b9a548614f705a437e0db78c3/lib/tools.js#L330
+export function disablePinoDirectWrite () {
+  process.stdout.write = process.stdout.write.bind(process.stdout)
+}
+
+/* c8 ignore start - Nothing to test */
+export function noop () {}
+
+export const abstractLogger = {
+  fatal: noop,
+  error: noop,
+  warn: noop,
+  info: noop,
+  debug: noop,
+  trace: noop,
+  done: noop,
+  child () {
+    return abstractLogger
+  }
+}
+/* c8 ignore end */
+
+export const stdTimeFunctions = {
+  epochTime: pino.stdTimeFunctions.epochTime,
+  unixTime: pino.stdTimeFunctions.unixTime,
+  nullTime: pino.stdTimeFunctions.nullTime,
+  isoTime: pino.stdTimeFunctions.isoTime
+}

package/lib/module.js

@@ -0,0 +1,175 @@
+import { existsSync } from 'node:fs'
+import { readFile, readdir } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { request } from 'undici'
+import { hasJavascriptFiles } from './file-system.js'
+
+let platformaticPackageVersion
+
+export const kFailedImport = Symbol('plt.utils.failedImport')
+
+export const defaultPackageManager = 'npm'
+
+export async function getLatestNpmVersion (pkg) {
+  const res = await request(`https://registry.npmjs.org/${pkg}`)
+  if (res.statusCode === 200) {
+    const json = await res.body.json()
+    return json['dist-tags'].latest
+  }
+  return null
+}
+
+export function getPkgManager () {
+  const userAgent = process.env.npm_config_user_agent
+  if (!userAgent) {
+    return 'npm'
+  }
+  const pmSpec = userAgent.split(' ')[0]
+  const separatorPos = pmSpec.lastIndexOf('/')
+  const name = pmSpec.substring(0, separatorPos)
+  return name || 'npm'
+}
+
+/**
+ * Get the package manager used in the project by looking at the lock file
+ *
+ * if `search` is true, will search for the package manager in a nested directory
+ */
+export async function getPackageManager (root, defaultManager = defaultPackageManager, search = false) {
+  if (existsSync(resolve(root, 'pnpm-lock.yaml'))) {
+    return 'pnpm'
+  }
+
+  if (existsSync(resolve(root, 'yarn.lock'))) {
+    return 'yarn'
+  }
+
+  if (existsSync(resolve(root, 'package-lock.json'))) {
+    return 'npm'
+  }
+
+  // search for the package manager in a nested directory
+  if (search) {
+    // look in the first level nested directory
+    for (const dir of await readdir(root)) {
+      const p = await getPackageManager(resolve(root, dir), null)
+      if (p) {
+        return p
+      }
+    }
+  }
+
+  return defaultManager
+}
+
+export function getInstallationCommand (packageManager, production) {
+  const args = ['install']
+  if (production) {
+    switch (packageManager) {
+      case 'pnpm':
+        args.push('--prod')
+        break
+      case 'yarn':
+        args.push('--production')
+        break
+      case 'npm':
+        args.push('--omit=dev')
+        break
+    }
+  }
+  return args
+}
+
+export async function getPlatformaticVersion () {
+  if (!platformaticPackageVersion) {
+    const packageJson = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf-8'))
+    platformaticPackageVersion = packageJson.version
+    return platformaticPackageVersion
+  }
+
+  return platformaticPackageVersion
+}
+
+export function hasDependency (packageJson, dependency) {
+  return packageJson.dependencies?.[dependency] || packageJson.devDependencies?.[dependency]
+}
+
+export function splitModuleFromVersion (module) {
+  if (!module) {
+    return {}
+  }
+  const versionMatcher = module.match(/(.+)@(\d+.\d+.\d+)/)
+  let version
+  if (versionMatcher) {
+    module = versionMatcher[1]
+    version = versionMatcher[2]
+  }
+  return { module, version }
+}
+
+export async function detectApplicationType (root, packageJson) {
+  if (!packageJson) {
+    try {
+      packageJson = JSON.parse(await readFile(resolve(root, 'package.json'), 'utf-8'))
+    } catch {
+      packageJson = {}
+    }
+  }
+
+  let name
+  let label
+
+  if (hasDependency(packageJson, '@nestjs/core')) {
+    name = '@platformatic/nest'
+    label = 'NestJS'
+  } else if (hasDependency(packageJson, 'next')) {
+    name = '@platformatic/next'
+    label = 'Next.js'
+  } else if (hasDependency(packageJson, '@remix-run/dev')) {
+    name = '@platformatic/remix'
+    label = 'Remix'
+  } else if (hasDependency(packageJson, 'astro')) {
+    name = '@platformatic/astro'
+    label = 'Astro'
+    // Since Vite is often used with other frameworks, we must check for Vite last
+  } else if (hasDependency(packageJson, 'vite')) {
+    name = '@platformatic/vite'
+    label = 'Vite'
+  } else if (await hasJavascriptFiles(root)) {
+    // If no specific framework is detected, we assume it's a generic Node.js application
+    name = '@platformatic/node'
+    label = 'Node.js'
+  }
+
+  return name ? { name, label } : null
+}
+
+export async function loadModule (require, path) {
+  if (path.startsWith('file://')) {
+    path = fileURLToPath(path)
+  }
+
+  let loaded
+  try {
+    try {
+      loaded = require(path)
+    } catch (err) {
+      /* c8 ignore next 4 */
+      if (err.code === 'ERR_REQUIRE_ESM') {
+        const toLoad = require.resolve(path)
+        loaded = await import('file://' + toLoad)
+      } else {
+        throw err
+      }
+    }
+  } catch (err) {
+    if (err.code === 'ERR_MODULE_NOT_FOUND' || err.code === 'MODULE_NOT_FOUND') {
+      err[kFailedImport] = path
+    }
+
+    throw err
+  }
+
+  return loaded?.default ?? loaded
+}

package/lib/node.js

@@ -0,0 +1,24 @@
+import { platform } from 'node:os'
+import { lt, satisfies } from 'semver'
+
+const currentPlatform = platform()
+
+export function checkNodeVersionForServices () {
+  const currentVersion = process.version
+  const minimumVersion = '22.18.0'
+
+  if (lt(currentVersion, minimumVersion)) {
+    throw new Error(
+      `Your current Node.js version is ${currentVersion}, while the minimum supported version is v${minimumVersion}. Please upgrade Node.js and try again.`
+    )
+  }
+}
+
+export const features = {
+  node: {
+    reusePort: satisfies(process.version, '^22.12.0 || ^23.1.0') && !['win32', 'darwin'].includes(currentPlatform),
+    worker: {
+      getHeapStatistics: satisfies(process.version, '^22.18.0')
+    }
+  }
+}

package/lib/object.js

@@ -0,0 +1,35 @@
+import { deepmerge as fastifyDeepMerge } from '@fastify/deepmerge'
+
+// This function merges arrays recursively. When the source is shorter than the target, the target value is cloned.
+function deepmergeArray (options) {
+  const { deepmerge, clone } = options
+
+  return function mergeArray (target, source) {
+    const sourceLength = source.length
+    const targetLength = Math.max(target.length, source.length)
+
+    const result = new Array(targetLength)
+    for (let i = 0; i < targetLength; i++) {
+      result[i] = i < sourceLength ? deepmerge(target[i], source[i]) : clone(target[i])
+    }
+
+    return result
+  }
+}
+
+export const deepmerge = fastifyDeepMerge({ all: true, mergeArray: deepmergeArray })
+
+export function isKeyEnabled (key, config) {
+  if (config === undefined) return false
+  if (typeof config[key] === 'boolean') {
+    return config[key]
+  }
+  if (config[key] === undefined) {
+    return false
+  }
+  return true
+}
+
+export function getPrivateSymbol (obj, name) {
+  return Object.getOwnPropertySymbols(obj).find(s => s.description === name)
+}