Module: Familia::Horreum::DefinitionMethods

Includes:
RelatedFieldsManagement, Settings
Defined in:
lib/familia/horreum/definition_methods.rb

Overview

DefinitionMethods: Provides class-level functionality for Horreum

This module is extended into classes that include Familia::Horreum, providing methods for Database operations and object management.

Key features: * Includes RelatedFieldsManagement for DataType field handling * Defines methods for managing fields, identifiers, and dbkeys * Provides utility methods for working with Database objects

Instance Attribute Summary

Attributes included from Settings

#current_key_version, #default_expiration, #delim, #encryption_keys, #encryption_personalization

Instance Method Summary collapse

Methods included from RelatedFieldsManagement

#attach_class_related_field, #attach_instance_related_field

Methods included from Settings

#config, #default_suffix

Instance Method Details



153
154
155
156
 
# File 'lib/familia/horreum/definition_methods.rb', line 153

def class_related_fields
  @class_related_fields ||= {}
  @class_related_fields
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.

Examples:

V2::Session.config_name => ‘session’

Returns:

  • (String) —

    The underscored class name as a string



174
175
176
177
178
179
 
# File 'lib/familia/horreum/definition_methods.rb', line 174

def config_name
  name.split('::').last
      .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
      .gsub(/([a-z\d])([A-Z])/, '\1_\2')
      .downcase
end

#dump_method ⇒ Object 



181
182
183
 
# File 'lib/familia/horreum/definition_methods.rb', line 181

def dump_method
  @dump_method || :to_json # Familia.dump_method
end

#field(name, as: name, fast_method: :"#{name}!", on_conflict: :raise, category: nil) ⇒ Object

Defines a field for the class and creates accessor methods.

This method defines a new field for the class, creating getter and setter instance methods similar to attr_accessor. It also generates a fast writer method for immediate persistence to Redis.

