json_api_model 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 89df9b9d8d8f4ae17c7bcd671f8f272b0339c5bc
-  data.tar.gz: 7db7eac6d7c3d4398fc3b912f23eed7f90c631f2
+  metadata.gz: b4309beecbe58dd95fe10e0aa45cfe3c9ab93710
+  data.tar.gz: 2cc02483222c4319429bd5539879cd8c20fe00d1
 SHA512:
-  metadata.gz: 0eb9b10ac0e5a56e2bb2307e7e2b9cde7fce35d2a409d34df9490e616a01902d801274032539db5062bfc62634a865ef7045276836972566671e43e657a0cab9
-  data.tar.gz: 03f7d39b4504ff47099aaec9fec4b9934f58cd31314a6ad1cd0712784c5b5f4e994332b477f00ebc06025147bfa07b4deb47d81b6b2977af559244b845691a75
+  metadata.gz: 137fd5629ae09611ef523a7092d4fe552900d78f189de0cc74d097f3b517144f81a556fbd54aa0d1768a7987617617a5751ce8baee4d8b1fcc18db5b77795502
+  data.tar.gz: f69d1952b0a22558d269e8549b40e1ed451e3df3c1c589541652cecb75c71c7ab45ecdff9eea550a53f3d4fd7ca2a5362462af2eeb17eb9395c0d286f2bd99be

data/Gemfile.lock

@@ -1,15 +1,16 @@
 PATH
   remote: .
   specs:
-    json_api_model (0.1.2)
+    json_api_model (0.3.0)
+      activesupport
       json_api_client
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activemodel (5.2.0)
-      activesupport (= 5.2.0)
-    activesupport (5.2.0)
+    activemodel (5.2.1)
+      activesupport (= 5.2.1)
+    activesupport (5.2.1)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 0.7, < 2)
       minitest (~> 5.1)
@@ -25,7 +26,7 @@ GEM
     faraday_middleware (0.12.2)
       faraday (>= 0.7.4, < 1.0)
     hashdiff (0.3.7)
-    i18n (1.0.1)
+    i18n (1.1.0)
       concurrent-ruby (~> 1.0)
     json (2.1.0)
     json_api_client (1.5.3)

data/README.md

@@ -31,6 +31,61 @@ Using the model wrappers is pretty straighforward. It thinly wraps `JsonApiClien
 
 Any instance or class(non-query) level method will fall thorugh to the client.
 
+### Associations
+
+You can define simple associations that behave very much like ActiveRecord associations. Once you define your association, you will have a method with that name that will do the lookups and cache the results for you.
+
+* `belongs_to association`: the base object has to have the association id
+  * will return a single object or nil
+* `has_one`: the assiociation object has the id of the base. 
+  * will return a single object or nil
+* `has_many`: the association object has the id of the base.
+  * will return an array
+
+#### Assocaition Options
+
+Associations have some of the standard ActiveRecord options. Namely:
+* `class`: specifies the class to find the record in.
+
+  ```ruby
+    has_one :special_thing, class: Thing
+  ```
+
+* `class_name`: specifies the class w.o having to have the class defined. Handy for circular dependencies
+
+  ```ruby
+    class Person < JsonApiModel::Model
+      wraps MyApi::Client::Person
+      has_one :nickname, class_name: "Pesudonym"
+    end
+
+    class Pseudonym < JsonApiModel::Model
+      wraps MyApi::Client::Pseudonym
+      belongs_to :bearer, class_name: "Person"
+    end
+  ```
+
+* `through`: many to may association helper.
+
+__NOTE__: Due to perf implications this is __only__ available for local classes (not things that come through the `relatinships` block in the payload). This will __*never ever*__ be available for remote models.
+
+```ruby
+  class Person < JsonApiModel::Model
+    wraps MyApi::Client::Person
+    has_many :person_foods
+    has_many :favorite_foods, through: :person_foods, class_name: "Food"
+  end
+
+  # locally stored models that respond to #{model_class}_id
+  class PersonFood < ActiveRecord::Base
+    belongs_to :person
+    belongs_to :food
+  end
+
+  class Food < ActiveRecord::Base
+  end
+```
+
 ### Example
 
 If you have an app that talks to a `user` service. Here's how your `User` model might look:
@@ -173,6 +228,10 @@ ActiveSupport::Notifications.subscribe "find.json_api_model" do |name, started,
 end
 ```
 
