feat: add IRCv3 capabilities, WHO/WHOX, MONITOR and message splitting

README.md

@@ -12,8 +12,8 @@ talk with IRC servers.
 
 - **Cross-runtime** — runs on Deno and Node.js with the same API
 - **Fully typed** — events, commands and state are inferred from TypeScript, no guessing
-- **Plugin architecture** — 40+ built-in plugins (SASL, DCC, CTCP, reconnect, flood control...)
-- **TLS & SASL** — PLAIN, EXTERNAL (client certificates), NickServ fallback
+- **Plugin architecture** — 50+ built-in plugins (SASL, DCC, CTCP, reconnect, flood control...)
+- **IRCv3** — server-time, echo-message, message-tags, MONITOR, SASL, and [more](API.md#ircv3-support)
 - **Zero dependencies** — no external runtime dependencies
 
 Any feedback and contributions are welcome.

core/client.ts

@@ -1,7 +1,7 @@
 import { type ClientError, type ErrorArgs, toClientError } from "./errors.ts";
 import { EventEmitter, type EventEmitterOptions } from "./events.ts";
 import { Hooks } from "./hooks.ts";
-import { Parser, type Raw } from "./parsers.ts";
+import { escapeTagValue, Parser, type Raw } from "./parsers.ts";
 import { loadPlugins, type Plugin } from "./plugins.ts";
 import {
   type AnyCommand,
@@ -260,7 +260,30 @@ export class CoreClient<
   async send(
     command: AnyRawCommand,
     ...params: (string | undefined)[]
-  ): Promise<string | null> {
+  ): Promise<string | null>;
+
+  /** Sends a raw message with IRCv3 tags to the server. */
+  async send(
+    tags: Record<string, string | undefined>,
+    command: AnyRawCommand,
+    ...params: (string | undefined)[]
+  ): Promise<string | null>;
+
+  // deno-lint-ignore no-explicit-any
+  async send(first: any, ...rest: any[]): Promise<string | null> {
+    let tags: Record<string, string | undefined> | undefined;
+    let command: AnyRawCommand;
+    let params: (string | undefined)[];
+
+    if (typeof first === "object") {
+      tags = first;
+      command = rest.shift();
+      params = rest;
+    } else {
+      command = first;
+      params = rest;
+    }
+
     if (this.conn === null) {
       this.emitError("write", "Unable to send message", this.send);
       return null;
@@ -280,8 +303,18 @@ export class CoreClient<
       params[last] = ":" + params[last];
     }
 
+    // Encodes tags prefix.
+    let tagStr = "";
+    if (tags) {
+      tagStr = "@" + Object.entries(tags)
+        .map(([k, v]) => v !== undefined ? `${k}=${escapeTagValue(v)}` : k)
+        .join(";") +
+        " ";
+    }
+
     // Prepares and encodes raw message.
-    const raw = (command + " " + params.join(" ")).trimEnd() + "\r\n";
+    const raw = tagStr +
+      (command + " " + params.join(" ")).trimEnd() + "\r\n";
     const bytes = this.encoder.encode(raw);
 
     try {

core/client_test.ts

@@ -91,6 +91,59 @@ describe("core/client", (test) => {
     ]);
   });
 
+  test("send raw message with tags", async () => {
+    const { client, server } = mock();
+
+    await client.connect("host");
+
+    client.send({ "+typing": "active" }, "TAGMSG", "#channel");
+    const raw = server.receive();
+
+    assertEquals(raw, ["@+typing=active TAGMSG #channel"]);
+  });
+
+  test("send raw message with tags and value escaping", async () => {
+    const { client, server } = mock();
+
+    await client.connect("host");
+
+    client.send({ "+msg": "hello world" }, "TAGMSG", "#channel");
+    const raw = server.receive();
+
+    assertEquals(raw, ["@+msg=hello\\sworld TAGMSG #channel"]);
+  });
+
+  test("send raw message with tag without value", async () => {
+    const { client, server } = mock();
+
+    await client.connect("host");
+
+    client.send({ "+typing": undefined }, "TAGMSG", "#channel");
+    const raw = server.receive();
+
+    assertEquals(raw, ["@+typing TAGMSG #channel"]);
+  });
+
+  test("send raw message with multiple tags", async () => {
+    const { client, server } = mock();
+
+    await client.connect("host");
+
+    client.send(
+      { "+reply": "msgid123", "+typing": "active" },
+      "PRIVMSG",
+      "#channel",
+      "hello",
+    );
+    const raw = server.receive();
+
+    assertEquals(raw.length, 1);
+    assertEquals(raw[0].startsWith("@"), true);
+    assertEquals(raw[0].includes("+reply=msgid123"), true);
+    assertEquals(raw[0].includes("+typing=active"), true);
+    assertEquals(raw[0].includes("PRIVMSG #channel hello"), true);
+  });
+
   test("fail to send raw message if not connected", async () => {
     const { client } = mock();
 

core/parsers.ts

@@ -62,6 +62,48 @@ export function parseSource(prefix: string): Source {
   return source;
 }
 
+const UNESCAPE_MAP: Record<string, string> = {
+  ":": ";",
+  "s": " ",
+  "\\": "\\",
+  "r": "\r",
+  "n": "\n",
+};
+
+/** Decodes IRCv3 tag value escaping. */
+export function unescapeTagValue(value: string): string {
+  if (value.indexOf("\\") === -1) return value;
+  let result = "";
+  for (let i = 0; i < value.length; i++) {
+    if (value[i] === "\\" && i + 1 < value.length) {
+      result += UNESCAPE_MAP[value[++i]] ?? value[i];
+    } else {
+      result += value[i];
+    }
+  }
+  return result;
+}
+
+/** Encodes a string as an IRCv3 tag value. */
+export function escapeTagValue(value: string): string {
+  return value.replace(/[; \\\r\n]/g, (c) => {
+    switch (c) {
+      case ";":
+        return "\\:";
+      case " ":
+        return "\\s";
+      case "\\":
+        return "\\\\";
+      case "\r":
+        return "\\r";
+      case "\n":
+        return "\\n";
+      default:
+        return c;
+    }
+  });
+}
+
 // The following is called on each received raw message
 // and must favor performance over readability.
 function parseMessage(raw: string): Raw {
@@ -80,8 +122,10 @@ function parseMessage(raw: string): Raw {
     while (start < end) {
       let pos = raw.indexOf(";", start);
       if (pos === -1) pos = end;
-      const [key, value] = raw.slice(start, pos).split("=");
-      msg.tags[key] = value;
+      const [key, rawValue] = raw.slice(start, pos).split("=");
+      msg.tags[key] = rawValue !== undefined
+        ? unescapeTagValue(rawValue)
+        : undefined;
       start = pos + 1;
     }
   }

core/parsers_test.ts

@@ -1,6 +1,6 @@
 import { assertEquals } from "@std/assert";
 import { describe } from "../testing/helpers.ts";
-import { Parser } from "./parsers.ts";
+import { escapeTagValue, Parser, unescapeTagValue } from "./parsers.ts";
 
 describe("core/parsers", (test) => {
   test("parse message without prefix", () => {
@@ -61,6 +61,94 @@ describe("core/parsers", (test) => {
     }]);
   });
 
+  test("parse message with tags but no source", () => {
+    const parser = new Parser();
+
+    const msg = Array.from(
+      parser.parseMessages("@time=2026-03-24T12:00:00Z PING :server\r\n"),
+    );
+
+    assertEquals(msg, [{
+      command: "ping",
+      params: ["server"],
+      tags: { "time": "2026-03-24T12:00:00Z" },
+    }]);
+  });
+
+  test("parse message with empty tag value", () => {
+    const parser = new Parser();
+
+    const msg = Array.from(
+      parser.parseMessages("@key= :nick!u@h PRIVMSG #chan :text\r\n"),
+    );
+
+    assertEquals(msg[0].tags, { "key": "" });
+  });
+
+  test("parse message with multiple escaped tags", () => {
+    const parser = new Parser();
+
+    const msg = Array.from(
+      parser.parseMessages(
+        "@a=1\\s2;b=x\\:y;c :nick!u@h PRIVMSG #chan :text\r\n",
+      ),
+    );
+
+    assertEquals(msg[0].tags, { "a": "1 2", "b": "x;y", "c": undefined });
+  });
+
+  test("parse tags split across chunks", () => {
+    const parser = new Parser();
+
+    const raw1 = Array.from(
+      parser.parseMessages("@time=2026-03-24T12:00:00Z :nick!u@h PRI"),
+    );
+    assertEquals(raw1, []);
+
+    const raw2 = Array.from(
+      parser.parseMessages("VMSG #chan :hello\r\n"),
+    );
+    assertEquals(raw2.length, 1);
+    assertEquals(raw2[0].tags, { "time": "2026-03-24T12:00:00Z" });
+    assertEquals(raw2[0].params, ["#chan", "hello"]);
+  });
+
+  test("parse message with escaped tag values", () => {
+    const parser = new Parser();
+
+    const msg = Array.from(
+      parser.parseMessages(
+        "@msg=hello\\sworld\\:test\\\\end :nick!u@h PRIVMSG #chan :text\r\n",
+      ),
+    );
+
+    assertEquals(msg[0].tags, { "msg": "hello world;test\\end" });
+  });
+
+  test("unescape tag values", () => {
+    assertEquals(unescapeTagValue("hello\\sworld"), "hello world");
+    assertEquals(unescapeTagValue("a\\:b"), "a;b");
+    assertEquals(unescapeTagValue("a\\\\b"), "a\\b");
+    assertEquals(unescapeTagValue("a\\rb"), "a\rb");
+    assertEquals(unescapeTagValue("a\\nb"), "a\nb");
+    assertEquals(unescapeTagValue("no\\escape"), "noescape");
+    assertEquals(unescapeTagValue("plain"), "plain");
+  });
+
+  test("escape tag values", () => {
+    assertEquals(escapeTagValue("hello world"), "hello\\sworld");
+    assertEquals(escapeTagValue("a;b"), "a\\:b");
+    assertEquals(escapeTagValue("a\\b"), "a\\\\b");
+    assertEquals(escapeTagValue("a\rb"), "a\\rb");
+    assertEquals(escapeTagValue("a\nb"), "a\\nb");
+    assertEquals(escapeTagValue("plain"), "plain");
+  });
+
+  test("roundtrip tag escape/unescape", () => {
+    const original = "hello world;semi\\backslash\r\n";
+    assertEquals(unescapeTagValue(escapeTagValue(original)), original);
+  });
+
   test("parse chunks of raw messages", () => {
     const parser = new Parser();
 

core/protocol.ts

@@ -1,8 +1,10 @@
 const COMMANDS = {
   "ADMIN": "admin",
   "AUTHENTICATE": "authenticate",
+  "ACCOUNT": "account",
   "AWAY": "away",
   "CAP": "cap",
+  "CHGHOST": "chghost",
   "CONNECT": "connect",
   "ERROR": "error",
   "INFO": "info",
@@ -13,6 +15,7 @@ const COMMANDS = {
   "LINKS": "links",
   "LIST": "list",
   "MODE": "mode",
+  "MONITOR": "monitor",
   "MOTD": "motd",
   "NICK": "nick",
   "NAMES": "names",
@@ -24,7 +27,9 @@ const COMMANDS = {
   "PONG": "pong",
   "PRIVMSG": "privmsg",
   "QUIT": "quit",
+  "SETNAME": "setname",
   "STATS": "stats",
+  "TAGMSG": "tagmsg",
   "TIME": "time",
   "TOPIC": "topic",
   "TRACE": "trace",
@@ -167,6 +172,10 @@ const REPLIES = {
   "394": "rpl_endofusers",
   "395": "rpl_nousers",
   "396": "rpl_hosthidden",
+  "730": "rpl_mononline",
+  "731": "rpl_monoffline",
+  "732": "rpl_monlist",
+  "733": "rpl_endofmonlist",
   "900": "rpl_loggedin",
   "901": "rpl_loggedout",
   "903": "rpl_saslsuccess",
@@ -266,6 +275,7 @@ const ERRORS = {
   "550": "err_badhostmask",
   "551": "err_hostunavail",
   "552": "err_usingsline",
+  "734": "err_monlistfull",
   "902": "err_nicklocked",
   "904": "err_saslfail",
   "905": "err_sasltoolong",