Serialized keyword


#1

Could you explain what the keyword serialized mean?

/**

  • If set, the time series will be normalized in the given zone
    */
    timeZone: string serialized TimeZone

#2

This means that when the type with this field gets serialized (to JSON, for example), the timeZone field will be a string primitive value. The same is true for when the value gets persisted to the database. However, in JavaScript code, the values of this field will be TimeZone type objects. The type after the serialized keyword must mix StringSerializable for this to work.


#3

It also provides documentation as to what the valid formats are. Instead of a bare string, you know that it must be something that can be converted by TimeZone.fromString.


#4

Why not just declare it as TimeZone directly then?


#5

@romain.juban then it will get serialized as { "name": 'UTC' } instead of just "UTC".

While this is ok in this case it is a bigger issue for types like Url that have many more fields then just a simple string. Same goes for ContentType and Color and Include (c3 include spec) etc etc.

Basically there are large number of types that have natural way to represent data as a serialized string but will be cumbersome to persist or serialize as a complex object.

Instead of modeling them as plain string C3 type system provides additional metadata by describing structural representation.

p.s. in V8 type-system will add implicit parse* member methods that can handle parsing and as needed caching of serialized string values. So you would get instance of TimeZone by calling spec.parseTimeZone()