fmrest 0.6.0 → 0.10.0

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module FmRest
+  module Spyke
+    module Model
+      module GlobalFields
+        extend ::ActiveSupport::Concern
+
+        FULLY_QUALIFIED_FIELD_NAME_MATCHER = /\A[^:]+::[^:]+\Z/.freeze
+
+        class_methods do
+          def set_globals(values_hash)
+            connection.patch(FmRest::V1.globals_path, {
+              globalFields: normalize_globals_hash(values_hash)
+            })
+          end
+
+          private
+
+          def normalize_globals_hash(hash)
+            hash.each_with_object({}) do |(k, v), normalized|
+              if v.kind_of?(Hash)
+                v.each do |k2, v2|
+                  normalized["#{k}::#{k2}"] = v2
+                end
+                next
+              end
+
+              unless FULLY_QUALIFIED_FIELD_NAME_MATCHER === k.to_s
+                raise ArgumentError, "global fields must be given in fully qualified format (table name::field name)"
+              end
+
+              normalized[k] = v
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -24,7 +24,8 @@ module FmRest
           # Methods delegated to FmRest::Spyke::Relation
           delegate :limit, :offset, :sort, :order, :query, :omit, :portal,
                    :portals, :includes, :with_all_portals, :without_portals,
-                   :script, to: :all
+                   :script, :find_one, :first, :any, :find_some,
+                   :find_in_batches, :find_each, to: :all
 
           def all
             # Use FmRest's Relation instead of Spyke's vanilla one

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

@@ -4,8 +4,8 @@ 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
+        FM_DATE_FORMAT = "%m/%d/%Y"
+        FM_DATETIME_FORMAT = "#{FM_DATE_FORMAT} %H:%M:%S"
 
         # Override Spyke's to_params to return FM Data API's expected JSON
         # format, and including only modified fields
@@ -63,9 +63,9 @@ module FmRest
         def serialize_values!(params)
           params.transform_values! do |value|
             case value
-            when DateTime, Time
-              value.strftime(FM_DATETIME_FORMAT)
-            when Date
+            when DateTime, Time, FmRest::StringDateTime
+              convert_datetime_timezone(value.to_datetime).strftime(FM_DATETIME_FORMAT)
+            when Date, FmRest::StringDate
               value.strftime(FM_DATE_FORMAT)
             else
               value
@@ -74,6 +74,17 @@ module FmRest
 
           params
         end
+
+        def convert_datetime_timezone(dt)
+          case fmrest_config.fetch(:timezone, nil)
+          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
       end
     end
   end

data/lib/fmrest/spyke/relation.rb

@@ -190,6 +190,79 @@ module FmRest
       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
 

data/lib/fmrest/spyke/{json_parser.rb → spyke_formatter.rb}

@@ -1,12 +1,24 @@
 # frozen_string_literal: true
 
 require "json"
+require "ostruct"
 
 module FmRest
   module Spyke
+    # Metadata class to be passed to Spyke::Collection#metadata
+    class Metadata < Struct.new(:messages, :script, :data_info)
+      alias_method :scripts, :script
+    end
+
+    class DataInfo < OpenStruct
+      def total_record_count; totalRecordCount; end
+      def found_count; foundCount; end
+      def returned_count; returnedCount; end
+    end
+
     # Response Faraday middleware for converting FM API's response JSON into
     # Spyke's expected format
-    class JsonParser < ::Faraday::Response::Middleware
+    class SpykeFormatter < ::Faraday::Response::Middleware
       SINGLE_RECORD_RE = %r(/records/\d+\z).freeze
       MULTIPLE_RECORDS_RE = %r(/records\z).freeze
       CONTAINER_RE = %r(/records/\d+/containers/[^/]+/\d+\z).freeze
@@ -24,7 +36,9 @@ module FmRest
 
       # @param env [Faraday::Env]
       def on_complete(env)
-        json = parse_json(env.body)
+        return unless env.body.is_a?(Hash)
+
+        json = env.body
 
         case
         when single_record_request?(env)
@@ -75,36 +89,61 @@ module FmRest
 
       # @param json [Hash]
       # @param include_errors [Boolean]
