oort 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2482601efe735a7063d6d22932bc2026ee1cdd456e29d6adf1e875d52845b3ed
-  data.tar.gz: 3020190a7db7c6eae9088046952e42dac96dbacc48eb7ffe64990191f3802182
+  metadata.gz: 9d13ddbadfac1d2c1ae4f77c6c81ebac6339ddfdb14b3e41a40da8ba93e62ae2
+  data.tar.gz: fae5d70f39bc682f322c16f6e969b64e01794f9fdd87ed50264fb44ce3beb54a
 SHA512:
-  metadata.gz: 215ba707002ebe3b5732f071eabd62e093f2480814736d10ae59f79f9b6b7c8fc20cb3a46efd2858fcc855fffa1c400e1fdf75c82c40e3e7351106d53aa4faa6
-  data.tar.gz: 73df1b6f0e2ec22d2b6fc66d1158e47bd863af85ef3b344ef2bd1a12955a5ea365555bf63afd2ee731c86618cbc3827e5e8987a6e80d0a4eeae90ce4d9eddf73
+  metadata.gz: aa7621267ccc7d99735bd5548eb7dbdcce7c4b3e280540dd393d4cd45707b0b671f9213eb55c01023c42a710afed5f31163213eead118b0db35d22365cc9fac1
+  data.tar.gz: e0e6d7d5a3d2752ac7747439f28256aceb7183e773418836c05896b3f8ade18dbed010b41a54f05a08360f76c8039ac23c87e5900444867491e7405582552bd6

data/Gemfile

@@ -10,6 +10,7 @@ gem "rubocop", require: false
 
 group :development, :test do
   gem "activerecord", "~> 7.0", ">= 7.0.1"
+  gem "benchmark"
   gem "pg"
   gem "zeitwerk", "~> 2.5"
 end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    oort (0.1.0)
+    oort (0.1.1)
 
 GEM
   remote: https://rubygems.org/
@@ -24,6 +24,7 @@ GEM
       tzinfo (~> 2.0)
     ast (2.4.2)
     base64 (0.2.0)
+    benchmark (0.2.1)
     bigdecimal (3.1.6)
     concurrent-ruby (1.2.3)
     connection_pool (2.4.1)
@@ -68,9 +69,11 @@ GEM
 
 PLATFORMS
   x86_64-darwin-20
+  x86_64-darwin-22
 
 DEPENDENCIES
   activerecord (~> 7.0, >= 7.0.1)
+  benchmark
   minitest
   oort!
   pg

data/README.md

@@ -1,6 +1,94 @@
 # Oort
 
-Ordering your collections without deadlocks.
+#### Rails sorting and ordering without deadlocks.
+
+*Rails and PostgreSQL only (for now).*
+
+Typically, ordering involves adding a position column to records and rearranging the entire collection when altering the sort order. However, this approach is prone to deadlocks and places a heavy load on the database, especially when modifying multiple records simultaneously.
+
+Oort provides an alternative solution by allowing the order to be stored in an array column on the parent object. Any changes to the sort order become a simple modification to a single column.
+
+
+## Instructions
+
+Let's begin with a basic schema involving a User and a Post. You can substitute these entities as needed; just ensure that handles_ordering_of has a corresponding has_many association. (Replace instances of post with your own association in the following examples.)
+
+### Migration
+
+Firstly, you will also need the following migration to users (postgresql only for now):
+
+```RUBY
+  def change
+    add_column(:users, :posts_ordering, :integer, array: true, default: [], using: 'ARRAY[benefit_type]::INTEGER[]')
+
+    add_check_constraint :users, '(array_position(posts_ordering, null) is null)', name: 'posts_ordering'
+  end
+```
+
+This will store the ids of posts in an array on the user, and will only accept integers to prevent any nasty surprises.
+
+### Model
+
+Include the `Oort::Ordered` module in the parent object:
+
+```RUBY
+class User < ActiveRecord::Base
+  include Oort::Ordered
+  handles_ordering_of :posts
+
+  has_many :posts
+end
+
+class Post < ActiveRecord::Base
+  belongs_to :user
+end
+
+```
+
+This inclusion adds `update_posts_ordering` to the user model and `insert_at` to the posts model. It also introduces removal methods: `remove_from_posts_ordering` for the user model and `remove_from_reorderable` for the posts model.
+
+
+### Callbacks
+
+The following callbacks are also added to post:
+
+```RUBY
+after_create_commit :insert_at
+after_destroy :remove_from_reorderable
+```
+
+These callbacks automatically insert a new post at the first position and remove a destroyed post from the user's list.
+
+### Usage
+To change to order of a post, simply call `post.insert_at(12)`
+To remove a post, simply call `post.remove_from_reorderable`
+
+### Scope
+The `ordered_with` scope is also added to the post model. This allows a `user` object to have the following query:
+
+```RUBY
+user.posts.ordered_with(user.posts_ordering)
+
+# or
+
+Post.where(user_id: user.id).ordered_with(user.posts_ordering)
+```
+
+### Customization
+
+`handles_ordering_of` can allow for new records to be the top of the order or the bottom of the order. By default it will push any new records to the top of the order, but you can specify the bottom of the order like so:
+
+```ruby
+
+class User < ActiveRecord::Base
+  include Oort::Ordered
+  handles_ordering_of :posts, default: :bottom
+
+  has_many :posts
+end
+
+```
+
 
 ## Installation
 

