store_model 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f44d7b9166ab63a3f1ea671f59bb152cea49b935111f57096e8669982063cd3b
-  data.tar.gz: 21d9661a28011ddca555b1ad36d188888de22d23a56fb3e114d6cc552ab649ca
+  metadata.gz: 272a27d0773295eeb4628b0cfd205ecd78bb0d53c9abad4f195a26a00582c465
+  data.tar.gz: dd1709b12b83f49f2a67ea0d92bd5db7cb61be8699433630a17c22d6d6fccec2
 SHA512:
-  metadata.gz: e091ee24a2d81510188a2d42f02946718105c5a1ce8deab5e22b37cae8ad07f1891f6f2366a47858a6e4117b31ae83286a5bf5c70307d1496dab41129a82b177
-  data.tar.gz: aef72b9a2fe4fbd0fd23ff31376c44a339becd6176f8a131d4fd798dfddbfdc2527b3f966e5c7628fadb0b1bc3141d13bfe47562686c06def80a2fd58eee6b60
+  metadata.gz: 1beb4e1bcc06a983e68db54be1d692023f2e56e82824893d5f918c84056ccf23f49d0768219191fb40869850717ffca8a69d36bc1aa0128056ced6efdeed91c1
+  data.tar.gz: c9f82ef6a68c480408cb176fe7817a61b8dd069df808f7450c9df3e54059a62a42866989728685af0cb2cdae8b68eeacfa98fbb1a36d324d6e76e6e76e5fe3d1

data/README.md

