Add dynamic routing

[BrunnerLivio]

I'm submitting a...

[ ] Regression 
[ ] Bug report
[x] Feature request
[ ] Documentation issue or request
[ ] Support request => Please do not submit support request here, instead post your question on Stack Overflow.

Current behavior

At the moment there is no way to register a route dynamically except by using the internal HTTP / Fastify / Express instance (related #124):

const expressInstance = express();
expressInstance.use(morgan('dev'));
const app = NestFactory.create(ApplicationModule, expressInstance);
expressInstance.get('/foo', function (req, res) {
    res.send('bar');
})

The problem with this approach is, Nest does internally not recognize this route. Therefore it will not show up in the e.g. swagger integration.

Expected behavior

I wish to have a dynamic router as part of the public Nest API, or at least a way to tell Nest to use an external route inside its router registry.

What is the motivation / use case for changing the behavior?

nestjs/terminus routes do not get registered because it directly modifies the HTTP instance. Therefore there is no Swagger integration or compatibility with middleware.

Related: nest/terminus#32 nest/terminus#33

other integrations such as @zMotivat0r for example uses this rather "hacky" workaround (sorry :P):
https://github.com/nestjsx/crud/blob/e255120b26dd8ca0eae9c7ec9dac4f893051f447/src/crud.module.ts#L5-L15
or nest-router by @shekohex uses what I would consider the internal API:

https://github.com/shekohex/nest-router/blob/3759c688b285792d7889b52f75fffb0e86d4dd54/src/router.module.ts#L53-L56

Environment

Nest version: 5.x.x

 
For Tooling issues:
- Node version: XX  
- Platform:  

Others:

[kamilmysliwiec]

What exactly would you like to see in the Nest core actually? Do you have any proposals on how the API could potentially look like? Just to clarify, I fully understand the use-case :)

[BrunnerLivio]

@kamilmysliwiec Maybe something like this?

const appRoutes: Routes = [
  { 
    path: 'hero',
    method: RequestMethod.POST,
    use: (heroService: HeroService) => heroService.getAll(),
    inject: [HeroService],
    // This option would ignore the `use` option.
    // What it basically does is telling Nest that the 'hero'-path 
    // is registered in the underyling httpServer.
    callThrough: true  
  },
];

@Module({
  imports: [
    RouterModule.forRoot(
      appRoutes,
      {enableTracing: true} // Future possibilities :)
    )
  ],
  ...
})

In general we should thrive for implementing every feature which is accessible through decorators, also a dynamic approach, as shown in this example. As you know, decorators are cool for clean code, but they lack in extensibility (I think you mentioned something similar in a past issue about Java Spring)

[shekohex]

Hi @BrunnerLivio
i would agree with you about the issue of external package sometimes have some sort of * cough cough * poor integration with each others, as an example you mentioned the swagger pkg, btw the first issue in nest-router was Swagger integration nestjsx/nest-router#3 , so your API is nice

const appRoutes: Routes = [
  { 
    path: 'hero',
    method: RequestMethod.POST,
    use: (heroService: HeroService) => heroService.getAll(),
    inject: [HeroService],
    // This option would ignore the `use` option.
    // What it basically does is telling Nest that the 'hero'-path 
    // is registered in the underyling httpServer.
    callThrough: true  
  },
];

@Module({
  imports: [
    RouterModule.forRoot(
      appRoutes,
      {enableTracing: true} // Future possibilities :)
    )
  ],
  ...
})

so do you think we actually need that in the core ?

oh, i think nest router package can do something like that !
it's already have a full access to the module containers, so we can get a ref to any service from any module.
https://github.com/shekohex/nest-router/blob/3759c688b285792d7889b52f75fffb0e86d4dd54/src/router.module.ts#L17

so what do you think ?
but since nest-router was created in first place to solve other problem, nesting routes see nestjsx/nest-router#43 is that possible ?
anyway i could help in either way here in the core or externally in another pkg or in nest-router itself 😄

[BrunnerLivio]

@shekohex thanks a lot for your answer!

so do you think we actually need that in the core ?

I guess it should atleast be at the same place where the routing is handled, therefore nestjs/core I guess?

In my opinion the functionality of your router or similar should be part of the framework. As already hinted at I would like to see every decorator functionality also as non-decorator configurable option. Therefore a public API of the router would be quite handy!

[shekohex]

ok, we can work on that

my opinion the functionality of your router or similar should be part of the framework.

Yeah, that was a long opened issue/discussion in nest-router see nestjsx/nest-router#19 it's about year ago !

i think we can do better, what about that, since most of the users who will use this api most of them will be 3rd party lib creators, we can make it even lower level api, instead of use: (someService: SomeService) => someService.someMethod(),, we give them a reference to the underlying module container itself, or an express-like (req, res, next, container) => {...} function api.

the reason of that, it would make it easier to anyone want to have a full control over the underlying router.
there is a lot of options there, but really i would love the idea of

to see every decorator functionality also as non-decorator configurable option

since i love to use nest in functional manner.

i know i know that nest built around a lot of concepts like DI, IoC, Modules ...etc, but really i love to use nest with just only functions.

[BrunnerLivio]

