@gulibs/vgrove-client/dist/middleware.d.ts

Client-side utilities for React auto routes

/**
 * VGrove 中间件系统
 * 基于 React Router v7+ 中间件特性的路由守卫和中间件链式处理
 */
import React from 'react';
import { type LoaderFunctionArgs, type ActionFunctionArgs, type Params } from 'react-router';
import type { AuthCheck } from './loaders';
import type { BaseUser } from './types';
/**
 * 中间件执行上下文
 */
export interface MiddlewareContext<TUser extends BaseUser = BaseUser> {
    /** 请求对象 */
    request: Request;
    /** 当前用户信息 */
    user?: TUser | null;
    /** 路由参数 */
    params: Params<string>;
    /** 中间件共享数据 */
    data: Record<string, any>;
    /** 是否为 loader 调用 */
    isLoader: boolean;
    /** 是否为 action 调用 */
    isAction: boolean;
}
/**
 * 中间件执行结果
 */
export interface MiddlewareResult {
    /** 是否继续执行后续中间件 */
    continue: boolean;
    /** 重定向响应（如果需要） */
    redirect?: Response;
    /** 修改后的上下文数据 */
    data?: Record<string, any>;
    /** 错误信息 */
    error?: string;
}
/**
 * 中间件函数类型
 */
export type MiddlewareFunction<TUser extends BaseUser = BaseUser> = (context: MiddlewareContext<TUser>) => Promise<MiddlewareResult> | MiddlewareResult;
/**
 * 中间件配置
 */
export interface MiddlewareConfig<TUser extends BaseUser = BaseUser> {
    /** 中间件名称 */
    name: string;
    /** 中间件函数 */
    handler: MiddlewareFunction<TUser>;
    /** 执行优先级（数字越小优先级越高） */
    priority: number;
    /** 是否启用 */
    enabled: boolean;
    /** 适用的路径模式 */
    pathPatterns?: string[];
    /** 排除的路径模式 */
    excludePatterns?: string[];
    /** 是否仅在 loader 中执行 */
    loaderOnly?: boolean;
    /** 是否仅在 action 中执行 */
    actionOnly?: boolean;
}
/**
 * 守卫失败提示配置
 */
export interface GuardFailureConfig {
    /** 提示组件类型 */
    type: 'toast' | 'modal' | 'redirect' | 'inline';
    /** 提示标题 */
    title?: string;
    /** 提示内容 */
    message: string;
    /** 动画类型 */
    animation?: 'fade' | 'slide' | 'bounce' | 'shake';
    /** 动画持续时间（毫秒） */
    duration?: number;
    /** 自动关闭时间（毫秒） */
    autoClose?: number;
    /** 重定向路径（type 为 redirect 时） */
    redirectPath?: string;
    /** 自定义样式类名 */
    className?: string;
    /** 是否可关闭 */
    closable?: boolean;
    /** 图标类型 */
    icon?: 'warning' | 'shield' | 'lock' | 'custom';
    /** 自定义图标 */
    customIcon?: React.ReactNode;
    /** 操作按钮 */
    actions?: Array<{
        label: string;
        onClick: () => void;
        variant?: 'primary' | 'secondary' | 'danger';
    }>;
}
/**
 * 中间件管理器
 */
export declare class MiddlewareManager<TUser extends BaseUser = BaseUser> {
    private middlewares;
    private guardFailureConfigs;
    private globalFailureConfig;
    private static instance;
    private constructor();
    static getManager<T extends BaseUser>(): MiddlewareManager<T>;
    /**
     * 注册中间件
     */
    register(config: MiddlewareConfig<TUser>): void;
    /**
     * 注销中间件
     */
    unregister(name: string): void;
    /**
     * 启用/禁用中间件
     */
    toggle(name: string, enabled: boolean): void;
    /**
     * 配置守卫失败提示
     */
    configureGuardFailure(guardName: string, config: GuardFailureConfig): void;
    /**
     * 配置全局守卫失败提示
     */
    configureGlobalGuardFailure(config: GuardFailureConfig): void;
    /**
     * 获取守卫失败配置
     */
    private getGuardFailureConfig;
    /**
     * 检查路径是否匹配模式
     */
    private matchesPattern;
    /**
     * 获取适用的中间件列表
     */
    private getApplicableMiddlewares;
    /**
     * 处理守卫失败
     */
    private handleGuardFailure;
    /**
     * 执行中间件链
     */
    execute(args: LoaderFunctionArgs | ActionFunctionArgs, user?: TUser | null): Promise<{
        success: boolean;
        data?: any;
        response?: Response;
    }>;
    /**
     * 获取所有中间件信息
     */
    getMiddlewares(): MiddlewareConfig<TUser>[];
    /**
     * 清空所有中间件
     */
    clear(): void;
}
export declare const middlewareManager: MiddlewareManager<BaseUser>;
/**
 * 为 vgrove-autoroutes 生成的路由初始化中间件
 * 此函数会被 vgrove-autoroutes 在生成路由代码时自动调用
 */
