wcc-contentful 0.2.2 → 0.3.0.pre.rc

data/lib/wcc/contentful/graphql.rb

@@ -1,4 +1,3 @@
-
 # frozen_string_literal: true
 
 gem 'graphql', '~> 1.7'

data/lib/wcc/contentful/graphql/types.rb

@@ -1,4 +1,3 @@
-
 # frozen_string_literal: true
 
 module WCC::Contentful::Graphql::Types
@@ -17,6 +16,7 @@ module WCC::Contentful::Graphql::Types
         return value if value.is_a? Array
         return value.to_h if value.respond_to?(:to_h)
         return JSON.parse(value) if value.is_a? String
+
         raise ArgumentError, "Cannot coerce value '#{value}' to a hash"
       }
     end

data/lib/wcc/contentful/helpers.rb

@@ -5,9 +5,9 @@ module WCC::Contentful::Helpers
 
   def content_type_from_raw(value)
     case value.dig('sys', 'type')
-    when 'Entry'
+    when 'Entry', 'DeletedEntry'
       value.dig('sys', 'contentType', 'sys', 'id')
-    when 'Asset'
+    when 'Asset', 'DeletedAsset'
       'Asset'
     else
       raise ArgumentError, "Unknown content type '#{value.dig('sys', 'type') || 'null'}'"
@@ -27,6 +27,7 @@ module WCC::Contentful::Helpers
 
   def content_type_from_constant(const)
     return const.content_type if const.respond_to?(:content_type)
+
     name = const.try(:name) || const.to_s
     name.demodulize.camelize(:lower)
   end

data/lib/wcc/contentful/indexed_representation.rb

@@ -15,6 +15,7 @@ module WCC::Contentful
 
     def []=(id, value)
       raise ArgumentError unless value.is_a?(ContentType)
+
       @types[id] = value
     end
 
@@ -39,6 +40,7 @@ module WCC::Contentful
     def ==(other)
       my_keys = keys
       return false unless my_keys == other.keys
+
       my_keys.all? { |k| self[k] == other[k] }
     end
 
@@ -54,6 +56,7 @@ module WCC::Contentful
       def initialize(hash_or_id = nil)
         @fields = {}
         return unless hash_or_id
+
         if hash_or_id.is_a?(String)
           @name = hash_or_id
           return
@@ -108,11 +111,13 @@ module WCC::Contentful
         unless TYPES.include?(raw_type)
           raise ArgumentError, "Unknown type #{raw_type}, expected one of: #{TYPES}"
         end
+
         @type = raw_type
       end
 
       def initialize(hash_or_id = nil)
         return unless hash_or_id
+
         if hash_or_id.is_a?(String)
           @name = hash_or_id
           return
@@ -128,6 +133,7 @@ module WCC::Contentful
           unless TYPES.include?(raw_type)
             raise ArgumentError, "Unknown type #{raw_type}, expected one of: #{TYPES}"
           end
+
           @type = raw_type
         end
 

data/lib/wcc/contentful/model.rb

@@ -1,23 +1,50 @@
-
 # frozen_string_literal: true
 
