Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation tweaks post-API updates #142

Merged
merged 1 commit into from
Aug 31, 2023
Merged

Documentation tweaks post-API updates #142

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 14 additions & 14 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ To instantiate the Spaces SDK, create an [Ably client](https://ably.com/docs/get
import Spaces from '@ably-labs/spaces';
import { Realtime } from 'ably';

const client = new Realtime.Promise({key: "<API-key>", clientId: "<client-ID>"});
const client = new Realtime.Promise({ key: "<API-key>", clientId: "<client-ID>" });
const spaces = new Spaces(client);
```
You can use [basic authentication](https://ably.com/docs/auth/basic) i.e. the API Key directly for testing purposes, however it is strongly recommended that you use [token authentication](https://ably.com/docs/auth/token) in production environments.
Expand Down Expand Up @@ -107,7 +107,7 @@ space.subscribe('update', (spaceState) => {
});

// Enter a space, publishing an update event, including optional profile data
space.enter({
await space.enter({
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've added these everywhere in docs to make it clear these are async operations and can be waited upon

username: 'Claire Lemons',
avatar: 'https://slides-internal.com/users/clemons.png',
});
Expand Down Expand Up @@ -136,7 +136,7 @@ The following is an example event payload received by subscribers when a user en

## Space members

The `members` namespace within a Space is a client-side filtered listener optimized for building avatar stacks. Subscribe to members entering, leaving, being removed from the Space (after a timeout) or updating their profile information.
The `members` namespace contains methods dedicated to building avatar stacks. Subscribe to members entering, leaving, being removed from the Space (after a timeout) or updating their profile information.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wasn't a big fan of the wording here - I think it's not accurate and could lead to confusion (a listener is for an example a function passed to an event listener; that's not what the namespace is, just the subscribe method. I think also saying client-side filtered is quite unspecific, we should be more specific or leave out the implementation detail here, like I did above)


```ts
// Subscribe to all member events in a space
Expand Down Expand Up @@ -201,17 +201,17 @@ const othersMemberInfo = await space.members.getOthers();

## Member locations

The `locations` namespace within a Space is a client-side filtered listener optimized for building member locations which enable you to track where users are within an application. A location could be a form field, multiple cells in a spreadsheet or a slide in a slide deck editor.
The `locations` namespace contains methods dedicated to building member locations, enabling you to track where users are within an application. A location could be a form field, multiple cells in a spreadsheet or a slide in a slide deck editor.

```ts
// You need to enter a space before publishing your location
space.enter({
await space.enter({
username: 'Claire Lemons',
avatar: 'https://slides-internal.com/users/clemons.png',
});

// Publish your location based on the UI element selected
space.locations.set({ slide: '3', component: 'slide-title' });
await space.locations.set({ slide: '3', component: 'slide-title' });

// Subscribe to location events from all members in a space
space.locations.subscribe('update', (locationUpdate) => {
Expand Down Expand Up @@ -258,22 +258,22 @@ Member locations has methods to get the current snapshot of member state:

```ts
// Get a snapshot of all the member locations
const allLocations = space.locations.getAll();
const allLocations = await space.locations.getAll();

// Get a snapshot of my location
const myLocation = space.locations.getSelf();
const myLocation = await space.locations.getSelf();

// Get a snapshot of everyone else's locations
const othersLocations = space.locations.getOthers();
const othersLocations = await space.locations.getOthers();
```

## Live cursors

The `cursors` namespace within a Space is a client-side filtered listener optimized for building live cursors which allows you to track a member's pointer position updates across an application. Events can also include associated data, such as pointer attributes and the IDs of associated UI elements:
The `cursors` namespace contains methods dedicated to building live cursors, allowing you to track a member's pointer position updates across an application. Events can also include associated data, such as pointer attributes and the IDs of associated UI elements:

```ts
// You need to enter a space before publishing your cursor updates
space.enter({
await space.enter({
username: 'Claire Lemons',
avatar: 'https://slides-internal.com/users/clemons.png',
});
Expand Down Expand Up @@ -306,11 +306,11 @@ Member cursors has methods to get the current snapshot of member state:

```ts
// Get a snapshot of all the cursors
const allCursors = space.cursors.getAll();
const allCursors = await space.cursors.getAll();

// Get a snapshot of my cursor
const myCursor = space.cursors.getSelf();
const myCursor = await space.cursors.getSelf();

// Get a snapshot of everyone else's cursors
const othersCursors = space.cursors.getOthers();
const othersCursors = await space.cursors.getOthers();
```
18 changes: 9 additions & 9 deletions docs/class-definitions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -224,10 +224,10 @@ space.members.unsubscribe('leave');

#### getSelf()

Returns a Promise which resolves to the [SpaceMember](#spacemember) object relating to the local connection. Will resolve to `undefined` if the client hasn't entered the space yet.
Returns a Promise which resolves to the [SpaceMember](#spacemember) object relating to the local connection. Will resolve to `null` if the client hasn't entered the space yet.

```ts
type getSelf = () => Promise<SpaceMember | undefined>;
type getSelf = () => Promise<SpaceMember | null>;
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I made a separate PR to make sure we always return null from these get* methods #141

```

Example:
Expand Down Expand Up @@ -355,7 +355,7 @@ space.locations.unsubscribe('update');
Get location for self.

```ts
type getSelf = () => Promise<Location | undefined>;
type getSelf = () => Promise<Location>;
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Location, as defined in this file, already includes null in it's type definition

```

Example:
Expand Down Expand Up @@ -465,41 +465,41 @@ space.cursors.unsubscribe('update');
Get the last `CursorUpdate` object for self.

```ts
type getSelf = () => <CursorUpdate | undefined>;
type getSelf = () => Promise<CursorUpdate | null>;
```

Example:

```ts
const selfPosition = space.cursors.getSelf();
const selfPosition = await space.cursors.getSelf();
```

#### getAll()

Get the last `CursorUpdate` object for all the members.

```ts
type getAll = () => Record<ConnectionId, CursorUpdate>;
type getAll = () => Promise<Record<string, CursorUpdate | null>>;
```

Example:

```ts
const allLatestPositions = space.cursors.getAll();
const allLatestPositions = await space.cursors.getAll();
```

#### getOthers()

Get the last `CursorUpdate` object for everyone else but yourself.

```ts
type getOthers = () => Record<ConnectionId, CursorUpdate>;
type getOthers = () => Promise<Record<string, CursorUpdate | null>>;
```

Example:

```ts
const otherPositions = space.cursors.getOthers();
const otherPositions = await space.cursors.getOthers();
```

### Related types
Expand Down
6 changes: 3 additions & 3 deletions docs/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,13 +96,13 @@ space.unsubscribe();
To become a member of a space (and use the other APIs, like location or cursors) a client needs to enter a space.

```ts
space.enter();
await space.enter();
```

This method can take an optional object called `profileData` so that users can include convenient metadata to update an avatar stack, such as a username and profile picture.

```ts
space.enter({
await space.enter({
username: 'Claire Lemons',
avatar: 'https://slides-internal.com/users/clemons.png',
});
Expand All @@ -121,7 +121,7 @@ A leave event does not remove the member immediately from `space.members`. Inste
As with `enter`, you can update the `profileData` on leave:

```ts
space.leave({
await space.leave({
username: 'Claire Lemons',
avatar: 'https://slides-internal.com/users/inactive.png',
});
Expand Down
Loading