json-emitter 0.2.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c101e09517330bff537ee6584fc20ec6c8785a7aa3fd86936599709de18ab54
-  data.tar.gz: 8d8cf0d57d66133d17c5cfc787244dfce26fba9c203049894a818381718720d3
+  metadata.gz: e68f558ac45759cbf0ddd691b8b20f499433dbf2d6321a360280a10b5fdb4840
+  data.tar.gz: 86e900c436e45efcf09fff15061a9e325781699bbb98c4fed8ca7accbeab3b5c
 SHA512:
-  metadata.gz: 21da8c5d80a1be418a5b402e57a240dc5e0e8477f15818b4d1826a2361008cf93720ff1ecc18f1b10099ce7729bec6acea9865772b869f42fc89f388220d1413
-  data.tar.gz: ba6d4e57f31d37a71892a4ad34b419d3401a26e447a4c02f3c5444865c75c86f2b0d7cabc9555571ae84c5804c24b108a6306a4ca1d060e2414c0b864559c73a
+  metadata.gz: ea19aa1f2ec09eb2b9634af8f2dfc9455957696bf28a26cf01bd70b49ff4b81d88e891f6564517cf56490e9482cc00a8a2dc94a0aaa76441d2587a4f0cbb9024
+  data.tar.gz: d246a354e506ccefbd5c8de2b2db1ff7faa2bad31b9425c18d2dc5eadf9fd9ad78e49fa2384aec0bb9f8b6881a3d3b9ac872e3661d40468046ee9e057912fbf6

data/README.md

@@ -1,4 +1,6 @@
-# JsonEmitter [![Build Status](https://travis-ci.org/jhollinger/json-emitter.svg?branch=master)](https://travis-ci.org/jhollinger/json-emitter)
+# JsonEmitter
+
+*NOTE this project may appear inactive, but that's just because it's **done** (I think). Enjoy!*
 
 JsonEmitter is a library for efficiently generating very large bits of JSON in Ruby. Need to generate a JSON array of 10,000 database records without eating up all your RAM? No problem! Objects? Nested structures? JsonEmitter has you covered.
 
@@ -21,7 +23,7 @@ class OrdersController < ApplicationController
   def index
     headers["Content-Type"] = "application/json"
     headers["Last-Modified"] = Time.now.ctime.to_s
