More strict notion of JSON-stringifiability for all properties

[eush77]

Currently the only requirement for data property is stringifiability which is defined as follows:

Its only limitation being that each property should by stringifyable: not throw when passed to JSON.stringify().

I think this is too broad, in particular because JSON.stringify won't usually throw:

> JSON.stringify({ foo: function () { console.log('foo') }})
'{}'
> JSON.stringify({ foo: undefined })
'{}'

I was worried about this when hacking on unist-builder-blueprint: there is no reliable way to compile functions to source code (with closures and stuff like heap references), so a more strict guarantee like "data and JSON.parse(JSON.stringify(data)) should be equivalent and interchangeable" or even deepEqual(JSON.parse(JSON.stringify(data)), data) would be helpful.

[wooorm]

how about using “valid JSON values” as the limitation?

only limitation being that each (nested) property houses a valid JSON value (string, number, object, array, true, false, or null)

• That leaves undefined, which I think should be valid too, but maybe that can be treated as JavaScript-implementation specific, where undefined is treated the same as no property when stringifying JSON.
• Or is this too strict? For example, Dates wouldn’t be possible.

[wooorm]

Regarding Dates (and other values with toJSON methods), maybe that can be left unspecified, as it’s JavaScript specific?

[wooorm]

And, a final thought: maybe the whole unist tree should be defined as JSON-stringifiable, not just data?

[eush77]

The question is what does "JSON-stringifiability" mean? It would be inconvenient to limit Unist properties to basic JSON types (e.g. Date as you mentioned), but I think we shouldn't allow functions or objects with custom prototypes because by that we lose the virtue of having a way to stringify Unist trees, save/transfer and parse back. Unist is a data format.

We can enforce that if we somehow specify that Unist utilities that use and store (for example) Dates in the tree must expect them to sometimes be JSON-stringified to a string:

function (node) {
  // Don't do this: node.date can be a string.
  //   node.date = node.date ? node.date : new Date;
  node.date = node.date ? new Date(node.date) : new Date;

  // ...
}

[eush77]

I'm not sure how to turn this into a specific requirement.

[wooorm]

I’d say it’s a bit weird to allow date to have a toJSON method, but not any other objects, why not allow everything?

[wooorm]

I agree that, if a Date is set as a value on a (nested) property, it should be handled in it’s Date form and its number form by utilities.

Can we require that all values in Unist are either JSON values or a serializer, meaning they have an appropriate accompanying JSON representation, which in JavaScript happens through a toJSON method? Plug-ins are required to work with both the non-serialized value (e.g., the Date object in ECMAScript) and the serialized value (e.g., the number timestamp in JSON)

[eush77]

I’d say it’s a bit weird to allow date to have a toJSON method, but not any other objects, why not allow everything?

Date was an example.

Can we require that all values in Unist are either JSON values or a serializer, meaning they have an appropriate accompanying JSON representation, which in JavaScript happens through a toJSON method.

Objects with custom prototypes can have no custom-defined toJSON method and still be serializable. This is more of a requirement for utilities and other users of Unist spec since it's impossible to know if JSON.stringify(obj) misses any detail.

Plug-ins are required to work with both the non-serialized value (e.g., the Date object in ECMAScript) and the serialized value (e.g., the number timestamp in JSON)

Are you saying that plug-ins are required to handle any property to be a string and be ready to (usually) JSON.parse, even when it's serializable in a strict sense? Or are properties parsed as JSON anyway and plug-ins must accept both value and JSON.parse(JSON.stringify(value))?
(Side note: Date serializes to ISO 8601 string as per ECMA spec)

[wooorm]

I think it’s okay for a project to define node.data.someDate in JavaScript as a Date, but it must handle both an ISO 8601 string (for some reason I mistakingly though it was a number...) and Dates in the input tree.

Then Unist would be just JSON values, other tools can use language-specific features (e.g., the case above for Dates) for other values, but only if those values are serializable to JSON values.

I was thinking of some examples, one would be a Unist syntax tree for CSS (CSSST?) which would define colours:

interface Color {
    red: number;
    green: number;
    blue: number;
}

...which could be implemented as follows:

function Color(r, g, b) {
  this.red = r;
  this.green = g;
  this.blue = b;
}

Color.prototype.toHSL //...

Color.prototype.toJSON = function() {
  // return [this.red, this.green, this.blue];
  // or
  return {red: this.red, green: this.green, blue: this.blue};
}

Not sure how useful that really would be, its all theoretical, but I can imagine something like this would be useful because there’re so many different colours functions in CSS... Although maybe utilities should be used for that.

Gist of it, I can imagine someone wants custom constructors and instances for some things, in JavaScript. This would be possible if all of Unist is JSON values, but tools are allowed to implement their own representation of those values, in which case utilities must handle both the Unist and the language-specific version of a value.

[eush77]

Color.prototype.toJSON = function() {
  return {red: this.red, green: this.green, blue: this.blue};
}

This is the default behavior of JSON.stringify for these objects, [this.red, this.green, this.blue] would be a better example.

Also, it can be helpful to provide an example of serialization-aware utility (and what we mean by that):

function toHSL (ast) {
    visit(ast, 'color', function (color) {
        if (!(color instanceof Color)) {
            color = new Color(color[0], color[1], color[2]);
        }
        // ...
    });
}

[wooorm]

Yeah, sorry, the example I gave was horrible, despite that, from your
response, I think you got the gist of it though. 😉

Do you agree, in theory, that a tool which builds upon Unist nodes,
can expose them as both “JSON values”, and rich values which transform
to JSON? E.g., taking the Color example a bit back:

function toRGB(someColor) {
  // `someColor` can be `"hsl()"`, `"hsla()"`, `#bada55`, `rgb()`, `rgba()`, &c.
  // ...
}

function Color(value) {
  // Expose `value` to be a valid `Text` node in JS.
  this.value = value;
}

function getRGBAPart(index) {
  return function () {
    return toRGB(this.value)[index];
  }
}

Color.prototype.type = 'value';
Color.prototype.red = getRGBAPart(0);
Color.prototype.green = getRGBAPart(1);
Color.prototype.blue = getRGBAPart(2);
Color.prototype.alpha = getRGBAPart(3);
// Probably something similar for hue, saturation, lightness, &c.

Note, the above example does not show a non-valid node, it’s perfectly
valid in JS because it indeed stringifies to a valid Unist node.
But it does show a non-JSON value.

As an example of an invalid value, Date seems fine and common, as it’s
only valid because of its (built-in) toJSON function which works with
JavaScript’s JSON.stringify function.

I agree on the need to provide an example for the serialisation, but I’m
unsure about how to make that practical, Unist isn’t yet implemented in
non-JavaScript, and I don’t know about other languages which support
the toJSON method on non-JSON values. Do you know one? And, how to make that into a spec?