Refactor filtering with getAbilities to account for query args

Author: gziolo

packages/client/README.md

@@ -75,7 +75,7 @@ function MyComponent() {
 
 ### Functions
 
-#### `getAbilities(category?: string): Promise<Ability[]>`
+#### `getAbilities( args: AbilitiesQueryArgs = {} ): Promise<Ability[]>`
 
 Returns all registered abilities. Optionally filter by category slug. Automatically handles pagination to fetch all abilities across multiple pages if needed.
 
@@ -85,11 +85,11 @@ const abilities = await getAbilities();
 console.log( `Found ${ abilities.length } abilities` );
 
 // Get abilities in a specific category
-const dataAbilities = await getAbilities( 'data-retrieval' );
+const dataAbilities = await getAbilities( { category: 'data-retrieval' } );
 console.log( `Found ${ dataAbilities.length } data retrieval abilities` );
 ```
 
-#### `getAbility(name: string): Promise<Ability | null>`
+#### `getAbility( name: string ): Promise<Ability | null>`
 
 Returns a specific ability by name, or null if not found.
 
@@ -100,7 +100,7 @@ if ( ability ) {
 }
 ```
 
-#### `registerAbility(ability: Ability): void`
+#### `registerAbility( ability: Ability ): void`
 
 Registers a client-side ability. Client abilities are executed locally in the browser and must include a callback function and a valid category.
 
@@ -115,18 +115,18 @@ registerAbility( {
   input_schema: {
     type: 'object',
     properties: {
-      url: { type: 'string' }
+      url: { type: 'string' },
     },
-    required: [ 'url' ]
+    required: [ 'url' ],
   },
   callback: async ( { url } ) => {
     window.location.href = url;
     return { success: true };
-  }
+  },
 } );
 ```
 
-#### `executeAbility(name: string, input?: Record<string, any>): Promise<any>`
+#### `executeAbility( name: string, input?: Record<string, any> ): Promise<any>`
 
 Executes an ability with optional input parameters. The HTTP method is automatically determined based on the ability's annotations:
 
@@ -150,8 +150,8 @@ const result = await executeAbility( 'my-plugin/create-item', {
 
 When using with `@wordpress/data`:
 
-- `getAbilities(category?)` - Returns all abilities from the store, optionally filtered by category
-- `getAbility(name)` - Returns a specific ability from the store
+- `getAbilities( args: AbilitiesQueryArgs = {} )` - Returns all abilities from the store, optionally filtered by query arguments
+- `getAbility( name: string )` - Returns a specific ability from the store
 
 ```javascript
 import { useSelect } from '@wordpress/data';
@@ -166,7 +166,8 @@ function MyComponent() {
 
   // Get abilities in a specific category
   const dataAbilities = useSelect(
-    ( select ) => select( abilitiesStore ).getAbilities( 'data-retrieval' ),
+    ( select ) =>
+      select( abilitiesStore ).getAbilities( { category: 'data-retrieval' } ),
     []
   );
 

packages/client/src/__tests__/api.test.ts

@@ -101,10 +101,10 @@ describe( 'API functions', () => {
 				getAbilities: mockGetAbilities,
 			} );
 
-			const result = await getAbilities( 'data-retrieval' );
+			const result = await getAbilities( { category: 'data-retrieval' } );
 
 			expect( resolveSelect ).toHaveBeenCalledWith( store );
-			expect( mockGetAbilities ).toHaveBeenCalledWith( 'data-retrieval' );
+			expect( mockGetAbilities ).toHaveBeenCalledWith( { category: 'data-retrieval' } );
 			expect( result ).toEqual( mockAbilities );
 		} );
 	} );

packages/client/src/api.ts

@@ -10,17 +10,17 @@ import { sprintf } from '@wordpress/i18n';
  * Internal dependencies
  */
 import { store } from './store';
-import type { Ability, AbilityInput, AbilityOutput } from './types';
+import type { Ability, AbilitiesQueryArgs, AbilityInput, AbilityOutput } from './types';
 import { validateValueFromSchema } from './validation';
 
 /**
- * Get all available abilities.
+ * Get all available abilities with optional filtering.
  *
- * @param category Optional category slug to filter abilities.
+ * @param args Optional query arguments to filter. Defaults to empty object.
  * @return Promise resolving to array of abilities.
  */
-export async function getAbilities( category?: string ): Promise< Ability[] > {
-	return await resolveSelect( store ).getAbilities( category );
+export async function getAbilities( args: AbilitiesQueryArgs = {}  ): Promise< Ability[] > {
+	return await resolveSelect( store ).getAbilities( args );
 }
 
 /**

packages/client/src/store/__tests__/resolvers.test.ts

@@ -99,7 +99,7 @@ describe( 'Store Resolvers', () => {
 
 			mockRegistry.resolveSelect.mockReturnValue( mockResolveSelect );
 
-			const resolver = getAbilities( 'data-retrieval' );
+			const resolver = getAbilities( { category: 'data-retrieval' } );
 			await resolver( {
 				dispatch: mockDispatch,
 				registry: mockRegistry,

packages/client/src/store/__tests__/selectors.test.ts

@@ -142,7 +142,7 @@ describe( 'Store Selectors', () => {
 				},
 			};
 
-			const result = getAbilities( state, 'data-retrieval' );
+			const result = getAbilities( state, { category: 'data-retrieval' } );
 
 			expect( result ).toHaveLength( 2 );
 			expect( result ).toContainEqual(
@@ -170,7 +170,7 @@ describe( 'Store Selectors', () => {
 				},
 			};
 
-			const result = getAbilities( state, 'non-existent-category' );
+			const result = getAbilities( state, { category: 'non-existent-category' } );
 
 			expect( result ).toEqual( [] );
 		} );

packages/client/src/store/resolvers.ts

@@ -14,8 +14,8 @@ import { receiveAbilities } from './actions';
  * Resolver for getAbilities selector.
  * Fetches all abilities from the server.
  *
- * The resolver only fetches once (without category filter) and stores all abilities.
- * Category filtering handled client-side by the selector for better performance
+ * The resolver only fetches once (without query args filter) and stores all abilities.
+ * Query args filtering handled client-side by the selector for better performance
  * and to avoid multiple API requests when filtering by different categories.
  */
 export function getAbilities() {

packages/client/src/store/selectors.ts

@@ -6,18 +6,18 @@ import { createSelector } from '@wordpress/data';
 /**
  * Internal dependencies
  */
-import type { Ability, AbilitiesState } from '../types';
+import type { Ability, AbilitiesQueryArgs, AbilitiesState } from '../types';
 
 /**
  * Returns all registered abilities.
- * Optionally filters by category.
+ * Optionally filters by query arguments.
  *
- * @param state    Store state.
- * @param category Optional category slug to filter by.
+ * @param state Store state.
+ * @param args  Optional query arguments to filter. Defaults to empty object.
  * @return Array of abilities.
  */
 export const getAbilities = createSelector(
-	( state: AbilitiesState, category?: string ): Ability[] => {
+	( state: AbilitiesState, { category }: AbilitiesQueryArgs = {} ): Ability[] => {
 		const abilities = Object.values( state.abilitiesByName );
 		if ( category ) {
 			return abilities.filter(

packages/client/src/types.ts

@@ -91,6 +91,16 @@ export interface Ability {
 	};
 }
 
+/**
+ * The shape of the arguments for querying abilities.
+ */
+export interface AbilitiesQueryArgs {
+	/**
+	 * Optional category slug to filter abilities.
+	 */
+	category?: string;
+}
+
 /**
  * The state shape for the abilities store.
  */