mara 0.1.0

data/lib/mara/configure.rb

@@ -0,0 +1,100 @@
+module Mara
+  ##
+  # Configure  Mara
+  #
+  # @param env [String] The default environment that is being configured.
+  #
+  #   If this block is called a second time, the previous env version will
+  #   be overridden
+  #
+  # @yield [config] The configuration object to set values on.
+  #
+  # @yieldparam config [ Mara::Configure] The configuration object.
+  # @yieldreturn [void]
+  #
+  # @return [void]
+  def self.configure(env)
+    instance = config
+    instance.send(:_set_env, env)
+    yield(instance)
+  end
+
+  ##
+  # @private
+  #
+  # The current config
+  def self.config
+    @config ||= Configure.new
+    @config
+  end
+
+  ##
+  # The configuration for  Mara
+  #
+  # @author Maddie Schipper
+  # @since 1.0.0
+  class Configure
+    ##
+    # DynamoDB specific config values.
+    #
+    # @!attribute [rw] table_name
+    #   The name of the DynamoDB table to use.
+    #
+    #   @note If this is not set, pretty much nothing will work.
+    #
+    #   @return [String, nil]
+    # @!attribute [rw] endpoint
+    #   The DynamoDB endpoint to use. If `nil` this will fallback to the
+    #   AWS default endpoint.
+    #
+    #   @return [String, nil]
+    DynamoConfig = Struct.new(:table_name, :endpoint)
+
+    ##
+    # Aws specific config values.
+    #
+    # @!attribute [rw] region
+    #   The region name to use for the Client.
+    #
+    #   @note By default this is `us-east-1`
+    #
+    #   @return [String]
+    AwsConfig = Struct.new(:region)
+
+    ##
+    # The current environment that  Mara is configured for.
+    #
+    # @return [String]
+    attr_reader :env
+
+    ##
+    # The Aws config
+    #
+    # @return [ Mara::Configure::AwsConfig]
+    attr_reader :aws
+
+    ##
+    # The DynamoDB config
+    #
+    # @return [ Mara::Configure::DynamoConfig]
+    attr_reader :dynamodb
+
+    ##
+    # @private
+    #
+    # Create a new instance.
+    #
+    # @note This should never be called directly by the client.
+    def initialize
+      @env = 'production'
+      @dynamodb = DynamoConfig.new(nil, nil)
+      @aws = AwsConfig.new('us-east-1')
+    end
+
+    private
+
+    def _set_env(env)
+      @env = env.to_s
+    end
+  end
+end

data/lib/mara/dynamo_helpers.rb

@@ -0,0 +1,34 @@
+module Mara
+  ##
+  # @private
+  #
+  # Helper methods for formatting data as it comes back from DynamoDB
+  module DynamoHelpers
+    def self.included(klass)
+      klass.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      ##
+      # Calculate all the consumed capacity in an array of capacity objects.
+      def calculate_consumed_capacity(consumed_capacity, table_name)
+        consumed = consumed_capacity.is_a?(Array) ? consumed_capacity : [consumed_capacity]
+
+        if table_name
+          consumed.select! { |cap| cap.table_name == table_name }
+        end
+
+        consumed.map! { |cap| _sum_capacity(cap) }
+        consumed.sum
+      end
+
+      ##
+      # @private
+      #
+      # Count the number of capcity unites in a capacity object.
+      def _sum_capacity(cap)
+        cap.capacity_units.to_f
+      end
+    end
+  end
+end

data/lib/mara/error.rb

@@ -0,0 +1,8 @@
+module Mara
+  ##
+  # The base error for any  Mara specific errors.
+  #
+  # @author Maddie Schipper
+  # @since 1.0.0
+  class Error < StandardError; end
+end

data/lib/mara/instrument.rb

@@ -0,0 +1,16 @@
+require 'active_support'
+
+module Mara
+  ##
+  # @private
+  #
+  # Convenience method for {ActiveSupport::Notifications} that also namespaces
+  #   the key.
+  #
+  # @param name [string] The name of the action being instrumented.
+  #
+  # @return [Object] The return value of the block
+  def self.instrument(name, *args, &block)
+    ActiveSupport::Notifications.instrument("mara.#{name}", *args, &block)
+  end
+end

data/lib/mara/model.rb

@@ -0,0 +1,13 @@
+require_relative 'model/base'
+
+module Mara
+  ##
+  # A  Mara Model.
+  #
+  # @see  Mara::Model::Base
+  #
+  # @author Maddie Schipper
+  # @since 1.0.0
+  module Model
+  end
+end

data/lib/mara/model/attributes.rb