-      # @return [Hash] the skeleton structure for a Spyke-formatted response
+      # @return [FmRest::Spyke::Metadata] the skeleton structure for a
+      #   Spyke-formatted response
       def build_base_hash(json, include_errors = false)
         {
-          metadata: { messages: json[:messages] }.merge(script: prepare_script_results(json).presence),
-          errors:   include_errors ? prepare_errors(json) : {}
+          metadata: Metadata.new(
+            prepare_messages(json),
+            prepare_script_results(json),
+            prepare_data_info(json)
+          ).freeze,
+          errors: include_errors ? prepare_errors(json) : {}
         }
       end
 
       # @param json [Hash]
-      # @return [Hash] the script(s) execution results for Spyke metadata format
+      # @return [Array<OpenStruct>] the skeleton structure for a
+      #   Spyke-formatted response
+      def prepare_messages(json)
+        return [] unless json[:messages]
+        json[:messages].map { |m| OpenStruct.new(m).freeze }.freeze
+      end
+
+      # @param json [Hash]
+      # @return [OpenStruct] the script(s) execution results for Spyke metadata
+      #   format
       def prepare_script_results(json)
         results = {}
 
         [:prerequest, :presort].each do |s|
           if json[:response][:"scriptError.#{s}"]
-            results[s] = {
+            results[s] = OpenStruct.new(
               result: json[:response][:"scriptResult.#{s}"],
               error:  json[:response][:"scriptError.#{s}"]
-            }
+            ).freeze
           end
         end
 
         if json[:response][:scriptError]
-          results[:after] = {
+          results[:after] = OpenStruct.new(
             result: json[:response][:scriptResult],
             error:  json[:response][:scriptError]
-          }
+          ).freeze
         end
 
-        results
+        results.present? ? OpenStruct.new(results).freeze : nil
+      end
+
+      # @param json [Hash]
+      # @return [OpenStruct] the script(s) execution results for
+      #   Spyke metadata format
+      def prepare_data_info(json)
+        data_info = json[:response] && json[:response][:dataInfo]
+
+        return nil unless data_info.present?
+
+        DataInfo.new(data_info).freeze
       end
 
       # @param json [Hash]
@@ -229,12 +268,6 @@ module FmRest
       def execute_script_request?(env)
         env.method == :get && env.url.path.match(SCRIPT_REQUEST_RE)
       end
-
-      # @param source [String] a JSON string
-      # @return [Hash] the parsed JSON
-      def parse_json(source)
-        JSON.parse(source, symbolize_names: true)
-      end
     end
   end
 end

