vite-plugin-automock 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025 vite-plugin-automock contributors
+
+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.
+
+THE SOFTWARE IS PROVIDED "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,350 @@
+# vite-plugin-automock
+
+Effortless API mock auto-generation for legacy projects. No manual files, just automock!
+
+---
+
+## Features
+
+- 🚀 Automatically captures API requests and generates local mock data
+- 🏆 Perfect for legacy projects, easily backfill missing mocks
+- 🛠️ Supports manual mock file creation with a simple format
+- ⚡ Zero-config, plug-and-play
+- 🧩 Fully compatible with the Vite plugin ecosystem
+- 📦 Production-ready with client-side interceptor
+- 🎛️ Visual mock inspector panel
+
+## Installation
+
+```bash
+pnpm add -D vite-plugin-automock
+# or
+npm install --save-dev vite-plugin-automock
+# or
+yarn add -D vite-plugin-automock
+```
+
+## Quick Start
+
+### 1. Configure Vite Plugin
+
+```typescript
+// vite.config.ts
+import { automock } from 'vite-plugin-automock'
+
+export default defineConfig({
+  plugins: [
+    automock({
+      mockDir: 'mock',
+      apiPrefix: '/api',
+      bundleMockData: true,      // Bundle mock data for production
+      productionMock: true,       // Enable mock in production
+      proxyBaseUrl: 'https://api.example.com'
+    })
+  ]
+})
+```
+
+### 2. Create Mock Files
+
+```typescript
+// mock/users.ts
+import { MockFileConfig } from 'vite-plugin-automock'
+
+export default {
+  enable: true,
+  data: { users: [{ id: 1, name: 'Alice' }] },
+  delay: 100,
+  status: 200
+} as MockFileConfig
+```
+
+### 3. Initialize Client Interceptor
+
+For PureHttp wrapper:
+
+```typescript
+// src/main.ts or src/api/index.ts
+import {
+  initMockInterceptorForPureHttp,
+  setMockEnabled,
+  registerHttpInstance
+} from 'vite-plugin-automock/client'
+import { http } from './http' // Your PureHttp instance
+
+// Register your http instance
+registerHttpInstance(http)
+
+// Initialize mock interceptor
+initMockInterceptorForPureHttp()
+  .then(() => {
+    console.log('[MockInterceptor] Initialized successfully')
+  })
+  .catch(error => {
+    console.error('[MockInterceptor] Failed to initialize:', error)
+  })
+
+// Enable mock in development
+if (import.meta.env.DEV) {
+  setMockEnabled(true)
+}
+```
+
+For plain Axios:
+
+```typescript
+// src/main.ts
+import { initMockInterceptor, setMockEnabled } from 'vite-plugin-automock/client'
+import axios from 'axios'
+
+// Initialize with axios instance
+initMockInterceptor(axios)
+  .then(() => {
+    console.log('[MockInterceptor] Initialized successfully')
+  })
+  .catch(error => {
+    console.error('[MockInterceptor] Failed to initialize:', error)
+  })
+
+// Enable mock in development
+if (import.meta.env.DEV) {
+  setMockEnabled(true)
+}
+```
+
+## Documentation
+
+For detailed usage instructions, configuration options, and examples, see:
+
+**[📚 Complete Usage Guide](./docs/USAGE_GUIDE.md)**
+
+Topics covered:
+- Development vs Production modes
+- Client interceptor configuration
+- Runtime mock toggle
+- Visual inspector
+- API reference
+- Common scenarios
+
+---
+
+## Basic Usage (Development Mode)
+
+Import and register the plugin in your `vite.config.ts`:
+
+```js
+import { automock } from "vite-plugin-automock";
+
+export default {
+  plugins: [
+    automock({
+      proxyBaseUrl: "http://localhost:8888", // Required: Your API server URL
+      mockDir: "mock", // Optional: Directory for mock files (default: 'mock')
+      apiPrefix: "/api", // Optional: API prefix to intercept (default: '/api')
+      pathRewrite: (path) => path, // Optional: Path rewrite function
+      inspector: true, // Optional: Enable visual inspector (default: false)
+    }),
+  ],
+};
+```
+
+### With Custom Inspector Configuration
+
+```js
+automock({
+  proxyBaseUrl: "http://localhost:8888",
+  inspector: {
+    route: "/__inspector/", // Custom route for inspector UI
+    enableToggle: true, // Allow toggling enable/disable
+  },
+});
+```
+
+## Configuration Options
+
+| Option         | Type              | Required | Default          | Description                       |
+| -------------- | ----------------- | -------- | ---------------- | --------------------------------- |
+| `proxyBaseUrl` | string            | ✅       | -                | Base URL of your API server       |
+| `mockDir`      | string            | ❌       | `'mock'`         | Directory to store mock files     |
+| `apiPrefix`    | string            | ❌       | `'/api'`         | API path prefix to intercept      |
+| `pathRewrite`  | function          | ❌       | `(path) => path` | Function to rewrite request paths |
+| `inspector`    | boolean \| object | ❌       | `false`          | Enable visual mock inspector UI   |
+
+### Inspector Options
+
+When `inspector` is an object, you can customize:
+
+| Option         | Type    | Default      | Description                        |
+| -------------- | ------- | ------------ | ---------------------------------- |
+| `route`        | string  | `'/__mock/'` | Route path for the inspector UI    |
+| `enableToggle` | boolean | `true`       | Allow toggling mock enable/disable |
+
+## Mock Inspector 🎨
+
+**NEW!** Visual interface to manage your mock files:
+
+```js
+automock({
+  proxyBaseUrl: "http://localhost:8888",
+  inspector: true, // Enable inspector UI
+});
+```
+
+Then visit `http://localhost:5173/__mock/` to:
+
+- 📋 **Browse** all mock files organized by URL
+- 🎛️ **Toggle** mock enable/disable status
+- ⏱️ **Adjust** response delay and status codes
+- ✏️ **Edit** JSON response data directly
+- 💾 **Save** changes with a single click
+
+![Inspector Demo](https://via.placeholder.com/800x400?text=Mock+Inspector+UI)
+
+## How It Works
+
+1. **Request Interception**: The plugin intercepts all requests matching the `apiPrefix`
+2. **Mock Check**: Checks if a corresponding mock file exists
+3. **Conditional Response**:
+   - If mock exists → Returns mock data
+   - If mock doesn't exist → Proxies to real API and saves response as mock
+4. **Auto-Generation**: Real API responses are automatically saved as mock files
+5. **Hot Reloading**: Changes to mock files are automatically detected and reloaded
+6. **Visual Inspector**: Manage and edit mocks through the web UI
+
+## Mock File Structure
+
+Mock files are organized by URL path and HTTP method:
+
+```
+mock/
+├── api/
+│   ├── users/
+│   │   ├── get.js     # GET /api/users
+│   │   └── post.js    # POST /api/users
+│   └── items/
+│       ├── get.js     # GET /api/items
+│       └── post.js    # POST /api/items
+```
+
+Each mock file exports an object with this structure:
+
+```javascript
+/**
+ * Mock data for /api/users (GET)
+ * Generated at 2025-01-11T10:30:00.000Z
+ */
+export default {
+  enable: false, // Whether to use this mock (default: false)
+  data: {
+    // Response data
+    code: 0,
+    message: "success",
+    data: [
+      { id: 1, name: "User 1" },
+      { id: 2, name: "User 2" },
+    ],
+  },
+  delay: 0, // Artificial delay in milliseconds
+  status: 200, // HTTP status code
+};
+```
+
+## Quick Start
+
+1. **Try the Example**:
+
+   ```bash
+   pnpm run example
+   ```
+
+   This starts the playground with a demo API server.
+
+2. **Manual Setup**:
+
+   ```bash
+   # Install the plugin
+   pnpm add -D vite-plugin-automock
+
+   # Add to your vite.config.js
+   import { automock } from "vite-plugin-automock";
+
+   export default {
+     plugins: [
+       automock({
+         proxyBaseUrl: "http://localhost:8888"
+       })
+     ]
+   };
+   ```
+
+3. **Start Development**:
+   - Start your API server
+   - Start Vite dev server
+   - Make API calls from your frontend
+   - Check the mock directory for generated files
+
+## Comparison with Traditional Mock Plugins
+
+| Feature                | Traditional Mock Plugins | vite-plugin-automock |
+| ---------------------- | ------------------------ | -------------------- |
+| Auto backfill          | ❌                       | ✅                   |
+| Legacy project support | ❌                       | ✅                   |
+| Manual mock files      | ✅                       | ✅                   |
+| Config complexity      | High                     | Very low             |
+| Zero setup             | ❌                       | ✅                   |
+| Real API integration   | ❌                       | ✅                   |
+
+## When to Use
+
+- **Legacy Projects**: Quickly add mock capability to existing projects
+- **API Development**: Test frontend while backend is being developed
+- **Offline Development**: Work without internet or when APIs are unavailable
+- **Testing**: Consistent test data without external dependencies
+- **Demo/Presentation**: Reliable demo data that doesn't change
+
+## Advanced Usage
+
+### Custom Path Rewriting
+
+```javascript
+automock({
+  proxyBaseUrl: "http://api.example.com",
+  pathRewrite: (path) => {
+    // Remove /api prefix when proxying
+    return path.replace(/^\/api/, "");
+  },
+});
+```
+
+### Conditional Mock Enabling
+
+```javascript
+// In your mock file
+export default {
+  enable: process.env.NODE_ENV === "development",
+  data: {
+    /* mock data */
+  },
+};
+```
+
+### Dynamic Mock Data
+
+```javascript
+// In your mock file
+export default {
+  enable: true,
+  data: () => ({
+    timestamp: new Date().toISOString(),
+    randomId: Math.floor(Math.random() * 1000),
+  }),
+};
+```
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+## License
+
+ISC

package/dist/chunk-KZB7ARYV.mjs

@@ -0,0 +1,338 @@
+// src/mockFileUtils.ts
+import path from "path";
+import fs from "fs-extra";
+import prettier from "prettier";
+var DEFAULT_CONFIG = {
+  enable: true,
+  data: null,
+  delay: 0,
+  status: 200
+};
+function toPosixPath(p) {
+  return p.replace(/\\/g, "/");
+}
+var isBinaryResponse = (contentType, data) => {
+  if (!contentType) return false;
+  const binaryTypes = [
+    "application/octet-stream",
+    "application/pdf",
+    "application/zip",
+    "application/x-zip-compressed",
+    "application/vnd.ms-excel",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "application/msword",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "application/vnd.ms-powerpoint",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    "image/",
+    "video/",
+    "audio/"
+  ];
+  return binaryTypes.some((type) => contentType.toLowerCase().includes(type)) || !isBufferTextLike(data);
+};
+var isBufferTextLike = (buffer) => {
+  try {
+    const sample = buffer.slice(0, 100);
+    const text = sample.toString("utf8");
+    const nullBytes = [...sample].filter((b) => b === 0).length;
+    const controlChars = [...sample].filter(
+      (b) => b < 32 && b !== 9 && b !== 10 && b !== 13
+    ).length;
+    return nullBytes === 0 && controlChars < 5;
+  } catch {
+    return false;
+  }
+};
+var getFileExtension = (contentType, url) => {
+  const mimeMap = {
+    "application/json": "json",
+    "application/pdf": "pdf",
+    "application/zip": "zip",
+    "application/vnd.ms-excel": "xls",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": "xlsx",
+    "application/msword": "doc",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "docx",
+    "application/vnd.ms-powerpoint": "ppt",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation": "pptx",
+    "image/jpeg": "jpg",
+    "image/png": "png",
+    "image/gif": "gif",
+    "text/plain": "txt",
+    "text/html": "html",
+    "text/css": "css",
+    "application/javascript": "js",
+    "text/xml": "xml"
+  };
+  if (contentType && mimeMap[contentType.toLowerCase()]) {
+    return mimeMap[contentType.toLowerCase()];
+  }
+  try {
+    const urlObj = new URL(url, "http://localhost");
+    const fileName = urlObj.searchParams.get("file_name");
+    if (fileName) {
+      const extensionMatch = fileName.match(/\.([a-zA-Z0-9]+)$/);
+      if (extensionMatch) {
+        return extensionMatch[1];
+      }
+    }
+  } catch (error) {
+  }
+  return "bin";
+};
+var saveMockData = async (url, method, data, rootDir, statusCode, contentType) => {
+  try {
+    const absoluteRootDir = path.isAbsolute(rootDir) ? rootDir : path.resolve(process.cwd(), rootDir);
+    let pathname;
+    let search;
+    try {
+      if (url.startsWith("http")) {
+        const urlObj = new URL(url);
+        pathname = urlObj.pathname;
+        search = urlObj.search;
+      } else {
+        const urlObj = new URL(url, "http://localhost");
+        pathname = urlObj.pathname;
+        search = urlObj.search;
+      }
+    } catch (error) {
+      const [pathPart, ...searchPart] = url.split("?");
+      pathname = pathPart;
+      search = searchPart.length > 0 ? "?" + searchPart.join("?") : "";
+    }
+    const filePath = path.join(
+      absoluteRootDir,
+      pathname.replace(/^\//, ""),
+      method.toLowerCase() + ".js"
+    );
+    const dir = path.dirname(filePath);
+    fs.ensureDirSync(dir);
+    const isBuffer = Buffer.isBuffer(data);
+    const binaryData = isBuffer ? data : Buffer.from(data || "");
+    const isBinary = isBinaryResponse(contentType, binaryData);
+    if (isBinary) {
+      const extension = getFileExtension(contentType, url);
+      const binaryFilePath = filePath.replace(/\.js$/, "." + extension);
+      if (fs.existsSync(binaryFilePath)) {
+        return null;
+      }
+      fs.writeFileSync(binaryFilePath, binaryData);
+      const configContent = `/**
+ * Mock data for ${pathname} (${method.toUpperCase()})${search || ""}
+ * @description ${pathname}${search || ""} - Binary file (${extension})
+ * Generated at ${(/* @__PURE__ */ new Date()).toISOString()}
+ */
+export default {
+  enable: false,
+  data: {
+    __binaryFile: '${extension}',
+    __originalPath: '${pathname}',
+    __originalQuery: '${search}',
+    __originalUrl: '${pathname}${search || ""}',
+    __contentType: '${contentType}',
+    __fileSize: ${binaryData.length}
+  },
+  delay: 0,
+  status: ${statusCode || 200}
+}`;
+      try {
+        const formattedCode = await prettier.format(configContent, {
+          parser: "babel"
+        });
+        fs.writeFileSync(filePath, formattedCode, "utf-8");
+      } catch (error) {
+        fs.writeFileSync(filePath, configContent, "utf-8");
+      }
+      return filePath;
+    } else {
+      if (fs.existsSync(filePath)) {
+        return null;
+      }
+      const dataStr = isBuffer ? data.toString("utf8") : data || "";
+      let jsonData;
+      if (!dataStr || dataStr.trim() === "") {
+        jsonData = {
+          error: true,
+          message: `Empty response (${statusCode || "unknown status"})`,
+          status: statusCode || 404,
+          data: null
+        };
+      } else {
+        try {
+          jsonData = JSON.parse(dataStr);
+          if (statusCode && statusCode >= 400) {
+            if (typeof jsonData === "object" && jsonData !== null) {
+              jsonData = {
+                ...jsonData,
+                __mockStatusCode: statusCode,
+                __isErrorResponse: true
+              };
+            } else {
+              jsonData = {
+                originalData: jsonData,
+                __mockStatusCode: statusCode,
+                __isErrorResponse: true
+              };
+            }
+          }
+        } catch {
+          jsonData = {
+            error: true,
+            message: `Non-JSON response (${statusCode || "unknown status"})`,
+            status: statusCode || 404,
+            data: dataStr,
+            __mockStatusCode: statusCode,
+            __isErrorResponse: true
+          };
+        }
+      }
+      const content = `/**
+ * Mock data for ${pathname} (${method.toUpperCase()})${search || ""}
+ * @description ${pathname}${search || ""}
+ * Generated at ${(/* @__PURE__ */ new Date()).toISOString()}
+ */
+export default {
+  enable: false,
+  data: ${JSON.stringify(jsonData)},
+  delay: 0,
+  status: ${statusCode || 200}
+}`;
+      try {
+        const formattedCode = await prettier.format(content, {
+          parser: "babel"
+        });
+        fs.writeFileSync(filePath, formattedCode, "utf-8");
+        return filePath;
+      } catch (error) {
+        fs.writeFileSync(filePath, content, "utf-8");
+        return filePath;
+      }
+    }
+  } catch (error) {
+    console.error(`Failed to save mock data for ${url}:`, error);
+    console.error(
+      `URL details: url=${url}, method=${method}, statusCode=${statusCode}, contentType=${contentType}`
+    );
+    throw error;
+  }
+};
+var recursiveReadAllFiles = (dir) => {
+  if (!fs.existsSync(dir)) return [];
+  const files = [];
+  try {
+    const list = fs.readdirSync(dir);
+    list.forEach((file) => {
+      const filePath = path.join(dir, file);
+      const stat = fs.statSync(filePath);
+      if (stat.isDirectory()) {
+        files.push(...recursiveReadAllFiles(filePath));
+      } else {
+        files.push(filePath);
+      }
+    });
+  } catch (error) {
+    console.error(`Error reading directory ${dir}:`, error);
+  }
+  return files;
+};
+var buildMockIndex = (mockDir) => {
+  const mockFileMap = /* @__PURE__ */ new Map();
+  if (!fs.existsSync(mockDir)) {
+    fs.ensureDirSync(mockDir);
+    return mockFileMap;
+  }
+  const files = recursiveReadAllFiles(mockDir);
+  files.forEach((filePath) => {
+    if (!filePath.endsWith(".js")) {
+      return;
+    }
+    try {
+      const relativePath = path.relative(mockDir, filePath);
+      const method = path.basename(filePath, ".js");
+      const dirPath = path.dirname(relativePath);
+      const urlPath = "/" + toPosixPath(dirPath);
+      const absolutePath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+      const key = `${urlPath}/${method}.js`.toLowerCase();
+      mockFileMap.set(key, absolutePath);
+    } catch (error) {
+      console.error(`\u274C [automock] \u5904\u7406\u6587\u4EF6\u5931\u8D25 ${filePath}:`, error);
+    }
+  });
+  return mockFileMap;
+};
+var parseMockModule = async (filePath) => {
+  const absolutePath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+  if (!fs.existsSync(absolutePath)) {
+    throw new Error(`Mock file does not exist: ${absolutePath}`);
+  }
+  const content = fs.readFileSync(absolutePath, "utf-8");
+  const headerCommentMatch = content.match(/^(\/\*\*[\s\S]*?\*\/)/);
+  const headerComment = headerCommentMatch ? headerCommentMatch[1] : void 0;
+  let description;
+  if (headerComment) {
+    const descMatch = headerComment.match(/@description\s+(.+?)(?:\n|\*\/)/s);
+    if (descMatch) {
+      description = descMatch[1].trim();
+    }
+  }
+  const { default: mockModule } = await import(`${absolutePath}?t=${Date.now()}`);
+  const exportedConfig = typeof mockModule === "function" ? mockModule() : mockModule;
+  const hasDynamicData = typeof exportedConfig?.data === "function";
+  const config = {
+    ...DEFAULT_CONFIG,
+    ...exportedConfig ?? {}
+  };
+  const serializable = !hasDynamicData;
+  const dataObj = typeof config.data === "object" && config.data !== null ? config.data : null;
+  const isBinary = dataObj !== null && "__binaryFile" in dataObj;
+  return {
+    config,
+    serializable,
+    hasDynamicData,
+    headerComment,
+    description,
+    dataText: isBinary ? `/* Binary file: ${dataObj?.__binaryFile} */` : serializable ? JSON.stringify(config.data ?? null, null, 2) : "/* data is generated dynamically and cannot be edited here */",
+    isBinary
+  };
+};
+var writeMockFile = async (filePath, mockInfo) => {
+  const absolutePath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+  let header = mockInfo.headerComment || "";
+  if (mockInfo.description !== void 0) {
+    if (header) {
+      if (/@description/.test(header)) {
+        header = header.replace(
+          /@description\s+.+?(?=\n|\*\/)/s,
+          `@description ${mockInfo.description}`
+        );
+      } else {
+        header = header.replace(
+          /\*\//,
+          ` * @description ${mockInfo.description}
+ */`
+        );
+      }
+    }
+  }
+  const content = header ? `${header}
+` : "";
+  const finalContent = `${content}export default ${JSON.stringify(mockInfo.config, null, 2)}
+`;
+  try {
+    const formattedCode = await prettier.format(finalContent, {
+      parser: "babel"
+    });
+    fs.writeFileSync(absolutePath, formattedCode, "utf-8");
+  } catch (error) {
+    console.error("Error formatting code with prettier:", error);
+    fs.writeFileSync(absolutePath, finalContent, "utf-8");
+  }
+};
+
+export {
+  DEFAULT_CONFIG,
+  saveMockData,
+  buildMockIndex,
+  parseMockModule,
+  writeMockFile
+};
+//# sourceMappingURL=chunk-KZB7ARYV.mjs.map