schemattr 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3162b47b2a1acf700ca81a8ee47222391cf0711ad4b5194b9d5c46cf19584162
+  data.tar.gz: 12b294d20e189e9d16bb23644a26199829bccd3c42ba1b7662aea33b79ae4662
+SHA512:
+  metadata.gz: 1134ffee2611f6f203f3891fe21088121a80f7ceb6a02197dd8cf4aa97b114d575a82c6652217faafb840ecbf6dbf904d61169984ee3cf7fb499dcb035f1a2fe
+  data.tar.gz: dee2aa5f9b8120885f8a0422de822e5ced1bf60103668149963d8ce8866c535db0915123427968af0b3b85653fb18626540190bad2ca16120da5bd79c7385c26

data/MIT.LICENSE

@@ -0,0 +1,22 @@
+Copyright 2015 Jeremy Jackson / ModeSet
+
+https://github.com/modeset/schemattr
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,307 @@
+Schemattr
+=========
+
+[![Gem Version](https://img.shields.io/gem/v/schemattr.svg)](http://badge.fury.io/rb/schemattr)
+[![Build Status](https://img.shields.io/travis/modeset/schemattr.svg)](https://travis-ci.org/modeset/schemattr)
+[![Code Climate](https://codeclimate.com/github/modeset/schemattr/badges/gpa.svg)](https://codeclimate.com/github/modeset/schemattr)
+[![Test Coverage](https://codeclimate.com/github/modeset/schemattr/badges/coverage.svg)](https://codeclimate.com/github/modeset/schemattr)
+[![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT)
+[![Dependency Status](https://gemnasium.com/modeset/schemattr.svg)](https://gemnasium.com/modeset/schemattr)
+
+Schemattr is an ActiveRecord extension that provides a helpful schema-less attribute DSL. It can be used to define a
+simple schema for a single attribute that can change over time without having to migrate existing data.
+
+### Background
+
+Let's say you have a User model, and that model has a simple concept of settings -- just one for now. It's a boolean
+named `opted_in`, and it means that the user is opted in to receive email updates. Sweet, we go add a migration for this
+setting and migrate. Ship it, we're done with that feature.
+
+Ok, so now it's a year later and your project has grown a lot. You have over 4MM users, and in that year there's been a
+lot of business requirements that necessitated new settings for users. Each setting has been added ad hoc, as needed --
+there's now three email lists, and users can opt in and out of each one independently.
+
+This is where Schemattr comes in. Adding a new setting, or changing the name of an existing setting is non-trivial at
+this point of your projects life-cycle, and requires a multi-step migration. You'll need to add the column (don't set a
+default for that column, because that locks the table!), then you'll need to update each record in batches, once
+complete you'll set a default, and finally you'll want to add a null constraint. This can become a hassle, and
+introduces complexity to your deployments.
+
+Schemattr allows you to move all of those settings into a single JSON (or similarly serialized) column. It can behave as
+though the column is defined on the record itself through delegation, allows providing overrides for getter/setter
+methods, can keep a real column synced with one if its fields, and more.
+
+If you're using Schemattr and want to add a new setting field, it's as simple as adding a new field to the attribute
+schema and setting a default right there in the code. No migrations, no hassles, easy deployment.
+
+
+## Table of Contents
+
+1. [Installation](#installation)
+2. [Usage](#usage)
+  - [Field types](#field-types)
+  - [Delegating](#delegating)
+  - [Strict mode](#strict-mode-vs-arbitrary-fields)
+  - [Overriding](#overriding-functionality)
+  - [Renaming fields](#renaming-fields)
+  - [Syncing attributes](#syncing-attributes)
+
+
+## Installation
+
+Add it to your Gemfile:
+```ruby
+gem 'schemattr'
+```
+
+And then execute:
+```shell
+$ bundle
+```
+
+Or install it yourself as:
+```shell
+$ gem install schemattr
+```
+
+
+## Usage
+
+In the examples we assume there's already a User model and table.
+
+First, let's create a migration to add your schema-less attribute. In postgres you can use a JSON column. We use the
+postgres JSON type as our example because the JSON type allows queries and indexing, and hstore does annoying things to
+booleans. We don't need to set our default value to an empty object because Schemattr handles that for us.
+
+*Note*: If you're using a different database provider, like sqlite3 for instance, you can use a text column and tell
+ActiveRecord to serialize that column (e.g. `serialize :settings` in your model). Though, you won't be able to easily
+query in these cases so consider your options.
+
+```ruby
+class AddSettingsToUsers < ActiveRecord::Migration
+  def change
+    add_column :users, :settings, :json
+  end
+end
+```
+
+Schemattr hooks into ActiveRecord and provides the `attribute_schema` method on any model that inherits from
+ActiveRecord. This method provides a simple DSL that allows you to define the schema for the attribute. You can define
+various fields, specify their types, defaults if needed, and additional options.
+
+```ruby
+class User < ActiveRecord::Base
+  attribute_schema :settings do
+    boolean :opted_in, default: true
+    boolean :email_list_advanced, default: false
+    boolean :email_list_expert, default: false
+  end
+end
+```
+
+Notice that we've done nothing else, but we already have a working version of what we want. It's shippable.
+
+```
+user = User.new
+user.settings.opted_in? # => true
+user.settings.email_group_advanced? # => false 
+user.settings.email_group_expert? # => false 
+```
+
+If we save the user at this point, these settings will be persisted. We can also make changes to them at this point, and
+when they're persisted they'll include whatever we've changed them to be. If we don't save the user, that's ok too --
+they'll just be the defaults if we ever ask again.
+
+### Field types
+
+The various field types are outlined below. When you define a string field for instance, the value will be coerced into
+a string at the time that it's set.
+
+type     | description
+---------|--------------
+boolean  | boolean value
+string   | string value  
+text     | same as string type
+integer  | number value
+bigint   | same as integer
+float    | floating point number value
+decimal  | same as float
+datetime | datetime object
+time     | time object (stored the same as datetime)
+date     | date object
+
+You can additionally define your own types using `field :foo, :custom_type` and there will no coercion at the time the
+field is set -- this is intended for when you need something that doesn't care what type it is. This generally makes it
+harder to use in forms however.
+
+### Delegating
+
+If you don't like the idea of having to access these attributes at `user.settings` you can specify that you'd like them
+delegated. This adds delegation of the methods that exist on settings to the User instances.
+
+```ruby
+  attribute_schema :settings, delegated: true do
+    field :opted_in, :boolean, default: true
+  end
+```
+
+```ruby
+user = User.new
+user.opted_in = false
+user.settings.opted_in? # => false
+user.opted_in? # => false
+```
+
+### Strict mode vs. arbitrary fields
+
+By default, Schemattr doesn't allow arbitrary fields to be added, but it supports it. When strict mode is disabled, it
+allows any arbitrary field to be set or asked for.
+
+*Note*: When delegated and strict mode is disabled, you cannot set arbitrary fields on the model directly and must
+access them through the attribute that you've defined -- in our case, it's `settings`.
+
+```ruby
+  attribute_schema :settings, delegated: true, strict: false do
+    field :opted_in, :boolean, default: true
+  end
+```
+
+```ruby
+user = User.new
+user.settings.foo # => nil
+user.settings.foo = "bar"
+user.settings.foo # => "bar"
+user.foo # => NoMethodError
+```
+
+### Overriding
+
+Schemattr provides the ability to specify your own attribute class. By doing so you can provide your own getters and
+setters and do more complex logic. In this example we're providing the inverse of `opted_in` with an `opted_out` psuedo
+field.
+
+```ruby
+class UserSettings < Schemattr::Attribute
+  def opted_out
+    !self[:opted_in]
+  end
+  alias_method :opted_out, :opted_out?
+  
+  def opted_out=(val)
+    opted_in = !val
+  end
+end
+```
+
+```ruby
+  attribute_schema :settings, class: UserSettings do
+    field :opted_in, :boolean, default: true
+  end
+```
+
+```ruby
+user = User.new
+user.settings.opted_out? # => false
+user.settings.opted_in? # => true
+user.settings.opted_out = true
+user.settings.opted_in? # => false
+```
+
+Our custom `opted_out` psuedo field won't be persisted, because it's not a defined field and is just an accessor for an
+existing field that is persisted (`opted_in`).
+
+#### Getters and setters
+
+When overriding the attribute class with your own, you can provide your own custom getters and setters as well. These
+will not be overridden by whatever Schemattr thinks they should do. Take this example, where when someone turns on or
+off a setting we want to subscribe/unsubscribe them to an email list via a third party.
+
+```ruby
+class UserSettings < Schemattr::Attribute
+  def opted_in=(val)
+    if val
+      SubscribeEmail.perform_async(model.email)
+    else
+      UnsubscribeEmail.perform_async(model.email)
+    end
+    # there is no super, so you must set it manually.
+    self[:opted_in] = val
+  end
+end
+```
+
+*Note*: This is not a real world scenario but serves our purposes of describing an example. 
+
+### Renaming fields
+
+Schemattr makes it easy to rename fields as well. Let's say you've got a field named `opted_in`, as the examples have
+shown thus far. But you've added new email lists, and you think `opted_in` is too vague. Like, opted in for what?
+
+We can create a new field that is correctly named, and specify what attribute we want to pull the value from.
+
+```ruby
+  attribute_schema :settings do
+    # field :opted_in, :boolean, default: true
+    field :email_list_beginner, :boolean, from: :opted_in, default: true
+  end
+```
+
+Specifying the `from: :opted_in` option will tell Schemattr to look for the value that may have already been defined in
+`opted_in` before the rename. This allows for slow migrations, but you can also write a migration to ensure this happens
+quickly.
+
+### Syncing attributes
+
+There's a down side to keeping some things internal to this settings attribute. You can query JSON types in postgres,
+but it may not be optimal given your indexing strategy. Schemattr provides a mechanism to keep an attribute in sync, but
+it's important to understand it and handle it with care.
+
+Let's say we want to be able to be able to easily query users who have opted in. We can add the `opted_in` column to (or
+leave it, as the case may be) on the users table.
+
+```ruby
+  attribute_schema :settings do
+    field :email_list_beginner, :boolean, default: true, sync: :opted_in
+  end
+```
+
+```ruby
+user = User.new
+user.settings.email_list_beginner = false
+user.read_attribute(:opted_in) # => false
+user.save!
+User.where(opted_in: false) # => user
+```
+
+By adding the sync option to the field, Schemattr will try to keep that attribute in sync. There are some caveats that
+can lead to confusion however.
+
+First, when you do this, it forces delegation of `user.opted_in` to `user.settings.opted_in` -- this is to make keeping
+things in sync easier. The second issue can arise is when this attribute is set directly in the database -- which means
+using things like `user.update_column(:opted_in, false)`, and `User.update_all(opted_in: false)` will allow things to
+get out of sync.
+
+
+## Querying a JSON column
+
+This has come up a little bit, and so it's worth documenting -- though it has very little to do with Schemattr. When you
+have a JSON column in postgres, you can query values from within that column in various ways.
+
+[The documentation](http://www.postgresql.org/docs/9.4/static/functions-json.html) can be a little hard to grok, so
+these are the common scenarios that we've used.
+
+```
+User.where("(settings->>'opted_in')::boolean") # boolean query
+User.where("settings->>'string_value' = ?", "some string") # string query 
+```
+
+
+## License
+
+Licensed under the [MIT License](http://creativecommons.org/licenses/MIT)
+
+Copyright 2015 [Mode Set](https://github.com/modeset)
+
+
+## Make Code Not War
+![crest](https://secure.gravatar.com/avatar/aa8ea677b07f626479fd280049b0e19f?s=75)

data/lib/schemattr.rb

@@ -0,0 +1,6 @@
+require "schemattr/version"
+require "schemattr/dsl"
+require "schemattr/attribute"
+require "schemattr/active_record_extension.rb"
+
+ActiveRecord::Base.send(:include, Schemattr::ActiveRecordExtension) if defined?(ActiveRecord)

data/lib/schemattr/active_record_extension.rb

@@ -0,0 +1,46 @@
+module Schemattr
+  module ActiveRecordExtension
+    module ClassMethods
+      def attribute_schema(name, options = {}, &block)
+        raise ArgumentError, "No schema provided, block expected for schemaless_attribute." unless block_given?
+
+        name = name.to_sym
+        attribute_schema = DSL.new(options[:class], &block)
+        if options[:delegated]
+          delegate(*attribute_schema.attribute_class.instance_methods(false), to: name)
+        else
+          delegate(*attribute_schema.delegated, to: name)
+        end
+
+        define_method "#{name}=" do |val|
+          raise ArgumentError, "Setting #{name} requires a hash" unless val.is_a?(Hash)
+          delegator = send(name)
+          val.each do |k, v|
+            endpoint = options[:delegated] && self.respond_to?("#{k}=") ? self : delegator
+            endpoint.send("#{k}=", v)
+          end
+          val
+        end
+
+        define_method "#{name}" do
+          _schemaless_attributes[name] ||= attribute_schema.attribute_class.new(self, name, options[:strict] == false)
+        end
+      end
+    end
+
+    def self.included(base = nil, &_block)
+      base.extend(ClassMethods)
+    end
+
+    def reload(*_args)
+      _schemaless_attributes.keys.each { |name| _schemaless_attributes[name] = nil }
+      super
+    end
+
+    private
+
+    def _schemaless_attributes
+      @_schemaless_attributes ||= {}
+    end
+  end
+end

data/lib/schemattr/attribute.rb

@@ -0,0 +1,60 @@
+module Schemattr
+  class Attribute
+    attr_accessor :model, :attr_name, :hash
+
+    def initialize(model, attr_name, allow_arbitrary_attributes = false)
+      @model = model
+      @attr_name = attr_name
+      @allow_arbitrary_attributes = allow_arbitrary_attributes
+      @hash = defaults.merge(model[attr_name] || {})
+    end
+
+    def field_names
+      (self.class.defaults.keys || []).map { |k| k.to_sym }
+    end
+
+    def defaults
+      self.class.defaults
+    end
+
+    def as_json(*args)
+      @hash
+    end
+
+    private
+
+    def method_missing(m, *args)
+      if @allow_arbitrary_attributes
+        self[$1] = args[0] if args.length == 1 && /^(\w+)=$/ =~ m
+        self[m.to_s.gsub(/\?$/, "")]
+      else
+        raise NoMethodError, "undefined method '#{m}' for #{self.class}"
+      end
+    end
+
+    def migrate_value(val, from)
+      return val unless from
+      if (old_val = self[from]).nil?
+        val
+      else
+        @hash.delete(from.to_s)
+        old_val
+      end
+    end
+
+    def sync_value(val, to)
+      model[to] = val if to
+      val
+    end
+
+    def []=(key, val)
+      hash[key.to_s] = val
+      model[attr_name] = hash
+      val
+    end
+
+    def [](key)
+      hash[key.to_s]
+    end
+  end
+end

data/lib/schemattr/dsl.rb

@@ -0,0 +1,86 @@
+module Schemattr
+  class DSL
+    attr_accessor :attribute_class, :delegated, :defaults
+
+    def initialize(klass_override = nil, &block)
+      @attribute_class = Class.new(klass_override || Attribute)
+      @delegated = []
+      @defaults = defaults = {}
+
+      instance_eval(&block)
+
+      @attribute_class.define_singleton_method("defaults") { defaults }
+    end
+
+    protected
+
+    def field(name, type, options = {})
+      if respond_to?(type, true)
+        send(type, name, options)
+      else
+        _define(name, false, options)
+      end
+    end
+
+    def string(name, options = {})
+      _define name, false, options, setter: lambda { |val| sync_value(self[name] = val.to_s, options[:sync]) }
+    end
+
+    def integer(name, options = {})
+      _define name, false, options, setter: lambda { |val| sync_value(self[name] = val.to_i, options[:sync]) }
+    end
+
+    def float(name, options = {})
+      _define name, false, options, setter: lambda { |val| sync_value(self[name] = val.to_f, options[:sync]) }
+    end
+
+    def datetime(name, options = {})
+      _define name, false, options
+    end
+
+    def date(name, options = {})
+      _define name, false, options
+    end
+
+    def boolean(name, options = {})
+      _define name, true, options, setter: lambda { |val|
+        bool = ActiveRecord::Type::Boolean.new.deserialize(val)
+        sync_value(self[name] = bool, options[:sync])
+      }
+    end
+
+    alias_method :text, :string
+    alias_method :bigint, :integer
+    alias_method :decimal, :float
+    alias_method :time, :datetime
+
+    private
+
+    def _define(name, boolean, options, blocks = {})
+      setter = blocks[:setter] || lambda { sync_value(self[name] = val, options[:sync]) }
+      getter = blocks[:getter] || lambda { migrate_value(self[name], options[:from]) }
+      _default(name, options[:default])
+      _method("#{name}=", options[:sync], &setter)
+      _method(name, options[:sync], &getter)
+      _alias("#{name}?", name, options[:sync]) if boolean
+    end
+
+    def _default(name, default)
+      @defaults[name.to_s] = default
+    end
+
+    def _method(name, delegated = false, &block)
+      @delegated.push(name.to_s) if delegated
+      unless attribute_class.instance_methods.include?(name.to_sym)
+        attribute_class.send(:define_method, name, &block)
+      end
+    end
+
+    def _alias(new, old, delegated)
+      @delegated.push(new.to_s) if delegated
+      unless attribute_class.instance_methods.include?(new.to_sym)
+        attribute_class.send(:alias_method, new, old)
+      end
+    end
+  end
+end

data/lib/schemattr/version.rb

@@ -0,0 +1,3 @@
+module Schemattr
+  VERSION = "0.0.1"
+end

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: schemattr
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- jejacks0n
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-11-16 00:00:00.000000000 Z
+dependencies: []
+description: ''
+email:
+- info@modeset.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT.LICENSE
+- README.md
+- lib/schemattr.rb
+- lib/schemattr/active_record_extension.rb
+- lib/schemattr/attribute.rb
+- lib/schemattr/dsl.rb
+- lib/schemattr/version.rb
+homepage: https://github.com/modeset/schemattr
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: ''
+test_files: []