export declare function initializeMiddlewares(): void;
/**
 * 检查中间件管理器是否已正确初始化
 */
export declare function isMiddlewareManagerReady(): boolean;
/**
 * 获取适用于特定路径的中间件列表
 * 用于调试和路由配置验证
 */
export declare function getMiddlewaresForPath(pathname: string): MiddlewareConfig<BaseUser>[];
/**
 * 认证中间件
 */
export declare function createAuthMiddleware<TUser extends BaseUser = BaseUser>(authCheck: AuthCheck<TUser>, options?: {
    priority?: number;
    pathPatterns?: string[];
    excludePatterns?: string[];
    failureConfig?: GuardFailureConfig;
}): MiddlewareConfig<TUser>;
/**
 * 角色检查中间件
 */
export declare function createRoleMiddleware<TUser extends BaseUser = BaseUser>(requiredRoles: string[], options?: {
    priority?: number;
    pathPatterns?: string[];
    excludePatterns?: string[];
    requireAll?: boolean;
    failureConfig?: GuardFailureConfig;
}): MiddlewareConfig<TUser>;
/**
 * 权限检查中间件
 */
export declare function createPermissionMiddleware<TUser extends BaseUser = BaseUser>(requiredPermissions: string[], options?: {
    priority?: number;
    pathPatterns?: string[];
    excludePatterns?: string[];
    requireAll?: boolean;
    failureConfig?: GuardFailureConfig;
}): MiddlewareConfig<TUser>;
/**
 * 速率限制中间件
 */
export declare function createRateLimitMiddleware<TUser extends BaseUser = BaseUser>(options: {
    maxRequests: number;
    windowMs: number;
    priority?: number;
    pathPatterns?: string[];
    excludePatterns?: string[];
    keyGenerator?: (context: MiddlewareContext<TUser>) => string;
}): MiddlewareConfig<TUser>;
/**
 * 注册认证中间件
 */
export declare function registerAuthMiddleware<TUser extends BaseUser = BaseUser>(authCheck: AuthCheck<TUser>, options?: Parameters<typeof createAuthMiddleware<TUser>>[1]): void;
/**
 * 注册角色中间件
 */
export declare function registerRoleMiddleware<TUser extends BaseUser = BaseUser>(requiredRoles: string[], options?: Parameters<typeof createRoleMiddleware<TUser>>[1]): void;
/**
 * 注册权限中间件
 */
export declare function registerPermissionMiddleware<TUser extends BaseUser = BaseUser>(requiredPermissions: string[], options?: Parameters<typeof createPermissionMiddleware<TUser>>[1]): void;
/**
 * 注册速率限制中间件
 */
export declare function registerRateLimitMiddleware<TUser extends BaseUser = BaseUser>(options: Parameters<typeof createRateLimitMiddleware<TUser>>[0]): void;
/**
 * 创建集成中间件的 loader
 */
export declare function createMiddlewareLoader(originalLoader?: (args: LoaderFunctionArgs) => any): (args: LoaderFunctionArgs) => Promise<any>;
/**
 * 创建集成中间件的 action
 */
export declare function createMiddlewareAction(originalAction?: (args: ActionFunctionArgs) => any): (args: ActionFunctionArgs) => Promise<any>;
//# sourceMappingURL=middleware.d.ts.map