tallty_duck_record 1.0.0

data/lib/duck_record/attribute_set/yaml_encoder.rb

@@ -0,0 +1,41 @@
+module DuckRecord
+  class AttributeSet
+    # Attempts to do more intelligent YAML dumping of an
+    # DuckRecord::AttributeSet to reduce the size of the resulting string
+    class YAMLEncoder # :nodoc:
+      def initialize(default_types)
+        @default_types = default_types
+      end
+
+      def encode(attribute_set, coder)
+        coder["concise_attributes"] = attribute_set.each_value.map do |attr|
+          if attr.type.equal?(default_types[attr.name])
+            attr.with_type(nil)
+          else
+            attr
+          end
+        end
+      end
+
+      def decode(coder)
+        if coder["attributes"]
+          coder["attributes"]
+        else
+          attributes_hash = Hash[coder["concise_attributes"].map do |attr|
+            if attr.type.nil?
+              attr = attr.with_type(default_types[attr.name])
+            end
+            [attr.name, attr]
+          end]
+          AttributeSet.new(attributes_hash)
+        end
+      end
+
+      # TODO Change this to private once we've dropped Ruby 2.2 support.
+      # Workaround for Ruby 2.2 'private attribute?' warning.
+      protected
+
+        attr_reader :default_types
+    end
+  end
+end

data/lib/duck_record/attributes.rb

@@ -0,0 +1,262 @@
+require "duck_record/attribute/user_provided_default"
+
+module DuckRecord
+  # See DuckRecord::Attributes::ClassMethods for documentation
+  module Attributes
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :attributes_to_define_after_schema_loads, instance_accessor: false # :internal:
+      self.attributes_to_define_after_schema_loads = {}
+    end
+
+    module ClassMethods
+      # Defines an attribute with a type on this model. It will override the
+      # type of existing attributes if needed. This allows control over how
+      # values are converted to and from SQL when assigned to a model. It also
+      # changes the behavior of values passed to
+      # {DuckRecord::Base.where}[rdoc-ref:QueryMethods#where]. This will let you use
+      # your domain objects across much of Active Record, without having to
+      # rely on implementation details or monkey patching.
+      #
+      # +name+ The name of the methods to define attribute methods for, and the
+      # column which this will persist to.
+      #
+      # +cast_type+ A symbol such as +:string+ or +:integer+, or a type object
+      # to be used for this attribute. See the examples below for more
+      # information about providing custom type objects.
+      #
+      # ==== Options
+      #
+      # The following options are accepted:
+      #
+      # +default+ The default value to use when no value is provided. If this option
+      # is not passed, the previous default value (if any) will be used.
+      # Otherwise, the default will be +nil+.
+      #
+      # +array+ (PostgreSQL only) specifies that the type should be an array (see the
+      # examples below).
+      #
+      # +range+ (PostgreSQL only) specifies that the type should be a range (see the
+      # examples below).
+      #
+      # ==== Examples
+      #
+      # The type detected by Active Record can be overridden.
+      #
+      #   # db/schema.rb
+      #   create_table :store_listings, force: true do |t|
+      #     t.decimal :price_in_cents
+      #   end
+      #
+      #   # app/models/store_listing.rb
+      #   class StoreListing < DuckRecord::Base
+      #   end
+      #
+      #   store_listing = StoreListing.new(price_in_cents: '10.1')
+      #
+      #   # before
+      #   store_listing.price_in_cents # => BigDecimal.new(10.1)
+      #
+      #   class StoreListing < DuckRecord::Base
+      #     attribute :price_in_cents, :integer
+      #   end
+      #
+      #   # after
+      #   store_listing.price_in_cents # => 10
+      #
+      # A default can also be provided.
+      #
+      #   # db/schema.rb
+      #   create_table :store_listings, force: true do |t|
+      #     t.string :my_string, default: "original default"
+      #   end
+      #
+      #   StoreListing.new.my_string # => "original default"
+      #
+      #   # app/models/store_listing.rb
+      #   class StoreListing < DuckRecord::Base
+      #     attribute :my_string, :string, default: "new default"
+      #   end
+      #
+      #   StoreListing.new.my_string # => "new default"
+      #
+      #   class Product < DuckRecord::Base
+      #     attribute :my_default_proc, :datetime, default: -> { Time.now }
+      #   end
+      #
+      #   Product.new.my_default_proc # => 2015-05-30 11:04:48 -0600
+      #   sleep 1
+      #   Product.new.my_default_proc # => 2015-05-30 11:04:49 -0600
+      #
+      # \Attributes do not need to be backed by a database column.
+      #
+      #   # app/models/my_model.rb
+      #   class MyModel < DuckRecord::Base
+      #     attribute :my_string, :string
+      #     attribute :my_int_array, :integer, array: true
+      #     attribute :my_float_range, :float, range: true
+      #   end
+      #
+      #   model = MyModel.new(
+      #     my_string: "string",
+      #     my_int_array: ["1", "2", "3"],
+      #     my_float_range: "[1,3.5]",
+      #   )
+      #   model.attributes
+      #   # =>
+      #     {
+      #       my_string: "string",
+      #       my_int_array: [1, 2, 3],
+      #       my_float_range: 1.0..3.5
+      #     }
+      #
+      # ==== Creating Custom Types
+      #
+      # Users may also define their own custom types, as long as they respond
+      # to the methods defined on the value type. The method +deserialize+ or
+      # +cast+ will be called on your type object, with raw input from the
+      # database or from your controllers. See ActiveModel::Type::Value for the
+      # expected API. It is recommended that your type objects inherit from an
+      # existing type, or from DuckRecord::Type::Value
+      #
+      #   class MoneyType < DuckRecord::Type::Integer
+      #     def cast(value)
+      #       if !value.kind_of?(Numeric) && value.include?('$')
+      #         price_in_dollars = value.gsub(/\$/, '').to_f
+      #         super(price_in_dollars * 100)
+      #       else
+      #         super
+      #       end
+      #     end
+      #   end
+      #
+      #   # config/initializers/types.rb
+      #   DuckRecord::Type.register(:money, MoneyType)
+      #
+      #   # app/models/store_listing.rb
+      #   class StoreListing < DuckRecord::Base
+      #     attribute :price_in_cents, :money
+      #   end
+      #
+      #   store_listing = StoreListing.new(price_in_cents: '$10.00')
+      #   store_listing.price_in_cents # => 1000
+      #
+      # For more details on creating custom types, see the documentation for
+      # ActiveModel::Type::Value. For more details on registering your types
+      # to be referenced by a symbol, see DuckRecord::Type.register. You can
+      # also pass a type object directly, in place of a symbol.
+      #
+      # ==== \Querying
+      #
+      # When {DuckRecord::Base.where}[rdoc-ref:QueryMethods#where] is called, it will
+      # use the type defined by the model class to convert the value to SQL,
+      # calling +serialize+ on your type object. For example:
+      #
+      #   class Money < Struct.new(:amount, :currency)
+      #   end
+      #
+      #   class MoneyType < Type::Value
+      #     def initialize(currency_converter:)
+      #       @currency_converter = currency_converter
+      #     end
+      #
+      #     # value will be the result of +deserialize+ or
+      #     # +cast+. Assumed to be an instance of +Money+ in
+      #     # this case.
+      #     def serialize(value)
+      #       value_in_bitcoins = @currency_converter.convert_to_bitcoins(value)
+      #       value_in_bitcoins.amount
+      #     end
+      #   end
+      #
+      #   # config/initializers/types.rb
+      #   DuckRecord::Type.register(:money, MoneyType)
+      #
+      #   # app/models/product.rb
+      #   class Product < DuckRecord::Base
+      #     currency_converter = ConversionRatesFromTheInternet.new
+      #     attribute :price_in_bitcoins, :money, currency_converter: currency_converter
+      #   end
+      #
+      #   Product.where(price_in_bitcoins: Money.new(5, "USD"))
+      #   # => SELECT * FROM products WHERE price_in_bitcoins = 0.02230
+      #
+      #   Product.where(price_in_bitcoins: Money.new(5, "GBP"))
+      #   # => SELECT * FROM products WHERE price_in_bitcoins = 0.03412
+      #
+      # ==== Dirty Tracking
+      #
+      # The type of an attribute is given the opportunity to change how dirty
+      # tracking is performed. The methods +changed?+ and +changed_in_place?+
+      # will be called from ActiveModel::Dirty. See the documentation for those
+      # methods in ActiveModel::Type::Value for more details.
+      def attribute(name, cast_type = Type::Value.new, **options)
+        name = name.to_s
+        reload_schema_from_cache
+
+        self.attributes_to_define_after_schema_loads =
+          attributes_to_define_after_schema_loads.merge(
+            name => [cast_type, options]
+          )
+      end
+
+      # This is the low level API which sits beneath +attribute+. It only
+      # accepts type objects, and will do its work immediately instead of
+      # waiting for the schema to load. Automatic schema detection and
+      # ClassMethods#attribute both call this under the hood. While this method
+      # is provided so it can be used by plugin authors, application code
+      # should probably use ClassMethods#attribute.
+      #
+      # +name+ The name of the attribute being defined. Expected to be a +String+.
+      #
+      # +cast_type+ The type object to use for this attribute.
+      #
+      # +default+ The default value to use when no value is provided. If this option
+      # is not passed, the previous default value (if any) will be used.
+      # Otherwise, the default will be +nil+. A proc can also be passed, and
+      # will be called once each time a new value is needed.
+      #
+      # +user_provided_default+ Whether the default value should be cast using
+      # +cast+ or +deserialize+.
+      def define_attribute(
+        name,
+        cast_type,
+        default: NO_DEFAULT_PROVIDED
+      )
+        attribute_types[name] = cast_type
+        define_default_attribute(name, default, cast_type)
+      end
+
+      def load_schema! # :nodoc:
+        super
+        attributes_to_define_after_schema_loads.each do |name, (type, options)|
+          if type.is_a?(Symbol)
+            type = DuckRecord::Type.lookup(type, **options.except(:default))
+          end
+
+          define_attribute(name, type, **options.slice(:default))
+        end
+      end
+
+      private
+
+        NO_DEFAULT_PROVIDED = Object.new # :nodoc:
+        private_constant :NO_DEFAULT_PROVIDED
+
+        def define_default_attribute(name, value, type)
+          if value == NO_DEFAULT_PROVIDED
+            default_attribute = _default_attributes[name].with_type(type)
+          else
+            default_attribute = Attribute::UserProvidedDefault.new(
+              name,
+              value,
+              type,
+              _default_attributes.fetch(name.to_s) { nil },
+            )
+          end
+          _default_attributes[name] = default_attribute
+        end
+    end
+  end
+end

