fmrest-spyke 0.13.0

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module FmRest
+  module Spyke
+    module Model
+      # Modifies Spyke models to use `__record_id` instead of `id` as the
+      # "primary key" method, so that we can map a model class to a FM layout
+      # with a field named `id` without clobbering it.
+      #
+      # The `id` reader method still maps to the record ID for backwards
+      # compatibility and because Spyke hardcodes its use at various points
+      # through its codebase, but it can be safely overwritten (e.g. to map to
+      # a FM field).
+      #
+      # The recommended way to deal with a layout that maps an `id` attribute
+      # is to remap it in the model to something else, e.g. `unique_id`.
+      #
+      module RecordID
+        extend ::ActiveSupport::Concern
+
+        included do
+          # @return [Integer] the record's recordId
+          attr_reader :__record_id
+          alias_method :record_id, :__record_id
+          alias_method :id, :__record_id
+
+          # @return [Integer] the record's modId
+          attr_reader :__mod_id
+          alias_method :mod_id, :__mod_id
+
+          # Get rid of Spyke's id= setter method, as we'll be using __record_id=
+          # instead
+          undef_method :id=
+
+          # Tell Spyke that we want __record_id as the PK
+          self.primary_key = :__record_id
+        end
+
+        # Sets the recordId and converts it to integer if it's not nil
+        #
+        # @param value [String, Integer, nil] The new recordId
+        #
+        # @return [Integer] the record's recordId
+        def __record_id=(value)
+          @__record_id = value.nil? ? nil : value.to_i
+        end
+
+        # Sets the modId and converts it to integer if it's not nil
+        #
+        # @param value [String, Integer, nil] The new modId
+        #
+        # @return [Integer] the record's modId
+        def __mod_id=(value)
+          @__mod_id = value.nil? ? nil : value.to_i
+        end
+
+        def __record_id?
+          __record_id.present?
+        end
+        alias_method :record_id?, :__record_id?
+        alias_method :persisted?, :__record_id?
+
+        # Spyke override -- Use `__record_id` instead of `id`
+        #
+        def hash
+          __record_id.hash
+        end
+
+        # Spyke override -- Renders class string with layout name and
+        # `record_id`.
+        #
+        # @return [String] A string representation of the class
+        #
+        def inspect
+          "#<#{self.class}(layout: #{self.class.layout}) record_id: #{__record_id.inspect} #{inspect_attributes}>"
+        end
+
+        # Spyke override -- Use `__record_id` instead of `id`
+        #
+        # @param id [Integer] The id of the record to destroy
+        #
+        def destroy(id = nil)
+          new(__record_id: id).destroy
+        end
+
+        private
+
+        # Spyke override (private)
+        #
+        def conflicting_ids?(attributes)
+          false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module FmRest
+  module Spyke
+    module Model
+      module Serialization
+        FM_DATE_FORMAT = "%m/%d/%Y"
+        FM_DATETIME_FORMAT = "#{FM_DATE_FORMAT} %H:%M:%S"
+
+        # Spyke override -- Return FM Data API's expected JSON format,
+        # including only modified fields.
+        #
+        def to_params
+          params = {
+            fieldData: serialize_values!(changed_params_not_embedded_in_url).merge(serialize_portal_deletions)
+          }
+
+          params[:modId] = __mod_id.to_s 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(:__record_id).transform_keys do |key|
+              "#{portal.attribute_prefix}::#{key}"
+            end
+
+          params[:recordId] = __record_id.to_s if __record_id
+          params[:modId] = __mod_id.to_s 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_record.marked_for_destruction?
+              portal_params = portal_data[portal.portal_key] ||= []
+              portal_params << portal_record.serialize_for_portal(portal)
+            end
+          end
+
+          portal_data
+        end
+
+        def serialize_portal_deletions
+          deletions = []
+
+          portals.each do |portal|
+            portal.select(&:marked_for_destruction?).each do |portal_record|
+              next unless portal_record.persisted?
+              deletions << "#{portal.portal_key}.#{portal_record.__record_id}"
+            end
+          end
+
+          return {} if deletions.length == 0
+
+          { deleteRelated: deletions.length == 1 ? deletions.first : deletions }
+        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_classes
+              convert_datetime_timezone(value.to_datetime).strftime(FM_DATETIME_FORMAT)
+            when *date_classes
+              value.strftime(FM_DATE_FORMAT)
+            else
+              value
+            end
+          end
+
+          params
+        end
+
+        def convert_datetime_timezone(dt)
+          case fmrest_config.timezone
+          when :utc, "utc"
+            dt.new_offset(0)
+          when :local, "local"
+            dt.new_offset(FmRest::V1.local_offset_for_datetime(dt))
+          when nil
+            dt
+          end
+        end
+
+        def datetime_classes
+          [DateTime, Time, defined?(FmRest::StringDateTime) && FmRest::StringDateTime].compact
+        end
+
+        def date_classes
+          [Date, defined?(FmRest::StringDate) && FmRest::StringDate].compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module FmRest
+  module Spyke
+    module Model
+      module URI
+        extend ::ActiveSupport::Concern
+
+        class_methods do
+          # Accessor for FM layout (helps with building the URI)
+          #
+          def layout(layout = nil)
+            @layout = layout if layout
+            @layout ||= model_name.name
+          end
+
+          # Spyke override -- Extends `uri` to default to FM Data's URI schema
+          #
+          def uri(uri_template = nil)
+            if @uri.nil? && uri_template.nil?
+              return FmRest::V1.record_path(layout) + "(/:#{primary_key})"
+            end
+            super
+          end
+        end
+      end
+    end
+  end
+end

