@adonisjs/repl 3.1.11 → 4.0.0-0

package/src/adonis_bindings.ts

@@ -0,0 +1,63 @@
+import { ApplicationService } from '@adonisjs/core/types'
+import { Repl } from './repl.js'
+
+function setupReplState(repl: any, key: string, value: any) {
+  repl.server.context[key] = value
+  repl.notify(
+    `Loaded ${key} module. You can access it using the "${repl.colors.underline(key)}" variable`,
+  )
+}
+
+export function defineReplBindings(application: ApplicationService, replService: Repl) {
+  /**
+   * Load the encryption module
+   */
+  replService.addMethod(
+    'loadEncryption',
+    async (repl) => {
+      setupReplState(repl, 'encryption', await application.container.make('encryption'))
+    },
+    {
+      description: 'Load encryption provider and save reference to the "encryption" variable',
+    },
+  )
+
+  /**
+   * Load the hash module
+   */
+  replService.addMethod(
+    'loadHash',
+    async (repl) => {
+      setupReplState(repl, 'hash', await application.container.make('hash'))
+    },
+    {
+      description: 'Load hash provider and save reference to the "hash" variable',
+    },
+  )
+
+  /**
+   * Load the HTTP router
+   */
+  replService.addMethod(
+    'loadRouter',
+    async (repl) => {
+      setupReplState(repl, 'router', await application.container.make('router'))
+    },
+    {
+      description: 'Load router and save reference to the "router" variable',
+    },
+  )
+
+  /**
+   * Load config
+   */
+  replService.addMethod(
+    'loadConfig',
+    async (repl) => {
+      setupReplState(repl, 'config', await application.container.make('config'))
+    },
+    {
+      description: 'Load config and save reference to the "config" variable',
+    },
+  )
+}

package/src/colorizer.ts

@@ -0,0 +1,62 @@
+/*
+ * @adonisjs/repl
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { Sheet, emphasize } from 'emphasize'
+import useColors from '@poppinss/colors'
+import { Colors } from '@poppinss/colors/types'
+
+/**
+ * Maps the token types to the colors
+ */
+const sheet = (colors: Colors): Sheet => ({
+  'comment': (s) => colors.gray(s),
+  'quote': (s) => colors.gray(s),
+
+  'keyword': (s) => colors.cyan(s),
+  'addition': (s) => colors.cyan(s),
+
+  'number': (s) => colors.yellow(s),
+  'string': (s) => colors.green(s),
+  'meta meta-string': (s) => colors.cyan(s),
+  'literal': (s) => colors.yellow(s),
+  'doctag': (s) => colors.cyan(s),
+  'regexp': (s) => colors.red(s),
+
+  'attribute': (s) => colors.yellow(s),
+  'attr': (s) => colors.yellow(s),
+  'variable': (s) => colors.yellow(s),
+  'template-variable': (s) => colors.yellow(s),
+  'class title': (s) => colors.yellow(s),
+  'function title': (s) => colors.yellow(s),
+  'type': (s) => colors.yellow(s),
+
+  'symbol': (s) => colors.green(s),
+  'bullet': (s) => colors.magenta(s),
+  'subst': (s) => colors.magenta(s),
+  'meta': (s) => colors.magenta(s),
+  'meta keyword': (s) => colors.magenta(s),
+  'link': (s) => colors.magenta(s),
+
+  'built_in': (s) => colors.cyan(s),
+  'deletion': (s) => colors.red(s),
+
+  'emphasis': (s) => colors.italic(s),
+  'strong': (s) => colors.bold(s),
+  'formula': (s) => colors.inverse(s),
+})
+
+export function colorizer() {
+  const colors = useColors.ansi()
+  const colorSheet = sheet(colors)
+
+  const highlight = (s: string) => emphasize.highlight('ts', s, colorSheet).value
+  highlight.colorizeMatchingBracket = (s: string) => colors.bgBlue(s)
+
+  return highlight
+}

package/src/repl.ts

