smarter_json 0.8.0 → 0.9.9

data/docs/_introduction.md

@@ -11,7 +11,7 @@
 
 # SmarterJSON Introduction
 
-`smarter_json` is a fast, lenient JSON parser and writer for Ruby. It reads strict JSON, JSON5, HJSON-style config, newline-delimited JSON (NDJSON / JSONL), markdown-wrapped / chatty blobs around a JSON payload, and the messy JSON-ish input humans actually paste — and in benchmarks it matches or beats Oj on nearly every file. It is opinionated: it optimizes for getting your data out, not for policing the JSON spec. Where other parsers stop at the first deviation, SmarterJSON keeps going.
+`smarter_json` is a fast, lenient JSON processor for Ruby. It reads strict JSON, JSON5, HJSON-style config, newline-delimited JSON (NDJSON / JSONL), markdown-wrapped / chatty blobs around a JSON payload, and the messy JSON-ish input humans actually paste — and in benchmarks it matches or beats Oj on every file. It is opinionated: it optimizes for getting your data out, not for policing the JSON spec. Where other parsers stop at the first deviation, SmarterJSON keeps going.
 
 ## Why another JSON library?
 
@@ -21,27 +21,21 @@ Most JSON parsers reject anything that isn't perfectly strict JSON, and they mak
 
 * **One reader, no modes, no flags.** There is no `dialect:` option and no "strict mode" — `SmarterJSON.process(input)` accepts the whole superset, and strict JSON is simply the narrowest case. You don't configure the reader to match your input; it adapts to whatever you give it.
 
-* **It reads multi-document input automatically — a distinguishing feature.** `SmarterJSON.process` handles NDJSON / JSONL / concatenated JSON with **no block and no special method**: zero documents returns `nil`, one document returns its value, two or more return an `Array`. The same rule applies when wrapper noise is stripped and several payloads are recovered from one blob. **Only SmarterJSON reads multi-document input via plain `process` — Oj and the stdlib `json` library raise without a block.** Pass a block to iterate the recovered documents one at a time. See [The Basic Read API](./basic_read_api.md).
+* **It reads multi-document input automatically — a distinguishing feature.** `SmarterJSON.process` handles NDJSON / JSONL / concatenated JSON with **no block and no special method**: it always returns an `Array` of the documents found (`[]` / `[doc]` / `[d1, d2, …]`). For the common single-document case, `SmarterJSON.process_one` returns the one value directly (and warns, never raises, if there was more than one). The same rule applies when wrapper noise is stripped and several payloads are recovered from one blob. **Only SmarterJSON reads multi-document input via plain `process` — Oj and the stdlib `json` library raise without a block.** For input larger than memory, pass a block to stream one document at a time. See [The Basic Read API](./basic_read_api.md).
 
-* **It's fast.** A C extension (with a pure-Ruby fallback that runs everywhere) puts it ahead of Oj on nearly every file we benchmark, and competitive with the stdlib `json` C parser. Floats are parsed with Ryū (correctly rounded, single-pass), so number-heavy data is fast and bit-exact.
+* **It's fast.** A C extension (with a pure-Ruby fallback that runs everywhere) matches or beats Oj on every file we benchmark, and is competitive with the stdlib `json` C parser. Floats are decoded with the **Eisel-Lemire** algorithm (fast_float), correctly rounded and bit-for-bit identical to `JSON.parse`, so number-heavy data is fast and exact.
 
 * **It writes JSON too.** `SmarterJSON.generate` turns Ruby values into strict, interoperable JSON — or into NDJSON, one element per line, the exact inverse of reading NDJSON back into an Array. See [The Basic Write API](./basic_write_api.md).
 
 ## What it accepts, beyond strict JSON
 
