@esportsplus/routing 0.6.0

package/src/client/router/index.ts

@@ -0,0 +1,294 @@
+import { ON_DELETE, ON_GET, ON_POST, ON_PUT, PACKAGE_NAME } from '../constants';
+import { Route, Name, Options, PathParamsTuple, Request, RouteOptions, RouteRegistry } from '../types';
+import { Node } from './node';
+import pipeline from '@esportsplus/pipeline';
+
+
+function key(method: string, subdomain?: string | null) {
+    return (method + (subdomain ? ' ' + subdomain : '')).toUpperCase();
+}
+
+function normalize(path: string) {
+    if (path) {
+        if (path[0] !== '/') {
+            path = '/' + path;
+        }
+
+        if (path.length > 1 && path[path.length - 1] === '/') {
+            path = path.slice(0, -1);
+        }
+    }
+
+    return path || '/';
+}
+
+function set<T>(route: Route<T>, options: Options<T> | RouteOptions<T>) {
+    let pipeline = route.pipeline;
+
+    for (let key in options) {
+        let value = options[key as keyof typeof options] as any;
+
+        if (key === 'middleware') {
+            for (let i = 0, n = value.length; i < n; i++) {
+                pipeline.add(value[i]);
+            }
+        }
+        else if (key === 'responder') {
+            pipeline.add(value);
+        }
+        else {
+            // @ts-ignore
+            route[key] = (route[key] || '') + value;
+        }
+    }
+}
+
+
+class Router<T, TRoutes extends RouteRegistry = {}> {
+    bucket: Record<ReturnType<typeof key>, { root: Node<T>, static: Record<string, Route<T>> }> = {};
+    groups: Options<T>[] = [];
+    routes: Record<Name, Route<T>> = {};
+    subdomains: string[] | null = null;
+
+
+    private add(method: string, path: string, route: Route<T>) {
+        let bucket = this.bucket[ key(method, route.subdomain) ] ??= {
+                root: new Node(),
+                static: {}
+            };
+
+        if (path.indexOf(':') === -1) {
+            if (path in bucket.static) {
+                throw new Error(`${PACKAGE_NAME}: static path '${path}' is already in use`);
+            }
+
+            bucket.static[path] = route;
+        }
+        else {
+            bucket.root.add(path, route);
+        }
+
+        return this;
+    }
+
+    private create(options: RouteOptions<T>) {
+        let groups = this.groups,
+            route: Route<T> = {
+                name: null,
+                path: null,
+                pipeline: pipeline<Request<T>, T>(),
+                subdomain: null
+            };
+
+        for (let i = 0, n = groups.length; i < n; i++) {
+            set(route, groups[i]);
+        }
+
+        set(route, options);
+
+        if (route.path) {
+            route.path = normalize(route.path);
+        }
+
+        if (route.subdomain === 'www') {
+            route.subdomain = '';
+        }
+
+        return route;
+    }
+
+
+    delete<RouteName extends string = string, RoutePath extends string = string>(
+        options: RouteOptions<T> & { name?: RouteName; path?: RoutePath }
+    ): Router<
+        T,
+        TRoutes & (
+            RouteName extends string
+                ? RoutePath extends string
+                    ? { [K in RouteName]: { path: RoutePath } }
+                    : TRoutes
+                : TRoutes
+        )
+    > {
+        this.on(ON_DELETE, options);
+        return this as any;
+    }
+
+    get<RouteName extends string = string, RoutePath extends string = string>(
+        options: RouteOptions<T> & { name?: RouteName; path?: RoutePath }
+    ): Router<
+        T,
+        TRoutes & (
+            RouteName extends string
+                ? RoutePath extends string
+                    ? { [K in RouteName]: { path: RoutePath } }
+                    : TRoutes
+                : TRoutes
+        )
+    > {
+        this.on(ON_GET, options);
+        return this as any;
+    }
+
+    group(options: Options<T>): {
+        routes: (fn: (router: Router<T, TRoutes>) => void) => Router<T, TRoutes>
+    } {
+        return {
+            routes: (fn: (router: Router<T, TRoutes>) => void) => {
+                this.groups.push(options);
+                fn(this);
+                this.groups.pop();
+                return this;
+            }
+        };
+    }
+
+    match(method: string, path: string, subdomain?: string | null) {
+        let bucket = this.bucket[ key(method, subdomain) ];
+
+        if (!bucket) {
+            return {};
+        }
+
+        path = normalize(path);
+
+        if (path in bucket.static) {
+            return { route: bucket.static[path] };
+        }
+
+        return bucket.root.find(path);
+    }
+
+    on<RouteName extends string = string, RoutePath extends string = string>(
+        methods: string[],
+        options: RouteOptions<T> & { name?: RouteName; path?: RoutePath }
+    ): Router<
+        T,
+        TRoutes & (
+            RouteName extends string
+                ? RoutePath extends string
+                    ? { [K in RouteName]: { path: RoutePath } }
+                    : TRoutes
+                : TRoutes
+        )
+    > {
+        let route = this.create(options);
+
+        let name = route.name,
+            path = route.path,
+            subdomain = route.subdomain;
+
+        if (name) {
+            if (this.routes[name]) {
+                throw new Error(`${PACKAGE_NAME}: '${name}' is already in use`);
+            }
+
+            this.routes[name] = route;
+        }
+
+        if (path) {
+            for (let i = 0, n = methods.length; i < n; i++) {
+                let method = methods[i];
+
+                if (path.indexOf('?:') !== -1) {
+                    let segments = path.split('?:'),
+                        url = segments[0];
+
+                    this.add(method, url, route);
+
+                    for (let i = 1; i < segments.length; i++) {
+                        url += '/:' + segments[i];
+                        this.add(method, url, route);
+                    }
+                }
+                else {
+                    this.add(method, path, route);
+                }
+            }
+        }
+
+        if (subdomain) {
+            (this.subdomains ??= []).push( subdomain.toLowerCase() );
+        }
+
+        return this as any;
+    }
+
+    post<RouteName extends string = string, RoutePath extends string = string>(
+        options: RouteOptions<T> & { name?: RouteName; path?: RoutePath }
+    ): Router<
+        T,
+        TRoutes & (
+            RouteName extends string
+                ? RoutePath extends string
+                    ? { [K in RouteName]: { path: RoutePath } }
+                    : TRoutes
+                : TRoutes
+        )
+    > {
+        this.on(ON_POST, options);
+        return this as any;
+    }
+
+    put<RouteName extends string = string, RoutePath extends string = string>(
+        options: RouteOptions<T> & { name?: RouteName; path?: RoutePath }
+    ): Router<
+        T,
+        TRoutes & (
+            RouteName extends string
+                ? RoutePath extends string
+                    ? { [K in RouteName]: { path: RoutePath } }
+                    : TRoutes
+                : TRoutes
+        )
+    > {
+        this.on(ON_PUT, options);
+        return this as any;
+    }
+
+    uri<RouteName extends keyof TRoutes & string>(
+        name: RouteName,
+        values: PathParamsTuple<TRoutes[RouteName]['path']> = [] as any
+    ): string {
+        let path = this.routes[name]?.path;
+
+        if (!path) {
+            throw new Error(`${PACKAGE_NAME}: route name '${name}' does not exist or it does not provide a path`);
+        }
+
+        let resolved: (string | number)[] = [],
+            segments = path.split('/'),
+            v = 0;
+
+        for (let i = 0, n = segments.length; i < n; i++) {
+            let segment = segments[i],
+                symbol = segment[0];
+
+            if (symbol === ':') {
+                resolved.push((values as (string | number)[])[v++]);
+            }
+            else if (symbol === '?') {
+                if ((values as (string | number)[])[v] === undefined) {
+                    break;
+                }
+
+                resolved.push((values as (string | number)[])[v++]);
+            }
+            else if (symbol === '*') {
+                for (let n = values.length; v < n; v++) {
+                    resolved.push((values as (string | number)[])[v]);
+                }
+                break;
+            }
+            else {
+                resolved.push(segment);
+            }
+        }
+
+        return resolved.join('/');
+    }
+}
+
+
+export { Router };
+export type { Route };

