How michalmuskala/jason works
Main Components
• Core Library (lib/): This includes the key modules:
• jason.ex: Acts as the entry point wrapping and coordinating the JSON parsing and generation.
• decoder.ex and encoder.ex: Contain the logic for parsing (decoding) JSON text into Elixir data structures and generating (encoding) JSON strings.
• formatter.ex: Manages pretty-printing and custom-formatting for output.
• fragment.ex: Provides support for injecting already encoded JSON fragments.
• Additional modules (codegen.ex, helpers.ex, ordered_object.ex, sigil.ex) supply supplementary functionalities such as utility functions, custom structures, and possibly compile-time code generation.
• Testing and Quality Assurance:
• test/ directory: Contains unit tests for validating encoding, decoding, formatting, and additional helper functions.
• formatter_test_suite and json_test_suite: These directories hold sample JSON cases (both correct and edge cases) to test the strict compliance with JSON standards.
• Benchmarking:
• bench/ directory: Contains benchmark scripts (encode.exs, decode.exs) and dataset files (e.g., giphy.json, pokedex.json, blockchain.json, etc.), which are used to run performance tests and generate reports.
Relationships and Dependencies
• The central Jason module coordinates the work and delegates to the specific encoder/decoder modules.
• The encoder and decoder modules interface with helper modules to process JSON formatting, error detection, and conformance with RFC 8259 and ECMA 404.
• Formatter is a bridge between encoder output and producing a readable JSON representation when pretty-printing is enabled.
• The fragment module is used within the generator chain to allow the injection of pre-encoded JSON without re-processing it.
• Testing and benchmarks are separate concerns that depend on the core modules but are executed in isolated environments (unit tests and performance runs).
Architectural Patterns and Design Principles
• Separation of Concerns: Each module has a specific purpose (parsing versus formatting versus fragment handling), keeping the code modular and extendable.
• Protocol Implementation: The library leverages Elixir protocols (as indicated in the README for encoding custom data types) to allow extensibility in JSON encoding.
• Test-Driven Approach: With dedicated suites and benchmarks, the design ensures strict conformance to JSON standards as well as high-performance goals.
• Reusability: The core functionality is exposed as a library that can be integrated into other systems (e.g., Ecto, Plug) without modification.