{"id":19210971,"url":"https://github.com/boudra/jaxon","last_synced_at":"2025-05-16T18:06:24.071Z","repository":{"id":49968212,"uuid":"128577089","full_name":"boudra/jaxon","owner":"boudra","description":"Streaming JSON parser for Elixir","archived":false,"fork":false,"pushed_at":"2024-08-20T22:26:16.000Z","size":10475,"stargazers_count":201,"open_issues_count":18,"forks_count":21,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-03T16:14:28.066Z","etag":null,"topics":["elixir","erlang","json","json-events","nif","nif-parser","parser","sax","stream","streaming"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/boudra.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-07T23:30:10.000Z","updated_at":"2025-03-05T16:25:41.000Z","dependencies_parsed_at":"2024-11-09T13:40:11.566Z","dependency_job_id":"74146092-4692-4dfb-a43d-0e7e0a0dc5e1","html_url":"https://github.com/boudra/jaxon","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boudra%2Fjaxon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boudra%2Fjaxon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boudra%2Fjaxon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boudra%2Fjaxon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/boudra","download_url":"https://codeload.github.com/boudra/jaxon/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248597837,"owners_count":21130959,"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":["elixir","erlang","json","json-events","nif","nif-parser","parser","sax","stream","streaming"],"created_at":"2024-11-09T13:40:01.204Z","updated_at":"2025-04-12T16:38:38.454Z","avatar_url":"https://github.com/boudra.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Jaxon :zap: [![Hex.pm](https://img.shields.io/hexpm/v/jaxon.svg)](https://hex.pm/packages/jaxon) [![Build Status](https://travis-ci.org/boudra/jaxon.svg?branch=master)](https://travis-ci.org/boudra/jaxon) [![Inline docs](http://inch-ci.org/github/boudra/jaxon.svg)](http://inch-ci.org/github/boudra/jaxon) [![Coverage Status](https://coveralls.io/repos/github/boudra/jaxon/badge.svg)](https://coveralls.io/github/boudra/jaxon)\n\n**Jaxon** is a [fast JSON parser](#benchmarks) that can [stream](#streaming) any JSON document without holding it all in memory.\n\nJaxon fully conforms to the [RFC 8259](https://tools.ietf.org/html/rfc8259) and [ECMA 404](http://www.ecma-international.org/publications/standards/Ecma-404.htm) standards and is tested against [JSONTestSuite](https://github.com/nst/JSONTestSuite).\n\nRoadmap:\n\n- Make an alternative parser in Elixir, for those who don't want to use NIFs.\n- JSON events to string Encoder.\n\nLinks:\n\n- [Online documentation](https://hexdocs.pm/jaxon/)\n- [Introduction to Jaxon](https://moboudra.com/intro-to-jaxon-json-parser-for-elixir/)\n- [Benchmarks](https://boudra.github.io/jaxon/benchmark_results/decode.html)\n\n---\n\n[Click here if you want to use the 1.x version](https://github.com/boudra/jaxon/tree/fb638f76945236822e8e015ee4b4d79b8255b71e)\n\n## Installation\n\n```elixir\ndef deps do\n  [\n    {:jaxon, \"~\u003e 2.0\"}\n  ]\nend\n```\n\n## Simple decoding\n\nDecode a binary:\n\n```elixir\niex\u003e Jaxon.decode(~s({\"jaxon\":\"rocks\",\"array\":[1,2]}))\n{:ok, %{\"array\" =\u003e [1, 2], \"jaxon\" =\u003e \"rocks\"}}\n\niex\u003e Jaxon.decode!(~s({\"jaxon\":\"rocks\",\"array\":[1,2]}))\n%{\"array\" =\u003e [1, 2], \"jaxon\" =\u003e \"rocks\"}\n```\n\n## Streaming\n\nJaxon can also query streams of JSON documents:\n\nQuery a binary JSON stream (notice how some items are incomplete JSON documents):\n\n```elixir\niex\u003e stream = [~s({\"jaxon\":\"rocks\",\"array\":[1,2]}),~s({\"jaxon\":\"rocks\"), ~s(,\"array\":[3,4]})]\niex\u003e stream |\u003e Jaxon.Stream.from_enumerable() |\u003e Jaxon.Stream.query([:root, \"array\", :all]) |\u003e Enum.to_list()\n[1, 2, 3, 4]\n```\n\nQuery a binary JSON stream using JSON path expressions:\n\n```elixir\niex\u003e stream = [~s({\"jaxon\":\"rocks\",\"array\":[1,2]})]\niex\u003e stream |\u003e Jaxon.Stream.from_enumerable() |\u003e Jaxon.Stream.query(Jaxon.Path.parse!(\"$.array[*]\")) |\u003e Enum.to_list()\n[1, 2]\n```\n\nQuery a large file without holding the whole file in memory:\n\n```elixir\n\"large_file.json\"\n|\u003e File.stream!()\n|\u003e Jaxon.Stream.from_enumerable()\n|\u003e Jaxon.Stream.query([:root, \"users\", :all, \"metadata\"])\n|\u003e Stream.map(\u0026(\u00261[\"username\"],\",\",\u00261[\"email\"],\"\\n\"))\n|\u003e Stream.into(File.stream!(\"large_file.csv\"))\n|\u003e Stream.run()\n```\n\n# JSON Path\n\nYou can either write your own like so:\n\n`[:root, \"users\", 0, \"name\"]`\n\nOr use the parser:\n\n```elixir\niex\u003e Jaxon.Path.parse!(\"$.array[*]\")\n[:root, \"array\", :all]\n```\n\n```elixir\niex\u003e Jaxon.Path.parse!(~s($[\"key with spaces\"][0]))\n[:root, \"key with spaces\", 0]\n```\n\n\n## How does Jaxon work?\n\nJaxon first parses the JSON string into a list of events/tokens:\n\n```elixir\niex(1)\u003e Jaxon.Parsers.NifParser.parse(~s({\"key\":true}), [])\n{:ok, [:start_object, {:string, \"key\"}, :colon, {:boolean, true}, :end_object]}\n```\n\nThese are all the available events:\n\n```elixir\n:start_object\n:end_object\n:start_array\n:end_array\n{:string, binary}\n{:integer, integer}\n{:decimal, float}\n{:boolean, boolean}\nnil\n{:incomplete, binary}\n{:error, binary}\n:colon\n:comma\n```\n\nWhich means that it can also parse a list of JSON tokens, even if the string is not a valid JSON representation:\n\n```elixir\niex\u003e Jaxon.Parser.parse(~s(\"this is a string\" \"another string\"))\n[{:string, \"this is a string\"}, {:string, \"another string\"}]\n```\n\nThis makes it very flexible when decoding files and lets us use different implementations for parsers, at the moment the default parser is written in C as a NIF. It can be changed in the config like this:\n\n```elixir\nconfig :jaxon, :parser, Jaxon.Parsers.NifParser # only NifParser is supported at the moment\n```\n\nThen, the decoder's job is to take a list of events and aggregate it into a Elixir term:\n\n```elixir\niex(4)\u003e Jaxon.Decoders.Value.decode([:start_object, {:string, \"key\"}, :colon, {:boolean, true}\n, :end_object])\n{:ok, %{\"key\" =\u003e true}}\n```\n\n## About the NIF parser\n\nAll the parser does is take a binary and return a list of JSON events, the NIF respects the Erlang scheduler and tries to run for a maximum of one millisecond, yielding to the VM for another call if it runs over the limit.\n\n## Benchmarks\n\nJaxon (using the NIF parser) performance is similar and often faster than **jiffy** and **jason**.\n\nTo run the benchmarks, execute:\n\n```shell\nmix bench.decode\n```\n\nSee the decode benchmarks here: [benchmarks](https://boudra.github.io/jaxon/benchmark_results/decode.html)\n\n## License\n\n```\nCopyright © 2018 Mohamed Boudra \u003cmohamed@numidian.io\u003e\n\nThis project is under the Apache 2.0 license. See the LICENSE file for more details.\n```\n\nDeveloped at [Konbert](https://konbert.com) for big data JSON parsing.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboudra%2Fjaxon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fboudra%2Fjaxon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboudra%2Fjaxon/lists"}