You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+123-3Lines changed: 123 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -40,7 +40,8 @@ import {PackMe, PackMeMessage} from 'packme';
40
40
// ... whatever code goes here
41
41
42
42
let packMe =newPackMe();
43
-
packMe.register(manifestMessageFactory); // Required by PackMe to create class instances while unpacking messages
43
+
// Register class factory to make PackMe able to create class instances while unpacking messages
44
+
packMe.register(manifestMessageFactory);
44
45
45
46
let request =GetUserRequest('a7db84cc2ef5012a6498bc64334ffa7d');
46
47
socket.send(packMe.pack(request)); // Some socket implementation
@@ -60,16 +61,135 @@ import {PackMe, PackMeMessage} from 'packme';
60
61
// ... whatever code goes here
61
62
62
63
let packMe =newPackMe();
63
-
packMe.register(manifestMessageFactory); // Required by PackMe to create class instances while unpacking messages
64
+
// Register class factory to make PackMe able to create class instances while unpacking messages
65
+
packMe.register(manifestMessageFactory);
64
66
65
67
server.listen((/** Uint8Array */data, /** SomeSocket */socket) => { // Some server implementation
66
68
let message =packMe.unpack(data);
67
69
if (message instanceof GetUserRequest) {
68
70
let response =GetUserResponse('Peter', 'Hollens', 39);
71
+
// Or: let response = message.$response('Peter', 'Hollens', 39);
69
72
socket.send(packMe.pack(response));
70
73
}
71
74
});
72
75
```
73
76
77
+
## Messages
78
+
There are two types of messages: single messages and request / response messages. Single message is declared as an array with single object in JSON:
79
+
```json
80
+
"update": [{
81
+
"field_1": "uint8",
82
+
"field_2": "uint8",
83
+
"field_3": "uint8"
84
+
}]
85
+
```
86
+
This will create class "UpdateMessage". Single messages are used when you need to send some data one way, for example, periodic updates. Request / response messages are declared as an array with two objects:
87
+
```json
88
+
"get_something": [{
89
+
"field_1": "uint8",
90
+
}, {
91
+
"field_1": "uint8",
92
+
"field_2": "uint8",
93
+
"field_3": "uint8"
94
+
}]
95
+
```
96
+
This will generate two classes: "GetSomethingRequest" and "GetSomethingResponse". Request class will have method $response(...) which returns an instance of response class.
97
+
98
+
## Optional fields
99
+
By default, all fields are required. In order to declare an optional field, use "?" prefix:
100
+
```json
101
+
"?something_optional": "string"
102
+
```
103
+
Using optional fields is a good way to optimize resulting packet size since PackMe does not store any data for null valued fields.
104
+
105
+
## Types
106
+
You can declare fields of standard type (such as uint32, double, string), custom type (declared enums or objects) or nested object type.
107
+
108
+
### Integer types
109
+
- uint8 - 8 bits (from 0 to 255)
110
+
- int8 - 8 bits (from -128 to 127)
111
+
- uint16 - 16 bits (from 0 to 65,535)
112
+
- int16 - 16 bits (from -32,768 to 32,767)
113
+
- uint32 - 8 bits (from 0 to 4,294,967,295)
114
+
- int32 - 8 bits (from -2,147,483,648 to 2,147,483,647)
115
+
- uint64 - 8 bits (from 0 to 18,446,744,073,709,551,615)
116
+
- int64 - 8 bits (from -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807)
Note that using bool type is more efficient than uint8 since it requires only 1 bit and PackMe stores all bool fields together (up to 8 fields per byte).
127
+
128
+
### String
129
+
```json
130
+
"parameter": "string"
131
+
```
132
+
All strings are interpreted and stored as UTF-8 strings.
133
+
134
+
### Date
135
+
```json
136
+
"event_date": "datetime"
137
+
```
138
+
Date is packed as 64-bit signed integer (number of milliseconds that have elapsed since the Unix epoch).
139
+
140
+
### Enum
141
+
Enum is a custom type you can declare in the same JSON manifest file or in the separate one. Enum is declared as an array of strings:
142
+
```json
143
+
"message_status": [
144
+
"sent",
145
+
"delivered",
146
+
"read",
147
+
"unsent"
148
+
]
149
+
```
150
+
It will generate enum "MessageStatus". In order to declare a field of enum type use "@" as a type prefix:
151
+
```json
152
+
"status": "@message_status"
153
+
```
154
+
155
+
### Object
156
+
Like enums objects can be declared in any JSON file. It will be accessible for all manifest files. Object is declared as an object:
157
+
```json
158
+
"user_profile": {
159
+
"first_name": "string",
160
+
"last_name": "string",
161
+
"birth_date": "datetime"
162
+
}
163
+
```
164
+
It will generate class "UserProfile". In order to declare a field of object type use "@" as a type prefix:
165
+
```json
166
+
"profile": "@user_profile"
167
+
```
168
+
169
+
### Nested object
170
+
It is possible to use nested objects as field types:
171
+
```json
172
+
"send_update": [{
173
+
"values": {
174
+
"min": "double",
175
+
"max": "double"
176
+
},
177
+
"rates": [{
178
+
"a": "float",
179
+
"b": "float",
180
+
"c": "float"
181
+
}]
182
+
}]
183
+
```
184
+
In this case additional classes will be created: "SendUpdateMessageValues" and "SendUpdateMessageRate" which will be used as types for "values" and "rates" properties of "SendUpdateMessage" class.
185
+
186
+
## Arrays
187
+
If you need to declare a field as an array of specific type, just put your type string into square brackets:
188
+
```json
189
+
"numbers": ["uint32"],
190
+
"names": ["string"],
191
+
"users": ["@user"]
192
+
```
193
+
74
194
## Supported platforms
75
-
Now it's only for Dart and JavaScript. Will there be more platforms? Well it depends... If developers will find this package useful then it will be implemented for C++ I guess.
195
+
Now it's available for Dart and JavaScript. Will there be more platforms? Well it depends... If developers will find this package useful then it will be implemented for C++ I guess.
0 commit comments