diff --git a/CHANGELOG.md b/CHANGELOG.md index b08615fdc..d1943f2e6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,77 @@ +1.4.0-RC / 2022-07-20 +================== + +This is a candidate for the next big release with many new exciting features to try. +It uses Kotlin 1.7.10 by default. + +### Integration with Okio's BufferedSource and BufferedSink + +[Okio library by Square](https://square.github.io/okio/) is a popular solution for fast and efficient IO operations on JVM, K/N and K/JS. +In this version, we have added functions that parse/write JSON directly to Okio's input/output classes, saving you the overhead of copying data to `String` beforehand. +These functions are called `Json.decodeFromBufferedSource` and `Json.encodeToBufferedSink`, respectively. +There's also `decodeBufferedSourceToSequence` that behaves similarly to `decodeToSequence` from Java streams integration, so you can lazily decode multiple objects the same way as before. + +Note that these functions are located in a separate new artifact, so users who don't need them wouldn't find themselves dependent on Okio. +To include this artifact in your project, use the same group id `org.jetbrains.kotlinx` and artifact id `kotlinx-serialization-json-okio`. +To find out more about this integration, check new functions' documentation and corresponding pull requests: +[#1901](https://github.com/Kotlin/kotlinx.serialization/pull/1901) and [#1982](https://github.com/Kotlin/kotlinx.serialization/pull/1982). + +### Inline classes and unsigned numbers do not require experimental annotations anymore + +Inline classes and unsigned number types have been promoted to a Stable feature in Kotlin 1.5, +and now we are promoting support for them in kotlinx.serialization to Stable status, too. +To be precise, [we've removed all](https://github.com/Kotlin/kotlinx.serialization/pull/1963) `@ExperimentalSerializationApi` annotations from functions related to inline classes encoding and decoding, +namely `SerialDescriptor.isInline`, `Encoder.encodeInline`, and some others. We've also updated related [documentation article](docs/value-classes.md). + +Additionally, all `@ExperimentalUnsignedTypes` annotations [were removed](https://github.com/Kotlin/kotlinx.serialization/pull/1962) completely, +so you can freely use types such as `UInt` and their respective serializers as a stable feature +without opt-in requirement. + +### Part of SerializationException's hierarchy is public now + +When kotlinx.serialization 1.0 was released, all subclasses of `SerializationException` were made internal, +since they didn't provide helpful information besides the standard message. +Since then, we've received a lot of feature requests with compelling use-cases for exposing some of these internal types to the public. +In this release, we are starting to fulfilling these requests by making `MissingFieldException` public. +One can use it in the `catch` clause to better understand the reasons of failure — for example, to return 400 instead of 500 from an HTTP server — +and then use its `fields` property to communicate the message better. +See the details in the corresponding [PR](https://github.com/Kotlin/kotlinx.serialization/pull/1983). + +In future releases, we'll continue work in this direction, and we aim to provide more useful public exception types & properties. +In the meantime, we've [revamped KDoc](https://github.com/Kotlin/kotlinx.serialization/pull/1980) for some methods regarding the exceptions — all of them now properly declare which exception types are allowed to be thrown. +For example, `KSerializer.deserialize` is documented to throw `IllegalStateException` to indicate problems unrelated to serialization, such as data validation in classes' constructors. + +### @MetaSerializable annotation + +This release introduces a new `@MetaSerializable` annotation that adds `@Serializable` behavior to user-defined annotations — i.e., those annotations would also instruct the compiler plugin to generate a serializer for class. In addition, all annotations marked with `@MetaSerializable` are saved in the generated `@SerialDescriptor` +as if they are annotated with `@SerialInfo`. + +This annotation will be particularly useful for various format authors who require adding some metadata to the serializable class — this can now be done using a single annotation instead of two, and without the risk of forgetting `@Serializable`. Check out details & examples in the KDoc and corresponding [PR](https://github.com/Kotlin/kotlinx.serialization/pull/1979). + +> Note: Kotlin 1.7.0 or higher is required for this feature to work. + +### Moving documentation from GitHub pages to kotlinlang.org + +As a part of a coordinated effort to unify kotlinx libraries users' experience, Dokka-generated documentation pages (KDoc) were moved from https://kotlin.github.io/kotlinx.serialization/ to https://kotlinlang.org/api/kotlinx.serialization/. No action from you is required — there are proper redirects at the former address, so there is no need to worry about links in your blogpost getting obsolete or broken. + +Note that this move does not affect guides written in Markdown in the `docs` folder. We aim to move them later, enriching text with runnable examples as in the Kotlin language guides. + +### Other improvements + + * Allow Kotlin's null literal in JSON DSL (#1907) (thanks to [Lukellmann](https://github.com/Lukellmann)) + * Stabilize EmptySerializersModule (#1921) + * Boost performance of polymorphic deserialization in optimistic scenario (#1919) + * Added serializer for the `kotlin.time.Duration` class (plugin support comes in Kotlin 1.7.20) (#1960) + * Support tagged not null marks in TaggedEncoder/Decoder (#1954) (thanks to [EdwarDDay](https://github.com/EdwarDDay)) + +### Bugfixes + + * Support quoting unsigned integers when used as map keys (#1969) + * Fix protocol buffer enum schema generation (#1967) (thanks to [mogud](https://github.com/mogud)) + * Support diamond inheritance of sealed interfaces in SealedClassSerializer (#1958) + * Support retrieving serializer for sealed interface (#1968) + * Fix misleading token description in JSON errors (#1941) (thanks to [TheMrMilchmann](https://github.com/TheMrMilchmann)) + 1.3.3 / 2022-05-11 ================== @@ -26,7 +100,7 @@ Many thanks to [Paul de Vrieze](https://github.com/pdvrieze) for his valuable co * Iterate over element indices in ObjectSerializer in order to let the format skip unknown keys (#1916) * Correctly support registering both default polymorphic serializer & deserializer (#1849) * Make error message for captured generic type parameters much more straightforward (#1863) - + 1.3.2 / 2021-12-23 ================== diff --git a/README.md b/README.md index 02ec8cb00..0887845c0 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,8 @@ [![JetBrains official project](https://jb.gg/badges/official.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub) [![GitHub license](https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat)](http://www.apache.org/licenses/LICENSE-2.0) [![TeamCity build](https://img.shields.io/teamcity/http/teamcity.jetbrains.com/s/KotlinTools_KotlinxSerialization_Ko.svg)](https://teamcity.jetbrains.com/viewType.html?buildTypeId=KotlinTools_KotlinxSerialization_Ko&guest=1) -[![Kotlin](https://img.shields.io/badge/kotlin-1.6.21-blue.svg?logo=kotlin)](http://kotlinlang.org) -[![Maven Central](https://img.shields.io/maven-central/v/org.jetbrains.kotlinx/kotlinx-serialization-core/1.3.3)](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-serialization-core/1.3.3/pom) +[![Kotlin](https://img.shields.io/badge/kotlin-1.7.10-blue.svg?logo=kotlin)](http://kotlinlang.org) +[![Maven Central](https://img.shields.io/maven-central/v/org.jetbrains.kotlinx/kotlinx-serialization-core/1.4.0-RC)](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-serialization-core/1.4.0-RC/pom) [![KDoc link](https://img.shields.io/badge/API_reference-KDoc-blue)](https://kotlinlang.org/api/kotlinx.serialization/) [![Slack channel](https://img.shields.io/badge/chat-slack-blue.svg?logo=slack)](https://kotlinlang.slack.com/messages/serialization/) @@ -89,8 +89,8 @@ Kotlin DSL: ```kotlin plugins { - kotlin("jvm") version "1.6.21" // or kotlin("multiplatform") or any other kotlin plugin - kotlin("plugin.serialization") version "1.6.21" + kotlin("jvm") version "1.7.10" // or kotlin("multiplatform") or any other kotlin plugin + kotlin("plugin.serialization") version "1.7.10" } ``` @@ -98,8 +98,8 @@ Groovy DSL: ```gradle plugins { - id 'org.jetbrains.kotlin.multiplatform' version '1.6.21' - id 'org.jetbrains.kotlin.plugin.serialization' version '1.6.21' + id 'org.jetbrains.kotlin.multiplatform' version '1.7.10' + id 'org.jetbrains.kotlin.plugin.serialization' version '1.7.10' } ``` @@ -116,7 +116,7 @@ buildscript { repositories { mavenCentral() } dependencies { - val kotlinVersion = "1.6.21" + val kotlinVersion = "1.7.10" classpath(kotlin("gradle-plugin", version = kotlinVersion)) classpath(kotlin("serialization", version = kotlinVersion)) } @@ -127,7 +127,7 @@ Groovy DSL: ```gradle buildscript { - ext.kotlin_version = '1.6.21' + ext.kotlin_version = '1.7.10' repositories { mavenCentral() } dependencies { @@ -156,7 +156,7 @@ repositories { } dependencies { - implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.3.3") + implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.4.0-RC") } ``` @@ -168,7 +168,7 @@ repositories { } dependencies { - implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.3.3" + implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.4.0-RC" } ``` @@ -286,8 +286,8 @@ Ensure the proper version of Kotlin and serialization version: ```xml - 1.6.21 - 1.3.3 + 1.7.10 + 1.4.0-RC ``` diff --git a/core/commonMain/src/kotlinx/serialization/SerializationExceptions.kt b/core/commonMain/src/kotlinx/serialization/SerializationExceptions.kt index c4c72aa9c..152f894a1 100644 --- a/core/commonMain/src/kotlinx/serialization/SerializationExceptions.kt +++ b/core/commonMain/src/kotlinx/serialization/SerializationExceptions.kt @@ -59,7 +59,7 @@ public open class SerializationException : IllegalArgumentException { } /** - * Thrown when [KSerializer] did not receive a non-optonal property from [CompositeDecoder] and [CompositeDecoder.decodeElementIndex] + * Thrown when [KSerializer] did not receive a non-optional property from [CompositeDecoder] and [CompositeDecoder.decodeElementIndex] * had already returned [CompositeDecoder.DECODE_DONE]. * * [MissingFieldException] is thrown on missing field from all [auto-generated][Serializable] serializers and it diff --git a/docs/value-classes.md b/docs/value-classes.md index 476b5db06..a55d8e4a0 100644 --- a/docs/value-classes.md +++ b/docs/value-classes.md @@ -45,7 +45,7 @@ output: ``` As we see, `Color` class is not included during the encoding, only its underlying data. This invariant holds even if the actual value class -is [allocated](https://kotlinlang.org/docs/reference/inline-classes.html#representation) — for example, when inline +is [allocated](https://kotlinlang.org/docs/reference/inline-classes.html#representation) — for example, when value class is used as a generic type argument: ```kotlin diff --git a/gradle.properties b/gradle.properties index 731bd6615..926fe2316 100644 --- a/gradle.properties +++ b/gradle.properties @@ -5,7 +5,7 @@ group=org.jetbrains.kotlinx version=1.4.0-SNAPSHOT -kotlin.version=1.7.0 +kotlin.version=1.7.10 # This version take precedence if 'bootstrap' property passed to project kotlin.version.snapshot=1.7.255-SNAPSHOT diff --git a/integration-test/gradle.properties b/integration-test/gradle.properties index 880a5f4cd..5ec861cf5 100644 --- a/integration-test/gradle.properties +++ b/integration-test/gradle.properties @@ -2,7 +2,7 @@ # Copyright 2017-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. # -mainKotlinVersion=1.7.0 +mainKotlinVersion=1.7.10 mainLibVersion=1.4.0-SNAPSHOT kotlin.code.style=official diff --git a/kotlin-js-store/yarn.lock b/kotlin-js-store/yarn.lock index aea22932a..a935ec5e4 100644 --- a/kotlin-js-store/yarn.lock +++ b/kotlin-js-store/yarn.lock @@ -55,6 +55,13 @@ brace-expansion@^1.1.7: balanced-match "^1.0.0" concat-map "0.0.1" +brace-expansion@^2.0.1: + version "2.0.1" + resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-2.0.1.tgz#1edc459e0f0c548486ecf9fc99f2221364b9a0ae" + integrity sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA== + dependencies: + balanced-match "^1.0.0" + braces@~3.0.2: version "3.0.2" resolved "https://registry.yarnpkg.com/braces/-/braces-3.0.2.tgz#3454e1a462ee8d599e236df336cd9ea4f8afe107" @@ -126,10 +133,10 @@ concat-map@0.0.1: resolved "https://registry.yarnpkg.com/concat-map/-/concat-map-0.0.1.tgz#d8a96bd77fd68df7793a73036a3ba0d5405d477b" integrity sha1-2Klr13/Wjfd5OnMDajug1UBdR3s= -debug@4.3.3: - version "4.3.3" - resolved "https://registry.yarnpkg.com/debug/-/debug-4.3.3.tgz#04266e0b70a98d4462e6e288e38259213332b664" - integrity sha512-/zxw5+vh1Tfv+4Qn7a5nsbcJKPaSvCDhojn6FEl9vupwK2VCSDtEiEtqr8DFtzYFOdz63LBkxec7DYuc2jon6Q== +debug@4.3.4: + version "4.3.4" + resolved "https://registry.yarnpkg.com/debug/-/debug-4.3.4.tgz#1319f6579357f2338d3337d2cdd4914bb5dcc865" + integrity sha512-PRWFHuSU3eDtQJPvnNY7Jcket1j0t5OuOsFzPPzsekD52Zl8qUfFIPEiswXqIvHWGVHOgX+7G/vCNNhehwxfkQ== dependencies: ms "2.1.2" @@ -217,11 +224,6 @@ glob@7.2.0: once "^1.3.0" path-is-absolute "^1.0.0" -growl@1.10.5: - version "1.10.5" - resolved "https://registry.yarnpkg.com/growl/-/growl-1.10.5.tgz#f2735dc2283674fa67478b10181059355c369e5e" - integrity sha512-qBr4OuELkhPenW6goKVXiv47US3clb3/IbuWF9KNKEijAy9oeHxU9IgzjvJhHkUzhaj7rOUD7+YGWqUjLp5oSA== - has-flag@^4.0.0: version "4.0.0" resolved "https://registry.yarnpkg.com/has-flag/-/has-flag-4.0.0.tgz#944771fd9c81c81265c4d6941860da06bb59479b" @@ -284,11 +286,6 @@ is-unicode-supported@^0.1.0: resolved "https://registry.yarnpkg.com/is-unicode-supported/-/is-unicode-supported-0.1.0.tgz#3f26c76a809593b52bfa2ecb5710ed2779b522a7" integrity sha512-knxG2q4UC3u8stRGyAVJCOdxFmv5DZiRcdlIaAQXAbSfJya+OhopNotLQrstBhququ4ZpuKbDc/8S6mgXgPFPw== -isexe@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/isexe/-/isexe-2.0.0.tgz#e8fbf374dc556ff8947a10dcb0572d633f2cfa10" - integrity sha1-6PvzdNxVb/iUehDcsFctYz8s+hA= - js-yaml@4.1.0: version "4.1.0" resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-4.1.0.tgz#c1fb65f8f5017901cdd2c951864ba18458a10602" @@ -311,39 +308,44 @@ log-symbols@4.1.0: chalk "^4.1.0" is-unicode-supported "^0.1.0" -minimatch@3.0.4, minimatch@^3.0.4: +minimatch@5.0.1: + version "5.0.1" + resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-5.0.1.tgz#fb9022f7528125187c92bd9e9b6366be1cf3415b" + integrity sha512-nLDxIFRyhDblz3qMuq+SoRZED4+miJ/G+tdDrjkkkRnjAsBexeGpgjLEQ0blJy7rHhR2b93rhQY4SvyWu9v03g== + dependencies: + brace-expansion "^2.0.1" + +minimatch@^3.0.4: version "3.0.4" resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-3.0.4.tgz#5166e286457f03306064be5497e8dbb0c3d32083" integrity sha512-yJHVQEhyqPLUTgt9B83PXu6W3rx4MvvHvSUvToogpwoGDOUQ+yDrR0HRot+yOCdCO7u4hX3pWft6kWBBcqh0UA== dependencies: brace-expansion "^1.1.7" -mocha@9.2.1: - version "9.2.1" - resolved "https://registry.yarnpkg.com/mocha/-/mocha-9.2.1.tgz#a1abb675aa9a8490798503af57e8782a78f1338e" - integrity sha512-T7uscqjJVS46Pq1XDXyo9Uvey9gd3huT/DD9cYBb4K2Xc/vbKRPUWK067bxDQRK0yIz6Jxk73IrnimvASzBNAQ== +mocha@10.0.0: + version "10.0.0" + resolved "https://registry.yarnpkg.com/mocha/-/mocha-10.0.0.tgz#205447d8993ec755335c4b13deba3d3a13c4def9" + integrity sha512-0Wl+elVUD43Y0BqPZBzZt8Tnkw9CMUdNYnUsTfOM1vuhJVZL+kiesFYsqwBkEEuEixaiPe5ZQdqDgX2jddhmoA== dependencies: "@ungap/promise-all-settled" "1.1.2" ansi-colors "4.1.1" browser-stdout "1.3.1" chokidar "3.5.3" - debug "4.3.3" + debug "4.3.4" diff "5.0.0" escape-string-regexp "4.0.0" find-up "5.0.0" glob "7.2.0" - growl "1.10.5" he "1.2.0" js-yaml "4.1.0" log-symbols "4.1.0" - minimatch "3.0.4" + minimatch "5.0.1" ms "2.1.3" - nanoid "3.2.0" + nanoid "3.3.3" serialize-javascript "6.0.0" strip-json-comments "3.1.1" supports-color "8.1.1" - which "2.0.2" - workerpool "6.2.0" + workerpool "6.2.1" yargs "16.2.0" yargs-parser "20.2.4" yargs-unparser "2.0.0" @@ -358,10 +360,10 @@ ms@2.1.3: resolved "https://registry.yarnpkg.com/ms/-/ms-2.1.3.tgz#574c8138ce1d2b5861f0b44579dbadd60c6615b2" integrity sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA== -nanoid@3.2.0: - version "3.2.0" - resolved "https://registry.yarnpkg.com/nanoid/-/nanoid-3.2.0.tgz#62667522da6673971cca916a6d3eff3f415ff80c" - integrity sha512-fmsZYa9lpn69Ad5eDn7FMcnnSR+8R34W9qJEijxYhTbfOWzr22n1QxCMzXLK+ODyW2973V3Fux959iQoUxzUIA== +nanoid@3.3.3: + version "3.3.3" + resolved "https://registry.yarnpkg.com/nanoid/-/nanoid-3.3.3.tgz#fd8e8b7aa761fe807dba2d1b98fb7241bb724a25" + integrity sha512-p1sjXuopFs0xg+fPASzQ28agW1oHD7xDsd9Xkf3T15H3c/cifrFHVwrh74PdoklAPi+i7MdRsE47vm2r6JoB+w== normalize-path@^3.0.0, normalize-path@~3.0.0: version "3.0.0" @@ -490,17 +492,10 @@ to-regex-range@^5.0.1: dependencies: is-number "^7.0.0" -which@2.0.2: - version "2.0.2" - resolved "https://registry.yarnpkg.com/which/-/which-2.0.2.tgz#7c6a8dd0a636a0327e10b59c9286eee93f3f51b1" - integrity sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA== - dependencies: - isexe "^2.0.0" - -workerpool@6.2.0: - version "6.2.0" - resolved "https://registry.yarnpkg.com/workerpool/-/workerpool-6.2.0.tgz#827d93c9ba23ee2019c3ffaff5c27fccea289e8b" - integrity sha512-Rsk5qQHJ9eowMH28Jwhe8HEbmdYDX4lwoMWshiCXugjtHqMD9ZbiqSDLxcsfdqsETPzVUtX5s1Z5kStiIM6l4A== +workerpool@6.2.1: + version "6.2.1" + resolved "https://registry.yarnpkg.com/workerpool/-/workerpool-6.2.1.tgz#46fc150c17d826b86a008e5a4508656777e9c343" + integrity sha512-ILEIE97kDZvF9Wb9f6h5aXK4swSlKGUcOEGiIYb2OOu/IrDU9iwj0fD//SsA6E5ibwJxpEvhullJY4Sl4GcpAw== wrap-ansi@^7.0.0: version "7.0.0"