@ekwoka/spotify-api - npm Package Compare versions

Comparing version 0.0.9 to 0.1.0

dist/endpoints/albums/getAlbum.d.ts

 import { QueryFunction } from '../../core';
 import { Album } from './types';
 /**
- * Gets single album by ID. This endpoint is implemented through getAlbums to
- * allow for improved performance and a smaller bundle size. In the future
- * this endpoint will batch and cache album data to limit requests.
+ * Gets single album by ID. This endpoint is the center of the main albums
+ * endpoints allowing for improved performance and smaller bundle sizes.
+ * This handles the individual calls to batch the requests together.
  * @param id string
@@ -8,0 +8,0 @@ * @param market string

dist/endpoints/albums/getAlbum.js

@@ -1,6 +0,7 @@
-import { getAlbums } from '.';
+import { batchAlbums } from '.';
+import { deepFreeze } from '../../utils';
 /**
- * Gets single album by ID. This endpoint is implemented through getAlbums to
- * allow for improved performance and a smaller bundle size. In the future
- * this endpoint will batch and cache album data to limit requests.
+ * Gets single album by ID. This endpoint is the center of the main albums
+ * endpoints allowing for improved performance and smaller bundle sizes.
+ * This handles the individual calls to batch the requests together.
  * @param id string
@@ -10,5 +11,10 @@ * @param market string
  */
