Important: This documentation applies to v2 of this package.
For v3 docs see vpic.shaggytech.com

Source

api/actions/GetModelsForMakeYear.ts

  1. /**
  2. * @module api/actions/GetModelsForMakeYear
  3. * @category Actions
  4. * @description GetModelsForMakeYear NHSTA Api Action.
  5. *
  6. * > **Module Exports**:
  7. * > - Class: [GetModelsForMakeYear](module-api_actions_GetModelsForMakeYear.GetModelsForMakeYear.html)
  8. * >
  9. * > **Types**
  10. * > - Type: [GetModelsForMakeYearResponse](#GetModelsForMakeYearResponse)
  11. * > - Type: [GetModelsForMakeYearResults](#GetModelsForMakeYearResults)
  12. *
  13. */
  14. /* Parent Class and Fetch Types */
  15. import {
  16. Fetch /* Class */,
  17. FetchConfig /* Type */,
  18. FetchResponse /* Type */,
  19. } from '../Fetch';
  20. /* Utility Functions */
  21. import { getTypeof } from '../../utils';
  22. /**
  23. * Implemented by [NHTSA](module-api_NHTSA-NHTSA.html).
  24. *
  25. * Extends [api/Fetch.Fetch](module-api_Fetch.Fetch.html).
  26. *
  27. * @category Actions
  28. * @param {FetchConfig} [userConfig] - User configuration options to construct the class with.
  29. */
  30. export class GetModelsForMakeYear extends Fetch {
  31. constructor(userConfig?: FetchConfig) {
  32. super(userConfig);
  33. }
  34. /**
  35. * This returns the Models in the vPIC dataset for a specified Model Year
  36. * and Make whose name is LIKE the Make in the vPIC Dataset.
  37. * - `params.make` is required. It can be a partial, or a full name for more specificity
  38. * (e.g., "Harley", "Harley Davidson", etc.).
  39. *
  40. * A minimum of one of the following are required (or a combination of both):
  41. * - `params.modelYear` is a number (greater than 1995)
  42. * - `params.vehicleType` can be a partial name, or a full name for more specificity
  43. * (e.g., "Vehicle", "Moto", "Low Speed Vehicle", etc.).
  44. *
  45. * @async
  46. *
  47. * @param {object} params - Query Search Parameters to append to the URL.
  48. * @param {string} params.make - Make name to search.
  49. * @param {number} [params.modelYear] - A number representing the model year to search (greater than 1995).
  50. * @param {string} [params.vehicleType] - String representing the vehicle type to search.
  51. *
  52. * @returns {(Promise<GetModelsForMakeYearResponse>)} Api Response object.
  53. */
  54. async GetModelsForMakeYear(params: {
  55. make: string;
  56. modelYear?: number;
  57. vehicleType?: string;
  58. }): Promise<GetModelsForMakeYearResponse> {
  59. const action = 'GetModelsForMakeYear';
  60. const make: string = params?.make;
  61. const modelYear: number | undefined = params?.modelYear;
  62. const vehicleType: string | undefined = params?.vehicleType;
  63. /* Valid params object */
  64. const typeofParams = getTypeof(params);
  65. if (typeofParams !== 'object') {
  66. return Promise.reject(
  67. new Error(
  68. `${action}, "params" argument must be of type object, got: ` +
  69. `<${typeofParams}> ${params}`
  70. )
  71. );
  72. }
  73. /* Required make param of type string */
  74. const typeofMake = getTypeof(make);
  75. if (typeofMake !== 'string') {
  76. return Promise.reject(
  77. new Error(
  78. `${action}, "params.make" argument is required and must be of type string, got: ` +
  79. `<${typeofMake}> ${make}`
  80. )
  81. );
  82. }
  83. /* At least one of modelYear or vehicleType params is required */
  84. if (!modelYear && !vehicleType) {
  85. return Promise.reject(
  86. new Error(
  87. `${action}, either one of "params.modelYear" or "params.vehicleType" is required, got: ` +
  88. `${modelYear} | ${vehicleType}`
  89. )
  90. );
  91. }
  92. /* valid modelYear param of type number */
  93. const typeofModelYear = getTypeof(modelYear);
  94. if (modelYear && typeofModelYear !== 'number') {
  95. return Promise.reject(
  96. new Error(
  97. `${action}, "params.modelYear" must be of type number, got: ` +
  98. `<${typeofModelYear}> ${modelYear}`
  99. )
  100. );
  101. }
  102. /* valid vehicleType param of type string */
  103. const typeofVehicleType = getTypeof(vehicleType);
  104. if (vehicleType && typeofVehicleType !== 'string') {
  105. return Promise.reject(
  106. new Error(
  107. `${action}, "params.vehicleType" must be of type string, got: ` +
  108. `<${typeofVehicleType}> ${vehicleType}`
  109. )
  110. );
  111. }
  112. /* Beginning of the the actionUrl */
  113. let actionUrl = `${action}/make/${params.make}/`;
  114. /* Append params.modelYear and params.vehicleType to the actionUrl, at least one is required by the API */
  115. if (modelYear && vehicleType) {
  116. actionUrl += `modelYear/${modelYear}/vehicleType/${vehicleType}`;
  117. } else if (modelYear) {
  118. actionUrl += `modelYear/${modelYear}`;
  119. } else {
  120. actionUrl += `vehicleType/${vehicleType}`;
  121. }
  122. /* Build the 'default' query string to be appended to the URL*/
  123. const queryString = await this.buildQueryString().catch((err: Error) =>
  124. Promise.reject(
  125. new Error(`${action}, Error building query string: ${err}`)
  126. )
  127. );
  128. /* Build the final request URL*/
  129. const url = `${this.baseUrl}/${actionUrl}${queryString}`;
  130. /* Return the result */
  131. return await this.get(url)
  132. .then((response) => response)
  133. .catch((err: Error) =>
  134. Promise.reject(new Error(`${action}, Fetch.get() error: ${err}`))
  135. );
  136. }
  137. }
  138. /**
  139. * Type representing the structure of objects found in the '{@link GetModelsForMakeYearResponse}.Results' array.
  140. *
  141. * @memberof module:api/actions/GetModelsForMakeYear
  142. * @alias GetModelsForMakeYearResults
  143. */
  144. export type GetModelsForMakeYearResults = {
  145. Make_ID: number;
  146. Make_Name: string;
  147. Model_ID: number;
  148. Model_Name: string;
  149. };
  150. /**
  151. * Type representing the complete response returned by the GetModelsForMakeYear API Action.
  152. *
  153. * @memberof module:api/actions/GetModelsForMakeYear
  154. * @alias GetModelsForMakeYearResponse
  155. */
  156. export type GetModelsForMakeYearResponse = {
  157. /** A count of the items returned in the Results array. */
  158. Count: number;
  159. /** A message describing the Results array. */
  160. Message: string;
  161. /** Search terms (VIN, WMI, manufacturer, etc.) used in the request URL. */
  162. SearchCriteria: string;
  163. /** The search results returned by the NHSTA API request. */
  164. Results: Array<GetModelsForMakeYearResults>;
  165. /** [Fetch API Response](https://github.github.io/fetch/#Response) properties. */
  166. FetchResponse: FetchResponse;
  167. };