@lark-apaas/devtool-kits 0.1.0-alpha.0

package/dist/index.d.cts

@@ -0,0 +1,179 @@
+import { Router, RequestHandler, Application } from 'express';
+
+/**
+ * 标准化基础路径，确保以 '/' 开头且不包含 trailing slash
+ * @param basePath 原始基础路径
+ * @returns 标准化后的基础路径
+ */
+declare function normalizeBasePath(basePath: string): string;
+
+type PostprocessStats = {
+    replacedUnknown: number;
+    unmatchedUnknown: string[];
+};
+declare function postprocessDrizzleSchema(targetPath: string): PostprocessStats | undefined;
+
+/**
+ * Shared context passed to all middlewares
+ */
+interface MiddlewareContext {
+    /** Base path for the application (e.g., '/', '/app') */
+    basePath: string;
+    /** Whether running in development mode */
+    isDev: boolean;
+    /** Root directory of the project */
+    rootDir: string;
+    /** Additional custom options */
+    [key: string]: any;
+}
+/**
+ * Express-compatible app (rspack/webpack dev server)
+ */
+type ExpressApp = Application;
+/**
+ * Vite-compatible middleware handler (Connect server)
+ * Using 'any' to avoid dependency on vite types
+ */
+type ViteMiddleware = any;
+/**
+ * Route registration info for better visibility
+ */
+interface RouteInfo {
+    /** HTTP method (GET, POST, etc.) or '*' for all methods */
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'ALL' | '*';
+    /** Route path (relative to mount point) */
+    path: string;
+    /** Description of what this route does */
+    description: string;
+}
+/**
+ * Route-based middleware
+ * Mounts a router at a specific path
+ */
+interface RouteMiddleware {
+    /** Unique name for this middleware */
+    name: string;
+    /**
+     * Mount path for this middleware (relative to basePath)
+     * e.g., '/dev/logs', '/openapi.json'
+     * Required for route-based middlewares
+     */
+    mountPath: string;
+    /**
+     * List of routes provided by this middleware
+     * Useful for debugging and documentation
+     */
+    routes?: RouteInfo[];
+    /**
+     * Determine if this middleware should be enabled
+     * @param context - Shared context
+     * @returns true if middleware should be registered
+     */
+    enabled?: (context: MiddlewareContext) => boolean;
+    /**
+     * Create router for this middleware
+     * @param context - Shared context
+     * @returns Express Router
+     */
+    createRouter: (context: MiddlewareContext) => Router;
+    /** Explicitly disallow createHandler for route middleware */
+    createHandler?: never;
+}
+/**
+ * Global middleware
+ * Applies to all requests without a specific mount path
+ */
+interface GlobalMiddleware {
+    /** Unique name for this middleware */
+    name: string;
+    /**
+     * Global middlewares should not have a mount path
+     * If you need path-specific behavior, use RouteMiddleware instead
+     */
+    mountPath?: never;
+    /**
+     * Determine if this middleware should be enabled
+     * @param context - Shared context
+     * @returns true if middleware should be registered
+     */
+    enabled?: (context: MiddlewareContext) => boolean;
+    /**
+     * Create handler for this middleware
+     * @param context - Shared context
+     * @returns Express request handler
+     */
+    createHandler: (context: MiddlewareContext) => RequestHandler;
+    /** Explicitly disallow createRouter for global middleware */
+    createRouter?: never;
+}
+/**
+ * Middleware can be either route-based or global
+ */
+type Middleware = RouteMiddleware | GlobalMiddleware;
+
+/**
+ * Options for OpenAPI middleware
+ */
+interface OpenapiMiddlewareOptions {
+    /** Path to the openapi.json file */
+    openapiFilePath: string;
+    /** Enable source code enhancement */
+    enableEnhancement?: boolean;
+}
+
+/**
+ * Creates OpenAPI middleware that serves enhanced openapi.json
+ * Supports both rspack/webpack and Vite dev servers
+ */
+declare function createOpenapiMiddleware(options: OpenapiMiddlewareOptions): RouteMiddleware;
+
+interface DevLogsMiddlewareOptions {
+    /** Directory containing log files */
+    logDir?: string;
+}
+/**
+ * Creates dev logs middleware for viewing application logs
+ * Supports both rspack/webpack and Vite dev servers
+ */
+declare function createDevLogsMiddleware(options?: DevLogsMiddlewareOptions): RouteMiddleware;
+
+/**
+ * Register middlewares for Express-compatible servers or Vite
+ * @param server - Express app or Vite middleware instance
+ * @param middlewares - List of middlewares to register
+ * @param options - Optional context configuration
+ * @returns Promise that resolves when all middlewares are registered
+ *
+ * @example
+ * ```typescript
+ * // In rspack/webpack setupMiddlewares
+ * setupMiddlewares: (middlewares, devServer) => {
+ *   if (devServer.app) {
+ *     registerMiddlewares(devServer.app, [
+ *       // Global middlewares (execute first)
+ *       createCorsMiddleware({ origin: '*' }),
+ *       createAuthMiddleware(),
+ *
+ *       // Route middlewares
+ *       createDevLogsMiddleware({ logDir: './logs' }),
+ *       createOpenapiMiddleware({ openapiFilePath: './openapi.json' })
+ *     ], {
+ *       basePath: '/api',
+ *       isDev: true,
+ *       rootDir: __dirname
+ *     });
+ *   }
+ *   return middlewares;
+ * }
+ *
+ * // In Vite configureServer
+ * configureServer: (server) => {
+ *   registerMiddlewares(server.middlewares, [
+ *     createDevLogsMiddleware({ logDir: './logs' })
+ *   ], { basePath: '/', isDev: true, rootDir: __dirname });
+ * }
+ * ```
+ */
+declare function registerMiddlewares(server: ExpressApp | ViteMiddleware, middlewares: Middleware[], options?: Partial<MiddlewareContext>): Promise<void>;
+
+export { type GlobalMiddleware, type Middleware, type MiddlewareContext, type RouteInfo, type RouteMiddleware, createDevLogsMiddleware, createOpenapiMiddleware, normalizeBasePath, postprocessDrizzleSchema, registerMiddlewares };