+## Known Issues
+
+* Due to an open issue in `JsonApiClient` scopes are modifiable, which means that `scope.where( params )` now permanently has those params in it. 
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/json_api_model.gemspec

@@ -20,6 +20,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  spec.add_dependency "activesupport"
   spec.add_dependency "json_api_client"
 
   spec.add_development_dependency "bundler", "~> 1.16"

data/lib/json_api_model.rb

@@ -2,6 +2,8 @@ require "json_api_model/version"
 
 module JsonApiModel
 
+  autoload :Associations, 'json_api_model/associations'
+  autoload :Associatable, 'json_api_model/associatable'
   autoload :Model,        'json_api_model/model'
   autoload :Instrumenter, 'json_api_model/instrumenter'
   autoload :ResultSet,    'json_api_model/result_set'

data/lib/json_api_model/associatable.rb

@@ -0,0 +1,70 @@
+module JsonApiModel
+  module Associatable
+    extend ActiveSupport::Concern
+
+    included do
+
+      class_attribute :__associations
+      self.__associations = {}
+
+      attr_accessor :__cached_associations
+
+      def has_relationship_ids?( name )
+        !!relationships[ name ]
+      end
+
+      def relationship_ids( name )
+        relationships_data = relationships[ name ]&.dig( :data )
+        case relationships_data
+        when Hash
+          [ relationships_data[ :id ] ]
+        when Array
+          relationships_data.map{ | datum | datum[ :id ] }
+        when NilClass
+          [ ]
+        else
+          raise "Unexpected relationship data type: #{relationships_data.class}"
+        end
+      end
+
+      class << self
+
+        def belongs_to( name, opts = {} )
+          process Associations::BelongsTo.new( self, name, opts )
+        end
+
+        def has_one( name, opts = {} )
+          process Associations::HasOne.new( self, name, opts )
+        end
+
+        def has_many( name, opts = {} )
+          process Associations::HasMany.new( self, name, opts )
+        end
+        
+        protected
+
+        def process( association )
+          associate association
+          methodize association
+        end
+
+        def associate( association )
+          self.__associations = __associations.merge association.name => association
+        end
+
+        def methodize( association )
+          define_method association.name do
+            self.__cached_associations ||= {}
+
+            unless self.__cached_associations.has_key? association.name
+              result = association.fetch( self )
+              
+              self.__cached_associations[association.name] = result
+            end
+            self.__cached_associations[association.name]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/json_api_model/associations.rb

@@ -0,0 +1,10 @@
+module JsonApiModel
+  module Associations
+    autoload :Base,       'json_api_model/associations/base'
+    autoload :BelongsTo,  'json_api_model/associations/belongs_to'
+    autoload :Flattable,  'json_api_model/associations/flattable'
+    autoload :Has,        'json_api_model/associations/has'
+    autoload :HasMany,    'json_api_model/associations/has_many'
+    autoload :HasOne,     'json_api_model/associations/has_one'
+  end
+end

data/lib/json_api_model/associations/base.rb

