@websublime/vite-plugin-open-api-server 0.24.0-next.5 → 0.24.0-next.7

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Plugin, ViteDevServer } from 'vite';
-import { Logger, SpecInfo, OpenApiServer, HandlerFn, AnySeedFn } from '@websublime/vite-plugin-open-api-core';
+import { Logger, SpecInfo, OpenApiServer, WebSocketHub, HandlerFn, AnySeedFn } from '@websublime/vite-plugin-open-api-core';
 export { HandlerContext, HandlerDefinition, HandlerFn, HandlerReturn, SecurityContext, SeedContext, SeedDefinition, SeedFn, SeedHelper, defineHandlers, defineSeeds } from '@websublime/vite-plugin-open-api-core';
 import { OpenAPIV3_1 } from '@scalar/openapi-types';
 import { Hono } from 'hono';
@@ -510,6 +510,19 @@ interface OrchestratorResult {
     instances: SpecInstance[];
     /** Spec metadata array for WebSocket `connected` event */
     specsInfo: SpecInfo[];
+    /**
+     * Shared WebSocket hub for the orchestrator.
+     *
+     * Created with `autoConnect: false` so the orchestrator controls
+     * the `connected` event (enhanced with `specs` metadata).
+     *
+     * In multi-spec mode (Epic 3, Task 3.1), this hub will be replaced by
+     * `createMultiSpecWebSocketHub()` which also wires broadcast interception
+     * and multi-spec command routing.
+     *
+     * @experimental Will be replaced by `createMultiSpecWebSocketHub()` in Epic 3.
+     */
+    wsHub: WebSocketHub;
     /** Start the shared HTTP server on the configured port */
     start(): Promise<void>;
     /** Stop the HTTP server and clean up resources */
@@ -712,14 +725,12 @@ 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
+ * What: File watcher for hot reloading handlers and seeds with per-spec isolation
+ * How: Uses chokidar to watch for file changes, one watcher per spec instance
+ * Why: Enables rapid development iteration without server restart; per-spec
+ *       isolation ensures handler/seed changes in one spec don't affect others
  *
  * @module hot-reload
- *
- * TODO: Full implementation in Task 3.3
- * This module provides placeholder/basic functionality for Task 3.1
  */
 
 /**
@@ -782,6 +793,14 @@ interface FileWatcher {
  * @returns Promise resolving to file watcher instance
  */
 declare function createFileWatcher(options: FileWatcherOptions): Promise<FileWatcher>;
+/**
+ * Debounced function with cancel support
+ */
+interface DebouncedFunction<T extends (...args: unknown[]) => unknown> {
+    (...args: Parameters<T>): void;
+    /** Cancel any pending debounce timer and queued execution */
+    cancel(): void;
+}
 /**
  * Debounce a function with async execution guard
  *
@@ -795,9 +814,50 @@ declare function createFileWatcher(options: FileWatcherOptions): Promise<FileWat
  *
  * @param fn - Function to debounce (can be sync or async)
  * @param delay - Debounce delay in milliseconds
- * @returns Debounced function
+ * @returns Debounced function with cancel() method
+ */
+declare function debounce<T extends (...args: unknown[]) => unknown>(fn: T, delay: number): DebouncedFunction<T>;
+/**
+ * Create file watchers for all spec instances
+ *
+ * Each spec gets independent watchers for its handlers and seeds directories.
+ * Changes to one spec's files only trigger reload for that spec instance.
+ *
+ * @param instances - All spec instances to watch
+ * @param vite - Vite dev server (for ssrLoadModule / module invalidation)
+ * @param cwd - Project root directory
+ * @param options - Resolved plugin options
+ * @returns Promise resolving to array of file watchers (one per spec)
+ */
+declare function createPerSpecFileWatchers(instances: SpecInstance[], vite: ViteDevServer, cwd: string, options: ResolvedOptions): Promise<FileWatcher[]>;
+/**
+ * Reload handlers for a specific spec instance
+ *
+ * Loads fresh handlers from disk via Vite's ssrLoadModule, updates
+ * the spec's server, broadcasts a WebSocket event, and logs the result.
+ *
+ * @param instance - The spec instance to reload handlers for
+ * @param vite - Vite dev server
+ * @param cwd - Project root directory
+ * @param options - Resolved plugin options
+ */
+declare function reloadSpecHandlers(instance: SpecInstance, vite: ViteDevServer, cwd: string, options: ResolvedOptions): Promise<void>;
+/**
+ * Reload seeds for a specific spec instance
+ *
+ * Loads fresh seeds from disk, clears the spec's store, and re-executes
+ * seeds. Broadcasts a WebSocket event and logs the result.
+ *
+ * Note: This operation is not fully atomic — there's a brief window between
+ * clearing the store and repopulating it where requests may see empty data.
+ * For development tooling, this tradeoff is acceptable.
+ *
+ * @param instance - The spec instance to reload seeds for
+ * @param vite - Vite dev server
+ * @param cwd - Project root directory
+ * @param options - Resolved plugin options
  */
-declare function debounce<T extends (...args: unknown[]) => unknown>(fn: T, delay: number): (...args: Parameters<T>) => void;
+declare function reloadSpecSeeds(instance: SpecInstance, vite: ViteDevServer, cwd: string, options: ResolvedOptions): Promise<void>;
 
 /**
  * Vue DevTools Integration
@@ -880,4 +940,4 @@ declare function registerDevTools(app: App, options?: RegisterDevToolsOptions):
  */
 declare function getDevToolsUrl(port?: number, host?: string, protocol?: 'http' | 'https'): string;
 
-export { API_PROXY_PATH, DEVTOOLS_PROXY_PATH, type DeriveProxyPathResult, type FileWatcher, type FileWatcherOptions, type LoadHandlersResult, type LoadSeedsResult, type OpenApiServerOptions, type OrchestratorResult, type ProxyPathSource, type RegisterDevToolsOptions, type ResolvedOptions, type ResolvedSpecConfig, SPEC_COLORS, type SpecConfig, type SpecInstance, ValidationError, type ValidationErrorCode, WS_PROXY_PATH, configureMultiProxy, createFileWatcher, createOrchestrator, debounce, deriveProxyPath, deriveSpecId, getDevToolsUrl, getHandlerFiles, getSeedFiles, loadHandlers, loadSeeds, normalizeProxyPath, openApiServer, registerDevTools, resolveOptions, slugify, validateSpecs, validateUniqueIds, validateUniqueProxyPaths };
+export { API_PROXY_PATH, DEVTOOLS_PROXY_PATH, type DebouncedFunction, type DeriveProxyPathResult, type FileWatcher, type FileWatcherOptions, type LoadHandlersResult, type LoadSeedsResult, type OpenApiServerOptions, type OrchestratorResult, type ProxyPathSource, type RegisterDevToolsOptions, type ResolvedOptions, type ResolvedSpecConfig, SPEC_COLORS, type SpecConfig, type SpecInstance, ValidationError, type ValidationErrorCode, WS_PROXY_PATH, configureMultiProxy, createFileWatcher, createOrchestrator, createPerSpecFileWatchers, debounce, deriveProxyPath, deriveSpecId, getDevToolsUrl, getHandlerFiles, getSeedFiles, loadHandlers, loadSeeds, normalizeProxyPath, openApiServer, registerDevTools, reloadSpecHandlers, reloadSpecSeeds, resolveOptions, slugify, validateSpecs, validateUniqueIds, validateUniqueProxyPaths };