oort 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2482601efe735a7063d6d22932bc2026ee1cdd456e29d6adf1e875d52845b3ed
-  data.tar.gz: 3020190a7db7c6eae9088046952e42dac96dbacc48eb7ffe64990191f3802182
+  metadata.gz: 59358b08ac7c205469cd32c017b73ab36846c520e6d066e67c577bfd4daaacad
+  data.tar.gz: 1c8ab9a97f89c45b7f1630198b2d810ceb6a877d7adbfd0641c92241e5aca425
 SHA512:
-  metadata.gz: 215ba707002ebe3b5732f071eabd62e093f2480814736d10ae59f79f9b6b7c8fc20cb3a46efd2858fcc855fffa1c400e1fdf75c82c40e3e7351106d53aa4faa6
-  data.tar.gz: 73df1b6f0e2ec22d2b6fc66d1158e47bd863af85ef3b344ef2bd1a12955a5ea365555bf63afd2ee731c86618cbc3827e5e8987a6e80d0a4eeae90ce4d9eddf73
+  metadata.gz: 819c6dce941d799a7497e88fe05bc104391e5bc0ce13e3f4ed0a96e388a1ccb3940f1e46de139a02fc742dc2fc26fa2b9643d5ce30995ae242fb2bf5132c4e44
+  data.tar.gz: 7763c120b0311b667159bf1adc48c464a8b43d3a770ac78af8bc9fcba7e616bbce11eef5564859c149b3ea09656e75e29bc2183f35d085fc6942d78a83b5fc58

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)
@@ -71,6 +72,7 @@ PLATFORMS
 
 DEPENDENCIES
   activerecord (~> 7.0, >= 7.0.1)
+  benchmark
   minitest
   oort!
   pg

data/README.md

@@ -1,6 +1,79 @@
 # 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):
+
+```
+  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:
+
+```
+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:
+
+```
+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:
+
+```
+user.posts.ordered_with(user.posts_ordering)
+
+# or
+
+Post.where(user_id: user.id).ordered_with(user.posts_ordering)
+```
+
 
 ## Installation
 

data/lib/oort/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: oort
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - tobyond
@@ -10,7 +10,7 @@ bindir: exe
 cert_chain: []
 date: 2024-01-26 00:00:00.000000000 Z
 dependencies: []
-description: Oort to sort, order
+description: Rails sorting and ordering without deadlocks
 email:
 executables: []
 extensions: []
@@ -41,7 +41,7 @@ files:
 - lib/oort/scopes.rb
 - lib/oort/version.rb
 - sig/oort.rbs
-homepage:
+homepage: https://github.com/tobyond/oort
 licenses:
 - MIT
 metadata: