# yws

> WebSocket Server/Client Wrapper

Latest version **0.0.3** (published 2021-12-27) · MIT license · 0 weekly downloads

## Install

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

## Health

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

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

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.3 |
| Published | 2021-12-27 |
| First published | 2021-12-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 10.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | kocisov |
| Maintainers | kocisov |
| Keywords | Client, Server, WebSocket, Wrapper |

## Links

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

## Dependencies (2)

- [nanoid](https://npm.io/package/nanoid.md) ^3.1.30
- [isomorphic-ws](https://npm.io/package/isomorphic-ws.md) ^4.0.1

## 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

- 0.0.3 (latest) — 2021-12-27
- 0.1.0-next.2 (next) — 2022-12-16
- 0.1.0-next.1 — 2022-12-16
- 0.1.0-next.0 — 2022-12-15
- 0.0.2 — 2021-12-26
- 0.0.1 — 2021-12-26

## README

# yws

> WebSocket Server/Client Wrapper

**🚧 The API is currently changing frequently.**

### Installation

```bash
$ (npm/yarn/pnpm) add yws
```

### Example

> WS server

```ts
import { Server } from "ws";
import { createTypedFunctions } from "yws/server";

const wss = new Server({
  port: 3000,
  clientTracking: false,
  maxPayload: 64 * 1024,
});

type Incoming = {
  type: "ping";
};

type Outgoing =
  | {
      type: "acknowledgement";
      id: string;
    }
  | {
      type: "pong";
    };

const { wrap } = createTypedFunctions<Incoming, Outgoing>();

wss.on("connection", (socket) => {
  const ws = wrap(socket);

  ws.commit({
    type: "acknowledgement",
    id: ws.id,
  });

  ws.onMessage(async (data) => {
    if (data.type === "ping") {
      ws.commit({
        type: "pong",
      });
    }
  });
});
```

> Fastify server

```ts
import fastify from "fastify";
import websocketPlugin from "fastify-websocket";
import { createTypedFunctions } from "yws/server";

type Incoming = {
  t: "ping";
};

type Outgoing =
  | {
      t: "ack";
      id: string;
    }
  | {
      t: "pong";
    }
  | {
      t: "hello";
      f: string;
    };

const { wrap, broadcast } = createTypedFunctions<Incoming, Outgoing>();

export const app = fastify()
  .register(websocketPlugin)
  .route({
    url: "/",
    method: "GET",
    handler(_req, res) {
      res.send("ok");
    },
    wsHandler(connection) {
      const ws = wrap(connection.socket);

      ws.commit({
        t: "ack",
        id: ws.id,
      });

      ws.onMessage(async (data) => {
        if (data.t === "ping") {
          ws.commit({ t: "pong" });
        }
      });
    },
  });

setInterval(() => {
  broadcast({
    t: "hello",
    f: "broadcast",
  });
}, 5000);

app.listen(3000);
```

> Client

```ts
import { createClient } from "yws";

type Incoming = {
  t: "pong";
};

type Outgoing =
  | {
      t: "ping";
    }
  | {
      t: "hello";
      d: string;
    };

const ws = createClient<Incoming, Outgoing>({
  url: "ws://localhost:3000",
  onMessage(data) {
    if (data.t === "pong") {
      console.log("Heartbeat successful.");
    }
  },
  heartBeat: {
    shape: {
      t: "ping",
    },
    interval: 25_000,
  },
});

ws.commit({
  t: "hello",
  d: "lorem ipsum...",
});
```

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