+# This is the top layer of the WCC::Contentful gem.  It exposes an API by which
+# you can query for data from Contentful.  The API is only accessible after calling
+# WCC::Contentful.init!
+#
+# The WCC::Contentful::Model class is the base class for all auto-generated model
+# classes.  A model class represents a content type inside Contentful.  For example,
+# the "page" content type is represented by a class named WCC::Contentful::Model::Page
+#
+# This WCC::Contentful::Model::Page class exposes the following API methods:
+# * {WCC::Contentful::ModelSingletonMethods#find Page.find(id)}
+#   finds a single Page by it's ID
+# * {WCC::Contentful::ModelSingletonMethods#find_by Page.find_by(field: <value>)}
+#   finds a single Page with the matching value for the specified field
+# * {WCC::Contentful::ModelSingletonMethods#find_all Page.find_all(field: <value>)}
+#   finds all instances of Page with the matching value for the specified field.
+#   It returns a lazy iterator of Page objects.
+#
+# The returned objects are instances of WCC::Contentful::Model::Page, or whatever
+# constant exists in the registry for the page content type.  You can register
+# custom types to be instantiated for each content type.  If a Model is subclassed,
+# the subclass is automatically registered.  This allows you to put models in your
+# app's `app/models` directory:
+#
+#    class Page < WCC::Contentful::Model::Page; end
+#
+# and then use the API via those models:
+#
+#    # this returns a ::Page, not a WCC::Contentful::Model::Page
+#    Page.find_by(slug: 'foo')
+#
+# Furthermore, anytime links are automatically resolved, the registered classes will
+# be used:
+#
+#    Menu.find_by(name: 'home').buttons.first.linked_page # is a ::Page
+#
+# @api Model
 class WCC::Contentful::Model
   extend WCC::Contentful::Helpers
-  extend WCC::Contentful::ModelValidators
 
   # The Model base class maintains a registry which is best expressed as a
   # class var.
   # rubocop:disable Style/ClassVars
 
   class << self
-    ##
-    # The configured store which executes all model queries against either the
-    # Contentful CDN or a locally-downloaded copy.
-    #
-    # See the {sync_store}[rdoc-ref:WCC::Contentful::Configuration.sync_store] parameter
-    # on the WCC::Contentful::Configuration class.
-    attr_accessor :store
-    attr_accessor :preview_store
+    include WCC::Contentful::ServiceAccessors
 
     def const_missing(name)
       raise WCC::Contentful::ContentTypeNotFoundError,
@@ -27,41 +54,48 @@ class WCC::Contentful::Model
 
   @@registry = {}
 
-  def self.all_models
-    # TODO: this needs to use the registry but it's OK for now cause we only
-    # use it in specs
-    WCC::Contentful::Model.constants(false).map { |k| WCC::Contentful::Model.const_get(k) }
-  end
-
-  ##
   # Finds an Entry or Asset by ID in the configured contentful space
   # and returns an initialized instance of the appropriate model type.
   #
-  # Makes use of the configured {store}[rdoc-ref:WCC::Contentful::Model.store]
+  # Makes use of the {WCC::Contentful::Services#store configured store}
   # to access the Contentful CDN.
   def self.find(id, context = nil)
     return unless raw = store.find(id)
 
+    new_from_raw(raw, context)
+  end
+
+  # Creates a new initialized instance of the appropriate model type for the
+  # given raw value.  The raw value must be the same format as returned from one
+  # of the stores for a given object.
+  def self.new_from_raw(raw, context = nil)
     content_type = content_type_from_raw(raw)
+    const = resolve_constant(content_type)
+    const.new(raw, context)
+  end
 
-    unless const = @@registry[content_type]
-      begin
-        # The app may have defined a model and we haven't loaded it yet
-        const = Object.const_missing(constant_from_content_type(content_type).to_s)
-      rescue NameError
-        nil
-      end
-    end
-    unless const
-      # Autoloading couldn't find their model - we'll register our own.
-      const = WCC::Contentful::Model.const_get(constant_from_content_type(content_type))
-      register_for_content_type(content_type, klass: const)
+  # Accepts a content type ID as a string and returns the Ruby constant
+  # stored in the registry that represents this content type.
+  def self.resolve_constant(content_type)
+    const = @@registry[content_type]
+    return const if const
+
+    const_name = constant_from_content_type(content_type).to_s
+    begin
+      # The app may have defined a model and we haven't loaded it yet
+      const = Object.const_missing(const_name)
+      return const if const && const < WCC::Contentful::Model
+    rescue NameError => e
+      raise e unless e.message =~ /uninitialized constant #{const_name}/
+
+      nil
     end
 
