Module: Familia::Features::SafeDump

Extended by:
ClassMethods
Defined in:
lib/familia/features/safe_dump.rb

Overview

SafeDump is a mixin that allows models to define a list of fields that are safe to dump. This is useful for serializing objects to JSON or other formats where you want to ensure that only certain fields are exposed.

To use SafeDump, include it in your model and define a list of fields that are safe to dump. The fields can be either symbols or hashes. If a field is a symbol, the method with the same name will be called on the object to retrieve the value. If the field is a hash, the key is the field name and the value is a lambda that will be called with the object as an argument. the hash syntax allows you to:

* define a field name that is different from the method name
* define a field that requires some computation on-the-fly
* define a field that is not a method on the object

Example:

@safe_dump_fields = [
  :objid,
  :updated,
  :created,
  { :active => ->(obj) { obj.active? } }
]

Internally, all fields are normalized to the hash syntax and store in of symbols in the order they were defined. From the example above, it would return ‘[:objid, :updated, :created, :active]`.

Defined Under Namespace

Modules: ClassMethods

Class Method Summary collapse

Instance Method Summary collapse

Methods included from ClassMethods

safe_dump_field_map, safe_dump_fields, set_safe_dump_fields

Class Method Details

.included(base) ⇒ Object 



87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/familia/features/safe_dump.rb', line 87

def self.included base
  Familia.ld "[Feature] Enabling SafeDump for #{base})"
  base.extend ClassMethods

  # Optionally define safe_dump_fields in the class to make
  # sure we always have an array to work with.
  unless base.instance_variable_defined?(:@safe_dump_fields)
    base.instance_variable_set(:@safe_dump_fields, [])
  end

  # Ditto for the field map
  unless base.instance_variable_defined?(:@safe_dump_field_map)
    base.instance_variable_set(:@safe_dump_field_map, {})
  end
end

Instance Method Details

#safe_dump ⇒ Object

Returns a hash of safe fields and their values. This method calls the callables defined in the safe_dump_field_map with the instance object as an argument.

The return values are not cached, so if you call this method multiple times, the callables will be called each time.

Example:

class Customer < Familia::HashKey
  include SafeDump
  @safe_dump_fields = [
    :name,
    { :active => ->(cust) { cust.active? } }
  ]

  def active?
    true # or false
  end

  cust = Customer.new :name => 'Lucy'
  cust.safe_dump
  #=> { :name => 'Lucy', :active => true }



127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/familia/features/safe_dump.rb', line 127

def safe_dump
  self.class.safe_dump_field_map.transform_values do |callable|
    transformed_value = callable.call(self)

    # If the value is a relative ancestor of SafeDump we can
    # call safe_dump on it, otherwise we'll just return the value as-is.
    if transformed_value.is_a?(SafeDump)
      transformed_value.safe_dump
    else
      transformed_value
    end
  end
end