Data-oriented Serialization for SoA/AoA

A zero-dependency serialization library for data-oriented design structures like SoA (Structure of Arrays) and AoA (Array of Arrays).

Features

• DataWriter: Serializes data from SoA object(s) to binary data provided array of indices to extract data from
• DataReader: Deserializes from binary data to SoA object(s) to the appropriate indices
• Binary data packed in an AoS-like format for optimal space efficiency
• ID mapping included for reading/writing data from/to different sets of indices
• Includes snapshot and delta modes
  • Snapshot mode serializes the entire state (default)
  • Delta mode only serializes state that has changed since the last serialization call

Planned

• Support for AoA serialization
• More flexible API
  • Schemas
  • Ability to pass in ArrayBuffers to write to

Example

importassertfrom'assert'import{createDataWriter,createDataReader}from'@webecs/do-serialization'/* SoA Object */constn=100constTransform={position: {x: newFloat32Array(n),y: newFloat32Array(n),z: newFloat32Array(n),},rotation: {x: newFloat32Array(n),y: newFloat32Array(n),z: newFloat32Array(n),},}/* Config */// a simple array of SoA objects acts as the configurationconstconfig=[Transform]/* Snapshot Mode */// DataWriter and DataReader must have the same config in order to function correctlyconstwrite=createDataWriter(config)constread=createDataReader(config)// initialize SoA stateconste=0Transform.position.x[e]=1Transform.position.y[e]=2Transform.position.z[e]=3// serializeletdata=write([e])// reset SoA stateTransform.position.x[e]=0Transform.position.y[e]=0Transform.position.z[e]=0// deserializeread(data)// assert data was deserialized onto SoA stateassert(Transform.position.x[e]===1)// trueassert(Transform.position.y[e]===2)// trueassert(Transform.position.z[e]===3)// true/* Delta Mode */// true value for second parameter enables delta mode (needed for both writer & reader)constwriteDeltas=createDataWriter(config,true)constreadDeltas=createDataReader(config,true)Transform.position.x[e]=0Transform.position.y[e]=0Transform.position.z[e]=0// serializedata=writeDeltas([e])assert(data.byteLength===0)// true, no changes made to the data// mutate SoA stateTransform.position.x[e]=1Transform.position.y[e]=2Transform.position.z[e]=3// serializedata=writeDeltas([e])assert(data.byteLength>0)// true, changes have been made to the data since the last call// reset SoA stateTransform.position.x[e]=0Transform.position.y[e]=0Transform.position.z[e]=0// deserializereadDeltas(data)// assert changed data was deserialized onto SoA stateassert(Transform.position.x[e]===1)// trueassert(Transform.position.y[e]===2)// trueassert(Transform.position.z[e]===3)// true/* ID Mapping */constidMap=newMap([[0,12]])// this will write index 0 from the SoA object as index 12 in the binary datadata=write([e],idMap)// this will read index 0 from the binary data to index 12 on the SoA objectread(data,idMap)