From 61c6c95563d5cc494e780ab1e6885fd06a554236 Mon Sep 17 00:00:00 2001
From: Ned Grady <gradyned@gmail.com>
Date: Wed, 31 Jan 2024 22:06:32 +0000
Subject: [PATCH 1/3] docs: add warning regarding using socket.data reference
 equality

Related: https://github.com/socketio/socket.io/discussions/4935
---
 .../02-Server/server-socket-instance.md       | 33 +++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/docs/categories/02-Server/server-socket-instance.md b/docs/categories/02-Server/server-socket-instance.md
index ec8a4c84..40472141 100644
--- a/docs/categories/02-Server/server-socket-instance.md
+++ b/docs/categories/02-Server/server-socket-instance.md
@@ -140,6 +140,39 @@ console.log(sockets[0].data.username); // "alice"
 
 More information [here](server-instance.md#utility-methods).
 
+:::caution
+Do not rely on reference equality when using properties of `data`.
+:::
+
+```js
+// BAD
+const activeUsers = new Set();
+io.on("connection", (socket) => {
+  socket.data.user = { name: "alice" };
+  activeUsers.add(socket.data.user);
+
+  socket.on("disconnect", () => {
+    // Socket.IO makes no guarentee data.user will reference the same object...
+    activeUsers.delete(socket.data.user);
+  });
+});
+```
+
+```js
+// GOOD
+const activeUsers = Map();
+io.on("connection", (socket) => {
+  const newUser = { name: "alice" };
+  socket.data.user = newUser;
+  activeUsers.set(socket.data.user.name, newUser);
+
+  socket.on("disconnect", () => {
+    // ... however primitive values will be preserved
+    activeUsers.delete(socket.data.user.name);
+  });
+});
+```
+
 ## Socket#conn
 
 A reference to the underlying Engine.IO socket (see [here](../01-Documentation/how-it-works.md)).

From 33606acfbd36bf604b5581e33dbfafa1bb06ebd6 Mon Sep 17 00:00:00 2001
From: Ned Grady <gradyned@gmail.com>
Date: Thu, 1 Feb 2024 09:40:04 +0000
Subject: [PATCH 2/3] Fix typo

---
 docs/categories/02-Server/server-socket-instance.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/categories/02-Server/server-socket-instance.md b/docs/categories/02-Server/server-socket-instance.md
index 40472141..2fd193d3 100644
--- a/docs/categories/02-Server/server-socket-instance.md
+++ b/docs/categories/02-Server/server-socket-instance.md
@@ -152,7 +152,7 @@ io.on("connection", (socket) => {
   activeUsers.add(socket.data.user);
 
   socket.on("disconnect", () => {
-    // Socket.IO makes no guarentee data.user will reference the same object...
+    // Socket.IO makes no guarantee data.user will reference the same object...
     activeUsers.delete(socket.data.user);
   });
 });

From 97687a764f64c9a869d136c487716eeb448bab89 Mon Sep 17 00:00:00 2001
From: Ned Grady <gradyned@gmail.com>
Date: Fri, 2 Feb 2024 21:16:10 +0000
Subject: [PATCH 3/3] Remove bad 'good' example.

---
 .../02-Server/server-socket-instance.md           | 15 ---------------
 1 file changed, 15 deletions(-)

diff --git a/docs/categories/02-Server/server-socket-instance.md b/docs/categories/02-Server/server-socket-instance.md
index 2fd193d3..7f55d68b 100644
--- a/docs/categories/02-Server/server-socket-instance.md
+++ b/docs/categories/02-Server/server-socket-instance.md
@@ -158,21 +158,6 @@ io.on("connection", (socket) => {
 });
 ```
 
-```js
-// GOOD
-const activeUsers = Map();
-io.on("connection", (socket) => {
-  const newUser = { name: "alice" };
-  socket.data.user = newUser;
-  activeUsers.set(socket.data.user.name, newUser);
-
-  socket.on("disconnect", () => {
-    // ... however primitive values will be preserved
-    activeUsers.delete(socket.data.user.name);
-  });
-});
-```
-
 ## Socket#conn
 
 A reference to the underlying Engine.IO socket (see [here](../01-Documentation/how-it-works.md)).