Class: Square::Internal::Types::Model Abstract

Inherits:

Object

Object
Square::Internal::Types::Model

show all

Includes:: Type

Defined in:: lib/square/internal/types/model.rb,
lib/square/internal/types/model/field.rb

Overview

This class is abstract.

An abstract model that all data objects will inherit from

Direct Known Subclasses

Defined Under Namespace

Classes: Field

Class Method Summary collapse

.===(instance) ⇒ Object
.add_extra_field_definition(name:, type:) ⇒ void private

Adds a new field definition into the class’s extra fields registry.
.coerce(value, strict: (respond_to?(:strict?) ? strict? : false)) ⇒ Object

rubocop:disable Lint/UnusedMethodArgument.
.extra_fields ⇒ Hash<Symbol, Field> private

Any extra fields that have been created from instantiation.
.field(name, type, optional: false, nullable: false, api_name: nil, default: nil) ⇒ void

Define a new field on this model.
.fields ⇒ Hash<Symbol, Field> private

The defined fields for this model.
.literal(name, value, api_name: nil) ⇒ void

Define a new literal for this model.
.load(str) ⇒ Object

Instance Method Summary collapse

#==(other) ⇒ Object
#initialize(values = {}) ⇒ self constructor

Creates a new instance of this model TODO: Should all this logic be in ‘#coerce` instead?.
#inspect ⇒ String
#to_h ⇒ Object

Methods included from Type

#coerce, #strict!, #strict?

Methods included from JSON::Serializable

#dump, #load

Constructor Details

#initialize(values = {}) ⇒ `self`

Creates a new instance of this model TODO: Should all this logic be in ‘#coerce` instead?

Parameters:

values (Hash) (defaults to: {})
strict (Hash) —

a customizable set of options

# File 'lib/square/internal/types/model.rb', line 138

def initialize(values = {})
  @data = {}

  values = Utils.symbolize_keys(values.dup)

  self.class.fields.each do |field_name, field|
    value = values.delete(field.api_name.to_sym) || values.delete(field.api_name) || values.delete(field_name)

    field_value = value || (if field.literal?
                              field.value
                            elsif field.default
                              field.default
                            end)

    @data[field_name] = Utils.coerce(field.type, field_value)
  end

  # Any remaining values in the input become extra fields
  values.each do |name, value|
    self.class.add_extra_field_definition(name: name, type: value.class)

    @data[name.to_sym] = value
  end
end

Class Method Details

.===(instance) ⇒ `Object`



127
128
129

# File 'lib/square/internal/types/model.rb', line 127

def ===(instance)
  instance.class.ancestors.include?(self)
end

.add_extra_field_definition(name:, type:) ⇒ `void`

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Adds a new field definition into the class’s extra fields registry

Parameters:

name (Symbol)
type (Class)
required (Hash) —

a customizable set of options
optional (Hash) —

a customizable set of options

# File 'lib/square/internal/types/model.rb', line 88

def add_extra_field_definition(name:, type:)
  return if extra_fields.key?(name.to_sym)

  extra_fields[name.to_sym] = Field.new(name: name, type: type, optional: true, nullable: false)

  define_accessor(name)
  define_setter(name)
end

.coerce(value, strict: (respond_to?(:strict?) ? strict? : false)) ⇒ `Object`

rubocop:disable Lint/UnusedMethodArgument

# File 'lib/square/internal/types/model.rb', line 115

def coerce(value, strict: (respond_to?(:strict?) ? strict? : false)) # rubocop:disable Lint/UnusedMethodArgument
  return value if value.is_a?(self)

  return value unless value.is_a?(::Hash)

  new(value)
end

.extra_fields ⇒ `Hash<Symbol, Field>`

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Any extra fields that have been created from instantiation

Returns:

(Hash<Symbol, Field>)



31
32
33

# File 'lib/square/internal/types/model.rb', line 31

def extra_fields
  @extra_fields ||= {}
end

.field(name, type, optional: false, nullable: false, api_name: nil, default: nil) ⇒ `void`

This method returns an undefined value.

Define a new field on this model

Parameters:

name (Symbol) —

The name of the field
type (Class) —

Type of the field
optional (Hash) (defaults to: false) —

a customizable set of options
nullable (Hash) (defaults to: false) —

a customizable set of options
api_name (Hash) (defaults to: nil) —

a customizable set of options

Options Hash (optional:):

If (Boolean) —

it is an optional field

Options Hash (nullable:):

If (Boolean) —

it is a nullable field

Options Hash (api_name:):

Name (Symbol, String) —

in the API of this field. When serializing/deserializing, will use this field name

# File 'lib/square/internal/types/model.rb', line 44