-    self.response_body = JsonEmitter.array(enumerator) { |order|
+    self.response_body = JsonEmitter.array(enumerator, rack: env) { |order|
       order.to_h
     }
   end
@@ -33,7 +35,7 @@ end
 ```ruby
 get "/orders" do
   content_type :json
-  JsonEmitter.array(enumerator) { |order|
+  JsonEmitter.array(enumerator, rack: env) { |order|
     order.to_h
   }
 end
@@ -43,7 +45,7 @@ end
 
 ```ruby
 get :orders do
-  stream JsonEmitter.array(enumerator) { |order|
+  stream JsonEmitter.array(enumerator, rack: env) { |order|
     ApiV1::Entities::Order.new(order)
   }
 end
@@ -52,40 +54,106 @@ end
 **Rack**
 
 ```ruby
-app = ->(env) {
-  stream = JsonEmitter.array(enumerator) { |order|
-    order.to_h
+map "/orders" do
+  run ->(env) {
+    stream = JsonEmitter.array(enumerator, rack: env) { |order|
+      order.to_h
+    }
+    [200, {"Content-Type" => "application/json"}, stream]
   }
-  [200, {"Content-Type" => "application/json"}, stream]
-}
+end
 ```
 
-# Other uses
+## Sending objects
 
-`JsonEmitter.array` takes an `Enumerable` and returns a stream that generates chunks of JSON.
-
-```ruby
-JsonEmitter.array(enumerator).each { |json_chunk|
-  # write json_chunk somewhere
-}
-```
-
-`JsonEmitter.object` takes a `Hash` and returns a stream that generates chunks of JSON. Hash values can be literals, Enumerators, Arrays, other Hashes, or Procs that return any of those. Hashes and arrays may be nested.
+You may also stream Hashes as JSON objects. Keys must be Strings or Symbols, but values may be anything: literals, Enumerators, Arrays, other Hashes, or Procs that return any of those.
 
 ```ruby
 JsonEmitter.object({
   orders: Order.find_each.lazy.map { |order|
     {id: order.id, desc: order.description}
   },
+  big_text: ->() { load_tons_of_text },
+}, rack: env)
+```
 
-  big_text_1: ->() {
-    load_tons_of_text
-  },
+## Rack middleware won't work!
 
-  big_text_2: ->() {
-    load_tons_of_text
-  },
-}).each { |json_chunk|
+**IMPORTANT** Your Rack middleware will be *finished* by the time your JSON is built! So if you're depending on middleware to set `Time.zone`, report exceptions, etc. it won't work here. Fortunately, you can use `JsonEmitter.wrap` and `JsonEmitter.error` as replacements.
+
+Put these somewhere like `config/initializers/json_emitter.rb`.
+
+### JsonEmitter.wrap
+
+```ruby
+# Ensure that ActiveRecord connections are returned to the connection pool
+JsonEmitter.wrap do
+  ->(app) { ActiveRecord::Base.with_connection(&app.call) }
+end
+
+JsonEmitter.wrap do
+  # Get TZ at the call site
+  current_tz = Time.zone
+  
+  # Return a Proc that restores the call site's TZ before building the JSON
+  ->(app) {
+    default_tz = Time.zone
+    Time.zone = current_tz
+    res = app.call
+    Time.zone = default_tz
+    res
+  }
+end
+```
+
+### JsonEmitter.error
+
+```ruby
+JsonEmitter.error do |ex, context|
+  Airbrake.notify(ex, {
+    request_path: context.request&.path,
+    query_string: context.request&.query_string,
+  })
+end
+```
+
+## Returning errors
+
+When streaming an HTTP response, you can't change the response code once you start sending data. So if you hit an error after you start, you need another way to communicate errors to the client.
+
+One way is to always steam an object that includes an `errors` field. Any errors will be collected while the `Enumerator` is running. After it's finished, they'll be added to the JSON object.
+
+```ruby
+  def get_data
+    errors = []
+    enum = Enumerator.new { |y|
+      finished = false
+      until finished
+        data, errs, finished = get_data_chunk
+        if errs
+          errors += errs
+          finished = true
+          next
+        end
+        data.each { x| y << x }
+      end
+    }
+    return enum, -> { errors }
+  end
+  
+  items_enum, errors_proc = get_data
+  JsonEmitter.object({
+    items: items_enum,
+    errors: errors_proc,
+  })
+```
+
+# Non-HTTP uses
+
+`JsonEmitter.array` takes an `Enumerable` and returns a stream that generates chunks of JSON.
+
+```ruby
+JsonEmitter.array(enumerator).each { |json_chunk|
   # write json_chunk somewhere
 }
 ```
@@ -104,4 +172,4 @@ MIT License. See LICENSE for details.
 
 # Copyright
 
-Copywrite (c) 2019 Jordan Hollinger.
+Copyright (c) 2019 Jordan Hollinger.

data/lib/json-emitter/buffered_stream.rb

@@ -62,12 +62,12 @@ module JsonEmitter
 
     def buffer
       Enumerator.new { |y|
-        buff = ""
+        buff = +""
         @enum.each { |str|
           buff << str
           if buff.bytesize >= @buffer_size
             y << buff
-            buff = ""
+            buff = +""
           end
         }
         y << buff unless buff.empty?

data/lib/json-emitter/context.rb

@@ -19,16 +19,43 @@ module JsonEmitter
       @pass_through_errors << Puma::ConnectionError if defined? Puma::ConnectionError
     end
 
+    #
     # Wrap the enumeration in a block. It will be passed a callback which it must call to continue.
-    # TODO better docs and examples.
+    # Define your wrappers somewhere like config/initializers/json_emitter.rb.
+    #
+    # JsonEmitter.wrap do
+    #   # Get TZ at the call site
+    #   current_tz = Time.zone
+    #
+    #   # Return a Proc that restores the call site's TZ before building the JSON
+    #   ->(app) {
+    #     default_tz = Time.zone
+    #     Time.zone = current_tz
+    #     res = app.call
+    #     Time.zone = default_tz
+    #     res
+    #   }
+    # end
+    #
     def wrap(&block)
       if (wrapper = block.call)
         @wrappers.unshift wrapper
       end
     end
 
-    # Add an error handler.
-    # TODO better docs and examples.
+    #
+    # Add an error handler. If the callsite is in a Rack app, the context will have a
+    # Rack::Request in context.request.
+    #
+    # Define your error handlers somewhere like config/initializers/json_emitter.rb.
+    #
+    # JsonEmitter.error do |ex, context|
+    #   Airbrake.notify(ex, {
+    #     request_path: context.request&.path,
+    #     query_string: context.request&.query_string,
+    #   })
+    # end
+    #
     def error(&handler)
       @error_handlers += [handler]
     end

data/lib/json-emitter/version.rb

@@ -1,4 +1,4 @@
 module JsonEmitter
   # Library version
-  VERSION = "0.2.0".freeze
+  VERSION = "1.1.0".freeze
 end

data/lib/json-emitter.rb

@@ -104,14 +104,41 @@ module JsonEmitter
     BufferedStream.new(emitter, buffer_size, unit: buffer_unit)
   end
 
-  # Wrap the enumeration in a Proc. It will be passed a callback which it must call to continue.
-  # TODO better docs and examples.
+  #
+  # Wrap the enumeration in a block. It will be passed a callback which it must call to continue.
+  # Define your wrappers somewhere like config/initializers/json_emitter.rb.
+  #
+  # JsonEmitter.wrap do
+  #   # Get TZ at the call site
+  #   current_tz = Time.zone
+  #
+  #   # Return a Proc that restores the call site's TZ before building the JSON
+  #   ->(app) {
+  #     default_tz = Time.zone
+  #     Time.zone = current_tz
+  #     res = app.call
+  #     Time.zone = default_tz
+  #     res
+  #   }
+  # end
+  #
   def self.wrap(&wrapper)
     @wrappers.unshift wrapper
   end
 
-  # Add an error handler.
-  # TODO better docs and examples.
+  #
+  # Add an error handler. If the callsite is in a Rack app, the context will have a
+  # Rack::Request in context.request.
+  #
+  # Define your error handlers somewhere like config/initializers/json_emitter.rb.
+  #
+  # JsonEmitter.error do |ex, context|
+  #   Airbrake.notify(ex, {
+  #     request_path: context.request&.path,
+  #     query_string: context.request&.query_string,
+  #   })
+  # end
+  #
   def self.error(&handler)
     @error_handlers << handler
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: json-emitter
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Jordan Hollinger
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-04-29 00:00:00.000000000 Z
+date: 2025-07-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_json
@@ -41,7 +41,7 @@ homepage: https://jhollinger.github.io/json-emitter/
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -49,15 +49,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
 summary: Efficiently generate tons of JSON
 test_files: []