Gluon allows correct and consistent automatic serialization and deserialization for a specific universe of datatypes. For every type in this universe, Gluon defines an F# representation, a TypeScript representation, a serialized JSON representation, and automatic converters between in-memory and serialized representations. The grammar for the type set is given below:
1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16:
JSON (or other serialized format) representations should be considered Gluon internal implementation detail and may change without notice. Gluon will never need to discriminate on values to infer the type of the represented objects, since type information is always available statically. This allows distinct types use similar JSON representations (such as a string) without confusion.
Boolean, String, Int, Double have intuitive representations. Gluon should preserve the complete range of values (including NaN, Infinity, null strings).
Since version 0.4.2, Gluon supports two semantics for DateTime values: the "physical" interpretation of DateTime is a time-point in universal time coordinates, and the "calendar" interpretation:
For convenience, both interpretations use the same types (the
distinction is not tracked in the type system). On the F# side the
System.DateTime, and on the TypeScript side it is
On CLR, physical datetimes are represented as
DateTime object with
Kind being either
TypeScript, these are represented as vanilla
Date objects. During
interop, zone conversions happen to preserve the universal coordinate
meaning of the datetime. Note that the browser always displays
objects in user-local zone, which might be different from the server
timezone; server timezone information is lost.
Calendar semantics are useful when displaying dates as-is, bypassing timezone conversions. Two dates are considered calendar-equivalent if they have the same year, month, day, hour, minute and second. Time zone information is not tracked and must be implied.
On CLR, calendar datetimes are
DateTime objects with
DateTimeKind.Unspecified. In TypeScript, these are represented as a
Date object that is extended to have an extra tag
true. Browsers ignores the tag and treat the
Date objects as if
they were in browser-local timezone, however the tag is used by Gluon
to make sure these values roundtrip to the server using calendar
Records and unions use the WebSharper serialization convention, where the internal representation of the type is considered, regardless of public/internal/private declarations. This is unlike some other conventions such as JSON.NET or other CLR serializers, that use public properties or opt-in and opt-out attributes. This limits flexibility but greatly simplifies constructing equivalent types in TypeScript, and ensuring turnaround. Records will map to TypeScript classes in an intuitive manner.
Unions currently generate a TypeScript class for each case and an
untagged TypeScript union type alias for the union itself. This scheme
has runtime efficiency and allows to discriminate values with the
instanceof operator. This representation may change in the future,
an alternative here is to provide a match construct that enforces
completeness check in the type system.
Since 0.4.x, Gluon also generates a typed pattern-matching helper for unions.
Array, sequence and list types will all map to TypeScript arrays.
Options will map to T | null | undefined. This provides type-safety
strictNullChecks is enabled in
tsconfig.json. This also
namespace provides helper functions to test for
or provide default values.
StringDict will use a newly introduced Dict