https://github.com/trytriplex/websocks
🧦 An end-to-end typed websocket server for Node.js with clients for React and events.
https://github.com/trytriplex/websocks
javascript nodejs reactjs typescript websocket
Last synced: 11 months ago
JSON representation
🧦 An end-to-end typed websocket server for Node.js with clients for React and events.
- Host: GitHub
- URL: https://github.com/trytriplex/websocks
- Owner: trytriplex
- License: mit
- Created: 2025-02-01T03:27:08.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-01T03:18:34.000Z (12 months ago)
- Last Synced: 2025-04-01T04:24:55.453Z (12 months ago)
- Topics: javascript, nodejs, reactjs, typescript, websocket
- Language: TypeScript
- Homepage:
- Size: 293 KB
- Stars: 8
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Websocks
[](https://discord.gg/nBzRBUEs4b) [](https://github.com/sponsors/itsdouges)
## Installation
```bash
npm i @triplex/websocks-server @triplex/websocks-client
```
## Usage
### Create the server
```ts
// 1. Create the websocks server
import { createWSServer } from "@triplex/websocks-server";
const wss = createWSServer();
// 2. Define routes
const routes = wss.collectTypes([
wss.route(
"/rng/:max",
({ max }) => Math.round(Math.random() * Number(max)),
(push) => {
setInterval(() => {
// Every 1s push a new value to the client.
push();
}, 1000);
},
),
]);
// 3. Define events
const events = wss.collectTypes([
tws.event<"ping", { timestamp: number }>("ping", (send) => {
setInterval(() => {
send({ timestamp: Date.now() });
}, 1000);
}),
]);
// 4. Start listening
wss.listen(3000);
// 5. Export types to use with the client
export type Routes = typeof routes;
export type Events = typeof events;
```
### Create the client
```tsx
// 1. Import the server types
import { createWSEvents } from "@triplex/websocks-client/events";
import { createWSHooks } from "@triplex/websocks-client/react";
import { type Events, type Routes } from "./server";
// 2. Declare the clients
const { preloadSubscription, useSubscription } = createWSHooks({
url: "ws://localhost:3000",
});
const { on } = createWSEvents({
url: "ws://localhost:3000",
});
// 3. Preload data
preloadSubscription("/rng/:max", { max: 100 });
// 4. Subscribe to the data
function Component() {
const value = useSubscription("/rng/:max", { max: 100 });
return
{value};
}
on("ping", ({ timestamp }) => {
console.log(timestamp);
});
```
## API
### `createWSServer()`
Creates a typed websocket server.
#### Returns
| Name | Description |
| --- | --- |
| `close()` | Closes the server. |
| `collectTypes(TEvents[] \| TRoutes[])` | Collects types from `event()` and `route()`. |
| `route(path: string, callback: Function, initialize: Function)` | Creates a route. |
| `event(eventName: string, initialize: Function)` | Creates an event. |
| `listen(port: number)` | Listens to the declared port. |
### `createWSHooks(options: Options | () => Options)`
Creates a routes client using types from the server that returns React hooks.
#### Returns
| Name | Description |
| --- | --- |
| `clearQuery(path: string, args: TArgs)` | Clears the query from the cache. |
| `preloadSubscription(path: string, args: TArgs)` | Preloads the subscription. |
| `useSubscription(path: string, args: TArgs)` | Returns the value of a preloaded subscription. |
| `useLazySubscription(path: string, args: TArgs)` | Returns the value of a subscription. |
### `createWSEvents(options: Options | () => Options)`
Creates an events client using types from the server.
#### Returns
| Name | Description |
| ------------------------------------------- | ------------------- |
| `on(eventName: string, callback: Function)` | Listen to an event. |