-* `//`, `/* … */`, and `#` comments (a `#`/`//` only starts a comment when preceded by whitespace, so `url: http://x.com` reads as a string, not a truncated value)
-* Trailing commas; unquoted keys (`{host: localhost}`); single-quoted, triple-quoted (`'''…'''`), and quoteless string values
-* Implicit root object — a config file that starts with `key: value`, no outer `{}`
-* `NaN`, `Infinity`, hex (`0xFF`), leading `+` / `.`, underscores in numbers (`1_000_000`)
-* UTF-8 BOM, smart/curly quotes, Python literals (`True` / `False` / `None`), JavaScript `undefined`
-* Mixed CR / LF / CRLF line endings, and any Ruby-supported input encoding (via `encoding:`)
-* Duplicate keys (last value wins by default; configurable — see [Configuration Options](./options.md))
+Comments (`//`, `/* … */`, `#` — a `#`/`//` only starts a comment when preceded by whitespace, so `url: http://x.com` reads as a string, not a truncated value), markdown-wrapped / chatty blobs around the payload, trailing commas, unquoted / single- / triple-quoted / quoteless strings, an implicit root object (`key: value`, no braces), `NaN` / `Infinity` / hex / underscored numbers, Python (`True` / `False` / `None`) and JavaScript (`undefined`) literals, smart quotes, a UTF-8 BOM, mixed CR / LF / CRLF line endings, any Ruby-supported input encoding (via `encoding:`), and duplicate keys. The full list — with the human-JSON spec references it's drawn from — is kept in one place: [**What it accepts, beyond strict JSON**](../README.md#what-it-accepts-beyond-strict-json) in the README.
 
-It raises only on genuinely unparseable input (unterminated string, mismatched bracket), with line and column in the message — never on valid-but-lenient input.
+It raises only on genuinely unreadable input (unterminated string, mismatched bracket), with line and column in the message — never on valid-but-lenient input.
 
 ## Nesting & untrusted input
 
-Both the C extension and the pure-Ruby parser are **iterative, not recursive** — they track nesting on an explicit, heap-allocated stack rather than the call stack. So deeply nested input **cannot overflow the call stack or segfault**: nesting is bounded only by available memory, the same posture as Oj (the stdlib `json` caps at 100). The trade-off: there is currently **no fixed nesting or input-size limit**, so size-limit untrusted input upstream of the parser.
+Both the C extension and the pure-Ruby engine are **iterative, not recursive** — they track nesting on an explicit, heap-allocated stack rather than the call stack. So deeply nested input **cannot overflow the call stack or segfault**: nesting is bounded only by available memory, the same posture as Oj (the stdlib `json` caps at 100). The trade-off: there is currently **no fixed nesting or input-size limit**, so size-limit untrusted input upstream.
 
 ---------------
 

data/docs/basic_read_api.md

@@ -18,40 +18,83 @@ Reading JSON has one entry point for content and one for files. Both accept the
 ```ruby
 require "smarter_json"
 
-SmarterJSON.process('{"a": 1, "b": [2, 3]}')          # => {"a"=>1, "b"=>[2, 3]}
-SmarterJSON.process("host: localhost\nport: 5432")     # => {"host"=>"localhost", "port"=>5432}  (no braces needed)
+SmarterJSON.process('{"a": 1, "b": [2, 3]}')          # => [{"a"=>1, "b"=>[2, 3]}]   (always an Array of documents)
+SmarterJSON.process_one('{"a": 1, "b": [2, 3]}')      # => {"a"=>1, "b"=>[2, 3]}     (the single document's value)
+SmarterJSON.process_one("host: localhost\nport: 5432") # => {"host"=>"localhost", "port"=>5432}  (no braces needed)
 ```
 
-`process` is polymorphic: its first argument is **either a String of JSON content or an IO to read from**. A String is always treated as content, never as a filename — use `process_file` for paths. When the input wraps the payload in obvious markdown / prose / tags, `process` strips that wrapper first and then parses the recovered payload(s).
+`process` accepts **either a String of JSON content or an IO to read from** as its first argument. A String is always treated as content, never as a filename — use `process_file` for paths. When the input wraps the payload in obvious markdown / prose / tags, `process` strips that wrapper first and then reads the recovered payload(s).
+
+````ruby
+SmarterJSON.process_one(<<~TEXT)
+  Here is the JSON:
+
+  ```json
+  {
+    "a": 1
+  }
+  ```
+TEXT
+# => {"a"=>1}
+
+SmarterJSON.process_one(<<~TEXT)
+  Here is the result:
+
+  {
+    "a": 1
+  }
+
+  Hope this helps.
+TEXT
+# => {"a"=>1}
+
+SmarterJSON.process(<<~TEXT)
+  first attempt:
+  {"a":1}
+
+  corrected payload:
+  {"b":2}
+TEXT
+# => [{"a"=>1}, {"b"=>2}]
+````
 
 ```ruby
-SmarterJSON.process(io)         # an open IO (File, StringIO, socket, …) — reads it and parses
+SmarterJSON.process(io)         # an open IO (File, StringIO, socket, …) — reads it and extracts the data
 SmarterJSON.process(some_string) # JSON content
 ```
 
