Class: Familia::JsonStringKey

Inherits:
DataType
  • Object
show all
Defined in:
lib/familia/data_type/types/json_stringkey.rb

Overview

Note:

This class intentionally does NOT include increment/decrement or other raw string operations that are incompatible with JSON serialization.

Note:

Performance: Each call to value, to_s, to_i, to_f makes a Redis roundtrip. If you need the value multiple times and don't expect it to change, store it in a local variable:

Inefficient (3 Redis calls):

puts json_str.to_s puts json_str.to_i puts json_str.to_f

Efficient (1 Redis call):

val = json_str.value puts val.to_s puts val.to_i puts val.to_f

JsonStringKey - A string DataType that uses JSON serialization for type preservation.

Unlike StringKey which uses raw string serialization (to support Redis operations like INCR/DECR/APPEND), JsonStringKey uses the base DataType's JSON serialization to preserve Ruby types across the Redis storage boundary.

Examples:

Basic usage

class MyIndex < Familia::Horreum
  class_json_string :last_synced_at, default: 0.0
end

MyIndex.last_synced_at = Time.now.to_f  # Stored as JSON number
MyIndex.last_synced_at  #=> 1704067200.123 (Float preserved)

Type preservation

json_str.value = 42        # Stored in Redis as: 42 (JSON number)
json_str.value = true      # Stored in Redis as: true (JSON boolean)
json_str.value = [1, 2, 3] # Stored in Redis as: [1,2,3] (JSON array)

Instance Attribute Summary collapse

Attributes included from Settings

#current_key_version, #default_expiration, #delim, #encryption_keys, #encryption_personalization, #logical_database, #prefix, #schema_path, #schema_validator, #schemas, #suffix, #transaction_mode

Instance Method Summary collapse

Methods included from Features::Autoloader

autoload_files, included, normalize_to_config_name

Methods included from DataType::Serialization

#deserialize_value, #deserialize_values, #deserialize_values_with_nil, #serialize_value

Methods included from DataType::DatabaseCommands

#current_expiration, #delete!, #echo, #exists?, #expire, #expireat, #move, #persist, #rename, #renamenx, #type

Methods included from DataType::Connection

#dbclient, #dbkey, #direct_access, #uri

Methods included from Connection::Behavior

#connect, #create_dbclient, #multi, #normalize_uri, #pipeline, #pipelined, #transaction, #uri=, #url, #url=

Methods included from Settings

#configure, #default_suffix, #pipelined_mode, #pipelined_mode=

Methods included from Base

add_feature, #as_json, #expired?, #expires?, find_feature, #generate_id, #to_json, #ttl, #update_expiration, #uuid

Constructor Details

This class inherits a constructor from Familia::DataType

Instance Attribute Details

#features_enabled ⇒ Object (readonly) Originally defined in module Features

Returns the value of attribute features_enabled.

#logical_database(val = nil) ⇒ Object Originally defined in module DataType::ClassMethods

#parent ⇒ Object Originally defined in module DataType::ClassMethods

Returns the value of attribute parent.

#prefix ⇒ Object Originally defined in module DataType::ClassMethods

Returns the value of attribute prefix.

#suffix ⇒ Object Originally defined in module DataType::ClassMethods

Returns the value of attribute suffix.

#uri(val = nil) ⇒ Object Originally defined in module DataType::ClassMethods

Returns the value of attribute uri.

Instance Method Details

#char_count ⇒ Integer Also known as: size, length

Returns the number of characters in the string representation of the value.

Returns:

  • (Integer) —

    number of characters



51
52
53
 
# File 'lib/familia/data_type/types/json_stringkey.rb', line 51

def char_count
  to_s&.size || 0
end

#del ⇒ Boolean

Deletes the key from the database.

Returns:

  • (Boolean) —

    true if the key was deleted, false if it didn't exist



105
106
107
108
 
# File 'lib/familia/data_type/types/json_stringkey.rb', line 105

def del
  ret = dbclient.del dbkey
  ret.positive?
end

#empty? ⇒ Boolean

Checks if the value is nil (key does not exist or has no value).

Returns:

  • (Boolean) —

    true if the value is nil



114
115
116
 
# File 'lib/familia/data_type/types/json_stringkey.rb', line 114

def empty?
  value.nil?
end

#init ⇒ Object

Initialization hook (required by DataType contract)



45
 
# File 'lib/familia/data_type/types/json_stringkey.rb', line 45

def init; end

#setnx(val) ⇒ Boolean

Sets the value only if the key does not already exist.

Parameters:

  • val (Object) —

    the value to store

Returns:

  • (Boolean) —

    true if the key was set, false if it already existed



95
96
97
98
99
 
# File 'lib/familia/data_type/types/json_stringkey.rb', line 95

def setnx(val)
  ret = dbclient.setnx(dbkey, serialize_value(val))
  update_expiration if ret
  ret
end

#to_f ⇒ Float?

Returns the float representation of the deserialized value.

Returns:

  • (Float, nil) —

    the deserialized value converted to float, or nil



144
145
146
147
148
149
 
# File 'lib/familia/data_type/types/json_stringkey.rb', line 144

def to_f
  val = deserialize_value(dbclient.get(dbkey))
  return nil if val.nil?

  val.to_f
end

#to_i ⇒ Integer?

Returns the integer representation of the deserialized value.

Returns:

  • (Integer, nil) —

    the deserialized value converted to integer, or nil



133
134
135
136
137
138
 
# File 'lib/familia/data_type/types/json_stringkey.rb', line 133

def to_i
  val = deserialize_value(dbclient.get(dbkey))
  return nil if val.nil?

  val.to_i
end

#to_s ⇒ String?

Returns the string representation of the deserialized value.

Returns:

  • (String, nil) —

    the deserialized value converted to string, or nil



122
123
124
125
126
127
 
# File 'lib/familia/data_type/types/json_stringkey.rb', line 122

def to_s
  val = deserialize_value(dbclient.get(dbkey))
  return nil if val.nil?

  val.to_s
end

#value ⇒ Object Also known as: content, get

Returns the current value stored at the key.

If a default option was provided during initialization, the default is set via SETNX (set if not exists) before retrieval.

Returns:

  • (Object) —

    the deserialized value, or the default if not set



64
65
66
67
68
69
70
71
 
# File 'lib/familia/data_type/types/json_stringkey.rb', line 64

def value
  echo :value, Familia.pretty_stack(limit: 1) if Familia.debug
  if @opts.key?(:default)
    was_set = dbclient.setnx(dbkey, serialize_value(@opts[:default]))
    update_expiration if was_set
  end
  deserialize_value dbclient.get(dbkey)
end

#value=(val) ⇒ String Also known as: replace, set

Sets the value at the key.

The value is JSON-serialized before storage, preserving its Ruby type.

Parameters:

  • val (Object) —

    the value to store

Returns:

  • (String) —

    "OK" on success



82
83
84
85
86
 
# File 'lib/familia/data_type/types/json_stringkey.rb', line 82

def value=(val)
  ret = dbclient.set(dbkey, serialize_value(val))
  update_expiration
  ret
end