From 91d266290bf9eccd9566a50ebbf8936421aef0bf Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Mon, 25 Sep 2023 17:03:59 -0300 Subject: [PATCH] wip editing moving etc I have no idea whether this documentation is going to be _useful_. maybe that's outside the scope of this work. TODO move edits into earlier commit idea is to keep all documentation readable, by always saying when something has been moved elsewhere. that way we can ship in whatever state this stuff is in. --- docs_errors.txt | 25 ++-------------- src/Cursors.ts | 11 ++----- src/Locations.ts | 25 +++++++++------- src/Locks.ts | 29 +++++------------- src/Members.ts | 34 +++++++++++++++------- src/Space.ts | 6 +++- src/types.ts | 76 +++++++++++++++++++++++++++++++++++++++++++++++- 7 files changed, 132 insertions(+), 74 deletions(-) diff --git a/docs_errors.txt b/docs_errors.txt index df213b1e..615b4f70 100644 --- a/docs_errors.txt +++ b/docs_errors.txt @@ -1,4 +1,7 @@ +[warning] LockStatuses.Pending, defined in ./dist/mjs/types.d.ts, is referenced by LockStatus but not included in the documentation. +[warning] LockStatuses.Locked, defined in ./dist/mjs/types.d.ts, is referenced by LockStatus but not included in the documentation. +[warning] LockStatuses.Unlocked, defined in ./dist/mjs/types.d.ts, is referenced by LockStatus but not included in the documentation. [warning] LockAttributes, defined in ./dist/mjs/Locks.d.ts, is referenced by LockOptions.attributes but not included in the documentation. [warning] @ably/spaces, defined in ./dist/mjs/index.d.ts, does not have any documentation. [warning] Space.client, defined in ./dist/mjs/Space.d.ts, does not have any documentation. @@ -7,7 +10,6 @@ [warning] Space.channel, defined in ./dist/mjs/Space.d.ts, does not have any documentation. [warning] Space.locks, defined in ./dist/mjs/Space.d.ts, does not have any documentation. [warning] Space.name, defined in ./dist/mjs/Space.d.ts, does not have any documentation. -[warning] Space.enter.profileData, defined in ./dist/mjs/Space.d.ts, does not have any documentation. [warning] Space.updateProfileData.profileDataOrUpdateFn, defined in ./dist/mjs/Space.d.ts, does not have any documentation. [warning] Space.updateProfileData.profileDataOrUpdateFn.__type, defined in ./dist/mjs/Space.d.ts, does not have any documentation. [warning] Space.leave, defined in ./dist/mjs/Space.d.ts, does not have any documentation. @@ -56,13 +58,10 @@ [warning] Locations.off.K, defined in ./dist/mjs/utilities/EventEmitter.d.ts, does not have any documentation. [warning] Locations.listeners.K, defined in ./dist/mjs/utilities/EventEmitter.d.ts, does not have any documentation. [warning] Locations.once.K, defined in ./dist/mjs/utilities/EventEmitter.d.ts, does not have any documentation. -[warning] LocationsEventMap, defined in ./dist/mjs/Locations.d.ts, does not have any documentation. [warning] LocationsEventMap.update, defined in ./dist/mjs/Locations.d.ts, does not have any documentation. [warning] LocationsEvents, defined in ./dist/mjs/Locations.d.ts, does not have any documentation. [warning] LocationsEvents.UpdateEvent, defined in ./dist/mjs/Locations.d.ts, does not have any documentation. [warning] LocationsEvents.UpdateEvent.member, defined in ./dist/mjs/Locations.d.ts, does not have any documentation. -[warning] LocationsEvents.UpdateEvent.currentLocation, defined in ./dist/mjs/Locations.d.ts, does not have any documentation. -[warning] LocationsEvents.UpdateEvent.previousLocation, defined in ./dist/mjs/Locations.d.ts, does not have any documentation. [warning] Locks.get.id, defined in ./dist/mjs/Locks.d.ts, does not have any documentation. [warning] Locks.acquire.id, defined in ./dist/mjs/Locks.d.ts, does not have any documentation. [warning] Locks.acquire.opts, defined in ./dist/mjs/Locks.d.ts, does not have any documentation. @@ -91,29 +90,11 @@ [warning] Members.off.K, defined in ./dist/mjs/utilities/EventEmitter.d.ts, does not have any documentation. [warning] Members.listeners.K, defined in ./dist/mjs/utilities/EventEmitter.d.ts, does not have any documentation. [warning] Members.once.K, defined in ./dist/mjs/utilities/EventEmitter.d.ts, does not have any documentation. -[warning] MembersEventMap, defined in ./dist/mjs/Members.d.ts, does not have any documentation. -[warning] MembersEventMap.leave, defined in ./dist/mjs/Members.d.ts, does not have any documentation. -[warning] MembersEventMap.enter, defined in ./dist/mjs/Members.d.ts, does not have any documentation. -[warning] MembersEventMap.update, defined in ./dist/mjs/Members.d.ts, does not have any documentation. [warning] MembersEventMap.updateProfile, defined in ./dist/mjs/Members.d.ts, does not have any documentation. -[warning] MembersEventMap.remove, defined in ./dist/mjs/Members.d.ts, does not have any documentation. -[warning] CursorPosition.x, defined in ./dist/mjs/types.d.ts, does not have any documentation. -[warning] CursorPosition.y, defined in ./dist/mjs/types.d.ts, does not have any documentation. -[warning] CursorUpdate.clientId, defined in ./dist/mjs/types.d.ts, does not have any documentation. -[warning] CursorUpdate.connectionId, defined in ./dist/mjs/types.d.ts, does not have any documentation. -[warning] CursorUpdate.position, defined in ./dist/mjs/types.d.ts, does not have any documentation. -[warning] CursorUpdate.data, defined in ./dist/mjs/types.d.ts, does not have any documentation. -[warning] ProfileData, defined in ./dist/mjs/types.d.ts, does not have any documentation. [warning] SpaceMember.lastEvent.__type, defined in ./dist/mjs/types.d.ts, does not have any documentation. [warning] SpaceMember.lastEvent.__type.name, defined in ./dist/mjs/types.d.ts, does not have any documentation. [warning] SpaceMember.lastEvent.__type.timestamp, defined in ./dist/mjs/types.d.ts, does not have any documentation. [warning] Lock.__type, defined in ./dist/mjs/types.d.ts, does not have any documentation. -[warning] Lock.__type.id, defined in ./dist/mjs/types.d.ts, does not have any documentation. -[warning] Lock.__type.status, defined in ./dist/mjs/types.d.ts, does not have any documentation. -[warning] Lock.__type.member, defined in ./dist/mjs/types.d.ts, does not have any documentation. -[warning] Lock.__type.timestamp, defined in ./dist/mjs/types.d.ts, does not have any documentation. -[warning] Lock.__type.attributes, defined in ./dist/mjs/types.d.ts, does not have any documentation. -[warning] Lock.__type.reason, defined in ./dist/mjs/types.d.ts, does not have any documentation. [warning] EventEmitter, defined in ./dist/mjs/utilities/EventEmitter.d.ts, does not have any documentation. [warning] EventEmitter.constructor, defined in ./dist/mjs/utilities/EventEmitter.d.ts, does not have any documentation. [warning] EventEmitter.constructor.T, defined in ./dist/mjs/utilities/EventEmitter.d.ts, does not have any documentation. diff --git a/src/Cursors.ts b/src/Cursors.ts index cfd12503..d02c005d 100644 --- a/src/Cursors.ts +++ b/src/Cursors.ts @@ -132,14 +132,9 @@ export default class Cursors extends EventEmitter { * ``` * The following are the properties of a cursor event payload: * - * | Property | Description | Type | - * |--------------|----------------------------------------------------------------------------------------------------|--------| - * | connectionId | The unique identifier of the member’s [connection](https://ably.com/docs/connect). | String | - * | clientId | The [client identifier](https://ably.com/docs/auth/identified-clients) for the member. | String | - * | position | An object containing the position of a member’s cursor. | Object | - * | position.x | The position of the member’s cursor on the X-axis. | Number | - * | position.y | The position of the member’s cursor on the Y-axis. | Number | - * | data | An optional arbitrary JSON-serializable object containing additional information about the cursor. | Object | + * > **Moved documentation** + * > + * > This documentation has been moved to {@link CursorUpdate} and {@link CursorPosition}. * * * diff --git a/src/Locations.ts b/src/Locations.ts index cb8c6443..84a9d1c9 100644 --- a/src/Locations.ts +++ b/src/Locations.ts @@ -15,11 +15,23 @@ import SpaceUpdate from './SpaceUpdate.js'; export namespace LocationsEvents { export interface UpdateEvent { member: SpaceMember; + /** + * + * The new location of the member. + */ currentLocation: unknown; + /** + * + * The previous location of the member. + */ previousLocation: unknown; } } +/** + * + * The property names of `LocationsEventMap` are the names of the events emitted by { @link Locations }. + */ export interface LocationsEventMap extends EventMap { update: LocationsEvents.UpdateEvent; } @@ -167,16 +179,9 @@ export default class Locations extends EventEmitter { * ``` * The following are the properties of a location event payload: * - * | Property | Description | Type | - * |----------------------------|-----------------------------------------------------------------------------------------------------------------------|---------| - * | member.clientId | The [client identifier](https://ably.com/docs/auth/identified-clients) for the member. | String | - * | member.connectionId | The unique identifier of the member’s [connection](https://ably.com/docs/connect). | String | - * | member.isConnected | Whether the member is connected to Ably or not. | Boolean | - * | member.lastEvent.name | The most recent [event](/spaces/avatar) emitted by the member. Will be one of {@link MembersEventMap.enter | `enter`}, {@link MembersEventMap.update | `update`}, {@link MembersEventMap.leave | `leave`} or {@link MembersEventMap.remove | `remove`}. | String | - * | member.lastEvent.timestamp | The timestamp of the most recently emitted event. | Number | - * | member.profileData | The optional [profile data](/spaces/avatar#profile-data) associated with the member. | Object | - * | previousLocation | The previous location of the member. | Object | - * | currentLocation | The new location of the member. | Object | + * > **Moved documentation** + * > + * > This documentation has been moved to { @link LocationsEvents.UpdateEvent }. * * > **Further reading** * > diff --git a/src/Locks.ts b/src/Locks.ts index ae38694d..62357d6e 100644 --- a/src/Locks.ts +++ b/src/Locks.ts @@ -55,14 +55,9 @@ export interface LocksEventMap extends EventMap { * * A lock will be in one of the following states: * - * `pending` - * A member has requested a lock by calling [`acquire()`](#acquire). - * - * `locked` - * The lock is confirmed to be held by the requesting member. - * - * `unlocked` - * The lock is confirmed to not be locked by the requesting member, or has been [released](#release) by a member previously holding the lock. + * > **Moved documentation** + * > + * > This documentation has been moved to { @link LockStatuses }. * * The following lock state transitions may occur: * @@ -458,19 +453,11 @@ export default class Locks extends EventEmitter { * ``` * The following are the properties of a lock event payload: * - * | Property | Description | Type | - * |----------------------------|------------------------------------------------------------------------------------------------------------------------------|-----------| - * | id | The unique ID of the lock request. | String | - * | status | The lock [status](#states) of the event. Will be either `locked` or `unlocked`. | String | - * | timestamp | The timestamp of the lock event. | Number | - * | attributes | The optional attributes of the lock, such as the ID of the component it relates to. | Object | - * | reason | The reason why the `request.status` is `unlocked`. | ErrorInfo | - * | member.clientId | The [client identifier](https://ably.com/docs/auth/identified-clients) for the member. | String | - * | member.connectionId | The unique identifier of the member’s [connection](https://ably.com/docs/connect). | String | - * | member.isConnected | Whether the member is connected to Ably or not. | Boolean | - * | member.lastEvent.name | The most recent [event](/spaces/avatar#events) emitted by the member. Will be one of `enter`, `update`, `leave` or `remove`. | String | - * | member.lastEvent.timestamp | The timestamp of the most recently emitted event. | Number | - * | member.profileData | The optional [profile data](/spaces/avatar#profile-data) associated with the member. | Object | + * > **Moved documentation** + * > + * > This documentation has been moved to { @link Lock }. + * + * * * * diff --git a/src/Members.ts b/src/Members.ts index 73f1921f..1e19bba1 100644 --- a/src/Members.ts +++ b/src/Members.ts @@ -11,11 +11,31 @@ import type { SpaceMember } from './types.js'; import type { PresenceMember } from './utilities/types.js'; import type Space from './Space.js'; +/** + * + * The property names of `MembersEventMap` are the names of the events emitted by { @link Members }. + */ export interface MembersEventMap extends EventMap { + /** + * + * A member has left the space. The member has either left explicitly by calling { @link Space.leave | `space.leave()` }, or has abruptly disconnected and not re-established a connection within 15 seconds. + */ leave: SpaceMember; + /** + * + * A new member has entered the space. The member has either entered explicitly by calling {@link Space.enter | `space.enter()` }, or has attempted to update their profile data before entering a space, which will instead emit an `enter` event. + */ enter: SpaceMember; + /** + * + * A member has updated their profile data by calling { @link Space.updateProfileData | `space.updateProfileData()` }. + */ update: SpaceMember; updateProfile: SpaceMember; + /** + * + * A member has been removed from the members list after the { @link SpaceOptions.offlineTimeout | `offlineTimeout` } period has elapsed. This enables members to appear greyed out in the avatar stack to indicate that they recently left for the period of time between their `leave` and `remove` events. + */ remove: SpaceMember; } @@ -29,17 +49,9 @@ export interface MembersEventMap extends EventMap { * * The following four event types are emitted by members: * - * `enter` - * A new member has entered the space. The member has either entered explicitly by calling [`space.enter()`](/spaces/space#enter), or has attempted to update their profile data before entering a space, which will instead emit an `enter` event. - * - * `update` - * A member has updated their profile data by calling [`space.updateProfileData()`](/spaces/space#update-profile). - * - * `leave` - * A member has left the space. The member has either left explicitly by calling [`space.leave()`](/spaces/space#leave), or has abruptly disconnected and not re-established a connection within 15 seconds. - * - * `remove` - * A member has been removed from the members list after the [`offlineTimeout`](/spaces/space#options) period has elapsed. This enables members to appear greyed out in the avatar stack to indicate that they recently left for the period of time between their `leave` and `remove` events. + * > **Moved documentation** + * > + * > This documentation has been moved to { @link MembersEventMap }. * * > **Note** * > diff --git a/src/Space.ts b/src/Space.ts index 8cdea2bd..7922a951 100644 --- a/src/Space.ts +++ b/src/Space.ts @@ -181,7 +181,9 @@ class Space extends EventEmitter { * * * - * Profile data can be set when [entering](#enter) a space. It is optional data that can be used to associate information with a member, such as a preferred username, or profile picture that can be subsequently displayed in their avatar. Profile data can be any arbitrary JSON-serializable object. + * > **Moved documentation** + * > + * > This documentation has been moved to { @link ProfileData }. * * Profile data is returned in the payload of all space events. * @@ -203,6 +205,8 @@ class Space extends EventEmitter { * type enter = (profileData?: Record) => Promise; * ``` * + * + * @param profileData Data to associate with the member who is entering the space. */ async enter(profileData: ProfileData = null): Promise { return new Promise((resolve) => { diff --git a/src/types.ts b/src/types.ts index 54f39ae2..6c66245f 100644 --- a/src/types.ts +++ b/src/types.ts @@ -39,7 +39,15 @@ export interface CursorsOptions { * */ export interface CursorPosition { + /** + * + * The position of the member’s cursor on the X-axis. + */ x: number; + /** + * + * The position of the member’s cursor on the Y-axis. + */ y: number; } @@ -70,9 +78,25 @@ export type CursorData = Record; * */ export interface CursorUpdate { + /** + * + * The [client identifier](https://ably.com/docs/auth/identified-clients) for the member. + */ clientId: string; + /** + * + * The unique identifier of the member’s [connection](https://ably.com/docs/connect). + */ connectionId: string; + /** + * + * An object containing the position of a member’s cursor. + */ position: CursorPosition; + /** + * + * An optional arbitrary JSON-serializable object containing additional information about the cursor. + */ data?: CursorData; } @@ -103,6 +127,10 @@ export interface SpaceOptions { cursors: CursorsOptions; } +/** + * + * Profile data can be set when {@link Space.enter | entering } a space. It is optional data that can be used to associate information with a member, such as a preferred username, or profile picture that can be subsequently displayed in their avatar. Profile data can be any arbitrary JSON-serializable object. + */ export type ProfileData = Record | null; /** @@ -163,6 +191,28 @@ export interface SpaceMember { }; } +/** + * + * The `LockStatuses` namespace describes the possible values of the {@link LockStatus} type. + */ +export namespace LockStatuses { + /** + * + * A member has requested a lock by calling { @link Locks.acquire | `acquire()` }. + */ + export type Pending = 'pending'; + /** + * + * The lock is confirmed to be held by the requesting member. + */ + export type Locked = 'locked'; + /** + * + * The lock is confirmed to not be locked by the requesting member, or has been { @link Locks.release | released } by a member previously holding the lock. + */ + export type Unlocked = 'unlocked'; +} + /** * * Represents a status of a lock. @@ -172,7 +222,7 @@ export interface SpaceMember { * ``` * */ -export type LockStatus = 'pending' | 'locked' | 'unlocked'; +export type LockStatus = LockStatuses.Pending | LockStatuses.Locked | LockStatuses.Unlocked; /** * @@ -191,10 +241,34 @@ export type LockStatus = 'pending' | 'locked' | 'unlocked'; * */ export type Lock = { + /** + * + * The unique ID of the lock request. + */ id: string; + /** + * + * The lock status of the event. + */ status: LockStatus; + /** + * + * Information about the space member who requested the lock. + */ member: SpaceMember; + /** + * + * The timestamp of the lock event. + */ timestamp: number; + /** + * + * The optional attributes of the lock, such as the ID of the component it relates to. + */ attributes?: LockAttributes; + /** + * + * The reason why the `request.status` is `unlocked`. + */ reason?: Types.ErrorInfo; };