data/lib/oort/callbacks.rb

@@ -2,22 +2,24 @@
 
 module Oort
   class Callbacks
-    def self.call(association_class:, remove_from_method_name:, insert_method_name:, instance_name:)
+    def self.call(association_class:, remove_from_method_name:, insert_method_name:, instance_name:, default:)
       new(
         association_class: association_class,
         remove_from_method_name: remove_from_method_name,
         insert_method_name: insert_method_name,
-        instance_name: instance_name
+        instance_name: instance_name,
+        default: default
       ).call
     end
 
-    attr_reader :association_class, :remove_from_method_name, :insert_method_name, :instance_name
+    attr_reader :association_class, :remove_from_method_name, :insert_method_name, :instance_name, :default
 
-    def initialize(association_class:, remove_from_method_name:, insert_method_name:, instance_name:)
+    def initialize(association_class:, remove_from_method_name:, insert_method_name:, instance_name:, default:)
       @association_class = association_class
       @remove_from_method_name = remove_from_method_name
       @insert_method_name = insert_method_name
       @instance_name = instance_name
+      @default = default
     end
 
     def call
@@ -29,7 +31,7 @@ module Oort
 
     def add_callbacks
       association_class.class_eval do
-        after_create_commit :insert_at
+        after_create_commit :initial_insert_at
         after_destroy :remove_from_reorderable
       end
     end
@@ -45,9 +47,13 @@ module Oort
         #   public_send(:user).public_send(:remove_from_posts_ordering, id)
         # end
         <<-RUBY, __FILE__, __LINE__ + 1
-          def insert_at(position = 0)
+          def insert_at(position = 0, initial: nil)
             public_send(#{instance_name.inspect})
-              .public_send(#{insert_method_name.inspect}, insert: id, at: position)
+              .public_send(#{insert_method_name.inspect}, insert: id, at: position, initial: initial)
+          end
+
+          def initial_insert_at
+            insert_at(initial: #{default.inspect})
           end
 
           def remove_from_reorderable

data/lib/oort/inserts.rb

@@ -26,13 +26,22 @@ module Oort
         #   end
         # end
         <<-RUBY, __FILE__, __LINE__ + 1
-          def #{insert_method_name}(insert:, at: 0)
+          def #{insert_method_name}(insert:, at: 0, initial: nil)
             with_lock do
               current_values = public_send(#{stored_in.inspect})
-              current_index = current_values.find_index(insert)
-              insertable = current_index.blank? ? insert : current_values.delete_at(current_index)
-              current_values.insert(at, insertable)
-              update(#{stored_in.inspect} => current_values)
+
+              if initial == :top
+                current_values.unshift(insert)
+                save
+              elsif initial == :bottom
+                current_values << insert
+                save
+              else
+                current_index = current_values.find_index(insert)
+                insertable = current_index.blank? ? insert : current_values.delete_at(current_index)
+                current_values.insert(at, insertable)
+                update(#{stored_in.inspect} => current_values)
+              end
             end
           end
         RUBY

data/lib/oort/ordered.rb

@@ -14,20 +14,23 @@ module Oort
     end
 
     module ClassMethods
-      def handles_ordering_of(association)
+      def handles_ordering_of(association, default: :top)
         args = {
           stored_in: :"#{association}_ordering",
           insert_method_name: :"update_#{association}_ordering",
           remove_from_method_name: :"remove_from_#{association}_ordering",
           association_class: association.to_s.classify.constantize,
           instance_name: :"#{name.downcase}",
-          class_name: name.classify.constantize
+          class_name: name.classify.constantize,
+          default:
         }
 
         Inserts.call(**args.slice(:stored_in, :insert_method_name, :class_name))
         Removes.call(**args.slice(:stored_in, :remove_from_method_name, :class_name))
         Scopes.call(**args.slice(:association_class))
-        Callbacks.call(**args.slice(:association_class, :remove_from_method_name, :insert_method_name, :instance_name))
+        Callbacks.call(
+          **args.slice(:association_class, :remove_from_method_name, :insert_method_name, :instance_name, :default)
+        )
       end
     end
   end

data/lib/oort/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Oort
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end

data/oort.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "lib/oort/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "oort"
+  spec.version = Oort::VERSION
+  spec.authors = ["tobyond"]
+  spec.homepage = "https://github.com/tobyond/oort"
+
+  spec.summary = "Oort to sort, order"
+  spec.description = "Rails sorting and ordering without deadlocks"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["source_code_uri"] = "https://github.com/tobyond/oort"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) || f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Uncomment to register a new dependency of your gem
+  # spec.add_dependency "rspec"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

metadata

@@ -1,16 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: oort
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - tobyond
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-01-26 00:00:00.000000000 Z
+date: 2024-03-16 00:00:00.000000000 Z
 dependencies: []
-description: Oort to sort, order
+description: Rails sorting and ordering without deadlocks
 email:
 executables: []
 extensions: []
@@ -40,8 +40,9 @@ files:
 - lib/oort/removes.rb
 - lib/oort/scopes.rb
 - lib/oort/version.rb
+- oort.gemspec
 - sig/oort.rbs
-homepage:
+homepage: https://github.com/tobyond/oort
 licenses:
 - MIT
 metadata:
@@ -61,7 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
 summary: Oort to sort, order