feat(runtime-utils): support once option in registerEndpoint (#1475)

Author: wattanx

examples/app-vitest/components/TestFetchComponent.vue

@@ -10,6 +10,46 @@ async function customFetcher() {
   })
   await fetcher('/test2/')
 }
+
+async function onceFetcher() {
+  try {
+    const fetcher = $fetch.create({})
+    await fetcher('/test-once/')
+  }
+  catch {
+    // Expected to fail on second call
+  }
+}
+
+async function onceReregisterFetcher() {
+  try {
+    const fetcher = $fetch.create({})
+    await fetcher('/test-once-reregister/')
+  }
+  catch {
+    // Expected to fail on second call
+  }
+}
+
+async function onceMethodGetFetcher() {
+  try {
+    const fetcher = $fetch.create({})
+    await fetcher('/test-method-once/', { method: 'GET' })
+  }
+  catch {
+    // Expected to fail on second call
+  }
+}
+
+async function onceMethodPostFetcher() {
+  try {
+    const fetcher = $fetch.create({})
+    await fetcher('/test-method-once/', { method: 'POST' })
+  }
+  catch {
+    // Expected to fail on second call
+  }
+}
 </script>
 
 <template>
@@ -26,5 +66,29 @@ async function customFetcher() {
     >
       custom fetch
     </button>
+    <button
+      id="once-fetcher"
+      @click="onceFetcher"
+    >
+      once fetch
+    </button>
+    <button
+      id="once-reregister-fetcher"
+      @click="onceReregisterFetcher"
+    >
+      once reregister fetch
+    </button>
+    <button
+      id="once-method-get-fetcher"
+      @click="onceMethodGetFetcher"
+    >
+      once method GET fetch
+    </button>
+    <button
+      id="once-method-post-fetcher"
+      @click="onceMethodPostFetcher"
+    >
+      once method POST fetch
+    </button>
   </div>
 </template>

examples/app-vitest/test/registerEndpoint.nuxt.spec.ts

@@ -28,4 +28,49 @@ describe('registerEndpoint tests', () => {
     expect(endpoint).toHaveBeenCalled()
     component.unmount()
   })
+
+  describe('once option', () => {
+    it('should handle the endpoint only once', async () => {
+      const endpoint = vi.fn(() => ({ name: 'Alice' }))
+      registerEndpoint('/test-once/', {
+        handler: () => endpoint(),
+        once: true,
+      })
+
+      const component = await mountSuspended(TestFetchComponent)
+
+      await component.find<HTMLButtonElement>('#once-fetcher').trigger('click')
+      expect(endpoint).toHaveBeenCalledTimes(1)
+
+      await component.find<HTMLButtonElement>('#once-fetcher').trigger('click')
+      expect(endpoint).toHaveBeenCalledTimes(1)
+
+      component.unmount()
+    })
+
+    it('should allow re-registering endpoint after once is consumed', async () => {
+      const endpoint1 = vi.fn(() => ({ name: 'Bob' }))
+      registerEndpoint('/test-once-reregister/', {
+        handler: () => endpoint1(),
+        once: true,
+      })
+
+      const component = await mountSuspended(TestFetchComponent)
+
+      await component.find<HTMLButtonElement>('#once-reregister-fetcher').trigger('click')
+      expect(endpoint1).toHaveBeenCalledTimes(1)
+
+      // Re-register with different handler
+      const endpoint2 = vi.fn(() => ({ name: 'Charlie' }))
+      registerEndpoint('/test-once-reregister/', {
+        handler: () => endpoint2(),
+        once: true,
+      })
+
+      await component.find<HTMLButtonElement>('#once-reregister-fetcher').trigger('click')
+      expect(endpoint2).toHaveBeenCalledTimes(1)
+
+      component.unmount()
+    })
+  })
 })

src/runtime-utils/mock.ts

@@ -18,30 +18,39 @@ import type {
 type Awaitable<T> = T | Promise<T>
 type OptionalFunction<T> = T | (() => Awaitable<T>)
 
+const endpointRegistry: Record<string, Array<{ handler: EventHandler, method?: HTTPMethod, once?: boolean }>> = {}
 /**
  * `registerEndpoint` allows you create Nitro endpoint that returns mocked data. It can come in handy if you want to test a component that makes requests to API to display some data.
  * @param url - endpoint name (e.g. `/test/`).
- * @param options - factory function that returns the mocked data or an object containing both the `handler` and the `method` properties.
+ * @param options - factory function that returns the mocked data or an object containing the `handler`, `method`, and `once` properties.
+ * - `handler`: the event handler function
+ * - `method`: (optional) HTTP method to match (e.g., 'GET', 'POST')
+ * - `once`: (optional) if true, the handler will only be used for the first matching request and then automatically removed
  * @example
  * ```ts
  * import { registerEndpoint } from '@nuxt/test-utils/runtime'
  *
- * registerEndpoint("/test/", () => {
+ * registerEndpoint("/test/", () => ({
  *  test: "test-field"
+ * }))
+ *
+ * // With once option
+ * registerEndpoint("/api/user", {
+ *   handler: () => ({ name: "Alice" }),
+ *   once: true
  * })
  * ```
  * @see https://nuxt.com/docs/getting-started/testing#registerendpoint
  */
-const endpointRegistry: Record<string, Array<{ handler: EventHandler, method?: HTTPMethod }>> = {}
-export function registerEndpoint(url: string, options: EventHandler | { handler: EventHandler, method: HTTPMethod }) {
+export function registerEndpoint(url: string, options: EventHandler | { handler: EventHandler, method?: HTTPMethod, once?: boolean }) {
   // @ts-expect-error private property
   const app: App = window.__app
 
   if (!app) {
     throw new Error('registerEndpoint() can only be used in a `@nuxt/test-utils` runtime environment')
   }
 
-  const config = typeof options === 'function' ? { handler: options, method: undefined } : options
+  const config = typeof options === 'function' ? { handler: options, method: undefined, once: false } : options
   config.handler = defineEventHandler(config.handler)
 
   // @ts-expect-error private property
@@ -54,9 +63,24 @@ export function registerEndpoint(url: string, options: EventHandler | { handler:
     // @ts-expect-error private property
     window.__registry.add(url)
 
-    app.use('/_' + url, defineEventHandler((event) => {
+    app.use('/_' + url, defineEventHandler(async (event) => {
       const latestHandler = [...endpointRegistry[url] || []].reverse().find(config => config.method ? event.method === config.method : true)
-      return latestHandler?.handler(event)
+      if (!latestHandler) return
+
+      const result = await latestHandler.handler(event)
+
+      if (!latestHandler.once) return result
+
+      const index = endpointRegistry[url]?.indexOf(latestHandler)
+      if (index === undefined || index === -1) return result
+
+      endpointRegistry[url]?.splice(index, 1)
+      if (endpointRegistry[url]?.length === 0) {
+        // @ts-expect-error private property
+        window.__registry.delete(url)
+      }
+
+      return result
     }), {
       match(_, event) {
         return endpointRegistry[url]?.some(config => config.method ? event?.method === config.method : true) ?? false