Skip to content

fix: Added JSdoc typedef to fix the TS typing output;

Martijn Houtman requested to merge feature/fix-hook-typing into master

The old JSDocs was:

/**
 * Custom hook to handle view filter queries.
 * It must be used within a ViewFilterQueryProvider.
 *
 * @throws {Error} If the hook is not used within a ViewFilterQueryProvider.
 *
 * @returns {Object} An object containing:
 * @property {Object} filters - The current filters
 * @property {number} page - The current page number, adjusted because the API is 0-indexed but visually (in the query params) we want to start at 1
 * @property {Function} setCurrentPage - Function to set the current page. The page number is enforced to be at least 1.
 * @property {Function} setFilters - Function to set the filters. The page number is reset to 1 when filters change because the user is likely looking for a different set of results.
 * @property {Function} setFilterValue - Function to set a specific filter value
 */

Which gave the following (incorrect) TS typing output:

/**
 * Custom hook to handle view filter queries.
 * It must be used within a ViewFilterQueryProvider.
 *
 * @throws {Error} If the hook is not used within a ViewFilterQueryProvider.
 *
 * @returns {Object} An object containing:
 * @property {Object} filters - The current filters
 * @property {number} page - The current page number, adjusted because the API is 0-indexed but visually (in the query params) we want to start at 1
 * @property {Function} setCurrentPage - Function to set the current page. The page number is enforced to be at least 1.
 * @property {Function} setFilters - Function to set the filters. The page number is reset to 1 when filters change because the user is likely looking for a different set of results.
 * @property {Function} setFilterValue - Function to set a specific filter value
 */
export default function useViewFilterQuery(): Object;

The new JSdoc is:

/**
 * Custom hook to handle view filter queries.
 * It must be used within a ViewFilterQueryProvider.
 *
 * @throws {Error} If the hook is not used within a ViewFilterQueryProvider.
 *
 * @typedef {Object} useViewFilterQueryReturn
 * @property {Object} filters - The current filters
 * @property {number} page - The current page number, adjusted because the API is 0-indexed but visually (in the query params) we want to start at 1
 * @property {Function} setCurrentPage - Function to set the current page. The page number is enforced to be at least 1.
 * @property {Function} setFilters - Function to set the filters. The page number is reset to 1 when filters change because the user is likely looking for a different set of results.
 * @property {Function} setFilterValue - Function to set a specific filter value
 *
 * @returns {useViewFilterQueryReturn} The return object.
 */

Which now gives the following TS typing output:

/**
 * Custom hook to handle view filter queries.
 * It must be used within a ViewFilterQueryProvider.
 *
 * @throws {Error} If the hook is not used within a ViewFilterQueryProvider.
 *
 * @typedef {Object} useViewFilterQueryReturn
 * @property {Object} filters - The current filters
 * @property {number} page - The current page number, adjusted because the API is 0-indexed but visually (in the query params) we want to start at 1
 * @property {Function} setCurrentPage - Function to set the current page. The page number is enforced to be at least 1.
 * @property {Function} setFilters - Function to set the filters. The page number is reset to 1 when filters change because the user is likely looking for a different set of results.
 * @property {Function} setFilterValue - Function to set a specific filter value
 *
 * @returns {useViewFilterQueryReturn} The return object.
 */
export default function useViewFilterQuery(): useViewFilterQueryReturn;
/**
 * Custom hook to handle view filter queries.
 * It must be used within a ViewFilterQueryProvider.
 */
export type useViewFilterQueryReturn = {
    /**
     * - The current filters
     */
    filters: Object;
    /**
     * - The current page number, adjusted because the API is 0-indexed but visually (in the query params) we want to start at 1
     */
    page: number;
    /**
     * - Function to set the current page. The page number is enforced to be at least 1.
     */
    setCurrentPage: Function;
    /**
     * - Function to set the filters. The page number is reset to 1 when filters change because the user is likely looking for a different set of results.
     */
    setFilters: Function;
    /**
     * - Function to set a specific filter value
     */
    setFilterValue: Function;
};

Merge request reports