feat(core): read–eval–print loop feature

[kamilmysliwiec]

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://github.com/nestjs/nest/blob/master/CONTRIBUTING.md
• Tests for the changes have been added (for bug fixes / features)
• Docs have been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

• Bugfix
• Feature
• Code style update (formatting, local variables)
• Refactoring (no functional changes, no api changes)
• Build related changes
• CI related changes
• Other... Please describe:

What is the current behavior?

Issue Number: N/A

What is the new behavior?

https://twitter.com/i/status/1529088190958735361

Does this PR introduce a breaking change?

• Yes
• No

Other information

[coveralls]

Pull Request Test Coverage Report for Build b52928ac-3c6e-4a55-a0d4-5db25ea40e60

• 116 of 124 (93.55%) changed or added relevant lines in 10 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage decreased (-0.01%) to 94.096%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
packages/common/utils/cli-colors.util.ts	0	1	0.0%
packages/core/repl/native-functions/debug-repl-fn.ts	22	23	95.65%
packages/core/repl/repl-context.ts	48	51	94.12%
packages/core/repl/repl-function.ts	4	7	57.14%

Totals
Change from base Build 6a42a282-8488-456e-9dd2-df532926a28e:	-0.01%
Covered Lines:	5897
Relevant Lines:	6267

---

💛 - Coveralls

[Tony133]

A fantastic feature!. I can't wait to try it out 😻

[micalevisk]

can't we have a .exit command (like Nodejs REPL) to quit the REPL? 🤔

[Tony133]

I think Ctrl + C should be enough to exit or exit() it would be perfect ,but I don't know if the nest application is always running once REPL is closed 🤔

[micalevisk]

as we have debug(), exit() would be better (an alternative for those who can't use Ctrl+c)

[Tony133]

Many times if not always Ctrl + c is more convenient 😁

[micalevisk]

I just test this and we already has .exit (and others) due to repl package from nodejs

It didn't work as Ctrl+c tho

[micalevisk]

I have three suggestions that I believe could improve DX:

1. Allow consumers to supply their own class that extends the ReplContext one, instead of hard-coding new ReplContext(app) on repl function
2. Display help messages by calling <command>.help (or by any other means)
3. Have some way to display the built-in expressions added by NestJS. I mean, we would have to go to the docs when forgot what are the functions available and what they do (debug, methods, etc). Maybe a help() that display a list of all other functions would be enough

I've implemented both locally to demonstrate 1 and 2:

Implementation

parts of the code

// repl-context.ts
export const REPL_COMMANDS = 'repl:all-commands';

type HelpTextBuilder = (colors: typeof clc) => string;

export function ReplCommand(
  helpTextOrBuilder: string | HelpTextBuilder,
): MethodDecorator {
  return (target: Object, propertyKey: string | symbol) => {
    const commands =
      Reflect.getMetadata(REPL_COMMANDS, target.constructor) || [];
    commands.push(propertyKey);
    Reflect.defineMetadata(REPL_COMMANDS, commands, target.constructor);

    Object.defineProperty(target[propertyKey], 'helpText', {
      value:
        (typeof helpTextOrBuilder === 'string'
          ? helpTextOrBuilder
          : helpTextOrBuilder(clc)) + '\n',
      enumerable: false,
      writable: false,
      configurable: false,
    });
  };
}

// repl.ts
import { Logger, Type } from '@nestjs/common';
import * as _repl from 'repl';
import { NestFactory } from '../nest-factory';
import { REPL_INITIALIZED_MESSAGE } from './constants';
import { ReplContext, REPL_COMMANDS } from './repl-context';
import { ReplLogger } from './repl-logger';

interface ReplOptions {
  Context?: Type<ReplContext>;
}

export async function repl(
  module: Type,
  replOptions?: ReplOptions = {},
) {
  const app = await NestFactory.create(module, {
    abortOnError: false,
    logger: new ReplLogger(),
  });
  await app.init();

  const Context = replOptions.Context || ReplContext;
  const replContext = new Context(app);
  Logger.log(REPL_INITIALIZED_MESSAGE);

  const replServer = _repl.start({
    prompt: '\x1b[32m>\x1b[0m ',
    ignoreUndefined: true,
  });

  const commands: string[] = Reflect.getMetadata(REPL_COMMANDS, Context) || [];
  commands.forEach(command => {
    if (!replContext[command]) return;

    replServer.context[command] = replContext[command].bind(replContext);

    Object.defineProperty(replServer.context[command], 'help', {
      get: () => replContext.writeToStdout(replContext[command].helpText),
      enumerable: false,
      configurable: false,
    });
  });

  return replServer;
}

demo.mp4

[kamilmysliwiec]

@micalevisk feel free to create a PR that's targeting this PR :)

[micalevisk]

@kamilmysliwiec I guess we can postpone those suggestions as they won't break the current behavior (and could be trickier to write tests).

[kamilmysliwiec]

@micalevisk I don't plan to merge it earlier than ~mid-June anyway so feel free to create a PR whenever you're ready!

[micalevisk]

why renaming globalThis to globalRef here but not in the introspectCollection method? 🤔

[kamilmysliwiec]

this might be a leftover I forgot to remove

[delucca]

Amazing feature! Looking forward to use it 🚀

Just left minor comments regarding some typos :)

[delucca]

I think there is a minor typo here 😄

Suggested change

	export * from './get-relp-fn';
	export * from './get-repl-fn';

[micalevisk]

yeah, my bad. I fixed them in #9720

[delucca]

(related to file): There is a minor typo in the file name. It should be get-repl-fn.ts

[kamilmysliwiec]

@micalevisk would you like to start working on a PR to the docs (for this feature)? Preferably in Recipes category :) I can pick it up later on if needed!