instead of use: (someService: SomeService) => someService.someMethod(),, we give them a reference to the underlying module container itself, or an express-like (req, res, next, container) => {...} function api.

Great input!

New Proposal

Router Module in @nest/core

// Route interfaces
interface RouteRegister {
  path: string;
  method?: RequestMethod;
}

interface RouteUse {
  use: (req: any, res: any, next: Function, container: any) => Promise<any> | any;
}

interface RouteCallThrough {
  callThrough?: boolean;
}

type RouteWithCallThrough = RouteRegister & RouteCallThrough & { callThrough: true };
type RouteWithUse = RouteRegister & RouteUse & { callThrough?: false | undefined | null };

type Route = RouteWithCallThrough | RouteWithUse;

// Module interfaces
interface RouterModuleOptions {
  routes: Route[];
  enableTracing?: boolean;
}

interface RouterOptionsFactory {
  createRouterOptions():
    | Promise<RouterModuleOptions>
    | RouterModuleOptions;
}

interface RouterModuleAsyncOptions
  extends Pick<ModuleMetadata, 'imports'> {
  name?: string;
  useClass?: Type<RouterOptionsFactory>;
  useExisting?: Type<RouterOptionsFactory>;
  useFactory?: (
    ...args: unknown[]
  ) => Promise<RouterModuleOptions> | RouterModuleOptions;
  inject?: unknown[];
}


// Router module implementation
export class RouterModule {
  static forRoot(options: RouterModuleOptions): DynamicModule {
    // Todo: Implement
    return {
      module: RouterModule,
    };
  }
  static forRootAsync(options: RouterModuleAsyncOptions): DynamicModule {
    // Todo: Implement
    return {
      module: RouterModule
    }
  }
}

Usage Synchonous

const routes: Route[] = [
  {
    path: '/underlying-route',
    method: RequestMethod.GET,
    callThrough: true,
  },
  {
    path: '/new-route',
    method: RequestMethod.GET,
    use: (req, res, next, container) => 'test',
  }
];

@Module({
  imports: [
    RouterModule.forRoot({
      routes,
      enableTracing: true
    }),
  ],
})
class AppRoutes { }

Usage Asynchronous

class RouterModuleFactory implements RouterOptionsFactory {
  constructor(private heroController: HeroController) { }
  createRouterOptions(): RouterModuleOptions {
    return {
      routes: [
        {
          path: '/new-route2',
          use: (req, res) => this.heroController.get(req, res),
        }
      ]
    }
  }
}

@Module({
  imports: [
    RouterModule.forRootAsync({
      useClass: RouterModuleFactory,
      inject: [HeroController]
    })
  ],
})
class AppRoutes { }

Disclaimer

The interface Route is kind of complicated. This is due to; if the user uses callThrough: true he mustn't use use. If callThrough: false or undefined the user can use use. Therefore the following would not be possible:

const routes = Route[] = [
  { path: '/test', callThrough: true, use: () => 'test' } // ERROR
]

@kamilmysliwiec @shekohex what do you think? :)

[marcus-sa]

use doesn't seem descriptive for what it does.
And that's still not a dynamic API as you can only add routes inside decorators.
You should be able to import the container in an injectable and add a route from there as well.

[BrunnerLivio]

@marcus-sa thanks for the feedback.

use doesn't seem descriptive for what it does.

I've used use because Express uses app.use too for middleware definitions

And that's still not a dynamic API as you can only add routes inside decorators.
You should be able to import the container in an injectable and add a route from there as well.

I see your point. Maybe an additional RouterService would do the trick? I would still keep the RouterModule though because it is a nice way to define routes at one central point, similar to Angular router. RouterService could then be an exported provider from RouterModule.

RouterModule is still pretty dynamic, because you can import providers using forRootAsync - but in some situations injecting a RouterService is just more convenient. Question is; should we support both? This could maybe raise inconsistencies into a users app if he/she starts using RouterModule, RouterService and @Controller() at the same time.

[marcus-sa]

@BrunnerLivio yes, but use is an inconsistent name in MAF's (module architecture framework) as by usage it's actually a FactoryProvider, so it should be useFactory instead for naming consistency within the entire Nest framework :)

[BrunnerLivio]

@marcus-sa I thought about that too, but it is not actually a factory, its a router handle. On top of that the way I proposed you can not inject anything into the use function, you would have to use the moduleContainer parameter which is given to the use function, or forRootAsync on the RouterModule. So the functionality differs from useFactory. But I agree that use could be misleading, so I am open for a better name. Maybe useHandler or handler?

[marcus-sa]

@BrunnerLivio yeah I just noticed that too and was about to propose the same useHandler or handler in the beginning

[shekohex]

That's pretty good api, it's actually similar to the nest-router module API.

should we support both? This could maybe raise inconsistencies into a users app if he/she starts using RouterModule, RouterService and @Controller() at the same time.

yup, if we need to make things dynamic and in the same time easy to use, we should also support RouterService.

This could maybe raise inconsistencies...

well, that's a good question here, but i really can't imagine that issue, since we will make nest knows all the routes either they are registered form RouterModule or using @Controller(..), or maybe better, if the user used callThrough for example, nest also should know that we have that route, which is the idea of this issue in 1st place.

I am open for a better name. Maybe useHandler or handler?

useHandler 👍