odac 1.4.16 → 1.4.17

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+### 🛠️ Fixes & Improvements
+
+- repair broken redis pub/sub delivery and align unsubscribe() across drivers
+- send() no longer JSON-serializes Buffer/TypedArray into TEXT frames
+- **test:** close WebSocketClient instances left open after each test
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
 ### ✨ What's New
 
 - add multipart file upload support with validation

package/docs/backend/13-utilities/02-ipc.md

@@ -72,6 +72,29 @@ await Odac.Ipc.publish('chat:global', { user: 'Emre', text: 'Hello World' });
 > [!TIP]
 > When using `memory` driver, the subscription listener is registered in the current worker. When a message is published, it goes to the Main process and is then broadcasted to all subscribed workers.
 
+#### Unsubscribing
+
+A channel can carry several independent subscribers, so a subscription is identified by its callback — not by the channel name alone. `subscribe()` returns a handle that removes exactly the subscription it created, which saves you from holding on to the callback yourself.
+
+```javascript
+const stats = await Odac.Ipc.subscribe('server:1:stream', onStats); // long-lived
+const ack = await Odac.Ipc.subscribe('server:1:stream', onAck);     // short-lived
+
+await ack.unsubscribe();          // only onAck stops; onStats keeps receiving
+```
+
+`unsubscribe(channel, callback)` does the same thing when you already hold the callback. To drop every subscriber on a channel at once, ask for it explicitly:
+
+```javascript
+await Odac.Ipc.unsubscribeAll('server:1:stream');
+```
+
+> [!WARNING]
+> `unsubscribe(channel)` without a callback cannot tell which subscriber is leaving, so it does nothing and logs a warning. It will throw in the next major version — pass the callback or the handle, or use `unsubscribeAll()`.
+
+> [!TIP]
+> Subscriptions created through the request-scoped `Odac.Ipc` are released automatically when the request ends, so you only need to unsubscribe by hand for subscriptions that should end earlier than the request.
+
 ### Atomic Counters
 
 Use `incrBy` / `decrBy` to atomically increment or decrement a numeric key. These are safe to call from multiple workers simultaneously — no read-then-write race conditions.
@@ -186,5 +209,7 @@ try {
 | `srem(key, ...members)` | Remove members from a set |
 | `lock(key, ttl)` | Acquire a mutex lock |
 | `unlock(key)` | Release a mutex lock |
-| `subscribe(channel, handler)` | Subscribe to a Pub/Sub channel |
+| `subscribe(channel, handler)` | Subscribe to a Pub/Sub channel; returns a handle with `unsubscribe()` |
+| `unsubscribe(channel, handler)` | Remove a single subscription, leaving other subscribers intact |
+| `unsubscribeAll(channel)` | Remove every subscription on a channel |
 | `publish(channel, message)` | Publish a message to a channel |

package/package.json

@@ -7,7 +7,7 @@
     "email": "mail@emre.red",
     "url": "https://emre.red"
   },
-  "version": "1.4.16",
+  "version": "1.4.17",
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"

package/src/Ipc.js

@@ -8,6 +8,7 @@ class Ipc extends EventEmitter {
     this.config = {}
     this._requests = new Map() // For memory driver response tracking
     this._subs = new Map() // For memory driver subscriptions
+    this._redisBridges = new Map() // channel -> the single node-redis listener bridging to our EventEmitter
   }
 
   /**
@@ -263,17 +264,47 @@ class Ipc extends EventEmitter {
     }
   }
 
+  /**
+   * A single channel may carry several independent consumers (e.g. a long-lived stats
+   * listener and a short-lived ack listener on the same stream). The callback reference
+   * is what tells them apart, so both drivers key subscriptions on it and both must be
+   * able to remove one without disturbing the others.
+   *
+   * @param {string} channel
+   * @param {function} callback
+   * @returns {Promise<{channel: string, callback: function, unsubscribe: function}>} Handle
+   *   that removes only this subscription, so callers need not retain the callback themselves.
+   */
   async subscribe(channel, callback) {
+    if (typeof callback !== 'function') {
+      throw new TypeError(`Odac.Ipc.subscribe('${channel}') requires a callback function.`)
+    }
+
     if (this.config.driver === 'redis') {
       if (!this.subRedis) {
         this.subRedis = this.redis.duplicate()
         await this.subRedis.connect()
-        this.subRedis.on('message', (chan, msg) => {
-          this.emit(chan, JSON.parse(msg))
-        })
       }
-      // Redis handles duplicate subscriptions gracefully (ignores them)
-      await this.subRedis.subscribe(channel)
+      // node-redis v4+ delivers messages to a per-channel listener passed to subscribe();
+      // it does not emit a client-wide 'message' event. We register exactly one bridge
+      // listener per channel and fan out locally, so removing one consumer never tears
+      // down the Redis subscription the other consumers still depend on.
+      if (!this._redisBridges.has(channel)) {
+        const bridge = raw => {
+          try {
+            this.emit(channel, JSON.parse(raw))
+          } catch (err) {
+            console.error('[Odac Ipc] Failed to parse message on channel "' + channel + '":', err)
+          }
+        }
+        this._redisBridges.set(channel, bridge)
+        try {
+          await this.subRedis.subscribe(channel, bridge)
+        } catch (err) {
+          this._redisBridges.delete(channel)
+          throw err
+        }
+      }
       this.on(channel, callback)
     } else {
       // Memory driver subscription
@@ -284,27 +315,67 @@ class Ipc extends EventEmitter {
       }
       this._subs.get(channel).add(callback)
     }
+
+    return {channel, callback, unsubscribe: () => this.unsubscribe(channel, callback)}
   }
 