data/lib/fmrest/spyke/portal.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module FmRest
+  module Spyke
+    # Extend Spyke's HasMany association with custom options
+    #
+    class Portal < ::Spyke::Associations::HasMany
+      def initialize(*args)
+        super
+
+        # Portals are always embedded, so no special URI
+        @options[:uri] = ""
+      end
+
+      def portal_key
+        (@options[:portal_key] || name).to_s
+      end
+
+      def attribute_prefix
+        (@options[:attribute_prefix] || portal_key).to_s
+      end
+
+      # Callback method, not meant to be used directly
+      #
+      def parent_changes_applied
+        each(&:changes_applied)
+      end
+
+      def <<(*records)
+        records.flatten.each { |r| add_to_parent(r) }
+        self
+      end
+      alias_method :push, :<<
+      alias_method :concat, :<<
+
+      def _remove_marked_for_destruction
+        find_some.reject!(&:marked_for_destruction?)
+      end
+
+      private
+
+      # Spyke::Associations::HasMany#initialize calls primary_key to build the
+      # default URI, which causes a NameError, so this is here just to prevent
+      # that. We don't care what it returns as we override the URI with nil
+      # anyway
+      def primary_key; end
+
+      # Make sure the association doesn't try to fetch records through URI
+      def uri; nil; end
+
+      def embedded_data
+        parent.attributes[portal_key]
+      end
+
+      # Spyke override
+      #
+      def add_to_parent(record)
+        raise ArgumentError, "Expected an instance of #{klass}, got a #{record.class} instead" unless record.kind_of?(klass)
+        find_some << record
+        record.embedded_in_portal
+        record
+      end
+    end
+  end
+end

data/lib/fmrest/spyke/relation.rb

