Experimental release. Minor version updates can introduce breaking changes before the first major update to 1.0, with the breaking changes always announced at least two weeks in advance. The upcoming minor update to v0.2.0 is planned to include the following breaking changes:
elementType
setting (deprecated) from JsonMember removed in favor of theelements
settingorder
setting from JsonMember removed, properties from then on are traversed in declaration orderTypedJSON.parse
will no longer work without specifying a type argument (use JSON.parse instead for untyped deserializing)typeHintPropertyKey
setting removed from thesettings
argument of TypedJSON.config, TypedJSON.parse, and TypedJSON.stringify in favor of a newtypeResolver
setting, accepting a callback function for custom type-resolving- This makes it straightforward to consume JSON from other serializers, such as JSON.net
- Polyfill for the
JSON
object removed from distributions. If your app relies on this, you'll need a third party polyfill.
If you have concerns about these changes, please don't hesitate to create an issue.
Typed JSON parsing and serializing for TypeScript that preserves type information, using decorators. Parse JSON into actual class instances. Recommended (but not required) to be used with ReflectDecorators, a prototype for an ES7 Reflection API for Decorator Metadata.
- Parse regular JSON into actual class instances safely
- Handles complex nested objects and polymorphism
- Seamlessly integrate into existing code with decorators, ultra-lightweight syntax
- Customize serialization and deserialization process, like custom names and default values
npm install typedjson-npm
typings install npm:typedjson-npm
- Snap the @JsonObject decorator on a class
- Snap the @JsonMember decorator on properties which should be serialized and deserialized
- Parse and stringify with the TypedJSON class
@JsonObject
class Person {
@JsonMember
firstName: string;
@JsonMember
lastName: string;
public getFullname() {
return this.firstName + " " + this.lastName;
}
}
var person = TypedJSON.parse('{ "firstName": "John", "lastName": "Doe" }', Person);
person instanceof Person; // true
person.getFullname(); // "John Doe"
If you choose to omit using ReflectDecorators, the class (constructor function) of each @JsonMember decorated property must be specified manually through the type
setting, for example:
@JsonMember({ type: String })
firstName: string;
Learn more about decorators in TypeScript
Using the JsonMember and JsonObject decorators will record metadata about classes and properties behind-the-scene. This metadata -- including property names and property types, as well as additional settings -- is available at runtime. When parsing JSON or stringifying an object, first the native JSON object is used for conversion between JSON string and simple Javascript Object
. After this preliminary conversion is done, the recorded metadata is traversed recursively.
JSON parsing is followed by deserialization, which converts the simple Javascript Object
from JSON.parse into the specified class instance by doing a recursive assignment to each marked property, as well as doing name conversion (if specified) and type-checking in the process. It also ensures that properties marked as required are present in the JSON, as an Error
is thrown otherwise. Deserialization is safe, as the entire process is done by traversing the expected metadata definitions, as opposed to traversing the actual data present in JSON. This means that incorrect JSON will cause errors during deserialization, instead of deserializing into an unexpected object-tree.
Warning: properties with type
Object
orany
are an exception to this rule. These types will be deserialized according to the actual data present in the JSON, as these properties have no usable metadata. Also be aware that a property with an interface type is considered as havingObject
as its determined type (consider setting therefersAbstractType
option totrue
for these properties).
JSON stringifying is followed by the serialization process, which is responsible for name conversion (if specified), as well as including any additional type-hints required when processing objects with polymorphic properties. When polymorphism is involved, type-hints are required to ensure serialized objects are deserialized into the correct subtype. The default property key used for type-hints embedded into the JSON string is __type
, which is configurable. The serialization process is much more relaxed than deserializing, as objects being serialized are expected to be of the correct type, and security implications are less significant.
TypedJSON is licensed under the MIT License.