Module: Sqlx::Json

Defined in:

runtime/sqlx/json.rbs,
runtime/sqlx/json.rb

Class Method Summary

• .decode(text) ⇒ Object

  the logical value a column holds: nil is SQL NULL and a String is the serialized text.

• .encodable?(value) ⇒ Boolean

  whether JSON can represent this value on its own terms: nil, true/false, a String, a finite number, or a nested Array/Hash of those (Hash keys may be Symbols; they read back as Strings).

• .encode(value) ⇒ String?

  the logical value a column holds: nil is SQL NULL and everything else is JSON text, so decode reads it back equal.

Class Method Details

.decode(text) ⇒ Object

the logical value a column holds: nil is SQL NULL and a String is the serialized text. Anything else is a caller bug — the logical value is already in hand, so there is nothing to decode, and guessing would hide it. Malformed text raises through the same door (see the file header for why the parser's own class stays inside).

Examples:

Sqlx::Json.decode("{\"a\":1}")  # => { "a" => 1 }
Sqlx::Json.decode(nil)          # => nil

Parameters:

• text (Object) —

  the stored column value; nil for SQL NULL

Returns:

• (Object) —

  the decoded Hash/Array/scalar, or nil for SQL NULL

Raises:

• (ArgumentError) —

  the value is not a String, or is a String the parser cannot decode

# File 'runtime/sqlx/json.rb', line 88

def self.decode: (untyped text) -> untyped

.encodable?(value) ⇒ Boolean

whether JSON can represent this value on its own terms: nil, true/false, a String, a finite number, or a nested Array/Hash of those (Hash keys may be Symbols; they read back as Strings). This is the predicate encode enforces, exposed because it is the precondition a caller holding untrusted input asks BEFORE putting the value in a column — the label?-beside-label shape.

Examples:

Sqlx::Json.encodable?({ "a" => [ 1, true ] })  # => true
Sqlx::Json.encodable?(Time.now)               # => false

Parameters:

• value (Object) —

  the value headed for the column

Returns:

• (Boolean) —

  true when encode accepts it; false for a Time, a non-finite Float, or any object the gem would stringify

# File 'runtime/sqlx/json.rb', line 28

def self.encodable?: (untyped value) -> bool

.encode(value) ⇒ String?

the logical value a column holds: nil is SQL NULL and everything else is JSON text, so decode reads it back equal. A value JSON cannot represent raises instead of being to_sd into the column — a Time never arrives as text by accident. JSON null is not distinguishable from SQL NULL here: a caller that needs the literal writes it directly.

Examples:

Sqlx::Json.encode({ a: 1 })  # => "{\"a\":1}"
Sqlx::Json.encode(nil)       # => nil

Parameters:

• value (Object) —

  the logical value; nil for an absent column

Returns:

• (String?) —

  the serialized text, or nil for SQL NULL

Raises:

• (ArgumentError) —

  the value is not a JSON value (encodable? answers false for it)

# File 'runtime/sqlx/json.rb', line 66

def self.encode: (untyped value) -> String?