@websublime/vite-plugin-open-api-server 0.19.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WebSublime
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,207 @@
+# @websublime/vite-plugin-open-api-server
+
+Vite plugin for OpenAPI mock server with DevTools integration.
+
+## Features
+
+- 🚀 **Zero-config mock server** - Automatically generates mock endpoints from OpenAPI spec
+- 🔄 **Hot reload** - Handlers and seeds reload automatically on file changes
+- 🎯 **Type-safe handlers** - Full TypeScript support with `defineHandlers()`
+- 🌱 **Seed data** - Define initial data with Faker.js integration
+- 🛠️ **DevTools** - Built-in DevTools for inspecting endpoints and data
+- ⚡ **Seamless Vite integration** - Works with Vite's proxy system
+
+## Installation
+
+```bash
+pnpm add -D @websublime/vite-plugin-open-api-server
+```
+
+## Quick Start
+
+### 1. Add the plugin to your Vite config
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+import { openApiServer } from '@websublime/vite-plugin-open-api-server';
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    openApiServer({
+      spec: './openapi/petstore.yaml',
+      port: 4000,
+      proxyPath: '/api',
+    }),
+  ],
+});
+```
+
+### 2. Create handler files (optional)
+
+```typescript
+// mocks/handlers/pets.handlers.ts
+import { defineHandlers } from '@websublime/vite-plugin-open-api-server';
+
+export default defineHandlers({
+  getPetById: async ({ req, store }) => {
+    const pet = store.get('Pet', req.params.petId);
+    if (!pet) {
+      return { status: 404, data: { message: 'Pet not found' } };
+    }
+    return pet;
+  },
+  
+  createPet: async ({ req, store, faker }) => {
+    const newPet = {
+      id: faker.number.int({ min: 1000, max: 9999 }),
+      ...req.body,
+    };
+    store.create('Pet', newPet);
+    return { status: 201, data: newPet };
+  },
+});
+```
+
+### 3. Create seed files (optional)
+
+```typescript
+// mocks/seeds/pets.seeds.ts
+import { defineSeeds } from '@websublime/vite-plugin-open-api-server';
+
+export default defineSeeds({
+  Pet: ({ seed, faker }) => {
+    return seed.count(10, () => ({
+      id: faker.number.int({ min: 1, max: 1000 }),
+      name: faker.animal.dog(),
+      category: {
+        id: faker.number.int({ min: 1, max: 5 }),
+        name: faker.helpers.arrayElement(['Dogs', 'Cats', 'Birds']),
+      },
+      status: faker.helpers.arrayElement(['available', 'pending', 'sold']),
+    }));
+  },
+});
+```
+
+### 4. Start your Vite dev server
+
+```bash
+pnpm dev
+```
+
+The mock server will start automatically and you'll see a startup banner:
+
+```text
+╭──────────────────────────────────────────────────────╮
+│              🚀 OpenAPI Mock Server                  │
+╰──────────────────────────────────────────────────────╯
+
+  API:        Swagger Petstore v1.0.0
+  Server:     http://localhost:4000
+  Proxy:      /api → localhost:4000
+
+  Endpoints: 15  │  Handlers: 2  │  Seeds: 1
+
+  DevTools:   http://localhost:4000/_devtools
+  API Info:   http://localhost:4000/_api
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `spec` | `string` | **required** | Path to OpenAPI spec file (YAML or JSON) |
+| `port` | `number` | `4000` | Mock server port |
+| `proxyPath` | `string` | `'/api'` | Vite proxy path prefix |
+| `handlersDir` | `string` | `'./mocks/handlers'` | Directory for handler files |
+| `seedsDir` | `string` | `'./mocks/seeds'` | Directory for seed files |
+| `enabled` | `boolean` | `true` | Enable/disable the plugin |
+| `idFields` | `Record<string, string>` | `{}` | ID field per schema |
+| `timelineLimit` | `number` | `500` | Max timeline events |
+| `devtools` | `boolean` | `true` | Enable DevTools |
+| `cors` | `boolean` | `true` | Enable CORS |
+| `corsOrigin` | `string \| string[]` | `'*'` | CORS origin configuration |
+| `silent` | `boolean` | `false` | Suppress startup banner |
+
+## Handler Context
+
+Handlers receive a context object with:
+
+```typescript
+interface HandlerContext {
+  req: {
+    method: string;
+    path: string;
+    params: Record<string, string>;
+    query: Record<string, string>;
+    body: unknown;
+    headers: Record<string, string>;
+  };
+  store: Store;
+  faker: Faker;
+  logger: Logger;
+}
+```
+
+## Response Formats
+
+Handlers can return data in several formats:
+
+```typescript
+// Simple data (status 200)
+return { id: 1, name: 'Fluffy' };
+
+// With status code
+return { status: 201, data: { id: 1, name: 'Fluffy' } };
+
+// With headers
+return {
+  status: 200,
+  data: { id: 1 },
+  headers: { 'X-Custom': 'value' },
+};
+```
+
+## File Naming Conventions
+
+- Handlers: `*.handlers.ts` or `*.handlers.js`
+- Seeds: `*.seeds.ts` or `*.seeds.js`
+
+## Response Priority
+
+When a request comes in, the server looks for a response in this order:
+
+1. **Custom Handler** - If defined for the operationId
+2. **Seed Data** - If data exists in the store
+3. **OpenAPI Example** - If defined in the spec
+4. **Generated Data** - Auto-generated from schema using Faker.js
+
+## Internal API
+
+The mock server exposes internal endpoints for debugging:
+
+- `/_api` - Server info and stats
+- `/_api/registry` - List all endpoints
+- `/_api/store` - View store data
+- `/_api/timeline` - Request/response history
+- `/_api/simulations` - Active error simulations
+- `/_devtools` - DevTools SPA
+
+## Requirements
+
+- **Node.js**: ^20.19.0 || >=22.12.0
+- **pnpm**: 9.x
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| `@websublime/vite-plugin-open-api-core` | Core server, store, router, generator |
+| `@websublime/vite-plugin-open-api-devtools` | Vue DevTools SPA |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,433 @@
+import { Plugin, ViteDevServer } from 'vite';
+import { Logger, HandlerFn, AnySeedFn } from '@websublime/vite-plugin-open-api-core';
+export { HandlerContext, HandlerDefinition, HandlerFn, HandlerReturn, SeedContext, SeedDefinition, SeedFn, SeedHelper, defineHandlers, defineSeeds } from '@websublime/vite-plugin-open-api-core';
+
+/**
+ * Vite Plugin Types
+ *
+ * What: Type definitions for the OpenAPI server Vite plugin
+ * How: Defines configuration options and internal types
+ * Why: Provides type safety and documentation for plugin consumers
+ *
+ * @module types
+ */
+
+/**
+ * Plugin configuration options
+ *
+ * @example
+ * ```typescript
+ * import { openApiServer } from '@websublime/vite-plugin-open-api-server';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     openApiServer({
+ *       spec: './openapi/petstore.yaml',
+ *       port: 4000,
+ *       proxyPath: '/api',
+ *       handlersDir: './mocks/handlers',
+ *       seedsDir: './mocks/seeds',
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+interface OpenApiServerOptions {
+    /**
+     * Path to OpenAPI spec file (required)
+     *
+     * Supports:
+     * - Local file paths (relative or absolute)
+     * - URLs (http:// or https://)
+     * - YAML or JSON format
+     *
+     * @example './openapi/petstore.yaml'
+     * @example 'https://petstore3.swagger.io/api/v3/openapi.json'
+     */
+    spec: string;
+    /**
+     * Server port for the mock server
+     *
+     * The mock server runs on this port, and Vite proxies
+     * requests from `proxyPath` to this server.
+     *
+     * @default 4000
+     */
+    port?: number;
+    /**
+     * Base path for request proxy
+     *
+     * All requests to this path in your Vite dev server
+     * will be proxied to the mock server.
+     *
+     * @example '/api/v3'
+     * @default '/api'
+     */
+    proxyPath?: string;
+    /**
+     * Directory containing handler files
+     *
+     * Handler files should export an object with operationId keys
+     * and handler functions as values. Use `defineHandlers()` for
+     * type-safe handler definitions.
+     *
+     * @example './mocks/handlers'
+     * @default './mocks/handlers'
+     */
+    handlersDir?: string;
+    /**
+     * Directory containing seed files
+     *
+     * Seed files should export an object with schema name keys
+     * and seed functions as values. Use `defineSeeds()` for
+     * type-safe seed definitions.
+     *
+     * @example './mocks/seeds'
+     * @default './mocks/seeds'
+     */
+    seedsDir?: string;
+    /**
+     * Enable/disable the plugin
+     *
+     * When false, the plugin does nothing and Vite runs normally.
+     * Useful for conditional enabling based on environment.
+     *
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * ID field configuration per schema
+     *
+     * Maps schema names to the field used as the primary identifier.
+     * Used by the store for CRUD operations.
+     *
+     * @example { User: 'username', Order: 'orderId' }
+     * @default {} (uses 'id' for all schemas)
+     */
+    idFields?: Record<string, string>;
+    /**
+     * Maximum timeline events to keep
+     *
+     * The timeline stores request/response history for DevTools.
+     * Older events are removed when this limit is exceeded.
+     *
+     * @default 500
+     */
+    timelineLimit?: number;
+    /**
+     * Enable DevTools integration
+     *
+     * When true, mounts the DevTools SPA at `/_devtools`
+     * and enables Vue DevTools custom tab.
+     *
+     * @default true
+     */
+    devtools?: boolean;
+    /**
+     * Enable CORS on the mock server
+     *
+     * @default true
+     */
+    cors?: boolean;
+    /**
+     * CORS origin configuration
+     *
+     * @default '*'
+     */
+    corsOrigin?: string | string[];
+    /**
+     * Custom logger instance
+     *
+     * Defaults to a Vite-integrated logger that respects
+     * Vite's logging level settings.
+     */
+    logger?: Logger;
+    /**
+     * Suppress startup banner
+     *
+     * When true, the plugin won't print the startup banner
+     * showing server details and loaded handlers/seeds.
+     *
+     * @default false
+     */
+    silent?: boolean;
+}
+/**
+ * Resolved plugin options with defaults applied
+ *
+ * @internal
+ */
+interface ResolvedOptions {
+    spec: string;
+    port: number;
+    proxyPath: string;
+    handlersDir: string;
+    seedsDir: string;
+    enabled: boolean;
+    idFields: Record<string, string>;
+    timelineLimit: number;
+    devtools: boolean;
+    cors: boolean;
+    corsOrigin: string | string[];
+    silent: boolean;
+    logger?: Logger;
+}
+
+/**
+ * Vite Plugin Implementation
+ *
+ * What: Main Vite plugin for OpenAPI mock server
+ * How: Uses configureServer hook to start mock server and configure proxy
+ * Why: Integrates OpenAPI mock server seamlessly into Vite dev workflow
+ *
+ * @module plugin
+ */
+
+/**
+ * Create the OpenAPI Server Vite plugin
+ *
+ * This plugin starts a mock server based on an OpenAPI specification
+ * and configures Vite to proxy API requests to it.
+ *
+ * @example
+ * ```typescript
+ * // vite.config.ts
+ * import { defineConfig } from 'vite';
+ * import vue from '@vitejs/plugin-vue';
+ * import { openApiServer } from '@websublime/vite-plugin-open-api-server';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     vue(),
+ *     openApiServer({
+ *       spec: './openapi/petstore.yaml',
+ *       port: 4000,
+ *       proxyPath: '/api',
+ *       handlersDir: './mocks/handlers',
+ *       seedsDir: './mocks/seeds',
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * @param options - Plugin configuration options
+ * @returns Vite plugin
+ */
+declare function openApiServer(options: OpenApiServerOptions): Plugin;
+
+/**
+ * Handler Loading
+ *
+ * What: Loads handler files from a directory using glob patterns
+ * How: Uses Vite's ssrLoadModule to transform and load TypeScript files
+ * Why: Enables users to define custom handlers for operationIds in TypeScript
+ *
+ * @module handlers
+ */
+
+/**
+ * Result of loading handlers
+ */
+interface LoadHandlersResult {
+    /** Map of operationId to handler function */
+    handlers: Map<string, HandlerFn>;
+    /** Number of handler files loaded */
+    fileCount: number;
+    /** List of loaded file paths (relative) */
+    files: string[];
+}
+/**
+ * Load handlers from a directory
+ *
+ * Searches for handler files matching the pattern `*.handlers.{ts,js,mjs}`
+ * in the specified directory. Each file should export an object with
+ * operationId keys and handler functions as values.
+ *
+ * Uses Vite's ssrLoadModule to transform TypeScript files on-the-fly.
+ *
+ * @example
+ * ```typescript
+ * // mocks/handlers/pets.handlers.ts
+ * import { defineHandlers } from '@websublime/vite-plugin-open-api-core';
+ *
+ * export default defineHandlers({
+ *   getPetById: async ({ req, store }) => {
+ *     const pet = store.get('Pet', req.params.petId);
+ *     return pet ?? { status: 404, data: { message: 'Pet not found' } };
+ *   },
+ * });
+ * ```
+ *
+ * @param handlersDir - Directory to search for handler files
+ * @param viteServer - Vite dev server instance for ssrLoadModule
+ * @param cwd - Current working directory (defaults to process.cwd())
+ * @param logger - Optional logger for warnings/errors
+ * @returns Promise resolving to loaded handlers
+ */
+declare function loadHandlers(handlersDir: string, viteServer: ViteDevServer, cwd?: string, logger?: Logger): Promise<LoadHandlersResult>;
+/**
+ * Get list of handler files in a directory
+ *
+ * Useful for file watching setup.
+ *
+ * @param handlersDir - Directory to search
+ * @param cwd - Current working directory
+ * @returns Promise resolving to list of absolute file paths
+ */
+declare function getHandlerFiles(handlersDir: string, cwd?: string): Promise<string[]>;
+
+/**
+ * Seed Loading
+ *
+ * What: Loads seed files from a directory using glob patterns
+ * How: Uses Vite's ssrLoadModule to transform and load TypeScript files
+ * Why: Enables users to define seed data for schemas in TypeScript
+ *
+ * @module seeds
+ */
+
+/**
+ * Result of loading seeds
+ */
+interface LoadSeedsResult {
+    /** Map of schema name to seed function */
+    seeds: Map<string, AnySeedFn>;
+    /** Number of seed files loaded */
+    fileCount: number;
+    /** List of loaded file paths (relative) */
+    files: string[];
+}
+/**
+ * Load seeds from a directory
+ *
+ * Searches for seed files matching the pattern `*.seeds.{ts,js,mjs}`
+ * in the specified directory. Each file should export an object with
+ * schema name keys and seed functions as values.
+ *
+ * Uses Vite's ssrLoadModule to transform TypeScript files on-the-fly.
+ *
+ * @example
+ * ```typescript
+ * // mocks/seeds/pets.seeds.ts
+ * import { defineSeeds } from '@websublime/vite-plugin-open-api-core';
+ *
+ * export default defineSeeds({
+ *   Pet: ({ seed, faker }) => {
+ *     return seed.count(10, () => ({
+ *       id: faker.number.int({ min: 1, max: 1000 }),
+ *       name: faker.animal.dog(),
+ *       status: faker.helpers.arrayElement(['available', 'pending', 'sold']),
+ *     }));
+ *   },
+ * });
+ * ```
+ *
+ * @param seedsDir - Directory to search for seed files
+ * @param viteServer - Vite dev server instance for ssrLoadModule
+ * @param cwd - Current working directory (defaults to process.cwd())
+ * @param logger - Optional logger for warnings/errors
+ * @returns Promise resolving to loaded seeds
+ */
+declare function loadSeeds(seedsDir: string, viteServer: ViteDevServer, cwd?: string, logger?: Logger): Promise<LoadSeedsResult>;
+/**
+ * Get list of seed files in a directory
+ *
+ * Useful for file watching setup.
+ *
+ * @param seedsDir - Directory to search
+ * @param cwd - Current working directory
+ * @returns Promise resolving to list of absolute file paths
+ */
+declare function getSeedFiles(seedsDir: string, cwd?: string): Promise<string[]>;
+
+/**
+ * Hot Reload
+ *
+ * What: File watcher for hot reloading handlers and seeds
+ * How: Uses chokidar to watch for file changes
+ * Why: Enables rapid development iteration without server restart
+ *
+ * @module hot-reload
+ *
+ * TODO: Full implementation in Task 3.3
+ * This module provides placeholder/basic functionality for Task 3.1
+ */
+
+/**
+ * File watcher configuration
+ */
+interface FileWatcherOptions {
+    /** Directory containing handler files */
+    handlersDir?: string;
+    /** Directory containing seed files */
+    seedsDir?: string;
+    /** Callback when a handler file changes */
+    onHandlerChange?: (filePath: string) => Promise<void> | void;
+    /** Callback when a seed file changes */
+    onSeedChange?: (filePath: string) => Promise<void> | void;
+    /** Current working directory */
+    cwd?: string;
+    /** Logger for error messages */
+    logger?: Logger;
+}
+/**
+ * File watcher instance
+ */
+interface FileWatcher {
+    /** Close the watcher and release resources */
+    close(): Promise<void>;
+    /** Check if watcher is active */
+    readonly isWatching: boolean;
+    /** Promise that resolves when all watchers are ready */
+    readonly ready: Promise<void>;
+}
+/**
+ * Create a file watcher for handlers and seeds
+ *
+ * Watches for changes to handler and seed files and invokes
+ * callbacks when changes are detected. Supports add, change,
+ * and unlink events.
+ *
+ * @example
+ * ```typescript
+ * const watcher = await createFileWatcher({
+ *   handlersDir: './mocks/handlers',
+ *   seedsDir: './mocks/seeds',
+ *   onHandlerChange: async (file) => {
+ *     console.log('Handler changed:', file);
+ *     const handlers = await loadHandlers('./mocks/handlers');
+ *     server.updateHandlers(handlers.handlers);
+ *   },
+ *   onSeedChange: async (file) => {
+ *     console.log('Seed changed:', file);
+ *     const seeds = await loadSeeds('./mocks/seeds');
+ *     // Re-execute seeds...
+ *   },
+ * });
+ *
+ * // Later, clean up
+ * await watcher.close();
+ * ```
+ *
+ * @param options - Watcher configuration
+ * @returns Promise resolving to file watcher instance
+ */
+declare function createFileWatcher(options: FileWatcherOptions): Promise<FileWatcher>;
+/**
+ * Debounce a function with async execution guard
+ *
+ * Useful for preventing multiple rapid reloads when
+ * multiple files change at once (e.g., during save all).
+ *
+ * This implementation prevents overlapping async executions:
+ * - If the function is already running, the call is queued
+ * - When the running function completes, it executes with the latest args
+ * - Multiple calls during execution are coalesced into one
+ *
+ * @param fn - Function to debounce (can be sync or async)
+ * @param delay - Debounce delay in milliseconds
+ * @returns Debounced function
+ */
+declare function debounce<T extends (...args: unknown[]) => unknown>(fn: T, delay: number): (...args: Parameters<T>) => void;
+
+export { type FileWatcher, type FileWatcherOptions, type LoadHandlersResult, type LoadSeedsResult, type OpenApiServerOptions, type ResolvedOptions, createFileWatcher, debounce, getHandlerFiles, getSeedFiles, loadHandlers, loadSeeds, openApiServer };