@adonisjs/core 6.1.5-2 → 6.1.5-3

package/src/helpers/types.ts

@@ -0,0 +1,46 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import is from '@sindresorhus/is'
+
+/**
+ * @deprecated
+ * Use "is" helpers instead. The types helpers exists
+ * for backward compatibility
+ */
+const types = {
+  lookup: is,
+  isNull: is.null_,
+  isBoolean: is.boolean,
+  isBuffer: is.buffer,
+  isNumber: is.number,
+  isString: is.string,
+  isArguments: is.arguments,
+  isObject: is.object,
+  isDate: is.date,
+  isArray: is.array,
+  isRegexp: is.regExp,
+  isError: is.error,
+  isFunction: is.function_,
+  isClass: is.class_,
+  isInteger: is.integer,
+  isFloat(value: number): value is number {
+    return value !== (value | 0)
+  },
+  isDecimal(value: string | number, options?: { decimalPlaces?: string }): boolean {
+    if (typeof value === 'number') {
+      value = value.toString()
+    }
+
+    const decimalPlaces = (options && options.decimalPlaces) || '1,'
+    return new RegExp(`^[-+]?([0-9]+)?(\\.[0-9]{${decimalPlaces}})$`).test(value)
+  },
+}
+
+export default types

package/src/ignitor/ace.ts

@@ -0,0 +1,90 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { Ignitor } from './main.js'
+import type { ApplicationService } from '../types.js'
+
+/**
+ * The Ace process is used to start the application in the
+ * console environment.
+ */
+export class AceProcess {
+  /**
+   * Ignitor reference
+   */
+  #ignitor: Ignitor
+
+  /**
+   * The callback that configures the tests runner. This callback
+   * runs at the time of starting the app.
+   */
+  #configureCallback: (app: ApplicationService) => Promise<void> | void = () => {}
+
+  constructor(ignitor: Ignitor) {
+    this.#ignitor = ignitor
+  }
+
+  /**
+   * Register a callback that runs after booting the AdonisJS app
+   * and just before the provider's ready hook
+   */
+  configure(callback: (app: ApplicationService) => Promise<void> | void): this {
+    this.#configureCallback = callback
+    return this
+  }
+
+  /**
+   * Handles the command line arguments and executes
+   * the matching ace commands
+   */
+  async handle(argv: string[]) {
+    const app = this.#ignitor.createApp('console')
+    await app.init()
+
+    const { createAceKernel } = await import('../../modules/ace/create_kernel.js')
+
+    const kernel = createAceKernel(app)
+    app.container.bindValue('ace', kernel)
+
+    /**
+     * Hook into kernel and start the app when the
+     * command needs the app.
+     *
+     * Since multiple commands can be executed in a single process,
+     * we add a check to only start the app only once.
+     */
+    kernel.loading(async (metaData) => {
+      if (metaData.options.startApp && !app.isReady) {
+        await app.boot()
+        await app.start(() => {})
+      }
+    })
+
+    await this.#configureCallback(app)
+
+    /**
+     * Handle command line args
+     */
+    await kernel.handle(argv)
+
+    /**
+     * Update the process exit code
+     */
+    process.exitCode = kernel.exitCode
+
+    /**
+     * Terminate the app when the command does not want to
+     * hold a long running process
+     */
+    const mainCommand = kernel.getMainCommand()
+    if (!mainCommand || !mainCommand.staysAlive) {
+      await app.terminate()
+    }
+  }
+}

package/src/ignitor/http.ts

