Reference / @open-music-sdk/core / tCollection

Interface: tCollection()<C>

Defined in: packages/core/src/endpoint.ts:250

Where a collection is for one call, such as v1/catalog/us/songs: a path with nothing after it. It is handed the options the call was given, of which C is the part it reads, and may ask the client, as a catalog does for a storefront no option named. Everything else a call was handed has been checked by the time it is asked.

A collection that has to ask the client gives a function for the path, a tLater, in place of the path. That function is called when a request is about to be made: at once for a function that asks for one thing, and as each loop starts for one that walks pages, so that a walk nobody loops over asks for nothing at all. A promise is taken too, and is on its way from the moment the collection gave it.

What it gives is checked before it is asked for: plain ASCII segments with single slashes between, none of them "." or "..", and no question mark, hash or backslash. A path that is not is a TypeError that says what is wrong with it, and never shows it:

A path that	Is refused because
holds a segment that is . or .., written out or as %2e	a URL reads them as "here" and "one up", so the request would go to another path
holds a backslash	a URL reads it as a slash, so it would begin another segment
holds a question mark	it begins the query, so what follows would not be part of the path
holds a hash	it begins a fragment, so what follows would not be sent
holds a space, a tab, a line break or another control character	a URL drops or trims it, joining what was on either side
holds a character outside ASCII	a URL rewrites it
holds an empty segment	two slashes together, or one at the end, leave out what was meant to be there
begins with a name and a colon	a URL reads it as a scheme, and the rest as another address
is empty, longer than 256 characters, or no string	no collection's path is

So a storefront from outside cannot move a request under /v1/me, where the client sends the Music User Token. A collection that checks its own parts with segmentOf gets to name the option that was wrong.

Type Parameters

C

C = tNone

tCollection(
   fn, 
   client, 
   options
): 
  | string
  | Promise<string>
| tLater<string>;

Defined in: packages/core/src/endpoint.ts:261

The collection's path for one call. What it throws, the function throws as it is, from the call: a collection that reads an option should throw a TypeError naming fn for one that is not what it should be, as segmentOf does.

Parameters

fn

string

The name of the function the call was made to, for errors.

client

tAppleMusicClient

The client the call is made with, for what only it can say, such as the listener's storefront.

options

C

The options the call was given, read as the collection's own; the rest are checked elsewhere.

Returns

| string | Promise<string> | tLater<string>

The path, such as v1/catalog/us/songs; a promise of it; or a function that gives either when the request is about to be made.

Properties

user?

readonly optional user?: boolean;

Defined in: packages/core/src/endpoint.ts:267

Whether what is asked of this collection carries the Music User Token. Left out, the client goes by the path, and sends it under /v1/me. false holds for every page of a walk, wherever a next link points: it is how a catalog says that nothing asked of it is the listener's. true sends it outside /v1/me as well.