Module: Rhales::JSONSerializer

Defined in:
lib/rhales/utils/json_serializer.rb

Overview

Centralized JSON serialization with optional Oj support

This module provides a unified interface for JSON operations with automatic Oj optimization when available. Oj is 10-20x faster than stdlib JSON for parsing and 5-10x faster for generation.

The serializer backend is determined once at load time for optimal performance. If you want to use Oj, require it before requiring Rhales:

Examples:

Ensuring Oj is used

require 'oj'
require 'rhales'

Basic usage

Rhales::JSONSerializer.dump({ user: 'Alice' })
# => "{\"user\":\"Alice\"}"

Rhales::JSONSerializer.parse('{"user":"Alice"}')
# => {"user"=>"Alice"}

Pretty printing

Rhales::JSONSerializer.pretty_dump({ user: 'Alice', count: 42 })
# => "{\n  \"user\": \"Alice\",\n  \"count\": 42\n}"

Check backend

Rhales::JSONSerializer.backend
# => :oj (if available) or :json (stdlib)

Class Method Summary collapse

Class Method Details

.backend ⇒ Symbol

Returns the active JSON backend

Returns:

  • (Symbol) —

    :oj or :json



74
75
76
 
# File 'lib/rhales/utils/json_serializer.rb', line 74

def backend
  @backend
end

.detect_backend! ⇒ Object (private)

Detect and configure JSON backend at load time



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/rhales/utils/json_serializer.rb', line 88

def detect_backend!
  oj_available = begin
    require 'oj'
    true
  rescue LoadError
    false
  end

  if oj_available
    @backend = :oj
    @json_dumper = ->(obj) { Oj.dump(obj, mode: :strict) }
    @json_pretty_dumper = ->(obj) { Oj.dump(obj, mode: :strict, indent: 2) }
    @json_loader = ->(json_string) { Oj.load(json_string, mode: :strict, symbol_keys: false) }
  else
    require 'json'
    @backend = :json
    @json_dumper = ->(obj) { JSON.generate(obj) }
    @json_pretty_dumper = ->(obj) { JSON.pretty_generate(obj) }
    @json_loader = ->(json_string) { JSON.parse(json_string) }
  end
end

.dump(obj) ⇒ String

Serialize Ruby object to JSON string

Uses the serializer backend determined at load time (Oj or stdlib JSON).

Parameters:

  • obj (Object) —

    Ruby object to serialize

Returns:

  • (String) —

    JSON string (compact format)

Raises:

  • (TypeError) —

    if object contains non-serializable types



43
44
45
 
# File 'lib/rhales/utils/json_serializer.rb', line 43

def dump(obj)
  @json_dumper.call(obj)
end

.parse(json_string) ⇒ Object

Parse JSON string to Ruby object

Uses the parser backend determined at load time (Oj or stdlib JSON). Always returns hashes with string keys (not symbols) for consistency.

Parameters:

  • json_string (String) —

    JSON string to parse

Returns:

  • (Object) —

    parsed Ruby object (Hash with string keys)

Raises:

  • (JSON::ParserError, Oj::ParseError) —

    if JSON is malformed



67
68
69
 
# File 'lib/rhales/utils/json_serializer.rb', line 67

def parse(json_string)
  @json_loader.call(json_string)
end

.pretty_dump(obj) ⇒ String

Serialize Ruby object to pretty-printed JSON string

Uses the serializer backend determined at load time (Oj or stdlib JSON). Output is formatted with indentation for readability.

Parameters:

  • obj (Object) —

    Ruby object to serialize

Returns:

  • (String) —

    Pretty-printed JSON string with 2-space indentation

Raises:

  • (TypeError) —

    if object contains non-serializable types



55
56
57
 
# File 'lib/rhales/utils/json_serializer.rb', line 55

def pretty_dump(obj)
  @json_pretty_dumper.call(obj)
end

.reset! ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Reset backend detection (useful for testing)



81
82
83
 
# File 'lib/rhales/utils/json_serializer.rb', line 81

def reset!
  detect_backend!
end