Skip to content

Commit

Permalink
fixup! Update usage docs
Browse files Browse the repository at this point in the history
  • Loading branch information
surminus committed Aug 17, 2023
1 parent bda1754 commit 6da38d5
Showing 1 changed file with 85 additions and 49 deletions.
134 changes: 85 additions & 49 deletions docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,57 +85,24 @@ The following is an example of setting `offlineTimeout` to 3 minutes and a `pagi
const space = await spaces.get('demoSlideshow', { offlineTimeout: 180_000, cursors: { paginationLimit: 10 } });
```

## Members
### Subscribe to a space

Members is a core concept of the library. When you enter a space, you become a `member`. On the client, your own membership is to referred to as `self`. You can get your `self` by calling `space.members.getSelf()`. To get all the members (including self), call `space.members.getAll()`. These method will return (respectively an object and array of):
You can subscribe to events in a space:

```js
{
"clientId": "clemons#142",
"connectionId": "hd9743gjDc",
"isConnected": true,
"lastEvent": {
"name": "enter",
"timestamp": 1677595689759
},
"location": null,
"profileData": {
"username": "Claire Lemons",
"avatar": "https://slides-internal.com/users/clemons.png"
}
}
```ts
space.subscribe('update', (spaceState) => {
console.log(spaceState);
});
```

See [SpaceMember](/docs/class-definitions.md#spacemember) for details on properties.

### Listen to members updates
This gets triggered on [member](#members), [location](#location) and [cursor](#cursor) events.

The `space` instance is an `EventEmitter`. Events will be emitted for updates to members (including self). You can listen to the following events:

#### enter

Emitted when a member enters a space. Called with the member entering the space.

#### leave

Emitted when a member leaves a space. Called with the member leaving the space.

#### update

Emitted when a member profile updates a space. Called with the member updating the space.

#### all

Emitted when members enter, leave and their location is updated:
Similarly you can unsubscribe:

```ts
space.members.subscribe((membersUpdate) => {
console.log(membersUpdate);
});
space.unsubscribe();
```

To stop listening to member events, users can call the `space.members.unsubscribe()` method. See [Event emitters](#event-emitters) for options and usage.

### Enter a space

To become a member of a space (and use the other APIs, like location or cursors) a client needs to enter a space.
Expand Down Expand Up @@ -185,6 +152,75 @@ await space.updateProfileData((oldProfileData) => {
});
```

## Members

Members is a core concept of the library. When you enter a space, you become a `member`. On the client, your own membership is to referred to as `self`. You can get your `self` by calling `space.members.getSelf()`. To get all the members (including self), call `space.members.getAll()`. These method will return (respectively an object and array of):

```js
{
"clientId": "clemons#142",
"connectionId": "hd9743gjDc",
"isConnected": true,
"lastEvent": {
"name": "enter",
"timestamp": 1677595689759
},
"location": null,
"profileData": {
"username": "Claire Lemons",
"avatar": "https://slides-internal.com/users/clemons.png"
}
}
```

See [SpaceMember](/docs/class-definitions.md#spacemember) for details on properties.

### Member events

Subscribe to either `enter`, `leave` or `update` events related to members in a space.

#### enter

Emitted when a member enters a space. Called with the member entering the space.

```ts
space.members.subscribe('enter', (memberJoins) => {
console.log(memberJoins);
});
```

#### leave

Emitted when a member leaves a space. Called with the member leaving the space.

```ts
space.members.subscribe('leave', (memberLeft) => {
console.log(memberLeft);
});
```

#### update

Emitted when for any event in a space:


```ts
space.members.subscribe('update', (memberUpdate) => {
console.log(memberUpdate);
});
```

This is the same as not specifying the event:

```ts
space.members.subscribe((memberUpdate) => {
console.log(memberUpdate);
});
```

To stop listening to member events, users can call the `space.members.unsubscribe()` method. See [Event emitters](#event-emitters) for options and usage.


## Location

Each member can set a location for themselves:
Expand All @@ -197,10 +233,10 @@ A location does not have a prescribed shape. In your UI it can represent a singl

The location property will be set on the [member](#members).

Because locations are part of members, an `update` member event will be emitted when a member updates their location. When a member leaves, their location is set to `null`.
Because locations are part of members, a member event will be emitted when a member updates their location. When a member leaves, their location is set to `null`.

```ts
space.members.subscribe('update', (memberProfileUpdate) => {
space.subscribe('update', (memberProfileUpdate) => {
console.log(memberProfileUpdate);
});
```
Expand Down Expand Up @@ -326,19 +362,19 @@ const lastPositions = await space.cursors.getAll();
Calling `subscribe` with a single function argument will subscribe to all events on that emitter.

```ts
space.members.subscribe(() => {});
space.members.subscribe();
```

Calling `subscribe` with a named event and a function argument will subscribe to that event only.

```ts
space.members.subscribe(`update`, () => {});
space.members.subscribe(`enter`, () => {});
```

Calling `subscribe` with an array of named events and a function argument will subscribe to those events.

```ts
space.members.subscribe([`enter`, `update`], () => {});
space.members.subscribe([`enter`, `leave`], () => {});
```

Calling `unsubscribe` with no arguments will remove all registered listeners.
Expand All @@ -350,13 +386,13 @@ space.members.unsubscribe();
Calling `unsubscribe` with a single named event will remove all listeners registered for that event.

```ts
space.members.unsubscribe(`update`);
space.members.unsubscribe(`enter`);
```

Calling `unsubscribe` with an array of named events will remove all listeners registered for those events.

```ts
space.members.unsubscribe([`update`]);
space.members.unsubscribe([`enter`, `leave`]);
```

Calling `unsubscribe` and adding a listener function as the second argument to both of the above will remove only that listener.
Expand Down

0 comments on commit 6da38d5

Please sign in to comment.