Skip to main content

Router

@webda/core


Class: Router<T>

Defined in: packages/core/src/rest/router.service.ts:239

Manage Route resolution

Webda Modda​

Extends​

Type Parameters​

T​

T extends RouterParameters = RouterParameters

Implements​

Constructors​

Constructor​

new Router<T>(name, params): Router<T>

Defined in: packages/core/src/services/service.ts:205

Create a new Service instance

Service

Parameters​

name​

string

The name of the service

params​

T

The parameters block define in the configuration file

Returns​

Router<T>

Inherited from​

Service.constructor

Properties​

_compiledCapabilities​

protected _compiledCapabilities: Record<string, any> = {}

Defined in: packages/core/src/services/iservice.ts:61

Capabilities detected at compile-time from @WebdaCapability-tagged interfaces.

Populated during Service.resolve by reading the service's entry in webda.module.json. Each key is a capability name (e.g., "request-filter"), and the value is an empty object {} by default. Override getCapabilities to provide capability-specific configuration or to conditionally disable capabilities.

See​

getCapabilities

Inherited from​

Service._compiledCapabilities


[WEBDA_EVENTS]​

[WEBDA_EVENTS]: object

Defined in: packages/core/src/services/service.ts:179

Set the Webda events here

Inherited from​

Service.[WEBDA_EVENTS]


aliases​

protected aliases: Record<string, RouteAliasDefinition> = {}

Defined in: packages/core/src/rest/router.service.ts:255

Route aliases configuration


aliasMap​

protected aliasMap: CompiledAlias[] = []

Defined in: packages/core/src/rest/router.service.ts:259

Compiled route aliases


logger​

protected logger: Logger

Defined in: packages/core/src/services/service.ts:192

Logger with class context

Inherited from​

Service.logger


metrics?​

protected optional metrics?: object

Defined in: packages/core/src/services/service.ts:196

Get metrics

Inherited from​

Service.metrics


models​

protected models: Map<string, string>

Defined in: packages/core/src/rest/router.service.ts:251

Models


name​

readonly name: string

Defined in: packages/core/src/services/iservice.ts:35

Name

Inherited from​

Service.name


parameters​

readonly parameters: T

Defined in: packages/core/src/services/iservice.ts:39

Parameters

Inherited from​

Service.parameters


pathMap​

protected pathMap: object[]

Defined in: packages/core/src/rest/router.service.ts:247

Path map

config​

config: RouteInfo

url​

url: string


remapNeeded​

protected remapNeeded: boolean = false

Defined in: packages/core/src/rest/router.service.ts:266

Routes changed since they were last mapped

Mapping compiles and sorts every route, so a route added or removed only flags it and the next lookup maps them once


routes​

protected routes: Map<string, RouteInfo[]>

Defined in: packages/core/src/rest/router.service.ts:243

Routes


createConfiguration?​

static optional createConfiguration?: (params) => any

Defined in: packages/core/src/services/iservice.ts:44

Create configuration set by the application on load

Parameters​

params​

any

Returns​

any

Inherited from​

Service.createConfiguration


filterConfiguration?​

static optional filterConfiguration?: (params) => any

Defined in: packages/core/src/services/iservice.ts:49

Create configuration set by the application on load

Parameters​

params​

any

Returns​

any

Inherited from​

Service.filterConfiguration


Parameters​

static Parameters: typeof ServiceParameters = ServiceParameters

Defined in: packages/core/src/services/service.ts:175

Service parameters

Inherited from​

Service.Parameters

Methods​

__clean()​

abstract __clean(): Promise<void>

Defined in: packages/core/src/services/service.ts:539

Clean the service data, can only be used in test mode

Returns​

Promise<void>

Inherited from​

Service.__clean


addAlias()​

addAlias(url, def): void

Defined in: packages/core/src/rest/router.service.ts:433

Add a route alias dynamically

Parameters​

url​

string

the alias URL pattern

def​

string | RouteAliasDefinition

target URL or RouteAliasDefinition

Returns​

void

Implementation of​

IRouter.addAlias


addCorsAllowedHeaders()​

addCorsAllowedHeaders(...names): void

Defined in: packages/core/src/rest/router.service.ts:1215

Allow additional request headers on cross-origin requests

They are listed in Access-Control-Allow-Headers of the preflight response