@@ -0,0 +1,167 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import type { Server as NodeHttpsServer } from 'node:https'
+import { IncomingMessage, ServerResponse, Server as NodeHttpServer, createServer } from 'node:http'
+
+import debug from '../debug.js'
+import { Ignitor } from './main.js'
+import type { ApplicationService, EmitterService, LoggerService } from '../types.js'
+
+/**
+ * The HTTP server process is used to start the application in the
+ * web environment.
+ */
+export class HttpServerProcess {
+  /**
+   * Ignitor reference
+   */
+  #ignitor: Ignitor
+
+  constructor(ignitor: Ignitor) {
+    this.#ignitor = ignitor
+  }
+
+  /**
+   * Calling this method closes the underlying HTTP server
+   */
+  #close(nodeHttpServer: NodeHttpsServer | NodeHttpServer): Promise<void> {
+    return new Promise((resolve) => {
+      debug('closing http server process')
+      nodeHttpServer.close(() => resolve())
+    })
+  }
+
+  /**
+   * Monitors the app and the server to close the HTTP server when
+   * either one of them goes down
+   */
+  #monitorAppAndServer(
+    nodeHttpServer: NodeHttpsServer | NodeHttpServer,
+    app: ApplicationService,
+    logger: LoggerService
+  ) {
+    /**
+     * Close the HTTP server when the application begins to
+     * terminate
+     */
+    app.terminating(async () => {
+      debug('terminating signal received')
+      await this.#close(nodeHttpServer)
+    })
+
+    /**
+     * Terminate the app when the HTTP server crashes
+     */
+    nodeHttpServer.once('error', (error: NodeJS.ErrnoException) => {
+      debug('http server crashed with error "%O"', error)
+      logger.fatal({ err: error }, error.message)
+      process.exitCode = 1
+      app.terminate()
+    })
+  }
+
+  /**
+   * Starts the http server a given host and port
+   */
+  #listen(
+    nodeHttpServer: NodeHttpsServer | NodeHttpServer
+  ): Promise<{ port: number; host: string }> {
+    return new Promise((resolve, reject) => {
+      const host = process.env.HOST || '0.0.0.0'
+      const port = Number(process.env.PORT || '3333')
+
+      nodeHttpServer.listen(port, host)
+      nodeHttpServer.once('listening', () => {
+        debug('listening to http server, host :%s, port: %s', host, port)
+        resolve({ port, host })
+      })
+
+      nodeHttpServer.once('error', (error: NodeJS.ErrnoException) => {
+        reject(error)
+      })
+    })
+  }
+
+  /**
+   * Notifies the app and the parent process that the
+   * HTTP server is ready
+   */
+  #notifyServerHasStarted(
+    app: ApplicationService,
+    logger: LoggerService,
+    emitter: EmitterService,
+    payload: { host: string; port: number }
+  ) {
+    /**
+     * Notify parent process
+     */
+    app.notify({ isAdonisJS: true, environment: 'web', ...payload })
+
+    /**
+     * Visual notification
+     */
+    logger.info('started HTTP server on %s:%s', payload.host, payload.port)
+
+    /**
+     * Notify app
+     */
+    emitter.emit('http:server_ready', payload)
+  }
+
+  /**
+   * Start the HTTP server by wiring up the application
+   */
+  async start(
+    serverCallback?: (
+      handler: (req: IncomingMessage, res: ServerResponse) => any
+    ) => NodeHttpsServer | NodeHttpServer
+  ) {
+    /**
+     * Method to create the HTTP server
+     */
+    const createHTTPServer = serverCallback || createServer
+    const app = this.#ignitor.createApp('web')
+
+    await app.init()
+    await app.boot()
+    await app.start(async () => {
+      /**
+       * Resolve and boot the AdonisJS HTTP server
+       */
+      const server = await app.container.make('server')
+      await server.boot()
+
+      /**
+       * Create Node.js HTTP server instance and share it with the
+       * AdonisJS HTTP server
+       */
+      const httpServer = createHTTPServer(server.handle.bind(server))
+      server.setNodeServer(httpServer)
+
+      const logger = await app.container.make('logger')
+      const emitter = await app.container.make('emitter')
+
+      /**
+       * Start the server by listening on a port of host
+       */
+      const payload = await this.#listen(httpServer)
+
+      /**
+       * Notify
+       */
+      this.#notifyServerHasStarted(app, logger, emitter, payload)
+
+      /**
+       * Monitor app and the server (after the server is listening)
+       */
+      this.#monitorAppAndServer(httpServer, app, logger)
+    })
+  }
+}

package/src/ignitor/main.ts

