fmrest 0.1.0 → 0.2.0

data/lib/fmrest/spyke/model.rb

@@ -1,8 +1,12 @@
+# frozen_string_literal: true
+
 require "fmrest/spyke/model/connection"
 require "fmrest/spyke/model/uri"
 require "fmrest/spyke/model/attributes"
+require "fmrest/spyke/model/serialization"
 require "fmrest/spyke/model/associations"
 require "fmrest/spyke/model/orm"
+require "fmrest/spyke/model/container_fields"
 
 module FmRest
   module Spyke
@@ -12,10 +16,13 @@ module FmRest
       include Connection
       include Uri
       include Attributes
+      include Serialization
       include Associations
       include Orm
+      include ContainerFields
 
       included do
+        # @return [Integer] the record's modId
         attr_accessor :mod_id
       end
     end

data/lib/fmrest/spyke/model/associations.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "fmrest/spyke/portal"
 
 module FmRest

data/lib/fmrest/spyke/model/attributes.rb

@@ -1,16 +1,19 @@
+# frozen_string_literal: true
+
+require "fmrest/spyke/model/orm"
+
 module FmRest
   module Spyke
     module Model
       module Attributes
         extend ::ActiveSupport::Concern
 
+        include Orm # Needed to extend custom save and reload
+
         include ::ActiveModel::Dirty
         include ::ActiveModel::ForbiddenAttributesProtection
 
         included do
-          # Keep mod_id as a separate, custom accessor
-          attr_accessor :mod_id
-
           # Prevent the creation of plain (no prefix/suffix) attribute methods
           # when calling ActiveModels' define_attribute_method, otherwise it
           # will define an `attribute` method which overrides the one provided
@@ -100,29 +103,12 @@ module FmRest
           super
         end
 
-        def save(*_args)
-          super.tap do |r|
-            next unless r.present?
-            changes_applied
-            portals.each(&:parent_changes_applied)
-          end
-        end
-
-        def reload
+        def reload(*args)
           super.tap { |r| clear_changes_information }
         end
 
-        # Override to_params to return FM Data API's expected JSON format, and
-        # including only modified fields
-        #
-        def to_params
-          params = { fieldData: changed_params_not_embedded_in_url }
-          params[:modId] = mod_id if mod_id
-
-          portal_data = serialize_portals
-          params[:portalData] = portal_data unless portal_data.empty?
-
-          params
+        def save(*args)
+          super.tap { |r| changes_applied_after_save if r }
         end
 
         # ActiveModel::Dirty since version 5.2 assumes that if there's an
@@ -143,44 +129,12 @@ module FmRest
           use_setters(sanitize_for_mass_assignment(new_attributes)) if new_attributes && !new_attributes.empty?
         end
 
-        protected
-
-        def serialize_for_portal(portal)
-          params =
-            changed_params.except(:id).transform_keys do |key|
-              "#{portal.attribute_prefix}::#{key}"
-            end
-
-          params[:recordId] = id if id
-          params[:modId] = mod_id if mod_id
-
-          params
-        end
-
         private
 
-        def serialize_portals
-          portal_data = {}
-
-          portals.each do |portal|
-            portal.each do |portal_record|
-              next unless portal_record.changed?
-              portal_params = portal_data[portal.portal_key] ||= []
-              portal_params << portal_record.serialize_for_portal(portal)
-            end
-          end
-
-          portal_data
-        end
-
         def changed_params
           attributes.to_params.slice(*mapped_changed)
         end
 
-        def changed_params_not_embedded_in_url
-          params_not_embedded_in_url.slice(*mapped_changed)
-        end
-
         def mapped_changed
           mapped_attributes.values_at(*changed)
         end
@@ -192,6 +146,11 @@ module FmRest
             "#{k}: #{attribute(v).inspect}"
           end.join(', ')
         end
+
+        def changes_applied_after_save
+          changes_applied
+          portals.each(&:parent_changes_applied)
+        end
       end
     end
   end

data/lib/fmrest/spyke/model/connection.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module FmRest
   module Spyke
     module Model

