tmdb-kit 1.1.0 → 1.2.0

package/dist/index.js

@@ -13,6 +13,15 @@ class TMDBRequestError extends TMDBError {
   }
 }
 
+class TMDBTimeoutError extends TMDBError {
+  timeoutMs;
+  constructor(timeoutMs, message = `TMDB request timed out after ${timeoutMs}ms`) {
+    super(message);
+    this.name = "TMDBTimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+}
+
 class TMDBResponseError extends TMDBError {
   body;
   headers;
@@ -135,6 +144,19 @@ function toId(value, name) {
   }
   return String(value);
 }
+function toSeasonNumber(value) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new TMDBRequestError("seasonNumber must be a non-negative integer");
+  }
+  return String(value);
+}
+function toGroupId(value) {
+  const groupId = value.trim();
+  if (!/^[A-Za-z0-9_-]+$/.test(groupId)) {
+    throw new TMDBRequestError("groupId must be a non-empty identifier");
+  }
+  return groupId;
+}
 function toSearchQuery(value) {
   const query = value.trim();
   if (query.length === 0) {
@@ -268,23 +290,25 @@ class ConfigurationResource {
   constructor(transport) {
     this.#transport = transport;
   }
-  details() {
-    return this.#transport.get("/configuration");
+  details(options = {}) {
+    return this.#transport.get("/configuration", { signal: options.signal });
   }
-  countries() {
-    return this.#transport.get("/configuration/countries");
+  countries(options = {}) {
+    return this.#transport.get("/configuration/countries", { signal: options.signal });
   }
-  jobs() {
-    return this.#transport.get("/configuration/jobs");
+  jobs(options = {}) {
+    return this.#transport.get("/configuration/jobs", { signal: options.signal });
   }
-  languages() {
-    return this.#transport.get("/configuration/languages");
+  languages(options = {}) {
+    return this.#transport.get("/configuration/languages", { signal: options.signal });
   }
-  primaryTranslations() {
-    return this.#transport.get("/configuration/primary_translations");
+  primaryTranslations(options = {}) {
+    return this.#transport.get("/configuration/primary_translations", {
+      signal: options.signal
+    });
   }
-  timezones() {
-    return this.#transport.get("/configuration/timezones");
+  timezones(options = {}) {
+    return this.#transport.get("/configuration/timezones", { signal: options.signal });
   }
 }
 
@@ -298,14 +322,16 @@ class GenresResource {
     return this.#transport.get("/genre/movie/list", {
       query: withLanguage(this.#transport.defaults, {
         language: options.language
-      })
+      }),
+      signal: options.signal
     });
   }
   tv(options = {}) {
     return this.#transport.get("/genre/tv/list", {
       query: withLanguage(this.#transport.defaults, {
         language: options.language
-      })
+      }),
+      signal: options.signal
     });
   }
 }
@@ -334,22 +360,26 @@ class MoviesResource {
   }
   popular(options = {}) {
     return this.#transport.get("/movie/popular", {
-      query: movieListQuery(this.#transport, options)
+      query: movieListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   topRated(options = {}) {
     return this.#transport.get("/movie/top_rated", {
-      query: movieListQuery(this.#transport, options)
+      query: movieListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   nowPlaying(options = {}) {
     return this.#transport.get("/movie/now_playing", {
-      query: movieListQuery(this.#transport, options)
+      query: movieListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   upcoming(options = {}) {
     return this.#transport.get("/movie/upcoming", {
-      query: movieListQuery(this.#transport, options)
+      query: movieListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   details(movieId, options = {}) {
@@ -357,14 +387,16 @@ class MoviesResource {
       query: withLanguage(this.#transport.defaults, {
         append_to_response: toCommaList(options.appendToResponse),
         language: options.language
-      })
+      }),
+      signal: options.signal
     });
   }
   credits(movieId, options = {}) {
     return this.#transport.get(`/movie/${toId(movieId, "movieId")}/credits`, {
       query: withLanguage(this.#transport.defaults, {
         language: options.language
-      })
+      }),
+      signal: options.signal
     });
   }
   images(movieId, options = {}) {
@@ -372,24 +404,28 @@ class MoviesResource {
       query: withLanguage(this.#transport.defaults, {
         include_image_language: toCommaList(options.includeImageLanguage),
         language: options.language
-      })
+      }),
+      signal: options.signal
     });
   }
   recommendations(movieId, options = {}) {
     return this.#transport.get(`/movie/${toId(movieId, "movieId")}/recommendations`, {
-      query: movieListQuery(this.#transport, options)
+      query: movieListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   similar(movieId, options = {}) {
     return this.#transport.get(`/movie/${toId(movieId, "movieId")}/similar`, {
-      query: movieListQuery(this.#transport, options)
+      query: movieListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   videos(movieId, options = {}) {
     return this.#transport.get(`/movie/${toId(movieId, "movieId")}/videos`, {
       query: withLanguage(this.#transport.defaults, {
         language: options.language
-      })
+      }),
+      signal: options.signal
     });
   }
 }