@@ -0,0 +1,118 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import debug from '../debug.js'
+import { AceProcess } from './ace.js'
+import { TestRunnerProcess } from './test.js'
+import { HttpServerProcess } from './http.js'
+import { setApp } from '../../services/app.js'
+import { Application } from '../../modules/app.js'
+import type { AppEnvironments } from '../../types/app.js'
+import type { ApplicationService, IgnitorOptions } from '../types.js'
+
+/**
+ * Ignitor is used to instantiate an AdonisJS application in different
+ * known environments.
+ */
+export class Ignitor {
+  /**
+   * Ignitor options
+   */
+  #options: IgnitorOptions
+
+  /**
+   * Application root URL
+   */
+  #appRoot: URL
+
+  /**
+   * Reference to the application instance created using
+   * the "createApp" method.
+   *
+   * We store the output of the last call made to "createApp" method
+   * and assume that in one process only one entrypoint will
+   * call this method.
+   */
+  #app?: ApplicationService
+
+  /**
+   * Reference to the created application
+   */
+  #tapCallbacks: Set<(app: ApplicationService) => void> = new Set()
+
+  constructor(appRoot: URL, options: IgnitorOptions) {
+    this.#appRoot = appRoot
+    this.#options = options
+  }
+
+  /**
+   * Runs all the tap callbacks
+   */
+  #runTapCallbacks(app: ApplicationService) {
+    this.#tapCallbacks.forEach((tapCallback) => tapCallback(app))
+  }
+
+  /**
+   * Get access to the application instance created
+   * by either the http server process or the ace
+   * process
+   */
+  getApp() {
+    return this.#app
+  }
+
+  /**
+   * Create an instance of AdonisJS application
+   */
+  createApp(environment: AppEnvironments) {
+    debug('creating application instance')
+    this.#app = new Application(this.#appRoot, { environment, importer: this.#options.importer })
+
+    setApp(this.#app)
+    this.#runTapCallbacks(this.#app)
+    return this.#app
+  }
+
+  /**
+   * Tap to access the application class instance.
+   */
+  tap(callback: (app: ApplicationService) => void): this {
+    this.#tapCallbacks.add(callback)
+    return this
+  }
+
+  /**
+   * Get instance of the HTTPServerProcess
+   */
+  httpServer() {
+    return new HttpServerProcess(this)
+  }
+
+  /**
+   * Get an instance of the AceProcess class
+   */
+  ace() {
+    return new AceProcess(this)
+  }
+
+  /**
+   * Get an instance of the TestRunnerProcess class
+   */
+  testRunner() {
+    return new TestRunnerProcess(this)
+  }
+
+  /**
+   * Terminates the app by calling the "app.terminate"
+   * method
+   */
+  async terminate() {
+    await this.#app?.terminate()
+  }
+}

package/src/ignitor/test.ts

