jet_set 0.3.2 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 9d9c31fea3ab85535b7334a1bcfea9f5a15577f6
-  data.tar.gz: 9dff8880d96dc20c7674a64e66553ac104da18be
+SHA256:
+  metadata.gz: bb3d54a41c9a91c8761053dd1ba08314f3f5416f9b9762cace0758bdb32e2c5f
+  data.tar.gz: 94c834a0a75d2cf2bae2a25d8e57b24ac68b7870e6e61ed6fc1fafb62c9e5a8c
 SHA512:
-  metadata.gz: 23b7ed643ec6ad827879e7d6f2e1e9d0f038a78cd7051483de3c85f6ea1f32d02361d098ecbeab6648375b5d206367028bdd16310ca8a11bd76962ece12b0258
-  data.tar.gz: c59832f80bbf2996665384963be940e81ae9bc26a68a28f6d5bb212e28c1899710c544cfb5eeff48564e5a9a7458453eddaa475708d5ad11809a765111bb8964
+  metadata.gz: 4e08aeb9e15d4918b310dcf33b03e9df48fa555ade341901518b21fa51b67eb4c22b98d184922ef7291baeb3edf08171e2737e90580b61e563e61f9452159645
+  data.tar.gz: 024b1e91903efb225aac4142932ce67abed52eb16681214ccf2a6803d72c929c77e183fb1352e58124bec1a70b2786320eabf426bd212a99ae0fcdf6a1d6cc3d

data/Gemfile

@@ -2,4 +2,3 @@ source "https://rubygems.org"
 
 gemspec
 
-

data/README.md

@@ -1,9 +1,8 @@
 # JetSet ![Build Status](https://travis-ci.org/cylon-v/jet_set.svg?branch=master)
 
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/jet_set`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+JetSet is a data mapping framework for domain-driven developers who think that SQL is the best tool for data querying.
+JetSet is built on top of [Sequel](https://github.com/jeremyevans/sequel) ORM and it's just an abstraction for making 
+the persistence of mapped objects invisible.  
 
 ## Installation
 
@@ -23,7 +22,156 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Initialization
+Open DB connection, see [Sequel docs](https://sequel.jeremyevans.net/rdoc/files/doc/opening_databases_rdoc.html):
+```ruby
+ @connection = Sequel.connect('sqlite:/') # you can connect to any DB supported by Sequel
+```
+
+Create a mapping of your model, details described [here]:
+```ruby
+class Mapping
+  def self.load_mapping
+    JetSet::map do
+      entity User do
+        field :first_name # reqular field
+        collection :invoices, type: Invoice # "has many" association
+        reference :plan, type: Plan, weak: true # "belongs to" association
+      end
+    end
+  end
+end
+```
+
+Init JetSet environment on start of your application:
+```ruby
+JetSet::init(Mapping.load_mapping, @container)
+```
+
+Open JetSet session:
+```ruby
+@jet_set = JetSet::open_session(@connection)
+```
+For web-applications it's reasonable to bind JetSet session to request lifetime - 
+all modification operations in an MVC action can represent a ["Unit of Work"](https://martinfowler.com/eaaCatalog/unitOfWork.html).
+
+### Object model
+Using JetSet you can wrap an application domain model and purely implement "Persistence Ignorance" approach. 
+The model objects are pure Ruby objects without any noisy stuff like annotations, inline mapping, etc:
+```ruby
+class User
+  attr_reader :invoices
+
+  def initialize(attrs = {})
+    @first_name = attrs[:first_name]
+    @last_name = attrs[:last_name]
+    @invoices = []
+  end
+
+  def add_invoice(invoice)
+    @invoices << invoice
+  end
+end
+
+class Invoice
+  attr_reader :created_at, :amount
+
+  def initialize(attrs = {})
+    @created_at = DateTime.now
+    @amount = attrs[:amount] || 0
+  end
+end
+```
+
+### Object model tracking and saving
+Create an objects which is described in the mapping:
+```ruby
+user = User.new(first_name: 'Ivan', last_name: 'Ivanov')
+invoice = Invoice.new(created_at: DateTime.now, user: user, amount: 100.0)
+```
+
+Attach them to the session:
+```ruby
+ @session.attach(invoice, user)
+```
+It makes the objects tracked by JetSet.
+
+Finalize the session:
+```ruby
+ @session.finalize
+```
+It saves all added/changed objects to the database.
+
+### Object model loading
+
+```ruby
+user_query = <<~SQL
+  SELECT
+    u.* AS ENTITY user
+  FROM users u
+  LIMIT 1
+SQL
+
+invoices_sql = <<~SQL
+  SELECT
+    i.* AS ENTITY invoice
+  WHERE i.user_id = :user_id
+SQL
+
+customer = @session.fetch(User, user_query) do |user|
+  preload(user, :invoices, invoices_sql, user_id: user.id)
+end
+```
+All loaded objects are already attached to the session and you can perform a changes which will be saved after the session finalization:
+
+```ruby
+customer.invoices[0].apply # changes invoice state
+@session.finalize
+```
+
+Do not load your object model just for drawing a views. For showing a results just use Sequel without any object mappings:
+```ruby
+result = @connection[:user].where(role: 'admin').to_a
+json = JSON.generate(data: result)
+```   
+In other words, following [CQS](https://en.wikipedia.org/wiki/Command%E2%80%93query_separation) approach you can 
+load your model for a command but not for a query.
+
+### Validation
+Simple validation is optional feature provided by JetSet out of the box. To add this to your domain object you just need
+to include module `JetSet::Validations` and use `validate` statements:
+
+```ruby
+require 'jet_set/validations'
+
+class User
+  include JetSet::Validations
+  validate :name, 'cannot be empty', -> (value) {!value.nil? && !value.empty?}
+  validate :email, type: :string, presence: true
+  validate :email, 'should be valid email address', -> (value) {value.match(...)}
+
+  def initialize(attrs = {})
+    @name = attrs[:name]
+  end
+end
+```
+JetSet uses such validations automatically on saving objects in the database. Also you can invoke validation manually,
+i.e. in unit tests, using `validate!` method:
+
+```ruby
+user = User.new(name: nil)
+user.validate! # raises JetSet::ValidationError
+```
+
+`JetSet::ValidationError` contains details regarding invalid items like:
+
+```ruby
+error.invalid_items # => {name: 'cannot be empty'}
+```
+
+
+
+You can find more interesting examples in [JetSet integration tests](https://github.com/cylon-v/jet_set/tree/master/spec/integration).        
 
 ## Development
 

data/jet_set.gemspec

@@ -30,12 +30,11 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'sequel', '~> 5.4.0'
-  spec.add_dependency 'hypo', '~> 0.9.0'
-
-  spec.add_development_dependency 'bundler', '~> 1.15'
-  spec.add_development_dependency 'rake', '~> 10.0'
-  spec.add_development_dependency 'rspec', '~> 3.0'
-  spec.add_development_dependency 'sqlite3', '~> 1.3'
-  spec.add_development_dependency 'simplecov', '~> 0.16'
+  spec.add_dependency 'sequel', '>= 5.4.0'
+  spec.add_dependency 'hypo', '>= 1.0.0'
+  spec.add_development_dependency 'bundler', '>= 2.1'
+  spec.add_development_dependency 'rake', '>= 10.0'
+  spec.add_development_dependency 'rspec', '>= 3.0'
+  spec.add_development_dependency 'sqlite3', '>= 1.3'
+  spec.add_development_dependency 'simplecov', '>= 0.16'
 end

data/lib/jet_set.rb

@@ -3,6 +3,9 @@ require 'sequel'
 require 'sequel/extensions/inflector'
 require 'jet_set/environment'
 require 'jet_set/mapping'
+require 'jet_set/validations'
+require 'jet_set/validation_error'
+require 'jet_set/validation_definition_error'
 require 'jet_set/version'
 
 module JetSet

data/lib/jet_set/entity_builder.rb

@@ -1,5 +1,6 @@
 require 'jet_set/mixin/identity'
 require 'jet_set/mixin/entity'
+require 'jet_set/validations'
 
 module JetSet
   # A converter of a pure Ruby object to JetSet trackable object.
@@ -22,6 +23,7 @@ module JetSet
 
       object.extend(Identity)
       object.extend(Entity)
+      object.extend(Validations)
     end
   end
 end

data/lib/jet_set/mapper.rb

@@ -15,7 +15,8 @@ module JetSet
       @container = container
 
       @mapping.entity_mappings.values.each do |entity_mapping|
-        container.register(entity_mapping.type)
+        entity_name = "jet_set__#{entity_mapping.type.name.underscore}".to_sym
+        container.register(entity_mapping.type, entity_name)
       end
     end
 
@@ -29,22 +30,29 @@ module JetSet
     #       "SELECT u.name AS customer__name from users u"
     def map(type, row_hash, session, prefix = type.name.underscore)
       entity_name = type.name.underscore.to_sym
+      resolve_name = "jet_set__#{type.name.underscore}".to_sym
       entity_mapping = @mapping.get(entity_name)
       row = Row.new(row_hash, entity_mapping.fields, prefix)
-      object = @container.resolve(entity_name)
-      entity = @entity_builder.create(object)
-      entity.load_attributes!(row.attributes)
 
+      reference_hash = {}
       row.reference_names.each do |reference_name|
         if entity_mapping.references.key? reference_name.to_sym
           reference_id_name = reference_name + '__id'
           unless row_hash[reference_id_name.to_sym].nil?
             type = entity_mapping.references[reference_name.to_sym].type
-            entity.set_reference! reference_name, map(type, row_hash, session, reference_name)
+            reference_hash[reference_name.to_sym] = map(type, row_hash, session, reference_name)
           end
         end
       end
 
+      object = @container.resolve(resolve_name, row.attributes_hash.merge(reference_hash))
+      entity = @entity_builder.create(object)
+      entity.load_attributes!(row.attributes)
+
+      reference_hash.each do |key, value|
+        entity.set_reference! key.to_s, value
+      end
+
       session.attach(entity)
       entity
     end

data/lib/jet_set/mixin/entity.rb

@@ -6,7 +6,7 @@ module JetSet
   module Entity
     # Loads the entity attributes.
     # Parameters:
-    #   +attributes+:: a hash of attributes in format :field => :value
+    #   +attributes+:: an array of key-pairs in format :field => :value
     def load_attributes!(attributes)
       attributes.each do |attribute|
         name = "@#{attribute[:field]}"
@@ -77,6 +77,8 @@ module JetSet
     # Parameters:
     #   +sequel+:: Sequel sequel
     def flush(sequel)
+      validate! if respond_to? :validate!
+
       table_name = self.class.name.underscore.pluralize.to_sym
       table = sequel[table_name]
       entity_name = self.class.name.underscore.to_sym
@@ -113,12 +115,14 @@ module JetSet
             values << value.instance_variable_get('@id')
           end
         end
+
         new_id = table.insert(fields, values)
         @__attributes['@id'] = Attribute.new('@id', new_id)
         @id = new_id
       elsif dirty?
         attributes = {}
         dirty_attributes.each {|attribute| attributes[attribute.name.sub('@', '')] = instance_variable_get(attribute.name)}
+
         if attributes.keys.length > 0
           table.where(id: @id).update(attributes)
         end

data/lib/jet_set/row.rb

@@ -1,7 +1,7 @@
 module JetSet
   # A container for fields/references extraction logic
   class Row
-    attr_reader :attributes, :reference_names
+    attr_reader :attributes, :attributes_hash, :reference_names
 
     def initialize(row_hash, entity_fields, prefix)
       keys = row_hash.keys.map {|key| key.to_s}
@@ -10,6 +10,11 @@ module JetSet
         .select {|key| entity_fields.include? key.sub(prefix + '__', '')}
         .map {|key| {field: key.sub(prefix + '__', ''), value: row_hash[key.to_sym]}}
 
+      @attributes_hash = {}
+      @attributes.each do |attr|
+        @attributes_hash[attr[:field].to_sym] = attr[:value]
+      end
+
       @reference_names = keys.select {|key| !key.start_with?(prefix) && key.include?('__')}
         .map {|key| key.split('__')[0]}
         .uniq

data/lib/jet_set/session.rb

@@ -14,6 +14,7 @@ module JetSet
       @query_parser = query_parser
       @entity_builder = entity_builder
       @dependency_graph = dependency_graph
+      @mutex = Mutex.new
     end
 
     # Fetches root entity using a result of +execute+ method.
@@ -87,9 +88,17 @@ module JetSet
         end
       end
 
-      to_attach.each do |object|
-        obj = object.kind_of?(Entity) ? object : @entity_builder.create(object)
-        @objects << obj
+      @mutex.synchronize do
+        to_attach.each do |object|
+          if object.kind_of?(Entity)
+            obj = object
+          else
+            obj = @entity_builder.create(object)
+            obj.validate! if obj.respond_to? :validate!
+          end
+
+          @objects << obj
+        end
       end
     end
 
@@ -100,9 +109,15 @@ module JetSet
       dirty_objects = @objects.select {|object| object.dirty?}
       ordered_objects = @dependency_graph.order(dirty_objects)
 
-      if ordered_objects.length > 0
-        @sequel.transaction do
-          ordered_objects.each{|obj| obj.flush(@sequel)}
+      begin
+        if ordered_objects.length > 0
+          @sequel.transaction do
+            ordered_objects.each{|obj| obj.flush(@sequel)}
+          end
+        end
+      ensure
+        @mutex.synchronize do
+          @objects = []
         end
       end
     end

data/lib/jet_set/validation_definition_error.rb

@@ -0,0 +1,4 @@
+module JetSet
+  class ValidationDefinitionError < StandardError
+  end
+end

data/lib/jet_set/validation_error.rb

@@ -0,0 +1,10 @@
+module JetSet
+  class ValidationError < StandardError
+    attr_reader :invalid_items
+
+    def initialize(message, invalid_items = {})
+      super(message)
+      @invalid_items = invalid_items
+    end
+  end
+end

data/lib/jet_set/validations.rb

@@ -0,0 +1,97 @@
+require 'jet_set/validation_error'
+
+module JetSet
+  # Optional validation decorator. Adds validation logic to pure Ruby objects.
+  module Validations
+    # The method runs all validations declared in the model
+    def validate!
+      @to_skip ||= []
+
+      validations = self.class.class_variable_defined?(:@@validations) ? self.class.class_variable_get(:@@validations) : {}
+      attributes = validations.keys - @to_skip
+      invalid_items = []
+
+      attributes.each do |attribute|
+        attribute_validations = validations[attribute] || []
+
+        error = nil
+        attribute_validations.each do |validation|
+          value = instance_variable_get("@#{attribute}")
+          if validation[:func].call(value) == false
+            error = validation[:message]
+            break
+          end
+        end
+        invalid_items << {"#{attribute}": error} if error
+      end
+
+      raise ValidationError.new("#{self.class.name} is invalid", invalid_items) if invalid_items.length > 0
+    end
+
+    # Disables attribute validation for edge cases
+    def do_not_validate(*attributes)
+      @to_skip ||= []
+      attributes.each { |a| @to_skip << a}
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Adds a validation to an attribute of the entity
+      # Parameters:
+      #   +attribute_name+:: +Symbol+ attribute name
+      #   +options+ || +message+:: validation options {type, presence, message, custom} or just a message
+      #   +func+:: boolean proc with a check for validity
+      def validate(attribute_name, options, func = nil)
+        validations = self.class_variable_defined?(:@@validations) ? self.class_variable_get(:@@validations) : {}
+        validations[attribute_name] ||= []
+
+        if options.is_a?(Hash)
+          if options.has_key?(:type)
+            validations[attribute_name] << validate_type(options[:type])
+          end
+
+          if options[:presence] == true
+            validations[attribute_name] << validate_presence
+          end
+
+          message = options[:message]
+        elsif options.is_a?(String)
+          message = options
+        else
+          raise ValidationDefinitionError, "Validation definition of attribute #{attribute_name} is incorrect."
+        end
+
+        func ||= options[:custom]
+
+        unless func.nil?
+          validations[attribute_name] << {func: func, message: message}
+        end
+
+        self.class_variable_set(:@@validations, validations)
+      end
+
+      private
+
+      def validate_presence
+        {message: 'cannot be blank', func: -> (value) {!value.nil? && value != ''}}
+      end
+
+      def validate_type(type)
+        unless [:numeric, :string, :boolean].include?(type)
+          raise ValidationDefinitionError, "the type should be :numeric, :string or :boolean"
+        end
+
+        checks = {
+          numeric: -> (value) {value.is_a?(Numeric)},
+          string: -> (value) {value.is_a?(String)},
+          boolean: -> (value) {!!value == value}
+        }
+
+        {message: "should be #{type}", func: -> (value) {value.nil? || checks[type].call(value)}}
+      end
+    end
+  end
+end

data/lib/jet_set/version.rb

@@ -1,3 +1,3 @@
 module JetSet
-  VERSION = "0.3.2"
+  VERSION = "0.5.3"
 end

metadata

@@ -1,111 +1,111 @@
 --- !ruby/object:Gem::Specification
 name: jet_set
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.5.3
 platform: ruby
 authors:
 - Vladimir Kalinkin
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2018-05-06 00:00:00.000000000 Z
+date: 2021-06-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sequel
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 5.4.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 5.4.0
 - !ruby/object:Gem::Dependency
   name: hypo
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: 1.0.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.15'
+        version: '2.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.15'
+        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '10.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.3'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0.16'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0.16'
 description: ''
@@ -143,14 +143,16 @@ files:
 - lib/jet_set/reference.rb
 - lib/jet_set/row.rb
 - lib/jet_set/session.rb
+- lib/jet_set/validation_definition_error.rb
+- lib/jet_set/validation_error.rb
+- lib/jet_set/validations.rb
 - lib/jet_set/version.rb
-- test.rb
 homepage: https://github.com/cylon-v/jet_set
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -165,9 +167,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.12
-signing_key: 
+rubygems_version: 3.2.15
+signing_key:
 specification_version: 4
 summary: JetSet is a microscopic ORM for DDD projects.
 test_files: []

data/test.rb

@@ -1,16 +0,0 @@
-class Test
-  def initialize
-    @method = 0
-  end
-
-  def calc
-    @method = 1
-    puts @method
-  end
-end
-
-Test.define_method '@method=' do |value|
-  @method = value + 5
-end
-test = Test.new
-test.calc