@@ -0,0 +1,65 @@
+module JsonApiModel
+  module Associations
+    class Base
+
+      attr_accessor :name, :opts, :key
+
+      def initialize( base_class, name, opts = {} )
+        self.name = name
+        self.opts = opts
+        self.key  = idify( base_class )
+
+        sanitize_opts( base_class )
+      end
+
+      def fetch( instance )
+        process klass.send( action, query( instance ) )
+      end
+
+      protected
+
+      def klass
+        @klass ||= association_class( name, opts )
+      end
+
+      def association_class( name, opts = {} )
+        a_class       = opts[:class]                   if opts.has_key? :class
+        a_class_name  = opts[:class_name].constantize  if opts.has_key? :class_name
+
+        a_class || a_class_name || derived_class_for( name )
+      end
+
+      def derived_class_for( name )
+        name.to_s.singularize.classify.constantize
+      end
+
+      def idify( class_name )
+        "#{class_name.to_s.demodulize.underscore}_id"
+      end
+
+      def supported_options
+        [ :class, :class_name ] + additional_options
+      end
+
+      def additional_options
+        []
+      end
+
+      def sanitize_opts( base_class )
+        if name.to_s == "object"
+          raise "#{base_class}: 'object_id' is a reserved keyword in ruby and cannot be overridden"
+        end
+        invalid_options = (opts.keys - supported_options)
+        if invalid_options.present?
+          list = invalid_options.map{|o|"'#{o}'"}.to_sentence
+          plural = invalid_options.count > 1
+          raise "#{base_class}: #{list} #{plural ? "are" : "is"} not supported."
+        end
+      end
+
+      def process( results )
+        results
+      end
+    end
+  end
+end

data/lib/json_api_model/associations/belongs_to.rb

@@ -0,0 +1,23 @@
+module JsonApiModel
+  module Associations
+    class BelongsTo < Base
+      include Flattable
+
+      def action
+        :find
+      end
+
+      def key
+        "#{name}_id"
+      end
+
+      def query( instance )
+        if instance.has_relationship_ids? name
+          { id: instance.relationship_ids( name ) }
+        else
+          instance.send key
+        end
+      end
+    end
+  end
+end

data/lib/json_api_model/associations/flattable.rb

@@ -0,0 +1,25 @@
+module JsonApiModel
+  module Associations
+    module Flattable
+      extend ActiveSupport::Concern
+
+      included do
+        def process( results )
+          if flattable? results
+            results.first
+          else
+            results
+          end
+        end
+
+        private
+
+        def flattable?( results )
+          results.is_a?( JsonApiModel::ResultSet ) ||
+          results.is_a?( Array ) ||
+          results.is_a?( JsonApiModel::Scope )
+        end
+      end
+    end
+  end
+end

data/lib/json_api_model/associations/has.rb

@@ -0,0 +1,46 @@
+module JsonApiModel
+  module Associations
+    class Has < Base
+      
+      def action
+        :where
+      end
+
+      def query( instance )
+        if instance.has_relationship_ids? name
+          { id: instance.relationship_ids( name ) }
+        elsif through?
+          { id: target_ids( instance ) }
+        else
+          { key => instance.id }
+        end
+      end
+
+      def additional_options
+        [ :through ]
+      end
+
+      protected
+
+      def through
+        opts[:through]
+      end
+
+      def through?
+        opts.has_key? :through
+      end
+
+      def target_ids( instance )
+        intermadiates = Array(instance.send( through ) )
+        
+        intermadiates.map do | intermediate | 
+          intermediate.send( through_key )
+        end
+      end
+      
+      def through_key
+        idify klass
+      end
+    end
+  end
+end

data/lib/json_api_model/associations/has_many.rb

@@ -0,0 +1,6 @@
+module JsonApiModel
+  module Associations
+    class HasMany < Has
+    end
+  end
+end

data/lib/json_api_model/associations/has_one.rb

@@ -0,0 +1,7 @@
+module JsonApiModel
+  module Associations
+    class HasOne < Has
+      include Flattable
+    end
+  end
+end

data/lib/json_api_model/model.rb

@@ -1,9 +1,7 @@
 module JsonApiModel
   class Model
     class << self
-      extend Forwardable
-
-      def_delegators :_new_scope, :where, :order, :includes, :select, :all, :paginate, :page, :with_params, :first, :find, :last
+      delegate :where, :order, :includes, :select, :all, :paginate, :page, :with_params, :first, :find, :last, to: :__new_scope
 
       attr_reader :client_class
       def wraps( client_class )