-    const.new(raw, context)
+    # Autoloading couldn't find their model - we'll register our own.
+    const = WCC::Contentful::Model.const_get(constant_from_content_type(content_type))
+    register_for_content_type(content_type, klass: const)
   end
 
-  ##
   # Registers a class constant to be instantiated when resolving an instance
   # of the given content type.  This automatically happens for the first subclass
   # of a generated model type, example:
@@ -82,19 +116,19 @@ class WCC::Contentful::Model
   def self.register_for_content_type(content_type = nil, klass: nil)
     klass ||= self
     raise ArgumentError, "#{klass} must be a class constant!" unless klass.respond_to?(:new)
+
     content_type ||= content_type_from_constant(klass)
 
     @@registry[content_type] = klass
   end
 
-  ##
   # Returns the current registry of content type names to constants.
   def self.registry
     return {} unless @@registry
+
     @@registry.dup.freeze
   end
 
-  ##
   # Checks if a content type has already been registered to a class and returns
   # that class.  If nil, the generated WCC::Contentful::Model::{content_type} class
   # will be resolved for this content type.

data/lib/wcc/contentful/model_builder.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative './sys'
+
 module WCC::Contentful
   class ModelBuilder
     include Helpers
@@ -22,11 +24,23 @@ module WCC::Contentful
 
       # TODO: https://github.com/dkubb/ice_nine ?
       typedef = typedef.deep_dup.freeze
