musicbrainz-api 0.25.1 → 0.27.0

package/README.md

@@ -100,6 +100,10 @@ const config = {
 
     // Optional: Disable rate limiting (default: false)
     disableRateLimiting: false,
+
+    // Optional: Set max number of request with X seconds
+    //           (default: 15 requests every 18 seconds)
+    rateLimit: [15, 18]
 };
 
 const mbApi = new MusicBrainzApi(config);

package/lib/http-client.js

@@ -1,5 +1,11 @@
 import Debug from "debug";
 const debug = Debug('musicbrainz-api-node');
+function isConnectionReset(err) {
+    // Undici puts the OS error on .cause, with .code like 'ECONNRESET'
+    const code = err?.cause?.code ?? err?.code;
+    // Add other transient codes you consider safe to retry:
+    return typeof code === "string" && code === 'ECONNRESET';
+}
 export class HttpClient {
     constructor(httpOptions) {
         this.httpOptions = httpOptions;
@@ -31,13 +37,24 @@ export class HttpClient {
             headers.set('Cookie', cookies);
         }
         while (retryLimit > 0) {
-            const response = await fetch(url, {
-                method,
-                ...options,
-                headers,
-                body: options.body,
-                redirect: options.followRedirects === false ? 'manual' : 'follow'
-            });
+            let response;
+            try {
+                response = await fetch(url, {
+                    method,
+                    ...options,
+                    headers,
+                    body: options.body,
+                    redirect: options.followRedirects === false ? 'manual' : 'follow'
+                });
+            }
+            catch (err) {
+                if (isConnectionReset(err)) {
+                    // Retry on TCP connection resets
+                    await this._delay(retryTimeout); // wait 200ms before retry
+                    continue;
+                }
+                throw err;
+            }
             if (response.status === 429 || response.status === 503) {
                 debug(`Received status=${response.status}, assume reached rate limit, retry in ${retryTimeout} ms`);
                 retryLimit--;

package/lib/musicbrainz-api.d.ts

@@ -39,7 +39,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 ReleaseIncludes = MiscIncludes | SubQueryIncludes | RelationsIncludes | 'artists' | 'collections' | 'labels' | 'recordings' | 'release-groups';
+export type ReleaseIncludes = MiscIncludes | SubQueryIncludes | RelationsIncludes | 'artists' | 'collections' | 'labels' | 'recordings' | 'release-groups' | 'recording-level-rels';
 export type ReleaseGroupIncludes = MiscIncludes | SubQueryIncludes | RelationsIncludes | 'artists' | 'releases';
 export type SeriesIncludes = MiscIncludes | RelationsIncludes;
 export type WorkIncludes = MiscIncludes | RelationsIncludes;
@@ -64,6 +64,17 @@ export interface IMusicBrainzConfig {
      */
     appContactInfo?: string;
     disableRateLimiting?: boolean;
+    /**
+     * Optional rate limit configuration.
+     *
+     * [maxRequests, periodSeconds]
+     *
+     * maxRequests     The maximum number of allowed requests within the period
+     * periodSeconds   The time window in seconds during which requests are counted
+     *
+     * Default is [15, 18], which allows up to 15 requests every 18 seconds
+     */
+    rateLimit?: [number, number];
 }
 interface IInternalConfig extends IMusicBrainzConfig {
     baseUrl: string;

package/lib/musicbrainz-api.js

@@ -36,7 +36,8 @@ export class MusicBrainzApi {
             ..._config
         };
         this.httpClient = this.initHttpClient();
-        this.rateLimiter = new RateLimitThreshold(15, 18);
+        const limits = this.config.rateLimit ?? [15, 18];
+        this.rateLimiter = new RateLimitThreshold(limits[0], limits[1]);
     }
     initHttpClient() {
         return new HttpClient({
@@ -74,6 +75,12 @@ export class MusicBrainzApi {
             // Serialize include parameter
             query.inc = inc.join(' ');
         }
+        for (const pipedFilter of ['type', 'status']) {
+            if (query[pipedFilter]) {
+                // Serialize type parameter
+                query[pipedFilter] = query[pipedFilter].join('|');
+            }
+        }
         return this.restGet(`/${entity}`, query);
     }
     search(entity, query) {

package/lib/musicbrainz.types.d.ts

@@ -46,7 +46,7 @@ export interface IMatch {
     score: number;
 }
 export type Gender = 'male' | 'female' | 'other' | 'not applicable';
-export interface IArtist extends ITypedEntity {
+export interface IArtist extends ITypedEntity, IMayHaveRelations {
     name: string;
     disambiguation: string;
     'sort-name': string;
@@ -60,7 +60,6 @@ export interface IArtist extends ITypedEntity {
     area?: IArea;
     begin_area?: IArea;
     end_area?: IArea;
-    relations?: IRelation[];
     /**
      * Only defined if 'releases' are includes
      */
@@ -104,7 +103,7 @@ export interface IInstrument extends ITypedEntity {
 export type ReleaseQuality = 'normal' | 'high';
 export type ReleaseStatus = 'Official' | 'Promotion' | 'Bootleg' | 'Pseudo-release' | 'Withdrawn' | 'Expunged' | 'Cancelled';
 export type ReleasePackaging = 'Book' | 'Box' | 'Cardboard/Paper Sleeve' | 'Cassette Case' | 'Clamshell Case' | 'Digibook' | 'Digifile' | 'Digipak' | 'Discbox Slider' | 'Fatbox' | 'Gatefold Cover' | 'Jewel case' | 'Keep Case' | 'Longbox' | 'Metal Tin' | 'Plastic sleeve' | 'Slidepack' | 'Slim Jewel Case' | 'Snap Case' | 'SnapPack' | 'Super Jewel Box' | 'Other' | 'None';
-export interface IRelease extends IEntity {
+export interface IRelease extends IEntity, IMayHaveRelations {
     title: string;
     'text-representation': {
         'language': string;
@@ -123,7 +122,6 @@ export interface IRelease extends IEntity {
     country: string;
     quality: ReleaseQuality;
     barcode: string;
-    relations?: IRelation[];
     'artist-credit'?: IArtistCredit[];
     'release-group'?: IReleaseGroup;
     collections?: ICollection[];
@@ -135,14 +133,13 @@ export interface IReleaseEvent {
     date?: string;
 }
 export type MediaFormatType = 'Digital Media';
-export interface IRecording extends IEntity {
+export interface IRecording extends IEntity, IMayHaveRelations {
     video: boolean;
     length: number;
     title: string;
     disambiguation: string;
     isrcs?: string[];
     releases?: IRelease[];
-    relations?: IRelation[];
     'artist-credit'?: IArtistCredit[];
     aliases?: IAlias[];
     'first-release-date': string;
@@ -273,7 +270,7 @@ export interface IRelation {
     url?: IUrl;
     release?: IRelease;
 }
-export interface IRelationList {
+export interface IMayHaveRelations {
     relations: IRelation[];
 }
 export interface IWork extends IEntity {
@@ -301,10 +298,9 @@ export interface ISeries extends ITypedEntity {
 export interface ITag {
     name: string;
 }
-export interface IUrl extends IEntity {
+export interface IUrl extends IEntity, IMayHaveRelations {
     id: string;
     resource: string;
-    relations?: IRelationList[];
 }
 export interface IExernalIds {
     [type: string]: string;
@@ -321,6 +317,14 @@ export type OtherEntityTypes = 'annotation' | 'cdstub' | 'tag';
  */
 export type EntityType = 'annotation' | 'area' | 'artist' | 'collection' | 'event' | 'instrument' | 'label' | 'place' | 'recording' | 'release' | 'release-group' | 'series' | 'work' | 'url';
 export type Relationships = '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';
+/**
+ * Ref: https://musicbrainz.org/doc/MusicBrainz_API#Release_.28Group.29_Type_and_Status
+ */
+export type ReleaseStatusQuery = 'official' | 'promotion' | 'bootleg' | 'pseudo-release' | 'withdrawn' | 'cancelled';
+/**
+ * Ref: https://musicbrainz.org/doc/MusicBrainz_API#Release_.28Group.29_Type_and_Status
+ */
+export type ReleaseTypeQuery = 'album' | 'single' | 'ep' | 'broadcast' | 'other' | 'audiobook' | 'compilation' | 'demo' | 'dj-mix' | 'field recording' | 'interview' | 'live' | 'mixtape/street' | 'remix' | 'soundtrack' | 'spokenword';
 export declare enum LinkType {
     license = 302,
     production = 256,
@@ -346,6 +350,13 @@ export interface IPagination {
      */
     limit?: number;
 }
+/**
+ * Release and release-group types
+ */
+export interface IReleaseTypeAndStatus {
+    status?: ReleaseStatusQuery[];
+    type?: ReleaseTypeQuery[];
+}
 /**
  * https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2/Search#Artist
  */
@@ -510,7 +521,7 @@ interface BrowseReleasesEntityParams {
     track_artist: string;
     work: string;
 }
-export type IBrowseReleasesQuery = IPagination & OneOf<BrowseReleasesEntityParams>;
+export type IBrowseReleasesQuery = IPagination & IReleaseTypeAndStatus & OneOf<BrowseReleasesEntityParams>;
 /**
  * List of entity names allowed for browsing artists by a single MBID.
  * Used as a key set for constructing exclusive query types.
@@ -591,7 +602,7 @@ interface BrowseReleaseGroupsEntityParams {
     collection: string;
     release: string;
 }
-export type IBrowseReleaseGroupsQuery = IPagination & OneOf<BrowseReleaseGroupsEntityParams>;
+export type IBrowseReleaseGroupsQuery = IPagination & IReleaseTypeAndStatus & OneOf<BrowseReleaseGroupsEntityParams>;
 /**
  * List of entity names allowed for browsing works by a single MBID.
  * Used as a key set for constructing exclusive query types.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "musicbrainz-api",
-  "version": "0.25.1",
+  "version": "0.27.0",
   "description": "MusicBrainz API client for reading and submitting metadata",
   "exports": {
     "node": {
@@ -58,22 +58,22 @@
     "rate-limit-threshold": "^0.2.0",
     "spark-md5": "^3.0.2",
     "tough-cookie": "^5.0.0",
-    "uuid": "^11.0.3"
+    "uuid": "^13.0.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.1.2",
+    "@biomejs/biome": "2.3.8",
     "@types/chai": "^5.0.0",
     "@types/jsontoxml": "^1.0.5",
     "@types/mocha": "^10.0.4",
     "@types/node": "^24.0.3",
-    "@types/sinon": "^17.0.3",
+    "@types/sinon": "^21.0.0",
     "@types/source-map-support": "^0",
     "@types/spark-md5": "^3",
     "@types/tough-cookie": "^4.0.5",
-    "@types/uuid": "^10.0.0",
+    "@types/uuid": "^11.0.0",
     "c8": "^10.1.2",
-    "chai": "^5.1.1",
-    "del-cli": "^6.0.0",
+    "chai": "^6.2.0",
+    "del-cli": "^7.0.0",
     "mocha": "^11.0.1",
     "remark-cli": "^12.0.0",
     "remark-preset-lint-recommended": "^7.0.0",
@@ -89,7 +89,7 @@
     "compile": "yarn run compile-lib && yarn run compile-test",
     "lint:md": "remark -u preset-lint-recommended .",
     "lint:ts": "biome check",
-    "lint:fix": "biome check --fix",
+    "lint:fix": "biome check --write",
     "lint": "yarn run lint:md && yarn run lint:ts",
     "test": "mocha",
     "build": "yarn run clean && yarn run compile",