musicbrainz-api 0.23.1 → 0.24.0

package/README.md

@@ -111,7 +111,8 @@ The MusicBrainz API allows you to look up various entities. Here’s how to use
 
 ## Lookup MusicBrainz Entities
 
-MusicBrainz API documentation: [XML Web Service/Version 2 Lookups](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2#Lookups)
+You can use the lookup function, to look up an entity, when you have the MBID for that entity.
+MusicBrainz API documentation: [MusicBrainz API - Lookups](https://wiki.musicbrainz.org/MusicBrainz_API#Lookups)
 
 ### Lookup Function
 
@@ -127,7 +128,7 @@ Arguments:
 #### Lookup URLs
 
 There is special method to lookup URL entity / entities by one, or an array of URLs 
-([MusicBrainz documentation](https://musicbrainz.org/doc/MusicBrainz_API#url_(by_text))):
+([MusicBrainz API documentation: url (by text)](https://musicbrainz.org/doc/MusicBrainz_API#url_(by_text))):
 
 ```js
 const urls = await mbApi.lookupUrl(['https://open.spotify.com/track/2AMysGXOe0zzZJMtH3Nizb', 'https://open.spotify.com/track/78Teboqh9lPIxWlIW5RMQL']);
@@ -136,7 +137,7 @@ const urls = await mbApi.lookupUrl(['https://open.spotify.com/track/2AMysGXOe0zz
 or 
 
 ```js
-const url = await mbApi.lookupUrl('https://open.spotify.com/track/2AMysGXOe0zzZJMtH3Nizb']);
+const url = await mbApi.lookupUrl('https://open.spotify.com/track/2AMysGXOe0zzZJMtH3Nizb');
 ```
 
 Arguments:
@@ -145,11 +146,29 @@ Arguments:
 
 Note that the return type is different, depending on if a single URL or an array of URLs is provided.
 
+## Browse requests
+Browse requests are a direct lookup of all the entities directly linked to another entity ("directly linked" here meaning it does not include entities linked by a relationship).
+
+For example, browse _releases_:
+```js
+
+const artist_mbid = 'ab2528d9-719f-4261-8098-21849222a0f2';
+
+const releases = await mbApi.browse('release', {
+    track_artist:  artist_mbid,
+    limit: 0,
+    offset: 0,
+  }, ['url-rels', 'isrcs', 'recordings']);
+```
+
+For the optional include arguments (`string[]`), see [Include arguments](#include-arguments).
+
 ### Browse artist
 
 ```js
 const artists = await mbApi.browse('artist', query);
-````
+const artists = await mbApi.browse('artist', query, ['area', 'collection']);
+```
 
 | Query argument        | Query value        | 
 |-----------------------|--------------------|  
@@ -163,7 +182,8 @@ const artists = await mbApi.browse('artist', query);
 ### Browse collection
 ```js
 const collections = await mbApi.browse('collection', query);
-````
+const collections = await mbApi.browse('collection', query, ['area', 'artist']);
+```
 
 | Query argument        | Query value        | 
 |-----------------------|--------------------|  
@@ -181,7 +201,8 @@ const collections = await mbApi.browse('collection', query);
 ### Browse events
 ```js
 const events = await mbApi.browse('event', query);
-````
+const events = await mbApi.browse('instrument', query, ['area', 'artist']);
+```
 
 | Query argument        | Query value     | 
 |-----------------------|-----------------|  
@@ -192,8 +213,9 @@ const events = await mbApi.browse('event', query);
 
 ### Browse instruments
 ```js
-const instruments = await mbApi.browse('event', query);
-````
+const instruments = await mbApi.browse('instrument', query);
+const instruments = await mbApi.browse('instrument', query, ['collection']);
+```
 
 | Query argument        | Query value        | 
 |-----------------------|--------------------|  
@@ -202,7 +224,8 @@ const instruments = await mbApi.browse('event', query);
 ### Browse labels
 ```js
 const labels = await mbApi.browse('label', query);
-````
+const places = await mbApi.browse('place', query, ['area', 'collection']);
+```
 
 | Query argument     | Query value     | 
 |--------------------|-----------------|  
@@ -213,7 +236,8 @@ const labels = await mbApi.browse('label', query);
 ### Browse places
 ```js
 const places = await mbApi.browse('place', query);
-````
+const places = await mbApi.browse('place', query, ['area', 'collection']);
+```
 
 | Query argument     | Query value     | 
 |--------------------|-----------------|  
@@ -222,8 +246,8 @@ const places = await mbApi.browse('place', query);
 
 ### Browse recordings
 ```js
-const recordings = await mbApi.browse('recording', query);
-````
+const recordings = await mbApi.browse('recording', query, ['artist']);
+```
 
 | Query argument     | Query value     | 
 |--------------------|-----------------|  
@@ -235,7 +259,8 @@ const recordings = await mbApi.browse('recording', query);
 ### Browse releases
 ```js
 const releases = await mbApi.browse('release', query);
-````
+const releases = await mbApi.browse('release', query, ['artist', 'track']);
+```
 
 | Query argument        | Query value        | 
 |-----------------------|--------------------|  
@@ -252,7 +277,8 @@ const releases = await mbApi.browse('release', query);
 
 ### Browse release-groups
 ```js
-const releaseGroups = await mbApi.browse('release-group',query);
+const releaseGroups = await mbApi.browse('release-group', query);
+const releaseGroups = await mbApi.browse('release-group', query, ['artist', 'release']);
 ```
 
 | Query argument     | Query value     | 
@@ -264,7 +290,8 @@ const releaseGroups = await mbApi.browse('release-group',query);
 ### Browse series
 ```js
 const series = await mbApi.browse('series');
-````
+const series = await mbApi.browse('series', ['collection']);
+```
 
 | Query argument        | Query value        | 
 |-----------------------|--------------------|  
@@ -282,7 +309,8 @@ const series = await mbApi.browse('series');
 ### Browse works
 ```js
 const works = await mbApi.browse('work');
-````
+const series = await mbApi.browse('series', ['artist', 'collection']);
+```
 
 | Query argument     | Query value     | 
 |--------------------|-----------------|  
@@ -292,7 +320,8 @@ const works = await mbApi.browse('work');
 ### Browse urls
 ```js
 const urls = await mbApi.browse('url');
-````
+const series = await mbApi.browse('series', ['artist', 'collection', 'artist-rels']);
+```
 
 | Query argument     | Query value     | 
 |--------------------|-----------------|  
@@ -301,7 +330,7 @@ const urls = await mbApi.browse('url');
 
 ## Search (query)
 
-Implements [XML Web Service/Version 2/Search](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2/Search).
+Implements [MusicBrainz API: Search](https://wiki.musicbrainz.org/MusicBrainz_API/Search).
 
 There are different search fields depending on the entity.
 
@@ -334,21 +363,21 @@ const result = await mbApi.search('release-group', {query});
 
 ```js
  mbApi.search('area', 'Île-de-France');
-````
+```
 
 ##### Example: search release by barcode
 
 Search a release with the barcode 602537479870:
 ```js
  mbApi.search('release', {query: {barcode: 602537479870}});
-````
+```
 
 ##### Example: search by object
 
 Same as previous example, but automatically serialize parameters to search query
 ```js
  mbApi.search('release', 'barcode: 602537479870');
-````
+```
 
 ##### Example: search artist by artist name
 
@@ -443,9 +472,9 @@ As such, keep in mind requesting "artist-rels" for an artist, "release-rels" for
 In a release request, you might also be interested on relationships for the recordings linked to the release, or the release group linked to the release, or even for the works linked to those recordings that are linked to the release (for example, to find out who played guitar on a specific track, who wrote the lyrics for the song being performed, or whether the release group is part of a series). Similarly, for a recording request, you might want to get the relationships for any linked works. 
 There are three additional includes for this:
 
-- recording-level-rels
-- release-group-level-rels (for releases only)
-- work-level-rels
+- `recording-level-rels`
+- `release-group-level-rels` (for releases only)
+- `work-level-rels`
 
 # Submitting data via XML POST
 

package/lib/musicbrainz-api.d.ts

@@ -1,11 +1,11 @@
-export { XmlMetadata } from './xml/xml-metadata.js';
-export { XmlIsrc } from './xml/xml-isrc.js';
-export { XmlIsrcList } from './xml/xml-isrc-list.js';
-export { XmlRecording } from './xml/xml-recording.js';
 import type { XmlMetadata } from './xml/xml-metadata.js';
 import { RateLimitThreshold } from 'rate-limit-threshold';
 import * as mb from './musicbrainz.types.js';
 import { HttpClient, type MultiQueryFormData } from "./http-client.js";
+export { XmlMetadata } from './xml/xml-metadata.js';
+export { XmlIsrc } from './xml/xml-isrc.js';
+export { XmlIsrcList } from './xml/xml-isrc-list.js';
+export { XmlRecording } from './xml/xml-recording.js';
 export * from './musicbrainz.types.js';
 export type RelationsIncludes = 'area-rels' | 'artist-rels' | 'event-rels' | 'instrument-rels' | 'label-rels' | 'place-rels' | 'recording-rels' | 'release-rels' | 'release-group-rels' | 'series-rels' | 'url-rels' | 'work-rels';
 export type SubQueryIncludes = 
@@ -90,7 +90,7 @@ export declare class MusicBrainzApi {
      * 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:}
+     * @param inc Includes, which allows you to request more information to be included about the entity
      */
     lookup(entity: 'area', mbid: string, inc?: AreaIncludes[]): Promise<mb.IArea>;
     lookup(entity: 'artist', mbid: string, inc?: ArtistIncludes[]): Promise<mb.IArtist>;
@@ -115,20 +115,21 @@ export declare class MusicBrainzApi {
      * 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:}
+     * @param inc Includes, which allows you to request more information to be included about the entity
      */
-    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(entity: 'area', query?: mb.IBrowseAreasQuery, inc?: AreaIncludes[]): Promise<mb.IBrowseAreasResult>;
+    browse(entity: 'artist', query?: mb.IBrowseArtistsQuery, inc?: ArtistIncludes[]): Promise<mb.IBrowseArtistsResult>;
+    browse(entity: 'collection', query?: mb.IBrowseCollectionsQuery, inc?: CollectionIncludes[]): Promise<mb.IBrowseCollectionsResult>;
+    browse(entity: 'event', query?: mb.IBrowseEventsQuery, inc?: EventIncludes[]): Promise<mb.IBrowseEventsResult>;
+    browse(entity: 'label', query?: mb.IBrowseLabelsQuery, inc?: LabelIncludes[]): Promise<mb.IBrowseLabelsResult>;
+    browse(entity: 'instrument', query?: mb.IBrowseInstrumentsQuery, inc?: InstrumentIncludes[]): Promise<mb.IBrowseInstrumentsResult>;
+    browse(entity: 'place', query?: mb.IBrowsePlacesQuery, inc?: PlaceIncludes[]): Promise<mb.IBrowsePlacesResult>;
+    browse(entity: 'recording', query?: mb.IBrowseRecordingsQuery, inc?: RecordingIncludes[]): Promise<mb.IBrowseRecordingsResult>;
+    browse(entity: 'release', query?: mb.IBrowseReleasesQuery, inc?: ReleaseIncludes[]): Promise<mb.IBrowseReleasesResult>;
+    browse(entity: 'release-group', query?: mb.IBrowseReleaseGroupsQuery, inc?: ReleaseGroupIncludes[]): Promise<mb.IBrowseReleaseGroupsResult>;
+    browse(entity: 'series', query?: mb.IBrowseSeriesQuery, inc?: SeriesIncludes[]): Promise<mb.IBrowseSeriesResult>;
+    browse(entity: 'url', query?: mb.IBrowseUrlsQuery, inc?: UrlIncludes[]): Promise<mb.IUrl>;
+    browse(entity: 'work', query?: mb.IBrowseWorksQuery, inc?: WorkIncludes[]): Promise<mb.IBrowseWorksResult>;
     /**
      * Search an entity using a search query
      * @param query e.g.: '" artist: Madonna, track: Like a virgin"' or object with search terms: {artist: Madonna}

package/lib/musicbrainz-api.js

@@ -1,13 +1,13 @@
 import { StatusCodes as HttpStatus } from 'http-status-codes';
 import Debug from 'debug';
-export { XmlMetadata } from './xml/xml-metadata.js';
-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 { RateLimitThreshold } from 'rate-limit-threshold';
 import * as mb from './musicbrainz.types.js';
 import { HttpClient } from "./http-client.js";
+export { XmlMetadata } from './xml/xml-metadata.js';
+export { XmlIsrc } from './xml/xml-isrc.js';
+export { XmlIsrcList } from './xml/xml-isrc-list.js';
+export { XmlRecording } from './xml/xml-recording.js';
 export * from './musicbrainz.types.js';
 const debug = Debug('musicbrainz-api');
 export class MusicBrainzApi {
@@ -60,16 +60,20 @@ export class MusicBrainzApi {
     async lookupUrl(url, inc = []) {
         const result = await this.restGet('/url', { resource: url, inc: inc.join(' ') });
         if (Array.isArray(url) && url.length <= 1) {
-            const searchResult = {
+            return {
                 'url-count': 1,
                 'url-offset': 0,
                 urls: [result],
             };
-            return searchResult;
         }
         return result;
     }
-    browse(entity, query) {
+    browse(entity, query, inc) {
+        query = query ? query : {};
+        if (inc) {
+            // Serialize include parameter
+            query.inc = inc.join(' ');
+        }
         return this.restGet(`/${entity}`, query);
     }
     search(entity, query) {

package/lib/musicbrainz.types.d.ts

@@ -438,131 +438,147 @@ export interface ILinkedEntitiesWork {
 export interface ILinkedEntitiesUrl {
     resource?: string;
 }
+export type OneOf<T> = {
+    [K in keyof T]: {
+        [P in K]: T[K];
+    } & Partial<Record<Exclude<keyof T, K>, never>>;
+}[keyof T];
 /**
- * Browse artist query <entity>: <MBID>
- * https://wiki.musicbrainz.org/MusicBrainz_API#Linked_entities
+ * List of entity names allowed for browsing releases by a single MBID.
+ * Used as a key set for constructing exclusive query types.
  */
-export interface IBrowseAreasQuery extends IPagination {
-    collection?: string;
-}
+interface BrowseReleasesEntityParams {
+    area: string;
+    artist: string;
+    editor: string;
+    event: string;
+    label: string;
+    place: string;
+    recording: string;
+    release: string;
+    'release-group': string;
+    track_artist: string;
+    work: string;
+}
+export type IBrowseReleasesQuery = IPagination & OneOf<BrowseReleasesEntityParams>;
 /**
- * Browse artist query <entity>: <MBID>
- * https://wiki.musicbrainz.org/MusicBrainz_API#Linked_entities
+ * List of entity names allowed for browsing artists by a single MBID.
+ * Used as a key set for constructing exclusive query types.
  */
-export interface IBrowseArtistsQuery extends IPagination {
-    area?: string;
-    collection?: string;
-    recording?: string;
-    release?: string;
-    'release-group'?: string;
-    work?: string;
-}
+interface BrowseArtistsEntityParams {
+    area: string;
+    collection: string;
+    recording: string;
+    release: string;
+    'release-group': string;
+    work: string;
+}
+export type IBrowseArtistsQuery = IPagination & OneOf<BrowseArtistsEntityParams>;
 /**
- * Browse collection query <entity>: <MBID>
- * https://wiki.musicbrainz.org/MusicBrainz_API#Linked_entities
+ * List of entity names allowed for browsing collections by a single MBID.
+ * Used as a key set for constructing exclusive query types.
  */
-export interface IBrowseCollectionsQuery extends IPagination {
-    area?: string;
-    artist?: string;
-    editor?: string;
-    event?: string;
-    label?: string;
-    place?: string;
-    recording?: string;
-    release?: string;
-    'release-group'?: string;
-    work?: string;
+interface BrowseCollectionsEntityParams {
+    area: string;
+    artist: string;
+    editor: string;
+    event: string;
+    label: string;
+    place: string;
+    recording: string;
+    release: string;
+    'release-group': string;
+    work: string;
+}
+export type IBrowseCollectionsQuery = IPagination & OneOf<BrowseCollectionsEntityParams>;
+/**
+ * List of entity names allowed for browsing events by a single MBID.
+ * Used as a key set for constructing exclusive query types.
+ */
+interface BrowseEventsEntityParams {
+    area: string;
+    artist: string;
+    collection: string;
+    place: string;
 }
+export type IBrowseEventsQuery = IPagination & OneOf<BrowseEventsEntityParams>;
 /**
- * Browse events query <entity>: <MBID>
- * https://wiki.musicbrainz.org/MusicBrainz_API#Linked_entities
+ * List of entity names allowed for browsing labels by a single MBID.
+ * Used as a key set for constructing exclusive query types.
  */
-export interface IBrowseEventsQuery extends IPagination {
-    area?: string;
-    artist?: string;
-    collection?: string;
-    place?: string;
+interface BrowseLabelsEntityParams {
+    area: string;
+    collection: string;
+    release: string;
 }
+export type IBrowseLabelsQuery = IPagination & OneOf<BrowseLabelsEntityParams>;
 /**
- * Browse instruments query <entity>: <MBID>
- * https://wiki.musicbrainz.org/MusicBrainz_API#Linked_entities
+ * List of entity names allowed for browsing places by a single MBID.
+ * Used as a key set for constructing exclusive query types.
  */
-export interface IBrowseInstrumentsQuery extends IPagination {
-    collection?: string;
+interface BrowsePlacesEntityParams {
+    area: string;
+    collection: string;
 }
+export type IBrowsePlacesQuery = IPagination & OneOf<BrowsePlacesEntityParams>;
 /**
- * Browse labels query <entity>: <MBID>
- * https://wiki.musicbrainz.org/MusicBrainz_API#Linked_entities
+ * List of entity names allowed for browsing recordings by a single MBID.
+ * Used as a key set for constructing exclusive query types.
  */
-export interface IBrowseLabelsQuery extends IPagination {
-    area?: string;
-    collection?: string;
-    release?: string;
+interface BrowseRecordingsEntityParams {
+    artist: string;
+    collection: string;
+    release: string;
+    work: string;
 }
+export type IBrowseRecordingsQuery = IPagination & OneOf<BrowseRecordingsEntityParams>;
 /**
- * Browse places query <entity>: <MBID>
- * https://wiki.musicbrainz.org/MusicBrainz_API#Linked_entities
+ * List of entity names allowed for browsing release-groups by a single MBID.
+ * Used as a key set for constructing exclusive query types.
  */
-export interface IBrowsePlacesQuery extends IPagination {
-    area?: string;
-    collection?: string;
+interface BrowseReleaseGroupsEntityParams {
+    artist: string;
+    collection: string;
+    release: string;
 }
+export type IBrowseReleaseGroupsQuery = IPagination & OneOf<BrowseReleaseGroupsEntityParams>;
 /**
- * Browse recordings query <entity>: <MBID>
- * https://wiki.musicbrainz.org/MusicBrainz_API#Linked_entities
+ * List of entity names allowed for browsing works by a single MBID.
+ * Used as a key set for constructing exclusive query types.
  */
-export interface IBrowseRecordingsQuery extends IPagination {
-    artist?: string;
-    collection?: string;
-    release?: string;
-    work?: string;
+interface BrowseWorksEntityParams {
+    artist: string;
+    collection: string;
 }
+export type IBrowseWorksQuery = IPagination & OneOf<BrowseWorksEntityParams>;
 /**
- * Browse releases query <entity>: <MBID>
+ * Query for browsing areas by collection MBID.
  * https://wiki.musicbrainz.org/MusicBrainz_API#Linked_entities
  */
-export interface IBrowseReleasesQuery extends IPagination {
-    area?: string;
-    artist?: string;
-    editor?: string;
-    event?: string;
-    label?: string;
-    place?: string;
-    recording?: string;
-    release?: string;
-    'release-group'?: string;
-    work?: string;
+export interface IBrowseAreasQuery extends IPagination {
+    collection?: string;
 }
 /**
- * Browse release-groups query <entity>: <MBID>
+ * Query for browsing instruments by collection MBID.
+ * https://wiki.musicbrainz.org/MusicBrainz_API#Linked_entities
  */
-export interface IBrowseReleaseGroupsQuery extends IPagination {
-    artist?: string;
+export interface IBrowseInstrumentsQuery extends IPagination {
     collection?: string;
-    release?: string;
 }
 /**
- * Browse release query <entity>: <MBID>
+ * Query for browsing series by collection MBID.
  * https://wiki.musicbrainz.org/MusicBrainz_API#Linked_entities
  */
 export interface IBrowseSeriesQuery extends IPagination {
     collection?: string;
 }
 /**
- * Browse urls query <entity>: <MBID>
+ * Query for browsing URLs by resource URI.
  * https://wiki.musicbrainz.org/MusicBrainz_API#Linked_entities
  */
 export interface IBrowseUrlsQuery extends IPagination {
     resource?: string;
 }
-/**
- * Browse works query <entity>: <MBID>
- * https://wiki.musicbrainz.org/MusicBrainz_API#Linked_entities
- */
-export interface IBrowseWorksQuery extends IPagination {
-    artist?: string;
-    collection?: string;
-}
 export interface IBrowseAreasResult {
     area: IArea;
     'area-count': number;
@@ -628,3 +644,4 @@ export interface IUrlLookupResult {
     'url-count': number;
     urls: IUrl[];
 }
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "musicbrainz-api",
-  "version": "0.23.1",
+  "version": "0.24.0",
   "description": "MusicBrainz API client for reading and submitting metadata",
   "exports": {
     "node": {
@@ -77,7 +77,7 @@
     "mocha": "^11.0.1",
     "remark-cli": "^12.0.0",
     "remark-preset-lint-recommended": "^7.0.0",
-    "sinon": "^19.0.2",
+    "sinon": "^20.0.0",
     "source-map-support": "^0.5.21",
     "ts-node": "^10.9.2",
     "typescript": "^5.5.4"