acfs 1.3.3 → 1.6.0

data/lib/acfs/request.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'acfs/request/callbacks'
+
+module Acfs
+  # Encapsulate all data required to make up a request to the
+  # underlaying http library.
+  #
+  class Request
+    attr_accessor :body, :format
+    attr_reader :url, :headers, :params, :data, :method, :operation
+
+    include Request::Callbacks
+    def initialize(url, **options, &block)
+      @url = URI.parse(url.to_s).tap do |_url|
+        @data    = options.delete(:data) || nil
+        @format  = options.delete(:format) || :json
+        @headers = options.delete(:headers) || {}
+        @params  = options.delete(:params) || {}
+        @method  = options.delete(:method) || :get
+      end.to_s
+
+      @operation = options.delete(:operation) || nil
+
+      on_complete(&block) if block_given?
+    end
+
+    def data?
+      !data.nil?
+    end
+  end
+end

data/lib/acfs/request/callbacks.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Acfs
+  class Request
+    # Module containing callback handling for Requests.
+    # Current the only callback type is `on_complete`:
+    #
+    #   request = Request.new 'URL'
+    #   request.on_complete { |response| ... }
+    #
+    module Callbacks
+      # Add a new `on_complete` callback for this request.
+      #
+      # @example Set on_complete.
+      #   request.on_complete { |response| print response.body }
+      #
+      # @param [ Block ] block The callback block to execute.
+      #
+      # @yield [ Acfs::Response ]
+      #
+      # @return [ Acfs::Request ] The request itself.
+      #
+      def on_complete(&block)
+        callbacks.insert 0, block if block_given?
+        self
+      end
+
+      # Return array of all callbacks.
+      #
+      # @return [ Array<Block> ] All callbacks.
+      #
+      def callbacks
+        @callbacks ||= []
+      end
+
+      # Trigger all callback for given response.
+      #
+      # @return [ Acfs::Request ] The request itself.
+      #
+      def complete!(response)
+        call_callback response, 0
+        self
+      end
+
+      private
+
+      def call_callback(res, index)
+        return if index >= callbacks.size
+
+        callbacks[index].call(res, proc {|bres| call_callback bres, index + 1 })
+      end
+    end
+  end
+end

data/lib/acfs/resource.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'active_model'
+
+# @api public
+#
+class Acfs::Resource
+  require 'acfs/resource/initialization'
+  require 'acfs/resource/attributes'
+  require 'acfs/resource/dirty'
+  require 'acfs/resource/loadable'
+  require 'acfs/resource/locatable'
+  require 'acfs/resource/operational'
+  require 'acfs/resource/persistence'
+  require 'acfs/resource/query_methods'
+  require 'acfs/resource/service'
+  require 'acfs/resource/validation'
+
+  if ActiveModel::VERSION::MAJOR >= 4
+    include ActiveModel::Model
+  else
+    extend ActiveModel::Naming
+    extend ActiveModel::Translation
+    include ActiveModel::Conversion
+    include ActiveModel::Validations
+  end
+
+  include Initialization
+
+  include Attributes
+  include Loadable
+  include Persistence
+  include Locatable
+  include Operational
+  include QueryMethods
+  include Service
+  include Dirty
+  include Validation
+end

