@project-agonyl/agonyl-utils
v1.3.0
Published
Assorted set of Javascript utilities that can used for developing tools and services for A3 Online
Downloads
6
Readme
Agonyl Utils
Assorted set of NodeJS utilities that can used for developing tools and services for A3 Online.
Usage
Install the package using NPM:
npm i @project-agonyl/agonyl-utils
Set experimentalDecorators
to true
in your tsconfig.json
file:
{
"compilerOptions": {
"experimentalDecorators": true
}
}
Documentation
Utility Classes
Serializable
A serializable class utility. It provides a serialize()
method that returns a binary
representation of the class and a deserialize()
method that takes a binary representation and populates the class.
Usage:
import { Serializable, meta } from '@project-agonyl/agonyl-utils';
class MySubSerializable extends Serializable {
@meta({
type: 'string',
order: 1,
length: 20
})
public mySubProperty: string = '';
}
class MySerializable extends Serializable {
@meta({
type: 'string',
order: 1,
length: 20
})
public myProperty: string = '';
@meta({
type: 'serializable',
order: 2,
length: 20
})
public mySubSerializable: MySubSerializable = new MySubSerializable();
@meta({
type: 'byte',
order: 3,
isArray: true,
arraySize: 2,
})
public myByteArray: number[] = [];
}
// Serialize
const mySerializable = new MySerializable();
mySerializable.myProperty = 'Hello World!';
mySerializable.mySubSerializable.mySubProperty = 'Hello Sub World!';
mySerializable.myByteArray = [0x01, 0x02];
const serialized = mySerializable.serialize();
// Deserialize
const deserializable = new MySerializable();
deserializable.deserialize(serialized);
console.log(deserializable.myProperty); // 'Hello World!'
console.log(deserializable.mySubSerializable.mySubProperty); // 'Hello Sub World!'
console.log(deserializable.myByteArray); // [0x01, 0x02]
Here the meta decorator is used to define the serialization order, type and length of the property. If meta is not defined, the property will be ignored during serialization.
The following types are supported:
- string
- number
- boolean
- byte
- short
- int
- int16
- int32
- int64
- serializable
Arrays are now supported as a serializable class property by setting isArray
and arraySize
meta properties
(except for serializable type).
SerializableWithAutoSetSize
A serializable class utility that automatically sets the size of the serialized data during serialization.
Usage:
import { SerializableWithAutoSetSize, meta } from '@project-agonyl/agonyl-utils';
class MySerializable extends SerializableWithAutoSetSize {
@meta({
type: 'int',
order: 1
})
public size: number = 0;
@meta({
type: 'string',
order: 2,
length: 20
})
public myProperty: string = '';
}
// Serialize
const mySerializable = new MySerializable();
mySerializable.myProperty = 'Hello World!';
const serialized = mySerializable.serialize();
// Deserialize
const deserializable = new MySerializable();
deserializable.deserialize(serialized);
console.log(deserializable.myProperty); // 'Hello World!'
It is important to note that the size property must be defined in the class and must be the first property in the serialization order. The size property will be overwritten during serialization even if it is defined.
BinaryReader
A utility class that provides methods to read binary data from a buffer/file.
Usage:
import { BinaryReader } from '@project-agonyl/agonyl-utils';
// From file
const fileReader = new BinaryReader('path/to/file');
while (!fileReader.isEndOfBuffer()) {
console.log(fileReader.readString(20));
}
// From buffer
const bufferReader = new BinaryReader(buffer);
while (!bufferReader.isEndOfBuffer()) {
console.log(bufferReader.readString(20));
}
// From file with custom offset
const fileReaderOffset = new BinaryReader('path/to/file', 100);
while (!fileReaderOffset.isEndOfBuffer()) {
console.log(fileReaderOffset.readString(20));
}
// From file with big endian byte order
const fileReaderBigEndian = new BinaryReader('path/to/file', 0, 'BE');
while (!fileReaderBigEndian.isEndOfBuffer()) {
console.log(fileReaderBigEndian.readString(20));
}
Default byte order is little endian.
Utility functions
| Function | Description |
|------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| getBytesFromNumberLE(num: number, bytes = 4): number[]
| Returns a buffer with the specified number of bytes in little endian format. |
| getBytesFromString(str: string): number[]
| Returns a buffer with the string in UTF-8 format. |
| getFixedLengthBytesFromString(str: string, length: number): number[]
| Returns a buffer with the string in UTF-8 format with the specified length. |
| getPrettySizeFromBytes(bytes: number): string
| Returns a human readable string from the specified number of bytes. |
| isValidJsonString(str: string): boolean
| Returns true if the string is a valid JSON string. |
| getStringFromBuffer(buffer: Buffer, start: number, length: number): string
| Returns a string from the specified buffer. |