@@ -0,0 +1,423 @@
+/*
+ * @adonisjs/repl
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import useColors from '@poppinss/colors'
+import { REPLServer, Recoverable } from 'node:repl'
+import prettyRepl from 'pretty-repl'
+import stringWidth from 'string-width'
+import { inspect, promisify as utilPromisify } from 'node:util'
+import { colorizer } from './colorizer.js'
+import { Handler, ContextOptions, Compiler } from './types/main.js'
+
+/**
+ * List of node global properties to remove from the
+ * ls inspect
+ */
+const GLOBAL_NODE_PROPERTIES = [
+  'performance',
+  'global',
+  'clearInterval',
+  'clearTimeout',
+  'setInterval',
+  'setTimeout',
+  'queueMicrotask',
+  'clearImmediate',
+  'setImmediate',
+  'structuredClone',
+  'atob',
+  'btoa',
+  'fetch',
+  'crypto',
+]
+
+const TS_UTILS_HELPERS = [
+  '__extends',
+  '__assign',
+  '__rest',
+  '__decorate',
+  '__param',
+  '__esDecorate',
+  '__runInitializers',
+  '__propKey',
+  '__setFunctionName',
+  '__metadata',
+  '__awaiter',
+  '__generator',
+  '__exportStar',
+  '__createBinding',
+  '__values',
+  '__read',
+  '__spread',
+  '__spreadArrays',
+  '__spreadArray',
+  '__await',
+  '__asyncGenerator',
+  '__asyncDelegator',
+  '__asyncValues',
+  '__makeTemplateObject',
+  '__importStar',
+  '__importDefault',
+  '__classPrivateFieldGet',
+  '__classPrivateFieldSet',
+  '__classPrivateFieldIn',
+]
+
+const icons =
+  process.platform === 'win32' && !process.env.WT_SESSION
+    ? { tick: '√', pointer: '>' }
+    : { tick: '✔', pointer: '❯' }
+
+export class Repl {
+  /**
+   * Length of the longest custom method name. We need to show a
+   * symmetric view of custom methods and their description
+   */
+  #longestCustomMethodName = 0
+
+  /**
+   * Reference to the original `eval` method of the repl server.
+   * Since we are monkey patching it, we need a reference to it
+   * to call it after our custom logic
+   */
+  #originalEval: Function | null = null
+
+  colors = useColors.ansi()
+
+  /**
+   * Reference to the repl server. Available after the `start` method
+   * is invoked
+   */
+  server?: REPLServer
+
+  /**
+   * Compiler that will transform the user input just
+   * before evaluation
+   */
+  #compiler?: Compiler
+
+  /**
+   * Set of registered ready callbacks
+   */
+  #onReadyCallbacks: ((repl: Repl) => void)[] = []
+
+  /**
+   * A set of registered custom methods
+   */
+  #customMethods: {
+    [name: string]: { handler: Handler; options: ContextOptions & { width: number } }
+  } = {}
+
+  /**
+   * Path to the history file
+   */
+  #historyFilePath: string | undefined
+
+  constructor(options?: { compiler?: Compiler; historyFilePath?: string }) {
+    this.#compiler = options?.compiler
+    this.#historyFilePath = options?.historyFilePath
+  }
+
+  /**
+   * Prints the welcome message
+   */
+  #printWelcomeMessage() {
+    console.log('')
+
+    /**
+     * Log about typescript support
+     */
+    if (this.#compiler?.supportsTypescript) {
+      console.log(
+        `${this.colors.green(icons.tick)} ${this.colors.dim('typescript compilation supported')}`,
+      )
+      console.log('')
+    }
+
+    /**
+     * Log about help command
+     */
+    this.notify('Type ".ls" to a view list of available context methods/properties')
+  }
+
+  /**
+   * Setup context with default globals
+   */
+  #setupContext() {
+    /**
+     * Register "clear" method
+     */
+    this.addMethod(
+      'clear',
+      function clear(repl: Repl, key: string) {
+        if (!key) {
+          console.log(repl.colors.red('Define a property name to remove from the context'))
+        } else {
+          delete repl.server!.context[key]
+        }
+        repl.server!.displayPrompt()
+      },
+      {
+        description: 'Clear a property from the REPL context',
+        usage: `clear ${this.colors.gray('(propertyName)')}`,
+      },
+    )
+
+    /**
+     * Register "p" method
+     */
+    this.addMethod(
+      'p',
+      function promisify(_: Repl, fn: Function) {
+        return utilPromisify(fn)
+      },
+      {
+        description: 'Promisify a function. Similar to Node.js "util.promisify"',
+        usage: `p ${this.colors.gray('(function)')}`,
+      },
+    )
+
+    /**
+     * Register all custom methods with the context
+     */
+    this.#registerCustomMethodsWithContext()
+  }
+
+  /**
+   * Register custom methods with the server context
+   */
+  #registerCustomMethodsWithContext() {
+    Object.keys(this.#customMethods).forEach((name) => {
+      this.#registerCustomMethodWithContext(name)
+    })
+  }
+
+  /**
+   * Find if the error is recoverable or not
+   */
+  #isRecoverableError(error: any) {
+    return /^(Unexpected end of input|Unexpected token|' expected)/.test(error.message)
+  }
+
+  /**
+   * Custom eval method to execute the user code
+   *
+   * Basically we are monkey patching the original eval method.
+   * The reason why we need to do that is because we want :
+   * - to compile the user code before executing it
+   * - and also benefit from the original eval method that supports
+   *  cool features like top level await.
+   */
+  #eval(
+    code: string,
+    context: any,
+    filename: string,
+    callback: (err: Error | null, result?: any) => void,
+  ) {
+    try {
+      const compiled = this.#compiler!.compile(code, filename)
+        .replace('export { };', '')
+        .replace(/\/\/# sourceMappingURL=(.*)$/, '/** sourceMappingURL=$1 */')
+
+      return this.#originalEval!(compiled, context, filename, callback)
+    } catch (error) {
+      if (this.#isRecoverableError(error)) {
+        callback(new Recoverable(error), null)
+        return
+      }
+
+      callback(error, null)
+    }
+  }
+
+  /**
+   * Setup history file
+   */
+  #setupHistory() {
+    if (!this.#historyFilePath) {
+      return
+    }
+
+    this.server!.setupHistory(this.#historyFilePath, (error) => {
+      if (!error) {
+        return
+      }
+
+      console.log(this.colors.red('Unable to write to the history file. Exiting'))
+      console.error(error)
+      process.exit(1)
+    })
+  }
+
+  /**
+   * Prints the help for the context properties
+   */
+  #printContextHelp() {
+    /**
+     * Print context properties
+     */
+    console.log('')
+    console.log(this.colors.green('CONTEXT PROPERTIES/METHODS:'))
+
+    const context = Object.keys(this.server!.context).reduce((result, key) => {
+      if (
+        !this.#customMethods[key] &&
+        !GLOBAL_NODE_PROPERTIES.includes(key) &&
+        !TS_UTILS_HELPERS.includes(key)
+      ) {
+        result[key] = this.server!.context[key]
+      }
+
+      return result
+    }, {} as Record<string, any>)
+
+    console.log(inspect(context, false, 1, true))
+  }
+
+  /**
+   * Prints the help for the custom methods
+   */
+  #printCustomMethodsHelp() {
+    /**
+     * Print loader methods
+     */
+    console.log('')
+    console.log(this.colors.green('GLOBAL METHODS:'))
+
+    Object.keys(this.#customMethods).forEach((method) => {
+      const { options } = this.#customMethods[method]
+      const spaces = new Array(this.#longestCustomMethodName - options.width + 2).join(' ')
+
+      console.log(
+        `${this.colors.yellow(options.usage || method)}${spaces}${this.colors.dim(
+          options.description || '',
+        )}`,
+      )
+    })
+  }
+
+  #registerCustomMethodWithContext(name: string) {
+    const customMethod = this.#customMethods[name]
+    if (!customMethod) {
+      return
+    }
+
+    /**
+     * Wrap handler
+     */
+    const handler = (...args: any[]) => customMethod.handler(this, ...args)
+
+    /**
+     * Re-define the function name to be more description
+     */
+    Object.defineProperty(handler, 'name', { value: customMethod.handler.name })
+
+    /**
+     * Register with the context
+     */
+    this.server!.context[name] = handler
+  }
+
+  /**
+   * Prints the context to the console
+   */
+  #ls() {
+    this.#printCustomMethodsHelp()
+    this.#printContextHelp()
+    this.server!.displayPrompt()
+  }
+
+  /**
+   * Notify by writing to the console
+   */
+  notify(message: string) {
+    console.log(this.colors.yellow().italic(message))
+    if (this.server) {
+      this.server.displayPrompt()
+    }
+  }
+
+  /**
+   * Start the REPL server
+   */
+  start() {
+    this.#printWelcomeMessage()
+
+    this.server = prettyRepl.start({
+      prompt: '> ',
+      input: process.stdin,
+      output: process.stdout,
+      terminal: process.stdout.isTTY && !Number.parseInt(process.env.NODE_NO_READLINE!, 10),
+      useGlobal: true,
+      // @ts-ignore
+      colorize: colorizer(),
+    })
+
+    /**
+     * Define the `ls` command
+     */
+    this.server!.defineCommand('ls', {
+      help: 'View list of available context methods/properties',
+      action: this.#ls.bind(this),
+    })
+
+    /**
+     * Setup context and history
+     */
+    this.#setupContext()
+    this.#setupHistory()
+
+    /**
+     * Monkey patch the eval method
+     */
+    this.#originalEval = this.server.eval
+    // @ts-ignore
+    this.server.eval = this.#eval.bind(this)
+
+    /**
+     * Display prompt
+     */
+    this.server.displayPrompt()
+
+    /**
+     * Execute onReady callbacks
+     */
+    this.#onReadyCallbacks.forEach((callback) => callback(this))
+
+    return this
+  }
+
+  /**
+   * Register a callback to be invoked once the server is ready
+   */
+  ready(callback: (repl: Repl) => void): this {
+    this.#onReadyCallbacks.push(callback)
+    return this
+  }
+
+  /**
+   * Register a custom loader function to be added to the context
+   */
+  addMethod(name: string, handler: Handler, options?: ContextOptions): this {
+    const width = stringWidth(options?.usage || name)
+    if (width > this.#longestCustomMethodName) {
+      this.#longestCustomMethodName = width
+    }
+
+    this.#customMethods[name] = { handler, options: Object.assign({ width }, options) }
+
+    /**
+     * Register method right away when server has been started
+     */
+    if (this.server) {
+      this.#registerCustomMethodWithContext(name)
+    }
+
+    return this
+  }
+}

