feat!: add Node.js 20+ compatibility via runtime abstraction layer

Isolate all Deno-specific code behind a runtime/ adapter so the library
works on both Deno and Node.js (via JSR). Same test suite runs on both
runtimes using Deno.test and node:test natively.

BREAKING CHANGE: connect() returns Conn instead of Deno.Conn.

Author: jeromeludmann

.github/workflows/ci.yml

@@ -39,11 +39,39 @@ jobs:
         run: deno task test
 
   e2e:
-    name: e2e
+    name: e2e (deno)
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: denoland/setup-deno@v2
         with:
           deno-version: v2.x
       - run: deno task test:e2e
+
+  test-node:
+    name: tests node (${{ matrix.node-version }})
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [20, 22]
+      fail-fast: true
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm install
+      - run: npm test
+
+  e2e-node:
+    name: e2e (node)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm install
+      - run: npm run test:e2e

.gitignore

@@ -1,3 +1,4 @@
 coverage
+node_modules
 .vscode
 .zed

.npmrc

@@ -0,0 +1 @@
+@jsr:registry=https://npm.jsr.io

API.md

@@ -1295,7 +1295,7 @@ Default port to `6667`.
 
 Resolves when connected.
 
-`async connect(hostname: string, options?: ConnectOptions): Promise<Deno.Conn | null>`
+`async connect(hostname: string, options?: ConnectOptions): Promise<Conn | null>`
 
 ```ts
 client.connect("irc.libera.chat");
@@ -1315,9 +1315,9 @@ client.connect("irc.libera.chat", {
 client.connect("irc.libera.chat", {
   port: 6697,
   tls: true,
-  cert: Deno.readTextFileSync("client.pem"),
-  key: Deno.readTextFileSync("client-key.pem"),
-  caCerts: [Deno.readTextFileSync("ca.pem")],
+  cert: certContent,
+  key: keyContent,
+  caCerts: [caContent],
 });
 ```
 

CONTRIBUTING.md

@@ -14,7 +14,8 @@ feature implementations to decoupled _plugins_ parts.
 
 The core contains some internal parts related to IRC protocol, TCP sockets and
 event system. Plugins contain all the extra features built on top of the core
-client.
+client. Runtime-specific code (Deno, Node.js) is isolated in the `runtime/`
+directory behind a common interface.
 
 In most of the cases, it is quite handy to add new features using plugins
 without touching the core.
@@ -26,13 +27,18 @@ All added parts (core and plugins):
 
 ## Development
 
