You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
`DeferredJSON` offers a drop in replacement for `JSON.stringify` and `JSON.parse` that defers parsing until the data is actually needed. If you happen to serialize a DeferredJSON instance later to a string without ever touching it, than neither the parse nor stringify needs to happen, and DeferredJSON can just feed out the already serialized contents stored at the start.
3
+
`DeferredJSON` offers a drop in replacement for `JSON.stringify` and `JSON.parse` that defers parsing until the parsed result is actually needed. If you re-stringify without ever accessing the data, the parsing can be fully avoided and performance greatly improved.
4
4
5
-
`DeferredJSON` works by returning a `Proxy` object that parses on demand the first time a value is accessed. `DeferredJSON` works with any incoming JSON value, including serialized arrays, objects, and primitive values.
5
+
`DeferredJSON` works by returning a `Proxy` object that parses on demand the first time a value is accessed, and storing the incoming serialized string of JSON for later use. Then later when `DeferredJSON.stringify` is used, any deferreds within the serialized tree re-use that incoming serialized string, avoiding the cost of re-serializing.
6
+
7
+
`DeferredJSON` works with any incoming JSON value, including serialized arrays, objects, and primitive values.
6
8
7
9
Also handy is that `DeferredJSON` serialization can interpolate several nested lazy JSON objects into an outer one when stringifing. If you are returning an outer object (say a REST API response) where one field on each record is a potentially-large JSON object, you can use `DeferredJSON` for those large objects, but still rely on `DeferredJSON.stringify` to avoid the cost of deserializing-and-re-serializing each little object in the payload.
8
10
9
11
## Background
10
12
11
13
A lot of nodejs programs serve up JSON data to a client, and to do that, some in-memory datastructure has to get serialized. Usually, you have to pay the price of serializing an entire JSON tree, which is an [event-loop-blocking](https://nodejs.org/en/learn/asynchronous-work/dont-block-the-event-loop) operation. If the JSON is very large, this event loop block can become a major issue.
12
14
13
-
But, a lot of the time, the JSON a program is serving is available in an _already serialized JSON_ form. It could be bytes in a file, or a `json` or `jsonb` field in Postgres, or incoming bytes from a request. If you already have JSON that you trust is valid in string form, it is wasteful to parse it, never touch it, and then serialize it again.
15
+
But a lot of the time, programs are serving JSON that started its life in an _already serialized string_ form. It could be bytes in a file, or a `json` or `jsonb` field in Postgres, or incoming bytes from a request. If you already have a JSON string that you trust is valid, it is wasteful to parse it, never touch it, and then serialize it again.
16
+
17
+
`DeferredJSON` helps with this performance issue in this specific situation by deferring the parsing of your existing serialized JSON until the last possible moment. If you do need to access data within the JSON, `DeferredJSON` will parse it on demand, incurring the same performance penalty as a normal `JSON.parse`. But, if you never end up accessing the deserialized data, `DeferredJSON` will never parse it, and can feed out the already serialized contents as is.
18
+
19
+
### Performance
20
+
21
+
`DeferredJSON` is written with high-performance node.js apps in mind and does its best to add as little overhead as possible, but there is some. When accessing keys of a `DeferredJSON` object, there is a small amount of overhead added to go through the proxy for each property access at the root-level node that is parsed. If you need absolutely no overhead in accessing the data you are parsing, then don't use `DeferredJSON`.
22
+
23
+
For serialization, `DeferredJSON` also adds some small overhead. `DeferredJSON` still uses the JS VM's high-performance `JSON.stringify` under the hood take advantage of all the optimizations baked in there, but then does a second pass over the serialized string to interpolate if needed. This adds some overhead, but for JSON objects of any size, the performance is still much better than doing the whole parse and re-serializing of the objects in question.
24
+
25
+
`DeferredJSON` was extracted out of [Gadget](https://gadget.dev) where it made a major performance difference for the JSON responses Gadget serves up.
14
26
15
-
`DeferredJSON` helps with this performance issue in this specific situation by deferring the parsing of your existing serialized JSON until the last possible moment. If you do need to access data within the JSON, `DeferredJSON` will parse it on demand. But, if you never need to access the data, `DeferredJSON` will never parse it, and can feed out the already serialized contents as is.
27
+
Here's the results of the benchmark at `spec/deferredjson.bench.ts`:
28
+
29
+
| Task Name | ops/sec | Average Time (ns) | Margin | Samples |
Use `DeferredJSON.parse` instead of `JSON.parse`, that's all. `DeferredJSON.parse` will return a `Proxy` object that should act just like a normal JSON object.
48
+
Use `DeferredJSON.parse` instead of `JSON.parse` -- that's all. `DeferredJSON.parse` will return a `Proxy` object that acts just like a normal JSON object.
22
49
23
50
```typescript
24
51
const obj =DeferredJSON.parse(`{"foo": "bar"}`);
25
52
// no parsing has happened yet
26
-
obj.foo; // "bar"
53
+
54
+
obj.foo; // triggers parsing of the string and returns "bar"
27
55
// object is now parsed and quacks the same as if JSON.parse was used
There's a few optimizations `DeferredJSON.parse` makes to be aware of:
40
68
41
-
- if the serialized JSON is a scalar value like a number or a boolean, it isn't wrapped in a `DeferredJSON` proxy, since parsing it is so cheap.
42
-
- if the JSON is still unparsed, and it is awaited by accessing the `.then` property, the JSON won't be deserialized, and instead the whole JSON will be returned. This means that if the `.then` property is actually a string inside the JSON that you care about, you need to forcibly parse the JSON to access it. This is a good thing, since it means you can still blindly await your `DeferredJSON`s and not worry about eagerly forcing parsing for no reason other than some async function baloney.
69
+
- unlike `JSON.parse`, if the string is invalid JSON, it won't throw an error until the first time the inner JSON is accessed.
70
+
- if the serialized JSON is a scalar value like a number or a boolean, it isn't wrapped in a `DeferredJSON` proxy and instead is eagerly deserialized and returned. Benchmarks showed proxying these simple scalars not to be worth it since parsing it is so cheap.
71
+
- if the JSON is still unparsed, and it is awaited by accessing the `.then` property, the JSON **won't** be deserialized. Instead the whole JSON will be returned. This means that if the `.then` property is actually a string inside the JSON that you care about, you need to forcibly parse the JSON to access it. This is a good thing, since it means you can still blindly await your `DeferredJSON`s and not worry about eagerly forcing parsing for no reason other than some async function baloney.
43
72
44
73
### Serializing
45
74
@@ -62,11 +91,3 @@ const response = {
62
91
DeferredJSON.stringify(response);
63
92
// `{"data":{"foo":"bar"},"other":"stuff"}`
64
93
```
65
-
66
-
### Performance
67
-
68
-
`DeferredJSON` is written with high-performance node.js apps in mind and does its best to add as little overhead as possible, but there is some. When accessing keys of a `DeferredJSON` object, there is a small amount of overhead added to go through the proxy for each property access at the root-level node that is parsed. If you need absolutely no overhead in accessing the data you are parsing, then don't use `DeferredJSON`.
69
-
70
-
For serialization, `DeferredJSON` also adds some small overhead. `DeferredJSON` still uses the JS VM's `JSON.stringify` under the hood to get maximum performance and all the optimizations baked in there, but then does a second pass over the serialized string to interpolate if needed. This adds some overhead, but for JSON objects of any size, the performance is still much better than doing the whole parse and re-serializing of the objects in question.
71
-
72
-
`DeferredJSON` was extracted out of [Gadget](https://gadget.dev) where it made a major performance difference for the JSON responses Gadget serves up.
0 commit comments