Make MediaService generic

src/constants/license.js

@@ -1,22 +1,45 @@
-export const CC_LICENSES = [
+export const CC_LICENSES = /** @type {const} */ ([
   'by',
   'by-sa',
   'by-nd',
   'by-nc',
   'by-nc-sa',
   'by-nc-nd',
-]
+])
+
+/**
+ * @template T
+ * @typedef {T extends `${infer P}-${infer PP}-${infer PPP}` ? [P, PP, PPP] : T extends `${infer P}-${infer PP}` ? [P, PP] : [T]} PartitionLicense
+ */
+
+/** @typedef {PartitionLicense<CCLicense>[number]} LicensePart */
+
+/** @typedef {typeof CC_LICENSES[number]} CCLicense */
+
+export const NON_CC_LICENSES = /** @type {const} */ (['cc0', 'pdm'])
 
-export const NON_CC_LICENSES = ['cc0', 'pdm']
+/** @typedef {typeof NON_CC_LICENSES[number]} NonCCLicense */
 
-export const DEPRECATED_LICENSES = ['nc-sampling+', 'sampling+']
+export const DEPRECATED_LICENSES = /** @type {const} */ ([
+  'nc-sampling+',
+  'sampling+',
+])
+
+/** @typedef {typeof DEPRECATED_LICENSES[number]} DeprecatedLicense */
 
 export const ALL_LICENSES = [
   ...CC_LICENSES,
   ...NON_CC_LICENSES,
   ...DEPRECATED_LICENSES,
 ]
 