+  /**
+   * Removes a single subscription. Other consumers of the same channel keep receiving
+   * messages; the underlying Redis/Primary subscription is torn down only once the last
+   * consumer is gone.
+   */
   async unsubscribe(channel, callback) {
+    if (typeof callback !== 'function') {
+      // Without a callback there is no way to know which consumer is leaving, so we
+      // refuse to guess: silently dropping the call leaks the listener, and dropping
+      // every listener would kill co-tenants on the channel.
+      console.warn(
+        `[Odac Ipc] unsubscribe('${channel}') was called without a callback and did nothing. ` +
+          `Pass the callback (or the handle returned by subscribe()) to remove one subscription, ` +
+          `or call unsubscribeAll('${channel}') to remove every subscription on the channel. ` +
+          `This call will throw in the next major version.`
+      )
+      return
+    }
+
     if (this.config.driver === 'redis') {
       this.removeListener(channel, callback)
       // If no more listeners for this channel, unsubscribe from redis to save resources
-      if (this.listenerCount(channel) === 0 && this.subRedis) {
-        await this.subRedis.unsubscribe(channel)
+      if (this.listenerCount(channel) === 0) {
+        await this._teardownRedisChannel(channel)
       }
     } else {
-      if (this._subs.has(channel)) {
-        const callbacks = this._subs.get(channel)
-        callbacks.delete(callback)
-        if (callbacks.size === 0) {
-          this._subs.delete(channel)
-          this._sendMemory('unsubscribe', {channel})
-        }
+      const callbacks = this._subs.get(channel)
+      if (!callbacks || !callbacks.delete(callback)) return
+      if (callbacks.size === 0) {
+        this._subs.delete(channel)
+        this._sendMemory('unsubscribe', {channel})
       }
     }
   }
 
+  /**
+   * Removes every subscription on a channel. Kept separate from unsubscribe() so that
+   * tearing down a shared channel is always a deliberate act, never an accident.
+   */
+  async unsubscribeAll(channel) {
+    if (this.config.driver === 'redis') {
+      this.removeAllListeners(channel)
+      await this._teardownRedisChannel(channel)
+    } else {
+      if (this._subs.delete(channel)) {
+        this._sendMemory('unsubscribe', {channel})
+      }
+    }
+  }
+
+  async _teardownRedisChannel(channel) {
+    const bridge = this._redisBridges.get(channel)
+    if (!bridge) return
+    this._redisBridges.delete(channel)
+    if (this.subRedis) await this.subRedis.unsubscribe(channel, bridge)
+  }
+
   // --- Drivers ---
 
   async _initRedis() {
@@ -587,6 +658,8 @@ class Ipc extends EventEmitter {
    */
   async close() {
     if (this.config.driver === 'redis') {
+      for (const channel of this._redisBridges.keys()) this.removeAllListeners(channel)
+      this._redisBridges.clear()
       if (this.subRedis) {
         await this.subRedis.quit().catch(() => {})
         this.subRedis = null

package/src/Odac.js

@@ -33,20 +33,36 @@ module.exports = {
     _odac._ipcSubs = []
     const ipcSingleton = require('./Ipc.js')
 
+    const forgetSub = (channel, callback) => {
+      const index = _odac._ipcSubs.findIndex(s => s.channel === channel && s.callback === callback)
+      if (index > -1) _odac._ipcSubs.splice(index, 1)
+    }
+
     _odac.Ipc = new Proxy(ipcSingleton, {
       get(target, prop) {
         if (prop === 'subscribe') {
           return async (channel, callback) => {
-            const res = await target.subscribe(channel, callback)
+            const handle = await target.subscribe(channel, callback)
             _odac._ipcSubs.push({channel, callback})
-            return res
+            // Route the handle's unsubscribe back through this instance so that releasing a
+            // subscription via the handle also drops it from the request-scoped cleanup list.
+            return {
+              ...handle,
+              unsubscribe: () => _odac.Ipc.unsubscribe(channel, callback)
+            }
           }
         }
         if (prop === 'unsubscribe') {
           return async (channel, callback) => {
             const res = await target.unsubscribe(channel, callback)
-            const index = _odac._ipcSubs.findIndex(s => s.channel === channel && s.callback === callback)
-            if (index > -1) _odac._ipcSubs.splice(index, 1)
+            forgetSub(channel, callback)
+            return res
+          }
+        }
+        if (prop === 'unsubscribeAll') {
+          return async channel => {
+            const res = await target.unsubscribeAll(channel)
+            _odac._ipcSubs = _odac._ipcSubs.filter(s => s.channel !== channel)
             return res
           }
         }

package/src/WebSocket.js

@@ -25,6 +25,21 @@ const READY_STATE = {
   CLOSED: 3
 }
 
+const isBinary = data => Buffer.isBuffer(data) || ArrayBuffer.isView(data) || data instanceof ArrayBuffer
+
+/**
+ * Views must be wrapped over their backing memory rather than passed to
+ * Buffer.from() directly: for anything wider than a byte (Uint16Array,
+ * Float32Array, DataView) Buffer.from() reads the view as a list of numbers
+ * and truncates each element to a single byte.
+ */
+const toPayload = data => {
+  if (Buffer.isBuffer(data)) return data
+  if (ArrayBuffer.isView(data)) return Buffer.from(data.buffer, data.byteOffset, data.byteLength)
+  if (data instanceof ArrayBuffer) return Buffer.from(data)
+  return Buffer.from(data)
+}
+
 class WebSocketClient {
   static CONNECTING = READY_STATE.CONNECTING
   static OPEN = READY_STATE.OPEN
@@ -264,7 +279,7 @@ class WebSocketClient {
     if (this.#readyState === READY_STATE.CLOSING && opcode !== OPCODE.CLOSE) return
     if (!this.#socket.writable) return
 
-    const payload = Buffer.isBuffer(data) ? data : Buffer.from(data)
+    const payload = toPayload(data)
     const length = payload.length
 
     let header
@@ -313,6 +328,10 @@ class WebSocketClient {
 
   send(data) {
     if (this.#readyState !== READY_STATE.OPEN) return this
+    if (isBinary(data)) {
+      this.#sendFrame(OPCODE.BINARY, data)
+      return this
+    }
     const payload = typeof data === 'object' ? JSON.stringify(data) : String(data)
     this.#sendFrame(OPCODE.TEXT, payload)
     return this

package/test/Ipc/subscribe.test.js

@@ -0,0 +1,154 @@
+'use strict'
+
+const cluster = require('node:cluster')
+
+/**
+ * Tests Ipc pub/sub subscription lifecycle on the memory driver.
+ * Why: A channel routinely carries several independent consumers (e.g. a long-lived stats
+ * listener and a short-lived ack listener on the same stream). Removing one must never
+ * silently leak it, nor take the co-tenants down with it.
+ */
+
+let Ipc
+let originalSend
+
+beforeEach(async () => {
+  jest.resetModules()
+  // Subscriptions are a worker-side concern: the Primary only tracks which workers listen.
+  Object.defineProperty(cluster, 'isPrimary', {value: false, configurable: true})
+  originalSend = process.send
+  process.send = jest.fn()
+
+  Ipc = require('../../src/Ipc')
+  global.Odac = {Config: {}}
+  await Ipc.init()
+})
+
+afterEach(async () => {
+  await Ipc.close()
+  process.removeAllListeners('message')
+  process.send = originalSend
+  delete global.Odac
+})
+
+/** Simulates the Primary forwarding a published message down to this worker. */
+const deliver = (channel, message) => process.emit('message', {type: 'ipc:message', channel, message})
+
+describe('Ipc - subscribe()', () => {
+  it('should deliver messages to the subscriber', async () => {
+    const cb = jest.fn()
+    await Ipc.subscribe('chan', cb)
+
+    deliver('chan', {hello: 'world'})
+
+    expect(cb).toHaveBeenCalledWith({hello: 'world'})
+  })
+
+  it('should fan out to every subscriber on the same channel', async () => {
+    const stats = jest.fn()
+    const ack = jest.fn()
+    await Ipc.subscribe('stream', stats)
+    await Ipc.subscribe('stream', ack)
+
+    deliver('stream', 'tick')
+
+    expect(stats).toHaveBeenCalledWith('tick')
+    expect(ack).toHaveBeenCalledWith('tick')
+  })
+
+  it('should reject a missing callback instead of registering undefined', async () => {
+    await expect(Ipc.subscribe('chan')).rejects.toThrow(TypeError)
+  })
+
+  it('should return a handle that removes only its own subscription', async () => {
+    const stats = jest.fn()
+    const ack = jest.fn()
+    await Ipc.subscribe('stream', stats)
+    const ackSub = await Ipc.subscribe('stream', ack)
+
+    await ackSub.unsubscribe()
+    deliver('stream', 'tick')
+
+    expect(ack).not.toHaveBeenCalled()
+    expect(stats).toHaveBeenCalledWith('tick')
+  })
+})
+
+describe('Ipc - unsubscribe()', () => {
+  it('should stop delivering to the removed callback', async () => {
+    const cb = jest.fn()
+    await Ipc.subscribe('chan', cb)
+    await Ipc.unsubscribe('chan', cb)
+
+    deliver('chan', 'tick')
+
+    expect(cb).not.toHaveBeenCalled()
+  })
+
+  it('should keep co-tenants on the channel alive', async () => {
+    const stats = jest.fn()
+    const ack = jest.fn()
+    await Ipc.subscribe('stream', stats)
+    await Ipc.subscribe('stream', ack)
+
+    await Ipc.unsubscribe('stream', ack)
+    deliver('stream', 'tick')
+
+    expect(ack).not.toHaveBeenCalled()
+    expect(stats).toHaveBeenCalledWith('tick')
+  })
+
+  it('should tell the Primary only once the last subscriber leaves', async () => {
+    const stats = jest.fn()
+    const ack = jest.fn()
+    await Ipc.subscribe('stream', stats)
+    await Ipc.subscribe('stream', ack)
+
+    const sentUnsub = () => process.send.mock.calls.filter(([m]) => m.type === 'ipc:unsubscribe').length
+
+    await Ipc.unsubscribe('stream', ack)
+    expect(sentUnsub()).toBe(0)
+
+    await Ipc.unsubscribe('stream', stats)
+    expect(sentUnsub()).toBe(1)
+  })
+
+  it('should warn and do nothing when the callback is omitted', async () => {
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
+    const stats = jest.fn()
+    await Ipc.subscribe('stream', stats)
+
+    await Ipc.unsubscribe('stream')
+    deliver('stream', 'tick')
+
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('without a callback'))
+    expect(stats).toHaveBeenCalledWith('tick')
+    warn.mockRestore()
+  })
+
+  it('should ignore an unknown channel', async () => {
+    await expect(Ipc.unsubscribe('never-subscribed', jest.fn())).resolves.toBeUndefined()
+  })
+})
+
+describe('Ipc - unsubscribeAll()', () => {
+  it('should remove every subscriber and notify the Primary', async () => {
+    const stats = jest.fn()
+    const ack = jest.fn()
+    await Ipc.subscribe('stream', stats)
+    await Ipc.subscribe('stream', ack)
+
+    await Ipc.unsubscribeAll('stream')
+    deliver('stream', 'tick')
+
+    expect(stats).not.toHaveBeenCalled()
+    expect(ack).not.toHaveBeenCalled()
+    expect(process.send).toHaveBeenCalledWith(expect.objectContaining({type: 'ipc:unsubscribe', channel: 'stream'}))
+  })
+
+  it('should not notify the Primary for a channel it never joined', async () => {
+    await Ipc.unsubscribeAll('never-subscribed')
+
+    expect(process.send).not.toHaveBeenCalledWith(expect.objectContaining({type: 'ipc:unsubscribe'}))
+  })
+})

package/test/Ipc/subscribeRedis.test.js

@@ -0,0 +1,141 @@
+'use strict'
+
+/**
+ * Tests Ipc pub/sub on the redis driver.
+ * Why: node-redis v4+ delivers messages to a listener passed to subscribe() and emits no
+ * client-wide 'message' event, so the bridge must be wired per channel. These tests pin
+ * that wiring and assert the driver removes subscriptions with the same per-callback
+ * semantics as the memory driver.
+ */
+
+// Channel -> the listener node-redis was handed. Lets a test push a message the way a real
+// server would, without a live Redis.
+const mockChannels = new Map()
+
+const mockSubClient = {
+  connect: jest.fn().mockResolvedValue(undefined),
+  subscribe: jest.fn(async (channel, listener) => mockChannels.set(channel, listener)),
+  unsubscribe: jest.fn(async channel => mockChannels.delete(channel)),
+  quit: jest.fn().mockResolvedValue(undefined)
+}
+
+const mockClient = {
+  connect: jest.fn().mockResolvedValue(undefined),
+  duplicate: jest.fn(() => mockSubClient),
+  publish: jest.fn().mockResolvedValue(1),
+  quit: jest.fn().mockResolvedValue(undefined)
+}
+
+jest.mock('redis', () => ({createClient: jest.fn(() => mockClient)}), {virtual: true})
+
+let Ipc
+
+beforeEach(async () => {
+  jest.clearAllMocks()
+  jest.resetModules()
+  mockChannels.clear()
+
+  Ipc = require('../../src/Ipc')
+  global.Odac = {Config: {ipc: {driver: 'redis'}}}
+  await Ipc.init()
+})
+
+afterEach(async () => {
+  await Ipc.close()
+  delete global.Odac
+})
+
+/** Simulates Redis pushing a message on a channel, as node-redis would. */
+const deliver = (channel, message) => mockChannels.get(channel)?.(JSON.stringify(message), channel)
+
+describe('Ipc redis - subscribe()', () => {
+  it('should register a listener with redis and deliver parsed messages', async () => {
+    const cb = jest.fn()
+    await Ipc.subscribe('chan', cb)
+
+    expect(mockSubClient.subscribe).toHaveBeenCalledWith('chan', expect.any(Function))
+
+    deliver('chan', {hello: 'world'})
+    expect(cb).toHaveBeenCalledWith({hello: 'world'})
+  })
+
+  it('should subscribe to a channel only once, however many consumers join', async () => {
+    await Ipc.subscribe('stream', jest.fn())
+    await Ipc.subscribe('stream', jest.fn())
+
+    expect(mockSubClient.subscribe).toHaveBeenCalledTimes(1)
+  })
+
+  it('should fan out to every consumer on the same channel', async () => {
+    const stats = jest.fn()
+    const ack = jest.fn()
+    await Ipc.subscribe('stream', stats)
+    await Ipc.subscribe('stream', ack)
+
+    deliver('stream', 'tick')
+
+    expect(stats).toHaveBeenCalledWith('tick')
+    expect(ack).toHaveBeenCalledWith('tick')
+  })
+
+  it('should reject a missing callback instead of registering undefined', async () => {
+    await expect(Ipc.subscribe('chan')).rejects.toThrow(TypeError)
+    expect(mockSubClient.subscribe).not.toHaveBeenCalled()
+  })
+})
+
+describe('Ipc redis - unsubscribe()', () => {
+  it('should keep co-tenants alive and hold the redis subscription open', async () => {
+    const stats = jest.fn()
+    const ack = jest.fn()
+    await Ipc.subscribe('stream', stats)
+    const ackSub = await Ipc.subscribe('stream', ack)
+
+    await ackSub.unsubscribe()
+
+    expect(mockSubClient.unsubscribe).not.toHaveBeenCalled()
+
+    deliver('stream', 'tick')
+    expect(ack).not.toHaveBeenCalled()
+    expect(stats).toHaveBeenCalledWith('tick')
+  })
+
+  it('should drop the redis subscription once the last consumer leaves', async () => {
+    const stats = jest.fn()
+    const ack = jest.fn()
+    await Ipc.subscribe('stream', stats)
+    await Ipc.subscribe('stream', ack)
+
+    await Ipc.unsubscribe('stream', ack)
+    await Ipc.unsubscribe('stream', stats)
+
+    expect(mockSubClient.unsubscribe).toHaveBeenCalledWith('stream', expect.any(Function))
+  })
+
+  it('should warn instead of throwing when the callback is omitted', async () => {
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
+    const stats = jest.fn()
+    await Ipc.subscribe('stream', stats)
+
+    await expect(Ipc.unsubscribe('stream')).resolves.toBeUndefined()
+
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('without a callback'))
+    deliver('stream', 'tick')
+    expect(stats).toHaveBeenCalledWith('tick')
+    warn.mockRestore()
+  })
+})
+
+describe('Ipc redis - unsubscribeAll()', () => {
+  it('should remove every consumer and drop the redis subscription', async () => {
+    const stats = jest.fn()
+    const ack = jest.fn()
+    await Ipc.subscribe('stream', stats)
+    await Ipc.subscribe('stream', ack)
+
+    await Ipc.unsubscribeAll('stream')
+
+    expect(mockSubClient.unsubscribe).toHaveBeenCalledWith('stream', expect.any(Function))
+    expect(Ipc.listenerCount('stream')).toBe(0)
+  })
+})

package/test/WebSocket/Client/fragmentation.test.js

@@ -31,6 +31,25 @@ function createMockSocket() {
   }
 }
 
+const openClients = []
+
+/**
+ * Creates a client and registers it for teardown.
+ *
+ * The constructor starts a rate-limit interval that is only cleared on close(),
+ * so a client left open keeps Jest's event loop alive after the run finishes.
+ */
+function createClient(...args) {
+  const client = new WebSocketClient(...args)
+  openClients.push(client)
+  return client
+}
+
+afterEach(() => {
+  for (const client of openClients) client.close()
+  openClients.length = 0
+})
+
 describe('WebSocketClient Fragmentation', () => {
   let server
 
@@ -40,7 +59,7 @@ describe('WebSocketClient Fragmentation', () => {
 
   it('should reassemble fragmented text messages', () => {
     const socket = createMockSocket()
-    const client = new WebSocketClient(socket, server, 'frag-1')
+    const client = createClient(socket, server, 'frag-1')
     client.resume()
 
     const messages = []
@@ -60,7 +79,7 @@ describe('WebSocketClient Fragmentation', () => {
 
   it('should reassemble fragmented binary messages', () => {
     const socket = createMockSocket()
-    const client = new WebSocketClient(socket, server, 'frag-2')
+    const client = createClient(socket, server, 'frag-2')
     client.resume()
 
     const messages = []
@@ -83,7 +102,7 @@ describe('WebSocketClient Fragmentation', () => {
 
   it('should close with 1002 on unexpected continuation frame', () => {
     const socket = createMockSocket()
-    const client = new WebSocketClient(socket, server, 'frag-3')
+    const client = createClient(socket, server, 'frag-3')
     client.resume()
 
     const dataHandler = socket.on.mock.calls.find(c => c[0] === 'data')[1]
@@ -96,7 +115,7 @@ describe('WebSocketClient Fragmentation', () => {
 
   it('should handle single unfragmented message normally', () => {
     const socket = createMockSocket()
-    const client = new WebSocketClient(socket, server, 'frag-4')
+    const client = createClient(socket, server, 'frag-4')
     client.resume()
 
     const messages = []
@@ -112,7 +131,7 @@ describe('WebSocketClient Fragmentation', () => {
 
   it('should discard fragment buffer on close', () => {
     const socket = createMockSocket()
-    const client = new WebSocketClient(socket, server, 'frag-5')
+    const client = createClient(socket, server, 'frag-5')
     client.resume()
 
     const messages = []

package/test/WebSocket/Client/limits.test.js

@@ -1,5 +1,24 @@
 const {WebSocketServer, WebSocketClient} = require('../../../src/WebSocket.js')
 
+const openClients = []
+
+/**
+ * Creates a client and registers it for teardown.
+ *
+ * The constructor starts a rate-limit interval that is only cleared on close(),
+ * so a client left open keeps Jest's event loop alive after the run finishes.
+ */
+function createClient(...args) {
+  const client = new WebSocketClient(...args)
+  openClients.push(client)
+  return client
+}
+
+afterEach(() => {
+  for (const client of openClients) client.close()
+  openClients.length = 0
+})
+
 describe('WebSocketClient Limits', () => {
   let server
 
@@ -18,7 +37,7 @@ describe('WebSocketClient Limits', () => {
         removeAllListeners: jest.fn(),
         writable: true
       }
-      const client = new WebSocketClient(socket, server, 'test-id', {maxPayload: 10})
+      const client = createClient(socket, server, 'test-id', {maxPayload: 10})
       client.resume()
 
       const buffer = Buffer.alloc(100)
@@ -42,7 +61,7 @@ describe('WebSocketClient Limits', () => {
         removeAllListeners: jest.fn(),
         writable: true
       }
-      const client = new WebSocketClient(socket, server, 'test-id', {rateLimit: {max: 2, window: 1000}})
+      const client = createClient(socket, server, 'test-id', {rateLimit: {max: 2, window: 1000}})
       client.resume()
 
       const buffer = Buffer.alloc(7)

package/test/WebSocket/Client/readyState.test.js

@@ -16,6 +16,25 @@ function createMockSocket() {
   }
 }
 
+const openClients = []
+
+/**
+ * Creates a client and registers it for teardown.
+ *
+ * The constructor starts a rate-limit interval that is only cleared on close(),
+ * so a client left open keeps Jest's event loop alive after the run finishes.
+ */
+function createClient(...args) {
+  const client = new WebSocketClient(...args)
+  openClients.push(client)
+  return client
+}
+
+afterEach(() => {
+  for (const client of openClients) client.close()
+  openClients.length = 0
+})
+
 describe('WebSocketClient readyState', () => {
   let server
 
@@ -41,13 +60,13 @@ describe('WebSocketClient readyState', () => {
 
   it('should start in CONNECTING state', () => {
     const socket = createMockSocket()
-    const client = new WebSocketClient(socket, server, 'rs-1')
+    const client = createClient(socket, server, 'rs-1')
     expect(client.readyState).toBe(READY_STATE.CONNECTING)
   })
 
   it('should transition to OPEN on resume()', () => {
     const socket = createMockSocket()
-    const client = new WebSocketClient(socket, server, 'rs-2')
+    const client = createClient(socket, server, 'rs-2')
 
     client.resume()
 
@@ -57,7 +76,7 @@ describe('WebSocketClient readyState', () => {
 
   it('should transition to CLOSED after close()', () => {
     const socket = createMockSocket()
-    const client = new WebSocketClient(socket, server, 'rs-3')
+    const client = createClient(socket, server, 'rs-3')
     client.resume()
 
     client.close()
@@ -68,7 +87,7 @@ describe('WebSocketClient readyState', () => {
 
   it('should be idempotent — second close() is a no-op', () => {
     const socket = createMockSocket()
-    const client = new WebSocketClient(socket, server, 'rs-4')
+    const client = createClient(socket, server, 'rs-4')
     client.resume()
 
     client.close()
@@ -79,7 +98,7 @@ describe('WebSocketClient readyState', () => {
 
   it('should not send data when in CONNECTING state', () => {
     const socket = createMockSocket()
-    const client = new WebSocketClient(socket, server, 'rs-5')
+    const client = createClient(socket, server, 'rs-5')
 
     client.send('hello')
 
@@ -88,7 +107,7 @@ describe('WebSocketClient readyState', () => {
 
   it('should not send data when in CLOSED state', () => {
     const socket = createMockSocket()
-    const client = new WebSocketClient(socket, server, 'rs-6')
+    const client = createClient(socket, server, 'rs-6')
     client.resume()
     client.close()
 
@@ -103,7 +122,7 @@ describe('WebSocketClient readyState', () => {
 
   it('should not send ping when not OPEN', () => {
     const socket = createMockSocket()
-    const client = new WebSocketClient(socket, server, 'rs-7')
+    const client = createClient(socket, server, 'rs-7')
 
     client.ping()
 
@@ -113,7 +132,7 @@ describe('WebSocketClient readyState', () => {
   it('should not write when socket is not writable', () => {
     const socket = createMockSocket()
     socket.writable = false
-    const client = new WebSocketClient(socket, server, 'rs-8')
+    const client = createClient(socket, server, 'rs-8')
     client.resume()
 
     client.send('hello')
@@ -123,7 +142,7 @@ describe('WebSocketClient readyState', () => {
 
   it('should transition to CLOSED when socket fires close event', () => {
     const socket = createMockSocket()
-    const client = new WebSocketClient(socket, server, 'rs-9')
+    const client = createClient(socket, server, 'rs-9')
     server.clients.set('rs-9', client)
     client.resume()
 
@@ -136,7 +155,7 @@ describe('WebSocketClient readyState', () => {
 
   it('should emit close event only once on double cleanup', () => {
     const socket = createMockSocket()
-    const client = new WebSocketClient(socket, server, 'rs-10')
+    const client = createClient(socket, server, 'rs-10')
     server.clients.set('rs-10', client)
     client.resume()
 

package/test/WebSocket/Client/send.test.js

@@ -0,0 +1,148 @@
+const {WebSocketServer, WebSocketClient} = require('../../../src/WebSocket.js')
+
+function createMockSocket() {
+  return {
+    pause: jest.fn(),
+    resume: jest.fn(),
+    on: jest.fn(),
+    write: jest.fn(),
+    end: jest.fn(),
+    removeAllListeners: jest.fn(),
+    writable: true
+  }
+}
+
+/**
+ * Splits the frame handed to socket.write() back into opcode and payload.
+ * Server-sent frames are never masked, so the payload starts right after
+ * the (possibly extended) length field.
+ */
+function readFrame(socket) {
+  const frame = socket.write.mock.calls[0][0]
+  const opcode = frame[0] & 0x0f
+  const length = frame[1] & 0x7f
+
+  let offset = 2
+  if (length === 126) offset = 4
+  else if (length === 127) offset = 10
+
+  return {opcode, payload: frame.subarray(offset)}
+}
+
+const openClients = []
+
+/**
+ * Creates a client and registers it for teardown.
+ *
+ * The constructor starts a rate-limit interval that is only cleared on close(),
+ * so a client left open keeps Jest's event loop alive after the run finishes.
+ */
+function createClient(...args) {
+  const client = new WebSocketClient(...args)
+  openClients.push(client)
+  return client
+}
+
+afterEach(() => {
+  for (const client of openClients) client.close()
+  openClients.length = 0
+})
+
+describe('WebSocketClient send', () => {
+  let server
+  let client
+  let socket
+
+  beforeEach(() => {
+    server = new WebSocketServer()
+    socket = createMockSocket()
+    client = createClient(socket, server, 'send-1')
+    client.resume()
+  })
+
+  it('should send strings as TEXT frames', () => {
+    client.send('hello')
+
+    const {opcode, payload} = readFrame(socket)
+
+    expect(opcode).toBe(0x1)
+    expect(payload.toString('utf8')).toBe('hello')
+  })
+
+  it('should send plain objects as JSON TEXT frames', () => {
+    client.send({type: 'ping', n: 1})
+
+    const {opcode, payload} = readFrame(socket)
+
+    expect(opcode).toBe(0x1)
+    expect(JSON.parse(payload.toString('utf8'))).toEqual({type: 'ping', n: 1})
+  })
+
+  it('should send a Buffer as a BINARY frame instead of JSON', () => {
+    client.send(Buffer.from([0xde, 0xad, 0xbe, 0xef]))
+
+    const {opcode, payload} = readFrame(socket)
+
+    expect(opcode).toBe(0x2)
+    expect([...payload]).toEqual([0xde, 0xad, 0xbe, 0xef])
+  })
+
+  it('should send a TypedArray as a BINARY frame', () => {
+    client.send(new Uint8Array([1, 2, 3]))
+
+    const {opcode, payload} = readFrame(socket)
+
+    expect(opcode).toBe(0x2)
+    expect([...payload]).toEqual([1, 2, 3])
+  })
+
+  it('should send an ArrayBuffer as a BINARY frame', () => {
+    const view = new Uint8Array([9, 8, 7])
+    client.send(view.buffer)
+
+    const {opcode, payload} = readFrame(socket)
+
+    expect(opcode).toBe(0x2)
+    expect([...payload]).toEqual([9, 8, 7])
+  })
+
+  it('should preserve the bytes of multi-byte TypedArrays', () => {
+    // Buffer.from(view) would read each element as a number and truncate it
+    // to one byte, silently corrupting anything wider than a Uint8Array.
+    client.send(new Uint16Array([0x0100, 0x0200]))
+
+    const {opcode, payload} = readFrame(socket)
+
+    expect(opcode).toBe(0x2)
+    expect(payload.length).toBe(4)
+    expect([...payload]).toEqual([0x00, 0x01, 0x00, 0x02])
+  })
+
+  it('should honour the byteOffset of a view over a larger buffer', () => {
+    const backing = new Uint8Array([1, 2, 3, 4, 5, 6])
+    const view = backing.subarray(2, 5)
+
+    client.send(view)
+
+    const {payload} = readFrame(socket)
+
+    expect([...payload]).toEqual([3, 4, 5])
+  })
+
+  it('should send binary through sendBinary without corrupting wide views', () => {
+    client.sendBinary(new Uint16Array([0x0100]))
+
+    const {opcode, payload} = readFrame(socket)
+
+    expect(opcode).toBe(0x2)
+    expect([...payload]).toEqual([0x00, 0x01])
+  })
+
+  it('should not send when the connection is not open', () => {
+    const closed = createClient(createMockSocket(), server, 'send-2')
+
+    closed.send('hello')
+
+    expect(closed.readyState).toBe(WebSocketClient.CONNECTING)
+  })
+})