data/lib/fmrest/spyke/model/container_fields.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "fmrest/spyke/container_field"
+
+module FmRest
+  module Spyke
+    module Model
+      module ContainerFields
+        extend ::ActiveSupport::Concern
+
+        class_methods do
+          def container(name, options = {})
+            field_name = options[:field_name] || name
+
+            define_method(name) do
+              @container_fields ||= {}
+              @container_fields[name.to_sym] ||= ContainerField.new(self, field_name)
+            end
+          end
+        end
+      end
+    end
+  end
+end
+

data/lib/fmrest/spyke/model/orm.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "fmrest/spyke/relation"
 
 module FmRest
@@ -14,6 +16,7 @@ module FmRest
         end
 
         class_methods do
+          # Methods delegated to FmRest::Spyke::Relation
           delegate :limit, :offset, :sort, :query, :portal, to: :all
 
           def all
@@ -42,6 +45,12 @@ module FmRest
             self.current_scope = previous
           end
 
+          # API-error-raising version of #create
+          #
+          def create!(attributes = {})
+            new(attributes).tap(&:save!)
+          end
+
           private
 
           def extend_scope_with_fm_params(scope, prefixed: false)
@@ -66,13 +75,71 @@ module FmRest
           end
         end
 
-        # Ensure save returns true/false, following ActiveRecord's convention
+        # Completely override Spyke's save to provide a number of features:
+        #
+        # * Validations
+        # * Data API scripts execution
+        # * Refresh of dirty attributes
         #
         def save(options = {})
-          if options[:validate] == false || valid?
-            super().present? # Failed save returns empty hash
-          else
-            false
+          callback = persisted? ? :update : :create
+
+          return false unless perform_save_validations(callback, options)
+          return false unless perform_save_persistence(callback, options)
+
+          true
+        end
+
+        def save!(options = {})
+          save(options.merge(raise_validation_errors: true))
+        end
+
+        # API-error-raising version of #update
+        #
+        def update!(new_attributes)
+          self.attributes = new_attributes
+          save!
+        end
+
+        def reload
+          reloaded = self.class.find(id)
+          self.attributes = reloaded.attributes
+          self.mod_id = reloaded.mod_id
+        end
+
+        private
+
+        def perform_save_validations(context, options)
+          return true if options[:validate] == false
+          options[:raise_validation_errors] ? validate!(context) : validate(context)
+        end
+
+        def perform_save_persistence(callback, options)
+          run_callbacks :save do
+            run_callbacks(callback) do
+
+              begin
+                send self.class.method_for(callback), build_params_for_save(options)
+
+              rescue APIError::ValidationError => e
+                if options[:raise_validation_errors]
+                  raise e
+                else
+                  return false
+                end
+              end
+
+            end
+          end
+
+          true
+        end
+
+        def build_params_for_save(options)
+          to_params.tap do |params|
+            if options.has_key?(:script)
+              params.merge!(FmRest::V1.convert_script_params(options[:script]))
+            end
           end
         end
       end

data/lib/fmrest/spyke/model/serialization.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module FmRest
+  module Spyke
+    module Model
+      module Serialization
+        FM_DATE_FORMAT = "%m/%d/%Y".freeze
+        FM_DATETIME_FORMAT = "#{FM_DATE_FORMAT} %H:%M:%S".freeze
+
+        # Override Spyke's to_params to return FM Data API's expected JSON
+        # format, and including only modified fields
+        #
+        def to_params
+          params = {
+            fieldData: serialize_values!(changed_params_not_embedded_in_url)
+          }
+
+          params[:modId] = mod_id if mod_id
+
+          portal_data = serialize_portals
+          params[:portalData] = portal_data unless portal_data.empty?
+
+          params
+        end
+
+        protected
+
+        def serialize_for_portal(portal)
+          params =
+            changed_params.except(:id).transform_keys do |key|
+              "#{portal.attribute_prefix}::#{key}"
+            end
+
+          params[:recordId] = id if id
+          params[:modId] = mod_id if mod_id
+
+          serialize_values!(params)
+        end
+
+        private
+
+        def serialize_portals
+          portal_data = {}
+
+          portals.each do |portal|
+            portal.each do |portal_record|
+              next unless portal_record.changed?
+              portal_params = portal_data[portal.portal_key] ||= []
+              portal_params << portal_record.serialize_for_portal(portal)
+            end
+          end
+
+          portal_data
+        end
+
+        def changed_params_not_embedded_in_url
+          params_not_embedded_in_url.slice(*mapped_changed)
+        end
+
+        # Modifies the given hash in-place encoding non-string values (e.g.
+        # dates) to their string representation when appropriate.
+        #
+        def serialize_values!(params)
+          params.transform_values! do |value|
+            case value
+            when DateTime, Time
+              value.strftime(FM_DATETIME_FORMAT)
+            when Date
+              value.strftime(FM_DATE_FORMAT)
+            else
+              value
+            end
+          end
+
+          params
+        end
+      end
+    end
+  end
+end

