fmrest 0.3.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0334b98968b68371d61a1f46c010937feb87bb5137b6e688c0096daf73b168a
-  data.tar.gz: c6585502bbb1a8005ea0f8a618c47d53b40b9412778a51e8154ab79393814ce5
+  metadata.gz: 7eb7073bb86836108750364857226e2ce6eaac9c88348c74b0c82ecb446f5d4e
+  data.tar.gz: 7e5d6bee538d00fce9feea4f0666014853fe4feba67ea11ff1841809a7d6c577
 SHA512:
-  metadata.gz: 433e6b05959fd64afbffddd2065df862449b3a3dcebe13780182b28bd6847f6263d4b2faffa3cef7d0a0f7949005ec1a1b9e8f7825129868bf49bd3833784ab5
-  data.tar.gz: 542d824f1cbb3c87722105a24b6bf2fdecd0d522a1a6d796d660a4c806ec83b356c50f400c9d37ce472cd2c4781ea1a50ecc533c361c4d6c02e19d47d625fb47
+  metadata.gz: 2e59d89d5829d94566be859060c10e88c875b3298bdd15dbc61b289df64b69534f3d294528b6b3a697b1583cf149472030fcc370eee97ddd0af0d03804520bec
+  data.tar.gz: 057a8bca299892de5d4415b2c67bec71a15778c8e80567726e44c9413bd7b75cf7d422bf86626b24a0021b2c5ca9eb7e43cf4eb486217e176133c19d3a509554

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## Changelog
 
