Module: Familia::Horreum::ManagementMethods

Includes:
RelatedFieldsManagement
Defined in:
lib/familia/horreum/management.rb

Overview

ManagementMethods - Class-level methods for Horreum model management

This module is extended into classes that include Familia::Horreum, providing class methods for database operations and object management (e.g., Customer.create, Customer.find_by_id)

Key features:

  • Includes RelatedFieldsManagement for DataType field handling
  • Provides utility methods for working with Database objects

Instance Method Summary collapse

Methods included from RelatedFieldsManagement

#attach_class_related_field, #attach_instance_related_field

Instance Method Details

#all(suffix = nil) ⇒ Object 



290
291
292
293
294
 
# File 'lib/familia/horreum/management.rb', line 290

def all(suffix = nil)
  suffix ||= self.suffix
  # objects that could not be parsed will be nil
  keys(suffix).filter_map { |k| find_by_key(k) }
end

#any?(filter = '*') ⇒ Boolean

Returns:

  • (Boolean) 


296
297
298
 
# File 'lib/familia/horreum/management.rb', line 296

def any?(filter = '*')
  matching_keys_count(filter).positive?
end

#config_name ⇒ String

Converts the class name into a string that can be used to look up configuration values. This is particularly useful when mapping familia models with specific database numbers in the configuration.

Familia::Horreum::DefinitionMethods#config_name

Examples:

V2::Session.config_name => 'session'

Returns:

  • (String) —

    The underscored class name as a string



84
85
86
87
88
 
# File 'lib/familia/horreum/management.rb', line 84

def config_name
  return nil if name.nil?

  name.demodularize.snake_case
end

#create ⇒ Object

Note:

The behavior of this method depends on the implementation of #new,

exists?, and #save in the class and its superclasses.

Creates and persists a new instance of the class.

This method serves as a factory method for creating and persisting new instances of the class. It combines object instantiation, existence checking, and persistence in a single operation.

The method is flexible in accepting both positional and keyword arguments:

  • Positional arguments (*args) are passed directly to the constructor.
  • Keyword arguments (**kwargs) are passed as a hash to the constructor.

After instantiation, the method checks if an object with the same identifier already exists. If it does, a Familia::Problem exception is raised to prevent overwriting existing data.

Finally, the method saves the new instance returns it.

Examples:

Creating an object with keyword arguments

User.create(name: "John", age: 30)

Creating an object with positional and keyword arguments (not recommended)

Product.create("SKU123", name: "Widget", price: 9.99)

Parameters:

  • args (Array) —

    Variable number of positional arguments to be passed to the constructor.

  • kwargs (Hash) —

    Keyword arguments to be passed to the constructor.

Returns:

  • (Object) —

    The newly created and persisted instance.

Raises:

  • (Familia::Problem) —

    If an instance with the same identifier already exists.

See Also:



56
57
58
59
60
 
# File 'lib/familia/horreum/management.rb', line 56

def create(*, **)
  fobj = new(*, **)
  fobj.save_if_not_exists
  fobj
end

#dbkey(identifier, suffix = self.suffix) ⇒ Object

+identifier+ can be a value or an Array of values used to create the index. We don't enforce a default suffix; that's left up to the instance. The suffix is used to differentiate between different types of objects.

+suffix+ If a nil value is explicitly passed in, it won't appear in the redis key that's returned. If no suffix is passed in, the class' suffix is used as the default (via the class method self.suffix). It's an important distinction b/c passing in an explicitly nil is how DataType objects at the class level are created without the global default 'object' suffix. See DataType#dbkey "parent_class?" for more details.



281
282
283
284
285
286
287
288
 
# File 'lib/familia/horreum/management.rb', line 281

def dbkey(identifier, suffix = self.suffix)
  if identifier.to_s.empty?
    raise NoIdentifier, "#{self} requires non-empty identifier, got: #{identifier.inspect}"
  end

  identifier &&= identifier.to_s
  Familia.dbkey(prefix, identifier, suffix)
end

#destroy!(identifier, suffix = nil) ⇒ Boolean

Destroys an object in Database with the given identifier.

