{"id":13674,"library":"node-unix-socket","title":"Node.js Unix Socket Extensions","description":"node-unix-socket is a Node.js addon, built with napi-rs and leveraging libuv, that extends Node.js's native networking capabilities to support Unix `SOCK_SEQPACKET` and `SOCK_DGRAM` sockets. It also enables the use of `SO_REUSEPORT` for TCP `net.Server` instances, offering an alternative to Node.js's built-in `cluster` module for load balancing, with kernel-level distribution. The package is currently at version 0.2.7, indicating ongoing development. It differentiates itself by providing these advanced socket types without introducing additional asynchronous runtimes, relying solely on Node.js's internal libuv. Pre-compiled binaries are shipped for common platforms, reducing the need for compilation environments. This library is particularly useful for inter-process communication patterns requiring message boundary preservation (seqpacket) or connectionless datagram communication, as well as optimizing high-throughput TCP servers. While release cadence isn't explicitly stated, its focus on specific, low-level features suggests a stable, less frequent update cycle unless major Node.js changes necessitate it.","status":"active","version":"0.2.7","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install node-unix-socket","lang":"bash","label":"npm"},{"cmd":"yarn add node-unix-socket","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-unix-socket","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM import for SeqpacketServer, typically used for server-side sequential packet communication.","wrong":"const { SeqpacketServer } = require('node-unix-socket');","symbol":"SeqpacketServer","correct":"import { SeqpacketServer } from 'node-unix-socket';"},{"note":"ESM import for SeqpacketSocket, used as a client or peer for sequential packet communication. Note that Seqpacket sockets are not supported on macOS.","wrong":"const { SeqpacketSocket } = require('node-unix-socket');","symbol":"SeqpacketSocket","correct":"import { SeqpacketSocket } from 'node-unix-socket';"},{"note":"ESM import for DgramSocket, enabling connectionless Unix datagram communication. The package exports a single class for both server and client roles in this context.","wrong":"const { DgramSocket } = require('node-unix-socket');","symbol":"DgramSocket","correct":"import { DgramSocket } from 'node-unix-socket';"}],"quickstart":{"code":"import { SeqpacketServer, SeqpacketSocket } from 'node-unix-socket';\nimport os from 'os';\nimport path from 'path';\nimport fs from 'fs';\n\nconst bindPath = path.resolve(os.tmpdir(), './my_seqpacket.sock');\n\n// Ensure the socket file does not exist from previous runs\ntry {\n  fs.unlinkSync(bindPath);\n} catch (e) {\n  // Ignore if file does not exist\n}\n\n// Create and start a Seqpacket server\nconst server = new SeqpacketServer();\nserver.listen(bindPath);\nserver.on('connection', (socket) => {\n  console.log('Server: Client connected');\n  socket.on('data', (buf) => {\n    console.log('Server: received', buf.toString());\n  });\n  socket.on('end', () => {\n    console.log('Server: Client disconnected');\n  });\n});\nserver.on('listening', () => {\n  console.log(`Server listening on ${bindPath}`);\n});\nserver.on('error', (err) => {\n  console.error('Server error:', err);\n});\n\n// Create and connect a Seqpacket client\nconst client = new SeqpacketSocket();\nclient.connect(bindPath, () => {\n  console.log('Client: Connected to server');\n  const data = ['hello, ', 'w', 'o', 'r', 'l', 'd'];\n\n  for (const str of data) {\n    client.write(Buffer.from(str));\n    console.log(`Client: Sent '${str}'`);\n  }\n  client.end(() => {\n    console.log('Client: Disconnected, closing server in 1 sec...');\n    setTimeout(() => server.close(), 1000);\n  });\n});\nclient.on('error', (err) => {\n  console.error('Client error:', err);\n  server.close(); // Ensure server closes on client error\n});\n\n// Clean up on process exit\nprocess.on('exit', () => {\n  try {\n    fs.unlinkSync(bindPath);\n    console.log('Cleaned up socket file.');\n  } catch (e) {\n    // Ignore if file already removed or never created\n  }\n});","lang":"typescript","description":"This example demonstrates how to set up a SeqpacketServer and connect a SeqpacketSocket client to it, sending multiple messages while preserving message boundaries, then cleaning up the socket file."},"warnings":[{"fix":"Ensure your deployment environment for SOCK_SEQPACKET sockets is Linux. For cross-platform compatibility, consider alternative IPC mechanisms like standard TCP sockets or other specialized libraries.","message":"SOCK_SEQPACKET sockets are explicitly noted as not working on macOS. Attempting to use them on this platform will result in an error or undefined behavior.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Thoroughly test SO_REUSEPORT behavior on all target operating systems and Node.js versions. Consult OS-specific documentation and network stack behavior for accurate expectations. Implement robust monitoring to ensure connections are distributed as intended.","message":"The behavior of SO_REUSEPORT can vary significantly across different operating systems, potentially leading to unexpected load balancing or connection distribution patterns compared to Node.js's native cluster module.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Check the project's supported platforms table in the README. Ensure your Node.js version, OS, and architecture match. If issues persist, refer to the `napi-rs` and Node.js N-API documentation for setting up a compilation environment, which may require specific toolchains (e.g., Python, C++ compiler, Node.gyp).","message":"As a native Node.js addon, `node-unix-socket` relies on pre-compiled binaries. If a pre-built binary is not available for your specific Node.js version, architecture, or operating system, you may encounter compilation errors during installation.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"search_vec":"'0.2.7':74 'addit':89 'addon':12 'advanc':84 'also':38 'altern':51 'asynchron':90 'balanc':62 'binari':102 'boundari':127 'built':13,56 'built-in':55 'cadenc':145 'capabl':27 'chang':168 'cluster':58 'common':106 'communic':123,133 'compil':101,112 'connectionless':131 'current':71 'cycl':164 'datagram':132 'develop':77 'dgram':35 'differenti':79 'distribut':67 'enabl':39 'environ':113 'explicit':148 'extend':22 'extens':4 'featur':157 'focus':151 'frequent':162 'high':139 'high-throughput':138 'indic':75 'instanc':48 'inter':121 'inter-process':120 'intern':97 'introduc':88 'isn':146 'javascript':171 'kernel':65 'kernel-level':64 'less':161 'level':66,156 'leverag':19 'librari':115 'libuv':20,98 'load':61 'low':155 'low-level':154 'major':166 'messag':126 'modul':59 'napi':16 'napi-r':15 'nativ':25 'necessit':169 'need':110 'net.server':47 'network':26 'node':6 'node-unix-socket':5 'node.js':1,11,23,53,95,167 'offer':49 'ongo':76 'optim':137 'packag':69 'particular':117 'pattern':124 'platform':107 'pre':100 'pre-compil':99 'preserv':128 'process':122 'provid':82 'reduc':108 'releas':144 'reli':92 'requir':125 'reuseport':44 'rs':17 'runtim':91 'seqpacket':32,129 'server':142 'ship':104 'sock':31,34 'socket':3,8,36,85 'sole':93 'specif':153 'stabl':160 'state':149 'suggest':158 'support':29 'tcp':46,141 'throughput':140 'type':86 'typescript':172 'unix':2,7,30 'unless':165 'updat':163 'use':41,118 'version':73 'well':135 'without':87","created_at":"2026-04-20T01:55:43.278604+00:00","updated_at":"2026-04-20T01:55:43.278604+00:00","problems":[{"fix":"Rebuild the native modules for your current Node.js version by running `npm rebuild node-unix-socket` or `npm install` again. Ensure your Node.js version is supported by the package.","cause":"The native addon was compiled for a different Node.js ABI version than the one currently running. This often happens after updating Node.js or when `npm install` was run with a different Node.js version.","error":"Error: The module '\\path\\to\\node_modules\\node-unix-socket\\index.node' was compiled against a different Node.js version"},{"fix":"Double-check the socket path for validity and correct permissions. For `SOCK_SEQPACKET` or `SOCK_DGRAM` sockets, ensure the operating system (e.g., macOS for `SOCK_SEQPACKET`) actually supports the requested operation. Verify the path is absolute and within acceptable length limits for the OS.","cause":"This typically indicates an invalid argument was provided to the `bind` method, such as a malformed socket path or an unsupported operation for the specific socket type/OS.","error":"Error: bind EINVAL"},{"fix":"Ensure the server is running and has successfully created the socket file at the specified path before the client attempts to connect. Verify the path used by the client exactly matches the path the server is binding to. Check file system permissions if the path exists but is inaccessible.","cause":"The client attempted to connect to a Unix domain socket path that does not exist or has been removed. This usually means the server is not listening on that path.","error":"Error: connect ENOENT / No such file or directory"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/node-unix-socket","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}