Parameters​

names​

...string[]

header names to allow (already allowed ones are ignored)

Returns​

void


addListener()​

addListener<Key>(eventName, listener): this

Defined in: packages/core/src/events/asynceventemitter.ts:90

Add listener

Type Parameters​

Key​

Key extends never

Parameters​

eventName​

Key

the event name

listener​

(event) => void | Promise<void>

the event listener

Returns​

this

this for chaining

See​

EventEmitter.addListener

Inherited from​

Service.addListener


addRoute()​

protected addRoute(url, methods, executer, openapi?, override?): void

Defined in: packages/core/src/services/service.ts:400

Add a route dynamicaly

Parameters​

url​

string

of the route can contains dynamic part like {uuid}

methods​

HttpMethodType[]

the HTTP methods

executer​

Function

Method to execute for this route

openapi?​

OpenAPIWebdaDefinition = {}

the OpenAPI specification

override?​

boolean = false

whether to override existing

Returns​

void

Inherited from​

Service.addRoute


addRouteToRouter()​

addRouteToRouter(url, info): void

Defined in: packages/core/src/rest/router.service.ts:375

Add a route dynamicaly

Parameters​

url​

string

of the route can contains dynamic part like {uuid}

info​

RouteInfo

the type of executor

Returns​

void


addVary()​

protected addVary(ctx, value): void

Defined in: packages/core/src/rest/router.service.ts:1263

Add a value to the Vary response header, keeping the existing ones

Note: a later setHeader("Vary", ...) replaces the whole value, the context has no hook to prevent it

Parameters​

ctx​

IWebContext

the operation context

value​

string

the header name to vary on

Returns​

void


authorizeClientEvent()​

authorizeClientEvent(_event, _context): boolean

Defined in: packages/core/src/services/service.ts:353

Authorize a public event subscription

Parameters​

_event​

string

the event name

_context​

OperationContext

the execution context

Returns​

boolean

true if the condition is met

Inherited from​

Service.authorizeClientEvent


checkCORSRequest()​

protected checkCORSRequest(ctx): Promise<boolean>

Defined in: packages/core/src/rest/router.service.ts:1274

Verify if an origin is allowed to do request on the API

Parameters​

ctx​

IWebContext

the operation context

Returns​

Promise<boolean>

true if the condition is met


checkRequest()​

checkRequest(ctx): Promise<boolean>

Defined in: packages/core/src/rest/router.service.ts:1189

Verify if a request can be done

Parameters​

ctx​

IWebContext

the operation context

Returns​

Promise<boolean>

true if the condition is met


comparePath()​

protected comparePath(a, b): number

Defined in: packages/core/src/rest/router.service.ts:542

Compare two route paths for sorting, prioritizing literal segments over parameters

Parameters​

a​

any

the first route

b​

any

the second route

Returns​

number

the result number


compileTemplate()​

protected compileTemplate(url): Pick<RouteInfo, "_uriTemplateParse" | "_queryParams" | "_queryCatchAll">

Defined in: packages/core/src/rest/router.service.ts:562

Compile a URI template with optional query parameter handling

Parameters​

url​

string

the URL pattern

Returns​

Pick<RouteInfo, "_uriTemplateParse" | "_queryParams" | "_queryCatchAll">

compiled template parser and query param definitions


completeOpenAPI()​

completeOpenAPI(openapi, skipHidden?): void

Defined in: packages/core/src/rest/router.service.ts:860

Add all known routes to paths

Parameters​

openapi​

Document

to complete

skipHidden?​

boolean = true

add hidden routes or not

Returns​

void


computeParameters()​

computeParameters(): void

Defined in: packages/core/src/services/service.ts:214

Used to compute or derivate input parameter to attribute

Returns​

void

Deprecated​

Inherited from​

Service.computeParameters


discoverFilters()​

discoverFilters(services): void

Defined in: packages/core/src/rest/router.service.ts:1458

Auto-discover services that declare request-filter or cors-filter capabilities and register them with the Router.

Called during framework initialization (after all services are resolved and initialized) to replace manual registerRequestFilter(this) calls. Iterates all services, checks their Service.getCapabilities return value, and registers matching services as request or CORS filters.

Parameters​

services​

Iterable<Service<ServiceParameters, { }>>

