fmrest 0.9.0 → 0.12.0

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

@@ -6,6 +6,10 @@ require "fmrest/spyke/validation_error"
 module FmRest
   module Spyke
     module Model
+      # This module adds and extends various ORM features in Spyke models,
+      # including custom query methods, remote script execution and
+      # exception-raising persistence methods.
+      #
       module Orm
         extend ::ActiveSupport::Concern
 
@@ -21,22 +25,25 @@ module FmRest
         end
 
         class_methods do
-          # Methods delegated to FmRest::Spyke::Relation
+          # Methods delegated to `FmRest::Spyke::Relation`
           delegate :limit, :offset, :sort, :order, :query, :omit, :portal,
                    :portals, :includes, :with_all_portals, :without_portals,
                    :script, :find_one, :first, :any, :find_some,
                    :find_in_batches, :find_each, to: :all
 
+          # Spyke override -- Use FmRest's Relation instead of Spyke's vanilla
+          # one
+          #
           def all
-            # Use FmRest's Relation instead of Spyke's vanilla one
             current_scope || Relation.new(self, uri: uri)
           end
 
-          # Extended fetch to allow properly setting limit, offset and other
+          # Spyke override -- allows properly setting limit, offset and other
           # options, as well as using the appropriate HTTP method/URL depending
-          # on whether there's a query present in the current scope, e.g.:
+          # on whether there's a query present in the current scope.
           #
-          #     Person.query(first_name: "Stefan").fetch # POST .../_find
+          # @example
+          #   Person.query(first_name: "Stefan").fetch # -> POST .../_find
           #
           def fetch
             if current_scope.has_query?
@@ -62,12 +69,21 @@ module FmRest
             self.current_scope = previous
           end
 
-          # API-error-raising version of #create
+          # Exception-raising version of `#create`
+          #
+          # @param attributes [Hash] the attributes to initialize the
+          #   record with
           #
           def create!(attributes = {})
             new(attributes).tap(&:save!)
           end
 
+          # Requests execution of a FileMaker script.
+          #
+          # @param script_name [String] the name of the FileMaker script to
+          #   execute
+          # @param param [String] an optional paramater for the script
+          #
           def execute_script(script_name, param: nil)
             params = {}
             params = {"script.param" => param} unless param.nil?
@@ -108,12 +124,20 @@ module FmRest
           end
         end
 
-        # Overwrite Spyke's save to provide a number of features:
+        # Spyke override -- Adds a number of features to original `#save`:
         #
         # * Validations
         # * Data API scripts execution
         # * Refresh of dirty attributes
         #
+        # @option options [String] :script the name of a FileMaker script to execute
+        #   upon saving
+        # @option options [Boolean] :raise_validation_errors whether to raise an
+        #   exception if validations fail
+        #
+        # @return [true] if saved successfully
+        # @return [false] if validations or persistence failed
+        #
         def save(options = {})
           callback = persisted? ? :update : :create
 
@@ -123,11 +147,34 @@ module FmRest
           true
         end
 
+        # Exception-raising version of `#save`.
+        #
+        # @option (see #save)
+        #
+        # @return [true] if saved successfully
+        #
+        # @raise if validations or presistence failed
+        #
         def save!(options = {})
           save(options.merge(raise_validation_errors: true))
         end
 
-        # Overwrite Spyke's destroy to provide Data API script execution
+        # Exception-raising version of `#update`.
+        #
+        # @param new_attributes [Hash] a hash of record attributes to update
+        #   the record with
+        #
+        # @option (see #save)
+        #
+        def update!(new_attributes, options = {})
+          self.attributes = new_attributes
+          save!(options)
+        end
+
+        # Spyke override -- Adds support for Data API script execution.
+        #
+        # @option options [String] :script the name of a FileMaker script to execute
+        #   upon deletion
         #
         def destroy(options = {})
           # For whatever reason the Data API wants the script params as query
@@ -142,22 +189,19 @@ module FmRest
           self.attributes = delete(uri.to_s + script_query_string)
         end
 
-        # API-error-raising version of #update
+        # (see #destroy)
+        #
+        # @option (see #destroy)
         #
-        def update!(new_attributes, options = {})
-          self.attributes = new_attributes
-          save!(options)
-        end
-
         def reload(options = {})
           scope = self.class
           scope = scope.script(options[:script]) if options.has_key?(:script)
-          reloaded = scope.find(id)
+          reloaded = scope.find(__record_id)
           self.attributes = reloaded.attributes
-          self.mod_id = reloaded.mod_id
+          self.__mod_id = reloaded.mod_id
         end
 