data/lib/duck_record/base.rb

@@ -0,0 +1,300 @@
+require "yaml"
+require "active_support/benchmarkable"
+require "active_support/dependencies"
+require "active_support/descendants_tracker"
+require "active_support/time"
+require "active_support/core_ext/module/attribute_accessors"
+require "active_support/core_ext/array/extract_options"
+require "active_support/core_ext/hash/deep_merge"
+require "active_support/core_ext/hash/slice"
+require "active_support/core_ext/hash/transform_values"
+require "active_support/core_ext/string/behavior"
+require "active_support/core_ext/kernel/singleton_class"
+require "active_support/core_ext/module/introspection"
+require "active_support/core_ext/object/duplicable"
+require "active_support/core_ext/class/subclasses"
+require "duck_record/define_callbacks"
+require "duck_record/errors"
+require "duck_record/attributes"
+
+module DuckRecord #:nodoc:
+  # = Active Record
+  #
+  # Active Record objects don't specify their attributes directly, but rather infer them from
+  # the table definition with which they're linked. Adding, removing, and changing attributes
+  # and their type is done directly in the database. Any change is instantly reflected in the
+  # Active Record objects. The mapping that binds a given Active Record class to a certain
+  # database table will happen automatically in most common cases, but can be overwritten for the uncommon ones.
+  #
+  # See the mapping rules in table_name and the full example in link:files/activerecord/README_rdoc.html for more insight.
+  #
+  # == Creation
+  #
+  # Active Records accept constructor parameters either in a hash or as a block. The hash
+  # method is especially useful when you're receiving the data from somewhere else, like an
+  # HTTP request. It works like this:
+  #
+  #   user = User.new(name: 'David', occupation: 'Code Artist')
+  #   user.name # => 'David'
+  #
+  # You can also use block initialization:
+  #
+  #   user = User.new do |u|
+  #     u.name = 'David'
+  #     u.occupation = 'Code Artist'
+  #   end
+  #
+  # And of course you can just create a bare object and specify the attributes after the fact:
+  #
+  #   user = User.new
+  #   user.name = 'David'
+  #   user.occupation = 'Code Artist'
+  #
+  # == Conditions
+  #
+  # Conditions can either be specified as a string, array, or hash representing the WHERE-part of an SQL statement.
+  # The array form is to be used when the condition input is tainted and requires sanitization. The string form can
+  # be used for statements that don't involve tainted data. The hash form works much like the array form, except
+  # only equality and range is possible. Examples:
+  #
+  #   class User < DuckRecord::Base
+  #     def self.authenticate_unsafely(user_name, password)
+  #       where('user_name = '#{user_name}' AND password = '#{password}'').first
+  #     end
+  #
+  #     def self.authenticate_safely(user_name, password)
+  #       where('user_name = ? AND password = ?', user_name, password).first
+  #     end
+  #
+  #     def self.authenticate_safely_simply(user_name, password)
+  #       where(user_name: user_name, password: password).first
+  #     end
+  #   end
+  #
+  # The <tt>authenticate_unsafely</tt> method inserts the parameters directly into the query
+  # and is thus susceptible to SQL-injection attacks if the <tt>user_name</tt> and +password+
+  # parameters come directly from an HTTP request. The <tt>authenticate_safely</tt> and
+  # <tt>authenticate_safely_simply</tt> both will sanitize the <tt>user_name</tt> and +password+
+  # before inserting them in the query, which will ensure that an attacker can't escape the
+  # query and fake the login (or worse).
+  #
+  # When using multiple parameters in the conditions, it can easily become hard to read exactly
+  # what the fourth or fifth question mark is supposed to represent. In those cases, you can
+  # resort to named bind variables instead. That's done by replacing the question marks with
+  # symbols and supplying a hash with values for the matching symbol keys:
+  #
+  #   Company.where(
+  #     'id = :id AND name = :name AND division = :division AND created_at > :accounting_date',
+  #     { id: 3, name: '37signals', division: 'First', accounting_date: '2005-01-01' }
+  #   ).first
+  #
+  # Similarly, a simple hash without a statement will generate conditions based on equality with the SQL AND
+  # operator. For instance:
+  #
+  #   Student.where(first_name: 'Harvey', status: 1)
+  #   Student.where(params[:student])
+  #
+  # A range may be used in the hash to use the SQL BETWEEN operator:
+  #
+  #   Student.where(grade: 9..12)
+  #
+  # An array may be used in the hash to use the SQL IN operator:
+  #
+  #   Student.where(grade: [9,11,12])
+  #
+  # When joining tables, nested hashes or keys written in the form 'table_name.column_name'
+  # can be used to qualify the table name of a particular condition. For instance:
+  #
+  #   Student.joins(:schools).where(schools: { category: 'public' })
+  #   Student.joins(:schools).where('schools.category' => 'public' )
+  #
+  # == Overwriting default accessors
+  #
+  # All column values are automatically available through basic accessors on the Active Record
+  # object, but sometimes you want to specialize this behavior. This can be done by overwriting
+  # the default accessors (using the same name as the attribute) and calling
+  # +super+ to actually change things.
+  #
+  #   class Song < DuckRecord::Base
+  #     # Uses an integer of seconds to hold the length of the song
+  #
+  #     def length=(minutes)
+  #       super(minutes.to_i * 60)
+  #     end
+  #
+  #     def length
+  #       super / 60
+  #     end
+  #   end
+  #
+  # == Attribute query methods
+  #
+  # In addition to the basic accessors, query methods are also automatically available on the Active Record object.
+  # Query methods allow you to test whether an attribute value is present.
+  # Additionally, when dealing with numeric values, a query method will return false if the value is zero.
+  #
+  # For example, an Active Record User with the <tt>name</tt> attribute has a <tt>name?</tt> method that you can call
+  # to determine whether the user has a name:
+  #
+  #   user = User.new(name: 'David')
+  #   user.name? # => true
+  #
+  #   anonymous = User.new(name: '')
+  #   anonymous.name? # => false
+  #
+  # == Accessing attributes before they have been typecasted
+  #
+  # Sometimes you want to be able to read the raw attribute data without having the column-determined
+  # typecast run its course first. That can be done by using the <tt><attribute>_before_type_cast</tt>
+  # accessors that all attributes have. For example, if your Account model has a <tt>balance</tt> attribute,
+  # you can call <tt>account.balance_before_type_cast</tt> or <tt>account.id_before_type_cast</tt>.
+  #
+  # This is especially useful in validation situations where the user might supply a string for an
+  # integer field and you want to display the original string back in an error message. Accessing the
+  # attribute normally would typecast the string to 0, which isn't what you want.
+  #
+  # == Dynamic attribute-based finders
+  #
+  # Dynamic attribute-based finders are a mildly deprecated way of getting (and/or creating) objects
+  # by simple queries without turning to SQL. They work by appending the name of an attribute
+  # to <tt>find_by_</tt> like <tt>Person.find_by_user_name</tt>.
+  # Instead of writing <tt>Person.find_by(user_name: user_name)</tt>, you can use
+  # <tt>Person.find_by_user_name(user_name)</tt>.
+  #
+  # It's possible to add an exclamation point (!) on the end of the dynamic finders to get them to raise an
+  # DuckRecord::RecordNotFound error if they do not return any records,
+  # like <tt>Person.find_by_last_name!</tt>.
+  #
+  # It's also possible to use multiple attributes in the same <tt>find_by_</tt> by separating them with
+  # '_and_'.
+  #
+  #  Person.find_by(user_name: user_name, password: password)
+  #  Person.find_by_user_name_and_password(user_name, password) # with dynamic finder
+  #
+  # It's even possible to call these dynamic finder methods on relations and named scopes.
+  #
+  #   Payment.order('created_on').find_by_amount(50)
+  #
+  # == Saving arrays, hashes, and other non-mappable objects in text columns
+  #
+  # Active Record can serialize any object in text columns using YAML. To do so, you must
+  # specify this with a call to the class method
+  # {serialize}[rdoc-ref:AttributeMethods::Serialization::ClassMethods#serialize].
+  # This makes it possible to store arrays, hashes, and other non-mappable objects without doing
+  # any additional work.
+  #
+  #   class User < DuckRecord::Base
+  #     serialize :preferences
+  #   end
+  #
+  #   user = User.create(preferences: { 'background' => 'black', 'display' => large })
+  #   User.find(user.id).preferences # => { 'background' => 'black', 'display' => large }
+  #
+  # You can also specify a class option as the second parameter that'll raise an exception
+  # if a serialized object is retrieved as a descendant of a class not in the hierarchy.
+  #
+  #   class User < DuckRecord::Base
+  #     serialize :preferences, Hash
+  #   end
+  #
+  #   user = User.create(preferences: %w( one two three ))
+  #   User.find(user.id).preferences    # raises SerializationTypeMismatch
+  #
+  # When you specify a class option, the default value for that attribute will be a new
+  # instance of that class.
+  #
+  #   class User < DuckRecord::Base
+  #     serialize :preferences, OpenStruct
+  #   end
+  #
+  #   user = User.new
+  #   user.preferences.theme_color = 'red'
+  #
+  #
+  # == Single table inheritance
+  #
+  # Active Record allows inheritance by storing the name of the class in a
+  # column that is named 'type' by default. See DuckRecord::Inheritance for
+  # more details.
+  #
+  # == Connection to multiple databases in different models
+  #
+  # Connections are usually created through
+  # {DuckRecord::Base.establish_connection}[rdoc-ref:ConnectionHandling#establish_connection] and retrieved
+  # by DuckRecord::Base.connection. All classes inheriting from DuckRecord::Base will use this
+  # connection. But you can also set a class-specific connection. For example, if Course is an
+  # DuckRecord::Base, but resides in a different database, you can just say <tt>Course.establish_connection</tt>
+  # and Course and all of its subclasses will use this connection instead.
+  #
+  # This feature is implemented by keeping a connection pool in DuckRecord::Base that is
+  # a hash indexed by the class. If a connection is requested, the
+  # {DuckRecord::Base.retrieve_connection}[rdoc-ref:ConnectionHandling#retrieve_connection] method
+  # will go up the class-hierarchy until a connection is found in the connection pool.
+  #
+  # == Exceptions
+  #
+  # * DuckRecordError - Generic error class and superclass of all other errors raised by Active Record.
+  # * AdapterNotSpecified - The configuration hash used in
+  #   {DuckRecord::Base.establish_connection}[rdoc-ref:ConnectionHandling#establish_connection]
+  #   didn't include an <tt>:adapter</tt> key.
+  # * AdapterNotFound - The <tt>:adapter</tt> key used in
+  #   {DuckRecord::Base.establish_connection}[rdoc-ref:ConnectionHandling#establish_connection]
+  #   specified a non-existent adapter
+  #   (or a bad spelling of an existing one).
+  # * AssociationTypeMismatch - The object assigned to the association wasn't of the type
+  #   specified in the association definition.
+  # * AttributeAssignmentError - An error occurred while doing a mass assignment through the
+  #   {DuckRecord::Base#attributes=}[rdoc-ref:AttributeAssignment#attributes=] method.
+  #   You can inspect the +attribute+ property of the exception object to determine which attribute
+  #   triggered the error.
+  # * ConnectionNotEstablished - No connection has been established.
+  #   Use {DuckRecord::Base.establish_connection}[rdoc-ref:ConnectionHandling#establish_connection] before querying.
+  # * MultiparameterAssignmentErrors - Collection of errors that occurred during a mass assignment using the
+  #   {DuckRecord::Base#attributes=}[rdoc-ref:AttributeAssignment#attributes=] method.
+  #   The +errors+ property of this exception contains an array of
+  #   AttributeAssignmentError
+  #   objects that should be inspected to determine which attributes triggered the errors.
+  # * RecordInvalid - raised by {DuckRecord::Base#save!}[rdoc-ref:Persistence#save!] and
+  #   {DuckRecord::Base.create!}[rdoc-ref:Persistence::ClassMethods#create!]
+  #   when the record is invalid.
+  # * RecordNotFound - No record responded to the {DuckRecord::Base.find}[rdoc-ref:FinderMethods#find] method.
+  #   Either the row with the given ID doesn't exist or the row didn't meet the additional restrictions.
+  #   Some {DuckRecord::Base.find}[rdoc-ref:FinderMethods#find] calls do not raise this exception to signal
+  #   nothing was found, please check its documentation for further details.
+  # * SerializationTypeMismatch - The serialized object wasn't of the class specified as the second parameter.
+  # * StatementInvalid - The database server rejected the SQL statement. The precise error is added in the message.
+  #
+  # *Note*: The attributes listed are class-level attributes (accessible from both the class and instance level).
+  # So it's possible to assign a logger to the class through <tt>Base.logger=</tt> which will then be used by all
+  # instances in the current object space.
+  class Base
+    extend ActiveModel::Naming
+
+    extend ActiveSupport::Benchmarkable
+    extend ActiveSupport::DescendantsTracker
+
+    extend Translation
+    extend Enum
+
+    include Core
+    include Persistence
+    include ReadonlyAttributes
+    include ModelSchema
+    include Inheritance
+    include AttributeAssignment
+    include ActiveModel::Conversion
+    include Validations
+    include Attributes
+    include AttributeDecorators
+    include DefineCallbacks
+    include AttributeMethods
+    include Callbacks
+    include Associations
+    include NestedValidateAssociation
+    include NestedAttributes
+    include Reflection
+    include Serialization
+  end
+
+  ActiveSupport.run_load_hooks(:duck_record, Base)
+end