Iterable of initialized services to scan for filter capabilities

Returns​

void

Example​

// Called automatically by Core.init():
router.discoverFilters(Object.values(this.services));

// A service with "request-filter" capability is auto-registered:
class HawkService extends Service implements RequestFilter {
// getCapabilities() returns { "request-filter": {}, "cors-filter": {} }
// → automatically registered with router as both request and CORS filter
}

Implementation of​

IRouter.discoverFilters


discoverRoutes()​

discoverRoutes(services): void

Defined in: packages/core/src/rest/router.service.ts:1480

Auto-discover routes declared with @Route (or the legacy constructor.routes bucket) on each service, and register them with the router. Called once from Core.init() after all services have resolved — services don't have to push their own routes anymore.

Parameters​

services​

Iterable<Service<ServiceParameters, { }>>

iterable of initialized services to scan

Returns​

void

Implementation of​

IRouter.discoverRoutes


emit()​

emit<Key>(event, data): Promise<void>

Defined in: packages/core/src/services/service.ts:520

Emit the event with data and wait for Promise to finish if listener returned a Promise

Type Parameters​

Key​

Key extends never

Parameters​

event​

Key

the event name

data​

object[Key]

the data to process

Returns​

Promise<void>

Inherited from​

Service.emit


ensureMapped()​

protected ensureMapped(): void

Defined in: packages/core/src/rest/router.service.ts:530

Map the routes if they changed since the last mapping

Returns​

void


execute()​

execute(ctx): Promise<void>

Defined in: packages/core/src/rest/router.service.ts:1094

Execute the matched route handler for a web context

Parameters​

ctx​

WebContext<any, any, any>

the operation context

Returns​

Promise<void>

Implementation of​

IRouter.execute


exportOpenAPI()​

exportOpenAPI(skipHidden?): Document

Defined in: packages/core/src/rest/router.service.ts:1308

Export OpenAPI

Parameters​

skipHidden?​

boolean = true

whether to skip hidden entries

Returns​

Document

the result

Implementation of​

IRouter.exportOpenAPI


getAliases()​

getAliases(): Record<string, RouteAliasDefinition>

Defined in: packages/core/src/rest/router.service.ts:460

Return all registered route aliases

Returns​

Record<string, RouteAliasDefinition>

map of alias URLs to definitions

Implementation of​

IRouter.getAliases


getCapabilities()​

getCapabilities(): Record<string, any>

Defined in: packages/core/src/services/iservice.ts:89

Return the capabilities of this service.

By default returns capabilities detected at compile-time from

Returns​

Record<string, any>

the result

Webda Capability-tagged​

interfaces in webda.module.json.

Override to disable capabilities based on configuration:

getCapabilities() {
const caps = super.getCapabilities();
if (!this.parameters.enabled) delete caps["request-filter"];
return caps;
}

Inherited from​

Service.getCapabilities


getClientEvents()​

getClientEvents(): string[]

Defined in: packages/core/src/services/service.ts:341

Return the events that an external system can subscribe to

Returns​

string[]

the list of results

Inherited from​

Service.getClientEvents


getCorsAllowedHeaders()​

getCorsAllowedHeaders(): string[]

Defined in: packages/core/src/rest/router.service.ts:1227

Get the request headers allowed on cross-origin requests

Returns​

string[]

a copy of the allowed header names


getFinalUrl()​

getFinalUrl(url): string

Defined in: packages/core/src/rest/router.service.ts:342

Include prefix to the url if not present

Parameters​

url​

string

the URL

Returns​

string

the result string


getMatchTarget()​

protected getMatchTarget(routeUrl, finalUrl): string

Defined in: packages/core/src/rest/router.service.ts:639

What a request URL is matched against for a route: a route declaring a query template ({?q,page?}, {?rest*}) matches the whole URL, any other route matches the path alone, so an extra query string (?v=123) neither prevents the match nor ends up in a path variable

Parameters​

routeUrl​

string

the route URL

finalUrl​

string

the request URL, from getFinalUrl

Returns​

string

the URL to match


getMaxListeners()​

getMaxListeners(): number

Defined in: packages/core/src/events/asynceventemitter.ts:97

Returns​

number

Inherited from​

Service.getMaxListeners


getMetric()​

getMetric<T>(type, configuration): T