This method is part of Familia's high-level object lifecycle management. While delete! operates directly on dbkeys, destroy! operates at the object level and is used for ORM-style operations. Use destroy! when removing complete objects from the system, and delete! when working directly with dbkeys.

Examples:

User.destroy!(123)  # Removes user:123:object from Valkey/Redis

Parameters:

  • identifier (String, Integer) —

    The unique identifier for the object to destroy.

  • suffix (Symbol, nil) (defaults to: nil) —

    The suffix to use in the dbkey (default: class suffix).

Returns:

  • (Boolean) —

    true if the object was successfully destroyed, false otherwise.



224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
 
# File 'lib/familia/horreum/management.rb', line 224

def destroy!(identifier, suffix = nil)
  suffix ||= self.suffix
  return MultiResult.new(false, []) if identifier.to_s.empty?

  objkey = dbkey identifier, suffix

  # Execute all deletion operations within a transaction
  transaction do |conn|
    # Clean up related fields first to avoid orphaned keys
    if relations?
      Familia.trace :DESTROY_RELATIONS!, nil, "#{self} has relations: #{related_fields.keys}" if Familia.debug?

      # Create a temporary instance to access related fields.
      # Pass identifier in constructor so init() sees it and can set dependent fields.
      identifier_field_name = self.identifier_field
      temp_instance = identifier_field_name ? new(identifier_field_name => identifier.to_s) : new

      related_fields.each do |name, _definition|
        obj = temp_instance.send(name)
        Familia.trace :DESTROY_RELATION!, name, "Deleting related field #{name} (#{obj.dbkey})" if Familia.debug?
        conn.del(obj.dbkey)
      end
    end

    # Delete the main object key
    ret = conn.del(objkey)
    Familia.trace :DESTROY!, nil, "#{objkey} #{ret.inspect}" if Familia.debug?
  end
end

#exists?(identifier, suffix = nil) ⇒ Boolean

Checks if an object with the given identifier exists in the database.

This method constructs the full dbkey using the provided identifier and suffix, then checks if the key exists in the database.

Examples:

User.exists?(123)  # Returns true if user:123:object exists in Valkey/Redis

Parameters:

  • identifier (String, Integer) —

    The unique identifier for the object.

  • suffix (Symbol, nil) (defaults to: nil) —

    The suffix to use in the dbkey (default: class suffix).

Returns:

  • (Boolean) —

    true if the object exists, false otherwise.

Raises:



197
198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/familia/horreum/management.rb', line 197

def exists?(identifier, suffix = nil)
  raise NoIdentifier, 'Empty identifier' if identifier.to_s.empty?

  suffix ||= self.suffix

  objkey = dbkey identifier, suffix

  ret = dbclient.exists objkey
  Familia.trace :EXISTS, nil, "#{objkey} #{ret.inspect}" if Familia.debug?

  ret.positive? # differs from Valkey API but I think it's okay bc `exists?` is a predicate method.
end

#familia_name ⇒ Object

Familia::Horreum::DefinitionMethods#familia_name

Examples:

V2::Session.config_name => 'Session'



94
95
96
97
98
 
# File 'lib/familia/horreum/management.rb', line 94

def familia_name
  return nil if name.nil?

  name.demodularize
end

#find_by_id(identifier, suffix = nil) ⇒ Object? Also known as: find, load, from_identifier

Retrieves and instantiates an object from Database using its identifier.

This method constructs the full dbkey using the provided identifier and suffix, then delegates to find_by_key for the actual retrieval and instantiation.

It's a higher-level method that abstracts away the key construction, making it easier to retrieve objects when you only have their identifier.

Examples:

User.find_by_id(123)  # Equivalent to User.find_by_key("user:123:object")

Parameters:

  • identifier (String, Integer) —

    The unique identifier for the object.

  • suffix (Symbol) (defaults to: nil) —

    The suffix to use in the dbkey (default: :object).

Returns:

  • (Object, nil) —

    An instance of the class if found, nil otherwise.



171
172
173
174
175
176
177
178
179
180
 
# File 'lib/familia/horreum/management.rb', line 171