package/src/client/router/node.ts

@@ -0,0 +1,122 @@
+import { PARAMETER, STATIC, WILDCARD } from '../constants';
+import { Route } from './index';
+
+
+class Node<T> {
+    parent: Node<T> | null = null;
+    path: string | null = null;
+    route: Route<T> | null = null;
+    static: Map<string | number, Node<T>> | null = null;
+    type: number | null = null;
+
+    // Parameter or Wildcard parameter name
+    name: string | null = null;
+    parameter: Node<T> | null = null;
+    wildcard: Node<T> | null = null;
+
+
+    constructor(parent: Node<T>['parent'] = null) {
+        this.parent = parent;
+    }
+
+
+    add(path: string, route: Route<T>) {
+        let node: Node<T> | undefined = this,
+            segments = path.split('/'),
+            type: Node<T>['type'] = STATIC,
+            unnamed = 0;
+
+        for (let i = 0, n = segments.length; i < n; i++) {
+            let segment = segments[i],
+                symbol = segment[0];
+
+            // Parameter
+            if (symbol === ':') {
+                if (!node.parameter) {
+                    node.parameter = new Node<T>(node);
+                    node.parameter.name = (segment.slice(1) || unnamed++).toString();
+                }
+
+                node = node.parameter;
+                type = PARAMETER;
+            }
+            // "*:" Wildcard
+            else if (symbol === '*') {
+                if (!node.wildcard) {
+                    node.wildcard = new Node<T>(node);
+                    node.wildcard.name = (segment.slice(2) || unnamed++).toString();
+                }
+
+                node = node.wildcard;
+                type = WILDCARD;
+            }
+            // Static name
+            else {
+                let next: Node<T> | undefined = node.static?.get(segment);
+
+                if (!next) {
+                    next = new Node<T>(node);
+                    (node.static ??= new Map()).set(segment, next);
+                }
+
+                node = next;
+            }
+        }
+
+        node.path = path;
+        node.route = route;
+        node.type = type;
+
+        return node;
+    }
+
+    find(path: string): {
+        parameters?: Readonly<Record<PropertyKey, unknown>>;
+        route?: Readonly<Route<T>>;
+    } {
+        let node: Node<T> | undefined = this,
+            parameters: Record<PropertyKey, unknown> | undefined,
+            segments = path.split('/'),
+            wildcard: { node: Node<T>, start: number } | undefined;
+
+        for (let i = 0, n = segments.length; i < n; i++) {
+            let segment = segments[i];
+
+            if (node.wildcard) {
+                wildcard = {
+                    node: node.wildcard,
+                    start: i
+                };
+            }
+
+            // Exact matches take precedence over parameters
+            let next: Node<T> | undefined = node.static?.get(segment) as Node<T> | undefined;
+
+            if (next) {
+                node = next;
+                continue;
+            }
+
+            if (!node.parameter) {
+                node = undefined;
+                break;
+            }
+
+            node = node.parameter;
+            (parameters ??= {})[node.name!] = segment;
+        }
+
+        if ((node === undefined || node.route === null) && wildcard) {
+            node = wildcard.node;
+            (parameters ??= {})[ node.name! ] = segments.slice(wildcard.start).join('/');
+        }
+
+        return {
+            parameters,
+            route: node?.route || undefined
+        };
+    }
+}
+
+
+export { Node };