-### Return value depends on how many documents the input holds
+### `process` always returns an Array of documents
+
+This is the distinguishing feature: `process` reads multi-document input (NDJSON / JSONL / concatenated) automatically, with no block and no special method, and **always returns an `Array` of the documents** it found:
+
+```ruby
+SmarterJSON.process("")                                 # => []            (zero documents)
+SmarterJSON.process('{"id":1}')                          # => [{"id"=>1}]   (one document, still an Array)
+SmarterJSON.process(%({"id":1}\n{"id":2}\n{"id":3}))     # => [{"id"=>1}, {"id"=>2}, {"id"=>3}]
+```
 
-This is the distinguishing feature: `process` reads multi-document input (NDJSON / JSONL / concatenated / whitespace-separated) automatically, with no block and no special method.
+For the common single-document case, **`process_one`** returns the one value directly — and *warns* (never raises) if there was more than one, so a stray extra document is never dropped silently:
 
 ```ruby
-SmarterJSON.process("")                                 # => nil          (zero documents)
-SmarterJSON.process('{"id":1}')                          # => {"id"=>1}    (one document → the value itself)
-SmarterJSON.process(%({"id":1}\n{"id":2}\n{"id":3}))     # => [{"id"=>1}, {"id"=>2}, {"id"=>3}]  (two or more → an Array)
+SmarterJSON.process_one('{"id":1}')   # => {"id"=>1}
+SmarterJSON.process_one("")           # => nil
 ```
 
-Documents are separated by whitespace, newlines, or simple concatenation — **not** by commas (a comma between top-level documents would be read as an implicit root array, which is not supported). If wrapper noise is stripped and several payloads are recovered, they are returned by the same rule: one payload → its value, several → an `Array`. Only SmarterJSON reads this via plain `process`: Oj and the stdlib `json` library raise without a block.
+> Type-checking the result? Use `result.is_a?(Array)`, not `result.class == Array` — idiomatic, and future-proof if the return ever becomes a specialized `Array` subclass.
+
+Documents are separated by **newlines, commas, RS (0x1E), or simple concatenation (self-delimiting values)** — **never by a space**. A top-level value must be a recognized JSON value (number / `true` / `false` / `null` / quoted string / object / array) or an implicit-root object (`host: localhost`); a bare top-level run such as `localhost` or `1 2 3` raises `ParseError`. (Quoteless string values *inside* objects and arrays are unchanged.) If wrapper noise is stripped and several payloads are recovered, they come back by the same rule — an `Array` of payloads (`process_one` returns the first). Only SmarterJSON reads multi-document input via plain `process`: Oj and the stdlib `json` library raise without a block.
 
 ## `SmarterJSON.process_file` — read a file by path
 
 ```ruby
-SmarterJSON.process_file("config.json5")     # read the file, then parse — same return-value rules as process
+SmarterJSON.process_file("config.json5")     # read the file, then process — same return-value rules as process
 ```
 
-`process_file` opens the file, reads it with the labeled [`encoding:`](./options.md) (default `"UTF-8"`, no transcoding pass), and parses it.
+`process_file` opens the file, reads it with the labeled [`encoding:`](./options.md) (default `"UTF-8"`, no transcoding pass), and processes it.
 
-## Streaming with a block
+## Streaming with a block (bounded memory)
 