+### 0.4.0
+
+* Implement ability to set limit and offset for portals
+* Implement disabling and requesting all portals
+
 ### 0.3.3
 
 * Fix encoding of paths for layouts with brackets in them (e.g. `"\[Very Ugly\]

data/README.md

@@ -447,22 +447,27 @@ passing arbitrary parameters to the REST backend. fmrest-ruby however is well
 aware of its backend API, so it extends Spkye models with a bunch of useful
 querying methods.
 
-```ruby
-class Honeybee < Spyke::Base
-  include FmRest::Spyke
+#### .limit
 
-  attributes name: "Bee Name", age: "Bee Age"
+`.limit` sets the limit for get and find request:
 
-  has_portal :hives, portal_key: "Bee Hives"
-end
+```ruby
+Honeybee.limit(10)
 ```
 
-#### .limit
+NOTE: You can also set a default limit value for a model class, see
+[Other notes on querying](#other-notes-on-querying).
 
-`.limit` sets the limit for get and find request:
+You can also use `.limit` to set limits on portals:
 
 ```ruby
-Honeybee.limit(10)
+Honeybee.limit(hives: 3, flowers: 2)
+```
+
+To remove the limit on a portal set it to `nil`:
+
+```ruby
+Honeybee.limit(flowers: nil)
 ```
 
 #### .offset
@@ -473,6 +478,18 @@ Honeybee.limit(10)
 Honeybee.offset(10)
 ```
 
+You can also use `.offset` to set offsets on portals:
+
+```ruby
+Honeybee.offset(hives: 3, flowers: 2)
+```
+
+To remove the offset on a portal set it to `nil`:
+
+```ruby
+Honeybee.offset(flowers: nil)
+```
+
 #### .sort
 
 `.sort` (or `.order`) sets sorting options for get and find requests:
@@ -490,16 +507,44 @@ Honeybee.sort(:name, :age!)
 Honeybee.sort(:name, :age__desc)
 ```
 
+NOTE: You can also set default sort values for a model class, see
+[Other notes on querying](#other-notes-on-querying).
+
 #### .portal
 
-`.portal` (or `.includes`) sets the portals to fetch for get and find requests
-(this recognizes portals defined with `has_portal`):
+`.portal` (aliased as `.includes` and `.portals`) sets which portals to fetch
+(if any) for get and find requests (this recognizes portals defined with
+`has_portal`):
 
 ```ruby
-Honeybee.portal(:hives)
+Honeybee.portal(:hives)   # include just the :hives portal
 Honeybee.includes(:hives) # alias method
+Honeybee.portals(:hives, :flowers) # alias for pluralization fundamentalists
+```
+
+Chaining calls to `.portal` will add portals to the existing included list:
+
+```ruby
+Honeybee.portal(:flowers).portal(:hives) # include both portals
+```
+
+If you want to disable portals for the scope call `.portal(false)`:
+
+```ruby
+Honeybee.portal(false) # disable portals for this scope
+```
+
+If you want to include all portals call `.portal(true)`:
+
+```ruby
+Honeybee.portal(true) # include all portals
 ```
 
+For convenience you can also use `.with_all_portals` and `.without_portals`,
+which behave just as calling `.portal(true)` and `portal(false)` respectively.
+
+NOTE: By default all portals are included.
+
 #### .query
 
 `.query` sets query conditions for a find request (and supports attributes as
@@ -553,8 +598,10 @@ Honeybee.limit(10).offset(20).sort(:name, :age!).portal(:hives).query(name: "Hut
 You can also set default values for limit and sort on the class:
 
 ```ruby
-Honeybee.default_limit = 1000
-Honeybee.default_sort = [:name, :age!]
+class Honeybee < FmRest::Spyke::Base
+  self.default_limit = 1000
+  self.default_sort = [:name, :age!]
+end
 ```
 
 Calling any `Enumerable` method on the resulting scope object will trigger a
@@ -672,7 +719,7 @@ end
 - [ ] Better/simpler-to-use core Ruby API
 - [ ] Better API documentation and README
 - [ ] Oauth support
-- [ ] Support for portal limit and offset
+- [x] Support for portal limit and offset
 - [x] More options for token storage
 - [x] Support for container fields
 - [x] Optional logging

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

@@ -17,7 +17,9 @@ module FmRest
 
         class_methods do
           # Methods delegated to FmRest::Spyke::Relation
-          delegate :limit, :offset, :sort, :query, :portal, to: :all
+          delegate :limit, :offset, :sort, :order, :query, :omit, :portal,
+                   :portals, :includes, :with_all_portals, :without_portals,
+                   to: :all
 
           def all
             # Use FmRest's Relation insdead of Spyke's vanilla one
@@ -66,9 +68,15 @@ module FmRest
                 prefixed ? scope.sort_params.to_json : scope.sort_params
             end
 
-            if scope.portal_params.present?
+            unless scope.included_portals.nil?
               where_options["portal"] =
-                prefixed ? scope.portal_params.to_json : scope.portal_params
+                prefixed ? scope.included_portals.to_json : scope.included_portals
+            end
+
+            if scope.portal_params.present?
+              scope.portal_params.each do |portal_param, value|
+                where_options["#{prefix}#{portal_param}"] = value
+              end
             end
 
             scope.where(where_options)

data/lib/fmrest/spyke/relation.rb

@@ -12,7 +12,7 @@ module FmRest
 
 
       attr_accessor :limit_value, :offset_value, :sort_params, :query_params,
-                    :portal_params
+                    :included_portals, :portal_params
 
       def initialize(*_args)
         super
@@ -24,20 +24,43 @@ module FmRest
         end
 
         @query_params = []
-        @portal_params = []
+
+        @included_portals = nil
+        @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 }
+      # @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 [Integer] the offset value
-      # @return [FmRest::Spyke::Relation] a new relation with the offset
+      # @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)
-        with_clone { |r| r.offset_value = value }
+      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
@@ -47,7 +70,7 @@ module FmRest
       #
       # @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
+      #   the FM Data API
       # @example
       #   Person.sort(:first_name, :age!)
       #   Person.sort(:first_name, :age__desc)
@@ -62,13 +85,45 @@ module FmRest
       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|
-          r.portal_params += args.flatten.map { |p| normalize_portal_param(p) }
-          r.portal_params.uniq!
+          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|
@@ -95,6 +150,28 @@ module FmRest
         fallback_or_reraise(error, default: nil)
       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)

data/lib/fmrest/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FmRest
-  VERSION = "0.3.3"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fmrest
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.4.0
 platform: ruby
 authors:
 - Pedro Carbajal
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-10-02 00:00:00.000000000 Z
+date: 2019-10-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday