refactor: add shared parseQueryParamList utility for query parameter parsing

- Added parseQueryParamList() function to handle parsing of query parameters that can be either strings or arrays, with support for comma-separated values
- Exported both parseCommaSeparatedList and parseQueryParamList from index-internals.ts for use in internal packages
- Added 11 comprehensive test cases covering string/array parsing, comma-separation with/without spaces, empty values, and whitespace handling
- This eliminates duplicate parsing logic and provides a single source of truth for query parameter handling

Author: MQ37

src/index-internals.ts

@@ -10,6 +10,7 @@ import { defaultTools, getActorsAsTools, toolCategories,
     toolCategoriesEnabledByDefault, unauthEnabledToolCategories, unauthEnabledTools } from './tools/index.js';
 import { actorNameToToolName } from './tools/utils.js';
 import type { ToolCategory } from './types.js';
+import { parseCommaSeparatedList, parseQueryParamList } from './utils/generic.js';
 import { getExpectedToolNamesByCategories, getToolPublicFieldOnly } from './utils/tools.js';
 import { TTLLRUCache } from './utils/ttl-lru.js';
 
@@ -30,4 +31,6 @@ export {
     getToolPublicFieldOnly,
     unauthEnabledToolCategories,
     unauthEnabledTools,
+    parseCommaSeparatedList,
+    parseQueryParamList,
 };

src/utils/generic.ts

@@ -15,6 +15,27 @@ export function parseCommaSeparatedList(input?: string): string[] {
     return input.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
 }
 
+/**
+ * Parses a query parameter that can be either a string or an array of strings.
+ * Handles comma-separated values in strings and filters out empty values.
+ *
+ * @param param - A query parameter that can be a string, array of strings, or undefined
+ * @returns An array of trimmed, non-empty strings
+ * @example
+ * parseQueryParamList("a,b,c"); // ["a", "b", "c"]
+ * parseQueryParamList(["a", "b"]); // ["a", "b"]
+ * parseQueryParamList(undefined); // []
+ */
+export function parseQueryParamList(param?: string | string[]): string[] {
+    if (!param) {
+        return [];
+    }
+    if (Array.isArray(param)) {
+        return param.flatMap((item) => parseCommaSeparatedList(item));
+    }
+    return parseCommaSeparatedList(param);
+}
+
 /**
  * Recursively gets the value in a nested object for each key in the keys array.
  * Each key can be a dot-separated path (e.g. 'a.b.c').

tests/unit/utils.generic.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 
-import { getValuesByDotKeys, isValidHttpUrl, parseBooleanFromString, parseCommaSeparatedList } from '../../src/utils/generic.js';
+import { getValuesByDotKeys, isValidHttpUrl, parseBooleanFromString, parseCommaSeparatedList, parseQueryParamList } from '../../src/utils/generic.js';
 
 describe('getValuesByDotKeys', () => {
     it('should get value for a key without dot', () => {
@@ -83,6 +83,63 @@ describe('parseCommaSeparatedList', () => {
     });
 });
 
+describe('parseQueryParamList', () => {
+    it('should parse comma-separated string', () => {
+        const result = parseQueryParamList('tool1, tool2, tool3');
+        expect(result).toEqual(['tool1', 'tool2', 'tool3']);
+    });
+
+    it('should parse comma-separated string without spaces', () => {
+        const result = parseQueryParamList('tool1,tool2,tool3');
+        expect(result).toEqual(['tool1', 'tool2', 'tool3']);
+    });
+
+    it('should parse array of strings', () => {
+        const result = parseQueryParamList(['tool1', 'tool2', 'tool3']);
+        expect(result).toEqual(['tool1', 'tool2', 'tool3']);
+    });
+
+    it('should handle undefined input', () => {
+        const result = parseQueryParamList(undefined);
+        expect(result).toEqual([]);
+    });
+
+    it('should handle empty string', () => {
+        const result = parseQueryParamList('');
+        expect(result).toEqual([]);
+    });
+
+    it('should handle empty array', () => {
+        const result = parseQueryParamList([]);
+        expect(result).toEqual([]);
+    });
+
+    it('should flatten array with comma-separated values', () => {
+        const result = parseQueryParamList(['tool1, tool2', 'tool3, tool4']);
+        expect(result).toEqual(['tool1', 'tool2', 'tool3', 'tool4']);
+    });
+
+    it('should filter empty strings from array', () => {
+        const result = parseQueryParamList(['tool1', '', 'tool2']);
+        expect(result).toEqual(['tool1', 'tool2']);
+    });
+
+    it('should handle single tool in string', () => {
+        const result = parseQueryParamList('single-tool');
+        expect(result).toEqual(['single-tool']);
+    });
+
+    it('should handle single tool in array', () => {
+        const result = parseQueryParamList(['single-tool']);
+        expect(result).toEqual(['single-tool']);
+    });
+
+    it('should trim whitespace from array items and their comma-separated values', () => {
+        const result = parseQueryParamList([' tool1 , tool2 ', ' tool3']);
+        expect(result).toEqual(['tool1', 'tool2', 'tool3']);
+    });
+});
+
 describe('isValidUrl', () => {
     it('should validate correct URLs', () => {
         expect(isValidHttpUrl('http://example.com')).toBe(true);