From d3f9555f41706623f7a10fc109172a4868ac4db3 Mon Sep 17 00:00:00 2001 From: absidue <48293849+absidue@users.noreply.github.com> Date: Wed, 8 Dec 2021 19:08:20 +0100 Subject: [PATCH] Significantly improve the docs for the Deezer classes and functions --- play-dl/Deezer/classes.ts | 361 ++++++++++++++++++++++++++++++++++++-- play-dl/Deezer/index.ts | 40 ++++- 2 files changed, 387 insertions(+), 14 deletions(-) diff --git a/play-dl/Deezer/classes.ts b/play-dl/Deezer/classes.ts index d4589a6..959b5e5 100644 --- a/play-dl/Deezer/classes.ts +++ b/play-dl/Deezer/classes.ts @@ -1,50 +1,169 @@ import { request } from '../Request'; +/** + * Interface representing an image on Deezer + * available in four sizes + */ interface DeezerImage { + /** + * The largest version of the image + */ xl: string; + /** + * The second largest version of the image + */ big: string; + /** + * The second smallest version of the image + */ medium: string; + /** + * The smallest version of the image + */ small: string; } +/** + * Interface representing a Deezer genre + */ interface DeezerGenre { + /** + * The name of the genre + */ name: string; + /** + * The thumbnail of the genre available in four sizes + */ picture: DeezerImage; } +/** + * Interface representing a Deezer user account + */ interface DeezerUser { + /** + * The id of the user + */ id: number; + /** + * The name of the user + */ name: string; } /** - * Class for Deezer Tracks + * Class representing a Deezer track */ export class DeezerTrack { + /** + * The id of the track + */ id: number; + /** + * The title of the track + */ title: string; + /** + * A shorter version of the title + */ shortTitle: string; + /** + * The URL of the track on Deezer + */ url: string; + /** + * The duration of the track in seconds + */ durationInSec: number; + /** + * The rank of the track + */ rank: number; + /** + * `true` if the track contains any explicit lyrics + */ explicit: boolean; + /** + * URL to a file containing the first 30 seconds of the track + */ previewURL: string; + /** + * The artist of the track + */ artist: DeezerArtist; + /** + * The album that this track is in + */ album: DeezerTrackAlbum; + /** + * The type, always `'track'`, useful to determine what the deezer function returned + */ type: 'track' | 'playlist' | 'album'; /** - * true for tracks in search results and false if the track was fetched directly. + * Signifies that some properties are not populated + * + * Partial tracks can be populated by calling {@link DeezerTrack.fetch}. + * + * `true` for tracks in search results and `false` if the track was fetched directly or expanded. */ partial: boolean; + /** + * The position of the track in the album + * + * `undefined` for partial tracks + * + * @see {@link DeezerTrack.partial} + */ trackPosition?: number; + /** + * The number of the disk the track is on + * + * `undefined` for partial tracks + * + * @see {@link DeezerTrack.partial} + */ diskNumber?: number; + /** + * The release date + * + * `undefined` for partial tracks + * + * @see {@link DeezerTrack.partial} + */ releaseDate?: Date; + /** + * The number of beats per minute + * + * `undefined` for partial tracks + * + * @see {@link DeezerTrack.partial} + */ bpm?: number; + /** + * The gain of the track + * + * `undefined` for partial tracks + * + * @see {@link DeezerTrack.partial} + */ gain?: number; + /** + * The artists that have contributed to the track + * + * `undefined` for partial tracks + * + * @see {@link DeezerTrack.partial} + */ contributors?: DeezerArtist[]; + /** + * Creates a Deezer track from the data in an API response + * @param data the data to use to create the track + * @param partial Whether the track should be partial + * @see {@link DeezerTrack.partial} + */ constructor(data: any, partial: boolean) { this.id = data.id; this.title = data.title; @@ -75,7 +194,11 @@ export class DeezerTrack { } /** - * Fetches the missing data for a partial {@link DeezerTrack}. + * Fetches and populates the missing fields + * + * The property {@link partial} will be `false` if this method finishes successfully. + * + * @returns A promise with the same track this method was called on. */ async fetch(): Promise { if (!this.partial) return this; @@ -100,7 +223,10 @@ export class DeezerTrack { return this; } - + /** + * Converts instances of this class to JSON data + * @returns JSON data. + */ toJSON() { return { id: this.id, @@ -127,31 +253,126 @@ export class DeezerTrack { * Class for Deezer Albums */ export class DeezerAlbum { + /** + * The id of the album + */ id: number; + /** + * The title of the album + */ title: string; + /** + * The URL to the album on Deezer + */ url: string; + /** + * The record type of the album (e.g. EP, ALBUM, etc ...) + */ recordType: string; + /** + * `true` if the album contains any explicit lyrics + */ explicit: boolean; + /** + * The artist of the album + */ artist: DeezerArtist; + /** + * The album cover available in four sizes + */ cover: DeezerImage; + /** + * The type, always `'album'`, useful to determine what the deezer function returned + */ type: 'track' | 'playlist' | 'album'; + /** + * The number of tracks in the album + */ tracksCount: number; /** - * true for albums in search results and false if the album was fetched directly. + * Signifies that some properties are not populated + * + * Partial albums can be populated by calling {@link DeezerAlbum.fetch}. + * + * `true` for albums in search results and `false` if the album was fetched directly or expanded. */ partial: boolean; + /** + * The **u**niversal **p**roduct **c**ode of the album + * + * `undefined` for partial albums + * + * @see {@link DeezerAlbum.partial} + */ upc?: string; + /** + * The duration of the album in seconds + * + * `undefined` for partial albums + * + * @see {@link DeezerAlbum.partial} + */ durationInSec?: number; + /** + * The number of fans the album has + * + * `undefined` for partial albums + * + * @see {@link DeezerAlbum.partial} + */ numberOfFans?: number; + /** + * The release date of the album + * + * `undefined` for partial albums + * + * @see {@link DeezerAlbum.partial} + */ releaseDate?: Date; + /** + * Whether the album is available + * + * `undefined` for partial albums + * + * @see {@link DeezerAlbum.partial} + */ available?: boolean; + /** + * The list of genres present in this album + * + * `undefined` for partial albums + * + * @see {@link DeezerAlbum.partial} + */ genres?: DeezerGenre[]; + /** + * The contributors to the album + * + * `undefined` for partial albums + * + * @see {@link DeezerAlbum.partial} + */ contributors?: DeezerArtist[]; + /** + * The list of tracks in the album + * + * empty (length === 0) for partial albums + * + * Use {@link DeezerAlbum.fetch} to populate the tracks and other properties + * + * @see {@link DeezerAlbum.partial} + */ tracks: DeezerTrack[]; + /** + * Creates a Deezer album from the data in an API response + * @param data the data to use to create the album + * @param partial Whether the album should be partial + * @see {@link DeezerAlbum.partial} + */ constructor(data: any, partial: boolean) { this.id = data.id; this.title = data.title; @@ -213,7 +434,11 @@ export class DeezerAlbum { } /** - * Fetches the missing data for a partial {@link DeezerAlbum}. + * Fetches and populates the missing fields including all tracks. + * + * The property {@link DeezerAlbum.partial} will be `false` if this method finishes successfully. + * + * @returns A promise with the same album this method was called on. */ async fetch(): Promise { if (!this.partial) return this; @@ -266,7 +491,10 @@ export class DeezerAlbum { return this; } - + /** + * Converts instances of this class to JSON data + * @returns JSON data. + */ toJSON() { return { id: this.id, @@ -290,29 +518,114 @@ export class DeezerAlbum { } } /** - * Class for Deezer Albums + * Class for Deezer Playlists */ export class DeezerPlaylist { + /** + * The id of the playlist + */ id: number; + /** + * The title of the playlist + */ title: string; + /** + * Whether the playlist is public or private + */ public: boolean; + /** + * The URL of the playlist on Deezer + */ url: string; + /** + * Cover picture of the playlist available in four sizes + */ picture: DeezerImage; + /** + * The date of the playlist's creation + */ creationDate: Date; + /** + * The type, always `'playlist'`, useful to determine what the deezer function returned + */ type: 'track' | 'playlist' | 'album'; + /** + * The Deezer user that created the playlist + */ creator: DeezerUser; + /** + * The number of tracks in the playlist + */ tracksCount: number; + /** + * Signifies that some properties are not populated + * + * Partial playlists can be populated by calling {@link DeezerPlaylist.fetch}. + * + * `true` for playlists in search results and `false` if the album was fetched directly or expanded. + */ partial: boolean; + /** + * Description of the playlist + * + * `undefined` for partial playlists + * + * @see {@link DeezerPlaylist.partial} + */ description?: string; + /** + * Duration of the playlist in seconds + * + * `undefined` for partial playlists + * + * @see {@link DeezerPlaylist.partial} + */ durationInSec?: number; + /** + * `true` if the playlist is the loved tracks playlist + * + * `undefined` for partial playlists + * + * @see {@link DeezerPlaylist.partial} + */ isLoved?: boolean; + /** + * Whether multiple users have worked on the playlist + * + * `undefined` for partial playlists + * + * @see {@link DeezerPlaylist.partial} + */ collaborative?: boolean; + /** + * The number of fans the playlist has + * + * `undefined` for partial playlists + * + * @see {@link DeezerPlaylist.partial} + */ fans?: number; + /** + * The list of tracks in the playlist + * + * empty (length === 0) for partial and non public playlists + * + * Use {@link DeezerPlaylist.fetch} to populate the tracks and other properties + * + * @see {@link DeezerPlaylist.partial} + * @see {@link DeezerPlaylist.public} + */ tracks: DeezerTrack[]; + /** + * Creates a Deezer playlist from the data in an API response + * @param data the data to use to create the playlist + * @param partial Whether the playlist should be partial + * @see {@link DeezerPlaylist.partial} + */ constructor(data: any, partial: boolean) { this.id = data.id; this.title = data.title; @@ -360,8 +673,11 @@ export class DeezerPlaylist { } /** - * Fetches the missing data for a partial {@link DeezerPlaylist} as well as fetching all tracks. - * @returns The Deezer playlist object this method was called on. + * Fetches and populates the missing fields, including all tracks. + * + * The property {@link DeezerPlaylist.partial} will be `false` if this method finishes successfully. + * + * @returns A promise with the same playlist this method was called on. */ async fetch(): Promise { if (!this.partial && (this.tracks.length === this.tracksCount || !this.public)) { @@ -430,7 +746,10 @@ export class DeezerPlaylist { return this; } - + /** + * Converts instances of this class to JSON data + * @returns JSON data. + */ toJSON() { return { id: this.id, @@ -473,12 +792,30 @@ class DeezerTrackAlbum { if (data.release_date) this.releaseDate = new Date(data.release_date); } } - +/** + * Class representing a Deezer artist + */ class DeezerArtist { + /** + * The id of the artist + */ id: number; + /** + * The name of the artist + */ name: string; + /** + * The URL of the artist on Deezer + */ url: string; + + /** + * The picture of the artist available in four sizes + */ picture?: DeezerImage; + /** + * The of the artist on the track + */ role?: string; constructor(data: any) { diff --git a/play-dl/Deezer/index.ts b/play-dl/Deezer/index.ts index 9b77793..12bbf92 100644 --- a/play-dl/Deezer/index.ts +++ b/play-dl/Deezer/index.ts @@ -9,20 +9,56 @@ interface TypeData { } interface DeezerSearchOptions { + /** + * The type to search for `'track'`, `'playlist'` or `'album'`. Defaults to `'track'`. + */ type?: 'track' | 'playlist' | 'album'; + /** + * The maximum number of results to return, maximum `100`, defaults to `10`. + */ limit?: number; + /** + * Whether the search should be fuzzy or only return exact matches. Defaults to `true`. + */ fuzzy?: boolean; } interface DeezerAdvancedSearchOptions { + /** + * The maximum number of results to return, maximum `100`, defaults to `10`. + */ limit?: number; + /** + * The name of the artist. + */ artist?: string; + /** + * The title of the album. + */ album?: string; + /** + * The title of the track. + */ title?: string; + /** + * The label that released the track. + */ label?: string; + /** + * The minimum duration in seconds. + */ minDurationInSec?: number; + /** + * The maximum duration in seconds. + */ maxDurationInSec?: number; + /** + * The minimum BPM. + */ minBPM?: number; + /** + * The minimum BPM. + */ maxBPM?: number; } @@ -139,8 +175,8 @@ export async function deezer(url: string): Promise { /** * Validates a Deezer URL * @param url The URL to validate - * @returns The type of the URL either 'track', 'playlist', 'album', 'search' or false. - * false means that the provided URL was a wrongly formatted or unsupported Deezer URL. + * @returns The type of the URL either `'track'`, `'playlist'`, `'album'`, `'search'` or `false`. + * `false` means that the provided URL was a wrongly formatted or an unsupported Deezer URL. */ export async function dz_validate(url: string): Promise<'track' | 'playlist' | 'album' | 'search' | false> { const typeData = await internalValidate(url);