+/** @typedef {typeof ALL_LICENSES[number]} License */
+
+export const MARKS = /** @type {const} */ (['cc0', 'pdm'])
+
+/** @typedef {typeof MARKS[number]} Mark */
+
+/** @type {Record<LicensePart | Mark, string>} */
 export const LICENSE_ICON_MAPPING = {
   by: 'by',
   nc: 'nc',

src/constants/media.js

@@ -8,25 +8,27 @@ export const ALL_MEDIA = 'all'
 /**
  * Media types that the API supports.
  * These types also support custom filters.
- * @type {MediaType[]}
  */
-export const supportedMediaTypes = [IMAGE, AUDIO]
+export const supportedMediaTypes = /** @type {const} */ ([IMAGE, AUDIO])
 
 /**
  * The types of content that users can search. `All` is also an option here.
- * @type {MediaType[]}
  */
-export const supportedContentTypes = [ALL_MEDIA, IMAGE, AUDIO]
+export const supportedContentTypes = /** @type {const} */ ([
+  ALL_MEDIA,
+  IMAGE,
+  AUDIO,
+])
 
-/** @typedef {'supported'|'beta'|'additional'} SupportStatus */
-/** @type {{SUPPORTED: SupportStatus, ADDITIONAL: SupportStatus, BETA: SupportStatus}}*/
-export const statuses = {
+export const statuses = /** @type {const} */ ({
   SUPPORTED: 'supported',
   BETA: 'beta',
   ADDITIONAL: 'additional',
-}
+})
+
+/** @typedef {typeof statuses[keyof typeof statuses]} SupportStatus */
 
-/** @type {Object.<MediaType, SupportStatus>} */
+/** @type {Record<MediaType, SupportStatus>} */
 export const contentStatus = {
   [ALL_MEDIA]: statuses.SUPPORTED,
   [IMAGE]: statuses.SUPPORTED,

src/data/media-service.js

@@ -2,28 +2,39 @@ import ApiService from '~/data/api-service'
 
 import decodeMediaData from '~/utils/decode-media-data'
 
+/**
+ * @template {import('../store/types').FrontendMediaType} [T=any]
+ */
 class MediaService {
+  /**
+   * @param {T} mediaType
+   */
   constructor(mediaType) {
+    /** @type {T} */
     this.mediaType = mediaType
   }
+
   /**
    * Decodes the text data to avoid encoding problems.
    * Also, converts the results from an array of media objects into an object with
    * media id as keys.
-   * @param {import('../store/types').MediaResult<import('../store/types').MediaDetail[]|{}>} data
-   * @returns {import('../store/types').MediaResult<import('../store/types').MediaStoreResult>}
+   * @param {import('../store/types').MediaResult<T[]>} data
+   * @returns {import('../store/types').MediaStoreResult<T>}
    */
   transformResults(data) {
-    data.results = data.results.reduce((acc, item) => {
-      acc[item.id] = decodeMediaData(item, this.mediaType)
-      return acc
-    }, {})
-    return data
+    return {
+      ...data,
+      results: data.results.reduce((acc, item) => {
+        acc[item.id] = decodeMediaData(item, this.mediaType)
+        return acc
+      }, /** @type {Record<string, import('../store/types').DetailFromMediaType<T>>} */ ({})),
+    }
   }
+
   /**
    * Search for media items by keyword.
-   * @param {Object} params
-   * @return {Promise<{data: any}>}
+   * @param {import('../store/types').ApiQueryParams} params
+   * @return {Promise<import('axios').AxiosResponse<import('../store/types').MediaResult<T[]>>>}
    */
   search(params) {
     return ApiService.query(this.mediaType, params)
@@ -32,9 +43,8 @@ class MediaService {
   /**
    * Retrieve media details by its id.
    * SSR-called
-   * @param {object} params
-   * @param {string} params.id
-   * @return {Promise<{data: any}>}
+   * @param {{ id: string }} params
+   * @return {Promise<import('axios').AxiosResponse<import('../store/types').MediaResult<T>>>}
    */
   getMediaDetail(params) {
     if (!params.id) {
@@ -48,9 +58,8 @@ class MediaService {
 
   /**
    * Retrieve related media
-   * @param {object} params
-   * @param {string} params.id
-   * @return {Promise<{data: any}>}
+   * @param {{ id: string }} params
+   * @return {Promise<import('axios').AxiosResponse<import('../store/types').MediaResult<T[]>>>}
    */
   getRelatedMedia(params) {
     if (!params.id) {

src/store/media.js

@@ -68,10 +68,10 @@ export const state = () => ({
   image: {},
 })
 
-export const mediaServices = {
+export const mediaServices = /** @type {const} */ ({
   [AUDIO]: new MediaService(AUDIO),
   [IMAGE]: new MediaService(IMAGE),
-}
+})
 
 export const createActions = (services = mediaServices) => ({
   /**

src/store/types.d.ts

@@ -1,11 +1,20 @@
 /**
  * The search result object
  */
-export interface MediaResult<T> {
+
+type FrontendMediaType = MediaDetail['frontendMediaType']
+export interface MediaResult<T extends FrontendMediaType | FrontendMediaType[] | Record<unknown, FrontendMediaType>> {
   result_count: number
   page_count: number
   page_size: number
-  results: T
+  results:
+    T extends FrontendMediaType
+      ? DetailFromMediaType<T>
+      : T extends Array<infer P>
+          ? DetailFromMediaType<P>[]
+          : T extends Record<infer K, infer P>
+            ? Record<K, DetailFromMediaType<P>>
+            : never
 }
 
 export type Query = {
@@ -37,58 +46,48 @@ export type ApiQueryParams = {
   mature?: string
 }
 
-/**
- * Audio Properties returned by the API
- */
-export type AudioDetail = {
+export interface Tag {
+  name: string
+  provider: [string]
+}
+
+export interface BaseMediaDetail<FrontendMediaType extends string> {
   id: string
   foreign_landing_url: string
   creator?: string
   creator_url?: string
   url: string
-  license: string
+  title?: string
+  license: import('../constants/license').License | import('../constants/license').Mark
   license_version: string
   license_url: string
   provider: string
   source?: string
-  tags?: any
+  tags?: Tag[]
   attribution: string
+  detail_url: string
+  related_url: string
+  thumbnail?: string
+  frontendMediaType: FrontendMediaType
+}
+
+export interface AudioDetail extends BaseMediaDetail<'audio'> {
   audio_set?: any
   genres?: any
   duration?: number
   bit_rate?: number
   sample_rate?: number
   alt_files?: any
-  detail_url: string
-  related_url: string
   filetype?: string
-  frontendMediaType?: 'audio'
 }
 
-/**
- * Image Properties returned by the API
- */
-export type ImageDetail = {
-  id: string
-  title?: string
-  creator?: string
-  creator_url?: string
-  tags?: { name: string; provider: [string] }[]
-  url: string
-  thumbnail?: string
-  provider: string
-  source?: string
-  license: string
-  license_version: string
-  license_url: string
-  foreign_landing_url: string
-  detail_url: string
-  related_url: string
+export interface ImageDetail extends BaseMediaDetail<'image'> {
   fields_matched?: string[]
-  frontendMediaType?: 'image'
 }
 
-export const MediaDetail = AudioDetail | ImageDetail
+export type MediaDetail = ImageDetail | AudioDetail
+
+export type DetailFromMediaType<T extends MediaDetail['frontendMediaType']> = T extends 'image' ? ImageDetail : T extends 'audio' ? AudioDetail : never
 
 export interface FilterItem {
   code: string
@@ -131,24 +130,19 @@ export interface ActiveMediaState {
   status: 'ejected' | 'playing' | 'paused' // 'ejected' means player is closed
 }
 
-export interface MediaStoreResult {
-  count: number
-  page?: number
-  pageCount: number
-  items: { [key: SupportedMediaType]: MediaDetail }
-}
+export interface MediaStoreResult<T extends FrontendMediaType> extends MediaResult<Record<MediaDetail['id'], T>> {}
 
 export interface MediaState {
   results: {
-    audio: MediaStoreResult
-    image: MediaStoreResult
+    audio: MediaStoreResult<AudioDetail>
+    image: MediaStoreResult<ImageDetail>
   }
   fetchState: {
     audio: FetchState
     image: FetchState
   }
-  audio: Object | AudioDetail
-  image: Object | ImageDetail
+  audio: AudioDetail
+  image: ImageDetail
 }
 
 export interface MediaFetchState {

src/utils/decode-data.js

@@ -1,17 +1,17 @@
 /**
  * decodes some edge cases of Unicode characters with an extra \
  * See test cases for some examples
- * @param {string} data
+ * @param {string} [data]
  */
 export default function decodeData(data) {
   if (data) {
     try {
       const regexASCII = /\\x([\d\w]{2})/gi
-      const ascii = data.replace(regexASCII, (match, grp) =>
+      const ascii = data.replace(regexASCII, (_, grp) =>
         String.fromCharCode(parseInt(grp, 16))
       )
       const regexUni = /\\u([\d\w]{4})/gi
-      const uni = ascii.replace(regexUni, (match, grp) =>
+      const uni = ascii.replace(regexUni, (_, grp) =>
         String.fromCharCode(parseInt(grp, 16))
       )
       const res = decodeURI(uni)

src/utils/decode-media-data.js

@@ -1,6 +1,12 @@
 import decodeData from '~/utils/decode-data'
 import { IMAGE } from '~/constants/media'
 
+/**
+ * @template {import('../store/types').MediaDetail} T
+ * @param {T} media
+ * @param {import('../constants/media').MediaType} mediaType
+ * @return {T}
+ */
 export default function decodeMediaData(media, mediaType = IMAGE) {
   return {
     ...media,

tsconfig.json

@@ -39,10 +39,14 @@
     "src/composables/use-browser-detection.js",
     "src/composables/use-media-query.js",
     "src/composables/window.js",
+    "src/constants/license.js",
     "src/constants/screens.js",
     "src/data/api-service.js",
+    "src/data/media-service.js",
     "src/data/usage-data-service.js",
     "src/store/user.js",
+    "src/utils/decode-data.js",
+    "src/utils/decode-media-data.js",
     "src/utils/key-codes.js",
     "src/utils/local.js",
     "src/utils/warn.js"