[email protected] Changes (#209)

* Update version number to `2.0.0-rc5`
* Refactor file naming (again) and break up some larger files.
* Tweak how `Client.login` works by making `game` optional (but forces
`TextOnly`, if omitted).
* Remove `Client.setAlias`.
* Add better generic typing support for methods in `DataStorageManager`
and `IntermediateDataOperation`.
* Fix some jsdoc comments.
* Optimize some typing.
* Fix `IntermediateDataOperation.commit` not returning the correct data.
* Add custom errors for expected AP.js specific errors.
* Add a getting started guide to the documentation.

README.md

@@ -16,19 +16,11 @@ Targeted to work on all major desktop and mobile browsers ([Firefox](https://www
 
 Install via `npm install archipelago.js` (or via your preferred package manager's flavor).
 
-## Quick Start
+## Quick Start Guide
 
-```js
-import { Client } from "archipelago.js";
+Check out the quick start documentation [here](https://archipealgo.js.org/stable/documents/Quick_Start.html)!
 
-const client = new Client();
-
-// Connect to Archipelago session.
-client.login("wss://archipelago.gg:38281", "Phar", "Clique")
-    .then(() => client.messages.chat("Hello, multiworld!"));
-```
-
-## Documentation
+## API Documentation
 
 The full API documentation is located [here](https://thephar.github.io/archipelago.js/). Please be sure to reference it
 while you are developing your JavaScript-based clients.

eslint.config.mjs

@@ -25,7 +25,7 @@ export default tslint.config(
             "@stylistic/indent-binary-ops": ["error", 4],
             "@stylistic/quotes": ["error", "double"],
             "@stylistic/semi": ["error", "always"],
-            "jsdoc/check-tag-names": ["warn", { definedTags: ["remarks", "category", "typeParam", "experimental"] }],
+            "jsdoc/check-tag-names": ["warn", { definedTags: ["remarks", "category", "experimental"] }],
             "jsdoc/require-description": "warn",
             "jsdoc/require-template": "warn",
             "jsdoc/require-returns": "off",

guides/getting_started.md

@@ -0,0 +1,144 @@
+---
+title: Quick Start
+group: Documents
+category: Guides
+---
+# Quick Start Guide
+
+## Pre-requisites
+
+Before we begin, make sure you fulfil the following prerequisites:
+
+* Have a basic understanding of JavaScript.
+* Have installed a JavaScript runtime or web server for starting in the web browser.
+* Have an Archipelago server to connect to.
+
+## Installation
+
+To start a new project with **archipelago.js**, you'll need to set up a project directory.
+
+If you're using a runtime like **Node**, you can install **archipelago.js** by running the following command in your
+project directory: `npm install archipelago.js`, then following the rest of this tutorial.
+
+If you're looking to run this in a web browser without packaging as a part of a tool like **vite** or **webpack**, you
+can add a `<script type="module">` tag to your HTML to write your JavaScript in and replace any mention of 
+```js
+import { /* ... */ } from "archipelago.js";
+```
+to
+```js
+import { /* ... */ } from "https://unpkg.com/archipelago.js/dist/archipelago.min.js";
+// or any other path to archipelago.js as desired
+``` 
+
+as appropriate for your project and all the code examples will still work.
+
+## Getting Started
+
+To create a basic client that can listen for chat messages and print them to the console, you can use the following
+example:
+
+```js
+import { Client } from "archipelago.js";
+
+// Create a new instance of the Client class.
+const client = new Client();
+
+// Setup a listener for incoming chat messages and print them to the console.
+client.messages
+    .on("chatMessage", (message, _, sender) => {
+        console.log(`${sender}: ${message}`);
+    });
+
+// Connect to the Archipelago server (replace url, slot name, and game as appropriate for your scenario).
+await client.login("wss://archipelago.gg:38281", "Phar", "Clique");
+
+// Send a message after connecting.
+client.messages.say("Hello, multiworld!")
+```
+
+Then, run this in your runtime of choice and see incoming messages print to console and your "Hello, multiworld!"
+message get broadcast to all clients (and back to yourself).
+
+## Listening for Server Events
+
+You can also listen for events, such as when your client receives items from the server:
+
+```js
+// Setup a listener for whenever items are received and log the details.
+client.items
+    .on("itemsReceived", (items) => {
+        for (const item of items) {
+            console.log(`Received item ${item} from player ${item.sender}.`);
+        }
+    });
+
+// ... misc client code below ...
+```
+
+Or if another player changes their alias:
+
+```js
+// Setup a listener for when a player's alias (name) changes.
+client.players
+    .on("aliasUpdated", (_, oldAlias, newAlias) => {
+        console.log(`${oldAlias} has changed their alias to ${newAlias}.`);
+    });
+
+// ... misc client code below ...
+```
+
+Or if you're using the DeathLink mechanic and another player dies:
+
+```js
+// Setup a listener for when another DeathLink player dies.
+client.deathLink
+    .on("deathReceived", (source, time, cause) => {
+        if (cause) {
+            console.log(`DeathLink received from ${source}: ${cause}`);
+            return;
+        }
+
+        // No cause was supplied.
+        console.log(`DeathLink received from ${source}!`);
+    });
+
+// ... misc client code below ...
+```
+
+## Sending Client Events
+
+You can also inform the server of actions you take as a client, such as checking locations:
+
+```js
+// Mark a list of location ids as checked.
+client.check(1001, 1002, 1003);
+```
+
+Updating keys in the data storage:
+
+```js
+// Add 1 to a data storage key.
+client.storage
+    .prepare("my_key", 0) /* 0 is the default if the key doesn't exist yet. */
+    .add(1)
+    .commit() // Commit changes.
+```
+
+Or sending your own DeathLinks to other players if you die.
+
+```js
+// Send a DeathLink to all DeathLink enabled players.
+client.deathLink.sendDeathLink("Phar", "Phar spontanously combusted after pressing a large red button.");
+```
+
+## Conclusion
+
+Congratulations! You are now a client developer and hopefully got a taste of what this library is capable of. For more
+information, check out the rest of the API documentation for **archipelago.js** (Client might be a good one to start
+with) and explore the available features.
+
+If you encounter any issues or have any questions, you can reach out on the GitHub repository for support, or in the
+[Archipelago Discord](https://discord.gg/8Z65BR2), specifically in this 
+[thread](https://discord.com/channels/731205301247803413/1127258929357934662) once you've joined. Thanks for checking
+out my little pet project for Archipelago!

package.json

@@ -1,6 +1,6 @@
 {
     "name": "archipelago.js",
-    "version": "2.0.0-rc4",
+    "version": "2.0.0-rc5",
     "description": "A runtime-agnostic and zero dependency TypeScript/JavaScript library for communicating with Archipelago servers.",
     "license": "MIT",
     "type": "module",
@@ -18,7 +18,7 @@
     },
     "scripts": {
         "build": "rimraf -rf dist && bun build.mjs",
-        "docs": "typedoc",
+        "docs": "typedoc --options typedoc.json",
         "lint": "eslint src",
         "pack": "pnpm pack --pack-destination packs"
     },

src/api/operations.ts → src/api/DataStorageOperations.ts

@@ -1,4 +1,4 @@
-import { JSONSerializableData } from "./types.ts";
+import { JSONSerializable } from "./types.ts";
 
 /**
  * Sets the current value of the key to `value`.
@@ -9,7 +9,7 @@ export type ReplaceDataStorageOperation = {
     readonly operation: "replace"
 
     /** A value for the operation to apply against the current data storage value. */
-    readonly value: JSONSerializableData
+    readonly value: JSONSerializable
 };
 
 /**
@@ -35,7 +35,7 @@ export type AddDataStorageOperation = {
     readonly operation: "add"
 
     /** A value for the operation to apply against the current data storage value. */
-    readonly value: number | JSONSerializableData[]
+    readonly value: number | JSONSerializable[]
 };
 
 /**
@@ -191,7 +191,7 @@ export type RemoveDataStorageOperation = {
     readonly operation: "remove"
 
     /** A value for the operation to apply against the current data storage value. */
-    readonly value: JSONSerializableData
+    readonly value: JSONSerializable
 };
 
 /**
@@ -204,7 +204,7 @@ export type PopDataStorageOperation = {
     readonly operation: "pop"
 
     /** A value for the operation to apply against the current data storage value. */
-    readonly value: JSONSerializableData
+    readonly value: JSONSerializable
 };
 
 /**
@@ -217,7 +217,7 @@ export type UpdateDataStorageOperation = {
     readonly operation: "update"
 
     /** A value for the operation to apply against the current data storage value. */
-    readonly value: JSONSerializableData
+    readonly value: JSONSerializable
 };
 
 /**

src/api/index.ts

@@ -1,5 +1,5 @@
 export * from "./constants.ts";
-export * from "./operations.ts";
+export * from "./DataStorageOperations.ts";
+export * from "./JSONMessageParts.ts";
 export * from "./packets";
-export * from "./parts.ts";
 export * from "./types.ts";

src/api/packets/client/bounce.ts → src/api/packets/client/Bounce.ts

@@ -1,4 +1,4 @@
-import { JSONSerializableData } from "../../types.ts";
+import { JSONRecord } from "../../types.ts";
 
 /**
  * Sent by the client to be broadcast from the server to all connected clients that match any one of the filter
@@ -10,7 +10,7 @@ export interface BouncePacket {
     readonly cmd: "Bounce"
 
     /** Any data you want to send. */
-    readonly data: { [p: string]: JSONSerializableData }
+    readonly data: JSONRecord
 
     /** Optional. Games that should receive this message. */
     readonly games?: string[]

src/api/packets/client/get.ts → src/api/packets/client/Get.ts

@@ -1,4 +1,4 @@
-import { JSONSerializableData } from "../../types.ts";
+import { JSONSerializable } from "../../types.ts";
 
 /**
  * Sent by the client to request a single or multiple values from the server's data storage, see the {@link SetPacket}
@@ -10,7 +10,7 @@ import { JSONSerializableData } from "../../types.ts";
  *
  * - `_read_hints_{team}_{slot}`: {@link NetworkHint}[] - All hinted {@link NetworkHint} items relevant to the requested
  * player.
- * - `_read_slot_data_{slot}`: {@link JSONSerializableData} - `slot_data` belonging to the requested slot.
+ * - `_read_slot_data_{slot}`: {@link JSONSerializable} - `slot_data` belonging to the requested slot.
  * - `_read_item_name_groups_{game}`: `Record<string, string[]>` - An object of item groups and their members.
  * - `_read_location_name_groups_{game}`: `Record<string, string[]>` - An object of location groups and their
  * members.
@@ -26,5 +26,5 @@ export interface GetPacket {
     readonly keys: string[]
 
     /** Additional arguments to be returned in {@link RetrievedPacket}. */
-    readonly [p: string]: JSONSerializableData
+    readonly [p: string]: JSONSerializable
 }

src/api/packets/client/set.ts → src/api/packets/client/Set.ts

@@ -1,5 +1,5 @@
-import { DataStorageOperation } from "../../operations.ts";
-import { JSONSerializableData } from "../../types.ts";
+import { DataStorageOperation } from "../../DataStorageOperations.ts";
+import { JSONSerializable } from "../../types.ts";
 
 /**
  * Sent by the client to write data to the server's data storage, that data can then be shared across worlds or just
@@ -13,7 +13,7 @@ export interface SetPacket {
     readonly cmd: "Set"
 
     /** The default value to use in case the key has no value on the server. */
-    readonly default: JSONSerializableData
+    readonly default: JSONSerializable
 
     /** The key to manipulate. */
     readonly key: string
@@ -28,5 +28,5 @@ export interface SetPacket {
     readonly want_reply: boolean
 
     /** Additional arguments to be returned in {@link SetReplyPacket}. */
-    readonly [p: string]: JSONSerializableData
+    readonly [p: string]: JSONSerializable
 }