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



72
73
74
 
# File 'lib/rhales/utils/json_serializer.rb', line 72

def backend
  @backend
end

.detect_backend! ⇒ Object (private)

Detect and configure JSON backend at load time



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

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



41
42
43
 
# File 'lib/rhales/utils/json_serializer.rb', line 41

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



65
66
67
 
# File 'lib/rhales/utils/json_serializer.rb', line 65

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



53
54
55
 
# File 'lib/rhales/utils/json_serializer.rb', line 53

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)



79
80
81
 
# File 'lib/rhales/utils/json_serializer.rb', line 79

def reset!
  detect_backend!
end