{"id":17129115,"url":"https://github.com/pomax/socketless","last_synced_at":"2025-09-07T14:04:14.243Z","repository":{"id":39954501,"uuid":"192209812","full_name":"Pomax/socketless","owner":"Pomax","description":"A framework and methodology for writing web socket RPC programs, without writing a single line of web socket or RPC code.","archived":false,"fork":false,"pushed_at":"2025-01-08T18:39:20.000Z","size":1170,"stargazers_count":30,"open_issues_count":11,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-13T05:09:18.668Z","etag":null,"topics":["browser","nodejs","rpc","websocket"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Pomax.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-16T15:54:10.000Z","updated_at":"2025-02-13T01:51:23.000Z","dependencies_parsed_at":"2024-01-05T22:21:51.849Z","dependency_job_id":"b6f57256-59ea-40aa-9a8c-554b05ce92ea","html_url":"https://github.com/Pomax/socketless","commit_stats":{"total_commits":220,"total_committers":2,"mean_commits":110.0,"dds":"0.045454545454545414","last_synced_commit":"c73838c5dd038e29b95895777adc9908a5777922"},"previous_names":["pomax/async-socket.io"],"tags_count":89,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pomax%2Fsocketless","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pomax%2Fsocketless/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pomax%2Fsocketless/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pomax%2Fsocketless/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Pomax","download_url":"https://codeload.github.com/Pomax/socketless/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248665748,"owners_count":21142123,"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","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":["browser","nodejs","rpc","websocket"],"created_at":"2024-10-14T19:08:54.727Z","updated_at":"2025-07-29T22:37:42.959Z","avatar_url":"https://github.com/Pomax.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Socketless\n\nSocketless is a websocket-based RPC-like framework for client/server implementations, written specifically so you never have to write any websocket or RPC code. As far as the clients and servers know, there is no network, code is just \"normal function-based API code\", with the only caveat being that function calls that need to return values will do so asynchronously. Just like any other `async`/`await` code you're used to writing.\n\n### The current version of `socketless` is `v6.0.0`\n[(See the changelog for more information)](./docs/CHANGELOG.md)\n\n# Table of contents\n\n- [Installation](#installation)\n- [A short example](#a-short-example)\n- [Check out the docs](#i-want-to-know-more)\n- [Get in touch](#what-if-i-want-to-get-in-touch)\n\n# Installation\n\nThe `socketles` library can be installed from https://www.npmjs.com/package/socketless using your package manager of choice, and can be used in Deno by importing `\"npm:socketless@4\"`.\n\n**Note**: This library is written and exposed as modern ESM code, and relies on enough modern JS language features that this library is only guaranteed to work on the current generation of browsers, and current LTS version of Node. No support for older/dead browsers or end-of-life versions of Node is offered.\n\n## Using `socketless` in the browser\n\nAs the `socketless` library is code that by definition needs to run server-side, it does not provide a precompiled single-file library in a `dist` directory, nor should you ever (need to) bundle `socketless` into a front-end bundle. Instead, the library has its own mechanism for letting browsers connect, shown off in the following example and explained in more detail in the [\"how to...\"](docs/HOWTO.md) documentation.\n\n# A short example\n\nA short example is the easiest way to demonstrate how Socketless works. Normally, we'd put the client and server classes, as well as the code that links and runs client and server instances in their own files, but thing'll work fine if we don't, of course:\n\n```js\n/**\n * Make our server class announce client connections:\n */\nexport class ServerClass {\n  onConnect(client) {\n    console.log(`[server] A client connected!`);\n  }\n  // And give the server a little test function that both logs and returns a value:\n  async test() {\n    console.log(`[server] test!`);\n    return \"success!\";\n  }\n}\n```\n\n```js\n/**\n * Then, make our client class announce its own connection, as well as browser connections:\n */\nexport class ClientClass {\n  onConnect() {\n    console.log(`[client] We connected to the server!`);\n  }\n  onBrowserConnect() {\n    console.log(`[client] A browser connected!`);\n    this.setState({ goodToGo: true });\n  }\n}\n```\n\n```js\n/**\n * Then we can link those up as a `socketless` factory and run a client/server setup:\n */\nimport { linkClasses } from \"socketless\";\nconst { createWebClient, createServer } = linkClasses(ClientClass, ServerClass);\nconst { server, webServer } = createServer();\n\n// For demo purposes, let's use some hardcoded ports:\nconst SERVER_PORT = 8000;\nconst CLIENT_PORT = 3000;\n\n// So, first: create our server and start listening for connections...\nwebServer.listen(SERVER_PORT, () =\u003e console.log(`Server running...`));\n\n// ...then create our client, pointed at our server's URL...\nconst serverURL = `http://localhost:${SERVER_PORT}`;\nconst publicDir = `public`;\nconst { client, clientWebServer } = createWebClient(serverURL, publicDir);\n\n// ...and have that start listening for browser connections, too:\nclientWebServer.listen(CLIENT_PORT, () =\u003e {\n  console.log(`Client running...`);\n  const clientURL = `http://localhost:${CLIENT_PORT}`;\n  import(`open`).then(({ default: open }) =\u003e {\n    console.log(`Opening a browser...`);\n    open(clientURL);\n  });\n});\n```\n\nOf course we'll need something for the browser to load so we'll create a minimal `index.html` and `setup.js` and stick them both in a `public` dir. First our index file:\n\n```html\n\u003c!doctype html\u003e\n\u003chtml lang=\"en-GB\"\u003e\n  \u003chead\u003e\n    \u003cmeta charset=\"utf-8\" /\u003e\n    \u003ctitle\u003eLet's test our connections!\u003c/title\u003e\n    \u003cscript src=\"setup.js\" type=\"module\" async\u003e\u003c/script\u003e\n  \u003c/head\u003e\n  \u003cbody\u003e\n    \u003c!-- we only need the dev tools console tab for now --\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\nAnd then our browser JS:\n\n```js\n/**\n * We don't need to put a \"socketless.js\" in our public dir,\n * this is a \"magic import\" provided by socketless itself:\n */\nimport { createBrowserClient } from \"./socketless.js\";\n\n/**\n * And then we can build a browser UI thin client that will\n * automatically connect to the real client:\n */\ncreateBrowserClient(\n  class {\n    async init() {\n      console.log(`[browser] We're connected to our web client!`);\n      console.log(`[browser] Calling test:`, await this.server.test());\n    }\n    update(prevState) {\n      console.log(`[browser] State updated, goodToGo: ${this.state.goodToGo}`);\n    }\n  }\n);\n```\n\nThen we can run the above code, and see following output on the console:\n\n```\nServer running...\nClient running...\n[server] A client connected!\n[client] We connected to the server!\nOpening a browser...\n[client] A browser connected!\n[server] test!\n```\n\nAnd then if we check the browser's developer tools' `console` tab, we also see:\n\n```\n[browser] We're connected to our web client!           setup.js:14:15\n[browser] State updated, goodToGo: true                setup.js:18:15\n[browser] Calling test: success!                       setup.js:15:15\n```\n\nIt's important to note that we don't create clients by passing them a direct reference to the `server` instance`, but instead it's given a URL to connect to: the client and server can, and typically will, run on completely different machines \"anywhere on the internet\". As long as the same versions of the client and server classes are used on both machines (because, say, you're running on the same branch of the same git repo) then there's nothing else you need to do...\n\n#### _It just works._\n\n## I want to know more!\n\nThat's the spirit! Also, if this didn't whet your appetite you probably didn't need this library in the first place, but let's cut to the chase: install this library, have a look at the [documentation](./docs), probably start at the [\"how to ...\"](/docs/HOWTO.md) docs, and let's get this working for you!\n\n## What if I want to get in touch?\n\nI mean there's always the issue tracker, that's a pretty solid way to get in touch in a way that'll let us cooperate on improving this library. However, if you just want to fire off a social media message, find me over on [Mastodon](https://mastodon.social/@TheRealPomax) and give me a shout.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpomax%2Fsocketless","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpomax%2Fsocketless","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpomax%2Fsocketless/lists"}