-Pass a block to have each recovered top-level document yielded one at a time; the method returns `nil` instead of collecting the documents into an Array. Both `process` and `process_file` forward the block.
+For input larger than memory, pass a block. Each recovered top-level document is yielded as it is framed, and the method returns the **document count** instead of collecting the documents into an Array. Both `process` and `process_file` forward the block.
 
 ```ruby
 SmarterJSON.process_file("events.ndjson") { |event| EventJob.perform_async(event) }
@@ -62,7 +105,7 @@ The streaming path now frames whole top-level documents, not just one line at a
 
 ## The C extension and the pure-Ruby fallback
 
-By default (`acceleration: true`) the C extension is used when it is compiled and loadable (`SmarterJSON::HAS_ACCELERATION` is then `true`); otherwise the pure-Ruby parser runs and produces identical results. Pass `acceleration: false` to force the pure-Ruby path. See [Configuration Options](./options.md).
+By default (`acceleration: true`) the C extension is used when it is compiled and loadable (`SmarterJSON::HAS_ACCELERATION` is then `true`); otherwise the pure-Ruby implementation runs and produces identical results. Pass `acceleration: false` to force the pure-Ruby path. See [Configuration Options](./options.md).
 
 ## Seeing what was fixed: `on_warning:`
 
@@ -71,7 +114,7 @@ By default (`acceleration: true`) the C extension is used when it is compiled an
 ```ruby
 warns = []
 result = SmarterJSON.process("[1,,2]", on_warning: ->(w) { warns << w })
-result            # => [1, 2]
+result            # => [[1, 2]]   (one document: the array [1, 2] with the empty slot collapsed; process always returns an Array of documents)
 warns.map(&:type) # => [:empty_slot]
 warns.first.to_s  # => "extra comma, collapsed an empty slot at line 1, col 4"
 ```

data/docs/basic_write_api.md

@@ -127,11 +127,11 @@ Note the difference from the default `format: :json`, where a top-level Array is
 
 ## Round-tripping
 
-`process` and `generate` are inverses:
+`process_one` reads one document back, `process` reads many (NDJSON) back into an `Array` — each is the inverse of the matching `generate`:
 
 ```ruby
 obj = { "a" => 1, "b" => [2, "three", nil, true] }
-SmarterJSON.process(SmarterJSON.generate(obj)) == obj                                  # => true
+SmarterJSON.process_one(SmarterJSON.generate(obj)) == obj                              # => true
 
 arr = [{ "id" => 1 }, { "id" => 2 }, { "id" => 3 }]
 SmarterJSON.process(SmarterJSON.generate(arr, format: :ndjson)) == arr                 # => true

data/docs/examples.md

@@ -11,7 +11,9 @@
 
 # Examples
 
-**Rescue from `SmarterJSON::Error` (recommended):** SmarterJSON raises only on genuinely unparseable input (an unterminated string, a mismatched bracket), with line and column in the message. Rescuing from `SmarterJSON::Error` lets your application handle bad input gracefully.
+**Rescue from `SmarterJSON::Error` (recommended):** SmarterJSON raises only on genuinely unreadable input (an unterminated string, a mismatched bracket), with line and column in the message. Rescuing from `SmarterJSON::Error` lets your application handle bad input gracefully.
+
+**`process` vs `process_one`:** `SmarterJSON.process` is the preferred call — it always returns an `Array` of documents, so the count is explicit and you never silently drop one. `SmarterJSON.process_one` is the convenience for the single-document case: it returns that one document's value directly, and *warns* (never raises) if the input turned out to hold more than one. Both appear below; reach for `process` unless you specifically want the single value.
 
 ---
 
@@ -36,38 +38,46 @@
 ```ruby
 require "smarter_json"
 
-SmarterJSON.process('{"a": 1, "b": [2, 3]}')   # => {"a"=>1, "b"=>[2, 3]}
+SmarterJSON.process('{"a": 1, "b": [2, 3]}')       # => [{"a"=>1, "b"=>[2, 3]}]   (always an Array of documents)
+SmarterJSON.process_one('{"a": 1, "b": [2, 3]}')   # => {"a"=>1, "b"=>[2, 3]}     (the one document's value)
 ```
 
 ### Example 2: Read a JSON File
 
 ```ruby
-SmarterJSON.process_file("config.json")        # => the parsed value
+SmarterJSON.process_file("config.json")        # => an Array of documents (same return rules as process)
 ```
 