@@ -0,0 +1,166 @@
+require_relative '../error'
+
+module Mara
+  module Model
+    ##
+    # Errors raised when trying to set a key.
+    #
+    # @author Maddie Schipper
+    # @since 1.0.0
+    class AttributeError <  Mara::Error; end
+
+    ##
+    # The container class for attributes.
+    #
+    # This should not be created directly. Instead use the Model convenience
+    # methods to have this setup automatically.
+    #
+    # @author Maddie Schipper
+    # @since 1.0.0
+    class Attributes
+      ##
+      # @private
+      #
+      # Create a new instance of attributes.
+      #
+      # @param default [Hash] The default attribute values to set.
+      def initialize(default)
+        @storage = {}
+        default.each { |k, v| set(k, v) }
+      end
+
+      ##
+      # @private
+      #
+      # Enumerate each key, value pair.
+      def each
+        return @storage.enum_for(:each) unless block_given?
+
+        @storage.each do |*args|
+          yield(*args)
+        end
+      end
+
+      ##
+      # Set a key, value pair on the attributes.
+      #
+      # @param key [#to_s] The key for the attribute you're trying to set.
+      #
+      #   This key will be normalized before being stored as an attribute.
+      #
+      # @param value [Any, nil] The value to set for the key.
+      #
+      # @param pre_formatted [true, false] If the key is already normalized.
+      #
+      # @note If the value is +nil+, the key will be deleted.
+      #
+      # @raise [AttributeError] The normalized value of the key can't be blank.
+      #
+      # @return [void]
+      def set(key, value, pre_formatted: false)
+        nkey = normalize_key(key, pre_formatted)
+
+        raise AttributeError, "Can't set an attribute without a key" if nkey.blank?
+
+        if value.nil?
+          @storage.delete(nkey)
+        else
+          @storage[nkey] = value
+        end
+      end
+
+      ##
+      # Get a value an attribute value.
+      #
+      # @param key [#to_s] The key for the attribute you're getting.
+      #
+      # @param pre_formatted [true, false] If the key is already normalized.
+      #
+      # @raise [AttributeError] The normalized value of the key can't be blank.
+      #
+      # @return [Any, nil]
+      def get(key, pre_formatted: false)
+        nkey = normalize_key(key, pre_formatted)
+
+        raise AttributeError, "Can't get an attribute without a key" if nkey.blank?
+
+        @storage[nkey]
+      end
+
+      ##
+      # Get an attribute value but it that value is nil, return the default
+      # passed as the second argument.
+      #
+      # @example Get a default value.
+      #   attrs.set('foo', nil)
+      #   attrs.fetch('foo', 'bar')
+      #   # => 'bar'
+      #
+      # @param key [#to_s] The key for the attribute you're getting.
+      #
+      # @param default [Any, nil] The default value to return if the value
+      #   for the key is nil.
+      #
+      # @param pre_formatted [true, false] If the key is already normalized.
+      #
+      # @return [Any, nil]
+      def fetch(key, default = nil, pre_formatted: false)
+        value = get(key, pre_formatted: pre_formatted)
+        return default if value.nil?
+
+        value
+      end
+
+      ##
+      # Check if a key exists.
+      #
+      # @param key [#to_s] The key you want to check to see if it exists.
+      #
+      # @param pre_formatted [true, false] If the key is already normalized.
+      #
+      # @return [true, false]
+      def key?(key, pre_formatted: false)
+        nkey = normalize_key(key, pre_formatted)
+        @storage.key?(nkey)
+      end
+
+      ##
+      # @private
+      #
+      # Dump the storage backend into a hash.
+      #
+      # @return [Hash<String, Any>]
+      def to_h
+        @storage.dup
+      end
+
+      ##
+      # @private
+      #
+      # Attribute Magic
+      def method_missing(name, *args, &_block)
+        if name.to_s.end_with?('=')
+          set(name.to_s.gsub(/=$/, ''), *args)
+        else
+          get(name, *args)
+        end
+      end
+
+      ##
+      # @private
+      #
+      # Attribute Magic
+      def respond_to_missing?(_name, _include_private = false)
+        true
+      end
+
+      private
+
+      def normalize_key(key, pre_formatted)
+        return key if pre_formatted == true
+
+        key.to_s.camelize
+      end
+    end
+  end
+end

data/lib/mara/model/base.rb