@@ -1,92 +1,54 @@
-[![Gem Version](https://badge.fury.io/rb/store_model.svg)](https://rubygems.org/gems/store_model)
-[![Build Status](https://travis-ci.org/DmitryTsepelev/store_model.svg?branch=master)](https://travis-ci.org/DmitryTsepelev/store_model)
-[![Coverage Status](https://coveralls.io/repos/github/DmitryTsepelev/store_model/badge.svg?branch=master)](https://coveralls.io/github/DmitryTsepelev/store_model?branch=master)
+# StoreModel [![Gem Version](https://badge.fury.io/rb/store_model.svg)](https://rubygems.org/gems/store_model) [![Build Status](https://travis-ci.org/DmitryTsepelev/store_model.svg?branch=master)](https://travis-ci.org/DmitryTsepelev/store_model) [![Coverage Status](https://coveralls.io/repos/github/DmitryTsepelev/store_model/badge.svg?branch=master)](https://coveralls.io/github/DmitryTsepelev/store_model?branch=master)
 
-# StoreModel
+**StoreModel** gem allows you to wrap JSON-backed DB columns with ActiveModel-like classes.
 
-<a href="https://evilmartians.com/?utm_source=store_model">
-<img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"></a>
-
-StoreModel allows to work with JSON-backed database columns in a similar way we work with ActiveRecord models. Supports Ruby >= 2.3 and Rails >= 5.2.
-
-For instance, imagine that you have a model `Product` with a `jsonb` column called `configuration`. Your usual workflow probably looks like:
-
-```ruby
-product = Product.find(params[:id])
-if product.configuration["model"] == "spaceship"
-  product.configuration["color"] = "red"
-end
-product.save
-```
-
-This approach works fine when you don't have a lot of keys with logic around them and just read the data. However, when you start working with that data more intensively (for instance, adding some validations around it) - you may find the code a bit verbose and error-prone. With this gem, the snipped above could be rewritten this way:
-
-```ruby
-product = Product.find(params[:id])
-if product.configuration.model == "spaceship"
-  product.configuration.color = "red"
-end
-product.save
-```
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'store_model'
-```
-
-And then execute:
-```bash
-$ bundle
-```
-
-Or install it yourself as:
-```bash
-$ gem install store_model
-```
-
-## How to register stored model
-
-Start with creating a class for representing the hash as an object:
+- 💪 **Powered with [Attributes API](https://api.rubyonrails.org/classes/ActiveRecord/Attributes/ClassMethods.html)**. You can use a number of familiar types or write your own
+- 🔧 **Works like ActiveModel**. Validations, enums and nested attributes work very similar to APIs provided by Rails
+- 1️⃣ **Follows single responsibility principle**. Keep the logic around the data stored in a JSON column separated from the model
+- 👷‍♂️ **Born in production**.
 
 ```ruby
 class Configuration
   include StoreModel::Model
 
   attribute :model, :string
-  attribute :color, :string
-end
-```
-
-Attributes should be defined using [Rails Attributes API](https://api.rubyonrails.org/classes/ActiveRecord/Attributes/ClassMethods.html). There is a number of types available out of the box, and you can always extend the type system with your own ones.
+  enum :status, %i[active archived], default: :active
 
-Register the field in the ActiveRecord model class:
+  validates :model, :status, presence: true
+end
 
-```ruby
 class Product < ApplicationRecord
   attribute :configuration, Configuration.to_type
 end
 ```
 
-## Handling arrays
+<p align="center">
+  <a href="https://evilmartians.com/?utm_source=store_model">
+    <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54">
+  </a>
+</p>
+
+## Why should I wrap my JSON columns?
 
-Should you store an array of models, you can use `#to_array_type` method:
+Imagine that you have a model `Product` with a `jsonb` column called `configuration`. This is how you likely gonna work with this column:
 
 ```ruby
-class Product < ApplicationRecord
-  attribute :configurations, Configuration.to_array_type
+product = Product.find(params[:id])
+if product.configuration["model"] == "spaceship"
+  product.configuration["color"] = "red"
 end
+product.save
 ```
 
-After that, your attribute will return array of `Configuration` instances.
+This approach works fine when you don't have a lot of keys with logic around them and just read the data. However, when you start working with that data more intensively–you may find the code a bit verbose and error-prone.
+
+For instance, try to find a way to validate `:model` value to be required. Despite of the fact, that you'll have to write this validation by hand, it violates single-repsponsibility principle: why parent model (`Product`) should know about the logic related to a child (`Configuration`)?
 
-> Heads up! Attribute is not the same as association, in this case - it's just a hash. `assign_attributes` (and similar) is going to _override_ the whole hash, not merge it with a previous value
+> 📖 Read more about the motivation in the [Wrapping JSON-based ActiveRecord attributes with classes](https://dev.to/evilmartians/wrapping-json-based-activerecord-attributes-with-classes-4apf) post
 
-## Validations
+## Getting started
 
-`StoreModel` supports all the validations shipped with `ActiveModel`. Start with defining validation for the store model:
+Start with creating a class for representing the hash as an object:
 
 ```ruby
 class Configuration
@@ -94,113 +56,38 @@ class Configuration
 
   attribute :model, :string
   attribute :color, :string
-
-  validates :color, presence: true
-end
-```
-
-Then, configure your ActiveRecord model to validates this field as a store model:
-
-```ruby
-class Product < ApplicationRecord
-  attribute :configuration, Configuration.to_type
-
-  validates :configuration, store_model: true
-end
-```
-
-When attribute is invalid, errors are not copied to the parent model by default:
-
-```ruby
-product = Product.new
-puts product.valid? # => false
-puts product.errors.messages # => { configuration: ["is invalid"] }
-puts product.configuration.errors.messages # => { color: ["can't be blank"] }
-```
-
-You can change this behavior to have these errors on the root level (instead of `["is invalid"]`):
-
-```ruby
-class Product < ApplicationRecord
-  attribute :configuration, Configuration.to_type
-
-  validates :configuration, store_model: { merge_errors: true }
-end
-```
-
-In this case errors look this way:
-
-```ruby
-product = Product.new
-puts product.valid? # => false
-puts product.errors.messages # => { color: ["can't be blank"] }
-```
-
-You can change the global behavior using `StoreModel.config`:
-
-```ruby
-StoreModel.config.merge_errors = true
-```
-
-> Heads up! Due to the [changes](https://github.com/rails/rails/pull/32313) of error internals in Rails >= 6.1 it's impossible to add an error with a key that does not have a corresponding attribute with the same name. Because of that, behavior of `merge_error` strategy will be different - all errors are going to be placed under the attribute name (`{ configuration: ["Color can't be blank"] }` instead of `{ color: ["can't be blank"] }`).
-
-You can also add your own custom strategies to handle errors. All you need to do is to provide a callable object to `StoreModel.config.merge_errors` or as value of `:merge_errors`. It should accept three arguments - _attribute_, _base_errors_ and _store_model_errors_:
-
-```ruby
-StoreModel.config.merge_errors = lambda do |attribute, base_errors, _store_model_errors| do
-  base_errors.add(attribute, "cthulhu fhtagn")
 end
 ```
 
-If the logic is complex enough - it worth defining a separate class with a `#call` method:
-
-```ruby
-class FhtagnErrorStrategy
-  def call(attribute, base_errors, _store_model_errors)
-    base_errors.add(attribute, "cthulhu fhtagn")
-  end
-end
-```
-
-You can provide its instance or snake-cased name when configuring global `merge_errors`:
-
-```ruby
-StoreModel.config.merge_errors = :fhtagn_error_strategy
-
-class Product < ApplicationRecord
-  attribute :configuration, Configuration.to_type
-
-  validates :configuration, store_model: { merge_errors: :fhtagn_error_strategy }
-end
-```
+Attributes should be defined using [Rails Attributes API](https://api.rubyonrails.org/classes/ActiveRecord/Attributes/ClassMethods.html). There is a number of types available out of the box, and you can always extend the type system.
 
-or when calling `validates` method on a class level:
+Register the field in the ActiveRecord model class:
 
 ```ruby
-StoreModel.config.merge_errors = FhtagnErrorStrategy.new
-
 class Product < ApplicationRecord
   attribute :configuration, Configuration.to_type
-
-  validates :configuration, store_model: { merge_errors: FhtagnErrorStrategy.new }
 end
 ```
 
-**Note**: `:store_model` validator does not allow nils by default, if you want to change this behavior - configure the validation with `allow_nil: true`:
+When you're done, the initial snippet could be rewritten in the following way:
 
 ```ruby
-class Product < ApplicationRecord
-  attribute :configuration, Configuration.to_type
-
-  validates :configuration, store_model: true, allow_nil: true
+product = Product.find(params[:id])
+if product.configuration.model == "spaceship"
+  product.configuration.color = "red"
 end
+product.save
 ```
 
-## Alternatives
+## Documentation
 
-- [store_attribute](https://github.com/palkan/store_attribute) - work with JSON fields as an attributes, defined on the ActiveRecord model (not in the separate class)
-- [jsonb_accessor](https://github.com/devmynd/jsonb_accessor) - same thing, but with built-in queries
-- [attr_json](https://github.com/jrochkind/attr_json) - works like previous one, but using `ActiveModel::Type`
+1. [Installation](./docs/installation.md)
+2. `StoreModel::Model` API:
+  * [Validations](./docs/validations.md)
+  * [Enums](./docs/enums.md)
+  * [Nested models](./docs/nested_models.md)
+3. [Array of stored models](./docs/array_of_stored_models.md)
+4. [Alternatives](./docs/alternatives.md)
 
 ## License
 

data/lib/store_model/enum.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module StoreModel
+  module Enum
+    def enum(name, values = nil, **kwargs)
+      values ||= kwargs[:in] || kwargs
+
+      ensure_hash(values).tap do |mapping|
+        define_attribute(name, mapping, kwargs[:default])
+        define_reader(name, mapping)
+        define_writer(name, mapping)
+        define_method("#{name}_value") { attributes[name.to_s] }
+        define_method("#{name}_values") { mapping }
+        define_predicate_methods(name, mapping)
+      end
+    end
+
+    private
+
+    def define_attribute(name, mapping, default)
+      attribute name, cast_type(mapping), default: default
+    end
+
+    def define_reader(name, mapping)
+      define_method(name) { mapping.key(send("#{name}_value")).to_s }
+    end
+
+    def define_writer(name, mapping)
+      type = cast_type(mapping)
+      define_method("#{name}=") { |value| super type.cast_value(value) }
+    end
+
+    def define_predicate_methods(name, mapping)
+      mapping.each do |label, value|
+        define_method("#{label}?") { send(name) == mapping.key(value).to_s }
+      end
+    end
+
+    def cast_type(mapping)
+      StoreModel::Types::EnumType.new(mapping)
+    end
+
+    def ensure_hash(values)
+      return values if values.is_a?(Hash)
+
+      values.zip(0...values.size).to_h
+    end
+  end
+end

data/lib/store_model/model.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 require "store_model/types"
+require "store_model/enum"
+require "store_model/type_builders"
+require "store_model/nested_attributes"
 
 module StoreModel
   module Model
@@ -8,15 +11,9 @@ module StoreModel
       base.include ActiveModel::Model
       base.include ActiveModel::Attributes
 
-      base.extend(Module.new do
-        def to_type
-          Types::JsonType.new(self)
-        end
-
-        def to_array_type
-          Types::ArrayType.new(self)
-        end
-      end)
+      base.extend StoreModel::Enum
+      base.extend StoreModel::TypeBuilders
+      base.extend StoreModel::NestedAttributes
     end
 
     def as_json(options = {})

data/lib/store_model/nested_attributes.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module StoreModel
+  module NestedAttributes
+    def accepts_nested_attributes_for(*associations)
+      associations.each do |association|
+        alias_method "#{association}_attributes=", "#{association}="
+      end
+    end
+  end
+end

data/lib/store_model/type_builders.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module StoreModel
+  module TypeBuilders
+    def to_type
+      Types::JsonType.new(self)
+    end
+
+    def to_array_type
+      Types::ArrayType.new(self)
+    end
+  end
+end

data/lib/store_model/types/enum_type.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+module StoreModel
+  module Types
+    class EnumType < ActiveModel::Type::Value
+      def initialize(mapping)
+        @mapping = mapping
+      end
+
+      def type
+        :integer
+      end
+
+      def cast_value(value)
+        return if value.blank?
+
+        case value
+        when String, Symbol then cast_symbol_value(value.to_sym)
+        when Integer then cast_integer_value(value)
+        else
+          raise StoreModel::Types::CastError,
+                "failed casting #{value.inspect}, only String, Symbol or " \
+                "Integer instances are allowed"
+        end
+      end
+
+      private
+
+      def cast_symbol_value(value)
+        raise_invalid_value!(value) unless @mapping.key?(value.to_sym)
+        @mapping[value.to_sym]
+      end
+
+      def cast_integer_value(value)
+        raise_invalid_value!(value) unless @mapping.value?(value)
+        value
+      end
+
+      def raise_invalid_value!(value)
+        raise ArgumentError, "invalid value '#{value}' is assigned"
+      end
+    end
+  end
+end

data/lib/store_model/types.rb

@@ -2,6 +2,7 @@
 
 require "store_model/types/json_type"
 require "store_model/types/array_type"
+require "store_model/types/enum_type"
 
 module StoreModel
   module Types

data/lib/store_model/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StoreModel
-  VERSION = "0.3.2"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: store_model
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - DmitryTsepelev
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-06-13 00:00:00.000000000 Z
+date: 2019-07-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -96,9 +96,13 @@ files:
 - lib/store_model/combine_errors_strategies/mark_invalid_error_strategy.rb
 - lib/store_model/combine_errors_strategies/merge_error_strategy.rb
 - lib/store_model/configuration.rb
+- lib/store_model/enum.rb
 - lib/store_model/model.rb
+- lib/store_model/nested_attributes.rb
+- lib/store_model/type_builders.rb
 - lib/store_model/types.rb
 - lib/store_model/types/array_type.rb
+- lib/store_model/types/enum_type.rb
 - lib/store_model/types/json_type.rb
 - lib/store_model/version.rb
 homepage: https://github.com/DmitryTsepelev/store_model