jsonpak - Yet another JSON library
jsonpak is JSON library that implements the JSON Patch RFC which is specified in RFC 6902 from the IETF.
It uses Packed ASTs for compact and efficient JSON representation. Based on Araq's idea.
Documentation
API documentation
For more information visit: https://jsonpatch.com/ or the linked RFC documents.
JSON Pointer
type JsonPtr* = distinct string
JSON Pointer (IETF RFC 6901) defines a string format for identifying a specific value within a JSON document. It is used by all operations in JSON Patch to specify the part of the document to operate on.
A JSON Pointer is a string of tokens separated by / characters, these tokens either
specify keys in objects or indexes into arrays. For example, given the JSON
{
"a": [1, 2, 3],
"b": 4,
"c": [5, 6],
"d": {"e": [7, 8], "f": 9}
}
/d/e would point to the array of ints [7, 8] and /d/e/0 would point to 7.
To point to the root of the document use an empty string for the pointer. The pointer
/ doesn’t point to the root, it points to a key of "" on the root (which is
totally valid in JSON).
If you need to refer to a key with ~ or / in its name, you must escape the
characters with ~0 and ~1 respectively. For example, to get "baz" from
{"foo/bar~": "baz" } you’d use the pointer /foo~1bar~0.
Finally, if you need to refer to the end of an array you can use - instead of an
index. For example, to refer to the end of the array above you would use
/a/-. This is useful when you need to insert a value at the end of an array.
Operations
Add
proc add(tree: var JsonTree; path: JsonPtr; value: JsonTree)
Adds a value to an object or inserts it into an array. In the case of an array, the value
is inserted before the given index. The - character can be used instead of an index to
insert at the end of an array.
Remove
proc remove(tree: var JsonTree; path: JsonPtr)
Removes a value from an object or array.
Replace
proc replace(tree: var JsonTree; path: JsonPtr, value: JsonTree)
Replaces a value. Equivalent to a remove followed by an add.
Copy
proc copy(tree: var JsonTree; `from`, path: JsonPtr)
Copies a value from one location to another within the JSON document. Both from and
path are JSON Pointers.
Move
proc move(tree: var JsonTree; `from`, path: JsonPtr)
Moves a value from one location to the other. Both from and path are JSON Pointers.
Test
proc test(tree: JsonTree; path: JsonPtr, value: JsonTree): bool
Tests that the specified value is set in the document.
Misc
# JsonTree type (import jsonpak, jsonpak/dollar) proc `==`(a, b: JsonTree): bool proc isEmpty(tree: JsonTree): bool proc newEmptyTree(): JsonTree proc copy(tree: JsonTree): JsonTree proc `$`(tree: JsonTree): string # basic usage (import jsonpak/extra) proc len(tree: JsonTree; path: JsonPtr): int proc kind(tree: JsonTree; path: JsonPtr): JsonNodeKind proc contains(tree: JsonTree; path: JsonPtr): bool proc extract(tree: JsonTree; path: JsonPtr): JsonTree proc dump(tree: JsonTree; path: JsonPtr): string # (de)serialize (import jsonpak/[builder, mapper]) proc fromJson[T](tree: JsonTree; path: JsonPtr; t: typedesc[T]): T proc toJson[T](x: T): JsonTree macro `%*`(x: untyped): JsonTree # iterators (import jsonpak/builder) iterator items[T](tree: JsonTree; path: JsonPtr; t: typedesc[T]): T iterator pairs[T](tree: JsonTree; path: JsonPtr; t: typedesc[T]): (lent string, T) # SortedJsonTree type (import jsonpak/sorted) proc sorted(tree: JsonTree): SortedJsonTree proc `==`(a, b: SortedJsonTree): bool proc deduplicate(tree: var SortedJsonTree) proc hash(tree: SortedJsonTree): Hash
Examples
import jsonpak, jsonpak/[patch, parser, jsonptr, extra, builder, mapper, sorted, dollar] var x = %*{ "a": [1, 2, 3], "b": 4, "c": [5, 6], "d": {"e": [7, 8], "f": 9} } # Basic usage assert len(x, JsonPtr"") == 4 assert contains(x, JsonPtr"/a") assert kind(x, JsonPtr"/a") == JArray add x, JsonPtr"/a/-", %*[5, 6] # {"a":[1,2,3,[5,6]],"b":4,"c":[5,6],"d":{"e":[7,8],"f":9}} remove x, JsonPtr"/d/e/1" # {"a":[1,2,3,[5,6]],"b":4,"c":[5,6],"d":{"e":[7],"f":9}} replace x, JsonPtr"/b", %*"foo" # {"a":[1,2,3,[5,6]],"b":"foo","c":[5,6],"d":{"e":[7],"f":9}} copy x, JsonPtr"/b", JsonPtr"/d/f" # {"a":[1,2,3,[5,6]],"b":"foo","c":[5,6],"d":{"e":[7],"f":"foo"}} move x, JsonPtr"/c", JsonPtr"/b" # {"a":[1,2,3,[5,6]],"b":[5,6],"d":{"e":[7],"f":"foo"}} # Comparing, copying, deserializing assert test(x, JsonPtr"/d", %*{"e": [7], "f": "foo"}) assert $extract(x, JsonPtr"/d") == """{"e":[7],"f":"foo"}""" assert fromJson(x, JsonPtr"/a/3", seq[int]) == @[5, 6] assert toJson(@[5, 6]) == extract(x, JsonPtr"/b") # Iterating for i in items(x, JsonPtr"/b", int): echo i, " " # 5 6 for k, v in pairs(x, JsonPtr"/d", JsonTree): echo (k, v), " " # ("e", [7]) ("f", "foo") # Sorting, deduplicating, repeatable hashes var y = parseJson("""{"b":5,"a":1,"b":{"d":4,"c":2,"d":3}}""").sorted deduplicate(y) # {"a": 1, "b": {"c": 2, "d": 3}} echo hash(y) # -3485509795705892506
Benchmarks
This section details the average time (in milliseconds) it takes to perform various operations on a JSON document containing 1,000 entries.
| Op\Lib | jsonpak | std/json |
|---|---|---|
| Extract | 0.2679 | 0.6892 |
| toString | 0.8314 | 0.6853 |
| fromJson | 0.0040 | 0.0008 |
| toJson | 0.0007 | 0.0005 |
| Parse | 0.9767 | 1.4560 |
| Test | 0.0041 | 0.0005 |
| Replace | 0.0043 | 0.0005 |
| Remove | 0.0131 | 0.0008 |
| Add | 0.0043 | 0.0005 |
| Copy | 0.0086 | 0.0005 |
| Move | 0.0179 | 0.0008 |
| Sort | 0.8483 | 0.1953 |
| Hash | 0.1045 | 0.1484 |
However, the standard library's representation occupies approximately 13.4MiB, whereas ours only takes up 2.8MiB. Therefore, this library aims to optimize for space, and further improvements are planned.