@@ -0,0 +1,225 @@
+require 'active_model'
+
+require_relative '../error'
+require_relative '../primary_key'
+
+require_relative 'dsl'
+require_relative 'query'
+require_relative 'persistence'
+require_relative 'attributes'
+
+module Mara
+  module Model
+    class PrimaryKeyError <  Mara::Error; end
+
+    ##
+    # The base class for a  Mara Model
+    #
+    # @example A basic Person class.
+    #   class Person <  Mara::Model::Base
+    #     # Set the Partition Key & Sort Key names.
+    #     primary_key 'PrimaryKey', 'RangeKey'
+    #   end
+    #
+    # @example Set dynamic attribute values.
+    #   person = Person.build
+    #   person[:first_name] = 'Maddie'
+    #   person.last_name = 'Schipper'
+    #
+    # @author Maddie Schipper
+    # @since 1.0.0
+    class Base
+      # @!parse extend  Mara::Model::Dsl::ClassMethods
+      # @!parse extend  Mara::Model::Query::ClassMethods
+      # @!parse extend  Mara::Model::Persistence::ClassMethods
+
+      include ActiveModel::Validations
+      include  Mara::Model::Dsl
+      include  Mara::Model::Query
+      include  Mara::Model::Persistence
+
+      ##
+      # @private
+      #
+      # The attributes container.
+      #
+      # @return [ Mara::Model::Attributes]
+      attr_reader :attributes
+
+      class << self
+        ##
+        # Create a new instance of the model.
+        #
+        # @example Building a new model.
+        #   person = Person.build(
+        #     partition_key: SecureRandom.uuid,
+        #     first_name: 'Maddie',
+        #     last_name: 'Schipper'
+        #   )
+        #
+        # @param attributes [Hash] The default attributes that can be assigned.
+        #
+        #   If a +partition_key+ is specified it will be used to set the model's
+        #   +partion_key+
+        #
+        #   If a +sort_key+ is specified it will be used to set the model's
+        #   +sort_key+
+        #
+        # @return [ Mara::Model::Base]
+        def build(attributes = {})
+          partition_key = attributes.delete(:partition_key)
+          sort_key = attributes.delete(:sort_key)
+
+          attrs =  Mara::Model::Attributes.new(attributes)
+
+          new(
+            partition_key: partition_key,
+            sort_key: sort_key,
+            attributes: attrs,
+            persisted: false
+          )
+        end
+
+        ##
+        # @private
+        def construct(record_hash)
+          partition_key = record_hash.delete(self.partition_key)
+          sort_key = record_hash.delete(self.sort_key)
+
+          attrs =  Mara::Model::Attributes.new(record_hash)
+
+          new(
+            partition_key: partition_key,
+            sort_key: sort_key,
+            attributes: attrs,
+            persisted: true
+          )
+        end
+      end
+
+      ##
+      # @private
+      #
+      # Create a new instance of the model.
+      #
+      # @param partition_key [Any] The partition_key for the model.
+      # @param sort_key [Any] The sort key for the model.
+      # @param attributes [ Mara::Model::Attributes] The already existing
+      #   attributes for the model.
+      def initialize(partition_key:, sort_key:, attributes:, persisted:)
+        if self.class.partition_key.blank?
+          raise  Mara::Model::PrimaryKeyError,
+                "Can't create instance of #{self.class.name} without a `partition_key` set."
+        end
+
+        unless attributes.is_a?( Mara::Model::Attributes)
+          raise ArgumentError, 'attributes is not  Mara::Model::Attributes'
+        end
+
+        @persisted = persisted == true
+        @attributes = attributes
+
+        self.partition_key = partition_key
+        self.sort_key = sort_key if sort_key
+      end
+
+      ##
+      # The partition_key key value for the object.
+      #
+      # @return [Any, nil]
+      attr_accessor :partition_key
+
+      ##
+      # Set an attribute key value pair.
+      #
+      # @param key [#to_s] The key for the attribute.
+      # @param value [Any, nil] The value of the attribute.
+      #
+      # @return [void]
+      def []=(key, value)
+        attributes.set(key, value)
+      end
+
+      ##
+      # Get an attribute's current value.
+      #
+      # @param key [#to_s] The key for the attribute.
+      #
+      # @return [Any, nil]
+      def [](key)
+        attributes.get(key)
+      end
+
+      def model_primary_key
+         Mara::PrimaryKey.new(model: self)
+      end
+
+      def model_identifier
+         Mara::PrimaryKey.generate(model_primary_key)
+      end
+
+      ##
+      # Fetch the current sort key value.
+      #
+      # @return [Any, nil]
+      def sort_key
+        if self.class.sort_key.blank?
+          raise  Mara::Model::PrimaryKeyError,
+                "Model #{self.class.name} does not specify a sort_key."
+        end
+
+        @sort_key
+      end
+
+      ##
+      # Checks if the model should have a sort key and returns the value if
+      # it does.
+      #
+      # @return [Any, nil]
+      def conditional_sort_key
+        return nil if self.class.sort_key.blank?
+
+        sort_key
+      end
+
+      ##
+      # Set a sort key value.
+      #
+      # @param sort_key [String] The sort key value.
+      #
+      # @return [void]
+      def sort_key=(sort_key)
+        if self.class.sort_key.blank?
+          raise  Mara::Model::PrimaryKeyError,
+                "Model #{self.class.name} does not specify a sort_key."
+        end
+
+        @sort_key = sort_key
+      end
+
+      ##
+      # @private
+      #
+      # Attribute Magic
+      def method_missing(name, *args, &block)
+        if attributes.respond_to?(name)
+          attributes.send(name, *args, &block)
+        else
+          super
+        end
+      end
+
+      ##
+      # @private
+      #
+      # Attribute Magic
+      def respond_to_missing?(name, include_private = false)
+        if attributes.respond_to?(name)
+          true
+        else
+          super
+        end
+      end
+    end
+  end
+end