A bidirectional long-polling library designed for use with Roblox.
npm install simpollsimpoll.new
simpoll:connect
simpoll:send
simpoll:onMessage
simpoll:destroy
Server.subscribeServer.broadcastServer.connectionsServer.onConnectionServer.onDisconnectServer.listenServer.appConnection.idConnection.tokenConnection.lastUpdatedConnection.queue file and install it through wally install or a comparable command.
2. To get started, use the following code:
`lua
local simpoll = require(path.to.simpoll)
local poll = simpoll.new("https://your.simpoll.server", "your_very_safe_secret_here")
if poll:connect() then
poll:onMessage("topicClient", function(data)
print(data)
end)
poll:send("topicServer", "Hello, world!")
end
`
NPM
1. Install the package using npm:
`bash
npm install simpoll
`
2. To get started, use the following code:
`typescript
import { Server } from "simpoll";
const server = new Server("your_very_safe_secret_here");
server.subscribe("topicClient", (connection, data) => {
console.log(Received data from ${connection.id}: ${data});
});
// Any arguments that express.listen accepts can be passed here.
server.listen(3000, () => {
console.log(Server listening!);
});
setInterval(() => {
server.broadcast("topicServer", "Hello, world!");
}, 1000);
`
3. (optional) In order to see debug logs, set the log level as follows:
`typescript
import { Logger } from "simpoll";
Logger.transports[0].level = "debug";
`
Luau Documentation
$3
`luau
simpoll.new(server: string, secret: string, id: string?): simpoll
`
Creates a new simpoll client. The server URL should start with http:// or https:// and should be running a simpoll server. The ID is optional and defaults to the game's Job ID. It will be used to identify the connection on the server and should be unique. The secret is a shared secret between the client and server, used to verify requests coming from the client.
Note that this function does not return an actual simpoll object, but instead returns a subConnection, a wrapper class allowing us to have multiple connections on the same ID work seamlessly. This ensures that multiple packages can use simpoll without interfering with each other. If you call subConnection:destroy, all events created by this class will be disconnected. If all subconnections are destroyed, the main connection will be destroyed as well.
$3
`luau
simpoll:connect(retry: (boolean | number)?, overwrite: boolean?): boolean
`
Connects to the simpoll server. Returns whether the connection was successful. If this function succeeds, the client immediately starts polling for messages. If retry is set to true, the client will automatically attempt to reconnect if the connection is not successful. If retry is set to a number, the client tries that many times to reconnect before giving up (retries every 5 seconds). If overwrite is set to true, the client will overwrite the existing connection with this ID if one exists, transferring over the current queue and request callback.
If polling fails, the server immediately tries to reconnect using overwrite set to true. This will refresh the connection and ensure that the client is always connected.
$3
`luau
simpoll:send(topic: string, data: string | json, retry: boolean?): boolean
`
Sends a message to the simpoll server with the given topic. Returns whether the message was sent successfully. If retry is true, Simpoll keeps retrying every 5 seconds until a successful request occurs.
$3
`luau
simpoll:onMessage(topic: string, callback: (data: json | string) -> ()): signal.Connection
`
Sets a callback to be called when a message is received from the simpoll server with the given topic. The callback should take a single argument, which is the data received from the server.
$3
`luau
simpoll:destroy()
`
Destroys the simpoll server. This function should be called when the entire poller is no longer needed. While it is technically reversible by calling simpoll:connect again, this is not recommended. Under the hood, this function disconnects all events and disconnects from the server.
TypeScript Documentation
Server
A server can be constructed using the Server class. The server can be used to listen for incoming connections and send and receive messages. The server can be constructed using the following code:
`typescript
import { Server } from "simpoll";
const server = new Server("your_very_safe_secret_here", "an_optional_api_path");
`
API path is optional and defaults to /.
$3
`typescript
server.subscribe(topic: string, callback: (connection: Connection, data: any) => void)
`
Subscribes to a topic. The callback will be called when a message is received from the client. The callback should take two arguments: the connection ID and the data received from the client.
$3
`typescript
server.broadcast(topic: string, data: any)
`
Broadcasts a message to all connected clients, with the given topic.
$3
`typescript
server.connections(): Connection[]
`
Returns all currently connected clients.
$3
`typescript
server.onConnection(callback: (connection: Connection, overwroteExisting: boolean) => void): void
`
Sets a callback to be called when a new connection is established. The callback should take two arguments: the connection object and a boolean indicating whether the connection overwrote an existing connection.
$3
`typescript
server.onDisconnect(callback: (connection: Connection) => void): void
`
Sets a callback to be called when a connection is disconnected. The callback should take one argument: the connection object.
$3
`typescript
server.listen(...args: any[]): void
`
Starts the server. Any arguments that express.listen accepts can be passed here. A list of possible arguments can be found here.
$3
This is the underlying Express app that the server is using. You can use this to add middleware.
Connection
A connection object represents a connection to a client.
$3
`typescript
connection.id: string
`
The ID of the connection.
$3
`typescript
connection.token: string
`
The token used to validate the connection.
$3
`typescript
connection.lastUpdated: Date
`
The last time the connection was updated. This is internally used to determine if a connection has timed out and should be removed. This should not be modified.
$3
`typescript
connection.queue(topic: string, payload: string): void
``