@shaggytools/nhtsa-api-wrapper/dist/types/utils/queryString.d.ts

Universal javascript wrapper for the NHTSA.dot.gov VPIC 'vehicles' API, useful for VIN decoding, etc.

/**
 * @module utils/queryString
 * @category Utility Functions
 */
/** Valid URI component types */
export type QueryStringTypes = string | number | boolean;
/** Object to build the query string with */
export type QueryStringParams = Record<string, QueryStringTypes>;
/** Object returned by encodeQueryStringParams() */
export type QueryStringParamsEncoded<T> = {
    [key in keyof T]: string;
};
/**
 * This function is used internally by other package functions. As a consumer of this package, you
 * should not need to use this function directly in most cases.
 *
 * Utility function to perform URI component encoding on all values in an object, for use in URL
 * query strings.
 *
 * - Returns an object of valid URI encoded parameters with same keys as the original object.
 * - Will silently filter out parameters with values that are not type `string`, `number`, or
 *   `boolean`.
 * - It filters invalid key/values so that encodeURIComponent() does not throw an error.
 *
 * In it's current implementation, this function assumes that invalid types have already been
 * filtered out, and that all values are valid. If you need to be sure that all keys are present
 * in the returned object, you can use the `validateArgument()` function to check the types of all
 * values are valid before calling this function.
 *
 * This function is not exported by the package, but is used internally by other
 * functions. However, it _is_ exported by the package as part of the composable function
 * `useQueryString`, and renamed to `encodeParams` for less verbose use.
 *
 * @param {QueryStringParams} params - An object of search parameters to be encoded.
 * @returns {QueryStringParamsEncoded} - A new object of same keys as the original object with
 * values converted to URI component strings. Any keys with values not a string, number, or
 * boolean are filtered out of final object.
 */
export declare const encodeQueryStringParams: <T extends QueryStringParams>(params: T) => QueryStringParamsEncoded<T>;
/**
 * This function is used internally by other package functions. As a consumer of this package, you
 * should not need to use this function directly in most cases.
 *
 * Utility function to generate a query string conforming to URI component standards. Takes an an
 * optional object of search parameters and returns an encoded query string.
 *
 * This function will always override `params.format` with `{ format: 'json' }`. This is hardcoded
 * into the package and cannot be overridden, this package provides no support for CSV or XML
 * formats at this time. This means the default query string will be `"?format=json"` even if no
 * `params` are provided by user.
 *
 * - Ignores parameters that are not strings, numbers, or booleans, and also ignores empty strings
 *   by default.
 *
 * - If you don't provide an object as the first argument, an error will be thrown. Providing an
 *   empty object will not throw an error.
 *
 * - If the second argument, `allowEmptyParams`, is set to `true`, the function will include keys
 *   with empty string values in the final query string, e.g. 'emptyKey='.
 *
 * @param {QueryStringParams} params - An object of search parameters to be converted to a query
 * string.
 * @param {boolean} [allowEmptyParams=false] - Set to `true` to include keys with empty string
 * values, e.g. 'emptyKey='.
 * @returns {string} - A query string of search parameters for use in a final fetch URL.
 */
export declare const createQueryString: <T extends QueryStringParams>(params?: T, allowEmptyParams?: boolean) => string;
//# sourceMappingURL=queryString.d.ts.map