From 97576b0de155ca8e4447617093df60b23b9875c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?marcin=20miko=C5=82ajczak?= Date: Fri, 29 Nov 2024 19:48:03 +0100 Subject: [PATCH] pl-api: improve docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: marcin mikołajczak --- packages/pl-api/lib/client.ts | 36 ++++++++++++++++++++----- packages/pl-api/lib/directory-client.ts | 5 ++++ 2 files changed, 34 insertions(+), 7 deletions(-) diff --git a/packages/pl-api/lib/client.ts b/packages/pl-api/lib/client.ts index 7b1c2de03..a1dd33ae9 100644 --- a/packages/pl-api/lib/client.ts +++ b/packages/pl-api/lib/client.ts @@ -241,8 +241,23 @@ import type { PaginatedResponse } from './responses'; const GROUPED_TYPES = ['favourite', 'reblog', 'emoji_reaction', 'event_reminder', 'participation_accepted', 'participation_request']; +interface PlApiClientConstructorOpts { + /** Instance object to use by default, to be populated eg. from cache */ + instance?: Instance; + /** Fetch instance after constructing */ + fetchInstance?: boolean; + /** Abort signal which can be used to cancel the callbacks */ + fetchInstanceSignal?: AbortSignal; + /** Executed after the initial instance fetch */ + onInstanceFetchSuccess?: (instance: Instance) => void; + /** Executed when the initial instance fetch failed */ + onInstanceFetchError?: (error?: any) => void; +} + /** * @category Clients + * + * Mastodon API client. */ class PlApiClient { @@ -259,17 +274,18 @@ class PlApiClient { close: () => void; }; + /** + * + * @param baseURL Mastodon API-compatible server URL + * @param accessToken OAuth token for an authorized user + */ constructor(baseURL: string, accessToken?: string, { instance, fetchInstance, + fetchInstanceSignal, onInstanceFetchSuccess, onInstanceFetchError, - }: { - instance?: Instance; - fetchInstance?: boolean; - onInstanceFetchSuccess?: (instance: Instance) => void; - onInstanceFetchError?: (error?: any) => void; - } = {}) { + }: PlApiClientConstructorOpts = {}) { this.baseURL = baseURL; this.#accessToken = accessToken; @@ -277,7 +293,13 @@ class PlApiClient { this.#setInstance(instance); } if (fetchInstance) { - this.instance.getInstance().then(onInstanceFetchSuccess).catch(onInstanceFetchError); + this.instance.getInstance().then((instance) => { + if (fetchInstanceSignal?.aborted) return; + onInstanceFetchSuccess?.(instance); + }).catch((error) => { + if (fetchInstanceSignal?.aborted) return; + onInstanceFetchError?.(error); + }); } } diff --git a/packages/pl-api/lib/directory-client.ts b/packages/pl-api/lib/directory-client.ts index d803a9da7..0b280de87 100644 --- a/packages/pl-api/lib/directory-client.ts +++ b/packages/pl-api/lib/directory-client.ts @@ -22,6 +22,8 @@ interface Params { /** * @category Clients + * + * joinmastodon.org-compatible server directory client. */ class PlApiDirectoryClient { @@ -33,6 +35,9 @@ class PlApiDirectoryClient { baseURL: string; public request = request.bind(this) as typeof request; + /** + * @param baseURL Server directory URL. e.g. `https://joinmastodon.org` + */ constructor(baseURL: string) { this.baseURL = baseURL; }