-      fields = typedef.fields.keys
       WCC::Contentful::Model.const_set(const,
         Class.new(WCC::Contentful::Model) do
+          extend ModelSingletonMethods
+          include ModelMethods
           include Helpers
 
+          const_set('ATTRIBUTES', typedef.fields.keys.map(&:to_sym).freeze)
+          const_set('FIELDS', typedef.fields.keys.freeze)
+
+          # Magic type in their system which has a separate endpoint
+          # but we represent in the same model space
+          if const == 'Asset'
+            define_singleton_method(:type) { 'Asset' }
+          else
+            define_singleton_method(:type) { 'Entry' }
+          end
+
           define_singleton_method(:content_type) do
             typedef.content_type
           end
@@ -35,67 +49,45 @@ module WCC::Contentful
             typedef
           end
 
-          define_singleton_method(:find) do |id, context = nil|
-            raw = WCC::Contentful::Model.store.find(id)
-            new(raw, context) if raw.present?
-          end
-
-          define_singleton_method(:find_all) do |filter = nil, context = nil|
-            if filter
-              filter.transform_keys! { |k| k.to_s.camelize(:lower) }
-              bad_fields = filter.keys.reject { |k| fields.include?(k) }
-              raise ArgumentError, "These fields do not exist: #{bad_fields}" unless bad_fields.empty?
-            end
-
-            query = WCC::Contentful::Model.store.find_all(content_type: content_type)
-            query = query.apply(filter) if filter
-            query.map { |r| new(r, context) }
-          end
-
-          define_singleton_method(:find_by) do |filter, context = nil|
-            filter.transform_keys! { |k| k.to_s.camelize(:lower) }
-            bad_fields = filter.keys.reject { |k| fields.include?(k) }
-            raise ArgumentError, "These fields do not exist: #{bad_fields}" unless bad_fields.empty?
-
-            result =
-              if defined?(context[:preview]) && context[:preview] == true
-                WCC::Contentful::Model.preview_store.find_by(content_type: content_type, filter: filter)
-              else
-                WCC::Contentful::Model.store.find_by(content_type: content_type, filter: filter)
-              end
-
-            new(result, context) if result
-          end
-
-          define_singleton_method(:inherited) do |subclass|
-            # only register if it's not already registered
-            return if WCC::Contentful::Model.registered?(typedef.content_type)
-            WCC::Contentful::Model.register_for_content_type(typedef.content_type, klass: subclass)
-          end
-
           define_method(:initialize) do |raw, context = nil|
             ct = content_type_from_raw(raw)
             if ct != typedef.content_type
               raise ArgumentError, 'Wrong Content Type - ' \
                 "'#{raw.dig('sys', 'id')}' is a #{ct}, expected #{typedef.content_type}"
             end
-
-            @locale = context[:locale] if context.present?
-            @locale ||= 'en-US'
-            @id = raw.dig('sys', 'id')
-            @space = raw.dig('sys', 'space', 'sys', 'id')
-            @created_at = raw.dig('sys', 'createdAt')
-            @created_at = Time.parse(@created_at) if @created_at.present?
-            @updated_at = raw.dig('sys', 'updatedAt')
-            @updated_at = Time.parse(@updated_at) if @updated_at.present?
-            @revision = raw.dig('sys', 'revision')
+            @raw = raw.freeze
+
+            created_at = raw.dig('sys', 'createdAt')
+            created_at = Time.parse(created_at) if created_at.present?
+            updated_at = raw.dig('sys', 'updatedAt')
+            updated_at = Time.parse(updated_at) if updated_at.present?
+            @sys = WCC::Contentful::Sys.new(
+              raw.dig('sys', 'id'),
+              raw.dig('sys', 'type'),
+              raw.dig('sys', 'locale') || context.try(:[], :locale) || 'en-US',
+              raw.dig('sys', 'space', 'sys', 'id'),
+              created_at,
+              updated_at,
+              raw.dig('sys', 'revision'),
+              OpenStruct.new(context).freeze
+            )
 
             typedef.fields.each_value do |f|
-              raw_value = raw.dig('fields', f.name, @locale)
+              raw_value = raw.dig('fields', f.name, @sys.locale)
               if raw_value.present?
                 case f.type
-                when :DateTime
-                  raw_value = Time.parse(raw_value).localtime
+                # DateTime is intentionally not parsed!
+                #  a DateTime can be '2018-09-28', '2018-09-28T17:00:00', or '2018-09-28T17:00:00Z'
+                #  depending entirely on the editor interface in Contentful.  Trying to parse this
+                #  requires an assumption of the correct time zone to place them in.  At this point
+                #  in the code we don't have that knowledge, so we're punting to app-defined models.
+                #
+                #  As an example, a user enters '2018-09-28' into Contentful.  That date is parsed as
+                #  '2018-09-28T00:00:00Z' when system time is UTC (ex. on Heroku), but translating that
+                #  date to US Central results in '2018-09-27' which is not what the user intentded.
+                #
+                # when :DateTime
+                #   raw_value = Time.parse(raw_value).localtime
                 when :Int
                   raw_value = Integer(raw_value)
                 when :Float
@@ -109,11 +101,13 @@ module WCC::Contentful
             end
           end
 
-          attr_reader :id
-          attr_reader :space
-          attr_reader :created_at
-          attr_reader :updated_at
-          attr_reader :revision
+          attr_reader :sys
+          attr_reader :raw
+          delegate :id, to: :sys
+          delegate :created_at, to: :sys
+          delegate :updated_at, to: :sys
+          delegate :revision, to: :sys
+          delegate :space, to: :sys
 
           # Make a field for each column:
           typedef.fields.each_value do |f|
@@ -125,18 +119,21 @@ module WCC::Contentful
                 val = instance_variable_get(var_name + '_resolved')
                 return val if val.present?
 
-                return unless val = instance_variable_get(var_name)
-
-                val =
-                  if val.is_a? Array
-                    val.map { |v| WCC::Contentful::Model.find(v.dig('sys', 'id')) }
-                  else
-                    WCC::Contentful::Model.find(val.dig('sys', 'id'))
-                  end
+                _resolve_field(name)
+              end
 
-                instance_variable_set(var_name + '_resolved', val)
-                val
+              id_method_name = "#{name}_id"
+              if f.array
+                id_method_name = "#{name}_ids"
+                define_method(id_method_name) do
+                  instance_variable_get(var_name)&.map { |link| link.dig('sys', 'id') }
+                end
+              else
+                define_method(id_method_name) do
+                  instance_variable_get(var_name)&.dig('sys', 'id')
+                end
               end
+              alias_method id_method_name.underscore, id_method_name
             when :Coordinates
               define_method(name) do
                 val = instance_variable_get(var_name)
@@ -162,6 +159,7 @@ module WCC::Contentful
                 instance_variable_get(var_name)
               end
             end
+
             alias_method name.underscore, name
           end
         end)

