Turn any async generator / function into a Websocket stream in 2 lines.
npm install socket-generatorTurn any JS/TS async generator / function into a typed Websocket stream in 2 lines.


!Build Passing
There wasn't any easy way to turn my server's simple async generator functions into a Websocket stream without a lot of fuss, and Socket.io is
arguably the best Websocket streaming library, so why not make it easy to glue them together!? Also,
- Mix and match plain async functions with async generators
- Bi-directional: frontends can be endpoints and servers can be clients, if you want
- Request / Response paradigm you're used to, but over Websockets with fallback to HTTP long polling
- Same mechanics you know and love from async generators, try/catch error handling etc.
- Zero dependencies (except implicitly on Socket.io >= v4)
- 100% line + branch test coverage, because you deserve it :-)
#### Define an async generator function for streaming (usually only on the server)
```
async function* wordGenerator(input: string) {
const words = input.split(' ');
for (const word of words) {
yield word;
}
}
#### Define a shared contract where client sends 1 string parameter and endpoint streams / yields strings back
``
const helloContract = newContract<[string], string, undefined>('hello');
#### Define a client (usually just on the frontend) that can issue requests
``
const helloClient = helloContract.newClient(clientSocket, 1);
#### Define an endpoint (usually just on the server) that can respond to requests and define the generator function
``
helloContract.newEndpoint(wordGenerator).bindClient(serverSocket);
#### Client streams the server's wordGenerator function remotely as if it was local!
``
const wordGenerator = helloClient('hello world');
for await (const word of wordGenerator) {
console.log(word);
}
See __tests__/examples.test.ts for all advanced usages and how to create Socket.io client / server sockets
Javascript note: If you're not using Typescript :-(, just remove anywhere you see <> in example code and it'll work just the same, though
you won't get typing benefits of a shared client / server Contract.
Just install the NPM package with:
``
npm i socket-generator
Creates a new Contract which is a shared type agreement between Socket.io client and endpoints. Because Socket.io is bidirectional, front-ends may be endpoints and servers may be clients too! A client
initializes a request by sending PARAMS and the endpoint responds with a stream of YIELDs ending in a RETURN.
@param uniqueName A unique name for this Socket.io client / endpoint contract
@returns A Contract instance that either client or endpoint can further instantiate with more context
``
function newContract
type Contract = {
newClient: (
socket: ClientSocket,
timeoutMs?: number) => ClientFn,
newEndpoint: (
responseGenerator: (...req: PARAMS) => AsyncGenerator | Promise,
logger?: (msg: string) => void) => Endpoint
}
`$3
An instance of an async generator that can be iterated to stream YIELDs from the parent Contract's endpoint, ending with a RETURN value when done
`
type ClientFn = (
...req: PARAMS
) => AsyncGenerator
`$3
After initializing contract.newEndpoint, you can bind many incoming clients' sockets to the new Endpoint by calling bindClient.
`
type Endpoint = {
bindClient: (socket: ServerSocket) => void
}
`Supported parameter / yield return types
Since all data must be passed over the wire, only JSON-supported types are allowed, except
for the special case of
yielding or returning undefined`, which is supported on topSee official Socket.io v4 documentation.
I can't think of what more this lib needs but if you can think of something cool, open a pull request or Issue.