-`process_file` opens the file, reads it with the labeled [`encoding:`](./options.md) (default `"UTF-8"`), and parses it.
+`process_file` opens the file, reads it with the labeled [`encoding:`](./options.md) (default `"UTF-8"`), and processes it.
 
 ### Example 3: Implicit Root Object (config-style, no braces)
 
 A config file that starts with `key: value` and has no outer `{}` is read as an object:
 
 ```ruby
-SmarterJSON.process("host: localhost\nport: 5432")   # => {"host"=>"localhost", "port"=>5432}
+SmarterJSON.process_one("host: localhost\nport: 5432")   # => {"host"=>"localhost", "port"=>5432}
 ```
 
 ### Example 4: Multiple Documents (NDJSON) → Array
 
-Plain `process` reads NDJSON / JSONL / concatenated documents with no block and no special method. Zero documents → `nil`, one → its value, two or more → an `Array`:
+Plain `process` reads NDJSON / JSONL / concatenated documents with no block and no special method, and always returns an `Array` — `[]` for none, `[doc]` for one, `[d1, d2, …]` for several:
 
 ```ruby
 SmarterJSON.process(%({"id":1}\n{"id":2}\n{"id":3}))   # => [{"id"=>1}, {"id"=>2}, {"id"=>3}]
-SmarterJSON.process('{"id":1}')                          # => {"id"=>1}
-SmarterJSON.process("")                                  # => nil
+SmarterJSON.process('{"id":1}')                          # => [{"id"=>1}]   (one document, still an Array)
+SmarterJSON.process("")                                  # => []            (zero documents)
+```
+
+For the single-document case, `process_one` returns the one value directly — and *warns* (never raises) if there was more than one:
+
+```ruby
+SmarterJSON.process_one('{"id":1}')   # => {"id"=>1}
+SmarterJSON.process_one("")           # => nil
 ```
 
-### Example 5: Iterate Documents with a Block
+### Example 5: Streaming a Large File with a Block
 
-Pass a block to receive each recovered document one at a time:
+For input larger than memory, pass a block. Each recovered document is yielded one at a time, and the method returns the **document count** instead of building an `Array`:
 
 ```ruby
 SmarterJSON.process_file("events.ndjson") { |event| EventJob.perform_async(event) }
@@ -76,17 +86,16 @@ SmarterJSON.process_file("events.ndjson") { |event| EventJob.perform_async(event
 ### Example 6: Symbolize Keys
 
 ```ruby
-SmarterJSON.process('{"a": 1, "b": 2}', symbolize_keys: true)   # => {:a=>1, :b=>2}
+SmarterJSON.process_one('{"a": 1, "b": 2}', symbolize_keys: true)   # => {:a=>1, :b=>2}
 ```
 
 ### Example 7: Duplicate Keys
 
-By default the last value wins. Choose `:first_wins` or `:raise` instead:
+By default the last value wins. Pass `:first_wins` to keep the first instead (either way, the repeat is reported through [`on_warning`](./options.md)):
 
 ```ruby
-SmarterJSON.process('{"a":1,"a":2}')                          # => {"a"=>2}   (:last_wins, the default)
-SmarterJSON.process('{"a":1,"a":2}', duplicate_key: :first_wins)  # => {"a"=>1}
-SmarterJSON.process('{"a":1,"a":2}', duplicate_key: :raise)   # raises SmarterJSON::ParseError
+SmarterJSON.process_one('{"a":1,"a":2}')                          # => {"a"=>2}   (:last_wins, the default)
+SmarterJSON.process_one('{"a":1,"a":2}', duplicate_key: :first_wins)  # => {"a"=>1}
 ```
 
 ### Example 8: High-Precision Numbers: BigDecimal vs Float
@@ -94,14 +103,14 @@ SmarterJSON.process('{"a":1,"a":2}', duplicate_key: :raise)   # raises SmarterJS
 The default `:auto` keeps high-precision decimals as `BigDecimal` (matching Oj). Force `Float` for raw speed when you don't need the precision:
 
 ```ruby
-SmarterJSON.process("65.613616999999977")                        # => BigDecimal (:auto, the default)
-SmarterJSON.process("65.613616999999977", bigdecimal_load: :float)  # => 65.613616999999977 (a Float)
+SmarterJSON.process_one("65.613616999999977")                        # => BigDecimal (:auto, the default)
+SmarterJSON.process_one("65.613616999999977", decimal_precision: :float)  # => 65.613616999999977 (a Float)
 ```
 
 ### Example 9: Lenient Input: Comments, Trailing Commas, Unquoted Keys
 
 ```ruby