@@ -36,13 +34,16 @@ module JsonApiModel
 
       private
 
-      def _new_scope
+      def __new_scope
         Scope.new( self )
       end
     end
-
+    include Associatable
+    
     attr_accessor :client
 
+    delegate :as_json, to: :client
+
     def initialize( attributes = {} )
       @client = self.class.client_class.new( attributes )
     end
@@ -53,10 +54,6 @@ module JsonApiModel
       raise NoMethodError, "No method `#{m}' found in #{self} or #{client}"
     end
 
-    def as_json
-      client.as_json
-    end
-
     RESERVED_FIELDS = [ :type, :id ]
   end
 end

data/lib/json_api_model/scope.rb

@@ -3,33 +3,42 @@ module JsonApiModel
     def initialize( model_class )
       @model_class  = model_class
       @client_scope = JsonApiClient::Query::Builder.new( model_class.client_class )
+      @cache        = {}
     end
 
-    def to_a
-      @to_a ||= find
-    end
-
-    alias all to_a
-
-
     def find( args = {} )
       JsonApiModel.instrumenter.instrument 'find.json_api_model',
                                             args: args,
                                             url: url do
-        results = @client_scope.find args
-        ResultSet.new( results, @model_class )
+        cache_or_find args do
+          results = @client_scope.find args
+          ResultSet.new( results, @model_class )
+        end
       end
     end
 
+    alias to_a find
+    alias all find
+
     def first
       JsonApiModel.instrumenter.instrument 'first.json_api_model', url: url do
-        @model_class.new_from_client @client_scope.first
+        # if the non-first query has already been executed, there's no need to make the call again
+        if cached?
+          cache.first
+        else
+          cache_or_find :first do
+            @model_class.new_from_client @client_scope.first
+          end
+        end
       end
     end
 
     def last
       JsonApiModel.instrumenter.instrument 'last.json_api_model', url: url do
-        @model_class.new_from_client @client_scope.last
+        # this is a separate call always because the last record may exceed page size
+        cache_or_find :last do
+          @model_class.new_from_client @client_scope.last
+        end
       end
     end
 
@@ -48,6 +57,35 @@ module JsonApiModel
 
     private
 
+    def cached?
+      @cache.has_key? keyify
+    end
+
+    def cache
+      @cache[keyify]
+    end
+
+    # because a scope can be modified and then resolved, we want to cache by the full param set
+    def cache_or_find( opts = {} )
+      key = keyify( opts )
+      @cache.fetch key do |key|
+        @cache[key] = yield
+      end
+    end
+
+    def keyify( opts = {} )
+      params.merge( hashify( opts ) ).sort.to_s
+    end
+
+    def hashify( opts = {} )
+      case opts
+      when Hash
+        opts
+      else
+        { opt: opts }
+      end
+    end
+
     def url
       @model_class.client_class.requestor.send( :resource_path, params )
     end

data/lib/json_api_model/version.rb

@@ -1,3 +1,3 @@
 module JsonApiModel
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: json_api_model
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Greg Orlov
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-08-03 00:00:00.000000000 Z
+date: 2018-08-24 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: json_api_client
   requirement: !ruby/object:Gem::Requirement
@@ -113,6 +127,14 @@ files:
 - bin/setup
 - json_api_model.gemspec
 - lib/json_api_model.rb
+- lib/json_api_model/associatable.rb
+- lib/json_api_model/associations.rb
+- lib/json_api_model/associations/base.rb
+- lib/json_api_model/associations/belongs_to.rb
+- lib/json_api_model/associations/flattable.rb
+- lib/json_api_model/associations/has.rb
+- lib/json_api_model/associations/has_many.rb
+- lib/json_api_model/associations/has_one.rb
 - lib/json_api_model/instrumenter.rb
 - lib/json_api_model/instrumenter/null_instrumenter.rb
 - lib/json_api_model/model.rb