vortez-io 2.0.0 → 2.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
# Vortez IO
|
|
1
|
+
# Vortez IO
|
|
2
2
|
|
|
3
|
-
`vortez-io
|
|
3
|
+
`vortez-io` is a small TypeScript library for encoding and decoding the Vortez IO binary frame format used over WebSocket connections. It implements the protocol described in [PROTOCOL.md](PROTOCOL.md) and provides helpers for request/response correlation, event delivery, and strict frame validation.
|
|
4
4
|
|
|
5
5
|
## Features
|
|
6
6
|
|
|
@@ -10,6 +10,7 @@
|
|
|
10
10
|
- Support for `BINARY`, `JSON`, `LINE`, and `CUSTOM` payload modes
|
|
11
11
|
- Strict protocol validation with typed errors
|
|
12
12
|
- Higher-level typed wrapper via `VIOStrict`
|
|
13
|
+
- Transport-agnostic runtime with a small, composable API surface
|
|
13
14
|
|
|
14
15
|
## Installation
|
|
15
16
|
|
|
@@ -22,8 +23,7 @@ The library is published from the TypeScript source in this repository and targe
|
|
|
22
23
|
## Quick Start
|
|
23
24
|
|
|
24
25
|
```ts
|
|
25
|
-
import VIO from '
|
|
26
|
-
import VIOError from './build/VIOError.js';
|
|
26
|
+
import VIO, { VIOError } from 'vortez-io';
|
|
27
27
|
|
|
28
28
|
const vio = new VIO({
|
|
29
29
|
setTimeout,
|
|
@@ -66,6 +66,7 @@ The main transport-aware protocol runtime.
|
|
|
66
66
|
- `event(name, data)`: send an event frame
|
|
67
67
|
- `handle(data)`: decode an incoming frame and dispatch it
|
|
68
68
|
- `transport`: event emitter that exposes outgoing frames through `send`
|
|
69
|
+
- `raw(data)`: send transport-level bytes without higher-level framing
|
|
69
70
|
|
|
70
71
|
### `Frame`
|
|
71
72
|
|
|
@@ -80,6 +81,10 @@ Use this when you need direct access to protocol bytes instead of the higher-lev
|
|
|
80
81
|
|
|
81
82
|
Typed wrapper for validating request and event payloads with schemas from `@netfeez/common`.
|
|
82
83
|
|
|
84
|
+
## Architecture Guide
|
|
85
|
+
|
|
86
|
+
For a higher-level view of the runtime layers, message flow, and the role of `VIO`, `Frame`, `RequestManager`, and `VIOStrict`, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
|
|
87
|
+
|
|
83
88
|
## Protocol Summary
|
|
84
89
|
|
|
85
90
|
The protocol is described in detail in [PROTOCOL.md](PROTOCOL.md). In short:
|
|
@@ -90,9 +95,12 @@ The protocol is described in detail in [PROTOCOL.md](PROTOCOL.md). In short:
|
|
|
90
95
|
- `EVENT` frames use string identifiers
|
|
91
96
|
- `ERROR` frames can be protocol-level (`NONE`) or request-bound (`UUID`)
|
|
92
97
|
|
|
93
|
-
##
|
|
98
|
+
## Documentation Map
|
|
94
99
|
|
|
95
|
-
|
|
100
|
+
- [README.md](README.md): project overview, install, and quick start.
|
|
101
|
+
- [PROTOCOL.md](PROTOCOL.md): wire format and protocol rules.
|
|
102
|
+
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): runtime layers and message flow.
|
|
103
|
+
- [docs/VIOStrict.md](docs/VIOStrict.md): typed wrapper example and schema map wiring.
|
|
96
104
|
|
|
97
105
|
## Development
|
|
98
106
|
|
|
@@ -9,7 +9,7 @@ import VIOError from "../../VIOError.js";
|
|
|
9
9
|
import Channel from "./Channel.js";
|
|
10
10
|
export const RRSchema = Schema.fromObject({
|
|
11
11
|
name: { type: 'string', required: true },
|
|
12
|
-
content: { type: 'object', required: true }
|
|
12
|
+
content: { type: 'object', allowAdditionalProperties: true, required: true }
|
|
13
13
|
});
|
|
14
14
|
export class RequestChannel extends Channel {
|
|
15
15
|
VIO;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"RequestChannel.js","sourceRoot":"","sources":["../../../src/strict/channel/RequestChannel.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,QAAQ,MAAM,mBAAmB,CAAC;AAEzC,OAAO,OAAO,MAAM,cAAc,CAAC;AAKnC,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC;IACtC,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;IACxC,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;
|
|
1
|
+
{"version":3,"file":"RequestChannel.js","sourceRoot":"","sources":["../../../src/strict/channel/RequestChannel.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# VIOStrict Example
|
|
2
|
+
|
|
3
|
+
This document shows how to build a typed wrapper around Vortez IO using `VIOStrict`.
|
|
4
|
+
|
|
5
|
+
The goal is the same as in a real application: define your schema maps once, keep request and event payloads typed, and let the strict wrapper validate traffic at the boundary.
|
|
6
|
+
|
|
7
|
+
## When To Use It
|
|
8
|
+
|
|
9
|
+
- You want named, schema-validated events.
|
|
10
|
+
- You want request and response shapes enforced at the call site.
|
|
11
|
+
- You want one place to wire transport, validation, and typed channels together.
|
|
12
|
+
|
|
13
|
+
## Example
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import { Schema } from '@netfeez/common';
|
|
17
|
+
import { VIOStrict } from 'vortez-io';
|
|
18
|
+
|
|
19
|
+
const dependencies = {
|
|
20
|
+
setTimeout,
|
|
21
|
+
clearTimeout,
|
|
22
|
+
};
|
|
23
|
+
|
|
24
|
+
export const clientEvents = {
|
|
25
|
+
message: Schema.fromObject({
|
|
26
|
+
user: { type: 'object', required: true, properties: {
|
|
27
|
+
username: { type: 'string', required: true },
|
|
28
|
+
role: { type: 'string', enum: ['system', 'admin', 'user'], default: 'user' },
|
|
29
|
+
avatar: { type: 'string', default: '/favicon.ico' }
|
|
30
|
+
} },
|
|
31
|
+
message: { type: 'string', required: true }
|
|
32
|
+
}),
|
|
33
|
+
'writing-started': Schema.fromObject({
|
|
34
|
+
username: { type: 'string', required: true }
|
|
35
|
+
}),
|
|
36
|
+
'writing-stopped': Schema.fromObject({
|
|
37
|
+
username: { type: 'string', required: true }
|
|
38
|
+
})
|
|
39
|
+
} satisfies VIOStrict.EMap;
|
|
40
|
+
|
|
41
|
+
export const serverEvents = {
|
|
42
|
+
...clientEvents,
|
|
43
|
+
message: Schema.fromObject({
|
|
44
|
+
message: { type: 'string', required: true }
|
|
45
|
+
}),
|
|
46
|
+
} satisfies VIOStrict.EMap;
|
|
47
|
+
|
|
48
|
+
export const clientRequests = {
|
|
49
|
+
} satisfies VIOStrict.RRMap;
|
|
50
|
+
|
|
51
|
+
export const serverRequests = {
|
|
52
|
+
} satisfies VIOStrict.RRMap;
|
|
53
|
+
|
|
54
|
+
export class ChatClient extends VIOStrict<
|
|
55
|
+
number,
|
|
56
|
+
typeof serverEvents,
|
|
57
|
+
typeof clientEvents,
|
|
58
|
+
typeof clientRequests,
|
|
59
|
+
typeof serverRequests
|
|
60
|
+
> {
|
|
61
|
+
public constructor() {
|
|
62
|
+
super(dependencies, serverEvents, clientEvents, clientRequests, serverRequests);
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## How It Maps To The Runtime
|
|
68
|
+
|
|
69
|
+
- `dependencies` provides the timeout functions used by `RequestManager` through `VIO`.
|
|
70
|
+
- `serverEvents` defines what this client can receive.
|
|
71
|
+
- `clientEvents` defines what this client can send.
|
|
72
|
+
- `serverRequests` defines the requests this client can receive.
|
|
73
|
+
- `clientRequests` defines the requests this client can send.
|
|
74
|
+
|
|
75
|
+
`VIOStrict` composes the underlying `VIO` instance and exposes three typed channels:
|
|
76
|
+
|
|
77
|
+
- `event` for schema-validated events.
|
|
78
|
+
- `request` for schema-validated request/response flows.
|
|
79
|
+
- `transport` for raw byte transport and low-level frame wiring.
|
|
80
|
+
|
|
81
|
+
## Typical Wiring
|
|
82
|
+
|
|
83
|
+
In a real application, you would connect the transport channel to your socket adapter:
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
const chat = new ChatClient();
|
|
87
|
+
|
|
88
|
+
chat.transport.on('send', (frame) => {
|
|
89
|
+
websocket.send(frame);
|
|
90
|
+
});
|
|
91
|
+
|
|
92
|
+
websocket.onmessage = (event) => {
|
|
93
|
+
chat.transport.handle(event.data);
|
|
94
|
+
};
|
|
95
|
+
|
|
96
|
+
chat.event.on('message', (data) => {
|
|
97
|
+
console.log('message from server:', data);
|
|
98
|
+
});
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## Notes
|
|
102
|
+
|
|
103
|
+
- Keep the schema maps in the same file or a nearby support module when the contract is small.
|
|
104
|
+
- Split them into separate modules once the application grows.
|
|
105
|
+
- Prefer `event.custom(...)` or `request.send(...)` only when you intentionally want to bypass the typed surface.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "vortez-io",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.1",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Binary WebSocket protocol for multiplexed events, requests, responses, and errors in Vortez or other applications.",
|
|
6
6
|
"main": "build/index.js",
|
|
@@ -41,6 +41,6 @@
|
|
|
41
41
|
],
|
|
42
42
|
"license": "Apache-2.0",
|
|
43
43
|
"dependencies": {
|
|
44
|
-
"@netfeez/common": "^3.
|
|
44
|
+
"@netfeez/common": "^3.2.1"
|
|
45
45
|
}
|
|
46
46
|
}
|