-export const getAlbum = (id, market) => async (client) => {
-    const { albums } = await getAlbums([id], market)(client);
-    return albums[0];
+export const getAlbum = (id, market) => async ({ token, cache }) => {
+    if (!cache.albums)
+        cache.albums = {};
+    if (cache.albums[id])
+        return cache.albums[id];
+    const album = await batchAlbums(token, id, market);
+    cache.albums[id] = deepFreeze(album);
+    return album;
 };

dist/endpoints/albums/getAlbums.d.ts

@@ -5,4 +5,4 @@ import { Album } from '.';
  * Gets multiple albums with one request to Spotify. Market limits the search
- * to a specific market. In the future, this endpoint will intelligently
- * batch and cache requests to improve performance and limit requests.
+ * to a specific market. This endpoint is passes the album IDs to getAlbum
+ * to allow for intelligent batching with a reduced bundle size.
  * @param ids string[]
@@ -9,0 +9,0 @@ * @param market string

dist/endpoints/albums/getAlbums.js

@@ -1,6 +0,6 @@
-import { spotifyFetch, toURLString } from '../../utils';
+import { getAlbum } from '.';
 /**
  * Gets multiple albums with one request to Spotify. Market limits the search
- * to a specific market. In the future, this endpoint will intelligently
- * batch and cache requests to improve performance and limit requests.
+ * to a specific market. This endpoint is passes the album IDs to getAlbum
+ * to allow for intelligent batching with a reduced bundle size.
  * @param ids string[]
@@ -10,9 +10,5 @@ * @param market string
  */
-export const getAlbums = (ids, market) => async ({ token }) => {
-    const endpoint = `albums?${toURLString({
-        ids: ids.join(','),
-        ...(market && { market }),
-    })}`;
-    const data = await spotifyFetch(endpoint, token);
-    return data;
+export const getAlbums = (ids, market) => async (client) => {
+    const albums = await Promise.all(ids.map((id) => getAlbum(id, market)(client)));
+    return { albums };
 };

dist/endpoints/albums/getAlbumTracks.d.ts

@@ -5,4 +5,4 @@ import { QueryFunction } from '../../core';
  * Gets single album's TrackList by ID. This endpoint is implemented through
- * getAlbums to allow for improved performance and a smaller bundle size.
- * In the future, this endpoint will batch and cache Tracklist info.
+ * getAlbum to allow for improved performance and a smaller bundle size.
+ * This batches Tracklist Requests into single calls to the API.
  * @param id string
@@ -9,0 +9,0 @@ * @param market string

dist/endpoints/albums/getAlbumTracks.js

@@ -1,6 +0,6 @@
-import { getAlbums } from './';
+import { getAlbum } from './';
 /**
  * Gets single album's TrackList by ID. This endpoint is implemented through
- * getAlbums to allow for improved performance and a smaller bundle size.
- * In the future, this endpoint will batch and cache Tracklist info.
+ * getAlbum to allow for improved performance and a smaller bundle size.
+ * This batches Tracklist Requests into single calls to the API.
  * @param id string
@@ -11,4 +11,4 @@ * @param market string
 export const getAlbumTracks = (id, market) => async (client) => {
-    const { albums } = await getAlbums([id], market)(client);
-    return albums[0].tracks;
+    const album = await getAlbum(id, market)(client);
+    return album.tracks;
 };

dist/endpoints/albums/index.d.ts

@@ -0,1 +1,2 @@
+export { batchAlbums } from './batchAlbums';
 export { getAlbum } from './getAlbum';
@@ -2,0 +3,0 @@ export { getAlbums } from './getAlbums';

dist/endpoints/albums/index.js

@@ -0,3 +1,4 @@
+export { batchAlbums } from './batchAlbums';
 export { getAlbum } from './getAlbum';
 export { getAlbums } from './getAlbums';
 export { getAlbumTracks } from './getAlbumTracks';

dist/utils/index.d.ts

@@ -0,1 +1,5 @@
+export { arrayWrap } from './arrayWrap';
+export { batchWrap } from './batchRequests';
+export { chunkArray } from './chunkArray';
+export { debounce } from './debounce';
 export { deepFreeze } from './deepFreeze';
@@ -7,3 +11,4 @@ export { isBrowser, isNode } from './isBrowserOrNode';
 export { toURLString } from './toURLString';
+export type { BatchedFunction } from './batchRequests';
 export type { Image, SpotifyPageURL, SpotifyAPIURL, } from './SpotifyUtilityTypes';
 //# sourceMappingURL=index.d.ts.map

dist/utils/index.js

@@ -0,1 +1,5 @@
+export { arrayWrap } from './arrayWrap';
+export { batchWrap } from './batchRequests';
+export { chunkArray } from './chunkArray';
+export { debounce } from './debounce';
 export { deepFreeze } from './deepFreeze';
@@ -2,0 +6,0 @@ export { isBrowser, isNode } from './isBrowserOrNode';

package.json

@@ -12,3 +12,3 @@ {
   "license": "MIT",
-  "version": "0.0.9",
+  "version": "0.1.0",
   "description": "Composable Wrapper for the Spotify Web Api and Spotify Web Playback SDK",
@@ -47,2 +47,3 @@ "keywords": [
     "size": "node scripts/esbuild.js",
+    "size:test": "NODE_ENV=test node scripts/esbuild.js",
     "build": "tsc",
@@ -49,0 +50,0 @@ "lint": "eslint --fix ./src; prettier --write ./src --loglevel error",

README.md

@@ -77,8 +77,12 @@ # ⚡️A tree-shakable, composable, lightweight wrapper for the multiple Spotify APIs🔥
 ```js
-import { getTokenFromCode, refreshToken, makeAuthURL } from '@ekwoka/spotify-api';
+import {
+  getTokenFromCode,
+  refreshToken,
+  makeAuthURL,
+} from '@ekwoka/spotify-api';
 
-const loginHandler = async(req, res) => {
-	const url = makeAuthURL(['user-read-email'])
-	res.redirect(302, url)
-}
+const loginHandler = async (req, res) => {
+  const url = makeAuthURL(['user-read-email']);
+  res.redirect(302, url);
+};
 
@@ -121,4 +125,7 @@ const codeHandler = async (req, res) => {
 
-> While these correspond to 3 different endpoints to Spotify's API, internally these 3 use only the `getAlbums` endpoints for improved code-reuse as well as future batching and caching.
+> While these correspond to 3 different endpoints to Spotify's API, internally these 3 use only the `getAlbums` endpoints for improved code-reuse.
 
+Cachekey: 'albums.[id]'
+Batching Limit: 20
+
 ### getAlbum
@@ -129,4 +136,4 @@
 ```js
-const album = client(getAlbum('6tLZvqqoWszgPagzzNNQQF'))
-const albumInMarket = client(getAlbum('6tLZvqqoWszgPagzzNNQQF', 'KR'))
+const album = client(getAlbum('6tLZvqqoWszgPagzzNNQQF'));
+const albumInMarket = client(getAlbum('6tLZvqqoWszgPagzzNNQQF', 'KR'));
 ```
@@ -139,4 +146,8 @@
 ```js
-const albums = client(getAlbums(['6tLZvqqoWszgPagzzNNQQF','6XBIkDFhDgc3PQOUEcO2fd']))
-const albumsInMarket = client(getAlbums(['6tLZvqqoWszgPagzzNNQQF','6XBIkDFhDgc3PQOUEcO2fd'], 'KR'))
+const albums = client(
+  getAlbums(['6tLZvqqoWszgPagzzNNQQF', '6XBIkDFhDgc3PQOUEcO2fd'])
+);
+const albumsInMarket = client(
+  getAlbums(['6tLZvqqoWszgPagzzNNQQF', '6XBIkDFhDgc3PQOUEcO2fd'], 'KR')
+);
 ```
@@ -149,7 +160,6 @@
 ```js
-const album = client(getAlbumTracks('6tLZvqqoWszgPagzzNNQQF'))
-const albumInMarket = client(getAlbumTracks('6tLZvqqoWszgPagzzNNQQF', 'KR'))
+const album = client(getAlbumTracks('6tLZvqqoWszgPagzzNNQQF'));
+const albumInMarket = client(getAlbumTracks('6tLZvqqoWszgPagzzNNQQF', 'KR'));
 ```
 
-
 ### Users
@@ -202,2 +212,40 @@
 
+## Batching and Caching
+
+One of the unique features of this API wrapper is the use of batched requests and intelligent caching. These features serve the purpose of reducing the number of requests make to the Spotify API and generally improving the responsiveness of your application.
+
+All of these takes place under the hood, and the implementation of your code should be relatively agnostic to the fact this is happening.
+
+### Batching
+
+Many endpoints that exist with the Spotify API accept the request for multiple items at a single time. For example, even though a singular `album` endpoint exists, there is also an `albums` endpoint that returns the same information, but simply using an array of album IDs instead of a singular one.
+
+So, the basic idea is that, if the application is making calls for many individual items ( like `album`), and those items can be batched (into `albums`), this wrapper will automatically do so and distribute the results.
+
+Example:
+
+```js
+const ids = ['6tLZvqqoWszgPagzzNNQQF', '6XBIkDFhDgc3PQOUEcO2fd'];
+ids.forEach(async (id) => {
+  const album = await client(getAlbum(id));
+  console.log(album.name);
+});
+```
+
+While this isa bit contrived, in a component based framework, you might have these actual calls happening in places far away from each other.
+
+In the background, these two ids will be bunched together (if they come in close enough to eachother) sent as a single request to Spotify, and resolved from the return. This also includes combining multiple requests for a single album into only the one reference requested from Spotify.
+
+#### Splitting Large Lists
+
+This system also comes with another nice feature. These multiple item endpoints have limits on the total number of items in a single request. For the above example of `albums` it's 20.
+
+Once again, in the background, as these requests come in, the total number of albums may be greater than 20. Or you may even do a direct request for more than 20 albums.
+
+In the background, the request will be bunched into groups of 20, sent as requests, and, once again, distributed back to whence they came.
+
+### Caching
+
+As this data changes infrequently, responses will be cached and reused when the same information is requested again. This works with the above batching, as well. So if you make a bulk request for 10 albums, 3 of which you've already searched for before, those 3 will be returned from cache and the other 7 will be fetched anew, all without any adjustments to how your code behaves.
+
 ## Special Utilities
@@ -204,0 +252,0 @@

Fixed alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

54892

increased by19.42%

Number of package files

119

increased by14.42%

Lines of code

738

increased by20.2%

Number of lines in readme file

262

increased by22.43%

Number of medium supply chain risk alerts

3

decreased by-25%

No dependency changes