package/{build/adonis-typings/container.js → src/types/extended.ts}

@@ -1,8 +1,16 @@
 /*
  * @adonisjs/repl
  *
- * (c) Harminder Virk <virk@adonisjs.com>
+ * (c) AdonisJS
  *
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
+
+import { Repl } from '../repl.js'
+
+declare module '@adonisjs/core/types' {
+  export interface ContainerBindings {
+    repl: Repl
+  }
+}

package/src/types/main.ts

@@ -0,0 +1,33 @@
+/*
+ * @adonisjs/repl
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { Repl } from '../repl.js'
+
+/**
+ * Custom method handler
+ */
+export type Handler = (repl: Repl, ...args: any[]) => any
+
+/**
+ * Options that can be set when defining a loader
+ * method
+ */
+export type ContextOptions = {
+  description?: string
+  usage?: string
+}
+
+/**
+ * Shape of the Compiler that must be passed to the
+ * repl constructor
+ */
+export type Compiler = {
+  compile: (code: string, fileName: string) => string
+  supportsTypescript: boolean
+}

package/src/utils.ts

@@ -0,0 +1,14 @@
+import { createRequire } from 'node:module'
+
+/**
+ * Check if a given module is installed
+ */
+export function isModuleInstalled(moduleName: string) {
+  const require = createRequire(import.meta.url)
+  try {
+    require.resolve(moduleName)
+    return true
+  } catch (error) {
+    return false
+  }
+}

