feat: add useRouteParam composable

Author: davidstackio

src/runtime/composables/route.ts

@@ -0,0 +1,19 @@
+import { useRoute } from '#imports'
+
+/**
+ * A composable that wraps `useRoute` and returns the specified route parameter as a string.
+ * This avoids repetitive casting (e.g., `route.params.uid as string`) for route parameters.
+ *
+ * @param param - The name of the route parameter to retrieve.
+ * @returns The route parameter value as a string (returns the first element if it is an array, or an empty string if undefined/null).
+ */
+export const useRouteParam = (param: string): string => {
+  const route = useRoute()
+  const value = route.params[param]
+
+  if (Array.isArray(value)) {
+    return value[0] ?? ''
+  }
+
+  return value ?? ''
+}

test/route.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { useRouteParam } from '../src/runtime/composables/route'
+import { useRoute } from '#imports'
+
+// Mock #imports to isolate useRouteParam testing from a running Nuxt instance
+vi.mock('#imports', () => {
+  return {
+    useRoute: vi.fn(),
+  }
+})
+
+describe('useRouteParam', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('returns route param as string when it is a simple string', () => {
+    vi.mocked(useRoute).mockReturnValue({
+      params: {
+        uid: 'user-123',
+      },
+    } as unknown as ReturnType<typeof useRoute>)
+
+    const param = useRouteParam('uid')
+    expect(param).toBe('user-123')
+  })
+
+  it('returns first element of array when route param is an array', () => {
+    vi.mocked(useRoute).mockReturnValue({
+      params: {
+        slug: ['category', 'product-name'],
+      },
+    } as unknown as ReturnType<typeof useRoute>)
+
+    const param = useRouteParam('slug')
+    expect(param).toBe('category')
+  })
+
+  it('returns empty string if the route param is not present or undefined', () => {
+    vi.mocked(useRoute).mockReturnValue({
+      params: {},
+    } as unknown as ReturnType<typeof useRoute>)
+
+    const param = useRouteParam('uid')
+    expect(param).toBe('')
+  })
+
+  it('returns empty string if the route param is null', () => {
+    vi.mocked(useRoute).mockReturnValue({
+      params: {
+        uid: null as unknown as string,
+      },
+    } as unknown as ReturnType<typeof useRoute>)
+
+    const param = useRouteParam('uid')
+    expect(param).toBe('')
+  })
+})