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; };