data/lib/acfs/resource/attributes.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+class Acfs::Resource
+  #
+  # = Acfs Attributes
+  #
+  # Allows to specify attributes of a class with default
+  # values and type safety.
+  #
+  # @example
+  #   class User < Acfs::Resource
+  #     attribute :name, :string, default: 'Anon'
+  #     attribute :age, :integer
+  #     attribute :special, My::Special::Type
+  #   end
+  #
+  # For each attribute a setter and getter will be created and values will be
+  # type casted when set.
+  #
+  module Attributes
+    extend ActiveSupport::Concern
+    include ActiveModel::AttributeMethods
+
+    # @api public
+    #
+    # Write default attributes defined in resource class.
+    #
+    # @see #write_attributes
+    # @see ClassMethods#attributes
+    #
+    def initialize(*attrs)
+      write_attributes self.class.attributes
+      reset_changes
+      super
+    end
+
+    # @api public
+    #
+    # Returns ActiveModel compatible list of attributes and values.
+    #
+    # @example
+    #   class User < Acfs::Resource
+    #     attribute :name, type: String, default: 'Anon'
+    #   end
+    #   user = User.new(name: 'John')
+    #   user.attributes # => { "name" => "John" }
+    #
+    # @return [HashWithIndifferentAccess{Symbol => Object}]
+    #   Attributes and their values.
+    #
+    # rubocop:disable Naming/MemoizedInstanceVariableName
+    def attributes
+      @_attrs ||= HashWithIndifferentAccess.new
+    end
+    # rubocop:enable Naming/MemoizedInstanceVariableName
+
+    # @api public
+    #
+    # Update all attributes with given hash. Attribute values will be casted
+    # to defined attribute type.
+    #
+    # @example
+    #   user.attributes = { :name => 'Adam' }
+    #   user.name # => 'Adam'
+    #
+    # @param [Hash{String, Symbol => Object}, #each{|key, value|}]
+    #   Attributes to set in resource.
+    # @see #write_attributes Delegates attributes hash to {#write_attributes}.
+    #
+    def attributes=(attributes)
+      write_attributes(attributes)
+    end
+
+    # @api public
+    #
+    # Read an attribute from instance variable.
+    #
+    # @param [Symbol, String] name Attribute name.
+    # @return [Object] Attribute value.
+    #
+    def read_attribute(name)
+      attributes[name.to_s]
+    end
+
+    # @api public
+    #
+    # Write a hash of attributes and values.
+    #
+    # If attribute value is a `Proc` it will be evaluated in the context
+    # of the resource after all non-proc attribute values are set. Values
+    # will be casted to defined attribute type.
+    #
+    # The behavior is used to apply default attributes from resource
+    # class definition.
+    #
+    # @example
+    #   user.write_attributes name: 'john', email: ->{ "#{name}@example.org" }
+    #   user.name  # => 'john'
+    #   user.email # => 'john@example.org'
+    #
+    # @param [Hash{String, Symbol => Object, Proc}, #each{|key, value|}]
+    #   Attributes to write.
+    #
+    # @see #write_attribute Delegates attribute values to `#write_attribute`.
+    #
+    def write_attributes(attributes, **opts)
+      unless attributes.respond_to?(:each) && attributes.respond_to?(:keys)
+        return false
+      end
+
+      if opts.fetch(:unknown, :ignore) == :raise &&
+         (attributes.keys.map(&:to_s) - self.class.attributes.keys).any?
+        missing = attributes.keys - self.class.attributes.keys
+        missing.map!(&:inspect)
+        raise ArgumentError.new "Unknown attributes: #{missing.join(', ')}"
+      end
+
+      procs = {}
+
+      attributes.each do |key, _|
+        if attributes[key].is_a? Proc
+          procs[key] = attributes[key]
+        else
+          write_local_attribute(key, attributes[key], **opts)
+        end
+      end
+
+      procs.each do |key, proc|
+        write_local_attribute(key, instance_exec(&proc), **opts)
+      end
+
+      true
+    end
+
+    # @api private
+    #
+    # Check if a public getter for attribute exists that should be called to
+    # write it or of {#write_attribute} should be called directly. This is
+    # necessary as {#write_attribute} should go though setters but can also
+    # handle unknown attribute that will not have a generated setter method.
+    #
+    def write_local_attribute(name, value, opts = {})
+      method = "#{name}="
+      if respond_to? method, true
+        public_send method, value
+      else
+        write_attribute name, value, opts
+      end
+    end
+
+    # @api public
+    #
+    # Write single attribute with given value. Value will be casted
+    # to defined attribute type.
+    #
+    # @param [String, Symbol] name Attribute name.
+    # @param [Object] value Value to write.
+    # @raise [ArgumentError] If no attribute with given name is defined.
+    #
+    def write_attribute(name, value, opts = {})
+      attr_type = self.class.defined_attributes[name.to_s]
+      if attr_type
+        write_raw_attribute name, attr_type.cast(value), opts
+      else
+        write_raw_attribute name, value, opts
+      end
+    end
+
+    # @api private
+    #
+    # Write an attribute without checking type or existence or casting
+    # value to attributes type. Value be stored in an instance variable
+    # named after attribute name.
+    #
+    # @param [String, Symbol] name Attribute name.
+    # @param [Object] value Attribute value.
+    #
+    def write_raw_attribute(name, value, _ = {})
+      attributes[name.to_s] = value
+    end
+
+    module ClassMethods
+      ATTR_CLASS_BASE = '::Acfs::Resource::Attributes'
+
+      #
+      # @api public
+      #
+      # Define a model attribute by name and type. Will create getter and
+      # setter for given attribute name. Existing methods will be overridden.
+      #
+      # Available types can be found in `Acfs::Model::Attributes::*`.
+      #
+      # @example
+      #   class User < Acfs::Resource
+      #     attribute :name, :string, default: 'Anon'
+      #     attribute :email, :string, default: lambda{ "#{name}@example.org"}
+      #   end
+      #
+      # @param [#to_sym] name Attribute name.
+      # @param [Symbol, String, Class] type Attribute
+      #   type identifier or type class.
+      #
+      def attribute(name, type, **opts)
+        if type.is_a?(Symbol) || type.is_a?(String)
+          type = "#{ATTR_CLASS_BASE}::#{type.to_s.classify}".constantize
+        end
+
+        define_attribute(name.to_sym, type, **opts)
+      end
+
+      # @api public
+      #
+      # Return list of possible attributes and default
+      # values for this model class.
+      #
+      # @example
+      #   class User < Acfs::Resource
+      #     attribute :name, :string
+      #     attribute :age, :integer, default: 25
+      #   end
+      #   User.attributes # => { "name": nil, "age": 25 }
+      #
+      # @return [Hash{String => Object, Proc}]
+      #   Attributes with default values.
+      #
+      def attributes
+        defined_attributes.each_with_object({}) do |(key, attr), hash|
+          hash[key] = attr.default_value
+        end
+      end
+
+      def defined_attributes
+        if superclass.respond_to?(:defined_attributes)
+          superclass.defined_attributes.merge(local_attributes)
+        else
+          local_attributes
+        end
+      end
+
+      private
+
+      def local_attributes
+        @local_attributes ||= {}
+      end
+
+      def define_attribute(name, type, **opts)
+        name      = name.to_s
+        attribute = type.new(**opts)
+
+        local_attributes[name] = attribute
+        define_attribute_method name
+
+        send :define_method, name do
+          read_attribute name
+        end
+
+        send :define_method, :"#{name}=" do |value|
+          write_attribute name, value
+        end
+      end
+    end
+  end
+end
+
+# Load attribute type classes.
+#
+Dir[File.join(__dir__, 'attributes/*.rb')].sort.each do |path|
+  filename = File.basename(path)
+  require "acfs/resource/attributes/#{filename}"
+end

