docs: Document WebSocket behavior of computed properties

sekassel · Aug 2, 2024 · 9affce7 · 9affce7
1 parent 738a1e2
commit 9affce7
Show file tree

Hide file tree

Showing 3 changed files with 11 additions and 7 deletions.
diff --git a/docs/WebSocket.md b/docs/WebSocket.md
@@ -62,19 +62,19 @@ However, the payload within the `data` field may contain any JSON value, not jus
 The following table shows which events may be sent.
 Some events are only visible to certain users for privacy reasons.
 
-| Event Name                                                                 | Payload                                                                          | Visible to          | Note                                                          |
-|----------------------------------------------------------------------------|----------------------------------------------------------------------------------|---------------------|---------------------------------------------------------------|
+| Event Name                                                                 | Payload                                                                          | Visible to          | Note                                                  |
+|----------------------------------------------------------------------------|----------------------------------------------------------------------------------|---------------------|-------------------------------------------------------|
 | `users.<userId>.{created,updated,deleted}`<sup>1, 2</sup>                  | [`User`](#model-User)                                                            | Everyone            |
 | `users.<userId>.achievements.<id>.{created,updated,deleted}`               | [`Achievement`](#model-Achievement)                                              | Everyone            |
 | `users.<from>.friends.<to>.{created,updated,deleted}`                      | [`Friend`](#model-Friend)                                                        | `from` or `to` User |
-| `games.<gameId>.{created,updated,deleted}`                                 | [`Game`](#model-Game)                                                            | Everyone            |
-| `games.<gameId>.ticked`                                                    | [`Game`](#model-Game)                                                            | Everyone            | Sent when ticking the game, after the `updated` event         |
+| `games.<gameId>.{created,updated,deleted}`                                 | [`Game`](#model-Game)<sup>4</sup>                                                | Everyone            |
+| `games.<gameId>.ticked`                                                    | [`Game`](#model-Game)                                                            | Everyone            | Sent when ticking the game, after the `updated` event |
 | `games.<gameId>.members.<userId>.{created,updated,deleted}`                | [`Member`](#model-Member)                                                        | Everyone            |
 | `games.<gameId>.systems.<systemId>.{created,updated,deleted}`              | [`System`](#model-System)                                                        | Game Members        |
 | `games.<gameId>.empires.<empireId>.{created,updated,deleted}`              | [`Empire`](#model-Empire) or [`ReadEmpireDto`](#model-ReadEmpireDto)<sup>3</sup> | Game Members        |
 | `games.<gameId>.empires.<empireId>.jobs.<jobId>.{created,updated,deleted}` | [`Job`](#model-Empire)                                                           | The Empire          |
 | `games.<gameId>.wars.<warId>.{created,updated,deleted}`                    | [`War`](#model-War)                                                              | Game Members        |
-| `games.<gameId>.fleets.<fleetId>.{created,updated,deleted}`                | [`Fleet`](#model-Fleet)                                                          | Game Members        |
+| `games.<gameId>.fleets.<fleetId>.{created,updated,deleted}`                | [`Fleet`](#model-Fleet)<sup>4</sup>                                              | Game Members        |
 | `games.<gameId>.fleets.<fleetId>.ships.<shipId>.{created,updated,deleted}` | [`Ship`](#model-Ship)                                                            | Game Members        |
 
 <sup>1</sup>: The shorthand notation `foo.{bar,baz}` means "either `foo.bar` or `foo.baz`" **in this table**. You **cannot** use this notation to subscribe to or unsubscribe from events!
@@ -85,3 +85,6 @@ You can use this to subscribe to events that concern a single resource. If you d
 Similarly, to receive all events regarding the messages of a group, you could use the pattern `groups.507f191e810c19729de860ea.messages.*.*`.
 
 <sup>3</sup>: The user corresponding to the empire receives more information than other game members.
+
+<sup>4</sup>: Computed properties like `Game.members` and `Fleet.ships` do not trigger events when changed.
+Instead, you need to listen for `created` or `deleted` events of the respective child resources.
diff --git a/src/fleet/fleet.schema.ts b/src/fleet/fleet.schema.ts
@@ -44,7 +44,8 @@ export class Fleet extends GlobalSchema {
   location: Types.ObjectId;
 
   @ApiProperty({
-    description: 'The actual number of ships in this fleet.',
+    description: '(Computed property) The actual number of ships in this fleet.',
+    readOnly: true,
   })
   @IsNumber()
   ships: number;

diff --git a/src/game/game.schema.ts b/src/game/game.schema.ts
@@ -59,7 +59,7 @@ export class Game extends GlobalSchema {
   owner: Types.ObjectId;
 
   @ApiProperty({
-    description: 'The number of members in the game.',
+    description: '(Computed property) The number of members in the game.',
     type: 'integer',
     readOnly: true,
   })