# typesockets

> An end-to-end typesafe websockets wrapper/addon through the creation of client and server endpoint functions.

Latest version **1.0.6** (published 2022-06-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install typesockets
pnpm add typesockets
yarn add typesockets
bun add typesockets
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.6 |
| Published | 2022-06-12 |
| First published | 2022-06-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 9.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | newclarity |
| Maintainers | newclarityex |
| Keywords | websockets, ws, typesafe |

## Links

- npm: https://www.npmjs.com/package/typesockets
- Repository: https://github.com/newclarityex/typesockets
- Issues: https://github.com/newclarityex/typesockets/issues
- npm.io page: https://npm.io/package/typesockets

## Dependencies (1)

- [ws](https://npm.io/package/ws.md) ^8.8.0

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 1.0.6 (latest) — 2022-06-12
- 1.0.5 — 2022-06-12
- 1.0.4 — 2022-06-12
- 1.0.3 — 2022-06-12
- 1.0.2 — 2022-06-11
- 1.0.1 — 2022-06-11
- 1.0.0 — 2022-06-11

## README

#  TypeSockets
An end-to-end typesafe websockets wrapper/addon through the creation of client and server endpoint functions.

## Installing
Install this module with `yarn add typesockets` or `npm i typesockets`.

## Importing
### Node
```TS
const { createServer, createServerEndpoints, createClientEndpoints } = require("typesockets");
```
### ES6
```TS
import { createServer, createServerEndpoints, createClientEndpoints } from "typesockets";
```
The following documentation will follow the ES6 syntax.

## Creating the Server
Create the server by using the very thin wrapper function `createServer`.
<br/>
It uses the same options as the node `ws` module, and returns a WebsocketServer as it is just a wrapper.
<br/>
https://github.com/websockets/ws/blob/HEAD/doc/ws.md#class-websocketserver
### server.ts
```TS
const server = createServer({ port: 8081 });
```

## Creating the Client
Create the client by using the W3C standard for websockets:
<br/>
https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket
<br/>
### client.ts
```TS
const socket = new Websocket("ws://server-ws.url");
```

## Server Endpoints
Server endpoints are functions that run on the server and are called from the client. To create these endpoints, run the `createServerEndpoints` function with the websocket server and a dictionary of functions as parameters. These endpoints can then be exported to be used client side. Then hydrate the functions with their actual functionality and attach it to the server.

### serverEndpoints.ts
Creating the endpoints using empty functions with needed parameters
```TS
import { createServerEndpoints } from "typesockets";

export const serverEndpoints = createServerEndpoints( {
    log: (msg: string) => { }
});
```

### server.ts
Hydrating and attaching the endpoints to the websocket server
```TS
import { serverEndpoints } from "../path/to/serverEndpoints.ts";

// Hydrating the functions
const hydrated = serverEndpoints.hydrate({
    log: (ws: Websocket, msg: string) => {
        console.log(string);
    }
});

// Create server
const server = createServer({ port: 8081 });

// Attach the newly hydrated functions to run on server
hydrated.attachServer(server);
```

### client.ts
Calling the server endpoints from the client
```TS
import { serverEndpoints } from "../path/to/serverEndpoints.ts";

// Use the converted functions from the server endpoints
const extractedEndpoints = serverEndpoints.extracted;

// Create client
const socket = new Websocket("ws://server-ws.url");

// Sends websocket request to server to run command 'log' with parameter "Hello World" as msg
extractedEndpoints.log(socket, "Hello World!");
```

## Client Endpoints
Client endpoints are similar to server endpoints, but instead call client functions from the server and do not require hydration, but still need to be attached.

### clientEndpoints.ts
Creating the client functions does not require a hydration step, just directly create the functions that need to be run
```TS
// Create the functions directly
export const clientEndpoints = createClientEndpoints({
    log: (msg: string) => {
        console.log(msg);
    }
});
```

### client.ts
Attaching the client endpoints to the websocket client
```TS
import { clientEndpoints } from "../path/to/clientEndpoints.ts";

// Create client
const socket = new Websocket("ws://server-ws.url");

// Attach client to endpoints
clientEndpoints.attachClient(socket);
```

### server.ts
Calling the client endpoints from the server
```TS
import { clientEndpoints } from "../path/to/clientEndpoints.ts";

// Create server
const server = createServer({ port: 8081 });

// Use the converted functions from the client endpoints
const extractedEndpoints = clientEndpoints.extracted;

// If we wanted to broadcast the log function to all clients
server.clients.forEach((client) => {
    // Sends websocket request to run log on every connected client
    extractedEndpoints.log(client, "Hello World");
});
```

## Example
TODO

---
_Source: https://npm.io/package/typesockets · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._