package/src/client/types.ts

@@ -0,0 +1,105 @@
+import { NeverAsync } from '@esportsplus/utilities';
+import { Router } from './router';
+import pipeline from '@esportsplus/pipeline';
+
+
+type AccumulateRoutes<T extends readonly RouteFactory<any>[]> =
+    T extends readonly [infer F extends RouteFactory<any>, ...infer Rest extends readonly RouteFactory<any>[]]
+        ? ExtractRoutes<F> & AccumulateRoutes<Rest>
+        : {};
+
+type ExtractOptionalParams<Path extends string> =
+    Path extends `/${infer Segment}/${infer Rest}`
+        ? (Segment extends `?:${infer Param}` ? Param : never) | ExtractOptionalParams<`/${Rest}`>
+        : Path extends `/${infer Segment}`
+            ? (Segment extends `?:${infer Param}` ? Param : never)
+            : never;
+
+type ExtractParamsTuple<Path extends string> =
+    Path extends `${infer _Start}:${infer Param}/${infer Rest}`
+        ? [Param, ...ExtractParamsTuple<`/${Rest}`>]
+        : Path extends `${infer _Start}:${infer Param}`
+            ? [Param]
+            : [];
+
+type ExtractRequiredParams<Path extends string> =
+    Path extends `/${infer Segment}/${infer Rest}`
+        ? (Segment extends `:${infer Param}` ? Param : never) | ExtractRequiredParams<`/${Rest}`>
+        : Path extends `/${infer Segment}`
+            ? (Segment extends `:${infer Param}` ? Param : never)
+            : never;
+
+type ExtractRoutes<F> =
+    F extends (r: Router<any, any>) => Router<any, infer Routes extends RouteRegistry>
+        ? Routes
+        : never;
+
+type InferOutput<F> = F extends RouteFactory<infer T> ? T : never;
+
+type LabeledParamsTuple<Params extends string[]> =
+    Params extends [infer _First extends string, ...infer Rest extends string[]]
+        ? [_First: string | number, ...LabeledParamsTuple<Rest>]
+        : [];
+
+type Middleware<T> = NeverAsync<(input: Request<T>, next: Next<T>) => T>;
+
+type Name = string;
+
+type Next<T> = NeverAsync<(input: Request<T>) => T>;
+
+type Options<T> = {
+    middleware?: Middleware<T>[];
+    name?: string;
+    path?: string;
+    subdomain?: string;
+};
+
+type PathParamsObject<Path extends string> =
+    { [K in ExtractRequiredParams<Path>]: string | number } &
+    { [K in ExtractOptionalParams<Path>]?: string | number };
+
+type PathParamsTuple<Path extends string> =
+    LabeledParamsTuple<ExtractParamsTuple<Path>>;
+
+type Request<T> = {
+    data: Record<PropertyKey, unknown> & ReturnType<Router<T>['match']>;
+    hostname: string;
+    href: string;
+    method: string;
+    origin: string;
+    path: string;
+    port: string;
+    protocol: string;
+    query: Record<string, unknown>;
+    subdomain?: string;
+};
+
+type Route<T> = {
+    name: Name | null;
+    path: string | null;
+    pipeline: ReturnType<typeof pipeline<Request<T>, T>>,
+    subdomain: string | null;
+};
+
+type RouteFactory<T> = (router: Router<T, any>) => Router<T, RouteRegistry>;
+
+type RouteOptions<T> = Options<T> & {
+    responder: Next<T>;
+};
+
+type RoutePath<Routes, K extends keyof Routes> =
+    Routes[K] extends { path: infer P extends string } ? P : string;
+
+type RouteRegistry = Record<string, { path: string }>;
+
+
+export type {
+    AccumulateRoutes,
+    ExtractOptionalParams, ExtractRequiredParams,
+    InferOutput,
+    Middleware,
+    Name, Next,
+    Options,
+    PathParamsObject, PathParamsTuple,
+    Request, Router, Route, RouteFactory, RouteOptions, RoutePath, RouteRegistry
+};

package/src/constants.ts

@@ -0,0 +1,4 @@
+const PACKAGE_NAME = '@esportsplus/routing';
+
+
+export { PACKAGE_NAME };