Home

Awesome

oson structured object notation

json has a bunch of problems.

oson fixes them.

installation

oson is on jsr.

features

oson can encode circular references:

const obj = {};
obj.self = obj;
JSON.stringify(obj); // error
oson.stringify(obj); // works!

oson can encode repeated references:

const obj = {};
const arr = [obj, obj];
const [left, right] = JSON.parse(JSON.stringify(arr));
assertStrictEquals(left, right); // error
const [l, r] = oson.parse(oson.stringify(arr));
assertStrictEquals(l, r); // works!

oson can encode undefined:

const undef = oson.parse(oson.stringify(undefined));
assertStrictEquals(undef, undefined);

oson can encode sparse arrays:

const arr = [5, , , , 6, , , 7];
console.log(oson.parse(oson.stringify(arr)));
// [ 5, <3 empty items>, 6, <2 empty items>, 7 ]

oson can encode bigint:

const num = 10n ** 1000n;
JSON.stringify(num); // error
oson.stringify(num); // works!

oson can encode class instances of the following built-in types:

oson can encode class instances of your custom classes:

class A {
  constructor(public prop: string) {}
}
const serializer: ValueConstructor<A, string> = {
  instance: A,
  from: (a) => [a.prop],
  create: ([prop]) => new A(prop),
};

GLOBAL_CONSTRUCTOR_MAP.set(A.name, serializer);

const a = new A("str");

assertInstanceOf(JSON.parse(JSON.stringify(a)), A); // error
assertInstanceOf(oson.parse(oson.stringify(a)), A); // works!

see also this type definition for classes that are containers for object values (which may lead to circular references).

oson provides listify and delistify which can be used to convert objects to a representation that JSON accepts.

const num = 10n;
JSON.stringify(num); // error
JSON.stringify(oson.listify(num)); // works!

this lets you avoid repeated serialization.

non-goals

the following things are explicitly not supported.

and they never will be, because they can never work well.

name

the oson in the name stands for oson structured object notation.

written from scratch, based on ideas in ARSON.