From 6a4c90d06148ea998e88abb6370b7aeea1479fc6 Mon Sep 17 00:00:00 2001 From: Dominik Biedebach Date: Fri, 29 Nov 2024 15:05:30 +0100 Subject: [PATCH] added more information for jsdoc comments --- packages/core/src/actor.ts | 13 +++++++++---- packages/core/src/feed.ts | 10 +++++++--- packages/core/src/global.d.ts | 5 +++++ packages/core/src/index.ts | 25 +++++++++++++++++++++++-- packages/core/src/list.ts | 15 +++++++++++++-- packages/core/src/paginate.ts | 17 +++++++++++++++++ packages/core/src/post.ts | 27 +++++++++++++++++++++++++-- packages/core/src/preference.ts | 13 +++++++++++-- packages/core/src/starterPack.ts | 13 +++++++++++-- packages/core/src/video.ts | 22 ++++++++++++++++++++-- 10 files changed, 141 insertions(+), 19 deletions(-) create mode 100644 packages/core/src/global.d.ts diff --git a/packages/core/src/actor.ts b/packages/core/src/actor.ts index 78064d9..e0867ec 100644 --- a/packages/core/src/actor.ts +++ b/packages/core/src/actor.ts @@ -16,12 +16,17 @@ import type { AppBskyGraphUnmuteActorList, AppBskyGraphUnmuteThread, AppBskyNS, -} from "@atproto/api"; -import { Paginator } from "./paginate"; -import { Preferences } from "./preference"; +} from '@atproto/api'; +import { Paginator } from './paginate'; +import { Preferences } from './preference'; export class BaseActor { - constructor(readonly instance: AppBskyNS, readonly actor: string) {} + /** + * Creates a new instance of the Actor class. + * @param instance The instance of the `AppBskyNS` class. + * @param actor The atproto identifier of the actor. + */ + constructor(readonly instance: AppBskyNS, readonly actor: AtIdentifier) {} /** * Get a list of starter packs created by the actor. diff --git a/packages/core/src/feed.ts b/packages/core/src/feed.ts index b65530f..8d02f0c 100644 --- a/packages/core/src/feed.ts +++ b/packages/core/src/feed.ts @@ -7,10 +7,14 @@ import type { AppBskyFeedGetTimeline, AppBskyFeedSendInteractions, AppBskyNS, -} from "@atproto/api"; -import { Paginator } from "./paginate"; +} from '@atproto/api'; +import { Paginator } from './paginate'; export class Feed { + /** + * Creates a new instance of the Feed class. + * @param instance The instance of the `AppBskyNS` class. + */ constructor(private instance: AppBskyNS) {} /** @@ -89,7 +93,7 @@ class FeedGenerator { feed( feeds: string[], options?: AppBskyFeedGetFeedGenerators.CallOptions - ): Promise; + ): Promise; async feed( feed: string | string[], diff --git a/packages/core/src/global.d.ts b/packages/core/src/global.d.ts new file mode 100644 index 0000000..1f1c239 --- /dev/null +++ b/packages/core/src/global.d.ts @@ -0,0 +1,5 @@ +/** + * A atproto identifier. + * @example 'at://did:plc:z72i7hdynmk6r22z27h6tvur' + */ +type AtIdentifier = string; diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index ba94445..6abb133 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -5,14 +5,21 @@ import type { AppBskyActorGetProfile, AppBskyActorSearchActorsTypeahead, AppBskyActorSearchActors, -} from "@atproto/api"; -import { Paginator } from "./paginate"; +} from '@atproto/api'; +import { Paginator } from './paginate'; export class TSky { + /** + * Creates a new instance of the TSky class. + * @param instance The instance of the `AppBskyNS` class. + */ constructor(private instance: AppBskyNS) {} /** * Get detailed profile view of an actor. Does not require auth, but contains relevant metadata with auth. + * @param identifier The atproto identifier of the actor. + * @param options Additional options. + * @returns The detailed profile view of the actor. */ profile( identifier: string, @@ -20,12 +27,20 @@ export class TSky { ): Promise; /** * Get detailed profile views of multiple actors. + * @param identifiers The atproto identifiers of the actors. + * @param options Additional options. */ profile( identifiers: string[], options?: AppBskyActorGetProfiles.CallOptions ): Promise; + /** + * Get detailed profile view of an actor. Does not require auth, but contains relevant metadata with auth. + * @param identifier The atproto identifier or identifiers of the actor/s. + * @param options Additional options. + * @returns The detailed profile view of the actor/s. + */ async profile( identifier: string | string[], options?: @@ -51,6 +66,9 @@ export class TSky { /** * Find actor suggestions for a prefix search term. Expected use is for auto-completion during text field entry. Does not require auth. + * @param params The query parameters. + * @param options Additional options. + * @returns The actor suggestions. */ async typeahead( params: AppBskyActorSearchActorsTypeahead.QueryParams, @@ -66,6 +84,9 @@ export class TSky { /** * Find actors (profiles) matching search criteria. Does not require auth. + * @param params The query parameters. + * @param options Additional options. + * @returns The paginator for the search results. */ async search( params: AppBskyActorSearchActors.QueryParams = {}, diff --git a/packages/core/src/list.ts b/packages/core/src/list.ts index 9c41564..124d753 100644 --- a/packages/core/src/list.ts +++ b/packages/core/src/list.ts @@ -2,14 +2,22 @@ import type { AppBskyFeedGetListFeed, AppBskyGraphGetList, AppBskyNS, -} from "@atproto/api"; -import { Paginator } from "./paginate"; +} from '@atproto/api'; +import { Paginator } from './paginate'; export class BskyList { + /** + * Creates a new instance of the List class. + * @param instance The instance of the `AppBskyNS` class. + * @param uri The atproto identifier of the list. + */ constructor(private instance: AppBskyNS, private uri: string) {} /** * Gets a 'view' (with additional context) of a specified list. + * @param limit The maximum number of items to return per page. + * @param options Additional options. + * @returns The list view paginator. */ about(limit?: number, options?: AppBskyGraphGetList.CallOptions) { return new Paginator(async (cursor) => { @@ -28,6 +36,9 @@ export class BskyList { /** * Get a feed of recent posts from a list (posts and reposts from any actors on the list). Does not require auth. + * @param limit The maximum number of items to return per page. + * @param options Additional options. + * @returns The list feed paginator. */ feed(limit?: number, options?: AppBskyFeedGetListFeed.CallOptions) { return new Paginator(async (cursor) => { diff --git a/packages/core/src/paginate.ts b/packages/core/src/paginate.ts index bdf6d4f..ea14bf2 100644 --- a/packages/core/src/paginate.ts +++ b/packages/core/src/paginate.ts @@ -3,9 +3,18 @@ type CursorResponse = { [key: string]: unknown; }; +/** + * A paginator for fetching data from a cursor-based API. + * @template T The type of the cursor response. + */ export class Paginator { readonly values: T[] = []; + /** + * Creates a new instance of the Paginator class. + * @param onNext The function to call to get the next page of data. + * @param defaultValues The default values to start with. + */ constructor( private onNext: (cursor?: string) => Promise, defaultValues?: T[] @@ -18,10 +27,18 @@ export class Paginator { // this.next(); } + /** + * Clone this paginator. + * @returns A new paginator with the same values. + */ clone() { return new Paginator(this.onNext, this.values); } + /** + * Get the data for the next page. + * @returns The data for the next page. If there is no more data, returns `null`. + */ async next() { const hasValues = this.values.length > 0; diff --git a/packages/core/src/post.ts b/packages/core/src/post.ts index 25bdc16..88f11e7 100644 --- a/packages/core/src/post.ts +++ b/packages/core/src/post.ts @@ -6,14 +6,21 @@ import type { AppBskyFeedGetRepostedBy, AppBskyFeedSearchPosts, AppBskyNS, -} from "@atproto/api"; -import { Paginator } from "./paginate"; +} from '@atproto/api'; +import { Paginator } from './paginate'; export class Post { + /** + * Creates a new instance of the Post class. + * @param instance The instance of the `AppBskyNS` class. + */ constructor(private instance: AppBskyNS) {} /** * Get posts in a thread. Does not require auth, but additional metadata and filtering will be applied for authed requests. + * @param params The query parameters. + * @param options Additional options. + * @returns The posts in the thread. */ async threads( params: AppBskyFeedGetPostThread.QueryParams, @@ -26,6 +33,9 @@ export class Post { /** * Get like records which reference a subject (by AT-URI and CID). + * @param params The query parameters. + * @param options Additional options. + * @returns The likes paginator of a post. */ likes( params: AppBskyFeedGetLikes.QueryParams, @@ -43,6 +53,9 @@ export class Post { /** * Get a list of quotes for a given post. + * @param params The query parameters. + * @param options Additional options. + * @returns The quotes paginator of a post. */ quotes( params: AppBskyFeedGetQuotes.QueryParams, @@ -60,6 +73,9 @@ export class Post { /** * Get a list of reposts for a given post. + * @param params The query parameters. + * @param options Additional options. + * @returns The reposts paginator of a post. */ repostedBy( params: AppBskyFeedGetRepostedBy.QueryParams, @@ -77,6 +93,9 @@ export class Post { /** * Find posts matching search criteria, returning views of those posts. + * @param params The query parameters. + * @param options Additional options. + * @returns The posts paginator. */ static search( instance: AppBskyNS, @@ -95,6 +114,10 @@ export class Post { /** * Gets post views for a specified list of posts (by AT-URI). This is sometimes referred to as 'hydrating' a 'feed skeleton'. + * @param instance The instance of the `AppBskyNS` class. + * @param posts The list of posts to get. + * @param options Additional options. + * @returns The hydrated posts. */ static async getMany( instance: AppBskyNS, diff --git a/packages/core/src/preference.ts b/packages/core/src/preference.ts index 97f2506..d16ef47 100644 --- a/packages/core/src/preference.ts +++ b/packages/core/src/preference.ts @@ -2,13 +2,19 @@ import type { AppBskyActorGetPreferences, AppBskyActorPutPreferences, AppBskyNS, -} from "@atproto/api"; +} from '@atproto/api'; export class Preferences { + /** + * Creates a new instance of the Preferences class. + * @param instance The instance of the `AppBskyNS` class. + */ constructor(private instance: AppBskyNS) {} /** * Get private preferences attached to the current account. Expected use is synchronization between multiple devices, and import/export during account migration. Requires auth. + * @param options Additional options. + * @returns The private preferences attached to the account. */ async get(options?: AppBskyActorGetPreferences.CallOptions) { const res = await this.instance.actor.getPreferences(undefined, options); @@ -18,9 +24,12 @@ export class Preferences { /** * Set the private preferences attached to the account. + * @param preferences The preferences to set. + * @param options Additional options. + * @returns An empty promise */ async set( - preferences: AppBskyActorPutPreferences.InputSchema["preferences"], + preferences: AppBskyActorPutPreferences.InputSchema['preferences'], options?: AppBskyActorPutPreferences.CallOptions ) { await this.instance.actor.putPreferences({ preferences }, options); diff --git a/packages/core/src/starterPack.ts b/packages/core/src/starterPack.ts index a860772..60e3e85 100644 --- a/packages/core/src/starterPack.ts +++ b/packages/core/src/starterPack.ts @@ -3,14 +3,16 @@ import type { AppBskyGraphGetStarterPacks, AppBskyGraphSearchStarterPacks, AppBskyNS, -} from "@atproto/api"; -import { Paginator } from "./paginate"; +} from '@atproto/api'; +import { Paginator } from './paginate'; export class StarterPack { constructor(private instance: AppBskyNS, private uri: string) {} /** * Gets a view of a starter pack. + * @param options Additional options. + * @returns The starter pack view. */ async about(options?: AppBskyGraphGetStarterPack.CallOptions) { const res = await this.instance.graph.getStarterPack( @@ -25,6 +27,10 @@ export class StarterPack { /** * Search for starter packs. + * @param query The search query. + * @param limit The maximum number of items to return per page. + * @param options Additional options. + * @returns The starter pack search paginator. */ static search( instance: AppBskyNS, @@ -48,6 +54,9 @@ export class StarterPack { /** * Get views for a list of starter packs. + * @param starterpacks The atproto identifiers of the starter packs. + * @param options Additional options. + * @returns The starter pack views. */ static async getMany( instance: AppBskyNS, diff --git a/packages/core/src/video.ts b/packages/core/src/video.ts index a840c8d..9596706 100644 --- a/packages/core/src/video.ts +++ b/packages/core/src/video.ts @@ -5,13 +5,24 @@ import type { AppBskyVideoUploadVideo, AppBskyVideoDefs, BlobRef, -} from "@atproto/api"; +} from '@atproto/api'; + +export type VideoJobState = + | 'JOB_STATE_COMPLETED' + | 'JOB_STATE_FAILED' + | (string & {}); export class Video { + /** + * Creates a new instance of the Video class. + * @param instance The instance of the `AppBskyNS` class. + */ constructor(private instance: AppBskyNS) {} /** * Get video upload limits for the authenticated user. + * @param options Additional options. + * @returns The video upload limits. */ async limit(options?: AppBskyVideoGetUploadLimits.CallOptions) { const res = await this.instance.video.getUploadLimits({}, options); @@ -21,6 +32,9 @@ export class Video { /** * Get status details for a video processing job. + * @param jobId The job ID. + * @param options Additional options. + * @returns The status details for the video processing job. */ async status(jobId: string, options?: AppBskyVideoGetJobStatus.CallOptions) { const res = await this.instance.video.getJobStatus({ jobId }, options); @@ -30,6 +44,9 @@ export class Video { /** * Upload a video to be processed then stored on the PDS. + * @param data The video upload data. + * @param options Additional options. + * @returns The status of the video processing job. */ async upload( data: AppBskyVideoUploadVideo.InputSchema, @@ -45,7 +62,7 @@ class JobStatus { jobId: string; did: string; /** The state of the video processing job. All values not listed as a known value indicate that the job is in process. */ - state: "JOB_STATE_COMPLETED" | "JOB_STATE_FAILED" | (string & {}); + state: VideoJobState; /** Progress within the current processing state. */ progress?: number; blob?: BlobRef; @@ -66,6 +83,7 @@ class JobStatus { /** * Update status details for a video processing job. + * @param options Additional options. */ async refresh(options?: AppBskyVideoGetJobStatus.CallOptions) { const res = await this.instance.video.getJobStatus(