-Prerequisites: [Deno](https://deno.land/) v2.x
+Prerequisites:
 
-Run `deno task` to see all available commands. Key tasks:
+- [Deno](https://deno.land/) 2+
+- [Node.js](https://nodejs.org/) 20+ (for cross-runtime testing)
 
-- `deno task test` — run unit tests
+Run `deno task` to see all available Deno commands. Key tasks:
+
+- `deno task test` — run unit tests (Deno)
 - `deno task lint` — lint the codebase
 - `deno task fmt` — format the codebase
+- `npm test` — run unit tests (Node.js)
+- `npm run test:e2e` — run E2E tests (Node.js)
 
 ## Releasing (maintainers)
 

README.md

@@ -1,13 +1,24 @@
 # deno-irc
 
 ![ci](https://github.com/jeromeludmann/deno-irc/workflows/ci/badge.svg)
+[![JSR](https://jsr.io/badges/@irc/client)](https://jsr.io/@irc/client)
 
-IRC client protocol module for [Deno](https://deno.land/) which aims to provide
-an easy way to talk with IRC servers.
+IRC client protocol module for [Deno](https://deno.land/) 2+ and
+[Node.js](https://nodejs.org/) 20+ which aims to provide an easy way to
+talk with IRC servers.
+
+> **New:** Node.js is now officially supported. Install via
+> `npx jsr add @irc/client` and use the same API as on Deno.
+
+- **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
+- **Zero dependencies** — no external runtime dependencies
 
 Any feedback and contributions are welcome.
 
-Now available on [JSR](https://jsr.io/@irc/client).
+Available on [JSR](https://jsr.io/@irc/client).
 
 ## Documentation
 
@@ -16,19 +27,27 @@ Now available on [JSR](https://jsr.io/@irc/client).
 
 ## Getting Started
 
-The first thing to do is to import the `Client`:
+### Installation
+
+**Deno:**
 
 ```ts
 import { Client } from "jsr:@irc/client";
 ```
 
-Alternatively, you can use the `deno.land/x` registry:
+**Node.js:**
+
+```sh
+npx jsr add @irc/client
+```
 
 ```ts
-import { Client } from "https://deno.land/x/irc/mod.ts";
+import { Client } from "@irc/client";
 ```
 
-and just instantiate a new client like this:
+### Usage
+
+Instantiate a new client like this:
 
 ```ts
 const client = new Client({
@@ -60,7 +79,7 @@ await client.connect("irc.libera.chat");
 await client.connect("irc.libera.chat", { port: 6697, tls: true });
 ```
 
-Note that connecting to servers requires the `--allow-net` option:
+When using Deno, connecting to servers requires the `--allow-net` permission:
 
 ```
 deno run --allow-net ./code.ts

core/client.ts

@@ -10,6 +10,8 @@ import {
   type AnyReply,
   PROTOCOL,
 } from "./protocol.ts";
+import type { Conn, Runtime } from "../runtime/types.ts";
+import { getRuntime } from "../runtime/mod.ts";
 
 type AnyRawEventName = `raw:${AnyCommand | AnyReply | AnyError}`;
 
@@ -81,28 +83,15 @@ export interface RemoteAddr {
 /** Network address exposed in events — without sensitive fields (cert/key). */
 export type PublicAddr = Omit<RemoteAddr, "cert" | "key">;
 
-/** How to connect to a server */
-interface ConnectImpl {
-  noTls(opts: Deno.ConnectOptions): Promise<Deno.Conn>;
-  withTls(
-    opts:
-      | Deno.ConnectTlsOptions
-      | (Deno.ConnectTlsOptions & Deno.TlsCertifiedKeyPem),
-  ): Promise<Deno.Conn>;
-}
-
 /** Low-level IRC client handling TCP connection, raw message parsing, and event dispatching. */
 export class CoreClient<
   TEvents extends CoreFeatures["events"] = CoreFeatures["events"],
 > extends EventEmitter<TEvents> {
   readonly state: CoreFeatures["state"];
   readonly utils: CoreFeatures["utils"];
 
-  protected connectImpl: ConnectImpl = {
-    noTls: Deno.connect,
-    withTls: Deno.connectTls,
-  };
-  protected conn: Deno.Conn | null = null;
+  protected runtime: Runtime | null = null;
+  protected conn: Conn | null = null;
   protected hooks: Hooks<CoreClient<TEvents>> = new Hooks<CoreClient<TEvents>>(
     this,
   );
@@ -148,26 +137,28 @@ export class CoreClient<
   async connect(
     hostname: string,
     options: ConnectOptions = {},
-  ): Promise<Deno.Conn | null> {
+  ): Promise<Conn | null> {
+    if (!this.runtime) {
+      this.runtime = await getRuntime();
+    }
+
     const { port = PORT } = options;
     const tls = options.tls ?? false;
 
     let tlsFields: { cert?: string; key?: string; caCerts?: string[] } = {};
     if (options.tls) {
-      const o = options as {
-        cert?: string;
-        key?: string;
-        caCerts?: string[];
-        certFile?: string;
-        keyFile?: string;
-        caCertFile?: string;
-      };
-      const cert = o.cert ??
-        (o.certFile ? Deno.readTextFileSync(o.certFile) : undefined);
-      const key = o.key ??
-        (o.keyFile ? Deno.readTextFileSync(o.keyFile) : undefined);
-      const caCerts = o.caCerts ??
-        (o.caCertFile ? [Deno.readTextFileSync(o.caCertFile)] : undefined);
+      const cert = options.cert ??
+        (options.certFile
+          ? this.runtime.readTextFileSync(options.certFile)
+          : undefined);
+      const key = options.key ??
+        (options.keyFile
+          ? this.runtime.readTextFileSync(options.keyFile)
+          : undefined);
+      const caCerts = options.caCerts ??
+        (options.caCertFile
+          ? [this.runtime.readTextFileSync(options.caCertFile)]
+          : undefined);
       tlsFields = {
         ...(cert !== undefined && { cert }),
         ...(key !== undefined && { key }),
@@ -187,12 +178,17 @@ export class CoreClient<
     try {
       if (tls) {
         const { cert, key, caCerts } = this.state.remoteAddr;
-        const tlsOpts: Deno.ConnectTlsOptions = { hostname, port, caCerts };
         this.conn = cert && key
-          ? await this.connectImpl.withTls({ ...tlsOpts, cert, key })
-          : await this.connectImpl.withTls(tlsOpts);
+          ? await this.runtime.connectTls({
+            hostname,
+            port,
+            caCerts,
+            cert,
+            key,
+          })
+          : await this.runtime.connectTls({ hostname, port, caCerts });
       } else {
-        this.conn = await this.connectImpl.noTls({ hostname, port });
+        this.conn = await this.runtime.connect({ hostname, port });
       }
       this.emit("connected", publicAddr);
     } catch (error) {
@@ -210,7 +206,7 @@ export class CoreClient<
     return publicAddr;
   }
 
-  private async loop(conn: Deno.Conn): Promise<void> {
+  private async loop(conn: Conn): Promise<void> {
     for (;;) {
       const chunks = await this.read(conn);
       if (chunks === null) break;
@@ -225,7 +221,7 @@ export class CoreClient<
     this.close();
   }
 
-  private async read(conn: Deno.Conn): Promise<string | null> {
+  private async read(conn: Conn): Promise<string | null> {
     let read: number | null;
 
     try {
@@ -305,9 +301,7 @@ export class CoreClient<
   /** Emits properly an error. */
   emitError(...args: ErrorArgs): void {
     const [, error] = args;
-    const isSilentError = error instanceof Deno.errors.BadResource ||
-      error instanceof Deno.errors.Interrupted;
-    if (isSilentError) {
+    if (this.runtime?.isSilentError(error)) {
       return;
     }
     this.emit("error", toClientError(...args));

core/client_test.ts

@@ -2,7 +2,7 @@ import { assertEquals, assertRejects, assertThrows } from "@std/assert";
 import { describe } from "../testing/helpers.ts";
 import { mockConsole } from "../testing/console.ts";
 import { MockServer } from "../testing/server.ts";
-import { MockCoreClient } from "../testing/client.ts";
+import { MockCoreClient, SilentTestError } from "../testing/client.ts";
 import { type CoreFeatures } from "./client.ts";
 import { type Raw } from "./parsers.ts";
 import { createPlugin, type Plugin } from "./plugins.ts";
@@ -353,23 +353,21 @@ describe("core/client", (test) => {
     assertEquals("key" in addr, false);
   });
 
-  test("prefer cert over certFile when both provided", async () => {
+  test("store TLS cert and key in remoteAddr", async () => {
     const { client } = mock();
 
     await client.connect("host", {
       tls: true,
       cert: "INLINE_CERT",
-      certFile: "/nonexistent/cert.pem",
       key: "INLINE_KEY",
-      keyFile: "/nonexistent/key.pem",
     });
 
     assertEquals(client.state.remoteAddr.cert, "INLINE_CERT");
     assertEquals(client.state.remoteAddr.key, "INLINE_KEY");
     client.disconnect();
   });
 
-  test("swallow some Deno errors silently", () => {
+  test("swallow silent errors", () => {
     const { client } = mock();
     let triggered = 0;
 
@@ -378,8 +376,8 @@ describe("core/client", (test) => {
     });
 
     client.emitError("write", new Error("Boom!")); // +1
-    client.emitError("write", new Deno.errors.BadResource()); // should not throw
-    client.emitError("write", new Deno.errors.Interrupted()); // should not throw
+    client.emitError("write", new SilentTestError()); // should not throw
+    client.emitError("write", new SilentTestError()); // should not throw
 
     assertEquals(triggered, 1);
   });