Histmy/play-dl-fix
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Significantly improve the docs for the Deezer classes and functions

Browse Source
This commit is contained in:
absidue 2021-12-08 19:08:20 +01:00
parent a4d725e24d
commit d3f9555f41
2 changed files with 387 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

361
play-dl/Deezer/classes.ts
View File

@ -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<DeezerTrack> {
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<DeezerAlbum> {
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<DeezerPlaylist> {
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) {

40
play-dl/Deezer/index.ts
View File

@ -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<Deezer> {
/**
* 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);