JsonRazor 2.0.0-rc

2.0.0-rc-1:

Changes to existing code:

• JSymbol has been renamed to TokenType. Also all members are no longer written in all caps. New flag Composite has been introduced, that is either Object or Array.
• JsonToken.GetFromPath() no longer accepts first char of root type, so all paths like "{obj{property" from now on must be "obj{property", and "[{obj{property" must be "{obj{property" ([ as first char is still valid, but it is considered as type of child, not root prefix).
• Implicit string casting operator for JsonToken has been removed. It called just Value, so all usages can be replaced with token?.Value;
• Extension method ToJsonObject(IEnumerable<KeyValuePair<string, string>>) has been removed. If it is necessary, it still can be implemented with simple foreach.
• Constructors JsonToken(string, string, bool, bool) and JsonValue(string, bool, bool) have been removed. For usages where useQuotes was false or detectType true, it is advised to use JsonToken.FromValue(string, string) and JsonValue.FromValue(string) static methods. When values where created as string, use constructors JsonToken(string, string, ValueType) and JsonValue(string, ValueType) and pass ValueType.String as valueType parameter (if string is not null).
• ValueBase.SetValue(string, bool, bool) has been removed. SetValue(string) can be used instead, and ValueType will be inferred from string value. SetValue(string, ValueType) can also be used, but valueType will need to be set correctly.
• JsonToken.Index and IToken.Index will return -1 when not set (previously 0).
• JsonObject no longer groups objects and arrays by type, rather they are put in document order. Objects() and Arrays() extension methods and object as either IEnumerable<JsonObject> or IEnumerable<JsonArray> still returns tokens only of given type (in document order).
• Assembly now targets netcoreapp 2.1 and 3.1, instead of netcoreapp 2.0 and 2.1.
• "null" is no longer treated like runtime null, now "null" is just string. Smh why it was like that.
• JsonValue.Get() was moved to base class and is accessible in JsonToken. Also its performance has been improved.
• Integer / fractional json values are now partially validated even when Json.ValueCorrectnessChecks is set to false. For example, OverflowException may be thrown when number exceeds long range. This may require putting ulong values as string.
• In previous release parsing token by token on nested structures has been removed. It is now added back with an extension - tokens returned by JsonToken.From() have not yet been parsed (except in case when they're empty), and it's now possible to fetch first token (be it object or array) and it is also not parsed. Useful when document has less regular structure.

Fixes:

• List<List<T>> previously would throw exception upon deserializing.
• Casting JsonComposite to IEnumerable<JsonObject> or IEnumerable<JsonArray>, or using Objects() or Arrays() extension methods would previously return equivalent of Tokens() due to covariance.
• Fixed cloning constructors JsonObject(JsonObject) and JsonArray(JsonArray).
• JsonArray.Find() would previously return nothing when not parsed. Also fixed issues with JsonObject.Find().
• Fixed issues with GetFromPath(string).
• Fixed issues with JsonToken.SwapFor(JsonToken). It is now allowed to swap token for token of different type, if parent is JsonArray (Remove() / Add(JsonToken) workaround not required).
• Fixed issues with JsonToken.Remove().
• Fixed issues with equality comparisons for all token types & array values.
• FirstToken property now loads first token if it isn't yet present. Other First... properties may have been fixed as well.
• Fixed certain failing cases for detecting escaped ".
• Other found issues have been fixed.
• Some method documentation has been improved.

New features:

• IConvertibleToken base interface has been extracted from ICommonToken interface, and ToDecimal() method has been added. IToken now derives from IConvertibleToken, but to access other methods it still needs to be casted to ICommonToken.
• Enum ValueType has been added, and it is returned from ValueType property in ValueBase class and IConvertibleToken interface. ValueType determines if value of IToken / JsonToken / JsonValue is null, true, false, string, long or double.
• ValueBase.SetValue(bool) has been added as a shorthand for SetValue(string, ValueType) when ValueType is either True or False.
• ValueBase.SetValue(object) has been added. object may be null, string, or boxed byte, sbyte, char, short, ushort, int, uint, long, ulong, float, double, decimal or DateTime. Ulong / decimal value is treated as String. Also static methods JsonToken.FromBoxedValue(object) and JsonValue.FromBoxedValue(object) have been added as well, their behaviour is the same.
• JsonToken.FromBool(string, bool), JsonToken.FromLong(string, long), JsonValue.FromBool(bool), JsonValue.FromLong(long) static methods have been added. If target framework is netcoreapp2.1 or higher, JsonToken.FromDouble(string, double) and JsonValue.FromDouble(double) are available as well.

Performance:

• CachingSerializer now in certain scenarios uses less memory to maintain the model.
• Reduced allocations when using JsonObject as either IEnumerable<JsonObject> or IEnumerable<JsonArray>, or when Objects() or Arrays() is called. The same applies for JsonArray, but only in certain scenarions.
• Reduced allocations in certain cases when cloning constructor JsonObject(JsonObject) or JsonArray(JsonArray) is called.
• ToBool(), ToLong(), and, if target framework is netcoreapp2.1 or higher, ToDouble(), have all been greatly improved in terms of performance, when used on tokens read from json. Get() performance is also improved for these value types. Obtaining long and double (netcoreapp2.1) values via Value property and parsing is now discouraged due to additional allocation.
• JsonStream.StreamFile() without skipping executed ~25% faster for given test file.
• JsonToken.Read(string) was faster ~20-40%. Memory usage during test scenario was ~22% lower.
• JsonToken.Read(StreamReader) was faster ~30-40%. Memory usage during test scenario was ~26% lower.
• Deserialization performance improvements (it's using the same improved parsing mechanism under the hood).

Package is in prerelease not because it's not stable, but rather because of planned breaking changes. There'll be around 1 or 2 more releases that will likely change existing APIs. There are some things that would make sense (like replacing JsonValues with JsonTokens for array), some deserialization improvements etc. Next release will probably be labeled as stable.