Defined in: packages/core/src/services/service.ts:323

Add service name label

Type Parameters​

T​

T = Gauge<string> | Counter<string> | Histogram<string>

Parameters​

type​

CustomConstructor<T, [MetricConfiguration<T>]>

the type to look up

configuration​

MetricConfiguration<T>

the configuration

Returns​

T

the result

Inherited from​

Service.getMetric


getModelUrl()​

getModelUrl(model): string

Defined in: packages/core/src/rest/router.service.ts:330

Return the route for model

Parameters​

model​

string | Storable<any, any>

the model to use

Returns​

string

the result


getName()​

getName(): string

Defined in: packages/core/src/services/service.ts:530

Get service name

Returns​

string

the result string

Inherited from​

Service.getName


getOpenApiReplacements()​

getOpenApiReplacements(): any

Defined in: packages/core/src/services/service.ts:429

Return variables for replacement in openapi

Returns​

any

the result

Inherited from​

Service.getOpenApiReplacements


getOpenAPISchema()​

protected getOpenAPISchema(schema): any

Defined in: packages/core/src/rest/router.service.ts:842

Convert a schema name or object to an OpenAPI $ref or inline schema

Parameters​

schema​

any

the schema object

Returns​

any

the result


getOperationId()​

getOperationId(id): string

Defined in: packages/core/src/services/service.ts:387

If undefined is returned it cancel the operation registration

Parameters​

id​

string

the identifier

Returns​

string

the result

Inherited from​

Service.getOperationId


getParameters()​

getParameters(): T

Defined in: packages/core/src/services/service.ts:222

Get the service parameters

Returns​

T

the result

Inherited from​

Service.getParameters


getRouteFromUrl()​

getRouteFromUrl(ctx, method, url): RouteInfo

Defined in: packages/core/src/rest/router.service.ts:814

Get the route from a method / url

Parameters​

ctx​

IWebContext

the operation context

method​

HttpMethodType

the HTTP method

url​

string

the URL

Returns​

RouteInfo

the result


getRouteMethodsFromUrl()​

getRouteMethodsFromUrl(url): HttpMethodType[]

Defined in: packages/core/src/rest/router.service.ts:752

Get all method for a specific url

Parameters​

url​

any

the URL

Returns​

HttpMethodType[]

the list of results


getRoutes()​

getRoutes(): Map<string, RouteInfo[]>

Defined in: packages/core/src/rest/router.service.ts:365

Return routes

Returns​

Map<string, RouteInfo[]>

the result


getService()​

getService<T>(name): ServicesMap[T]

Defined in: packages/core/src/services/service.ts:313

Get a service by name

Type Parameters​

T​

T extends keyof ServicesMap

Parameters​

name​

T

the name to use

Returns​

ServicesMap[T]

the result map

Deprecated​

Use useService, might reconsider

Inherited from​

Service.getService


getState()​

getState(): ServiceStates

Defined in: packages/core/src/services/service.ts:185

Get the current state

Returns​

ServiceStates

the result

Inherited from​

Service.getState


getUrl()​

getUrl(url, _methods): string

Defined in: packages/core/src/services/service.ts:364

Return the full path url based on parameters

Parameters​

url​

string

relative url to service

_methods​

HttpMethodType[]

in case we need filtering (like Store)

Returns​

string

absolute url or undefined if need to skip the Route

Inherited from​

Service.getUrl


init()​

abstract init(): Promise<Router<T>>

Defined in: packages/core/src/services/service.ts:510

Will be called after all the Services are created

Returns​

Promise<Router<T>>

Inherited from​

Service.init


initMetrics()​

initMetrics(): void

Defined in: packages/core/src/services/service.ts:303

Init the metrics

Returns​

void

Inherited from​

Service.initMetrics


initOperations()​

initOperations(): void

Defined in: packages/core/src/services/service.ts:459

Init the operations from

Returns​

void

Operation​

decorators on this service

Inherited from​

Service.initOperations


listeners()​

listeners(eventName): Function[]

Defined in: packages/core/src/events/asynceventemitter.ts:195

Get all listeners for an event

Parameters​

eventName​

never

the event name

Returns​

Function[]

the list of results

Inherited from​

Service.listeners


loadCapabilities()​

protected loadCapabilities(): void

Defined in: packages/core/src/services/service.ts:283