data/lib/fmrest/spyke/model/uri.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module FmRest
   module Spyke
     module Model

data/lib/fmrest/spyke/portal.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module FmRest
   module Spyke
     # Extend Spyke's HasMany association with custom options

data/lib/fmrest/spyke/relation.rb

@@ -1,12 +1,16 @@
+# frozen_string_literal: true
+
 module FmRest
   module Spyke
     class Relation < ::Spyke::Relation
       SORT_PARAM_MATCHER = /(.*?)(!|__desc(?:end)?)?\Z/.freeze
 
-      # We need to keep these separate from regular params because FM Data API
-      # uses either "limit" or "_limit" (or "_offset", etc.) as param keys
-      # depending on the type of request, so we can't set the params until the
-      # last moment
+      # NOTE: We need to keep limit, offset, sort, query and portal accessors
+      # separate from regular params because FM Data API uses either "limit" or
+      # "_limit" (or "_offset", etc.) as param keys depending on the type of
+      # request, so we can't set the params until the last moment
+
+
       attr_accessor :limit_value, :offset_value, :sort_params, :query_params,
                     :portal_params
 
@@ -23,32 +27,40 @@ module FmRest
         @portal_params = []
       end
 
+      # @param value [Integer] the limit value
+      # @return [FmRest::Spyke::Relation] a new relation with the limit applied
       def limit(value)
         with_clone { |r| r.limit_value = value }
       end
 
+      # @param value [Integer] the offset value
+      # @return [FmRest::Spyke::Relation] a new relation with the offset
+      #   applied
       def offset(value)
         with_clone { |r| r.offset_value = value }
       end
 
       # Allows sort params given in either hash format (using FM Data API's
       # format), or as a symbol, in which case the of the attribute must match
-      # a known mapped attribute, optionally suffixed with ! or __desc[end] to
+      # a known mapped attribute, optionally suffixed with `!` or `__desc` to
       # signify it should use descending order.
       #
-      # E.g.
-      #
-      #     Person.sort(:first_name, :age!)
-      #     Person.sort(:first_name, :age__desc)
-      #     Person.sort(:first_name, :age__descend)
-      #     Person.sort({ fieldName: "FirstName" }, { fieldName: "Age", sortOrder: "descend" })
-      #
+      # @param args [Array<Symbol, Hash>] the names of attributes to sort by with
+      #   optional `!` or `__desc` suffix, or a hash of options as expected by
+      #     the FM Data API
+      # @example
+      #   Person.sort(:first_name, :age!)
+      #   Person.sort(:first_name, :age__desc)
+      #   Person.sort(:first_name, :age__descend)
+      #   Person.sort({ fieldName: "FirstName" }, { fieldName: "Age", sortOrder: "descend" })
+      # @return [FmRest::Spyke::Relation] a new relation with the sort options
+      #   applied
       def sort(*args)
         with_clone do |r|
           r.sort_params = args.flatten.map { |s| normalize_sort_param(s) }
         end
       end
-      alias :order :sort
+      alias order sort
 
       def portal(*args)
         with_clone do |r|
@@ -56,7 +68,7 @@ module FmRest
           r.portal_params.uniq!
         end
       end
-      alias :includes :portal
+      alias includes portal
 
       def query(*params)
         with_clone do |r|
@@ -68,10 +80,14 @@ module FmRest
         query(params.merge(omit: true))
       end
 
+      # @return [Boolean] whether a query was set on this relation
       def has_query?
         query_params.present?
       end
 
+      # Finds a single instance of the model by forcing limit = 1
+      #
+      # @return [FmRest::Spyke::Base]
       def find_one
         return super if params[klass.primary_key].present?
         @find_one ||= klass.new_collection_from_result(limit(1).fetch).first