ACOS JSON Delta for Websocket Networking
Generate a delta of your JSON data of any changes, reducing your bandwidth bytes transmitted to players. When JSON delta is received at receiver, merge it with the previous JSON data.
This package is used in combination with the acos-json-encoder to maximize bandwidth reduction.
Installation
npm i acos-json-delta
Usage
CommonJS usage
const { delta, merge, hidden } = require("acos-json-delta");
ES6 usage
import {delta, merge, hidden} = require("acos-json-delta");
Delta and Merge example
//example JSON data
let defaultGame = {
state: {
board: [
[0, 2, 0, 2, 0, 2, 0, 2], //white
[2, 0, 2, 0, 2, 0, 2, 0],
[0, 2, 0, 2, 0, 2, 0, 2],
[0, 0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0, 0, 0],
[1, 0, 1, 0, 1, 0, 1, 0],
[0, 1, 0, 1, 0, 1, 0, 1],
[1, 0, 1, 0, 1, 0, 1, 0], //black
],
cells: ["", "", "", "", "", "", "", "", ""],
startPlayer: "",
},
players: {},
rules: {
bestOf: 5,
maxPlayers: 2,
},
next: {},
events: [],
};
// mutate the JSON data
let changed = JSON.parse(JSON.stringify(defaultGame));
changed.state.board[0][0] = 1;
changed.state.cells[0] = "x";
changed.state.cells[1] = "x";
changed.state.cells[2] = "o";
changed.players["joe"] = { name: "Joe", type: "x" };
delete changed.state.startPlayer;
// build a delta of the mutated JSON
let diff = delta(defaultGame, changed, {});
// print delta
console.log("------------------");
console.log("delta1: \n", JSON.stringify(diff, null, 2));
// merge the delta with previous
let merged = merge(defaultGame, diff);
// mutate the new JSON data again
changed = JSON.parse(JSON.stringify(merged));
delete changed.players.joe.type;
// build another delta of the JSON
diff = delta(merged, changed, {});
// print delta
console.log("------------------");
console.log("delta2: \n", JSON.stringify(diff, null, 2));
// merge the delta from mutated JSON with previous
merged = merge(merged, diff);
Example Output
The array changes appear complex, but when combined with acos-json-encoder they are efficiently optimized to use up minimum bytes. You can identify array deltas when their key is prefixed with #
.
Deletions of an object key are added to a key named $
with array of keys to be deleted on merge. See delta2 example below.
------------------
delta1:
{
"state": {
"#board": [
{
"index": 0,
"type": "nested",
"value": [
{
"index": 0,
"type": "setvalue",
"value": 1
}
]
}
],
"#cells": [
{
"index": 0,
"type": "setvalue",
"value": "x"
},
{
"index": 1,
"type": "setvalue",
"value": "x"
},
{
"index": 2,
"type": "setvalue",
"value": "o"
}
],
"$": [
"startPlayer"
]
},
"players": {
"joe": {
"name": "Joe",
"type": "x"
}
}
}
------------------
delta2:
{
"players": {
"joe": {
"$": [
"type"
]
}
}
}
Methods
delta(from, to, result)
Generate a delta between two JSON data
Parameters
- from (JSON object or array) - Data before mutation
- to (JSON object or array) - Data after mutation
- result (JSON object or array) - Data after merging the from/to
Returns
result is returned redundantly, for readability.
.
merge(from, delta)
Merge JSON data with a JSON delta
Parameters
- from (JSON object or array) - Data previously saved
-
delta (JSON object or array) - Delta JSON generated using the
delta
function
Returns
JSON data merged between the from
and the delta
.
.
hidden(json)
Parameters
- json (JSON object or array) - Data that will be mutated to delete objects
Deletes and extracts the keys marked as hidden. Keys with prefix _
are marked hidden.
Returns
Extracted hidden keys and values.