@chidchanun/bcp 0.1.0

package/packages/router/src/advanced-router.ts

@@ -0,0 +1,1032 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export type RouteSegment =
+    | {
+        type: "static";
+        value: string;
+    }
+    | {
+        type: "dynamic";
+        value: string;
+    }
+    | {
+        type: "catchAll";
+        value: string;
+    }
+    | {
+        type: "optionalCatchAll";
+        value: string;
+    }
+    | {
+        type: "group";
+        value: string;
+    };
+
+export type RouteParamValue =
+    | string
+    | string[]
+    | undefined;
+
+export type RouteParams = Record<
+    string,
+    RouteParamValue
+>;
+
+interface RoutePattern {
+    pathname: string;
+    filePath: string;
+    segments: RouteSegment[];
+    appDirectory?: string;
+}
+
+export interface Route
+    extends RoutePattern {
+    layouts: string[];
+}
+
+export interface ApiRoute
+    extends RoutePattern { }
+
+export interface RouteMatch<
+    T extends RoutePattern
+> {
+    route: T;
+
+    /*
+     * Kept structurally permissive for backward compatibility with
+     * pre-Step-27 server internals that still annotate params as
+     * Record<string, string>. Runtime values follow RouteParams:
+     * dynamic => string, catch-all => string[], optional catch-all =>
+     * string[] | undefined.
+     */
+    params: Record<string, any>;
+}
+
+export function scanRoutes(
+    appDirectory: string
+): Route[] {
+    validateAppDirectory(
+        appDirectory
+    );
+
+    const routes: Route[] = [];
+
+    walkDirectory(
+        appDirectory,
+        (fullPath, fileName) => {
+            if (!isPageFile(fileName)) {
+                return;
+            }
+
+            const relativePath =
+                path.relative(
+                    appDirectory,
+                    fullPath
+                );
+
+            const sourceSegments =
+                getRouteSourceSegments(
+                    relativePath,
+                    "page"
+                );
+
+            routes.push({
+                pathname:
+                    sourceSegmentsToPathname(
+                        sourceSegments
+                    ),
+                filePath:
+                    fullPath,
+                layouts:
+                    collectLayouts(
+                        appDirectory,
+                        fullPath
+                    ),
+                segments:
+                    parseRouteSegments(
+                        sourceSegments,
+                        relativePath
+                    ),
+                appDirectory:
+                    path.resolve(
+                        appDirectory
+                    ),
+            });
+        }
+    );
+
+    validateRouteCollection(
+        routes,
+        "page"
+    );
+
+    return routes.sort(
+        compareRoutes
+    );
+}
+
+export function scanApiRoutes(
+    appDirectory: string
+): ApiRoute[] {
+    validateAppDirectory(
+        appDirectory
+    );
+
+    const routes: ApiRoute[] = [];
+
+    walkDirectory(
+        appDirectory,
+        (fullPath, fileName) => {
+            if (!isApiRouteFile(fileName)) {
+                return;
+            }
+
+            const relativePath =
+                path.relative(
+                    appDirectory,
+                    fullPath
+                );
+
+            const sourceSegments =
+                getRouteSourceSegments(
+                    relativePath,
+                    "route"
+                );
+
+            routes.push({
+                pathname:
+                    sourceSegmentsToPathname(
+                        sourceSegments
+                    ),
+                filePath:
+                    fullPath,
+                segments:
+                    parseRouteSegments(
+                        sourceSegments,
+                        relativePath
+                    ),
+                appDirectory:
+                    path.resolve(
+                        appDirectory
+                    ),
+            });
+        }
+    );
+
+    validateRouteCollection(
+        routes,
+        "API"
+    );
+
+    return routes.sort(
+        compareRoutes
+    );
+}
+
+export function assertNoPageApiConflicts(
+    pageRoutes: Route[],
+    apiRoutes: ApiRoute[]
+): void {
+    const pages =
+        new Map<string, Route>();
+
+    for (const route of pageRoutes) {
+        pages.set(
+            createRouteSignature(
+                route
+            ),
+            route
+        );
+    }
+
+    for (const apiRoute of apiRoutes) {
+        const page =
+            pages.get(
+                createRouteSignature(
+                    apiRoute
+                )
+            );
+
+        if (!page) {
+            continue;
+        }
+
+        throw new Error(
+            "Page route and API route conflict:\n" +
+            `  Page: ${page.pathname}\n` +
+            `  API:  ${apiRoute.pathname}\n\n` +
+            "page.tsx and route.ts cannot own the same route pattern."
+        );
+    }
+}
+
+export function matchRoute(
+    routes: Route[],
+    pathname: string
+): RouteMatch<Route> | null {
+    return matchRoutePattern(
+        routes,
+        pathname
+    );
+}
+
+export function matchApiRoute(
+    routes: ApiRoute[],
+    pathname: string
+): RouteMatch<ApiRoute> | null {
+    return matchRoutePattern(
+        routes,
+        pathname
+    );
+}
+
+function matchRoutePattern<
+    T extends RoutePattern
+>(
+    routes: T[],
+    pathname: string
+): RouteMatch<T> | null {
+    const requestSegments =
+        splitRequestPath(
+            pathname
+        );
+
+    for (const route of routes) {
+        const urlSegments =
+            getUrlSegments(
+                route.segments
+            );
+
+        const params:
+            Record<string, any> = {};
+
+        let requestIndex = 0;
+        let matched = true;
+
+        for (
+            let routeIndex = 0;
+            routeIndex < urlSegments.length;
+            routeIndex++
+        ) {
+            const segment =
+                urlSegments[
+                    routeIndex
+                ];
+
+            if (
+                segment.type ===
+                "catchAll" ||
+                segment.type ===
+                "optionalCatchAll"
+            ) {
+                const remaining =
+                    requestSegments.slice(
+                        requestIndex
+                    );
+
+                if (
+                    segment.type ===
+                        "catchAll" &&
+                    remaining.length === 0
+                ) {
+                    matched = false;
+                    break;
+                }
+
+                params[
+                    segment.value
+                ] =
+                    remaining.length > 0
+                        ? remaining
+                        : undefined;
+
+                requestIndex =
+                    requestSegments.length;
+                continue;
+            }
+
+            const requestSegment =
+                requestSegments[
+                    requestIndex
+                ];
+
+            if (
+                requestSegment ===
+                undefined
+            ) {
+                matched = false;
+                break;
+            }
+
+            if (
+                segment.type ===
+                "static"
+            ) {
+                if (
+                    segment.value !==
+                    requestSegment
+                ) {
+                    matched = false;
+                    break;
+                }
+            } else {
+                params[
+                    segment.value
+                ] =
+                    requestSegment;
+            }
+
+            requestIndex++;
+        }
+
+        if (
+            matched &&
+            requestIndex ===
+                requestSegments.length
+        ) {
+            return {
+                route,
+                params,
+            };
+        }
+    }
+
+    return null;
+}
+
+function validateRouteCollection<
+    T extends RoutePattern
+>(
+    routes: T[],
+    type: string
+): void {
+    assertNoDuplicateRoutes(
+        routes,
+        type
+    );
+    assertNoAmbiguousRoutes(
+        routes,
+        type
+    );
+}
+
+function walkDirectory(
+    directory: string,
+    callback: (
+        fullPath: string,
+        fileName: string
+    ) => void
+): void {
+    const entries =
+        fs.readdirSync(
+            directory,
+            {
+                withFileTypes: true,
+            }
+        );
+
+    for (const entry of entries) {
+        const fullPath =
+            path.join(
+                directory,
+                entry.name
+            );
+
+        if (entry.isDirectory()) {
+            walkDirectory(
+                fullPath,
+                callback
+            );
+            continue;
+        }
+
+        callback(
+            fullPath,
+            entry.name
+        );
+    }
+}
+
+function validateAppDirectory(
+    appDirectory: string
+): void {
+    if (
+        fs.existsSync(
+            appDirectory
+        )
+    ) {
+        return;
+    }
+
+    throw new Error(
+        `App directory was not found: ${appDirectory}`
+    );
+}
+
+function getRouteSourceSegments(
+    filePath: string,
+    kind: "page" | "route"
+): string[] {
+    const normalized =
+        filePath.replace(
+            /\\/g,
+            "/"
+        );
+
+    const filePattern =
+        kind === "page"
+            ? /(?:^|\/)page\.tsx?$/
+            : /(?:^|\/)route\.ts$/;
+
+    const withoutFile =
+        normalized.replace(
+            filePattern,
+            ""
+        );
+
+    if (!withoutFile) {
+        return [];
+    }
+
+    return withoutFile
+        .split("/")
+        .filter(Boolean);
+}
+
+function sourceSegmentsToPathname(
+    segments: string[]
+): string {
+    const urlSegments =
+        segments.filter(
+            (segment) =>
+                !isRouteGroup(
+                    segment
+                )
+        );
+
+    return urlSegments.length > 0
+        ? `/${urlSegments.join("/")}`
+        : "/";
+}
+
+function parseRouteSegments(
+    sourceSegments: string[],
+    sourceLabel: string
+): RouteSegment[] {
+    const dynamicNames =
+        new Set<string>();
+
+    const result:
+        RouteSegment[] = [];
+
+    let foundCatchAll = false;
+
+    for (
+        let index = 0;
+        index < sourceSegments.length;
+        index++
+    ) {
+        const source =
+            sourceSegments[index];
+
+        if (isRouteGroup(source)) {
+            validateRouteGroup(
+                source,
+                sourceLabel
+            );
+
+            result.push({
+                type: "group",
+                value:
+                    source.slice(
+                        1,
+                        -1
+                    ),
+            });
+            continue;
+        }
+
+        if (foundCatchAll) {
+            throw new Error(
+                `Catch-all segment must be the last URL segment in "${sourceLabel}".`
+            );
+        }
+
+        const optionalCatchAll =
+            /^\[\[\.\.\.([A-Za-z_][A-Za-z0-9_]*)\]\]$/.exec(
+                source
+            );
+
+        if (optionalCatchAll) {
+            const name =
+                optionalCatchAll[1];
+
+            assertUniqueParam(
+                dynamicNames,
+                name,
+                sourceLabel
+            );
+
+            result.push({
+                type:
+                    "optionalCatchAll",
+                value:
+                    name,
+            });
+            foundCatchAll = true;
+            continue;
+        }
+
+        const catchAll =
+            /^\[\.\.\.([A-Za-z_][A-Za-z0-9_]*)\]$/.exec(
+                source
+            );
+
+        if (catchAll) {
+            const name =
+                catchAll[1];
+
+            assertUniqueParam(
+                dynamicNames,
+                name,
+                sourceLabel
+            );
+
+            result.push({
+                type:
+                    "catchAll",
+                value:
+                    name,
+            });
+            foundCatchAll = true;
+            continue;
+        }
+
+        const dynamic =
+            /^\[([A-Za-z_][A-Za-z0-9_]*)\]$/.exec(
+                source
+            );
+
+        if (dynamic) {
+            const name =
+                dynamic[1];
+
+            assertUniqueParam(
+                dynamicNames,
+                name,
+                sourceLabel
+            );
+
+            result.push({
+                type:
+                    "dynamic",
+                value:
+                    name,
+            });
+            continue;
+        }
+
+        if (
+            source.includes("[") ||
+            source.includes("]")
+        ) {
+            throw new Error(
+                `Invalid dynamic segment "${source}" in "${sourceLabel}".`
+            );
+        }
+
+        if (
+            source.startsWith("(") ||
+            source.endsWith(")")
+        ) {
+            throw new Error(
+                `Invalid route group segment "${source}" in "${sourceLabel}".`
+            );
+        }
+
+        result.push({
+            type: "static",
+            value: source,
+        });
+    }
+
+    return result;
+}
+
+function assertUniqueParam(
+    dynamicNames: Set<string>,
+    name: string,
+    sourceLabel: string
+): void {
+    if (dynamicNames.has(name)) {
+        throw new Error(
+            `Duplicate dynamic parameter "${name}" in route "${sourceLabel}".`
+        );
+    }
+
+    dynamicNames.add(name);
+}
+
+function isRouteGroup(
+    segment: string
+): boolean {
+    return /^\([^()]+\)$/.test(
+        segment
+    );
+}
+
+function validateRouteGroup(
+    segment: string,
+    sourceLabel: string
+): void {
+    const name =
+        segment.slice(
+            1,
+            -1
+        ).trim();
+
+    if (!name) {
+        throw new Error(
+            `Route group cannot be empty in "${sourceLabel}".`
+        );
+    }
+
+    if (
+        name.includes("/") ||
+        name.includes("\\")
+    ) {
+        throw new Error(
+            `Invalid route group "${segment}" in "${sourceLabel}".`
+        );
+    }
+}
+
+function getUrlSegments(
+    segments: RouteSegment[]
+): Exclude<
+    RouteSegment,
+    { type: "group" }
+>[] {
+    return segments.filter(
+        (
+            segment
+        ): segment is Exclude<
+            RouteSegment,
+            { type: "group" }
+        > =>
+            segment.type !==
+            "group"
+    );
+}
+
+function splitRequestPath(
+    pathname: string
+): string[] {
+    const cleanPathname =
+        pathname.split("?")[0]
+            .split("#")[0] ||
+        "/";
+
+    if (cleanPathname === "/") {
+        return [];
+    }
+
+    return cleanPathname
+        .replace(/^\/+|\/+$/g, "")
+        .split("/")
+        .filter(Boolean)
+        .map(
+            safeDecodeURIComponent
+        );
+}
+
+function safeDecodeURIComponent(
+    value: string
+): string {
+    try {
+        return decodeURIComponent(
+            value
+        );
+    } catch {
+        return value;
+    }
+}
+
+function compareRoutes<
+    T extends RoutePattern
+>(
+    left: T,
+    right: T
+): number {
+    const a =
+        getUrlSegments(
+            left.segments
+        );
+    const b =
+        getUrlSegments(
+            right.segments
+        );
+
+    const maxLength =
+        Math.max(
+            a.length,
+            b.length
+        );
+
+    for (
+        let index = 0;
+        index < maxLength;
+        index++
+    ) {
+        const aSegment =
+            a[index];
+        const bSegment =
+            b[index];
+
+        if (!aSegment || !bSegment) {
+            if (
+                !aSegment &&
+                bSegment?.type ===
+                    "optionalCatchAll"
+            ) {
+                return -1;
+            }
+
+            if (
+                !bSegment &&
+                aSegment?.type ===
+                    "optionalCatchAll"
+            ) {
+                return 1;
+            }
+
+            break;
+        }
+
+        const rankDifference =
+            segmentRank(
+                bSegment
+            ) -
+            segmentRank(
+                aSegment
+            );
+
+        if (rankDifference !== 0) {
+            return rankDifference;
+        }
+
+        if (
+            aSegment.type ===
+                "static" &&
+            bSegment.type ===
+                "static" &&
+            aSegment.value !==
+                bSegment.value
+        ) {
+            return aSegment.value
+                .localeCompare(
+                    bSegment.value
+                );
+        }
+    }
+
+    if (a.length !== b.length) {
+        return b.length - a.length;
+    }
+
+    return left.pathname
+        .localeCompare(
+            right.pathname
+        );
+}
+
+function segmentRank(
+    segment: Exclude<
+        RouteSegment,
+        { type: "group" }
+    >
+): number {
+    switch (segment.type) {
+        case "static":
+            return 4;
+        case "dynamic":
+            return 3;
+        case "catchAll":
+            return 2;
+        case "optionalCatchAll":
+            return 1;
+    }
+}
+
+function assertNoDuplicateRoutes<
+    T extends RoutePattern
+>(
+    routes: T[],
+    type: string
+): void {
+    const paths =
+        new Map<string, T>();
+
+    for (const route of routes) {
+        const existing =
+            paths.get(
+                route.pathname
+            );
+
+        if (existing) {
+            throw new Error(
+                `Duplicate ${type} route "${route.pathname}":\n` +
+                `  ${existing.filePath}\n` +
+                `  ${route.filePath}\n\n` +
+                "Route groups do not appear in URLs, so grouped routes must still have unique public pathnames."
+            );
+        }
+
+        paths.set(
+            route.pathname,
+            route
+        );
+    }
+}
+
+function assertNoAmbiguousRoutes<
+    T extends RoutePattern
+>(
+    routes: T[],
+    type: string
+): void {
+    const signatures =
+        new Map<string, T>();
+
+    for (const route of routes) {
+        const signature =
+            createRouteSignature(
+                route
+            );
+
+        const existing =
+            signatures.get(
+                signature
+            );
+
+        if (
+            existing &&
+            existing.pathname !==
+                route.pathname
+        ) {
+            throw new Error(
+                `Ambiguous ${type} routes:\n` +
+                `  ${existing.pathname}\n` +
+                `  ${route.pathname}\n\n` +
+                "Both routes match the same URL pattern."
+            );
+        }
+
+        signatures.set(
+            signature,
+            route
+        );
+    }
+}
+
+function createRouteSignature(
+    route: RoutePattern
+): string {
+    return getUrlSegments(
+        route.segments
+    )
+        .map(
+            (segment) => {
+                switch (
+                    segment.type
+                ) {
+                    case "static":
+                        return `s:${segment.value}`;
+                    case "dynamic":
+                        return "d:[]";
+                    case "catchAll":
+                        return "c:[...]";
+                    case "optionalCatchAll":
+                        return "o:[[...]]";
+                }
+            }
+        )
+        .join("/");
+}
+
+function isPageFile(
+    fileName: string
+): boolean {
+    return (
+        fileName === "page.ts" ||
+        fileName === "page.tsx"
+    );
+}
+
+function isApiRouteFile(
+    fileName: string
+): boolean {
+    return fileName ===
+        "route.ts";
+}
+
+function collectLayouts(
+    appDirectory: string,
+    pageFilePath: string
+): string[] {
+    const layouts: string[] = [];
+
+    const pageDirectory =
+        path.dirname(
+            pageFilePath
+        );
+
+    const relativeDirectory =
+        path.relative(
+            appDirectory,
+            pageDirectory
+        );
+
+    const segments =
+        relativeDirectory
+            ? relativeDirectory.split(
+                path.sep
+            )
+            : [];
+
+    let currentDirectory =
+        appDirectory;
+
+    const rootLayout =
+        findLayoutFile(
+            currentDirectory
+        );
+
+    if (rootLayout) {
+        layouts.push(
+            rootLayout
+        );
+    }
+
+    for (const segment of segments) {
+        currentDirectory =
+            path.join(
+                currentDirectory,
+                segment
+            );
+
+        const layout =
+            findLayoutFile(
+                currentDirectory
+            );
+
+        if (layout) {
+            layouts.push(
+                layout
+            );
+        }
+    }
+
+    return layouts;
+}
+
+function findLayoutFile(
+    directory: string
+): string | null {
+    const tsxFile =
+        path.join(
+            directory,
+            "layout.tsx"
+        );
+    const tsFile =
+        path.join(
+            directory,
+            "layout.ts"
+        );
+
+    const hasTsx =
+        fs.existsSync(
+            tsxFile
+        );
+    const hasTs =
+        fs.existsSync(
+            tsFile
+        );
+
+    if (hasTsx && hasTs) {
+        throw new Error(
+            `Both layout.tsx and layout.ts exist in ${directory}. Keep only one layout file.`
+        );
+    }
+
+    if (hasTsx) {
+        return tsxFile;
+    }
+
+    if (hasTs) {
+        return tsFile;
+    }
+
+    return null;
+}