-        # ActiveModel 5+ implements this method, so we only needed if we're in
+        # ActiveModel 5+ implements this method, so we only need it if we're in
         # the older AM4
         if ActiveModel::VERSION::MAJOR == 4
           def validate!(context = nil)

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

@@ -0,0 +1,78 @@
+# 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_accessor :__record_id
+          alias_method :record_id, :__record_id
+          alias_method :id, :__record_id
+
+          # @return [Integer] the record's modId
+          attr_accessor :__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
+
+        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

@@ -4,11 +4,11 @@ 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
+        # Spyke override -- Return FM Data API's expected JSON format,
+        # including only modified fields.
         #
         def to_params
           params = {
@@ -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_classes
+              convert_datetime_timezone(value.to_datetime).strftime(FM_DATETIME_FORMAT)
+            when *date_classes
               value.strftime(FM_DATE_FORMAT)
             else
               value
@@ -74,6 +74,25 @@ module FmRest
 
           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

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

@@ -3,7 +3,7 @@
 module FmRest
   module Spyke
     module Model
-      module Uri
+      module URI
         extend ::ActiveSupport::Concern
 
         class_methods do
@@ -14,13 +14,12 @@ module FmRest
             @layout ||= model_name.name
           end
 
-          # Extend uri acccessor to default to FM Data schema
+          # 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) + "(/:id)"
+              return FmRest::V1.record_path(layout) + "(/:#{primary_key})"
             end
-
             super
           end
         end

data/lib/fmrest/spyke/spyke_formatter.rb

@@ -63,8 +63,8 @@ module FmRest
         response = json[:response]
 
         data = {}
-        data[:mod_id] = response[:modId] if response[:modId]
-        data[:id]     = response[:recordId].to_i if response[:recordId]
+        data[:__mod_id] = response[:modId] if response[:modId]
+        data[:__record_id] = response[:recordId].to_i if response[:recordId]
 
         build_base_hash(json, true).merge!(data: data)
       end
@@ -188,7 +188,7 @@ module FmRest
       # @param json_data [Hash]
       # @return [Hash] the record data in Spyke format
       def prepare_record_data(json_data)
-        out = { id: json_data[:recordId].to_i, mod_id: json_data[:modId] }
+        out = { __record_id: json_data[:recordId].to_i, __mod_id: json_data[:modId] }
         out.merge!(json_data[:fieldData])
         out.merge!(prepare_portal_data(json_data[:portalData])) if json_data[:portalData]
         out
@@ -213,8 +213,8 @@ module FmRest
 
           out[portal_name] =
             portal_records.map do |portal_fields|
-              attributes = { id: portal_fields[:recordId].to_i }
-              attributes[:mod_id] = portal_fields[:modId] if portal_fields[:modId]
+              attributes = { __record_id: portal_fields[:recordId].to_i }
+              attributes[:__mod_id] = portal_fields[:modId] if portal_fields[:modId]
 
               prefix = portal_options[:attribute_prefix] || portal_name
               prefix_matcher = /\A#{prefix}::/

data/lib/fmrest/string_date.rb

@@ -79,17 +79,24 @@ module FmRest
     class InvalidDate < ArgumentError; end
 
     class << self
-      alias_method :strptime, :new
+      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_format, **str_args)
+    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)
 
-      begin
-        @delegate = self.class::DELEGATE_CLASS.strptime(str, date_format)
-      rescue ArgumentError
-        raise InvalidDate
-      end
+      @delegate = date
 
       freeze
     end
@@ -178,4 +185,36 @@ module FmRest
       @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

data/lib/fmrest/token_store.rb

@@ -2,5 +2,11 @@
 
 module FmRest
   module TokenStore
+    autoload :Base,         "fmrest/token_store/base"
+    autoload :Memory,       "fmrest/token_store/memory"
+    autoload :Null,         "fmrest/token_store/null"
+    autoload :ActiveRecord, "fmrest/token_store/active_record"
+    autoload :Moneta,       "fmrest/token_store/moneta"
+    autoload :Redis,        "fmrest/token_store/redis"
   end
 end

data/lib/fmrest/token_store/base.rb

@@ -10,15 +10,15 @@ module FmRest
       end
 
       def load(key)
-        raise "Not implemented"
+        raise NotImplementedError
       end
 
       def store(key, value)
-        raise "Not implemented"
+        raise NotImplementedError
       end
 
       def delete(key)
-        raise "Not implemented"
+        raise NotImplementedError
       end
     end
   end

data/lib/fmrest/token_store/null.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+module FmRest
+  module TokenStore
+    module Null < Base
+      include Singleton
+
+      def delete(key)
+      end
+
+      def load(key)
+      end
+
+      def store(key, value)
+      end
+    end
+  end
+end