json-emitter 0.0.4 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ffd5b387bbbf0ce7f40a9b725dbaaea83a479ac53ada2ede1f01231c5be28e1
-  data.tar.gz: c0af5bb60b80c67da129f2ba14fea69a99c97ba69a47e508de165ebb12bf11e7
+  metadata.gz: d2228e23ca76886db68f546e171db2e9c318f35c02e4262b19adf162d43e1151
+  data.tar.gz: c137299a78e76f0ffdeba789d9477ef94a4b161d0718287ba074dcbc90f4c82d
 SHA512:
-  metadata.gz: 6ffb66b5cae058582b8d0904b6ae55272b7065ea6f412a2ddc7ab6db89a030f1e13c7801894e672f182c2da0b72d9e7211b9751f500f05fa91c8356679416403
-  data.tar.gz: e7a855f40029fbd7343cd4bfebf0e59594d81257fd2d0a232b8bf9cee4d0ac82210c8fa8907f6c5ae0eeaf4ee3acb68ca5b58adaa9a7525c1c094ac8f67e6d35
+  metadata.gz: b2a21066822a1e4f84df8facee734dd60951dbd489d5e80444be11546e9851e77f9d8c9edc6f9fd1900fd55407cf96cbc193c4402223aa78459265a119ab75a5
+  data.tar.gz: 2b025e42af1069efc578d5138e6535b35b507659e931ce59dd9164d96adc7dd1d1ceec334b22aa710a233198b63d8cad033b67e244d52a78854d553383e41bea

data/README.md

@@ -1,12 +1,12 @@
-# JsonEmitter
+# JsonEmitter [![Build Status](https://travis-ci.org/jhollinger/json-emitter.svg?branch=master)](https://travis-ci.org/jhollinger/json-emitter)
 
 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.
 
-Use JsonEmitter in your Rack/Rails/Sinatra/Grape API to stream large JSON responses without worrying about RAM or HTTP timeouts. Use it to write large JSON objects to your filesystem, S3, or ~~a 3D printer~~ anywhere else!
+Use JsonEmitter in your Rack/Rails/Sinatra/Grape API to stream large JSON responses without worrying (much) about RAM or HTTP timeouts. Use it to write large JSON objects to your filesystem, S3, or ~~a 3D printer~~ anywhere else!
 
 # HTTP Chunked Responses
 
-These examples will use the Order enumerator to generate chunks of JSON and send them to the client as more chunks are generated. No more than 500 orders will be in memory at a time, regardless of how many orders there are. And only small portions of the JSON will be in memory at once, no matter how much we're generating.
+These examples will use the Order enumerator to generate chunks of JSON and send them to the client as more chunks are generated. No more than 500 orders will be in memory at a time, regardless of how many orders there are. And only small portions of the JSON will be in memory at once, no matter how much we're generating. (NOTE There **are** limits to how long something will stream - your app server, nginx/apache, your browser, etc. may cut it off eventually.)
 
 ```ruby
 enumerator = Order.
@@ -70,7 +70,7 @@ JsonEmitter.array(enumerator).each { |json_chunk|
 }
 ```
 