def find_by_id(identifier, suffix = nil)
  suffix ||= self.suffix
  return nil if identifier.to_s.empty?

  objkey = dbkey(identifier, suffix)

  Familia.ld "[.find_by_id] #{self} from key #{objkey})"
  Familia.trace :FIND_BY_ID, nil, objkey if Familia.debug?
  find_by_key objkey
end

#find_by_key(objkey) ⇒ Object? Also known as: from_dbkey

Retrieves and instantiates an object from Database using the full object key.

This method performs a two-step process to safely retrieve and instantiate objects:

  1. It first checks if the key exists in the database. This is crucial because:

    • It provides a definitive answer about the object's existence.
    • It prevents ambiguity that could arise from hgetall returning an empty hash for non-existent keys, which could lead to the creation of "empty" objects.

  2. If the key exists, it retrieves the object's data and instantiates it.

This approach ensures that we only attempt to instantiate objects that actually exist in Valkey/Redis, improving reliability and simplifying debugging.

Examples:

User.find_by_key("user:123")  # Returns a User instance if it exists,
nil otherwise

Parameters:

  • objkey (String) —

    The full dbkey for the object.

Returns:

  • (Object, nil) —

    An instance of the class if the key exists, nil otherwise.

Raises:

  • (ArgumentError) —

    If the provided key is empty.



128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/familia/horreum/management.rb', line 128

def find_by_key(objkey)
  raise ArgumentError, 'Empty key' if objkey.to_s.empty?

  # We use a lower-level method here b/c we're working with the
  # full key and not just the identifier.
  does_exist = dbclient.exists(objkey).positive?

  Familia.ld "[.find_by_key] #{self} from key #{objkey} (exists: #{does_exist})"
  Familia.trace :FROM_KEY, nil, objkey if Familia.debug?

  # This is the reason for calling exists first. We want to definitively
  # and without any ambiguity know if the object exists in the database. If it
  # doesn't, we return nil. If it does, we proceed to load the object.
  # Otherwise, hgetall will return an empty hash, which will be passed to
  # the constructor, which will then be annoying to debug.
  return unless does_exist

  obj = dbclient.hgetall(objkey) # horreum objects are persisted as database hashes
  Familia.trace :FROM_KEY2, nil, "#{objkey}: #{obj.inspect}" if Familia.debug?

  new(**obj)
end

#find_keys(suffix = '*') ⇒ Array<String>

Finds all keys in Database matching the given suffix pattern.

This method searches for all dbkeys that match the given suffix pattern. It uses the class's dbkey method to construct the search pattern.

Examples:

User.find  # Returns all keys matching user:*:object
User.find('active')  # Returns all keys matching user:*:active

Parameters:

  • suffix (String) (defaults to: '*') —

    The suffix pattern to match (default: '*').

Returns:

  • (Array<String>) —

    An array of matching dbkeys.



266
267
268
 
# File 'lib/familia/horreum/management.rb', line 266

def find_keys(suffix = '*')
  dbclient.keys(dbkey('*', suffix)) || []
end

#matching_keys_count(filter = '*') ⇒ Integer Also known as: size, length

Returns the number of dbkeys matching the given filter pattern

Parameters:

  • filter (String) (defaults to: '*') —

    dbkey pattern to match (default: '*')

Returns:

  • (Integer) —

    Number of matching keys



304
305
306
 
# File 'lib/familia/horreum/management.rb', line 304

def matching_keys_count(filter = '*')
  dbclient.keys(dbkey(filter)).compact.size
end

#multiget(*ids) ⇒ Object 



62
63
64
65
 
# File 'lib/familia/horreum/management.rb', line 62

def multiget(*ids)
  ids = rawmultiget(*ids)
  ids.filter_map { |json| from_json(json) }
end

#rawmultiget(*ids) ⇒ Object 



67
68
69
70
71
72
73
 
# File 'lib/familia/horreum/management.rb', line 67

def rawmultiget(*ids)
  ids.collect! { |objid| dbkey(objid) }
  return [] if ids.compact.empty?

  Familia.trace :MULTIGET, nil, "#{ids.size}: #{ids}" if Familia.debug?
  dbclient.mget(*ids)
end