package/build/adonis-typings/container.d.ts

@@ -1,6 +0,0 @@
-declare module '@ioc:Adonis/Core/Application' {
-    import { ReplContract } from '@ioc:Adonis/Addons/Repl';
-    interface ContainerBindings {
-        'Adonis/Addons/Repl': ReplContract;
-    }
-}

package/build/adonis-typings/index.d.ts

@@ -1,2 +0,0 @@
-/// <reference path="container.d.ts" />
-/// <reference path="repl.d.ts" />

package/build/adonis-typings/index.js

@@ -1,10 +0,0 @@
-/*
- * @adonisjs/repl
- *
- * (c) Harminder Virk <virk@adonisjs.com>
- *
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- */
-/// <reference path="./container.ts" />
-/// <reference path="./repl.ts" />

package/build/adonis-typings/repl.d.ts

@@ -1,46 +0,0 @@
-/// <reference types="node" />
-declare module '@ioc:Adonis/Addons/Repl' {
-    import { REPLServer } from 'repl';
-    import { getBest } from '@poppinss/colors';
-    /**
-     * Custom method callback
-     */
-    export type Handler = (repl: ReplContract, ...args: any[]) => any;
-    /**
-     * Options that can be set when defining a loader
-     * method
-     */
-    export type ContextOptions = {
-        description?: string;
-        usage?: string;
-    };
-    /**
-     * Shape of the REPL class
-     */
-    export interface ReplContract {
-        colors: ReturnType<typeof getBest>;
-        /**
-         * Reference to the REPL server
-         */
-        server: REPLServer;
-        /**
-         * Start the repl
-         */
-        start(): this;
-        /**
-         * Notify by writing message to the console
-         * and resuming the prompt
-         */
-        notify(message: string): void;
-        /**
-         * Add a method. Loader methods works as a shortcut for
-         */
-        addMethod(name: string, handler: Handler, options?: ContextOptions): this;
-        /**
-         * Register a callback to be invoked once the server is ready
-         */
-        ready(callback: (repl: ReplContract) => void): this;
-    }
-    const Repl: ReplContract;
-    export default Repl;
-}

package/build/commands/AdonisRepl.d.ts

@@ -1,11 +0,0 @@
-import { BaseCommand } from '@adonisjs/core/build/standalone';
-export default class ReplCommand extends BaseCommand {
-    static commandName: string;
-    static description: string;
-    static settings: {
-        loadApp: boolean;
-        environment: "repl";
-        stayAlive: boolean;
-    };
-    run(): Promise<void>;
-}