data/lib/fmrest/string_date.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "date"
+
+module FmRest
+  # Gotchas:
+  #
+  # 1.
+  #
+  #   Date === <StringDate instance> # => false
+  #
+  # The above can affect case conditions, as trying to match a StringDate
+  # with:
+  #
+  #   case obj
+  #   when Date
+  #     ...
+  #
+  # ...will not work.
+  #
+  # Instead one must specify the FmRest::StringDate class:
+  #
+  #   case obj
+  #   when Date, FmRest::StringDate
+  #     ...
+  #
+  # 2.
+  #
+  # StringDate#eql? only matches other strings, not dates.
+  #
+  # This could affect hash indexing when a StringDate is used as a key.
+  #
+  # TODO: Verify the above
+  #
+  # 3.
+  #
+  # StringDate#succ and StringDate#next return a String, despite Date#succ
+  # and Date#next also existing.
+  #
+  # Workaround: Use StringDate#next_day or strdate + 1
+  #
+  # 4.
+  #
+  # StringDate#to_s returns the original string, not the Date string
+  # representation.
+  #
+  # Workaround: Use strdate.to_date.to_s
+  #
+  # 5.
+  #
+  # StringDate#hash returns the hash for the string (important when using
+  # a StringDate as a hash key)
+  #
+  # 6.
+  #
+  # StringDate#as_json returns the string
+  #
+  # Workaround: Use strdate.to_date.as_json
+  #
+  # 7.
+  #
+  # Equality with Date is not reciprocal:
+  #
+  #   str_date == date #=> true
+  #   date == str_date #=> false
+  #
+  # NOTE: Potential workaround: Inherit StringDate from Date instead of String
+  #
+  # 8.
+  #
+  # Calling string transforming methods (e.g. .upcase) returns a StringDate
+  # instead of a String.
+  #
+  # NOTE: Potential workaround: Inherit StringDate from Date instead of String
+  #
+  class StringDate < String
+    DELEGATE_CLASS = ::Date
+
+    class InvalidDate < ArgumentError; end
+
+    class << self
+      def strptime(str, date_format, *_)
+        begin
+          date = self::DELEGATE_CLASS.strptime(str, date_format)
+        rescue ArgumentError
+          raise InvalidDate
+        end
+
+        new(str, date)
+      end
+    end
+
+    def initialize(str, date, **str_args)
+      raise ArgumentError, "str must be of class String" unless str.is_a?(String)
+      raise ArgumentError, "date must be of class #{self.class::DELEGATE_CLASS.name}" unless date.is_a?(self.class::DELEGATE_CLASS)
+
+      super(str, **str_args)
+
+      @delegate = date
+
+      freeze
+    end
+
+    def is_a?(klass)
+      klass == ::Date || super
+    end
+    alias_method :kind_of?, :is_a?
+
+    def to_date
+      @delegate
+    end
+
+    def to_datetime
+      @delegate.to_datetime
+    end
+
+    def to_time
+      @delegate.to_time
+    end
+
+    # ActiveSupport method
+    def in_time_zone(*_)
+      @delegate.in_time_zone(*_)
+    end
+
+    def inspect
+      "#<#{self.class.name} #{@delegate.inspect} - #{super}>"
+    end
+
+    def <=>(oth)
+      return @delegate <=> oth if oth.is_a?(::Date) || oth.is_a?(Numeric)
+      super
+    end
+
+    def +(val)
+      return @delegate + val if val.kind_of?(Numeric)
+      super
+    end
+
+    def <<(val)
+      return @delegate << val if val.kind_of?(Numeric)
+      super
+    end
+
+    def ==(oth)
+      return @delegate == oth if oth.kind_of?(::Date) || oth.kind_of?(Numeric)
+      super
+    end
+    alias_method :===, :==
+
+    def upto(oth, &blk)
+      return @delegate.upto(oth, &blk) if oth.kind_of?(::Date) || oth.kind_of?(Numeric)
+      super
+    end
+
+    def between?(a, b)
+      return @delegate.between?(a, b) if [a, b].any? {|o| o.is_a?(::Date) || o.is_a?(Numeric) }
+      super
+    end
+
+    private
+
+    def respond_to_missing?(name, include_private = false)
+      @delegate.respond_to?(name, include_private)
+    end
+
+    def method_missing(method, *args, &block)
+      @delegate.send(method, *args, &block)
+    end
+  end
+
+  class StringDateTime < StringDate
+    DELEGATE_CLASS = ::DateTime
+
+    def is_a?(klass)
+      klass == ::DateTime || super
+    end
+    alias_method :kind_of?, :is_a?
+
+    def to_date
+      @delegate.to_date
+    end
+
+    def to_datetime
+      @delegate
+    end
+  end
+
+  module StringDateAwareness
+    def _parse(v, *_)
+      if v.is_a?(StringDateTime)
+        return { year: v.year, mon: v.month, mday: v.mday, hour: v.hour, min: v.min, sec: v.sec, sec_fraction: v.sec_fraction, offset: v.offset }
+      end
+      if v.is_a?(StringDate)
+        return { year: v.year, mon: v.month, mday: v.mday }
+      end
+      super
+    end
+
+    def parse(v, *_)
+      if v.is_a?(StringDate)
+        return self == ::DateTime ? v.to_datetime : v.to_date
+      end
+      super
+    end
+
+    # Overriding case equality method so that it returns true for
+    # `FmRest::StringDate` instances
+    #
+    # Calls superclass method
+    #
+    def ===(other)
+      super || other.is_a?(StringDate)
+    end
+
+    def self.enable(classes: [Date, DateTime])
+      classes.each { |klass| klass.singleton_class.prepend(self) }
+    end
+  end
+end