-`JsonEmitter.object` takes a `Hash` and returns a stream that generates chunks of JSON.
+`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.
 
 ```ruby
 JsonEmitter.object({
@@ -97,3 +97,42 @@ File.open("~/out.json", "w+") { |f|
   JsonEmitter.array(enumerator).write f
 }
 ```
+
+# Deailing with 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,
+  })
+```
+
+# License
+
+MIT License. See LICENSE for details.
+
+# Copyright
+
+Copywrite (c) 2019 Jordan Hollinger.

data/lib/json-emitter/context.rb

@@ -8,7 +8,11 @@ module JsonEmitter
   # and JsonEmitter.error to add critical behavior back in.
   #
   class Context
-    def initialize
+    # @return [Hash] The Rack environment Hash (if present)
+    attr_reader :rack_env
+
+    def initialize(rack_env: nil)
+      @rack_env = rack_env
       @wrappers = JsonEmitter.wrappers.map(&:call).compact
       @error_handlers = JsonEmitter.error_handlers
       @pass_through_errors = []
@@ -29,6 +33,13 @@ module JsonEmitter
       @error_handlers += [handler]
     end
 
+    # Returns a Rack::Request from rack_env (if rack_env was given).
+    def request
+      if rack_env
+        @request ||= Rack::Request.new(rack_env)
+      end
+    end
+
     # Execute a block within this context.
     def execute(&inner)
       @wrappers.reduce(inner) { |f, outer_wrapper|
@@ -38,7 +49,7 @@ module JsonEmitter
     rescue *@pass_through_errors => e
       raise e
     rescue => e
-      @error_handlers.each { |h| h.call(e) }
+      @error_handlers.each { |h| h.call(e, self) }
       raise e
     end
   end

data/lib/json-emitter/emitter.rb

@@ -1,4 +1,6 @@
 module JsonEmitter
+  COMMA = ",".freeze
+
   #
   # Builds Enumerators that yield JSON from Ruby Arrays or Hashes.
   #
@@ -6,8 +8,8 @@ module JsonEmitter
     # @return [JsonEmitter::Context]
     attr_reader :context
 
-    def initialize
-      @context = Context.new
+    def initialize(rack_env: nil)
+      @context = Context.new(rack_env: rack_env)
     end
 
     #
@@ -51,7 +53,7 @@ module JsonEmitter
 
         first = true
         enum.each { |val|
-          y << ",".freeze unless first
+          y << COMMA unless first
           first = false if first
 
           mapped_val = mapper ? mapper.call(val) : val
@@ -70,7 +72,7 @@ module JsonEmitter
 
         first = true
         hash.each { |key, val|
-          y << ",".freeze unless first
+          y << COMMA unless first
           first = false if first
 
           json_key = MultiJson.dump(key.to_s)

data/lib/json-emitter/version.rb

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

data/lib/json-emitter.rb

@@ -51,11 +51,12 @@ module JsonEmitter
   # @param enum [Enumerable] Something that can be enumerated over, like an Array or Enumerator. Each element should be something that can be rendered as JSON (e.g. a number, string, boolean, Array, or Hash).
   # @param buffer_size [Integer] The buffer size in kb. This is a size *hint*, not a hard limit.
   # @param buffer_unit [Symbol] :bytes | :kb (default) | :mb
+  # @param rack [Hash] optional Rack env for error handling
   # @yield If a block is given, it will be yielded each value in the array. The return value from the block will be converted to JSON instead of the original value.
   # @return [JsonEmitter::BufferedStream]
   #
-  def self.array(enum, buffer_size: 16, buffer_unit: :kb, &mapper)
-    emitter = Emitter.new.array(enum, &mapper)
+  def self.array(enum, buffer_size: 16, buffer_unit: :kb, rack: nil, &mapper)
+    emitter = Emitter.new(rack_env: rack).array(enum, &mapper)
     BufferedStream.new(emitter, buffer_size, unit: buffer_unit)
   end
 
@@ -95,10 +96,11 @@ module JsonEmitter
   # @param hash [Hash] Keys should be Strings or Symbols and values should be any JSON-compatible value like a number, string, boolean, Array, or Hash.
   # @param buffer_size [Integer] The buffer size in kb. This is a size *hint*, not a hard limit.
   # @param buffer_unit [Symbol] :bytes | :kb (default) | :mb
+  # @param rack [Hash] optional Rack env for error handling
   # @return [JsonEmitter::BufferedStream]
   #
-  def self.object(hash, buffer_size: 16, buffer_unit: :kb)
-    emitter = Emitter.new.object(hash)
+  def self.object(hash, buffer_size: 16, buffer_unit: :kb, rack: nil)
+    emitter = Emitter.new(rack_env: rack).object(hash)
     BufferedStream.new(emitter, buffer_size, unit: buffer_unit)
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: json-emitter
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 1.0.0
 platform: ruby
 authors:
 - Jordan Hollinger
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-01-31 00:00:00.000000000 Z
+date: 2022-07-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_json
@@ -56,8 +56,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 3.0.3.1
 signing_key: 
 specification_version: 4
 summary: Efficiently generate tons of JSON