github.com/kamalshkeir/kencoding@v0.0.2-0.20230409043843-44b609a0475a/json/README.md (about) 1 # encoding/json [![GoDoc](https://godoc.org/github.com/kamalshkeir/kencoding/json?status.svg)](https://godoc.org/github.com/kamalshkeir/kencoding/json) 2 3 Go package offering a replacement implementation of the standard library's 4 [`encoding/json`](https://golang.org/pkg/encoding/json/) package, with much 5 better performance. 6 7 ## Usage 8 9 The exported API of this package mirrors the standard library's 10 [`encoding/json`](https://golang.org/pkg/encoding/json/) package, the only 11 change needed to take advantage of the performance improvements is the import 12 path of the `json` package, from: 13 ```go 14 import ( 15 "encoding/json" 16 ) 17 ``` 18 to 19 ```go 20 import ( 21 "github.com/kamalshkeir/kencoding/json" 22 ) 23 ``` 24 25 One way to gain higher encoding throughput is to disable HTML escaping. 26 It allows the string encoding to use a much more efficient code path which 27 does not require parsing UTF-8 runes most of the time. 28 29 ## Performance Improvements 30 31 The internal implementation uses a fair amount of unsafe operations (untyped 32 code, pointer arithmetic, etc...) to avoid using reflection as much as possible, 33 which is often the reason why serialization code has a large CPU and memory 34 footprint. 35 36 The package aims for zero unnecessary dynamic memory allocations and hot code 37 paths that are mostly free from calls into the reflect package. 38 39 ## Compatibility with encoding/json 40 41 This package aims to be a drop-in replacement, therefore it is tested to behave 42 exactly like the standard library's package. However, there are still a few 43 missing features that have not been ported yet: 44 45 - Streaming decoder, currently the `Decoder` implementation offered by the 46 package does not support progressively reading values from a JSON array (unlike 47 the standard library). In our experience this is a very rare use-case, if you 48 need it you're better off sticking to the standard library, or spend a bit of 49 time implementing it in here ;) 50 51 Note that none of those features should result in performance degradations if 52 they were implemented in the package, and we welcome contributions! 53 54 ## Trade-offs 55 56 As one would expect, we had to make a couple of trade-offs to achieve greater 57 performance than the standard library, but there were also features that we 58 did not want to give away. 59 60 Other open-source packages offering a reduced CPU and memory footprint usually 61 do so by designing a different API, or require code generation (therefore adding 62 complexity to the build process). These were not acceptable conditions for us, 63 as we were not willing to trade off developer productivity for better runtime 64 performance. To achieve this, we chose to exactly replicate the standard 65 library interfaces and behavior, which meant the package implementation was the 66 only area that we were able to work with. The internals of this package make 67 heavy use of unsafe pointer arithmetics and other performance optimizations, 68 and therefore are not as approachable as typical Go programs. Basically, we put 69 a bigger burden on maintainers to achieve better runtime cost without 70 sacrificing developer productivity. 71 72 For these reasons, we also don't believe that this code should be ported upstream 73 to the standard `encoding/json` package. The standard library has to remain 74 readable and approachable to maximize stability and maintainability, and make 75 projects like this one possible because a high quality reference implementation 76 already exists.