@@ -0,0 +1,359 @@
+# frozen_string_literal: true
+
+module FmRest
+  module Spyke
+    class Relation < ::Spyke::Relation
+      SORT_PARAM_MATCHER = /(.*?)(!|__desc(?:end)?)?\Z/.freeze
+
+      # 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,
+                    :included_portals, :portal_params, :script_params
+
+      def initialize(*_args)
+        super
+
+        @limit_value = klass.default_limit
+
+        if klass.default_sort.present?
+          @sort_params = Array.wrap(klass.default_sort).map { |s| normalize_sort_param(s) }
+        end
+
+        @query_params = []
+
+        @included_portals = nil
+        @portal_params = {}
+        @script_params = {}
+      end
+
+      # @param options [String, Array, Hash, nil, false] sets script params to
+      #   execute in the next get or find request
+      #
+      # @example
+      #   # Find records and run the script named "My script"
+      #   Person.script("My script").find_some
+      #
+      #   # Find records and run the script named "My script" with param "the param"
+      #   Person.script(["My script", "the param"]).find_some
+      #
+      #   # Find records and run a prerequest, presort and after (normal) script
+      #   Person.script(after: "Script", prerequest: "Prereq script", presort: "Presort script").find_some
+      #
+      #   # Same as above, but passing parameters too
+      #   Person.script(
+      #     after:      ["After script", "the param"],
+      #     prerequest: ["Prereq script", "the param"],
+      #     presort: o  ["Presort script", "the param"]
+      #   ).find_some
+      #
+      #   Person.script(nil).find_some # Disable script execution
+      #   Person.script(false).find_some # Disable script execution
+      #
+      # @return [FmRest::Spyke::Relation] a new relation with the script
+      #   options applied
+      def script(options)
+        with_clone do |r|
+          if options.eql?(false) || options.eql?(nil)
+            r.script_params = {}
+          else
+            r.script_params = script_params.merge(FmRest::V1.convert_script_params(options))
+          end
+        end
+      end
+
+      # @param value_or_hash [Integer, Hash] the limit value for this layout,
+      #   or a hash with limits for the layout's portals
+      # @example
+      #   Person.limit(10) # Set layout limit
+      #   Person.limit(children: 10) # Set portal limit
+      # @return [FmRest::Spyke::Relation] a new relation with the limits
+      #   applied
+      def limit(value_or_hash)
+        with_clone do |r|
+          if value_or_hash.respond_to?(:each)
+            r.set_portal_params(value_or_hash, :limit)
+          else
+            r.limit_value = value_or_hash
+          end
+        end
+      end
+
+      # @param value_or_hash [Integer, Hash] the offset value for this layout,
+      #   or a hash with offsets for the layout's portals
+      # @example
+      #   Person.offset(10) # Set layout offset
+      #   Person.offset(children: 10) # Set portal offset
+      # @return [FmRest::Spyke::Relation] a new relation with the offsets
+      #   applied
+      def offset(value_or_hash)
+        with_clone do |r|
+          if value_or_hash.respond_to?(:each)
+            r.set_portal_params(value_or_hash, :offset)
+          else
+            r.offset_value = value_or_hash
+          end
+        end
+      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` to
+      # signify it should use descending order.
+      #
+      # @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
+
+      # Sets the portals to include with each record in the response.
+      #
+      # @param args [Array<Symbol, String>, true, false] the names of portals to
+      #   include, or `false` to request no portals
+      # @example
+      #   Person.portal(:relatives, :pets)
+      #   Person.portal(false) # Disables portals
+      #   Person.portal(true) # Enables portals (includes all)
+      # @return [FmRest::Spyke::Relation] a new relation with the portal
+      #   options applied
+      def portal(*args)
+        raise ArgumentError, "Call `portal' with at least one argument" if args.empty?
+
+        with_clone do |r|
+          if args.length == 1 && args.first.eql?(true) || args.first.eql?(false)
+            r.included_portals = args.first ? nil : []
+          else
+            r.included_portals ||= []
+            r.included_portals += args.flatten.map { |p| normalize_portal_param(p) }
+            r.included_portals.uniq!
+          end
+        end
+      end
+      alias includes portal
+      alias portals portal
+
+      # Same as calling `portal(true)`
+      #
+      # @return (see #portal)
+      def with_all_portals
+        portal(true)
+      end
+
+      # Same as calling `portal(false)`
+      #
+      # @return (see #portal)
+      def without_portals
+        portal(false)
+      end
+
+      def query(*params)
+        with_clone do |r|
+          r.query_params += params.flatten.map { |p| normalize_query_params(p) }
+        end
+      end
+
+      def omit(params)
+        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, or simply
+      # fetching the record by id if the primary key was set
+      #
+      # @return [FmRest::Spyke::Base]
+      def find_one
+        @find_one ||=
+          if primary_key_set?
+            without_collection_params { super }
+          else
+            klass.new_collection_from_result(limit(1).fetch).first
+          end
+      rescue ::Spyke::ConnectionError => error
+        fallback_or_reraise(error, default: nil)
+      end
+      alias_method :first, :find_one
+      alias_method :any, :find_one
+
+      # Yields each batch of records that was found by the find options.
+      #
+      # NOTE: By its nature, batch processing is subject to race conditions if
+      # other processes are modifying the database
+      #
+      # @param batch_size [Integer] Specifies the size of the batch.
+      # @return [Enumerator] if called without a block.
+      def find_in_batches(batch_size: 1000)
+        unless block_given?
+          return to_enum(:find_in_batches, batch_size: batch_size) do
+            total = limit(1).find_some.metadata.data_info.found_count
+            (total - 1).div(batch_size) + 1
+          end
+        end
+
+        offset = 1 # DAPI offset is 1-based
+
+        loop do
+          relation = offset(offset).limit(batch_size)
+
+          records = relation.find_some
+
+          yield records if records.length > 0
+
+          break if records.length < batch_size
+
+          # Save one iteration if the total is a multiple of batch_size
+          if found_count = records.metadata.data_info && records.metadata.data_info.found_count
+            break if found_count == (offset - 1) + batch_size
+          end
+
+          offset += batch_size
+        end
+      end
+
+      # Looping through a collection of records from the database (using the
+      # #all method, for example) is very inefficient since it will fetch and
+      # instantiate all the objects at once.
+      #
+      # In that case, batch processing methods allow you to work with the
+      # records in batches, thereby greatly reducing memory consumption and be
+      # lighter on the Data API server.
+      #
+      # The find_each method uses #find_in_batches with a batch size of 1000
+      # (or as specified by the :batch_size option).
+      #
+      # NOTE: By its nature, batch processing is subject to race conditions if
+      # other processes are modifying the database
+      #
+      # @param (see #find_in_batches)
+      # @example
+      #   Person.find_each do |person|
+      #     person.greet
+      #   end
+      #
+      #   Person.query(name: "==Mitch").find_each do |person|
+      #     person.say_hi
+      #   end
+      # @return (see #find_in_batches)
+      def find_each(batch_size: 1000)
+        unless block_given?
+          return to_enum(:find_each, batch_size: batch_size) do
+            limit(1).find_some.metadata.data_info.found_count
+          end
+        end
+
+        find_in_batches(batch_size: batch_size) do |records|
+          records.each { |r| yield r }
+        end
+      end
+
+      protected
+
+      def set_portal_params(params_hash, param)
+        # Copy portal_params so we're not modifying the same hash as the parent
+        # scope
+        self.portal_params = portal_params.dup
+
+        params_hash.each do |portal_name, value|
+          # TODO: Use a hash like { portal_name: { param: value } } instead so
+          # we can intelligently avoid including portal params for excluded
+          # portals
+          key = "#{param}.#{normalize_portal_param(portal_name)}"
+
+          # Delete key if value is falsy
+          if !value && portal_params.has_key?(key)
+            portal_params.delete(key)
+          else
+            self.portal_params[key] = value
+          end
+        end
+      end
+
+      private
+
+      def normalize_sort_param(param)
+        if param.kind_of?(Symbol) || param.kind_of?(String)
+          _, attr, descend = param.to_s.match(SORT_PARAM_MATCHER).to_a
+
+          unless field_name = klass.mapped_attributes[attr]
+            raise ArgumentError, "Unknown attribute `#{attr}' given to sort as #{param.inspect}. If you want to use a custom sort pass a hash in the Data API format"
+          end
+
+          hash = { fieldName: field_name }
+          hash[:sortOrder] = "descend" if descend
+          return hash
+        end
+
+        # TODO: Sanitize sort hash param for FM Data API conformity?
+        param
+      end
+
+      def normalize_portal_param(param)
+        if param.kind_of?(Symbol)
+          portal_key, = klass.portal_options.find { |_, opts| opts[:name].to_s == param.to_s }
+
+          unless portal_key
+            raise ArgumentError, "Unknown portal #{param.inspect}. If you want to include a portal not defined in the model pass it as a string instead"
+          end
+
+          return portal_key
+        end
+
+        param
+      end
+
+      def normalize_query_params(params)
+        params.each_with_object({}) do |(k, v), normalized|
+          if k == :omit || k == "omit"
+            # FM Data API wants omit values as strings, e.g. "true" or "false"
+            # rather than true/false
+            normalized["omit"] = v.to_s
+            next
+          end
+
+          # TODO: Raise ArgumentError if an attribute given as symbol isn't defiend
+          if k.kind_of?(Symbol) && klass.mapped_attributes.has_key?(k)
+            normalized[klass.mapped_attributes[k].to_s] = v
+          else
+            normalized[k.to_s] = v
+          end
+        end
+      end
+
+      def primary_key_set?
+        params[klass.primary_key].present?
+      end
+
+      def without_collection_params
+        orig_values = limit_value, offset_value, sort_params, query_params
+        self.limit_value = self.offset_value = self.sort_params = self.query_params = nil
+        yield
+      ensure
+        self.limit_value, self.offset_value, self.sort_params, self.query_params = orig_values
+      end
+
+      def with_clone
+        clone.tap do |relation|
+          yield relation
+        end
+      end
+    end
+  end
+end