@@ -409,21 +445,24 @@ class PeopleResource {
   }
   popular(options = {}) {
     return this.#transport.get("/person/popular", {
-      query: peopleListQuery(this.#transport, options)
+      query: peopleListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   details(personId, options = {}) {
     return this.#transport.get(`/person/${toId(personId, "personId")}`, {
       query: withLanguage(this.#transport.defaults, {
         language: options.language
-      })
+      }),
+      signal: options.signal
     });
   }
   combinedCredits(personId, options = {}) {
     return this.#transport.get(`/person/${toId(personId, "personId")}/combined_credits`, {
       query: withLanguage(this.#transport.defaults, {
         language: options.language
-      })
+      }),
+      signal: options.signal
     });
   }
 }
@@ -442,22 +481,26 @@ class SearchResource {
   }
   movies(query, options = {}) {
     return this.#transport.get("/search/movie", {
-      query: movieSearchQuery(this.#transport, query, options)
+      query: movieSearchQuery(this.#transport, query, options),
+      signal: options.signal
     });
   }
   tv(query, options = {}) {
     return this.#transport.get("/search/tv", {
-      query: tvSearchQuery(this.#transport, query, options)
+      query: tvSearchQuery(this.#transport, query, options),
+      signal: options.signal
     });
   }
   people(query, options = {}) {
     return this.#transport.get("/search/person", {
-      query: commonSearchQuery(this.#transport, query, options)
+      query: commonSearchQuery(this.#transport, query, options),
+      signal: options.signal
     });
   }
   async multi(query, options = {}) {
     const response = await this.#transport.get("/search/multi", {
-      query: commonSearchQuery(this.#transport, query, options)
+      query: commonSearchQuery(this.#transport, query, options),
+      signal: options.signal
     });
     const excluded = options.exclude;
     if (excluded === undefined || excluded.length === 0) {
@@ -511,7 +554,8 @@ class TrendingResource {
       query: withLanguage(this.#transport.defaults, {
         language: options.language,
         page: options.page
-      })
+      }),
+      signal: options.signal
     });
   }
   movies(timeWindow = "day", options = {}) {
@@ -519,7 +563,8 @@ class TrendingResource {
       query: withLanguage(this.#transport.defaults, {
         language: options.language,
         page: options.page
-      })
+      }),
+      signal: options.signal
     });
   }
   tv(timeWindow = "day", options = {}) {
@@ -527,7 +572,8 @@ class TrendingResource {
       query: withLanguage(this.#transport.defaults, {
         language: options.language,
         page: options.page
-      })
+      }),
+      signal: options.signal
     });
   }
   people(timeWindow = "day", options = {}) {
@@ -535,7 +581,8 @@ class TrendingResource {
       query: withLanguage(this.#transport.defaults, {
         language: options.language,
         page: options.page
-      })
+      }),
+      signal: options.signal
     });
   }
 }
