Add array streaming helpers (#115)

An implementation of
#112 that
introduces `beginArray`/`endArray` for the streaming creation of arrays.

In order to accomodate the need for intra-element plumbing, we add
`begin`/`end` marker calls to the `writeValue` implementation which
helps the writer keep track of each value being written and therefore
allows it to inject the correct delimiters and indents.

Here's an example of writing a `writeValue` overload that writes an
array nested in an object:

```nim
proc writeValue(w: var JsonWriter, t: MyType) =
  w.beginArray()

  for i in 0 ..< t.children:
    writer.beginObject()

    writer.writeMember("id", i)
    writer.writeMember("name", "item" & t.childName[i])

    writer.endObject()

  writer.endArray()
```

Similar to the existing `beginRecord`/`endRecord` fields we add
`beginArray` and `endArray` - we also take the opportunity to name
`beginObject` according to its json-spec-derived name. The old name
remains available.

This change introduces a backwards-compatibility break for custom
writers that try to access the stream directly: they now have to delimit
their value writing with `w.streamElement(s): s.write ...` where `s` is
the stream variable. The block template enforces begin/end markers on
behalf of the writer.

Further examples are available in the documentation.

With this change, we also deprecate workarounds like `fieldWritten` and
`endRecordField` since a regular replacement exists in the form of
consistent begin/end pairs.

* doc fixes

* make beginElement/endElement private

Should not be called directly as `writeValue` / `streamElement` take
care of it.

Author: arnetheduck

docs/examples/reference0.nim

@@ -18,11 +18,8 @@ type
 var conf = defaultJsonReaderConf
 conf.nestedDepthLimit = 0
 
-let native =
-  Json.decode(rawJson, NimServer, flags = defaultJsonReaderFlags, conf = conf)
-
 # decode into native Nim
-#let native = Json.decode(rawJson, NimServer)
+let native = Json.decode(rawJson, NimServer)
 
 # decode into mixed Nim + JsonValueRef
 let mixed = Json.decode(rawJson, MixedServer)

docs/examples/streamwrite0.nim

@@ -0,0 +1,18 @@
+import json_serialization, faststreams/outputs
+
+let file = fileOutput("output.json")
+var writer = JsonWriter[DefaultFlavor].init(file, pretty = true)
+
+writer.beginArray()
+
+for i in 0 ..< 2:
+  writer.beginObject()
+
+  writer.writeMember("id", i)
+  writer.writeMember("name", "item" & $i)
+
+  writer.endObject()
+
+writer.endArray()
+
+file.close()

docs/examples/streamwrite1.nim

@@ -0,0 +1,17 @@
+import json_serialization, faststreams/outputs
+
+let file = fileOutput("output.json")
+var writer = JsonWriter[DefaultFlavor].init(file)
+
+# ANCHOR: Nesting
+writer.writeObject:
+  writer.writeMember("status", "ok")
+  writer.writeName("data")
+  writer.writeArray:
+    for i in 0 ..< 2:
+      writer.writeObject:
+        writer.writeMember("id", i)
+        writer.writeMember("name", "item" & $i)
+# ANCHOR_END: Nesting
+
+file.close()

docs/src/SUMMARY.md

@@ -3,6 +3,7 @@
 # User guide
 
 - [Getting started](./getting_started.md)
+- [Streaming](./streaming.md)
 - [Reference](./reference.md)
 
 # Developer guide

docs/src/reference.md

@@ -83,7 +83,7 @@ You can adjust these defaults to suit your needs:
 
 ### Common API
 
-Similar to parsing, the [common serialization API]() is used to produce JSON documents.
+Similar to parsing, the [common serialization API](https://github.com/status-im/nim-serialization?tab=readme-ov-file#common-api) is used to produce JSON documents.
 
 ```nim
 {{#include ../examples/reference0.nim:Encode}}
@@ -246,24 +246,7 @@ readRecordValue[T](r: var JsonReader, value: var T)
 
 ## JsonWriter Helper Procedures
 
-```nim
-beginRecord(w: var JsonWriter, T: type)
-beginRecord(w: var JsonWriter)
-endRecord(w: var JsonWriter)
-
-writeObject(w: var JsonWriter, T: type)
-writeObject(w: var JsonWriter)
-
-writeFieldName(w: var JsonWriter, name: string)
-writeField(w: var JsonWriter, name: string, value: auto)
-
-iterator stepwiseArrayCreation[C](w: var JsonWriter, collection: C): auto
-writeIterable(w: var JsonWriter, collection: auto)
-writeArray[T](w: var JsonWriter, elements: openArray[T])
-
-writeNumber[F,T](w: var JsonWriter[F], value: JsonNumber[T])
-writeJsonValueRef[F,T](w: var JsonWriter[F], value: JsonValueRef[T])
-```
+See the [API reference](./api/json_serialization/writer.html)
 
 ## Enums
 

docs/src/streaming.md

@@ -0,0 +1,52 @@
+# Streaming
+
+`JsonWriter` can be used to incrementally write JSON data.
+
+Incremental processing is ideal for large documents or when you want to avoid building the entire JSON structure in memory.
+
+<!-- toc -->
+
+## Writing
+
+You can use `JsonWriter` to write JSON objects, arrays, and values step by step, directly to a file or any output stream.
+
+The process is similar to when you override `writeValue` to provide custom serialization.
+
+### Example: Writing a JSON Array of Objects
+
+Suppose you want to write a large array of objects to a file, one at a time:
+
+```nim
+{{#include ../examples/streamwrite0.nim}}
+```
+
+Resulting file (`output.json`):
+```json
+[
+  {
+    "id": 0,
+    "name": "item0"
+  },
+  {
+    "id": 1,
+    "name": "item1"
+  }
+]
+```
+
+### Example: Writing Nested Structures
+
+Objects and arrays can be nested arbitrarily.
+
+Here is the same array of JSON objects, nested in an envelope containing an additional `status` field.
+
+Instead of manually placing `begin`/`end` pairs, we're using the convenience helpers `writeObject` and `writeArrayMember`, along with `writeElement` to manage the required element markers:
+
+```ni
+{{#include ../examples/streamwrite1.nim:Nesting}}
+```
+
+This produces a the following output - notice the more compact representation when `pretty = true` is not used:
+```json
+{"status":"ok","data":[{"id":0,"name":"item0"},{"id":1,"name":"item1"}]}
+```

json_serialization/types.nim

@@ -7,6 +7,8 @@
 # This file may not be copied, modified, or distributed except according to
 # those terms.
 
+{.push gcsafe, raises: [].}
+
 import
   std/tables,
   serialization/errors
@@ -18,13 +20,13 @@ export
 type
   JsonError* = object of SerializationError
 
-  # This is a special type to parse whatever
-  # json value into string.
   JsonString* = distinct string
+    ## A string containing valid JSON.
+    ## Used to preserve and pass on parts of a JSON document to another parser
+    ## or layer without interpreting it further
 
-  # This is a special type to parse whatever
-  # json value into nothing/skip it.
   JsonVoid* = object
+    ## Marker used for skipping a JSON value during parsing
 
   JsonSign* {.pure.} = enum
     None
@@ -63,11 +65,11 @@ type
     stringLengthLimit*: int
 
   JsonValueKind* {.pure.} = enum
-    String,
-    Number,
-    Object,
-    Array,
-    Bool,
+    String
+    Number
+    Object
+    Array
+    Bool
     Null
 
   JsonObjectType*[T: string or uint64] = OrderedTable[string, JsonValueRef[T]]
@@ -88,7 +90,6 @@ type
     of JsonValueKind.Null:
       discard
 
-
 const
   minPortableInt* = -9007199254740991 # -2**53 + 1
   maxPortableInt* =  9007199254740991 # +2**53 - 1
@@ -110,8 +111,6 @@ const
     stringLengthLimit: 0,
   )
 
-{.push gcsafe, raises: [].}
-
 template `==`*(lhs, rhs: JsonString): bool =
   string(lhs) == string(rhs)
 
@@ -172,4 +171,7 @@ func `==`*(lhs, rhs: JsonValueRef): bool =
   of JsonValueKind.Null:
     true
 
+template `$`*(s: JsonString): string =
+  string(s)
+
 {.pop.}