-SmarterJSON.process(<<~JSON)
+SmarterJSON.process_one(<<~JSON)
   {
     host: localhost,   # unquoted key, quoteless value, and a trailing comma
     port: 5432,
@@ -116,8 +125,10 @@ A `#`/`//` only starts a comment when preceded by whitespace, so `http://example
 
 ### Example 10: Wrapper Noise Around a Payload
 
-```ruby
-SmarterJSON.process(<<~TEXT)
+#### Fenced payload
+
+````ruby
+SmarterJSON.process_one(<<~TEXT)
   Here is the JSON:
 
   ```json
@@ -127,15 +138,38 @@ SmarterJSON.process(<<~TEXT)
   ```
 TEXT
 # => {"a"=>1}
+````
+
+#### Prose before / after the payload
+
+```ruby
+SmarterJSON.process_one(<<~TEXT)
+  Here is the result:
+
+  {
+    "a": 1
+  }
+
+  Hope this helps.
+TEXT
+# => {"a"=>1}
+```
+
+#### Wrapper tags
 
-SmarterJSON.process("<json>{\"a\":1}</json>")
+```ruby
+SmarterJSON.process_one("<json>{\"a\":1}</json>")
 # => {"a"=>1}
+```
+
+#### Multiple recovered payloads from one noisy blob
 
+```ruby
 SmarterJSON.process(<<~TEXT)
-  first:
+  first attempt:
   {"a":1}
 
-  second:
+  corrected payload:
   {"b":2}
 TEXT
 # => [{"a"=>1}, {"b"=>2}]
@@ -160,7 +194,7 @@ SmarterJSON.generate([{ "id" => 1 }, { "id" => 2 }], format: :ndjson)   # => "{\
 
 ```ruby
 obj = { "a" => 1, "b" => [2, "three", nil, true] }
-SmarterJSON.process(SmarterJSON.generate(obj)) == obj   # => true
+SmarterJSON.process_one(SmarterJSON.generate(obj)) == obj   # => true
 ```
 
 ---------------

data/docs/options.md

@@ -13,32 +13,32 @@
 
 ## Reading
 
-These options are passed to [`SmarterJSON.process`](./basic_read_api.md) and `SmarterJSON.process_file` as the second argument; anything you set overrides the defaults below.
+These options are passed to [`SmarterJSON.process`](./basic_read_api.md), `SmarterJSON.process_one`, and `SmarterJSON.process_file` as the second argument; anything you set overrides the defaults below.
 
 | Option            | Default      | Explanation                                                                                                            |
 |-------------------|--------------|------------------------------------------------------------------------------------------------------------------------|
-| `:symbolize_keys` | `false`      | Return object keys as Symbols instead of Strings.                                                                      |
-| `:duplicate_key`  | `:last_wins` | How to handle a key that repeats within one object: `:last_wins`, `:first_wins`, or `:raise`.                          |
-| `:bigdecimal_load`| `:auto`      | `:auto` keeps high-precision decimals as `BigDecimal` (matches Oj); `:float` forces every number to `Float`; `:bigdecimal` forces every decimal to `BigDecimal`. |
-| `:acceleration`   | `true`       | Use the C extension when it is compiled and loadable; `false` forces the pure-Ruby parser. Both produce identical results. |
+| `:acceleration`   | `true`       | Use the C extension when it is compiled and loadable; `false` forces the pure-Ruby implementation. Both produce identical results. |
+| `:decimal_precision`| `:auto`      | `:auto` keeps high-precision decimals as `BigDecimal` (matches Oj); `:float` forces every number to `Float`; `:bigdecimal` forces every decimal to `BigDecimal`. |
+| `:duplicate_key`  | `:last_wins` | How to handle a key that repeats within one object: `:last_wins` or `:first_wins`. (Every repeat is also reported through `:on_warning` — see below.)                          |
 | `:encoding`       | `nil`        | Labels the input's encoding (e.g. `"UTF-8"`). It does **not** trigger a transcoding pass — see below.                  |
 | `:on_warning`     | `nil`        | A callable invoked once per lenient fix applied, passed a `SmarterJSON::Warning`. Never changes the return value. See below. |
+| `:symbolize_keys` | `false`      | Return object keys as Symbols instead of Strings.                                                                      |
 
 ```ruby
-SmarterJSON.process('{"a": 1}', symbolize_keys: true)               # => {:a=>1}
-SmarterJSON.process('{"a":1,"a":2}', duplicate_key: :raise)         # raises SmarterJSON::ParseError
-SmarterJSON.process(big_decimal_json, bigdecimal_load: :float)      # every number as Float (fastest)
-SmarterJSON.process("[1,,2]", on_warning: ->(w) { puts w })         # => [1, 2], and prints the warning
+SmarterJSON.process_one('{"a": 1}', symbolize_keys: true)               # => {:a=>1}
+SmarterJSON.process_one('{"a":1,"a":2}', duplicate_key: :first_wins)    # => {"a"=>1}  (default keeps the 2)
+SmarterJSON.process_one(big_decimal_json, decimal_precision: :float)      # every number as Float (fastest)
+SmarterJSON.process_one("[1,,2]", on_warning: ->(w) { puts w })         # => [1, 2], and prints the warning
 ```
 
 ### A note on `:on_warning`
 
-`smarter_json` is lenient by design — it salvages your data instead of rejecting the whole document over a stray comma. `on_warning:` keeps that, but also hands you a record of what it had to fix, so leniency is transparent rather than silent. It takes a callable that the parser invokes once per fix, passing a `SmarterJSON::Warning` (with `type` (a Symbol), `message`, `line`, and `col`). It never changes the return value — `process` still hands back the bare value — and it fires on every path, including the streaming block form. With no handler (the default), nothing is recorded and there is zero overhead.
+`smarter_json` is lenient by design — it salvages your data instead of rejecting the whole document over a stray comma. `on_warning:` keeps that, but also hands you a record of what it had to fix, so leniency is transparent rather than silent. It takes a callable that SmarterJSON invokes once per fix, passing a `SmarterJSON::Warning` (with `type` (a Symbol), `message`, `line`, and `col`). It never changes the return value — `process` still returns its `Array` of documents (and `process_one` its single value) — and it fires on every path, including the streaming block form. With no handler (the default), nothing is recorded and there is zero overhead.
 
 ```ruby
 warns = []
 result = SmarterJSON.process("[1,,2]", on_warning: ->(w) { warns << w })
-result                         # => [1, 2]
+result                         # => [[1, 2]]   (one document: the array [1, 2], with the empty slot collapsed)
 warns.map(&:type)              # => [:empty_slot]
 warns.first.to_s               # => "extra comma, collapsed an empty slot at line 1, col 4"
 ```
@@ -47,11 +47,11 @@ The warning types are `:empty_slot` (a collapsed empty comma slot, e.g. `[1,,2]`
 
 ### A note on `:encoding`
 
-`:encoding` labels what the input *is* — it does not transcode. The parser works on the bytes in their native encoding and emits string values with the same encoding tag, the same way `smarter_csv` handles encodings. Bytes that are invalid for the claimed encoding raise `SmarterJSON::EncodingError` (a kind of `SmarterJSON::ParseError`). A UTF-8 BOM is handled automatically; UTF-16 / UTF-32 input is out of scope.
+`:encoding` labels what the input *is* — it does not transcode. SmarterJSON works on the bytes in their native encoding and emits string values with the same encoding tag, the same way `smarter_csv` handles encodings. Bytes that are invalid for the claimed encoding raise `SmarterJSON::EncodingError` (a kind of `SmarterJSON::ParseError`). A UTF-8 BOM is handled automatically; UTF-16 / UTF-32 input is out of scope.
 
-### A note on `:bigdecimal_load`
+### A note on `:decimal_precision`
 
-The default `:auto` preserves high-precision numbers as `BigDecimal`, matching Oj's default. That is intrinsically slower than producing `Float` on number-heavy files (e.g. `canada.json`). For raw speed when you don't need the extra precision, pass `bigdecimal_load: :float`.
+The default `:auto` preserves high-precision numbers as `BigDecimal`, matching Oj's default. That is intrinsically slower than producing `Float` on number-heavy files (e.g. `canada.json`). For raw speed when you don't need the extra precision, pass `decimal_precision: :float`.
 
 ## Writing