Load capabilities from webda.module.json metadata into _compiledCapabilities.

Called during resolve after dependency injection. Reads the service's type name from parameters, looks it up in the application's module metadata (moddas or beans section), and populates _compiledCapabilities with an empty object for each declared capability name.

Fails silently if the application is not available (e.g., in unit tests where services are instantiated without a full application context).

Returns​

void

Example​

// If webda.module.json contains:
// { "moddas": { "MyApp/HawkService": { "capabilities": ["request-filter", "cors-filter"] } } }
// Then after resolve(), this.getCapabilities() returns:
// { "request-filter": {}, "cors-filter": {} }

See​

getCapabilities

Inherited from​

Service.loadCapabilities


log()​

log(level, ...args): void

Defined in: packages/core/src/services/service.ts:561

Log operation

Parameters​

level​

WorkerLogLevel

to log

args​

...any[]

additional arguments

Returns​

void

Inherited from​

Service.log


mapRoutes()​

protected mapRoutes(): void

Defined in: packages/core/src/rest/router.service.ts:498

Compile the URI templates of all routes and sort them by priority

Returns​

void


matchTemplate()​

protected matchTemplate(entry, routeUrl, finalUrl): Record<string, any>

Defined in: packages/core/src/rest/router.service.ts:650

Match a URL against an entry (route or alias)

Parameters​

entry​

TemplateMatchEntry

route or alias info

routeUrl​

string

the route or alias URL template

finalUrl​

string

the incoming request URL

Returns​

Record<string, any>

extracted parameters map, or undefined if no match


mergeHeaderNames()​

mergeHeaderNames(current, added): string

Defined in: packages/core/src/rest/router.service.ts:1248

Merge header names case-insensitively, keeping the first spelling

Parameters​

current​

string

comma separated header names

added​

string[]

names to add

Returns​

string

comma separated header names


off()​

off<Key>(eventName, listener): this

Defined in: packages/core/src/events/asynceventemitter.ts:152

Perform off

Type Parameters​

Key​

Key extends never

Parameters​

eventName​

Key

the event name

listener​

(event) => void

the event listener

Returns​

this

this for chaining

See​

EventEmitter.off

Inherited from​

Service.off


on()​

on<Key>(eventName, listener): this

Defined in: packages/core/src/events/asynceventemitter.ts:128

Perform on

Type Parameters​

Key​

Key extends never

Parameters​

eventName​

Key

the event name

listener​

(event) => void

the event listener

Returns​

this

this for chaining

See​

EventEmitter.once

Inherited from​

Service.on


once()​

once<Key>(eventName, listener): this

Defined in: packages/core/src/events/asynceventemitter.ts:116

Perform once

Type Parameters​

Key​

Key extends never

Parameters​

eventName​

Key

the event name

listener​

(event) => void

the event listener

Returns​

this

this for chaining

See​

EventEmitter.once

Inherited from​

Service.once


openapi()​

openapi(output?, includeHidden?): void

Defined in: packages/core/src/rest/router.service.ts:1284

Export the OpenAPI definition as JSON to stdout

Parameters​

output?​

string

file path to write to (prints to stdout if omitted)

includeHidden?​

boolean

include hidden routes in the output

Returns​

void


operationSchemaName()​

protected operationSchemaName(method, side): string

Defined in: packages/core/src/services/service.ts:441

Schema of an operation side: <service name>.<method>.<side> when the application knows it, else the one the build writes, <class>.<method>.<side>, for the class or its nearest ancestor that has it (a service configured under another name than its class)

Parameters​

method​

string

the method name

side​

"input" | "output"

input or output

Returns​

string

the schema name

Inherited from​

Service.operationSchemaName


registerCORSFilter()​

registerCORSFilter(filter): void

Defined in: packages/core/src/rest/router.service.ts:1431

Register a CORS request filtering

Does not apply in devMode

Parameters​

filter​

CORSFilter

the filter to apply

Returns​

void

Implementation of​

IRouter.registerCORSFilter


registerModelUrl()​

registerModelUrl(model, url): void

Defined in: packages/core/src/rest/router.service.ts:285

Registration of a model

Parameters​

model​

string

the model to use

url​

string

the URL

Returns​

void

Implementation of​

IRouter.registerModelUrl


