From 32a70634e8ac56049ea61a1e3e9f16f16bdb7a38 Mon Sep 17 00:00:00 2001
From: wellwelwel <46850407+wellwelwel@users.noreply.github.com>
Date: Mon, 6 Jul 2026 21:59:36 -0300
Subject: [PATCH] docs: add `Set` and `Map` usage docs

---
 README.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/README.md b/README.md
index e1cb22d..71d092d 100644
--- a/README.md
+++ b/README.md
@@ -222,6 +222,15 @@ escape([
 // => '(1, 2, 3), (4, 5, 6)'
 ```
 
+#### Sets
+
+Sets are treated like arrays, turning into comma-separated lists with natural deduplication:
+
+```js
+escape(new Set([1, 2, 3]));
+// => '1, 2, 3'
+```
+
 ---
 
 ### escapeId
@@ -311,6 +320,27 @@ format('UPDATE users SET ?', [{ name: 'foo' }], true);
 // => "UPDATE users SET '[object Object]'"
 ```
 
+#### Maps in SET clauses
+
+Maps are treated like plain objects, preserving insertion order. In `SET` or `ON DUPLICATE KEY UPDATE` contexts, they are expanded into `key = value` pairs:
+
+```js
+format('UPDATE users SET ?', [
+  new Map([
+    ['name', 'foo'],
+    ['email', 'bar@test.com'],
+  ]),
+]);
+// => "UPDATE users SET `name` = 'foo', `email` = 'bar@test.com'"
+```
+
+Outside of `SET` or `ON DUPLICATE KEY UPDATE`, a `Map` is stringified as `'[object Map]'`, the same security measure applied to objects:
+
+```js
+format('SELECT * FROM users WHERE data = ?', [new Map([['id', 1]])]);
+// => "SELECT * FROM users WHERE data = '[object Map]'"
+```
+
 ---
 
 ### raw