JSON.md

JSON serialization

nstructjs can serialize to JSON in addition to its binary format. The same registered classes and STRUCT scripts are used for both.

API

• nstructjs.writeJSON(obj) — serialize an object to a plain JSON-compatible object.
• nstructjs.readJSON(json, classOrStructId, migrate?) — read an instance back from JSON. With a migrate option ({ version, warnMissing?, reporter? }), runs migrateJSON on json in place before reading; see Migration.
• nstructjs.formatJSON(json, cls, addComments?, validate?) — pretty-print JSON, optionally with field comments and validation.
• nstructjs.validateJSON(json, cls, useInternalParser?, printColors?, logger?) — validate a JSON payload against a struct definition. With useInternalParser (the default) the internal parser produces nicer error messages.

Example

class AbstractClass {
  constructor() {
    this.value = 1;
  }

  loadSTRUCT(reader) {
    reader(this);
  }
}
AbstractClass.STRUCT = nstructjs.inlineRegister(
  AbstractClass,
  `
  AbstractClass {
    value : int;
  }
`
);

// Subclasses inherit the parent's fields automatically with inlineRegister —
// no need to repeat them or call the deprecated nstructjs.inherit.
class A extends AbstractClass {}
A.STRUCT = nstructjs.inlineRegister(A, `A {}`);

class B extends AbstractClass {}
B.STRUCT = nstructjs.inlineRegister(B, `B {}`);

class C extends AbstractClass {}
C.STRUCT = nstructjs.inlineRegister(C, `C {}`);

class Test {
  constructor() {
    this.test = new C();
  }

  loadSTRUCT(reader) {
    reader(this);
  }
}
Test.STRUCT = nstructjs.inlineRegister(
  Test,
  `
  Test {
    test : abstract(AbstractClass, "type");
  }
`
);

Note the "type" parameter in the abstract keyword — it controls which field in the JSON object stores the object type. (If omitted, _structName is used; see the Specification.)

To save, use nstructjs.writeJSON:

nstructjs.writeJSON(new Test());

It produces:

{
  "test": {
    "value": 1,
    "type" : "C"
  }
}

To read it back, use nstructjs.readJSON with the target class (or its struct id):

const test = nstructjs.readJSON(json, Test);

Migration

A struct or field renamed since the JSON was written needs migrateSTRUCT to reshape the data before readJSON matches JSON keys against the current schema — see Migration for migrateSTRUCT, readJSON's migrate option, and struct-rename resolution for abstract(...) fields.