@adonisjs/core 6.1.5-1 → 6.1.5-3

package/src/debug.ts

@@ -0,0 +1,12 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { debuglog } from 'node:util'
+
+export default debuglog('adonisjs:core')

package/src/helpers/is.ts

@@ -0,0 +1,11 @@
+/*
+ * @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'
+export default is

package/src/helpers/main.ts

@@ -0,0 +1,13 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+export { default as parseImports } from 'parse-imports'
+export { createId as cuid } from '@paralleldrive/cuid2'
+export { safeEqual, compose, base64, fsImportAll, fsReadAll, slash } from '@poppinss/utils'
+export { parseBindingReference } from './parse_binding_reference.js'

package/src/helpers/parse_binding_reference.ts

@@ -0,0 +1,93 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import parseImports from 'parse-imports'
+import { LazyImport, Constructor } from '../../types/http.js'
+
+/**
+ * The "parseBindingReference" method can be used to parse a binding references
+ * similar to route controller binding value or event listener binding value.
+ *
+ * See the following examples to understand how this function works.
+ *
+ * ### Magic strings
+ * ```ts
+ * parseBindingReference('#controllers/home_controller')
+ * // returns { moduleNameOrPath: '#controllers/home_controller', method: 'handle' }
+
+ * parseBindingReference('#controllers/home_controller.index')
+ * // returns { moduleNameOrPath: '#controllers/home_controller', method: 'index' }
+
+ * parseBindingReference('#controllers/home.controller.index')
+ * // returns { moduleNameOrPath: '#controllers/home.controller', method: 'index' }
+ * ```
+ *
+ * ### Class reference
+ * ```ts
+ * class HomeController {}
+ *
+ * parseBindingReference([HomeController])
+ * // returns { moduleNameOrPath: 'HomeController', method: 'handle' }
+
+ * parseBindingReference([HomeController, 'index'])
+ * // returns { moduleNameOrPath: 'HomeController', method: 'index' }
+ * ```
+ *
+ * ### Lazy import reference
+ * ```ts
+ * const HomeController = () => import('#controllers/home_controller')
+ *
+ * parseBindingReference([HomeController])
+ * // returns { moduleNameOrPath: '#controllers/home_controller', method: 'handle' }
+
+ * parseBindingReference([HomeController, 'index'])
+ * // returns { moduleNameOrPath: 'controllers/home_controller', method: 'index' }
+ * ```
+ */
+export async function parseBindingReference(
+  binding: string | [LazyImport<Constructor<any>> | Constructor<any>, any?]
+): Promise<{ moduleNameOrPath: string; method: string }> {
+  /**
+   * The binding reference is a magic string. It might not have method
+   * name attached to it. Therefore we split the string and attempt
+   * to find the method or use the default method name "handle".
+   */
+  if (typeof binding === 'string') {
+    const tokens = binding.split('.')
+    if (tokens.length === 1) {
+      return { moduleNameOrPath: binding, method: 'handle' }
+    }
+    return { method: tokens.pop()!, moduleNameOrPath: tokens.join('.') }
+  }
+
+  const [bindingReference, method] = binding
+
+  /**
+   * Parsing the binding reference for dynamic imports and using its
+   * import value.
+   */
+  const imports = [...(await parseImports(bindingReference.toString()))]
+  const importedModule = imports.find(
+    ($import) => $import.isDynamicImport && $import.moduleSpecifier.value
+  )
+  if (importedModule) {
+    return {
+      moduleNameOrPath: importedModule.moduleSpecifier.value!,
+      method: method || 'handle',
+    }
+  }
+
+  /**
+   * Otherwise using the name of the binding reference.
+   */
+  return {
+    moduleNameOrPath: bindingReference.name,
+    method: method || 'handle',
+  }
+}

package/src/helpers/string.ts

@@ -0,0 +1,89 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import he, { EncodeOptions } from 'he'
+import prettyHrTime from 'pretty-hrtime'
+import string from '@poppinss/utils/string'
+import StringBuilder from '@poppinss/utils/string_builder'
+
+/**
+ * Collection of string helpers to transform a string value.
+ */
+const stringHelpers: typeof string & {
+  /**
+   * Creates an instance of the string builder
+   */
+  create(value: string | StringBuilder): StringBuilder
+
+  ordinalize: (typeof string)['ordinal']
+
+  /**
+   * Convert a string to a sentence
+   */
+  toSentence: (typeof string)['sentence']
+
+  /**
+   * Generate a random string value of a given length
+   */
+  generateRandom: (typeof string)['random']
+
+  /**
+   * Pretty print hrtime diff
+   */
+  prettyHrTime(
+    time: [number, number],
+    options?: { verbose?: boolean | undefined; precise?: boolean | undefined }
+  ): string
+
+  /**
+   * Check if a string is empty.
+   */
+  isEmpty(value: string): boolean
+
+  /**
+   * Escape HTML entities
+   */
+  escapeHTML(value: string, options?: { encodeSymbols?: boolean }): string
+
+  /**
+   * Encode symbols to html entities
+   */
+  encodeSymbols(value: string, options?: EncodeOptions): string
+} = {
+  ...string,
+  toSentence: string.sentence,
+  ordinalize: string.ordinal,
+  generateRandom: string.random,
+
+  create(value: string | StringBuilder): StringBuilder {
+    return new StringBuilder(value)
+  },
+
+  prettyHrTime(time, options) {
+    return prettyHrTime(time, options)
+  },
+
+  isEmpty(value: string): boolean {
+    return value.trim().length === 0
+  },
+
+  escapeHTML(value: string, options?: { encodeSymbols?: boolean }): string {
+    value = he.escape(value)
+    if (options && options.encodeSymbols) {
+      value = this.encodeSymbols(value, { allowUnsafeSymbols: true })
+    }
+    return value
+  },
+
+  encodeSymbols(value: string, options?: EncodeOptions): string {
+    return he.encode(value, options)
+  },
+}
+
+export default stringHelpers

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)
+  }
+}