@@ -0,0 +1,51 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { Ignitor } from './main.js'
+import type { ApplicationService } from '../types.js'
+
+/**
+ * The Test runner process is used to start the tests runner process
+ */
+export class TestRunnerProcess {
+  /**
+   * Ignitor reference
+   */
+  #ignitor: Ignitor
+
+  /**
+   * The callback that configures the tests runner. This callback
+   * runs at the time of starting the app.
+   */
+  #configureCallback: (app: ApplicationService) => Promise<void> | void = () => {}
+
+  constructor(ignitor: Ignitor) {
+    this.#ignitor = ignitor
+  }
+
+  /**
+   * Register a callback that runs after booting the AdonisJS app
+   * and just before the provider's ready hook
+   */
+  configure(callback: (app: ApplicationService) => Promise<void> | void): this {
+    this.#configureCallback = callback
+    return this
+  }
+
+  /**
+   * Runs a callback after starting the app
+   */
+  async run(callback: (app: ApplicationService) => Promise<void> | void) {
+    const app = this.#ignitor.createApp('test')
+    await app.init()
+    await app.boot()
+    await app.start(this.#configureCallback)
+    await callback(app)
+  }
+}

package/src/internal_helpers.ts

@@ -0,0 +1,59 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import fs from 'node:fs'
+import { ApplicationService } from './types.js'
+
+/**
+ * Imports assembler optionally
+ */
+export async function importAssembler(
+  app: ApplicationService
+): Promise<typeof import('@adonisjs/assembler') | undefined> {
+  try {
+    return await app.import('@adonisjs/assembler')
+  } catch {}
+}
+
+/**
+ * Imports typescript optionally
+ */
+export async function importTypeScript(
+  app: ApplicationService
+): Promise<typeof import('typescript') | undefined> {
+  try {
+    return await app.importDefault('typescript')
+  } catch {}
+}
+
+/**
+ * Detects the assets bundler in use. The rcFile.assetsBundler is
+ * used when exists.
+ */
+export async function detectAssetsBundler(app: ApplicationService) {
+  if (app.rcFile.assetsBundler) {
+    return app.rcFile.assetsBundler
+  }
+
+  if (fs.existsSync(app.makePath('vite.config.js'))) {
+    return {
+      name: 'vite',
+      devServerCommand: 'vite',
+      buildCommand: 'vite build',
+    }
+  }
+
+  if (fs.existsSync(app.makePath('webpack.config.js'))) {
+    return {
+      name: 'encore',
+      devServerCommand: 'encore dev-server',
+      buildCommand: 'encore',
+    }
+  }
+}

package/src/test_utils/http.ts

@@ -0,0 +1,79 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import debug from '../debug.js'
+import type { TestUtils } from './main.js'
+import type { Server as NodeHttpsServer } from 'node:https'
+import { IncomingMessage, ServerResponse, Server as NodeHttpServer, createServer } from 'node:http'
+
+/**
+ * Http server utils are used to start the AdonisJS HTTP server
+ * during testing
+ */
+export class HttpServerUtils {
+  #utils: TestUtils
+
+  constructor(utils: TestUtils) {
+    this.#utils = utils
+  }
+
+  /**
+   * Starts the http server a given host and port
+   */
+  #listen(
+    nodeHttpServer: NodeHttpsServer | NodeHttpServer
+  ): Promise<{ port: number; host: string }> {
+    return new Promise((resolve, reject) => {
+      const host = process.env.HOST || '0.0.0.0'
+      const port = Number(process.env.PORT || '3333')
+
+      nodeHttpServer.listen(port, host)
+      nodeHttpServer.once('listening', () => {
+        debug('listening to utils http server, host :%s, port: %s', host, port)
+        resolve({ port, host })
+      })
+
+      nodeHttpServer.once('error', (error: NodeJS.ErrnoException) => {
+        reject(error)
+      })
+    })
+  }
+
+  /**
+   * Testing hook to start the HTTP server to listen for new request.
+   * The return value is a function to close the HTTP server.
+   */
+  async start(
+    serverCallback?: (
+      handler: (req: IncomingMessage, res: ServerResponse) => any
+    ) => NodeHttpsServer | NodeHttpServer
+  ): Promise<() => Promise<void>> {
+    const createHTTPServer = serverCallback || createServer
+
+    const server = await this.#utils.app.container.make('server')
+    await server.boot()
+
+    const httpServer = createHTTPServer(server.handle.bind(server))
+    server.setNodeServer(httpServer)
+
+    await this.#listen(httpServer)
+
+    return () => {
+      return new Promise<void>((resolve, reject) => {
+        httpServer.close((error) => {
+          if (error) {
+            reject(error)
+          } else {
+            resolve()
+          }
+        })
+      })
+    }
+  }
+}

package/src/test_utils/main.ts

@@ -0,0 +1,69 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { Socket } from 'node:net'
+import Macroable from '@poppinss/macroable'
+import { IncomingMessage, ServerResponse } from 'node:http'
+
+import { HttpServerUtils } from './http.js'
+import { CookieClient } from '../../modules/http.js'
+import type { ApplicationService } from '../types.js'
+
+/**
+ * Test utils has a collection of helper methods to make testing
+ * experience great for AdonisJS applications
+ */
+export class TestUtils extends Macroable {
+  #booted: boolean = false
+
+  /**
+   * Check if utils have been booted
+   */
+  get isBooted() {
+    return this.#booted
+  }
+
+  declare cookies: CookieClient
+
+  constructor(public app: ApplicationService) {
+    super()
+  }
+
+  /**
+   * Boot test utils. It requires the app to be booted
+   * and container to have all the bindings
+   */
+  async boot() {
+    if (!this.isBooted) {
+      this.#booted = true
+      this.cookies = new CookieClient(await this.app.container.make('encryption'))
+    }
+  }
+
+  /**
+   * Returns an instance of the HTTP server testing
+   * utils
+   */
+  httpServer() {
+    return new HttpServerUtils(this)
+  }
+
+  /**
+   * Create an instance of HTTP context for testing
+   */
+  async createHttpContext(options: { req?: IncomingMessage; res?: ServerResponse } = {}) {
+    const req = options.req || new IncomingMessage(new Socket())
+    const res = options.res || new ServerResponse(req)
+    const server = await this.app.container.make('server')
+
+    const request = server.createRequest(req, res)
+    const response = server.createResponse(req, res)
+    return server.createHttpContext(request, response, this.app.container.createResolver())
+  }
+}