{"id":16254777,"url":"https://github.com/havvy/irc-socket","last_synced_at":"2025-08-10T14:15:56.054Z","repository":{"id":8476262,"uuid":"10077901","full_name":"Havvy/irc-socket","owner":"Havvy","description":"A simple IRC socket for use with Node IRC libraries.","archived":false,"fork":false,"pushed_at":"2022-02-06T09:29:52.000Z","size":103,"stargazers_count":16,"open_issues_count":4,"forks_count":7,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-08-09T16:07:16.474Z","etag":null,"topics":["irc","irc-socket","javascript","nodejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Havvy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-05-15T12:16:48.000Z","updated_at":"2023-08-27T04:47:46.000Z","dependencies_parsed_at":"2022-09-19T17:20:42.490Z","dependency_job_id":null,"html_url":"https://github.com/Havvy/irc-socket","commit_stats":null,"previous_names":["havvy/simple-irc-socket"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/Havvy/irc-socket","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Havvy%2Firc-socket","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Havvy%2Firc-socket/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Havvy%2Firc-socket/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Havvy%2Firc-socket/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Havvy","download_url":"https://codeload.github.com/Havvy/irc-socket/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Havvy%2Firc-socket/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269734193,"owners_count":24466568,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["irc","irc-socket","javascript","nodejs"],"created_at":"2024-10-10T15:24:16.280Z","updated_at":"2025-08-10T14:15:55.693Z","avatar_url":"https://github.com/Havvy.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"IRC Socket - Socket wrapper to emit irc messages and handle server startup. \n\nWe provide for you the following benefits:\n\n* One \"data\" event per IRC message.\n* Pings are automatically ponged too..\n* The startup handshake (before the RPL_WELCOME) message is handled.\n* A `raw` method to send raw messages to the server.\n\n## Installation ##\n\n```\nnpm install irc-socket --save\n```\n\n## Instantiation ##\n\n```javascript\nvar NetSocket = require(\"net\").Socket;\nvar IrcSocket = require(\"irc-socket\");\n\nvar netSocket = new Socket();\nvar ircSocket = IrcSocket({\n    socket: netSocket,\n\n    port: 6667,\n    server: \"irc.someircnetwork.net\",\n    nicknames: [\"freddy\", \"freddy_\"],\n    username: \"freddy\",\n    realname: \"Freddy\",\n\n    password: \"server-password\",\n\n    // For transparent proxies using\n    // the webirc protocol.\n    proxy: {\n        password: \"shared-webirc-password\",\n        username: \"users-username\",\n        hostname: \"users-hostname\",\n        ip: \"users-ip\"\n    },\n\n    // For anybody wanting IRC3 capabilities.\n    capabilities: {\n        requires: [\"multi-prefix\", \"userhost-in-names\"],\n        wants: [\"account-notify\"]\n    },\n\n    // Passed as the options parameter to socket's\n    // connect method.\n    // Shown here are example options.\n    connectOptions: {\n        localAddress: \"a-local-address\",\n        localPort: \"a-local-port\",\n        family: 6, // for ipv6 with net.Socket\n    },\n\n    // optional number of milliseconds with no \n    // response before timeout is fired\n    timeout: 5 * 60 * 1000 \n});\n```\n\n### IrcSocket(config, socket) ###\n\nThe IrcSocket constructor is overloaded to provide a convenience form that\ntakes the socket separately. This is provided so that if the config is created\napart from the Socket, you don't need to modify the config object, especially\nsince the rest of the configuration values can be serialized as JSON.\n\n```javascript\nvar NetSocket = require(\"net\").Socket;\nvar IrcSocket = require(\"irc-socket\");\nvar fs = require(\"fs\");\n\nvar config = fs.readFileSync(\"config.json\");\nvar netSocket = new NetSocket();\nvar ircSocket = IrcSocket(config, netSocket);\n```\n\n### Configuration\n\nThe configuration options are as follows.\n\n - `socket`: [**required**] A net.Socket that IrcSocket wraps around.\n\n - `server`: [**required**] The server/host to connect to. e.g. \"irc.mibbit.net\"\n\n - `port`: [**required**] Which port to connect to. Normally 6667, or 6697 for TLS.\n\n - `nicknames`: [**required**] Array of nicknames to try to use in order.\n\n - `username`: [**required**] Username part of the hostmask.\n\n - `realname`: [**required**] \"Real name\" to send with the USER command.\n\n - `password`: Password used to connect to the network. Most networks don't have one.\n\n - `proxy`: WEBIRC details if your connection is acting as a (probably web-based) proxy.\n\n - `capabilities`: See the Capabilities section below..\n\n - `connectOptions`: Options passed to the wrapped socket's connect method. Options `host` and `port` are overwritten. See [io.js's net.Socket.prototype.connect](https://iojs.org/api/net.html#net_socket_connect_options_connectlistener) for options when using `net.Socket` in either Node.js or io.js. (Node.js's documentation is incomplete.)\n\n#### Capabilities ####\n\nCapabilities are a feature added in IRCv3 to extend IRC while still keeping\nIRCv2 compatibility. You can see the specification and well-known capabilities\nat [their website](http://ircv3.atheme.org/).\n\nShould you want to use IRCv3 features, pass an object with the `requires`\nproperty listing which features you absolutely require and `wants` for\nfeatures that you can handle not being there. Both properties are optional.\n\n#### Proxy ####\n\nThe proxy object has the following four fields, all required:\n\n- `password`: Shared secret password between you and the network you are connecting with.\n\n- `username`: User or client requesting spoof.\n\n- `hostname`: Hostname of user connecting to your proxy.\n\n- `ip`: IP Address of user connecting to your proxy.\n\n## Starting and Closing the Socket ##\n\nYou start and end the socket like a normal net.Socket with the `connect` and\n`end` methods. You shouldn't call `end` yourself though. Instead, you should\nwrite a QUIT message to the server (see tnext section).\n\nThe `connect` method returns a\n`Promise\u003cResult\u003c{capabilities, nickname}, ConnectFailure\u003e, Error\u003e`.\n\nYou can either use the \"ready\" event or use the promises returned by the connect method.\n\n```javascript\nvar client = IrcSocket(...);\nclient.once('ready', function () {\n    client.end();\n}\nclient.connect();\n```\n\n```javascript\nvar client = IrcSocket(...);\nclient.connect().then(function (res) {\n    // If connect failed, it already closed itself (or was force killed).\n    // Otherwise, it succeeded, and we want to end it ourself.\n    if (res.isOk()) {\n        client.end();\n    }\n});\n```\n\n## Writing to the Server ##\nTo send messages to the server, use socket.raw(). It accepts either a\nstring or an array of Strings. The message '''must''' follow the \n[IRC protocol](https://irc-wiki.org/RFC 1459).\n\n```javascript\nvar details = {...};\nvar client = Ircsocket(details);\n\nmySocket.connect().then(function (res) {\n    if (res.isFail()) {\n        return;\n    }\n\n    // Using a string.\n    mySocket.raw(\"JOIN #biscuits\");\n}\n\nmySocket.on('data', function (message) {\n    message = message.split(\" \");\n\n    // Numeric 333 is sent when a user joins a channel.\n    if (message[1] === \"333\" \u0026\u0026\n        message[2] === details.nick \u0026\u0026\n        message[3] === \"#biscuits\")\n    {\n        // Using an array instead of a string.\n        mySocket.raw([\"PRIVMSG\", \"#biscuits\", \":Hello world.\"])\n    }\n});\n\nmySocket.on('data', function (message) {\n    // This is sent when you send QUIT too.\n    if (message.slice(0, 5) === \"ERROR\") {\n        mySocket.end();\n    }\n});\n```\n\nThe raw method does not allow the usage of newline characters.\n\nIf an array is passed to `raw`, the message will be joined with a space.\n\n## Reading from the Server ##\n\nAll messages are emitted via a 'data' event. Receiving callbacks to this\nevent will receive the message as the first parameter.\n\nExamples of reading messages are in the previous example. Messages generally\nlook like the following:\n\n```\n:irc.uk.mibbit.net 376 Havvy :End of /MOTD command.\n:NyanCat!Mibbit@mib-FFFFFFFF.redacted.com QUIT :Quit: http://www.mibbit.com ajax IRC Client\nERROR :Closing Link: Havvy[127-00-00-00.redacted.com] (Quit: Custom quit message.)\n```\n\nAll PING messages sent from the server are automatically PONGed too. You\ndo not need to handle them yourself, but you still receive them, should\nyou wish to log them.\n\n## Timeouts ##\n\nThe IRC socket will listen to ping messages and respond to them \nappropriately, so you do not need to handle this yourself.\n\nFurthermore, if no message from the server is sent within five\nminutes, the IrcSocket will ping the server. If no response is\nthenn sent in five more minutes, the socket will close and emit\na `\"timeout\"` event.\n\nShould that not be good enough, you can always use\n`setTimeout(number, optionalCallback)` to use the implementing\nsocket's (usually a net.Socket) timeout mechanisms.\n\nYou can listen to the `\"timeout\"` event for when this occurs.\n\n## Utility Methods ##\n\n### isStarted() ###\n\nThis method will return true if the socket was ever started.\n\n### isConnected() ###\n\nThis method will return true when the socket is started, but not ended. It\nwill otherwise return false.\n\n### isReady() ###\n\nThis method will return true if the RPL_WELCOME message has been sent and the\nsocket is still open. It will otherwise return false.\n\n### getRealname() ###\n\nThis method returns the realname (sometimes called gecos) of the connection.\n\n## Events ##\n\nThe irc-socket is an event emitter. It emits five events.\n\n+ ready(): Once the first 001 message has been acknowledged.\n+ data(message: String): Every message (including the 001) from the\nsender (inclusive) the the newline (exclusive).\n+ close(): Once the implementing socket has been closed.\n+ timeout(): When either this or the implenting socket time out.\n+ end(): Once the implementing socket emits an 'end' event.\n\n## Testing ##\n\nWe install `mocha` as a developer dependency, and run tests with that.\n\n```\nnpm install\nnpm test\n```\n\n## Upgrading from v.2.0.0 ##\n\nAll of the legacy compatibility has been removed.\n\nA lot of things have changed/been added.\n\n* Changed: \"nickname\" property is now \"nicknames\" and takes an array.\n* Changed: You cannot restart an irc-socket Socket.\n* Changed: you must pass in your own Socket under the \"socket\" property. All socket related configuration has been removed.\n* Changed: Real support for IRC3 capabilities. \"capab\" property changed to \"capabilities\", takes an object now.\n* Added: Support for the (Webirc)[http://wiki.mibbit.com/index.php/WebIRC] protocol.\n* Added: `isStarted`, `isReady` methods. for more fine grained status tracking.\n* Added: `connect` method returns a (Bluebird) Promise that either resolves to a Result of Ok([capabilities]) or Fail(FailReason).\n* Removed: Auto-addition of colons in .raw(Array) are gone. Put them in yourself as needed.\n* Added `debug` property which takes a function like `console.log`.\n\n### Configuration\n\nYou *must* rename the `nickname` property to `nicknames` and change it to an array.\nThis was done so that we can have multiple nicknames. Should all of them be not\naccepted, the socket will close itself.\n\nIf you were using the (practically useless) `capab` property, you probably want to\nuse the `capabilities` property which takes an object now.\n\nIf you were using `ipv6` you now want to pass `family: 6` to the `connectOptions`\nproperty object now. Likewise, other Socket connect options should go there.\n\nIf you were using `secure`, you now want to create a `net.Socket` and then upgrade\nit to a `tls.Socket` and finally upgrade that to an `irc-socket`. See the next\nsection for details.\n\n### Initialization\n\nWe now upgrade your socket into an irc-socket instead of instatiating it ourself.\n\nThis means that you need to instantiate the socket you want. Once you upgrade the\nsocket, you give up ownership of it, but gain ownership of the upgraded socket.\n\n```\nvar NetSocket = require(\"net\").Socket;\nvar IrcSocket = require(\"irc-socket\");\n\nvar netSocket = new Socket();\nvar ircSocket = IrcSocket({\n    port: 6667,\n    server: \"irc.someircnetwork.net\",\n    nicknames: [\"freddy\", \"freddy_\"],\n    username: \"freddy\",\n    realname: \"Freddy\"\n});\n```\n\nEven though `port` and `server` are part of the Socket connect options, you\nmust pass them to the IrcSocket options object. For every other connect\noption that was supported, you should instead pass the option in the\nconnectOptions object.\n\n```\nvar NetSocket = require(\"net\").Socket;\nvar IrcSocket = require(\"irc-socket\");\n\nvar netSocket = new Socket();\nvar ircSocket = IrcSocket({\n    socket: netSocket,\n    port: 6667,\n    server: \"irc.someircnetwork.net\",\n    nicknames: [\"freddy\", \"freddy_\"],\n    username: \"freddy\",\n    realname: \"Freddy\",\n    connectOptions: {\n        localAddress: aLocalAddress,\n        family: 6 // was `ipv6` option in old version, is `family` in net.Socket.\n    }\n});\n```\n\nFor what was a `secure` socket, you must instead wrap a NetSocket around a\nTLS socket.\n\n```\nvar NetSocket = require(\"net\").Socket;\nvar TlsSocket = require(\"tls\").TLSSocket;\nvar IrcSocket = require(\"irc-socket\");\n\nvar netSocket = new Socket();\nvar tlsSocket = new TlsSocket(netSocket, {rejectUnauthorized: false});\nvar IrcSocket = IrcSocket({\n    socket: tlsSocket,\n    ...\n});\n```\n\n### raw([String]) breaking change\n\nIf you were using the `raw` method with an array and relying on it to put in colons\nfor you, you must go back and add those colons in yourself. Just grep for `raw([`\nand you should find all of them.\n\n### connect() returns a Promise\n\nInstead of listening to the `ready` event and doing your own startup handling there,\nthe `connect` method return a Promise. The promise resolves to a\n[r-result](https://npmjs.org/package/r-result) result (mostly equivalent to Rust's\nResult type) where it is either Ok({capabilities, nickname}) or Fail(ConnectFailureReason).\nThe connect failure reasons are located at IrcSocket.connectFailures.\n\n## See Also\n\nThe [irc-message](https://github.com/expr/irc-message) package will quickly parse the strings you pass into objects.\nThe new version also merges with `irc-message-stream` to provide a stream.\n\nFor a full IRC Bot framework, take a look at [Tennu](https://tennu.github.io).\n\nFor long-running IRC Clients, take a look at [IRC Factory](https://github.com/ircanywhere/irc-factory).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhavvy%2Firc-socket","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhavvy%2Firc-socket","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhavvy%2Firc-socket/lists"}