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

package/LICENSE

@@ -0,0 +1,13 @@
+MIT License
+
+Copyright (c) 2024 Lark Technologies Pte. Ltd. and/or its affiliates
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted,provided that the above copyright notice and this permission notice appear in all copies.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE
+INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO
+EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
+CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
+DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
+ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,313 @@
+# Fullstack Toolkits
+
+A comprehensive toolkit for NestJS applications, providing middleware utilities and development tools.
+
+## Features
+
+- 🔧 **Development Middleware** - Dev-logs middleware for request/response logging and tracing
+- 📚 **OpenAPI Enhancement** - Enhanced OpenAPI/Swagger documentation with source code information
+- 🛠️ **Utility Functions** - Common utilities for path normalization and more
+- 🔍 **Path Matching** - Powerful path pattern matching for OpenAPI/Swagger/NestJS routes
+
+## Installation
+
+```bash
+npm install @apaas/fullstack-toolkits
+# or
+yarn add @apaas/fullstack-toolkits
+```
+
+## Usage
+
+### Middleware Registration
+
+The toolkit supports two types of middlewares:
+- **Route Middlewares**: Mount at specific paths (e.g., `/dev/logs`, `/openapi.json`)
+- **Global Middlewares**: Apply to all requests without path mounting
+
+Use the `registerMiddlewares` function to register both types:
+
+```typescript
+import {
+  registerMiddlewares,
+  createDevLogsMiddleware,
+  createOpenapiMiddleware
+} from '@apaas/fullstack-toolkits';
+
+// For rspack/webpack dev server
+export default {
+  devServer: {
+    setupMiddlewares: (middlewares, devServer) => {
+      if (devServer.app) {
+        registerMiddlewares(devServer.app, [
+          // Global middlewares execute first (in array order)
+          createCorsMiddleware({ origin: '*' }),
+          createRequestLoggerMiddleware(),
+
+          // Route middlewares mount at specific paths
+          createDevLogsMiddleware({ logDir: './logs' }),
+          createOpenapiMiddleware({
+            openapiFilePath: './openapi.json',
+            enableEnhancement: true
+          }),
+        ], {
+          basePath: '/api',
+          isDev: true,
+          rootDir: __dirname
+        });
+      }
+      return middlewares;
+    }
+  }
+}
+
+// For Vite dev server
+export default {
+  plugins: [
+    {
+      name: 'dev-middlewares',
+      configureServer: (server) => {
+        registerMiddlewares(server.middlewares, [
+          createDevLogsMiddleware({ logDir: './logs' }),
+          createOpenapiMiddleware({
+            openapiFilePath: './openapi.json',
+            enableEnhancement: true
+          }),
+        ], {
+          basePath: '/',
+          isDev: true,
+          rootDir: __dirname
+        });
+      }
+    }
+  ]
+}
+```
+
+**Important Notes:**
+- Middleware execution order matches the array order
+- Place global middlewares before route middlewares
+- Global middlewares apply to all requests
+- Route middlewares only handle requests matching their mount path
+
+### Global Middleware Examples
+
+Create custom global middlewares using the `GlobalMiddleware` interface:
+
+```typescript
+import type { GlobalMiddleware } from '@apaas/fullstack-toolkits';
+
+// Example: CORS middleware
+function createCorsMiddleware(options?: { origin?: string }): GlobalMiddleware {
+  return {
+    name: 'cors',
+    createHandler: () => {
+      return (req, res, next) => {
+        res.setHeader('Access-Control-Allow-Origin', options?.origin || '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE');
+        next();
+      };
+    }
+  };
+}
+
+// Example: Request logger
+function createRequestLoggerMiddleware(): GlobalMiddleware {
+  return {
+    name: 'request-logger',
+    enabled: (context) => context.isDev, // Only in dev mode
+    createHandler: () => {
+      return (req, res, next) => {
+        console.log(`[${new Date().toISOString()}] ${req.method} ${req.path}`);
+        next();
+      };
+    }
+  };
+}
+```
+
+See `src/middlewares/examples.ts` for more global middleware examples.
+
+### Dev Logs Middleware
+
+Provides request/response logging with trace ID support.
+
+**Features:**
+- View log entries by trace ID
+- Browse recent trace calls with pagination
+- Filter logs by API path patterns
+- Support for OpenAPI/Swagger path patterns
+
+**Routes:**
+- `GET /dev/logs/app/trace/:traceId` - Get log entries by trace ID
+- `GET /dev/logs/trace/recent` - Get recent trace calls (with pagination and path filtering)
+- `GET /dev/logs/files/:fileName` - Get log file content
+
+**Example:**
+```typescript
+createDevLogsMiddleware({
+  logDir: './logs', // Optional, defaults to 'logs'
+})
+```
+
+### OpenAPI Middleware
+
+Enhances OpenAPI/Swagger documentation with source code information.
+
+**Features:**
+- Automatically enhance OpenAPI paths with controller source locations
+- Transform paths to include basePath
+- Caching support for better performance
+
+**Routes:**
+- `GET /dev/openapi` - Get enhanced OpenAPI documentation
+
+**Example:**
+```typescript
+createOpenapiMiddleware({
+  openapiPath: './openapi.json',
+  enableEnhancement: true,
+})
+```
+
+### Path Matching Utility
+
+Powerful path pattern matching for OpenAPI/Swagger/NestJS routes.
+
+**Supported Patterns:**
+- Exact matching: `/api/users` === `/api/users`
+- Path parameters: `/api/users/{id}` matches `/api/users/123`
+- Single wildcard: `/api/*/users` matches `/api/v1/users`
+- Recursive wildcard: `/files/**` matches `/files/a/b/c`
+- Prefix matching: `/api/users` matches `/api/users/123`
+
+**Example:**
+```typescript
+import { matchesPathPattern, extractPathParams } from '@apaas/fullstack-toolkits';
+
+// Match path patterns
+matchesPathPattern('/api/users/123', '/api/users/{id}'); // true
+matchesPathPattern('/api/v1/users', '/api/*/users'); // true
+matchesPathPattern('/files/a/b/c', '/files/**'); // true
+
+// Extract path parameters
+extractPathParams('/api/users/123', '/api/users/{id}');
+// Returns: { id: '123' }
+
+extractPathParams('/api/users/123/posts/456', '/api/users/{userId}/posts/{postId}');
+// Returns: { userId: '123', postId: '456' }
+```
+
+### Utility Functions
+
+```typescript
+import { normalizeBasePath } from '@apaas/fullstack-toolkits';
+
+// Normalize base path (adds leading slash, removes trailing slash)
+normalizeBasePath('api'); // '/api'
+normalizeBasePath('/api/'); // '/api'
+normalizeBasePath('api/v1'); // '/api/v1'
+```
+
+## API Reference
+
+### Middleware Types
+
+#### `RouteMiddleware`
+Route-based middleware that mounts at a specific path.
+
+```typescript
+interface RouteMiddleware {
+  name: string;
+  mountPath: string;  // Required - path to mount the router
+  routes?: RouteInfo[];
+  enabled?: (context: MiddlewareContext) => boolean;
+  createRouter: (context: MiddlewareContext) => Router;
+}
+```
+
+**Example:**
+```typescript
+function createDevLogsMiddleware(options): RouteMiddleware {
+  return {
+    name: 'dev-logs',
+    mountPath: '/dev/logs',
+    createRouter: (context) => createRouter(options)
+  };
+}
+```
+
+#### `GlobalMiddleware`
+Global middleware that applies to all requests.
+
+```typescript
+interface GlobalMiddleware {
+  name: string;
+  mountPath?: never;  // Must not have mountPath
+  enabled?: (context: MiddlewareContext) => boolean;
+  createHandler: (context: MiddlewareContext) => RequestHandler;
+}
+```
+
+**Example:**
+```typescript
+function createCorsMiddleware(): GlobalMiddleware {
+  return {
+    name: 'cors',
+    createHandler: () => (req, res, next) => {
+      res.setHeader('Access-Control-Allow-Origin', '*');
+      next();
+    }
+  };
+}
+```
+
+#### `Middleware`
+Union type of route-based and global middlewares.
+
+```typescript
+type Middleware = RouteMiddleware | GlobalMiddleware;
+```
+
+#### `MiddlewareContext`
+```typescript
+interface MiddlewareContext {
+  basePath: string;
+  isDev: boolean;
+  rootDir: string;
+  [key: string]: any;
+}
+```
+
+### Core Functions
+
+#### `registerMiddlewares(server, middlewares, options?): Promise<void>`
+Register middlewares for Express-compatible servers or Vite dev server.
+
+**Parameters:**
+- `server` - Express app or Vite middleware instance
+- `middlewares` - Array of middleware objects (route or global)
+- `options` - Optional context configuration
+
+**Returns:** Promise that resolves when all middlewares are registered
+
+**Example:**
+```typescript
+await registerMiddlewares(devServer.app, [
+  createCorsMiddleware(),
+  createDevLogsMiddleware({ logDir: './logs' })
+], {
+  basePath: '/api',
+  isDev: true,
+  rootDir: __dirname
+});
+```
+
+### Utility Functions
+
+#### `normalizeBasePath(basePath): string`
+Normalize base path to ensure it starts with '/' and has no trailing slash.
+
+## License
+
+MIT