data/lib/wcc/contentful/model_methods.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+# This module is included by all {WCC::Contentful::Model models} and defines instance
+# methods that are not dynamically generated.
+#
+# @api Model
+module WCC::Contentful::ModelMethods
+  # Resolves all links in an entry to the specified depth.
+  #
+  # Each link in the entry is recursively retrieved from the store until the given
+  # depth is satisfied.  Depth resolution is unlimited, circular references will
+  # be resolved to the same object.
+  #
+  # @param [Fixnum] depth how far to recursively resolve.  Must be >= 1
+  # @param [Array<String, Symbol>] fields (optional) A subset of fields whose
+  #   links should be resolved.  Defaults to all fields.
+  # @param [Hash] context passed to the resolved model's `new` function to provide
+  #   contextual information ex. current locale.
+  #   See {WCC::Contentful::ModelSingletonMethods#find Model#find}, {WCC::Contentful::Sys#context}
+  # @param [Hash] options The remaining optional parameters, defined below
+  # @option options [Symbol] circular_reference Determines how circular references are
+  #   handled.  `:raise` causes a {WCC::Contentful::CircularReferenceError} to be raised,
+  #   `:ignore` will cause the field to remain unresolved, and any other value (or nil)
+  #   will cause the field to point to the previously resolved ruby object for that ID.
+  def resolve(depth: 1, fields: nil, context: {}, **options)
+    raise ArgumentError, "Depth must be > 0 (was #{depth})" unless depth && depth > 0
+    return self if resolved?(depth: depth, fields: fields)
+
+    fields = fields.map { |f| f.to_s.camelize(:lower) } if fields.present?
+    fields ||= self.class::FIELDS
+
+    typedef = self.class.content_type_definition
+    links = fields.select { |f| %i[Asset Link].include?(typedef.fields[f].type) }
+
+    raw_links =
+      links.any? do |field_name|
+        raw_value = raw.dig('fields', field_name, sys.locale)
+        if raw_value&.is_a? Array
+          raw_value.any? { |v| v&.dig('sys', 'type') == 'Link' }
+        elsif raw_value
+          raw_value.dig('sys', 'type') == 'Link'
+        end
+      end
+    if raw_links
+      # use include param to do resolution
+      raw = self.class.store.find_by(content_type: self.class.content_type,
+                                     filter: { 'sys.id' => id },
+                                     options: { include: [depth, 10].min })
+      unless raw
+        raise WCC::Contentful::ResolveError, "Cannot find #{self.class.content_type} with ID #{id}"
+      end
+
+      @raw = raw.freeze
+      links.each { |f| instance_variable_set('@' + f, raw.dig('fields', f, sys.locale)) }
+    end
+
+    links.each { |f| _resolve_field(f, depth, context, options) }
+    self
+  end
+
+  # Determines whether the object has been resolved up to the prescribed depth.
+  def resolved?(depth: 1, fields: nil)
+    raise ArgumentError, "Depth must be > 0 (was #{depth})" unless depth && depth > 0
+
+    fields = fields.map { |f| f.to_s.camelize(:lower) } if fields.present?
+    fields ||= self.class::FIELDS
+
+    typedef = self.class.content_type_definition
+    links = fields.select { |f| %i[Asset Link].include?(typedef.fields[f].type) }
+    links.all? { |f| _resolved_field?(f, depth) }
+  end
+
+  # Turns the current model into a hash representation as though it had been retrieved from
+  # the Contentful API.
+  #
+  # This differs from `#raw` in that it recursively includes the `#to_h`
+  # of resolved links.  It also sets the fields to the value for the entry's `#sys.locale`,
+  # as though the entry had been retrieved from the API with `locale={#sys.locale}` rather
+  # than `locale=*`.
+  def to_h(stack = nil)
+    raise WCC::Contentful::CircularReferenceError.new(stack, id) if stack&.include?(id)
+
+    stack = [*stack, id]
+    typedef = self.class.content_type_definition
+    fields =
+      typedef.fields.each_with_object({}) do |(name, field_def), h|
+        if field_def.type == :Link || field_def.type == :Asset
+          if _resolved_field?(name, 0)
+            val = public_send(name)
+            val =
+              _try_map(val) { |v| v.to_h(stack) }
+          else
+            ids = field_def.array ? public_send("#{name}_ids") : public_send("#{name}_id")
+            val =
+              _try_map(ids) do |id|
+                {
+                  'sys' => {
+                    'type' => 'Link',
+                    'linkType' => field_def.type == :Asset ? 'Asset' : 'Entry',
+                    'id' => id
+                  }
+                }
+              end
+          end
+        else
+          val = public_send(name)
+          val = _try_map(val) { |v| v.respond_to?(:to_h) ? v.to_h.stringify_keys! : v }
+        end
+
+        h[name] = val
+      end
+
+    {
+      'sys' => { 'locale' => @sys.locale }.merge!(@raw['sys']),
+      'fields' => fields
+    }
+  end
+
+  delegate :to_json, to: :to_h
+
+  private
+
+  def _resolve_field(field_name, depth = 1, context = {}, options = {})
+    return if depth <= 0
+
+    var_name = '@' + field_name
+    return unless val = instance_variable_get(var_name)
+
+    context = sys.context.to_h.merge(context)
+    # load a single link from a raw link or entry, by either finding it via the API
+    # or instantiating it directly from a raw entry
+    load =
+      ->(raw) {
+        id = raw.dig('sys', 'id')
+        already_resolved = context[:backlinks]&.find { |m| m.id == id }
+
+        new_context = context.merge({ backlinks: [self, *context[:backlinks]].freeze })
+
+        if already_resolved && %i[ignore raise].include?(options[:circular_reference])
+          raise WCC::Contentful::CircularReferenceError.new(
+            new_context[:backlinks].map(&:id).reverse,
+            id
+          )
+        end
+
+        # Use the already resolved circular reference, or resolve a link, or
+        # instantiate from already resolved raw entry data.
+        m = already_resolved ||
+          if raw.dig('sys', 'type') == 'Link'
+            WCC::Contentful::Model.find(id, new_context)
+          else
+            WCC::Contentful::Model.new_from_raw(raw, new_context)
+          end
+
+        m.resolve(depth: depth - 1, context: new_context, **options) if m && depth > 1
+        m
+      }
+
+    begin
+      val = _try_map(val) { |v| load.call(v) }
+
+      instance_variable_set(var_name + '_resolved', val)
+    rescue WCC::Contentful::CircularReferenceError
+      raise unless options[:circular_reference] == :ignore
+    end
+  end
+
+  def _resolved_field?(field_name, depth = 1)
+    var_name = '@' + field_name
+    raw = instance_variable_get(var_name)
+    return true if raw.nil? || (raw.is_a?(Array) && raw.all?(&:nil?))
+    return false unless val = instance_variable_get(var_name + '_resolved')
+    return true if depth <= 1
+
+    return val.resolved?(depth: depth - 1) unless val.is_a? Array
+
+    val.all? { |i| i.nil? || i.resolved?(depth: depth - 1) }
+  end
+
+  def _try_map(val)
+    if val.is_a? Array
+      return val&.map do |item|
+        yield item unless item.nil?
+      end
+    end
+
+    yield val unless val.nil?
+  end
+end