@@ -548,22 +595,26 @@ class TVResource {
   }
   popular(options = {}) {
     return this.#transport.get("/tv/popular", {
-      query: tvListQuery(this.#transport, options)
+      query: tvListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   topRated(options = {}) {
     return this.#transport.get("/tv/top_rated", {
-      query: tvListQuery(this.#transport, options)
+      query: tvListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   airingToday(options = {}) {
     return this.#transport.get("/tv/airing_today", {
-      query: tvListQuery(this.#transport, options)
+      query: tvListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   onTheAir(options = {}) {
     return this.#transport.get("/tv/on_the_air", {
-      query: tvListQuery(this.#transport, options)
+      query: tvListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   details(seriesId, options = {}) {
@@ -571,14 +622,16 @@ class TVResource {
       query: withLanguage(this.#transport.defaults, {
         append_to_response: toCommaList(options.appendToResponse),
         language: options.language
-      })
+      }),
+      signal: options.signal
     });
   }
   credits(seriesId, options = {}) {
     return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/credits`, {
       query: withLanguage(this.#transport.defaults, {
         language: options.language
-      })
+      }),
+      signal: options.signal
     });
   }
   images(seriesId, options = {}) {
@@ -586,32 +639,103 @@ class TVResource {
       query: withLanguage(this.#transport.defaults, {
         include_image_language: toCommaList(options.includeImageLanguage),
         language: options.language
-      })
+      }),
+      signal: options.signal
     });
   }
   recommendations(seriesId, options = {}) {
     return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/recommendations`, {
-      query: tvListQuery(this.#transport, options)
+      query: tvListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   similar(seriesId, options = {}) {
     return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/similar`, {
-      query: tvListQuery(this.#transport, options)
+      query: tvListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   videos(seriesId, options = {}) {
     return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/videos`, {
       query: withLanguage(this.#transport.defaults, {
         language: options.language
-      })
+      }),
+      signal: options.signal
     });
   }
   seasonDetails(seriesId, seasonNumber, options = {}) {
-    return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/season/${toId(seasonNumber, "seasonNumber")}`, {
+    return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/season/${toSeasonNumber(seasonNumber)}`, {
       query: withLanguage(this.#transport.defaults, {
         append_to_response: toCommaList(options.appendToResponse),
         language: options.language
-      })
+      }),
+      signal: options.signal
+    });
+  }
+  seasonCredits(seriesId, seasonNumber, options = {}) {
+    return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/season/${toSeasonNumber(seasonNumber)}/credits`, {
+      query: withLanguage(this.#transport.defaults, {
+        language: options.language
+      }),
+      signal: options.signal
+    });
+  }
+  seasonAggregateCredits(seriesId, seasonNumber, options = {}) {
+    return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/season/${toSeasonNumber(seasonNumber)}/aggregate_credits`, {
+      query: withLanguage(this.#transport.defaults, {
+        language: options.language
+      }),
+      signal: options.signal
+    });
+  }
+  seasonImages(seriesId, seasonNumber, options = {}) {
+    return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/season/${toSeasonNumber(seasonNumber)}/images`, {
+      query: withLanguage(this.#transport.defaults, {
+        include_image_language: toCommaList(options.includeImageLanguage),
+        language: options.language
+      }),
+      signal: options.signal
+    });
+  }
+  seasonVideos(seriesId, seasonNumber, options = {}) {
+    return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/season/${toSeasonNumber(seasonNumber)}/videos`, {
+      query: withLanguage(this.#transport.defaults, {
+        language: options.language
+      }),
+      signal: options.signal
+    });
+  }
+  episodeDetails(seriesId, seasonNumber, episodeNumber, options = {}) {
+    return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/season/${toSeasonNumber(seasonNumber)}/episode/${toId(episodeNumber, "episodeNumber")}`, {
+      query: withLanguage(this.#transport.defaults, {
+        append_to_response: toCommaList(options.appendToResponse),
+        language: options.language
+      }),
+      signal: options.signal
+    });
+  }
+  aggregateCredits(seriesId, options = {}) {
+    return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/aggregate_credits`, {
+      query: withLanguage(this.#transport.defaults, {
+        language: options.language
+      }),
+      signal: options.signal
+    });
+  }
+  episodeGroups(seriesId, options = {}) {
+    return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/episode_groups`, {
+      query: withLanguage(this.#transport.defaults, {
+        language: options.language
+      }),
+      signal: options.signal
+    });
+  }
+  episodeGroup(groupId, options = {}) {
+    return this.#transport.get(`/tv/episode_group/${toGroupId(groupId)}`, {
+      query: withLanguage(this.#transport.defaults, {
+        language: options.language
+      }),
+      signal: options.signal
     });
   }
 }
@@ -634,13 +758,17 @@ class TMDBClient {
   tv;
   #transport;
   constructor(options) {
-    const { transport, images, ...httpOptions } = options;
-    const fallbackTransform = images?.transform;
-    const builtInClient = transport === undefined ? new TMDBHttpClient({ ...httpOptions, images }) : undefined;
-    this.#transport = builtInClient ?? transport;
+    let imageTransform = options.images?.transform;
+    if (options.transport === undefined) {
+      const builtInClient = new TMDBHttpClient(options);
+      this.#transport = builtInClient;
+      imageTransform = builtInClient.imageTransform;
+    } else {
+      this.#transport = options.transport;
+    }
     this.configuration = new ConfigurationResource(this.#transport);
     this.genres = new GenresResource(this.#transport);
-    this.images = new ImagesHelper(this.#transport, builtInClient ? builtInClient.imageTransform : fallbackTransform);
+    this.images = new ImagesHelper(this.#transport, imageTransform);
     this.movies = new MoviesResource(this.#transport);
     this.people = new PeopleResource(this.#transport);
     this.search = new SearchResource(this.#transport);
@@ -654,6 +782,238 @@ class TMDBClient {
 function createTMDB(options) {
   return new TMDBClient(options);
 }
+// src/helpers/cache.ts
+function withMemoryCache(transport, options = {}) {
+  const ttlMs = options.ttlMs ?? 5 * 60000;
+  const maxEntries = options.maxEntries ?? 100;
+  if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+    throw new RangeError("ttlMs must be a positive number");
+  }
+  if (!Number.isInteger(maxEntries) || maxEntries < 1) {
+    throw new RangeError("maxEntries must be a positive integer");
+  }
+  const entries = new Map;
+  return {
+    ...transport,
+    async get(path, requestOptions = {}) {
+      const key = cacheKey(path, requestOptions);
+      const cached = entries.get(key);
+      if (cached !== undefined) {
+        if (cached.expiresAt > Date.now()) {
+          entries.delete(key);
+          entries.set(key, cached);
+          return cached.value;
+        }
+        entries.delete(key);
+      }
+      const value = await transport.get(path, requestOptions);
+      entries.set(key, { expiresAt: Date.now() + ttlMs, value });
+      evictOverflow(entries, maxEntries);
+      return value;
+    },
+    clear() {
+      entries.clear();
+    }
+  };
+}
+function cacheKey(path, options) {
+  return `${path}?${serializeQuery(options.query)}|${serializeHeaders(options.headers)}`;
+}
+function serializeQuery(query) {
+  if (query === undefined) {
+    return "";
+  }
+  return Object.entries(query).filter(([, value]) => value !== undefined && value !== null).sort(([left], [right]) => left.localeCompare(right)).map(([key, value]) => `${key}=${Array.isArray(value) ? value.map(String).join(",") : String(value)}`).join("&");
+}
+function serializeHeaders(headers) {
+  if (headers === undefined) {
+    return "";
+  }
+  return [...new Headers(headers)].sort(([left], [right]) => left.localeCompare(right)).map(([key, value]) => `${key}:${value}`).join("|");
+}
+function evictOverflow(entries, maxEntries) {
+  while (entries.size > maxEntries) {
+    entries.delete(entries.keys().next().value);
+  }
+}
+// src/helpers/pagination.ts
+async function* paginate(fetchPage, options = {}) {
+  const startPage = options.startPage ?? 1;
+  const endPage = options.endPage ?? 500;
+  assertPositiveInteger(startPage, "startPage");
+  assertPositiveInteger(endPage, "endPage");
+  for (let page = startPage;page <= endPage; page += 1) {
+    options.signal?.throwIfAborted();
+    const response = await fetchPage(page);
+    yield response;
+    if (response.results.length === 0 || page >= response.total_pages) {
+      return;
+    }
+  }
+}
+async function* paginateItems(fetchPage, options = {}) {
+  for await (const page of paginate(fetchPage, options)) {
+    yield* page.results;
+  }
+}
+function assertPositiveInteger(value, name) {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new RangeError(`${name} must be a positive integer`);
+  }
+}
+// src/helpers/retry.ts
+var MAX_RETRY_AFTER_MS = 60000;
+async function retry(task, options = {}) {
+  const retries = options.retries ?? 2;
+  if (!Number.isInteger(retries) || retries < 0) {
+    throw new RangeError("retries must be a non-negative integer");
+  }
+  const retryOn = options.retryOn ?? shouldRetry;
+  const signal = options.signal;
+  if (signal?.aborted) {
+    throw signal.reason;
+  }
+  for (let attempt = 0;; attempt += 1) {
+    try {
+      return await task();
+    } catch (error) {
+      if (signal?.aborted) {
+        throw signal.reason;
+      }
+      if (attempt >= retries || !retryOn(error, attempt)) {
+        throw error;
+      }
+      const delayMs = retryDelay(error, attempt, options);
+      options.onRetry?.({ attempt, delayMs, error });
+      await sleep(delayMs, signal);
+    }
+  }
+}
+function withRetry(transport, options = {}) {
+  return {
+    ...transport,
+    get(path, requestOptions) {
+      const { cleanup, signal } = combineSignals(options.signal, requestOptions?.signal);
+      const effectiveOptions = signal === undefined ? requestOptions : { ...requestOptions, signal };
+      return retry(() => transport.get(path, effectiveOptions), {
+        ...options,
+        signal
+      }).finally(cleanup);
+    }
+  };
+}
+function shouldRetry(error) {
+  if (error instanceof TMDBRateLimitError) {
+    return true;
+  }
+  if (error instanceof TMDBResponseError) {
+    return error.isServerError || error.status === 408;
+  }
+  if (error instanceof TMDBTimeoutError) {
+    return false;
+  }
+  if (error instanceof TMDBRequestError) {
+    if (error.cause === undefined || error.cause instanceof TMDBTimeoutError) {
+      return false;
+    }
+    return !isAbortError(error.cause);
+  }
+  return false;
+}
+function retryDelay(error, attempt, options) {
+  const retryAfter = retryAfterMs(error);
+  if (retryAfter !== undefined) {
+    return Math.min(Math.max(retryAfter, 0), MAX_RETRY_AFTER_MS);
+  }
+  if (error instanceof TMDBRateLimitError) {
+    return Math.min(Math.max(error.retryAfter * 1000, 0), MAX_RETRY_AFTER_MS);
+  }
+  const baseDelayMs = options.baseDelayMs ?? 250;
+  const maxDelayMs = options.maxDelayMs ?? 1e4;
+  const factor = options.factor ?? 2;
+  const delay = Math.min(maxDelayMs, baseDelayMs * factor ** attempt);
+  return options.jitter === false ? delay : Math.random() * delay;
+}
+function retryAfterMs(error) {
+  if (!(error instanceof TMDBResponseError)) {
+    return;
+  }
+  const header = error.headers.get("retry-after");
+  if (header === null || header.trim() === "") {
+    return;
+  }
+  return parseRetryAfter(header) * 1000;
+}
+function combineSignals(first, second) {
+  if (first === undefined || second === undefined || first === second) {
+    return { cleanup: noop, signal: first ?? second };
+  }
+  const controller = new AbortController;
+  const onAbort = () => controller.abort((first.aborted ? first : second).reason);
+  first.addEventListener("abort", onAbort, { once: true });
+  second.addEventListener("abort", onAbort, { once: true });
+  if (first.aborted || second.aborted) {
+    onAbort();
+  }
+  return {
+    cleanup() {
+      first.removeEventListener("abort", onAbort);
+      second.removeEventListener("abort", onAbort);
+    },
+    signal: controller.signal
+  };
+}
+function noop() {}
+function isAbortError(error) {
+  return typeof error === "object" && error !== null && "name" in error && error.name === "AbortError";
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      reject(signal.reason);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted) {
+      onAbort();
+    }
+  });
+}
+// src/helpers/timeout.ts
+async function withTimeout(timeoutMs, task, options = {}) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new RangeError("timeoutMs must be a positive number");
+  }
+  const parent = options.signal;
+  const controller = new AbortController;
+  const timeoutError = new TMDBTimeoutError(timeoutMs, options.message);
+  const onAbort = () => controller.abort(parent.reason);
+  parent?.addEventListener("abort", onAbort, { once: true });
+  if (parent?.aborted) {
+    parent.removeEventListener("abort", onAbort);
+    throw parent.reason;
+  }
+  const timer = setTimeout(() => controller.abort(timeoutError), timeoutMs);
+  try {
+    return await task(controller.signal);
+  } catch (error) {
+    if (controller.signal.reason === timeoutError) {
+      throw timeoutError;
+    }
+    if (parent?.aborted) {
+      throw parent.reason;
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    parent?.removeEventListener("abort", onAbort);
+  }
+}
 // src/search-guards.ts
 function isMovieSearchResult(result) {
   return isObjectWithMediaType(result, "movie");
@@ -737,9 +1097,11 @@ export {
   KNOWN_STILL_SIZES,
   TMDBClient,
   TMDBError,
+  TMDBHttpClient,
   TMDBRateLimitError,
   TMDBRequestError,
   TMDBResponseError,
+  TMDBTimeoutError,
   buildImageUrl,
   createTMDB,
   isKnownBackdropSize,
@@ -753,8 +1115,14 @@ export {
   isPerson,
   isPersonSearchResult,
   isTV,
-  isTVSearchResult
+  isTVSearchResult,
+  paginate,
+  paginateItems,
+  retry,
+  withMemoryCache,
+  withRetry,
+  withTimeout
 };
 
-//# debugId=00B61D5405D17A8964756E2164756E21
+//# debugId=24603BBDC4DA497C64756E2164756E21
 //# sourceMappingURL=index.js.map