@veap/plugins 0.0.0-stage → 0.1.1

package/dist/router/route-tree.d.ts

@@ -0,0 +1,177 @@
+/**
+ * @module route-tree
+ * @description Core route tree engine for the Veap unstable custom router.
+ *
+ * Implements a tree-based routing structure that mirrors Next.js App Router
+ * file conventions. Supports static, dynamic, catch-all, optional catch-all,
+ * route group, and parallel route segments.
+ *
+ * @example
+ * ```ts
+ * const tree = new RouteTree();
+ * tree.addTree({
+ *   segment: "",
+ *   layout: RootLayout,
+ *   children: [
+ *     { segment: "blog", page: BlogPage, children: [
+ *       { segment: "[slug]", page: BlogPostPage },
+ *     ]},
+ *   ],
+ * });
+ *
+ * const result = tree.match("/blog/hello-world");
+ * // result.params => { slug: "hello-world" }
+ * ```
+ */
+import type { UserPermission, UserRole } from "@veap/auth";
+import type { Metadata } from "next";
+import type * as React from "react";
+import type { ApiMiddleware, BreadcrumbValue, VeapMiddleware } from "../common/types";
+/**
+ * A single node in the route tree. Mirrors Next.js App Router file conventions.
+ * Each node represents a URL segment and can contain page/layout/loading/error
+ * components, metadata generators, middleware pipelines, and auth constraints.
+ */
+export interface RouteNode {
+    /**
+     * Segment of the path.
+     * - Regular: `"blog"`, `"about"`
+     * - Dynamic: `"[id]"`, `"[slug]"`
+     * - Catch-all: `"[...path]"`
+     * - Optional catch-all: `"[[...path]]"`
+     * - Route group: `"(marketing)"` - transparent in URL
+     * - Empty string `""` for root/index
+     */
+    segment: string;
+    /** Page component - equivalent to `page.tsx`. */
+    page?: React.ComponentType<any>;
+    /** Layout wrapping children - equivalent to `layout.tsx`. */
+    layout?: React.ComponentType<{
+        children: React.ReactNode;
+        params?: any;
+        [slotName: string]: any;
+    }>;
+    /** Loading component - equivalent to `loading.tsx`. */
+    loading?: React.ComponentType;
+    /** Error component - equivalent to `error.tsx` (client component). */
+    error?: React.ComponentType<{
+        error: Error;
+        reset: () => void;
+    }>;
+    /** Not-found component - equivalent to `not-found.tsx`. */
+    notFound?: React.ComponentType;
+    /** Default component for parallel route slots - equivalent to `default.tsx`. */
+    default?: React.ComponentType<any>;
+    /** API route handlers - equivalent to `route.ts`. Contains exported HTTP methods like GET, POST, etc. */
+    route?: {
+        GET?: Function;
+        POST?: Function;
+        PUT?: Function;
+        DELETE?: Function;
+        PATCH?: Function;
+        OPTIONS?: Function;
+        HEAD?: Function;
+        [key: string]: any;
+    };
+    /**
+     * Metadata generator for this route node.
+     * Called with params and searchParams to produce `<head>` metadata.
+     */
+    generateMetadata?: (props: {
+        params: Record<string, string>;
+        searchParams: Record<string, string>;
+    }) => Promise<Metadata> | Metadata;
+    /** Middleware pipeline applied when this node is part of the matched chain. */
+    middlewares?: (VeapMiddleware | ApiMiddleware)[] | any[];
+    /** Whether authentication is required to access this route. */
+    auth?: boolean;
+    /** Roles required to access this route (RBAC). */
+    roles?: UserRole[];
+    /** Permissions required to access this route (RBAC). */
+    permissions?: UserPermission[];
+    /** Breadcrumb configuration for this route node. */
+    breadcrumb?: BreadcrumbValue;
+    /** Route ID for template overrides and programmatic identification. */
+    id?: string;
+    /** Child route nodes. */
+    children?: RouteNode[];
+    /**
+     * Parallel route slots: `@slotName` → subtree.
+     * Parallel routes are resolved independently against the same URL path.
+     */
+    parallelRoutes?: Record<string, RouteNode>;
+}
+/**
+ * Represents a single entry in the layout chain collected during route matching.
+ * Each entry captures the layout, loading, error, middleware, and auth config
+ * from one level of the tree as we walk from root to the matched leaf.
+ */
+export interface LayoutChainEntry {
+    /** Layout component at this level. */
+    layout?: React.ComponentType<any>;
+    /** Loading component at this level. */
+    loading?: React.ComponentType;
+    /** Error component at this level. */
+    error?: React.ComponentType<{
+        error: Error;
+        reset: () => void;
+    }>;
+    /** NotFound component at this level. */
+    notFound?: React.ComponentType;
+    /** Middleware pipeline at this level. */
+    middlewares?: (VeapMiddleware | ApiMiddleware)[] | any[];
+    /** Whether authentication is required at this level. */
+    auth?: boolean;
+    /** Roles required at this level. */
+    roles?: UserRole[];
+    /** Permissions required at this level. */
+    permissions?: UserPermission[];
+    /** Resolved parallel slot contents for this layout level. */
+    parallelSlots?: Record<string, RouteNode>;
+    /** The path segments consumed up to this layout level. Used for parallel route matching. */
+    consumedPath?: string;
+    /** Route ID for template overrides. */
+    id?: string;
+}
+/**
+ * Result of matching a URL path against the route tree.
+ */
+export interface MatchResult {
+    /** The matched leaf node (has a `page` component). */
+    node: RouteNode;
+    /** Extracted URL parameters (dynamic segments, catch-all, etc.). */
+    params: Record<string, string>;
+    /** Chain of layouts from root to the matched node. */
+    layoutChain: LayoutChainEntry[];
+    /** Path segments that were matched (for debugging/breadcrumbs). */
+    matchedSegments: string[];
+    /** True if the path was fully consumed and matched a leaf node (page). False for partial matches. */
+    isExact: boolean;
+}
+export declare function isGroupSegment(segment: string): boolean;
+export declare function isDynamicSegment(segment: string): boolean;
+export declare function isCatchAllSegment(segment: string): boolean;
+export declare function isOptionalCatchAllSegment(segment: string): boolean;
+export declare function isParallelSlot(segment: string): boolean;
+export declare function extractParamName(segment: string): string;
+export declare function segmentMatchesUrlPart(segment: string, urlPart: string): boolean;
+export declare function resolveMagicPrefix(node: RouteNode, prefixPath: string): RouteNode;
+export declare class RouteTree {
+    private root;
+    private rewrites;
+    constructor(initialRoot?: RouteNode, initialRewrites?: Map<string, string> | Record<string, string>);
+    private normalizeRewritePath;
+    addRewrite(from: string, to: string): this;
+    setRewrites(rewrites: Map<string, string> | Record<string, string>): this;
+    getRewrites(): Map<string, string>;
+    resolveRewrite(path: string): string;
+    private matchRewritePattern;
+    private applyRewritePattern;
+    getRoot(): RouteNode;
+    addTree(source: RouteNode | RouteTree, prefix?: string): void;
+    mergeNode(target: RouteNode, source: RouteNode): void;
+    match(path: string): MatchResult | null;
+    generateMetadata(path: string, searchParams?: Record<string, string>): Promise<Metadata>;
+    private collectMetadataGenerators;
+    private collectGeneratorsRecursive;
+}