From 714978b84513e7ff76b32c017b3802c0a51ec1a8 Mon Sep 17 00:00:00 2001 From: Zach Parks Date: Sun, 10 Nov 2024 03:34:15 -0600 Subject: [PATCH 1/5] Fix exports and improve documentation. * Also increment version to `2.0.1`. --- package.json | 2 +- src/classes/Client.ts | 20 ++++++++++---------- src/classes/managers/DataStorageManager.ts | 2 +- src/classes/managers/DeathLinkManager.ts | 2 +- src/classes/managers/MessageManager.ts | 2 +- src/classes/managers/PlayersManager.ts | 2 +- src/classes/managers/SocketManager.ts | 6 +++--- src/constants.ts | 7 +++++-- src/index.ts | 4 ++++ 9 files changed, 27 insertions(+), 20 deletions(-) diff --git a/package.json b/package.json index b1fbb15..dcd018e 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "archipelago.js", - "version": "2.0.0", + "version": "2.0.1", "description": "A runtime-agnostic and zero dependency TypeScript/JavaScript library for communicating with Archipelago servers.", "license": "MIT", "type": "module", diff --git a/src/classes/Client.ts b/src/classes/Client.ts index 08008cd..81e4b3c 100644 --- a/src/classes/Client.ts +++ b/src/classes/Client.ts @@ -97,9 +97,9 @@ export class Client { * @param name The slot name this client will be connecting to. * @param game The game name this client will be connecting to. If omitted, client will connect in "TextOnly" mode. * @param options Additional optional connection arguments. - * @throws ArgumentError If slot name is empty. - * @throws LoginError If the server refuses the authentication attempt. - * @throws TypeError If provided URL is malformed or invalid protocol. + * @throws {@link ArgumentError} if slot name is empty. + * @throws {@link LoginError} if the server refuses the authentication attempt. + * @throws {@link TypeError} if provided URL is malformed or invalid protocol. * @remarks If the port is omitted, the client will default to `38281` (AP default). * * If the protocol is omitted, client will attempt to connect via wss, then fallback to ws if unsuccessful. @@ -211,7 +211,7 @@ export class Client { /** * Update the client status for the current player. For a list of known client statuses, see {@link clientStatuses}. * @param status The status to change to. - * @throws UnauthenticatedError If not connected and authenticated. + * @throws {@link UnauthenticatedError} if not connected and authenticated. * @remarks The server will automatically set the player's status to {@link clientStatuses.disconnected} when all * clients connected to this slot have disconnected, set the status to {@link clientStatuses.connected} if a client * connects to this slot when previously set to {@link clientStatuses.disconnected}, or ignores any future updates @@ -236,7 +236,7 @@ export class Client { /** * A shorthand for running `Client.updateStatus(clientStatuses.goal)`. Once set, cannot be changed and if release * and/or collect is set to automatic, will release/collect all items. - * @throws UnauthenticatedError If not connected and authenticated. + * @throws {@link UnauthenticatedError} if not connected and authenticated. */ public goal(): void { this.updateStatus(clientStatuses.goal); @@ -245,7 +245,7 @@ export class Client { /** * Request the server update this client's tags. * @param tags Tags to replace the current ones. - * @throws UnauthenticatedError If not connected and authenticated. + * @throws {@link UnauthenticatedError} if not connected and authenticated. */ public updateTags(tags: string[]): void { if (!this.authenticated) { @@ -258,7 +258,7 @@ export class Client { /** * Request the server update the kinds of item received events this client should receive. * @param items New item handling flags. - * @throws UnauthenticatedError If not connected and authenticated. + * @throws {@link UnauthenticatedError} if not connected and authenticated. */ public updateItemsHandling(items: number): void { if (!this.authenticated) { @@ -271,7 +271,7 @@ export class Client { /** * Marks a list of locations as checked on the server. * @param locations Location ids to check. - * @throws UnauthenticatedError If attempting to check locations while not authenticated. + * @throws {@link UnauthenticatedError} if attempting to check locations while not authenticated. * @remarks Locations that do not exist or have already been checked in the multi-world are ignored. */ public check(...locations: number[]): void { @@ -294,7 +294,7 @@ export class Client { * relevant clients. * - If set to `2`, this packet will create hints for all locations in this packet and broadcast only new hints to * all relevant clients. - * @throws UnauthenticatedError If attempting to scout locations while not authenticated. + * @throws {@link UnauthenticatedError} if attempting to scout locations while not authenticated. */ public async scout(locations: number[], createHint: 0 | 1 | 2 = 0): Promise { if (!this.authenticated) { @@ -326,7 +326,7 @@ export class Client { * @param targets.slots Specific slots that should receive this bounce. * @param targets.tags Specific clients with these tags that should receive this bounce. * @param data The json-serializable data to send. - * @throws UnauthenticatedError If attempting to send a bounce while not authenticated. + * @throws {@link UnauthenticatedError} if attempting to send a bounce while not authenticated. * @remarks If no targets are specified, no clients will receive this bounce packet. */ public bounce(targets: { games?: string[], slots?: number[], tags?: string[] }, data: JSONRecord): void { diff --git a/src/classes/managers/DataStorageManager.ts b/src/classes/managers/DataStorageManager.ts index 9957a58..80defb6 100644 --- a/src/classes/managers/DataStorageManager.ts +++ b/src/classes/managers/DataStorageManager.ts @@ -146,7 +146,7 @@ export class DataStorageManager { * perform certain operations, just chain additional methods until finished, then call `prepare()`. * @param key The key to manipulate. * @param _default The default value to be used if key does not exist. - * @throws TypeError if attempting to modify a read only key. + * @throws {@link TypeError} if attempting to modify a read only key. * @example * // Prepare key "my-key" and set initial value to 100, if key doesn't exist. * client.storage diff --git a/src/classes/managers/DeathLinkManager.ts b/src/classes/managers/DeathLinkManager.ts index 78781e8..4c25642 100644 --- a/src/classes/managers/DeathLinkManager.ts +++ b/src/classes/managers/DeathLinkManager.ts @@ -69,7 +69,7 @@ export class DeathLinkManager extends EventBasedManager { * multiplayer game. * @param cause Optional text explaining the cause of death. When provided, this should include the player's name. * (e.g., `Phar drowned in a vat of kittens.`) - * @throws UnauthenticatedError If attempting to send a death link before authenticating to the server. + * @throws {@link UnauthenticatedError} if attempting to send a death link before authenticating to the server. * @remarks DeathLinks sent from this client will not fire a {@link DeathEvents.deathReceived} event to avoid * an infinite feedback loop of deaths. */ diff --git a/src/classes/managers/MessageManager.ts b/src/classes/managers/MessageManager.ts index 00be64a..370735e 100644 --- a/src/classes/managers/MessageManager.ts +++ b/src/classes/managers/MessageManager.ts @@ -51,7 +51,7 @@ export class MessageManager extends EventBasedManager { * Sends a chat message to the server. * @param text The textual message to broadcast to all connected clients. * @returns A promise that resolves when the server has broadcast the chat message. - * @throws UnauthenticatedError if attempting to send a chat message when not connected or authenticated. + * @throws {@link UnauthenticatedError} if attempting to send a chat message when not connected or authenticated. */ public async say(text: string): Promise { if (!this.#client.authenticated) { diff --git a/src/classes/managers/PlayersManager.ts b/src/classes/managers/PlayersManager.ts index 91f2156..1d09fb3 100644 --- a/src/classes/managers/PlayersManager.ts +++ b/src/classes/managers/PlayersManager.ts @@ -57,7 +57,7 @@ export class PlayersManager extends EventBasedManager { /** * Returns the {@link Player} for this client's player. - * @throws Error If attempting to lookup {@link Player} object before connecting to the server. + * @throws {@link Error} if attempting to lookup {@link Player} object before connecting to the server. */ public get self(): Player { if (this.#slot === 0) { diff --git a/src/classes/managers/SocketManager.ts b/src/classes/managers/SocketManager.ts index 98c6af4..f6599eb 100644 --- a/src/classes/managers/SocketManager.ts +++ b/src/classes/managers/SocketManager.ts @@ -33,7 +33,7 @@ export class SocketManager extends EventBasedManager { * Send a list of raw client packets to the server. * @param packets List of client packets to send. * @returns This SocketManager. - * @throws SocketError if not connected to a server. + * @throws {@link SocketError} if not connected to a server. */ public send(...packets: ClientPacket[]): SocketManager { if (this.#socket) { @@ -50,8 +50,8 @@ export class SocketManager extends EventBasedManager { * needed to be performed before authenticating, but after connecting (e.g., DataPackage). * @param url The url of the server, including the protocol (e.g., `wss://archipelago.gg:38281`). * @returns The {@link RoomInfoPacket} received on initial connection. - * @throws SocketError If failed to connect or no websocket API is available. - * @throws TypeError If provided URL is malformed or invalid protocol. + * @throws {@link SocketError} if failed to connect or no websocket API is available. + * @throws {@link TypeError} if provided URL is malformed or invalid protocol. * @remarks If the port is omitted, client will default to `38281`. * * If the protocol is omitted, client will attempt to connect via `wss`, then fallback to `ws` if unsuccessful. diff --git a/src/constants.ts b/src/constants.ts index ffcae93..e9e4e10 100644 --- a/src/constants.ts +++ b/src/constants.ts @@ -1,8 +1,11 @@ /** * Archipelago version this library attempts to target. Support for older versions of the Archipelago API is not * guaranteed and some newer enhancements may no longer work or be supported. + * + * Version is represented in the format: `major.minor.build`. */ -export const targetVersion = { major: 0, minor: 5, build: 1 }; +export const targetVersion = { major: 0, minor: 5, build: 1 } as const; // Phar if you forget to update this on release, I swear to god. -export const libraryVersion = "2.0.0"; +/** The version of this library. */ +export const libraryVersion = "2.0.1"; diff --git a/src/index.ts b/src/index.ts index b433878..e0f493c 100644 --- a/src/index.ts +++ b/src/index.ts @@ -16,6 +16,7 @@ export * from "./classes/MessageNode.ts"; export * from "./classes/PackageMetadata.ts"; export * from "./classes/Player.ts"; export * from "./constants.ts"; +export * from "./errors.ts"; export * from "./events/DeathLinkEvents.ts"; export * from "./events/ItemEvents.ts"; export * from "./events/MessageEvents.ts"; @@ -25,6 +26,9 @@ export * from "./events/SocketEvents.ts"; export * from "./interfaces/ClientOptions.ts"; export * from "./interfaces/ConnectionOptions.ts"; +/* Export these API consts to the root module. */ +export { clientStatuses, itemClassifications, itemsHandlingFlags, permissions, slotTypes } from "./api"; + /** * A collection of types, constants, and enumerations that get passed over the Archipelago network protocol. * From c4b4df1b85ff32969c11ae0be787879d31fe43bb Mon Sep 17 00:00:00 2001 From: Zach Parks Date: Sun, 10 Nov 2024 03:37:15 -0600 Subject: [PATCH 2/5] Rename `itemsHandlingFlags.normal` to `itemsHandlingFlags.none` and fix doc comments --- src/api/constants.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/api/constants.ts b/src/api/constants.ts index 37b4c61..aa5394b 100644 --- a/src/api/constants.ts +++ b/src/api/constants.ts @@ -35,7 +35,7 @@ export const itemClassifications = { trap: 0b100, /** A shorthand with no flags set, also known as 'filler' or 'junk' items. */ - normal: 0, + none: 0, } as const; /** @@ -48,13 +48,13 @@ export const itemsHandlingFlags = { /** Indicates the client get items sent from other worlds. */ others: 0b001, - /** Indicates the client get items sent from your own world. Requires `REMOTE_DIFFERENT_WORLDS` to be set. */ + /** Indicates the client get items sent from your own world. Requires `others` bitflag to be set. */ own: 0b010, - /** Indicates the client get your starting inventory sent. Requires `REMOTE_DIFFERENT_WORLDS` to be set. */ + /** Indicates the client get your starting inventory sent. Requires `others` bitflag to be set. */ starting: 0b100, - /** Shorthand for `REMOTE_DIFFERENT_WORLDS`, `REMOTE_OWN_WORLD`, and `REMOTE_STARTING_INVENTORY`. */ + /** Shorthand for `others`, `own`, and `starting`. */ all: 0b111, } as const; From 3d4dd9b47851adb52773ff6ea2dba19d454b51b8 Mon Sep 17 00:00:00 2001 From: Zach Parks Date: Sun, 10 Nov 2024 03:38:39 -0600 Subject: [PATCH 3/5] Missed a spot --- src/classes/Item.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/classes/Item.ts b/src/classes/Item.ts index e25bc73..dfccb28 100644 --- a/src/classes/Item.ts +++ b/src/classes/Item.ts @@ -88,7 +88,7 @@ export class Item { /** Returns `true` if this item has no special flags. */ public get filler(): boolean { - return this.flags === itemClassifications.normal; + return this.flags === itemClassifications.none; } /** Returns the item classification bitflags for this item. */ From 709d171742579b997ecd7b34f2f258725a4329b4 Mon Sep 17 00:00:00 2001 From: Zach Parks Date: Sun, 10 Nov 2024 03:39:42 -0600 Subject: [PATCH 4/5] Small adjustment to doc comment for typedoc to be happy --- src/api/constants.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/api/constants.ts b/src/api/constants.ts index aa5394b..0590a80 100644 --- a/src/api/constants.ts +++ b/src/api/constants.ts @@ -22,7 +22,7 @@ export const clientStatuses = { } as const; /** - * Bit flags that define the special characteristics of a {@link NetworkItem}. + * Bit flags that define the special characteristics of a {@link API.NetworkItem}. */ export const itemClassifications = { /** If set, indicates the item may unlock logical advancement. */ From 970381315f5dd48e0d36aa1c92c7edfbae0fd8d7 Mon Sep 17 00:00:00 2001 From: Zach Parks Date: Sun, 10 Nov 2024 03:57:02 -0600 Subject: [PATCH 5/5] Change package.json `homepage` to https://archipelago.js.org --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index dcd018e..9a7f59c 100644 --- a/package.json +++ b/package.json @@ -22,7 +22,7 @@ "lint": "eslint src", "pack": "pnpm pack --pack-destination packs" }, - "homepage": "https://thephar.github.io/archipelago.js/", + "homepage": "https://archipelago.js.org", "repository": "https://github.com/ThePhar/archipelago.js.git", "bugs": "https://github.com/ThePhar/archipelago.js/issues", "devDependencies": {