Routes

Routes are just functions, the first parameter is always the Call Context, the rest of parameters are remote parameters that get deserialized and validated before the route gets executed

There are no Urls or Paths when defining a route. The entire API is defined using a plain javascript object, where every entry of the object is a route or hook. This way we simplify referencing the routes directly from the client.

Internally an Url is generated for each route so these can be referenced using regular http requests, but all this complexity is managed transparently by the client.

Defining a Route

Routes can be defined using a single function Handler or a RouteDef object in case we need to customize the behavior (metadata) of a route.

Quick Tip:
Never assign a type to Routes/Hooks, instead always use the satisfies operator! .
import {RouteDef, Routes} from '@mionkit/router';

// Defining a route as simple function
const sayHello = (ctx, name: string): string => {
    return `Hello ${name}.`;
}; // Satisfies Route

// Using a Route Definition object
const sayHello2 = {
    enableSerialization: false,
    enableValidation: false,
    // route handler
    route(ctx, name1: string, name2: string): string {
        return `Hello ${name1} and ${name2}.`;
    },
} satisfies RouteDef;

const routes = {
    sayHello,
    sayHello2,
} satisfies Routes;

Naming Routes

keep it simple and use regular valid JS variable names for routes, It is not recommended to use the array notation (using quotes) to define route names.

When a route lookup is done there is no URL decoding done so if you define names that include especial URl encoded characters then routes won't be found.
import {Routes, registerRoutes} from '@mionkit/router';

const sayHello = (ctx, name: string): string => {
    return `Hello ${name}.`;
};

const routes = {
    'say-Hello': sayHello, // path = /say-Hello  !! NOT Recommended
    'say Hello': sayHello, // path = /say%20Hello  !! ROUTE WONT BE FOUND
} satisfies Routes;

export const apiSpec = registerRoutes(routes);

Type Reference

Handler

A Route can be a simple function Handler with the call context as first parameter.

export type Handler<Context extends CallContext = CallContext, Ret = any> = (
    /** Call Context */
    context: Context,
    /** Remote Call parameters */
    ...parameters: any
) => Ret | Promise<Ret>;

RouteDef

We can use a RouteDef object when we want to customize the default behavior of a route.

export interface RouteDef<Context extends CallContext = CallContext, Ret = any> {
    /** description of the route, mostly for documentation purposes */
    description?: string;
    /** Overrides global enableValidation */
    enableValidation?: boolean;
    /** Overrides global enableSerialization */
    enableSerialization?: boolean;
    /** Route Handler */
    route: Handler<Context, Ret>;
}
Table of Contents