musicbrainz-api 0.13.0 → 0.14.0

package/README.md

@@ -2,7 +2,7 @@
 [![NPM version](https://img.shields.io/npm/v/musicbrainz-api.svg)](https://npmjs.org/package/musicbrainz-api)
 [![npm downloads](http://img.shields.io/npm/dm/musicbrainz-api.svg)](https://npmcharts.com/compare/musicbrainz-api?interval=30&start=365)
 [![Coverage Status](https://coveralls.io/repos/github/Borewit/musicbrainz-api/badge.svg?branch=master)](https://coveralls.io/github/Borewit/musicbrainz-api?branch=master)
-[![Codacy Badge](https://app.codacy.com/project/badge/Grade/2bc47b2006454bae8c737991f152e518)](https://www.codacy.com/gh/Borewit/musicbrainz-api/dashboard?utm_source=github.com&utm_medium=referral&utm_content=Borewit/musicbrainz-api&utm_campaign=Badge_Grade)
+[![Codacy Badge](https://app.codacy.com/project/badge/Grade/2bc47b2006454bae8c737991f152e518)](https://app.codacy.com/gh/Borewit/musicbrainz-api/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
 [![CodeQL](https://github.com/Borewit/musicbrainz-api/actions/workflows/codeql.yml/badge.svg)](https://github.com/Borewit/musicbrainz-api/actions/workflows/codeql.yml)
 [![Known Vulnerabilities](https://snyk.io/test/github/Borewit/musicbrainz-api/badge.svg?targetFile=package.json)](https://snyk.io/test/github/Borewit/musicbrainz-api?targetFile=package.json)
 [![DeepScan grade](https://deepscan.io/api/teams/5165/projects/6991/branches/63373/badge/grade.svg)](https://deepscan.io/dashboard#view=project&tid=5165&pid=6991&bid=63373)
@@ -82,106 +82,14 @@ MusicBrainz API documentation: [XML Web Service/Version 2 Lookups](https://wiki.
 ### Generic lookup function
 
 Arguments:
-*   entity: `'artist'` | `'label'` | `'recording'` | `'release'` | `'release-group'` | `'work'` | `'area'` | `'url'`
+*   entity: `'area'` | `'artist'` | `'collection'` | `'instrument'` | `'label'` | `'place'` | `'release'` | `'release-group'` | `'recording'` | `'series'` | `'work'` | `'url'` | `'event'`
 *   MBID [(MusicBrainz identifier)](https://wiki.musicbrainz.org/MusicBrainz_Identifier)
+*   query
 
 ```js
-const artist = await mbApi.lookupEntity('artist', 'ab2528d9-719f-4261-8098-21849222a0f2');
+const artist = await mbApi.lookup('artist', 'ab2528d9-719f-4261-8098-21849222a0f2');
 ```
 
-### Lookup area
-
-```js
-const area = await mbApi.lookupArea('ab2528d9-719f-4261-8098-21849222a0f2');
-```
-
-### Lookup artist
-
-Lookup an `artist` and include their `releases`, `release-groups` and `aliases`
-
-```js
-const artist = await mbApi.lookupArtist('ab2528d9-719f-4261-8098-21849222a0f2');
-```
-
-### Lookup collection
-
-Lookup an instrument
-
-```js
-const collection = await mbApi.lookupCollection('de4fdfc4-53aa-458a-b463-8761cc7f5af8');
-```
-
-Lookup an event
-
-```js
-const event = await mbApi.lookupEvent('6d32c658-151e-45ec-88c4-fb8787524d61');
-```
-
-### Lookup instrument
-
-Lookup an instrument
-
-```js
-const instrument = await mbApi.lookupInstrument('b3eac5f9-7859-4416-ac39-7154e2e8d348');
-```
-
-### Lookup label
-
-Lookup a label
-
-```js
-const label = await mbApi.lookupLabel('25dda9f9-f069-4898-82f0-59330a106c7f');
-```
-
-### Lookup place
-
-```js
-const place = await mbApi.lookupPlace('e6cfb74d-d69b-44c3-b890-1b3f509816e4');
-```
-
-```js
-const place = await mbApi.lookupSeries('1ae6c9bc-2931-4d75-bee4-3dc53dfd246a');
-```
-
-The second argument can be used to pass [subqueries](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2#Subqueries), which will return more (nested) information:
-```js
-const artist = await mbApi.lookupArtist('ab2528d9-719f-4261-8098-21849222a0f2', ['releases', 'recordings', 'url-rels']);
-```
-
-### Lookup recording
-
-The second argument can be used to pass [subqueries](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2#Subqueries):
-```js
-const recording = await mbApi.lookupRecording('16afa384-174e-435e-bfa3-5591accda31c', ['artists', 'url-rels']);
-```
-
-### Lookup release
-```js
-const release = await mbApi.lookupRelease('976e0677-a480-4a5e-a177-6a86c1900bbf', ['artists', 'url-rels']);
-```
-
-### Lookup release-group
-```js
-const releaseGroup = await mbApi.lookupReleaseGroup('19099ea5-3600-4154-b482-2ec68815883e');
-```
-
-### Lookup work
-```js
-const work = await mbApi.lookupWork('b2aa02f4-6c95-43be-a426-aedb9f9a3805');
-```
-
-### Lookup URL
-```js
-const url = await mbApi.lookupUrl('c69556a6-7ded-4c54-809c-afb45a1abe7d');
-```
-
-## Browse entities
-
-### Browse area
-
-```js
-const area = await browseAreas(query);
-````
 
 | Query argument        | Query value     | 
 |-----------------------|-----------------|  
@@ -190,7 +98,7 @@ const area = await browseAreas(query);
 ### Browse artist
 
 ```js
-const artist = await browseArtist(query);
+const artists = await browse('artist', query);
 ````
 
 | Query argument        | Query value        | 
@@ -204,7 +112,7 @@ const artist = await browseArtist(query);
 
 ### Browse collection
 ```js
-const artist = await browseCollection(query);
+const collections = await browse('collection', query);
 ````
 
 | Query argument        | Query value        | 
@@ -222,7 +130,7 @@ const artist = await browseCollection(query);
 
 ### Browse events
 ```js
-const events = await browseEvents(query);
+const events = await browse('event', query);
 ````
 
 | Query argument        | Query value     | 
@@ -234,7 +142,7 @@ const events = await browseEvents(query);
 
 ### Browse instruments
 ```js
-const instruments = await browseEvents(query);
+const instruments = await browse('event', query);
 ````
 
 | Query argument        | Query value        | 
@@ -243,7 +151,7 @@ const instruments = await browseEvents(query);
 
 ### Browse labels
 ```js
-const labels = await browseLabels(query);
+const labels = await browse('label', query);
 ````
 
 | Query argument     | Query value     | 
@@ -254,7 +162,7 @@ const labels = await browseLabels(query);
 
 ### Browse places
 ```js
-const places = await browsePlaces(query);
+const places = await browse('place', query);
 ````
 
 | Query argument     | Query value     | 
@@ -264,7 +172,7 @@ const places = await browsePlaces(query);
 
 ### Browse recordings
 ```js
-const recordings = await browseRecordings(query);
+const recordings = await browse('recording', query);
 ````
 
 | Query argument     | Query value     | 
@@ -276,7 +184,7 @@ const recordings = await browseRecordings(query);
 
 ### Browse releases
 ```js
-const places = await browseReleases(query);
+const releases = await browse('release', query);
 ````
 
 | Query argument        | Query value        | 
@@ -294,7 +202,7 @@ const places = await browseReleases(query);
 
 ### Browse release-groups
 ```js
-const places = await browseReleaseGroups(query);
+const releaseGroups = await browse('release-group',query);
 ```
 
 | Query argument     | Query value     | 
@@ -305,7 +213,7 @@ const places = await browseReleaseGroups(query);
 
 ### Browse series
 ```js
-const places = await browseSeries();
+const series = await browse('series');
 ````
 
 | Query argument        | Query value        | 
@@ -323,7 +231,7 @@ const places = await browseSeries();
 
 ### Browse works
 ```js
-const places = await browseWorks();
+const works = await browse('work');
 ````
 
 | Query argument     | Query value     | 
@@ -333,7 +241,7 @@ const places = await browseWorks();
 
 ### Browse urls
 ```js
-const urls = await browseUrls();
+const urls = await browse('url');
 ````
 
 | Query argument     | Query value     | 
@@ -347,9 +255,9 @@ Implements [XML Web Service/Version 2/Search](https://wiki.musicbrainz.org/Devel
 
 There are different search fields depending on the entity.
 
-### Generic search function
+### Search function
 
-Searches can be performed using the generic search function: `query(entity: mb.EntityType, query: string | IFormData, offset?: number, limit?: number)`
+Searches can be performed using the generic search function: `query(entity: mb.EntityType, query: string | IFormData, offset?: number, limit?: number): Promise<entity>`
 
 Arguments:
 *   Entity type, which can be one of:
@@ -392,27 +300,25 @@ Same as previous example, but automatically serialize parameters to search query
  mbApi.search('release', 'barcode: 602537479870');
 ````
 
-### Entity specific search functions
-
-The following entity specific search functions are available:
-```TypeScript
-searchArtist(query: string | IFormData, offset?: number, limit?: number): Promise<mb.IArtistList>
-searchReleaseGroup(query: string | IFormData, offset?: number, limit?: number): Promise<mb.IReleaseGroupList>`
-```
+##### Example: search artist by artist name
 
 Search artist:
 ```js
-const result = await mbApi.searchArtist({query: 'Stromae'});
+const result = await mbApi.search('artist', {query: 'Stromae'});
 ```
 
+##### Example: search release-group by artist name
+
 Search release-group:
 ```js
-const result = await mbApi.searchReleaseGroup({query: 'Racine carrée'});
+const result = await mbApi.search('release-group', {query: 'Racine carrée'});
 ```
 
+##### Example: search release-group by release-group and an artist
+
 Search a combination of a release-group and an artist.
 ```js
-const result = await mbApi.searchReleaseGroup({artist: 'Racine carrée', releasegroup: 'Stromae'});
+const result = await mbApi.search('release-group', {artist: 'Racine carrée', releasegroup: 'Stromae'});
 ```
 
 # Submitting data via XML POST
@@ -439,7 +345,7 @@ For all of the following function you need to use a dedicated bot account.
 
 ## Submitting ISRC via post user form-data
 
-<img width="150" src="http://www.clker.com/cliparts/i/w/L/q/u/1/work-in-progress.svg"/>
+<img width="150" src="http://www.clker.com/cliparts/i/w/L/q/u/1/work-in-progress.svg" alt="Work in progress"/>
 Use with caution, and only on a test server, it may clear existing metadata as side effect.
       
 ```js
@@ -448,7 +354,7 @@ const mbid_Formidable = '16afa384-174e-435e-bfa3-5591accda31c';
 const isrc_Formidable = 'BET671300161';
 
     
-const recording = await mbApi.lookupRecording(mbid_Formidable);
+const recording = await mbApi.lookup('recording', mbid_Formidable);
 
 // Authentication the http-session against MusicBrainz (as defined in config.baseUrl)
 const succeed = await mbApi.login();
@@ -461,7 +367,7 @@ await mbApi.addIsrc(recording, isrc_Formidable);
 ### Submit recording URL
 
 ```js
-const recording = await mbApi.lookupRecording('16afa384-174e-435e-bfa3-5591accda31c');
+const recording = await mbApi.lookup('recording', '16afa384-174e-435e-bfa3-5591accda31c');
 
 const succeed = await mbApi.login();
 assert.isTrue(succeed, 'Login successful');
@@ -474,7 +380,7 @@ await mbApi.addUrlToRecording(recording, {
 
 Actually a Spotify-track-ID can be submitted easier: 
 ```js
-const recording = await mbApi.lookupRecording('16afa384-174e-435e-bfa3-5591accda31c');
+const recording = await mbApi.lookup('recording', '16afa384-174e-435e-bfa3-5591accda31c');
 
 const succeed = await mbApi.login();
 assert.isTrue(succeed, 'Login successful');

package/lib/musicbrainz-api.d.ts

@@ -37,7 +37,7 @@ export type InstrumentIncludes = MiscIncludes | RelationsIncludes;
 export type LabelIncludes = MiscIncludes | RelationsIncludes | 'releases';
 export type PlaceIncludes = MiscIncludes | RelationsIncludes;
 export type RecordingIncludes = MiscIncludes | RelationsIncludes | SubQueryIncludes | 'artists' | 'releases' | 'isrcs';
-export type ReleasesIncludes = MiscIncludes | SubQueryIncludes | RelationsIncludes | 'artists' | 'collections' | 'labels' | 'recordings' | 'release-groups';
+export type ReleaseIncludes = MiscIncludes | SubQueryIncludes | RelationsIncludes | 'artists' | 'collections' | 'labels' | 'recordings' | 'release-groups';
 export type ReleaseGroupIncludes = MiscIncludes | SubQueryIncludes | RelationsIncludes | 'artists' | 'releases';
 export type SeriesIncludes = MiscIncludes | RelationsIncludes;
 export type WorkIncludes = MiscIncludes | RelationsIncludes;
@@ -84,162 +84,58 @@ export declare class MusicBrainzApi {
         [key: string]: any;
     }, attempt?: number): Promise<T>;
     /**
-     * Generic lookup function
-     * @param entity
-     * @param mbid
-     * @param inc
-     */
-    lookupEntity<T, I extends string = never>(entity: mb.EntityType, mbid: string, inc?: I[]): Promise<T>;
-    /**
-     * Lookup area
-     * @param areaId Area MBID
-     * @param inc Sub-queries
-     */
-    lookupArea(areaId: string, inc?: AreaIncludes[]): Promise<mb.IArea>;
-    /**
-     * Lookup artist
-     * @param artistId Artist MBID
-     * @param inc Sub-queries
-     */
-    lookupArtist(artistId: string, inc?: ArtistIncludes[]): Promise<mb.IArtist>;
-    /**
-     * Lookup collection
-     * @param collectionId Collection MBID
-     * @param inc List of additional information to be included about the entity. Any of the entities directly linked to the entity can be included.
-     */
-    lookupCollection(collectionId: string, inc?: ArtistIncludes[]): Promise<mb.ICollection>;
-    /**
-     * Lookup instrument
-     * @param artistId Instrument MBID
-     * @param inc Sub-queries
-     */
-    lookupInstrument(instrumentId: string, inc?: InstrumentIncludes[]): Promise<mb.IInstrument>;
-    /**
-     * Lookup label
-     * @param labelId Area MBID
-     * @param inc Sub-queries
-     */
-    lookupLabel(labelId: string, inc?: LabelIncludes[]): Promise<mb.ILabel>;
-    /**
-     * Lookup place
-     * @param placeId Area MBID
-     * @param inc Sub-queries
-     */
-    lookupPlace(placeId: string, inc?: PlaceIncludes[]): Promise<mb.IPlace>;
-    /**
-     * Lookup release
-     * @param releaseId Release MBID
-     * @param inc Include: artist-credits, labels, recordings, release-groups, media, discids, isrcs (with recordings)
-     * ToDo: ['recordings', 'artists', 'artist-credits', 'isrcs', 'url-rels', 'release-groups']
-     */
-    lookupRelease(releaseId: string, inc?: ReleasesIncludes[]): Promise<mb.IRelease>;
-    /**
-     * Lookup release-group
-     * @param releaseGroupId Release-group MBID
-     * @param inc Include: ToDo
-     */
-    lookupReleaseGroup(releaseGroupId: string, inc?: ReleaseGroupIncludes[]): Promise<mb.IReleaseGroup>;
-    /**
-     * Lookup recording
-     * @param recordingId Label MBID
-     * @param inc Include: artist-credits, isrcs
-     */
-    lookupRecording(recordingId: string, inc?: RecordingIncludes[]): Promise<mb.IRecording>;
-    /**
-     * Lookup series
-     * @param seriesId Series MBID
-     */
-    lookupSeries(seriesId: string): Promise<mb.ISeries>;
-    /**
-     * Lookup work
-     * @param workId Work MBID
-     */
-    lookupWork(workId: string, inc?: WorkIncludes[]): Promise<mb.IWork>;
-    /**
-     * Lookup URL
-     * @param urlId URL MBID
-     */
-    lookupUrl(urlId: string, inc?: UrlIncludes[]): Promise<mb.IUrl>;
-    /**
-     * Lookup Event
-     * @param eventId Event MBID
-     * @param eventIncludes List of sub-queries to enable
-     */
-    lookupEvent(eventId: string, eventIncludes?: EventIncludes[]): Promise<mb.IEvent>;
-    /**
-     * Generic browse function
+     * Lookup entity
+     * @param entity 'area', 'artist', collection', 'instrument', 'label', 'place', 'release', 'release-group', 'recording', 'series', 'work', 'url' or 'event'
+     * @param mbid Entity MBID
+     * @param inc Query, like: {<entity>: <MBID:}
+     */
+    lookup(entity: 'area', mbid: string, inc?: AreaIncludes[]): Promise<mb.IArea>;
+    lookup(entity: 'artist', mbid: string, inc?: ArtistIncludes[]): Promise<mb.IArtist>;
+    lookup(entity: 'collection', mbid: string, inc?: CollectionIncludes[]): Promise<mb.ICollection>;
+    lookup(entity: 'instrument', mbid: string, inc?: InstrumentIncludes[]): Promise<mb.IInstrument>;
+    lookup(entity: 'label', mbid: string, inc?: LabelIncludes[]): Promise<mb.ILabel>;
+    lookup(entity: 'place', mbid: string, inc?: PlaceIncludes[]): Promise<mb.IPlace>;
+    lookup(entity: 'release', mbid: string, inc?: ReleaseIncludes[]): Promise<mb.IRelease>;
+    lookup(entity: 'release-group', mbid: string, inc?: ReleaseGroupIncludes[]): Promise<mb.IReleaseGroup>;
+    lookup(entity: 'recording', mbid: string, inc?: RecordingIncludes[]): Promise<mb.IRecording>;
+    lookup(entity: 'series', mbid: string, inc?: SeriesIncludes[]): Promise<mb.ISeries>;
+    lookup(entity: 'work', mbid: string, inc?: WorkIncludes[]): Promise<mb.IWork>;
+    lookup(entity: 'url', mbid: string, inc?: UrlIncludes[]): Promise<mb.IUrl>;
+    lookup(entity: 'event', mbid: string, inc?: EventIncludes[]): Promise<mb.IEvent>;
+    /**
+     * Browse entity
+     * https://wiki.musicbrainz.org/MusicBrainz_API#Browse
+     * https://wiki.musicbrainz.org/MusicBrainz_API#Linked_entities
      * https://wiki.musicbrainz.org/Development/JSON_Web_Service#Browse_Requests
+     * For example: http://musicbrainz.org/ws/2/release?label=47e718e1-7ee4-460c-b1cc-1192a841c6e5&offset=12&limit=2
      * @param entity MusicBrainz entity
      * @param query Query, like: {<entity>: <MBID:}
      */
-    browseEntity<T>(entity: mb.EntityType, query?: {
-        [key: string]: any;
-    }): Promise<T>;
-    /**
-     * Browse areas
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browseAreas(query?: mb.IBrowseAreasQuery): Promise<mb.IBrowseAreasResult>;
-    /**
-     * Browse artists
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browseArtists(query?: mb.IBrowseArtistsQuery): Promise<mb.IBrowseArtistsResult>;
-    /**
-     * Browse collections
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browseCollections(query?: mb.IBrowseCollectionsQuery): Promise<mb.IBrowseCollectionsResult>;
+    browse(entity: 'area', query?: mb.IBrowseAreasQuery): Promise<mb.IBrowseAreasResult>;
+    browse(entity: 'artist', query?: mb.IBrowseArtistsQuery): Promise<mb.IBrowseArtistsResult>;
+    browse(entity: 'collection', query?: mb.IBrowseCollectionsQuery): Promise<mb.IBrowseCollectionsResult>;
+    browse(entity: 'event', query?: mb.IBrowseEventsQuery): Promise<mb.IBrowseEventsResult>;
+    browse(entity: 'label', query?: mb.IBrowseLabelsQuery): Promise<mb.IBrowseLabelsResult>;
+    browse(entity: 'instrument', query?: mb.IBrowseInstrumentsQuery): Promise<mb.IBrowseInstrumentsResult>;
+    browse(entity: 'place', query?: mb.IBrowsePlacesQuery): Promise<mb.IBrowsePlacesResult>;
+    browse(entity: 'recording', query?: mb.IBrowseRecordingsQuery): Promise<mb.IBrowseRecordingsResult>;
+    browse(entity: 'release', query?: mb.IBrowseReleasesQuery): Promise<mb.IBrowseReleasesResult>;
+    browse(entity: 'release-group', query?: mb.IBrowseReleaseGroupsQuery): Promise<mb.IBrowseReleaseGroupsResult>;
+    browse(entity: 'series', query?: mb.IBrowseSeriesQuery): Promise<mb.IBrowseSeriesResult>;
+    browse(entity: 'url', query?: mb.IBrowseUrlsQuery): Promise<mb.IUrl>;
+    browse(entity: 'work', query?: mb.IBrowseWorksQuery): Promise<mb.IBrowseWorksResult>;
     /**
-     * Browse events
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browseEvents(query?: mb.IBrowseEventsQuery): Promise<mb.IBrowseEventsResult>;
-    /**
-     * Browse instruments
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browseInstruments(query?: mb.IBrowseInstrumentsQuery): Promise<mb.IBrowseInstrumentsResult>;
-    /**
-     * Browse labels
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browseLabels(query?: mb.IBrowseLabelsQuery): Promise<mb.IBrowseLabelsResult>;
-    /**
-     * Browse places
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browsePlaces(query?: mb.IBrowsePlacesQuery): Promise<mb.IBrowsePlacesResult>;
-    /**
-     * Browse recordings
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browseRecordings(query?: mb.IBrowseRecordingsQuery): Promise<mb.IBrowseRecordingsResult>;
-    /**
-     * Browse releases
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browseReleases(query?: mb.IBrowseReleasesQuery): Promise<mb.IBrowseReleasesResult>;
-    /**
-     * Browse release-groups
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browseReleaseGroups(query?: mb.IReleaseGroupsQuery): Promise<mb.IBrowseReleaseGroupsResult>;
-    /**
-     * Browse series
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browseSeries(query?: mb.IBrowseSeriesQuery): Promise<mb.IBrowseSeriesResult>;
-    /**
-     * Browse works
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browseWorks(query?: mb.IBrowseWorksQuery): Promise<mb.IBrowseWorksResult>;
-    /**
-     * Browse URLs
-     * @param query Query, like: {<entity>: <MBID:}
+     * Search an entity using a search query
+     * @param query e.g.: '" artist: Madonna, track: Like a virgin"' or object with search terms: {artist: Madonna}
+     * @param entity e.g. 'recording'
+     * @param query Arguments
      */
-    browseUrls(query?: mb.IBrowseUrlsQuery): Promise<mb.IUrl>;
+    search(entity: 'area', query: mb.ISearchQuery<AreaIncludes> & mb.ILinkedEntitiesArea): Promise<mb.IAreaList>;
+    search(artist: 'artist', query: mb.ISearchQuery<ArtistIncludes> & mb.ILinkedEntitiesArea): Promise<mb.IArtistList>;
+    search(artist: 'recording', query: mb.ISearchQuery<AreaIncludes> & mb.ILinkedEntitiesArea): Promise<mb.IRecordingList>;
+    search(artist: 'release', query: mb.ISearchQuery<ReleaseIncludes> & mb.ILinkedEntitiesArea): Promise<mb.IReleaseList>;
+    search(artist: 'release-group', query: mb.ISearchQuery<ReleaseGroupIncludes> & mb.ILinkedEntitiesArea): Promise<mb.IReleaseGroupList>;
+    search(artist: 'url', query: mb.ISearchQuery<UrlIncludes> & mb.ILinkedEntitiesArea): Promise<mb.IUrlList>;
     postRecording(xmlMetadata: XmlMetadata): Promise<void>;
     post(entity: mb.EntityType, xmlMetadata: XmlMetadata): Promise<void>;
     login(): Promise<boolean>;
@@ -271,13 +167,6 @@ export declare class MusicBrainzApi {
      * @param editNote Edit note
      */
     addIsrc(recording: mb.IRecording, isrc: string, editNote?: string): Promise<void>;
-    /**
-     * Search an entity using a search query
-     * @param query e.g.: '" artist: Madonna, track: Like a virgin"' or object with search terms: {artist: Madonna}
-     * @param entity e.g. 'recording'
-     * @param query Arguments
-     */
-    search<T extends mb.ISearchResult, I extends string = never>(entity: mb.EntityType, query: mb.ISearchQuery<I>): Promise<T>;
     /**
      * Add Spotify-ID to MusicBrainz recording.
      * This function will automatically lookup the recording title, which is required to submit the recording URL
@@ -286,11 +175,6 @@ export declare class MusicBrainzApi {
      * @param editNote Comment to add.
      */
     addSpotifyIdToRecording(recording: mb.IRecording, spotifyId: string, editNote: string): Promise<void>;
-    searchArea(query: mb.ISearchQuery<AreaIncludes> & mb.ILinkedEntitiesArea): Promise<mb.IAreaList>;
-    searchArtist(query: mb.ISearchQuery<ArtistIncludes> & mb.ILinkedEntitiesArtist): Promise<mb.IArtistList>;
-    searchRelease(query: mb.ISearchQuery<ReleasesIncludes> & mb.ILinkedEntitiesRelease): Promise<mb.IReleaseList>;
-    searchReleaseGroup(query: mb.ISearchQuery<ReleaseGroupIncludes> & mb.ILinkedEntitiesReleaseGroup): Promise<mb.IReleaseGroupList>;
-    searchUrl(query: mb.ISearchQuery<UrlIncludes> & mb.ILinkedEntitiesUrl): Promise<mb.IUrlList>;
     private getSession;
 }
 export declare function makeAndQueryString(keyValuePairs: IFormData): string;

package/lib/musicbrainz-api.js

@@ -6,7 +6,7 @@ export { XmlIsrc } from './xml/xml-isrc.js';
 export { XmlIsrcList } from './xml/xml-isrc-list.js';
 export { XmlRecording } from './xml/xml-recording.js';
 import { DigestAuth } from './digest-auth.js';
-import { RateLimiter } from './rate-limiter.js';
+import { RateLimitThreshold } from 'rate-limit-threshold';
 import * as mb from './musicbrainz.types.js';
 import got from 'got';
 import { CookieJar } from 'tough-cookie';
@@ -80,11 +80,12 @@ export class MusicBrainzApi {
             },
             cookieJar: cookieJar
         };
-        this.rateLimiter = new RateLimiter(15, 18);
+        this.rateLimiter = new RateLimitThreshold(15, 18);
     }
     async restGet(relUrl, query = {}, attempt = 1) {
         query.fmt = 'json';
-        await this.rateLimiter.limit();
+        const delay = await this.rateLimiter.limit();
+        debug(`Client side rate limiter activated: cool down for ${Math.round(delay / 100) / 10} s...`);
         const response = await got.get('ws/2' + relUrl, {
             ...this.options,
             searchParams: query,
@@ -95,225 +96,21 @@ export class MusicBrainzApi {
         });
         return response.body;
     }
-    // -----------------------------------------------------------------------------------------------------------------
-    // Lookup functions
-    // -----------------------------------------------------------------------------------------------------------------
-    /**
-     * Generic lookup function
-     * @param entity
-     * @param mbid
-     * @param inc
-     */
-    lookupEntity(entity, mbid, inc = []) {
+    lookup(entity, mbid, inc = []) {
         return this.restGet(`/${entity}/${mbid}`, { inc: inc.join(' ') });
     }
-    /**
-     * Lookup area
-     * @param areaId Area MBID
-     * @param inc Sub-queries
-     */
-    lookupArea(areaId, inc = []) {
-        return this.lookupEntity('area', areaId, inc);
-    }
-    /**
-     * Lookup artist
-     * @param artistId Artist MBID
-     * @param inc Sub-queries
-     */
-    lookupArtist(artistId, inc = []) {
-        return this.lookupEntity('artist', artistId, inc);
-    }
-    /**
-     * Lookup collection
-     * @param collectionId Collection MBID
-     * @param inc List of additional information to be included about the entity. Any of the entities directly linked to the entity can be included.
-     */
-    lookupCollection(collectionId, inc = []) {
-        return this.lookupEntity('collection', collectionId, inc);
-    }
-    /**
-     * Lookup instrument
-     * @param artistId Instrument MBID
-     * @param inc Sub-queries
-     */
-    lookupInstrument(instrumentId, inc = []) {
-        return this.lookupEntity('instrument', instrumentId, inc);
-    }
-    /**
-     * Lookup label
-     * @param labelId Area MBID
-     * @param inc Sub-queries
-     */
-    lookupLabel(labelId, inc = []) {
-        return this.lookupEntity('label', labelId, inc);
-    }
-    /**
-     * Lookup place
-     * @param placeId Area MBID
-     * @param inc Sub-queries
-     */
-    lookupPlace(placeId, inc = []) {
-        return this.lookupEntity('place', placeId, inc);
-    }
-    /**
-     * Lookup release
-     * @param releaseId Release MBID
-     * @param inc Include: artist-credits, labels, recordings, release-groups, media, discids, isrcs (with recordings)
-     * ToDo: ['recordings', 'artists', 'artist-credits', 'isrcs', 'url-rels', 'release-groups']
-     */
-    lookupRelease(releaseId, inc = []) {
-        return this.lookupEntity('release', releaseId, inc);
-    }
-    /**
-     * Lookup release-group
-     * @param releaseGroupId Release-group MBID
-     * @param inc Include: ToDo
-     */
-    lookupReleaseGroup(releaseGroupId, inc = []) {
-        return this.lookupEntity('release-group', releaseGroupId, inc);
-    }
-    /**
-     * Lookup recording
-     * @param recordingId Label MBID
-     * @param inc Include: artist-credits, isrcs
-     */
-    lookupRecording(recordingId, inc = []) {
-        return this.lookupEntity('recording', recordingId, inc);
-    }
-    /**
-     * Lookup series
-     * @param seriesId Series MBID
-     */
-    lookupSeries(seriesId) {
-        return this.lookupEntity('series', seriesId);
-    }
-    /**
-     * Lookup work
-     * @param workId Work MBID
-     */
-    lookupWork(workId, inc = []) {
-        return this.lookupEntity('work', workId, inc);
-    }
-    /**
-     * Lookup URL
-     * @param urlId URL MBID
-     */
-    lookupUrl(urlId, inc = []) {
-        return this.lookupEntity('url', urlId, inc);
-    }
-    /**
-     * Lookup Event
-     * @param eventId Event MBID
-     * @param eventIncludes List of sub-queries to enable
-     */
-    lookupEvent(eventId, eventIncludes = []) {
-        return this.lookupEntity('event', eventId, eventIncludes);
-    }
-    // -----------------------------------------------------------------------------------------------------------------
-    // Browse functions
-    // -----------------------------------------------------------------------------------------------------------------
-    // https://wiki.musicbrainz.org/MusicBrainz_API#Browse
-    // https://wiki.musicbrainz.org/MusicBrainz_API#Linked_entities
-    // For example: http://musicbrainz.org/ws/2/release?label=47e718e1-7ee4-460c-b1cc-1192a841c6e5&offset=12&limit=2
-    /**
-     * Generic browse function
-     * https://wiki.musicbrainz.org/Development/JSON_Web_Service#Browse_Requests
-     * @param entity MusicBrainz entity
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browseEntity(entity, query) {
+    browse(entity, query) {
         return this.restGet(`/${entity}`, query);
     }
-    /**
-     * Browse areas
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browseAreas(query) {
-        return this.browseEntity('area', query);
-    }
-    /**
-     * Browse artists
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browseArtists(query) {
-        return this.browseEntity('artist', query);
-    }
-    /**
-     * Browse collections
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browseCollections(query) {
-        return this.browseEntity('collection', query);
-    }
-    /**
-     * Browse events
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browseEvents(query) {
-        return this.browseEntity('event', query);
-    }
-    /**
-     * Browse instruments
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browseInstruments(query) {
-        return this.browseEntity('instrument', query);
-    }
-    /**
-     * Browse labels
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browseLabels(query) {
-        return this.browseEntity('label', query);
-    }
-    /**
-     * Browse places
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browsePlaces(query) {
-        return this.browseEntity('place', query);
-    }
-    /**
-     * Browse recordings
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browseRecordings(query) {
-        return this.browseEntity('recording', query);
-    }
-    /**
-     * Browse releases
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browseReleases(query) {
-        return this.browseEntity('release', query);
-    }
-    /**
-     * Browse release-groups
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browseReleaseGroups(query) {
-        return this.browseEntity('release-group', query);
-    }
-    /**
-     * Browse series
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browseSeries(query) {
-        return this.browseEntity('series', query);
-    }
-    /**
-     * Browse works
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browseWorks(query) {
-        return this.browseEntity('work', query);
-    }
-    /**
-     * Browse URLs
-     * @param query Query, like: {<entity>: <MBID:}
-     */
-    browseUrls(query) {
-        return this.browseEntity('url', query);
+    search(entity, query) {
+        const urlQuery = { ...query };
+        if (typeof query.query === 'object') {
+            urlQuery.query = makeAndQueryString(query.query);
+        }
+        if (Array.isArray(query.inc)) {
+            urlQuery.inc = urlQuery.inc.join(' ');
+        }
+        return this.restGet('/' + entity + '/', urlQuery);
     }
     // ---------------------------------------------------------------------------
     async postRecording(xmlMetadata) {
@@ -470,25 +267,6 @@ export class MusicBrainzApi {
         }
     }
     // -----------------------------------------------------------------------------------------------------------------
-    // Query functions
-    // -----------------------------------------------------------------------------------------------------------------
-    /**
-     * Search an entity using a search query
-     * @param query e.g.: '" artist: Madonna, track: Like a virgin"' or object with search terms: {artist: Madonna}
-     * @param entity e.g. 'recording'
-     * @param query Arguments
-     */
-    search(entity, query) {
-        const urlQuery = { ...query };
-        if (typeof query.query === 'object') {
-            urlQuery.query = makeAndQueryString(query.query);
-        }
-        if (Array.isArray(query.inc)) {
-            urlQuery.inc = urlQuery.inc.join(' ');
-        }
-        return this.restGet('/' + entity + '/', urlQuery);
-    }
-    // -----------------------------------------------------------------------------------------------------------------
     // Helper functions
     // -----------------------------------------------------------------------------------------------------------------
     /**
@@ -505,21 +283,6 @@ export class MusicBrainzApi {
             text: 'https://open.spotify.com/track/' + spotifyId
         }, editNote);
     }
-    searchArea(query) {
-        return this.search('area', query);
-    }
-    searchArtist(query) {
-        return this.search('artist', query);
-    }
-    searchRelease(query) {
-        return this.search('release', query);
-    }
-    searchReleaseGroup(query) {
-        return this.search('release-group', query);
-    }
-    searchUrl(query) {
-        return this.search('url', query);
-    }
     async getSession() {
         const response = await got.get('login', {
             ...this.options,

package/lib/musicbrainz.types.d.ts

@@ -104,6 +104,7 @@ export interface IRelease extends IEntity {
     relations?: IRelation[];
     'artist-credit'?: IArtistCredit[];
     'release-group'?: IReleaseGroup;
+    collections?: ICollection[];
 }
 export interface IReleaseEvent {
     area?: IArea;
@@ -162,14 +163,16 @@ export interface IReleaseGroup extends IEntity {
     }[];
     releases?: IRelease[];
 }
+export interface IAreaMatch extends IArea, IMatch {
+}
 export interface IArtistMatch extends IArtist, IMatch {
 }
+export interface IRecordingMatch extends IRecording, IMatch {
+}
 export interface IReleaseGroupMatch extends IReleaseGroup, IMatch {
 }
 export interface IReleaseMatch extends IRelease, IMatch {
 }
-export interface IAreaMatch extends IArea, IMatch {
-}
 export interface ISearchResult {
     created: DateTimeFormat;
     count: number;
@@ -185,6 +188,10 @@ export interface IReleaseList extends ISearchResult {
     releases: IReleaseMatch[];
     'release-count': number;
 }
+export interface IRecordingList extends ISearchResult {
+    recordings: IRecordingMatch[];
+    'recordings-count': number;
+}
 export interface IReleaseGroupList extends ISearchResult {
     'release-groups': IReleaseGroupMatch[];
 }
@@ -285,6 +292,7 @@ export interface ISearchQuery<I extends string> extends IPagination {
      */
     query?: string | IFormData;
     inc?: I[];
+    artist?: string;
 }
 /**
  * https://musicbrainz.org/doc/MusicBrainz_API#Browse
@@ -508,7 +516,7 @@ export interface IBrowseReleasesQuery extends IPagination {
 /**
  * Browse release-groups query <entity>: <MBID>
  */
-export interface IReleaseGroupsQuery extends IPagination {
+export interface IBrowseReleaseGroupsQuery extends IPagination {
     artist?: string;
     collection?: string;
     release?: string;
@@ -586,12 +594,12 @@ export interface IBrowseReleaseGroupsResult {
     'release-group-offset': number;
 }
 export interface IBrowseSeriesResult {
-    series: IReleaseGroupsQuery[];
+    series: IReleaseGroup[];
     'series-count': number;
     'series-offset': number;
 }
 export interface IBrowseWorksResult {
-    works: IReleaseGroupsQuery[];
+    works: IReleaseGroup[];
     'work-count': number;
     'work-offset': number;
 }

package/lib/musicbrainz.types.js

@@ -10,5 +10,5 @@ export var LinkType;
     LinkType[LinkType["crowdfunding_page"] = 905] = "crowdfunding_page";
     LinkType[LinkType["other_databases"] = 306] = "other_databases";
     LinkType[LinkType["Allmusic"] = 285] = "Allmusic";
-})(LinkType = LinkType || (LinkType = {}));
+})(LinkType || (LinkType = {}));
 //# sourceMappingURL=musicbrainz.types.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "musicbrainz-api",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "MusicBrainz API client for reading and submitting metadata",
   "exports": "./lib/index.js",
   "types": "lib/index.d.ts",
@@ -55,6 +55,7 @@
     "http-status-codes": "^2.1.4",
     "json-stringify-safe": "^5.0.1",
     "jsontoxml": "^1.0.1",
+    "rate-limit-threshold": "^0.1.5",
     "source-map-support": "^0.5.16",
     "tough-cookie": "^4.1.3",
     "uuid": "^9.0.0"
@@ -62,7 +63,7 @@
   "devDependencies": {
     "@types/chai": "^4.3.0",
     "@types/jsontoxml": "^1.0.5",
-    "@types/mocha": "^9.0.0",
+    "@types/mocha": "^10.0.4",
     "@types/node": "^20.8.10",
     "@typescript-eslint/eslint-plugin": "^5.13.0",
     "@typescript-eslint/parser": "^5.13.0",
@@ -70,17 +71,16 @@
     "chai": "^4.2.0",
     "del-cli": "^5.0.0",
     "eslint": "^8.10.0",
-    "eslint-config-prettier": "^8.4.0",
+    "eslint-config-prettier": "^9.0.0",
     "eslint-import-resolver-typescript": "^3.3.0",
     "eslint-plugin-import": "^2.25.4",
     "eslint-plugin-jsdoc": "^46.8.2",
     "eslint-plugin-node": "^11.1.0",
-    "eslint-plugin-unicorn": "^46.0.0",
+    "eslint-plugin-unicorn": "^49.0.0",
     "mocha": "^10.1.0",
-    "remark-cli": "^11.0.0",
+    "remark-cli": "^12.0.0",
     "remark-preset-lint-recommended": "^6.1.2",
     "ts-node": "^10.0.0",
-    "tslint": "^6.1.1",
     "typescript": "^5.0.2"
   },
   "scripts": {

package/lib/rate-limiter.d.ts

@@ -1,8 +0,0 @@
-export declare class RateLimiter {
-    private maxCalls;
-    static sleep(ms: number): Promise<void>;
-    queue: number[];
-    private readonly period;
-    constructor(maxCalls: number, period: number);
-    limit(): Promise<void>;
-}

package/lib/rate-limiter.js

@@ -1,30 +0,0 @@
-import Debug from 'debug';
-const debug = Debug('musicbrainz-api:rate-limiter');
-export class RateLimiter {
-    static sleep(ms) {
-        return new Promise(resolve => setTimeout(resolve, ms));
-    }
-    constructor(maxCalls, period) {
-        this.maxCalls = maxCalls;
-        this.queue = [];
-        debug(`Rate limiter initialized with max ${maxCalls} calls in ${period} seconds.`);
-        this.period = 1000 * period;
-    }
-    async limit() {
-        let now = new Date().getTime();
-        const t0 = now - (this.period);
-        while (this.queue.length > 0 && this.queue[0] < t0) {
-            this.queue.shift();
-        }
-        // debug(`Current rate is  ${this.queue.length} per ${this.period / 1000} sec`);
-        if (this.queue.length >= this.maxCalls) {
-            const delay = this.queue[0] + this.period - now;
-            debug(`Client side rate limiter activated: cool down for ${delay / 1000} s...`);
-            return RateLimiter.sleep(delay);
-        }
-        now = new Date().getTime();
-        this.queue.push(now);
-        // const ratePerSec = 1000 * this.queue.length / (now - this.queue[0]);
-    }
-}
-//# sourceMappingURL=rate-limiter.js.map