def field(name, type, optional: false, nullable: false, api_name: nil, default: nil)
  add_field_definition(name: name, type: type, optional: optional, nullable: nullable, api_name: api_name,
                       default: default)

  define_accessor(name)
  define_setter(name)
end

.fields ⇒ `Hash<Symbol, Field>`

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The defined fields for this model

Returns:

(Hash<Symbol, Field>)

# File 'lib/square/internal/types/model.rb', line 18

def fields
  @fields ||= if self < Square::Internal::Types::Model
                superclass.fields.dup
              else
                {}
              end
end

.literal(name, value, api_name: nil) ⇒ `void`

This method returns an undefined value.

Define a new literal for this model

Parameters:

name (Symbol)
value (Object)
api_name (Hash) (defaults to: nil) —

a customizable set of options

Options Hash (api_name:):

(Symbol, String)

# File 'lib/square/internal/types/model.rb', line 58

def literal(name, value, api_name: nil)
  add_field_definition(name: name, type: value.class, optional: false, nullable: false, api_name: api_name,
                       value: value)

  define_accessor(name)
end

.load(str) ⇒ `Object`



123
124
125

# File 'lib/square/internal/types/model.rb', line 123

def load(str)
  coerce(::JSON.parse(str, symbolize_names: true))
end

Instance Method Details

#==(other) ⇒ `Object`



191
192
193

# File 'lib/square/internal/types/model.rb', line 191

def ==(other)
  self.class == other.class && to_h == other.to_h
end

#inspect ⇒ `String`

Returns:

(String)

# File 'lib/square/internal/types/model.rb', line 196

def inspect
  attrs = @data.map do |name, value|
    field = self.class.fields[name] || self.class.extra_fields[name]
    display_value = field&.sensitive? ? "[REDACTED]" : value.inspect
    "#{name}=#{display_value}"
  end

  "#<#{self.class.name}:0x#{object_id&.to_s(16)} #{attrs.join(" ")}>"
end

#to_h ⇒ `Object`

# File 'lib/square/internal/types/model.rb', line 163

def to_h
  result = self.class.fields.merge(self.class.extra_fields).each_with_object({}) do |(name, field), acc|
    # If there is a value present in the data, use that value
    # If there is a `nil` value present in the data, and it is optional but NOT nullable, exclude key altogether
    # If there is a `nil` value present in the data, and it is optional and nullable, use the nil value

    value = @data[name]

    next if value.nil? && field.optional && !field.nullable

    if value.is_a?(::Array)
      value = value.map { |item| item.respond_to?(:to_h) ? item.to_h : item }
    elsif value.respond_to?(:to_h)
      value = value.to_h
    end

    acc[field.api_name] = value
  end

  # Inject union discriminant if this instance was coerced from a discriminated union
  # and the discriminant key is not already present in the result
  discriminant_key = instance_variable_get(:@_fern_union_discriminant_key)
  discriminant_value = instance_variable_get(:@_fern_union_discriminant_value)
  result[discriminant_key] = discriminant_value if discriminant_key && discriminant_value && !result.key?(discriminant_key)

  result
end

Class: Square::Internal::Types::Model Abstract

Overview

Direct Known Subclasses

Defined Under Namespace

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Type

Methods included from JSON::Serializable

Constructor Details

#initialize(values = {}) ⇒ self

Class Method Details

.===(instance) ⇒ Object

.add_extra_field_definition(name:, type:) ⇒ void

.coerce(value, strict: (respond_to?(:strict?) ? strict? : false)) ⇒ Object

.extra_fields ⇒ Hash<Symbol, Field>

.field(name, type, optional: false, nullable: false, api_name: nil, default: nil) ⇒ void

.fields ⇒ Hash<Symbol, Field>

.literal(name, value, api_name: nil) ⇒ void

.load(str) ⇒ Object

Instance Method Details

#==(other) ⇒ Object

#inspect ⇒ String

#to_h ⇒ Object

#initialize(values = {}) ⇒ `self`

.===(instance) ⇒ `Object`

.add_extra_field_definition(name:, type:) ⇒ `void`

.coerce(value, strict: (respond_to?(:strict?) ? strict? : false)) ⇒ `Object`

.extra_fields ⇒ `Hash<Symbol, Field>`

.field(name, type, optional: false, nullable: false, api_name: nil, default: nil) ⇒ `void`

.fields ⇒ `Hash<Symbol, Field>`

.literal(name, value, api_name: nil) ⇒ `void`

.load(str) ⇒ `Object`

#==(other) ⇒ `Object`

#inspect ⇒ `String`

#to_h ⇒ `Object`