Parameters:

  • name (Symbol, String) —

    the name of the field to define. If a method with the same name already exists, an error is raised.

  • as (Symbol, String, false, nil) (defaults to: name) —

    as the name to use for the accessor method (defaults to name). If false or nil, no accessor methods are created.

  • fast_method (Symbol, false, nil) (defaults to: :"#{name}!") —

    the name to use for the fast writer method (defaults to :”#name!”). If false or nil, no fast writer method is created.

  • on_conflict (Symbol) (defaults to: :raise) —

    conflict resolution strategy when method already exists: - :raise - raise error if method exists (default) - :skip - skip definition if method exists - :warn - warn but proceed (may overwrite) - :ignore - proceed silently (may overwrite)

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

    field category for special handling: - nil - regular field (default) - :encrypted - field contains encrypted data - :transient - field is not persisted - Others, depending on features available



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

def field(name, as: name, fast_method: :"#{name}!", on_conflict: :raise, category: nil)
  # Use field type system internally for consistency
  require_relative '../field_type'

  # Create appropriate field type based on category
  field_type = if category == :transient
                 require_relative '../features/transient_fields/transient_field_type'
                 TransientFieldType.new(name, as: as, fast_method: false, on_conflict: on_conflict)
               else
                 # For regular fields and other categories, create custom field type with category override
                 custom_field_type = Class.new(FieldType) do
                   define_method :category do
                     category || :field
                   end
                 end
                 custom_field_type.new(name, as: as, fast_method: fast_method, on_conflict: on_conflict)
               end

  register_field_type(field_type)
end

#field_method_map ⇒ Object

Returns a hash mapping field names to method names for backward compatibility



195
196
197
 
# File 'lib/familia/horreum/definition_methods.rb', line 195

def field_method_map
  field_types.transform_values(&:method_name)
end

#field_types ⇒ Object

Storage for field type instances



190
191
192
 
# File 'lib/familia/horreum/definition_methods.rb', line 190

def field_types
  @field_types ||= {}
end

#fields ⇒ Object

Returns the list of field names defined for the class in the order that they were defined. i.e. field :a; field :b; fields => [:a, :b].



148
149
150
151
 
# File 'lib/familia/horreum/definition_methods.rb', line 148

def fields
  @fields ||= []
  @fields
end

#has_relations? ⇒ Boolean

Returns:

  • (Boolean) 


163
164
165
 
# File 'lib/familia/horreum/definition_methods.rb', line 163

def has_relations?
  @has_relations ||= false
end

#identifier_field(val = nil) ⇒ Object

Sets or retrieves the unique identifier field for the class.

This method defines or returns the field or method that contains the unique identifier used to generate the dbkey for the object. If a value is provided, it sets the identifier field; otherwise, it returns the current identifier field.

Parameters:

  • val (Object) (defaults to: nil) —

    the field name or method to set as the identifier field (optional).

Returns:

  • (Object) —

    the current identifier field.



49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
 
# File 'lib/familia/horreum/definition_methods.rb', line 49

def identifier_field(val = nil)
  if val
    # Validate identifier field definition at class definition time
    case val
    when Symbol, String, Proc
      @identifier_field = val
    else
      raise Problem, <<~ERROR
        Invalid identifier field definition: #{val.inspect}.
        Use a field name (Symbol/String) or Proc.
      ERROR
    end
  end
  @identifier_field
end

#load_method ⇒ Object 



185
186
187
 
# File 'lib/familia/horreum/definition_methods.rb', line 185

def load_method
  @load_method || :from_json # Familia.load_method
end

#logical_database(v = nil) ⇒ Object 



140
141
142
143
144
 
# File 'lib/familia/horreum/definition_methods.rb', line 140

def logical_database(v = nil)
  Familia.trace :DB, Familia.dbclient, "#{@logical_database} #{v.nil?}", caller(0..2) if Familia.debug?
  @logical_database = v unless v.nil?
  @logical_database || parent&.logical_database
end

#persistent_fields ⇒ Object

Get fields for serialization (excludes transients)



200
201
202
203
204
 
# File 'lib/familia/horreum/definition_methods.rb', line 200

def persistent_fields
  fields.select do |field|
    field_types[field]&.persistent?
  end
end

#prefix(a = nil) ⇒ String, Symbol

Sets or retrieves the prefix for generating Redis keys.

The exception is only raised when both @prefix is nil/falsy AND name is nil, which typically occurs with anonymous classes that haven’t had their prefix explicitly set.

Parameters:

  • a (String, Symbol, nil) (defaults to: nil) —

    the prefix to set (optional).

Returns:

  • (String, Symbol) —

    the current prefix.



129
130
131
132
133
134
135
136
137
138
 
# File 'lib/familia/horreum/definition_methods.rb', line 129

def prefix(a = nil)
  @prefix = a if a
  @prefix || begin
    if name.nil?
      raise Problem, 'Cannot generate prefix for anonymous class. ' \
                     'Use `prefix` method to set explicitly.'
    end
    name.downcase.gsub('::', Familia.delim).to_sym
  end
end

#register_field_type(field_type) ⇒ Object

Register a field type instance with this class

This method installs the field type’s methods and registers it for later reference. It maintains backward compatibility by creating FieldDefinition objects.

Parameters:

  • field_type (FieldType) —

    The field type to register



221
222
223
224
225
226
227
 
# File 'lib/familia/horreum/definition_methods.rb', line 221

def register_field_type(field_type)
  fields << field_type.name
  field_type.install(self)
  # Complete the registration after installation. If we do this beforehand
  # we can run into issues where it looks like it's already installed.
  field_types[field_type.name] = field_type
end

#related_fields ⇒ Object 



158
159
160
161
 
# File 'lib/familia/horreum/definition_methods.rb', line 158

def related_fields
  @related_fields ||= {}
  @related_fields
end

#suffix(a = nil, &blk) ⇒ String, Symbol

Sets or retrieves the suffix for generating Redis keys.

Parameters:

  • a (String, Symbol, nil) (defaults to: nil) —

    the suffix to set (optional).

  • blk (Proc) —

    a block that returns the suffix (optional).

Returns:

  • (String, Symbol) —

    the current suffix or Familia.default_suffix if none is set.



115
116
117
118
 
# File 'lib/familia/horreum/definition_methods.rb', line 115

def suffix(a = nil, &blk)
  @suffix = a || blk if a || !blk.nil?
  @suffix || Familia.default_suffix
end

#transient_field(name) ⇒ Object

Create and register a transient field type

Parameters:

  • name (Symbol) —

    The field name

  • options (Hash) —

    Field options



234
235
236
237
238
 
# File 'lib/familia/horreum/definition_methods.rb', line 234

def transient_field(name, **)
  require_relative '../features/transient_fields/transient_field_type'
  field_type = TransientFieldType.new(name, **, fast_method: false)
  register_field_type(field_type)
end

#transient_fields ⇒ Object

Get fields that are not persisted to the database (transients)



207
208
209
210
211
 
# File 'lib/familia/horreum/definition_methods.rb', line 207

def transient_fields
  fields.select do |field|
    field_types[field]&.transient?
  end
end