{"id":13878251,"url":"https://github.com/thisismydesign/json-streamer","last_synced_at":"2025-04-13T11:04:06.421Z","repository":{"id":56879610,"uuid":"59911623","full_name":"thisismydesign/json-streamer","owner":"thisismydesign","description":"Ruby gem for getting data from JSON streams based on various criteria (key, nesting level, etc)","archived":false,"fork":false,"pushed_at":"2020-05-14T12:51:30.000Z","size":118,"stargazers_count":58,"open_issues_count":2,"forks_count":9,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-17T12:08:56.300Z","etag":null,"topics":["json","ruby","ruby-gem","streamer"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thisismydesign.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"thisismydesign"}},"created_at":"2016-05-28T19:43:31.000Z","updated_at":"2025-01-07T20:52:48.000Z","dependencies_parsed_at":"2022-08-20T11:40:42.702Z","dependency_job_id":null,"html_url":"https://github.com/thisismydesign/json-streamer","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thisismydesign%2Fjson-streamer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thisismydesign%2Fjson-streamer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thisismydesign%2Fjson-streamer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thisismydesign%2Fjson-streamer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thisismydesign","download_url":"https://codeload.github.com/thisismydesign/json-streamer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245767357,"owners_count":20668826,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json","ruby","ruby-gem","streamer"],"created_at":"2024-08-06T08:01:44.021Z","updated_at":"2025-03-27T02:12:16.210Z","avatar_url":"https://github.com/thisismydesign.png","language":"Ruby","readme":"# Json::Streamer\n\n#### Ruby gem for getting data from JSON streams based on various criteria (key, nesting level, etc).\n\nStatus and support\n\n- \u0026#x2714; stable\n- \u0026#x2714; supported\n- \u0026#x2716; no ongoing development\n\n\u003c!--- Version informartion --\u003e\n*You are viewing the README of version [v2.1.0](https://github.com/thisismydesign/json-streamer/releases/tag/v2.1.0). You can find other releases [here](https://github.com/thisismydesign/json-streamer/releases).*\n\u003c!--- Version informartion end --\u003e\n\n| Branch | Status |\n| ------ | ------ |\n| Release | [![Coverage Status](https://coveralls.io/repos/github/thisismydesign/json-streamer/badge.svg?branch=release)](https://coveralls.io/github/thisismydesign/json-streamer?branch=release)   [![Gem Version](https://badge.fury.io/rb/json-streamer.svg)](https://badge.fury.io/rb/json-streamer)   [![Total Downloads](http://ruby-gem-downloads-badge.herokuapp.com/json-streamer?type=total)](https://rubygems.org/gems/json-streamer) |\n| Development | [![Build Status](https://github.com/thisismydesign/json-streamer/workflows/Test/badge.svg)](https://github.com/thisismydesign/json-streamer/actions)   [![Coverage Status](https://coveralls.io/repos/github/thisismydesign/json-streamer/badge.svg?branch=master)](https://coveralls.io/github/thisismydesign/json-streamer?branch=master) |\n\n####  If you've tried JSON streaming with other Ruby libraries before (e.g. [JSON::Stream](https://github.com/dgraham/json-stream), [Yajl::FFI](https://github.com/dgraham/yajl-ffi))\n\nThis gem will basically spare you the need to define your own callbacks (i.e. implement an actual JSON parser using `start_object`, `end_object`, `key`, `value`, etc.).\n\n#### If you're new to this\n\nStreaming is useful for\n- big files that do not fit in the memory (or you'd rather avoid the risk)\n- files read in chunks (e.g. arriving over network)\n- cases where you expect some issue with the file (e.g. losing connection to source, invalid data at some point) but would like to get as much data as possible anyway\n\nThis gem is aimed at making streaming as easy and convenient as possible.\n\n#### Performance\n\nHighly depends on the event generator. Out of the box the gem uses [JSON::Stream](https://github.com/dgraham/json-stream). It was chosen because it's a pure Ruby parser with no runtime dependencies. You can use any custom event generator, such as [Yajl::FFI](https://github.com/dgraham/yajl-ffi) which is dependent on the native YAJL library and is [~10 times faster](https://github.com/dgraham/yajl-ffi#performance). See the [Custom event generators](#custom-event-generators) chapter.\n\nI did not measure the performance of my implementation on top of these libraries.\n\n#### Dependencies\n\nThe gem's single runtime dependency is [JSON::Stream](https://github.com/dgraham/json-stream). It is only loaded if the default event generator is used.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'json-streamer'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install json-streamer\n\n## Usage\n\n```ruby\nrequire 'json/streamer'\n```\n\n#### Passing IO upfront\n\nSince [v1.2.0](https://github.com/thisismydesign/json-streamer/releases/tag/v1.2.0)\n\n```ruby\nfile_stream = File.open('data.json', 'r')\nchunk_size = 500 # defaults to 1000\n\nstreamer = Json::Streamer.parser(file_io: file_stream, chunk_size: chunk_size)\n```\n\n#### Get objects based on nesting level\n\n```ruby\n# Level zero yields the full JSON, first level yields data within the JSON 1-by-1, etc.\nstreamer.get(nesting_level:1) do |object|\n    p object\nend\n```\n\nInput:\n```json\n{\n    \"object1\": \"first_level_value\",\n    \"object2\": {}\n}\n```\n\nOutput:\n```ruby\n\"first_level_value\"\n{}\n```\n\n#### Get data based on key\n\n```ruby\nstreamer.get(key:'desired_key') do |object|\n    p object\nend\n```\n\nInput:\n```json\n{\n    \"obj1\" : {\n        \"desired_key\" : \"value1\"\n    },\n    \"desired_key\" : \"value2\",\n    \"obj2\" : {\n        \"desired_key\" : {\n            \"desired_key\" : \"value3\"\n        }\n    }\n}\n```\n\nOutput:\n```ruby\n\"value1\"\n\"value2\"\n\"value3\"\n{\"desired_key\" =\u003e \"value3\"}\n```\n\n#### Skip values\n\n```ruby\nstreamer.get(nesting_level:1, yield_values:false) do |object|\n    p object\nend\n```\n\nInput:\n```json\n{\n    \"obj1\" : {},\n    \"key\" : \"value\"\n}\n```\n\nOutput:\n```json\n{}\n```\n\n#### Symbolize keys\n\nSince [v1.3.0](https://github.com/thisismydesign/json-streamer/releases/tag/v1.3.0)\n\n```ruby\nstreamer.get(nesting_level:0, symbolize_keys: true) do |object|\n    p object\nend\n```\n\nInput:\n```json\n{\n    \"obj1\" : {\"key\" : \"value\"}\n}\n```\n\nOutput:\n```ruby\n{:obj1=\u003e{:key=\u003e\"value\"}}\n```\n\n#### Passing IO later (EventMachine-style)\n\n```ruby\n# Get a JsonStreamer object that provides access to the parser\n# but does not start processing immediately\nstreamer = Json::Streamer.parser\n\nstreamer.get(nesting_level:1) do |object|\n    p object\nend\n```\n\nThen later in your EventMachine handler:\n\n```ruby\ndef receive_data(data)\n    streamer \u003c\u003c data\nend\n```\n\n#### Custom event generators\n\nSince [v2.1.0](https://github.com/thisismydesign/json-streamer/releases/tag/v2.1.0)\n\n```ruby\nrequire \"yajl/ffi\"\n\nJson::Streamer.parser(event_generator: Yajl::FFI::Parser.new)\n```\n\nAny parser can be used that provides the right events. The gem is tested with [Yajl::FFI](https://github.com/dgraham/yajl-ffi) and [JSON::Stream](https://github.com/dgraham/json-stream).\n\n#### Custom yield conditions\n\nSince [v2.0.0](https://github.com/thisismydesign/json-streamer/releases/tag/v2.0.0)\n\nCustom conditions provide ultimate control over what to yield.\n\nThe Conditions API exposes 3 callbacks:\n- `yield_value`\n- `yield_array`\n- `yield_object`\n\nEach of them may be redefined. They are called once the corresponding data (value, array or object) is available. They should return whether the data should be yielded for the outside. They receive the data and the `aggregator` as parameters.\n\nThe `aggregator` exposes data about the current state of the partly parsed JSON such as:\n- `level` - current level\n- `key` - current key\n- `value` - current value\n- `key_for_level(level)` - key for custom level\n- `value_for_level(level)` - value for custom level\n- `get` - the raw data (in a custom format)\n\nExample usage (inspired by [this issue](https://github.com/thisismydesign/json-streamer/issues/7#issuecomment-330232484)):\n\n```ruby\nconditions = Json::Streamer::Conditions.new\nconditions.yield_value = -\u003e(aggregator:, value:) { false }\nconditions.yield_array = -\u003e(aggregator:, array:) { false }\nconditions.yield_object = lambda do |aggregator:, object:|\n    aggregator.level.eql?(2) \u0026\u0026 aggregator.key_for_level(1).eql?('items1')\nend\n\nstreamer.get_with_conditions(conditions) do |object|\n    p object\nend\n```\n\nInput:\n\n```ruby\n{\n  \"other\": \"stuff\",\n  \"items1\": [\n    {\n      \"key1\": \"value\"\n    },\n    {\n      \"key2\": \"value\"\n    }\n  ],\n  \"items2\": [\n    {\n      \"key3\": \"value\"\n    },\n    {\n      \"key4\": \"value\"\n    }\n  ]\n}\n```\n\nOutput:\n\n```ruby\n{\"key1\"=\u003e\"value\"}\n{\"key2\"=\u003e\"value\"}\n```\n\n#### Get an Enumerable when not passing a block\n\nSince [v2.1.0](https://github.com/thisismydesign/json-streamer/releases/tag/v2.1.0)\n\nWhen _not_ passed a block both `get` and `get_with_conditions` return an enumerator of the requested objects. When passed a block they return an empty enumerator. This means that **when _not_ passed a block the requested objects will accumulate in memory**.\n\nWithout block\n\n```ruby\nobjects = streamer.get(nesting_level:1)\np objects\n```\n\nInput:\n```json\n{\n    \"object1\": \"first_level_value\",\n    \"object2\": {}\n}\n```\n\nOutput:\n```ruby\n[\"first_level_value\", {}]\n```\n\nWith block\n\n```ruby\nunyielded_objects = streamer.get(nesting_level:1) { |object| do_something(object) }\np unyielded_objects\n```\n\nInput:\n```json\n{\n    \"object1\": \"first_level_value\",\n    \"object2\": {}\n}\n```\n\nOutput:\n```ruby\n[]\n```\n\n#### Other usage information\n\nCheck the unit tests for more examples ([spec/streamer_spec.rb](spec/json/streamer/json_streamer_spec.rb)).\n\nOne `streamer` object handles one set of conditions. For multiple conditions create multiple streamers. For more details see [this discussion](https://github.com/thisismydesign/json-streamer/issues/9).\n\n#### Deprecated API\n\nPre [v1.2.0](https://github.com/thisismydesign/json-streamer/releases/tag/v1.2.0)\n\nThis functionality is deprecated but kept for compatibility reasons.\n\n```ruby\n# Same as Json::Streamer.parser\nstreamer = Json::Streamer::JsonStreamer.new\n```\n\n```ruby\n# Same as streamer \u003c\u003c data\nstreamer.parser \u003c\u003c data\n```\n\n## Contribution and feedback\n\nThis project is built around known use-cases. If you have one that isn't covered don't hesitate to open an issue and start a discussion.\n\nBug reports and pull requests are welcome on GitHub at https://github.com/thisismydesign/json-streamer. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\n## Conventions\n\nThis project follows [C-Hive guides](https://github.com/c-hive/guides) for code style, way of working and other development concerns.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n","funding_links":["https://github.com/sponsors/thisismydesign"],"categories":["Ruby","Data Processing and ETL"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthisismydesign%2Fjson-streamer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthisismydesign%2Fjson-streamer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthisismydesign%2Fjson-streamer/lists"}