promise-socket

promise-socket

This module allows the conversion net.Socket stream into its promisified version, which returns Promise object fulfilled when the stream's events occurred.

Requirements

This module requires Node >= 16.

Installation

npm install promise-socket

Usage

import PromiseSocket, {TimeoutError} from "promise-socket"

constructor

const promiseSocket = new PromiseSocket(socket)

PromiseSocket object requires socket object to work. New net.Socket object is created if socket argument is missing.

Example:

import net from "node:net"
import PromiseSocket from "promise-socket"

const socket = new net.Socket()

const promiseSocket = new PromiseSocket(socket)

stream

const socket = promiseSocket.stream

Original socket object.

Example:

console.log(promiseSocket.stream.localAddress)

connect

await connect(port, host)
await connect(path)
await connect(options)

Initiate a connection on a given socket. Promise if fulfilled when connect event is emitted. Check socket.connect for arguments.

Example:

await connect(80, "localhost")
// or
await connect({port: 80, host: "localhost"})

setTimeout

promiseSocket = socket.setTimeout(ms)

Set the timeout for idle socket and after this timeout the socket will be destroyed with a TimeoutError. It means that socket methods (connect, read, write, etc.) will be rejected.

The method returns this object.

Example:

socket.setTimeout(1000)
await socket.readAll()

read

const chunk = await promiseSocket.read(chunkSize)

Check PromiseReadable.read for details.

readAll

const content = await promiseSocket.readAll()

Check PromiseReadable.readAll for details.

iterate

for await (const chunk of promiseDuplex.iterate(chunkSize)) {
}

Check PromiseReadable.iterate for details.

Symbol.asyncIterator

for await (const chunk of promiseDuplex.iterate(chunkSize)) {
}

Check PromiseReadable[Symbol.asyncIterator] for details.

write

await promiseSocket.write(chunk)

Check PromiseWritable.write for details.

writeAll

await promiseSocket.writeAll(content, chunkSize)

Check PromiseWritable.writeAll for details.

end

await promiseSocket.end()

Check PromiseWritable.once for details.

once

const result = await promiseSocket.once(event)

Check PromiseReadable.once and PromiseWritable.once for details.

destroy

promiseSocket = promiseSocket.destroy()

This method calls destroy method on stream and cleans up all own handlers.

The method returns this object.

TimeoutError

try {
  socket.setTimeout(5000).connect({port, host})
} catch (e) {
  if (e instanceof TimeoutError) {
    console.error("Socket timeout")
  }
}

This is an error class that is used when the timeout occurred after using setTimeout method.

See also

PromiseReadable, PromiseWritable, PromiseDuplex, PromisePiping.

License

Copyright (c) 2017-2024 Piotr Roszatycki mailto:[e-mail]

MIT

Changelog

v8.0.0 2024-06-21

• Converted to ESM module.
• Requires Node >= 16.
• Uses "node:" prefix for Node.js modules.
• Uses promise-writable with listeners leak fixed in dex4er/js-promise-writable#55; closes dex4er/js-promise-socket#63.
• Uses promise-duplex with closed property that works with Node.js >= 16; closes dex4er/js-promise-socket#77.
• setTimeout returns this; closes: dex4er/js-promise-socket#72.