data/lib/acfs/resource/attributes/base.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Acfs::Resource::Attributes
+  class Base
+    attr_reader :default
+
+    def initialize(default: nil)
+      @default = default
+    end
+
+    def cast(value)
+      cast_value(value) unless value.nil?
+    end
+
+    def default_value
+      if default.respond_to? :call
+        default
+      else
+        cast default
+      end
+    end
+
+    private
+
+    def cast_value(_value)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/acfs/resource/attributes/boolean.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Acfs::Resource::Attributes
+  # @api public
+  #
+  # Boolean attribute type. Use it in your model as an attribute type:
+  #
+  # @example
+  #   class User < Acfs::Resource
+  #     attribute :name, :boolean
+  #   end
+  #
+  # Given objects will be converted to string. The following strings
+  # are considered true, everything else false:
+  #
+  #  true, on, yes
+  #
+  class Boolean < Base
+    FALSE_VALUES = [false, 0, '0', 'f', 'F', 'false', 'FALSE', 'off', 'OFF', 'no', 'NO'].to_set
+
+    # @api public
+    #
+    # Cast given object to boolean.
+    #
+    # @param [Object] value Object to cast.
+    # @return [TrueClass, FalseClass] Casted boolean.
+    #
+    def cast_value(value)
+      return true if value == true
+      return false if value == false
+
+      if value.blank?
+        nil
+      else
+        !FALSE_VALUES.include?(value)
+      end
+    end
+  end
+end