package/dist/index.d.ts

@@ -0,0 +1,179 @@
+import { Router, RequestHandler, Application } from 'express';
+
+/**
+ * 标准化基础路径，确保以 '/' 开头且不包含 trailing slash
+ * @param basePath 原始基础路径
+ * @returns 标准化后的基础路径
+ */
+declare function normalizeBasePath(basePath: string): string;
+
+type PostprocessStats = {
+    replacedUnknown: number;
+    unmatchedUnknown: string[];
+};
+declare function postprocessDrizzleSchema(targetPath: string): PostprocessStats | undefined;
+
+/**
+ * Shared context passed to all middlewares
+ */
+interface MiddlewareContext {
+    /** Base path for the application (e.g., '/', '/app') */
+    basePath: string;
+    /** Whether running in development mode */
+    isDev: boolean;
+    /** Root directory of the project */
+    rootDir: string;
+    /** Additional custom options */
+    [key: string]: any;
+}
+/**
+ * Express-compatible app (rspack/webpack dev server)
+ */
+type ExpressApp = Application;
+/**
+ * Vite-compatible middleware handler (Connect server)
+ * Using 'any' to avoid dependency on vite types
+ */
+type ViteMiddleware = any;
+/**
+ * Route registration info for better visibility
+ */
+interface RouteInfo {
+    /** HTTP method (GET, POST, etc.) or '*' for all methods */
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'ALL' | '*';
+    /** Route path (relative to mount point) */
+    path: string;
+    /** Description of what this route does */
+    description: string;
+}
+/**
+ * Route-based middleware
+ * Mounts a router at a specific path
+ */
+interface RouteMiddleware {
+    /** Unique name for this middleware */
+    name: string;
+    /**
+     * Mount path for this middleware (relative to basePath)
+     * e.g., '/dev/logs', '/openapi.json'
+     * Required for route-based middlewares
+     */
+    mountPath: string;
+    /**
+     * List of routes provided by this middleware
+     * Useful for debugging and documentation
+     */
+    routes?: RouteInfo[];
+    /**
+     * Determine if this middleware should be enabled
+     * @param context - Shared context
+     * @returns true if middleware should be registered
+     */
+    enabled?: (context: MiddlewareContext) => boolean;
+    /**
+     * Create router for this middleware
+     * @param context - Shared context
+     * @returns Express Router
+     */
+    createRouter: (context: MiddlewareContext) => Router;
+    /** Explicitly disallow createHandler for route middleware */
+    createHandler?: never;
+}
+/**
+ * Global middleware
+ * Applies to all requests without a specific mount path
+ */
+interface GlobalMiddleware {
+    /** Unique name for this middleware */
+    name: string;
+    /**
+     * Global middlewares should not have a mount path
+     * If you need path-specific behavior, use RouteMiddleware instead
+     */
+    mountPath?: never;
+    /**
+     * Determine if this middleware should be enabled
+     * @param context - Shared context
+     * @returns true if middleware should be registered
+     */
+    enabled?: (context: MiddlewareContext) => boolean;
+    /**
+     * Create handler for this middleware
+     * @param context - Shared context
+     * @returns Express request handler
+     */
+    createHandler: (context: MiddlewareContext) => RequestHandler;
+    /** Explicitly disallow createRouter for global middleware */
+    createRouter?: never;
+}
+/**
+ * Middleware can be either route-based or global
+ */
+type Middleware = RouteMiddleware | GlobalMiddleware;
+
+/**
+ * Options for OpenAPI middleware
+ */
+interface OpenapiMiddlewareOptions {
+    /** Path to the openapi.json file */
+    openapiFilePath: string;
+    /** Enable source code enhancement */
+    enableEnhancement?: boolean;
+}
+
+/**
+ * Creates OpenAPI middleware that serves enhanced openapi.json
+ * Supports both rspack/webpack and Vite dev servers
+ */
+declare function createOpenapiMiddleware(options: OpenapiMiddlewareOptions): RouteMiddleware;
+
+interface DevLogsMiddlewareOptions {
+    /** Directory containing log files */
+    logDir?: string;
+}
+/**
+ * Creates dev logs middleware for viewing application logs
+ * Supports both rspack/webpack and Vite dev servers
+ */
+declare function createDevLogsMiddleware(options?: DevLogsMiddlewareOptions): RouteMiddleware;
+
+/**
+ * Register middlewares for Express-compatible servers or Vite
+ * @param server - Express app or Vite middleware instance
+ * @param middlewares - List of middlewares to register
+ * @param options - Optional context configuration
+ * @returns Promise that resolves when all middlewares are registered
+ *
+ * @example
+ * ```typescript
+ * // In rspack/webpack setupMiddlewares
+ * setupMiddlewares: (middlewares, devServer) => {
+ *   if (devServer.app) {
+ *     registerMiddlewares(devServer.app, [
+ *       // Global middlewares (execute first)
+ *       createCorsMiddleware({ origin: '*' }),
+ *       createAuthMiddleware(),
+ *
+ *       // Route middlewares
+ *       createDevLogsMiddleware({ logDir: './logs' }),
+ *       createOpenapiMiddleware({ openapiFilePath: './openapi.json' })
+ *     ], {
+ *       basePath: '/api',
+ *       isDev: true,
+ *       rootDir: __dirname
+ *     });
+ *   }
+ *   return middlewares;
+ * }
+ *
+ * // In Vite configureServer
+ * configureServer: (server) => {
+ *   registerMiddlewares(server.middlewares, [
+ *     createDevLogsMiddleware({ logDir: './logs' })
+ *   ], { basePath: '/', isDev: true, rootDir: __dirname });
+ * }
+ * ```
+ */
+declare function registerMiddlewares(server: ExpressApp | ViteMiddleware, middlewares: Middleware[], options?: Partial<MiddlewareContext>): Promise<void>;
+
+export { type GlobalMiddleware, type Middleware, type MiddlewareContext, type RouteInfo, type RouteMiddleware, createDevLogsMiddleware, createOpenapiMiddleware, normalizeBasePath, postprocessDrizzleSchema, registerMiddlewares };