feat: add option to exclude pure api fs

Author: Andrea Cosentino

docs/api/index.md

@@ -82,6 +82,34 @@ universalApi({
 If the directory doesn't exist, file-based routing will be disabled automatically, but the plugin will still work for custom handlers.
 :::
 
+### disablePureFsApi
+
+- **Type**: `boolean`
+- **Default**: `false`
+
+Disable the **pure File-System API** — the automatic fallback that maps incoming requests directly to files inside `fsDir` when no REST handler matches.
+
+When set to `true`, only REST handlers explicitly configured with `handle: "FS"` continue to read files from `fsDir`. Every other unmatched request is handled according to [`noHandledRestFsRequestsAction`](#nohandledrestfsrequestsaction) (default: `"404"`).
+
+> **This option does not affect handlers whose `handle` property is `"FS"`**. Those always keep their file-system behaviour, regardless of this flag.
+
+```typescript
+universalApi({
+  fsDir: 'mock',
+  disablePureFsApi: true,  // only explicit FS handlers can reach the filesystem
+  handlers: [
+    { pattern: '/api/users', method: 'GET', handle: 'FS' }
+  ]
+})
+
+// GET /api/users   → served from mock/api/users.json  ✓ (explicit FS handler)
+// GET /api/orders  → 404 / forwarded                  ✓ (pure FS fallback disabled)
+```
+
+::: tip When to use this option
+Use `disablePureFsApi: true` when you want explicit control over which endpoints are exposed and want to prevent the plugin from automatically serving any file that happens to exist under `fsDir`.
+:::
+
 ### enablePreview
 
 - **Type**: `boolean`
@@ -452,6 +480,7 @@ export default defineConfig({
       logLevel: 'debug',
       endpointPrefix: '/api',
       fsDir: 'mock',
+      disablePureFsApi: false, // set to true to expose only explicit FS handlers
 
       // Preview behaviour
       enablePreview: false, // Disable mocks when running vite preview

docs/guide/file-system-api.md

@@ -352,6 +352,35 @@ const users = Array.from({ length: 100 }, (_, i) => ({
 // Save to mock/users.json
 ```
 
+## Disabling the Pure File-System API
+
+By default, any request that reaches the plugin and does not match a REST handler is automatically resolved against `fsDir` (the pure File-System API). You can turn off this automatic fallback with the `disablePureFsApi` option.
+
+```typescript
+universalApi({
+  fsDir: 'mock',
+  disablePureFsApi: true, // disable the automatic FS fallback
+  handlers: [
+    { pattern: '/api/users', method: 'GET', handle: 'FS' }
+  ]
+})
+```
+
+When `disablePureFsApi` is `true`:
+
+- Requests that match a handler with `handle: "FS"` are **still served from `fsDir`** as usual.
+- Requests that do **not** match any handler are handled according to `noHandledRestFsRequestsAction` (`"404"` by default) — they are **never** automatically mapped to files.
+
+| Request | `disablePureFsApi: false` (default) | `disablePureFsApi: true` |
+|---------|--------------------------------------|--------------------------|
+| Matches a handler with `handle: "FS"` | Served from `fsDir` ✓ | Served from `fsDir` ✓ |
+| Matches a custom handler | Custom logic ✓ | Custom logic ✓ |
+| No handler matched | Automatic FS lookup ✓ | 404 / forward ✓ |
+
+::: tip When to use this option
+Use `disablePureFsApi: true` when you want strict, explicit control over which endpoints are exposed and you want to prevent the plugin from automatically serving any file that happens to exist under `fsDir`.
+:::
+
 ## Limitations
 
 - ❌ POST with multiple files not supported (only first file is written)

src/models/plugin.model.ts

@@ -1588,6 +1588,39 @@ type UniversalApiBaseOptions = {
 	 */
 	fsDir?: string | null;
 
+	/**
+	 * Disable the **pure File-System API** — the automatic fallback that serves
+	 * files directly from `fsDir` when no REST handler matches an incoming
+	 * request.
+	 *
+	 * When `true`, only REST handlers explicitly configured with `handle: "FS"`
+	 * continue to read files from `fsDir`; every other unmatched request is
+	 * handled according to `noHandledRestFsRequestsAction` (default: `"404"`).
+	 *
+	 * This option has **no effect** on handlers whose `handle` property is set
+	 * to `"FS"` — those always keep their file-system behaviour regardless of
+	 * this flag.
+	 *
+	 * Setting `disablePureFsApi: true` is useful when you want precise, explicit
+	 * control over which endpoints are exposed without relying on the implicit
+	 * directory-to-route mapping.
+	 *
+	 * @default false
+	 *
+	 * @example
+	 * // Serve files only through explicitly declared FS handlers
+	 * {
+	 *   fsDir: './mock-data',
+	 *   disablePureFsApi: true,
+	 *   handlers: [
+	 *     { pattern: '/api/users', method: 'GET', handle: 'FS' }
+	 *   ]
+	 * }
+	 * // GET /api/users   → served from mock-data/api/users.json  ✓ (explicit FS handler)
+	 * // GET /api/orders  → 404 or forwarded                       ✓ (pure FS disabled)
+	 */
+	disablePureFsApi?: boolean;
+
 	/**
 	 * Enable the plugin in preview mode (`vite preview`).
 	 * When `false`, the plugin does not intercept requests in preview mode.
@@ -1884,6 +1917,7 @@ export type UniversalApiOptions = UniversalApiBaseOptions & (
 /** @internal */
 export type UniversalApiOptionsRequired = Omit<Required<UniversalApiOptions>, "handlerMiddlewares" | "endpointPrefix"> & {
 	endpointPrefix: string[];
+	disablePureFsApi: boolean;
 	/**
 	 * Prefixes that were provided by the user but rejected because they resolve
 	 * to the root path ("/") after normalisation. Stored so that runAsyncInit

src/plugin/index.ts

@@ -26,6 +26,7 @@ export function universalApiPlugin(opts?: UniversalApiOptions): Plugin {
 		wsHandlers: [],
 		pagination: null,
 		filters: null,
+		disablePureFsApi: false,
 		config: {} as UniversalApiOptionsRequired["config"],
 		matcher: {} as UniversalApiOptionsRequired["matcher"],
 	};

src/utils/plugin.ts

@@ -598,7 +598,7 @@ async function handlingApiRestRequest(logger: ILogger, matcher: AntPathMatcher,
 }
 
 const runPluginInternal = async (req: IncomingMessage, res: ServerResponse, logger: ILogger, options: UniversalApiOptionsRequired) => {
-	const { config, endpointPrefix, handlers, matcher, middlewares, errorMiddlewares, delay, fullFsDir, filters, pagination, parser } = options;
+	const { config, endpointPrefix, handlers, matcher, middlewares, errorMiddlewares, delay, fullFsDir, filters, pagination, parser, disablePureFsApi } = options;
 	const fullUrl = Utils.request.buildFullUrl(req, config);
 	const endpointNoPrefix = Utils.request.removeEndpointPrefix(fullUrl.pathname, endpointPrefix);
 	let requ: UniversalApiRequest<any> = req as UniversalApiRequest<any>;
@@ -625,9 +625,11 @@ const runPluginInternal = async (req: IncomingMessage, res: ServerResponse, logg
 			return result;
 		}
 
-		handled = await handlingApiFsRequest(logger, fullUrl, request, res, pagination, filters, parser, null, endpointPrefix, fullFsDir, result);
-		if (handled) {
-			return result;
+		if (!disablePureFsApi) {
+			handled = await handlingApiFsRequest(logger, fullUrl, request, res, pagination, filters, parser, null, endpointPrefix, fullFsDir, result);
+			if (handled) {
+				return result;
+			}
 		}
 
 		throw new UniversalApiError(`Impossible handling request with url ${fullUrl}`, "NO_HANDLER", fullUrl.pathname);

src/utils/utils.ts

@@ -117,6 +117,7 @@ export const Utils = {
 				wsHandlers: opts?.wsHandlers ?? [],
 				pagination: opts?.pagination ?? null,
 				filters: opts?.filters ?? null,
+				disablePureFsApi: opts?.disablePureFsApi ?? false,
 				config,
 				matcher: new AntPathMatcher()
 			};