registerRequestFilter()​

registerRequestFilter(filter): void

Defined in: packages/core/src/rest/router.service.ts:1421

Register a request filtering

Will apply to all requests regardless of the devMode

Parameters​

filter​

RequestFilter

the filter to apply

Returns​

void

Implementation of​

IRouter.registerRequestFilter


remapRoutes()​

remapRoutes(): void

Defined in: packages/core/src/rest/router.service.ts:470

Reinit all routes and aliases

It will readd the URITemplates if needed Sort all routes and aliases again

Returns​

void


removeAlias()​

removeAlias(url): void

Defined in: packages/core/src/rest/router.service.ts:448

Remove a route alias dynamically

Parameters​

url​

string

the alias URL pattern to remove

Returns​

void

Implementation of​

IRouter.removeAlias


removeAllListeners()​

removeAllListeners<Key>(eventName?): this

Defined in: packages/core/src/events/asynceventemitter.ts:162

Remove all listeners

Type Parameters​

Key​

Key extends never

Parameters​

eventName?​

Key

the event name

Returns​

this

this for chaining

See​

EventEmitter.removeAllListeners

Inherited from​

Service.removeAllListeners


removeListener()​

removeListener<Key>(eventName, listener): this

Defined in: packages/core/src/events/asynceventemitter.ts:140

Remove listener

Type Parameters​

Key​

Key extends never

Parameters​

eventName​

Key

the event name

listener​

(event) => void

the event listener

Returns​

this

this for chaining

See​

EventEmitter.removeListener

Inherited from​

Service.removeListener


removeRoute()​

removeRoute(url, info?): void

Defined in: packages/core/src/rest/router.service.ts:416

Remove a route dynamicly

Parameters​

url​

string

to remove

info?​

RouteInfo = undefined

the information object

Returns​

void


resolve()​

resolve(): Router<T>

Defined in: packages/core/src/rest/router.service.ts:301

Resolve dependencies and wire up core lifecycle listeners.

The Router pulls its inputs from events rather than being driven by Core.init() directly:

  • Webda.Init.Services — scan every resolved service for @Route metadata and filter capabilities.
  • Webda.Init — finalize the URI template index after all routes (dynamic or decorator-based) have been registered.

Returns​

Router<T>

the result

Overrides​

Service.resolve


resolveAlias()​

resolveAlias(ctx, method, url): object

Defined in: packages/core/src/rest/router.service.ts:706

Resolve an incoming URL against route aliases

Parameters​

ctx​

IWebContext

the operation context

method​

HttpMethodType

the HTTP method

url​

string

the URL to resolve (relative to prefix)

Returns​

object

resolved alias target and metadata, or undefined

alias​

alias: string

mode​

mode: RouteAliasMode

redirectCode?​

optional redirectCode?: number

url​

url: string

Implementation of​

IRouter.resolveAlias


setCorsHeaders()​

protected setCorsHeaders(ctx): void

Defined in: packages/core/src/rest/router.service.ts:1237

Set the CORS response headers for a request whose Origin was accepted

The origin is always echoed (never *) as credentials are allowed

Parameters​

ctx​

IWebContext

the operation context

Returns​

void


setMaxListeners()​

setMaxListeners(n): this

Defined in: packages/core/src/events/asynceventemitter.ts:104

Parameters​

n​

number

Returns​

this

Inherited from​

Service.setMaxListeners


stop()​

stop(): Promise<void>

Defined in: packages/core/src/services/service.ts:230

Shutdown the current service if action need to be taken

Returns​

Promise<void>

Inherited from​

Service.stop


toJSON()​

toJSON(): string

Defined in: packages/core/src/services/service.ts:499

Prevent service to be serialized

Returns​

string

the result

Inherited from​

Service.toJSON


toString()​

toString(): string

Defined in: packages/core/src/services/service.ts:238

Return service representation

Returns​

string

the result

Inherited from​

Service.toString


writeNotFound()​

protected writeNotFound(ctx, method, url): void

Defined in: packages/core/src/rest/router.service.ts:1176

Answer a request no route matches: 404 with the same error body a thrown NotFound gets, so clients don't receive an empty response

Parameters​

ctx​

WebContext<any, any, any>

the web context

method​

string

the HTTP method

url​

string

the requested URL

Returns​

void