active_windows 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 997432adcf9a7b09e16440849eac9c1e2c5f740993d3a61e037bf425bd649be7
-  data.tar.gz: 13a7e599db4e091490e1597892400838e205548a2c750b3e0307dbc46b7ddf1f
+  metadata.gz: 40d81b47d0bf35406b6d9004f3eb82b0137b3bfc0dc5bed7e2d33b697753aeae
+  data.tar.gz: 11897b5353a3c8b993922c7af8a4819964d417640bce9501182b145750051144
 SHA512:
-  metadata.gz: 28680757fe01be911b248555904c9569576b39e5fd743dc715e710ef1cf79609a82b543ca25ed975e6d3bc85157c15795df915d5732ad44aa799bf466a55b8bb
-  data.tar.gz: 7db21e9e9f36be6fd1f2db12e5fb3e999e1fa5dd588b8b5567e0fd3a19d21c8c5d4805ab21ee19e5747dc6cea3c8ecccfdce55fccab595bf339b494ddbe33326
+  metadata.gz: 3b858116cd6290e77e23c5688336102efd83a234bb2caca193728e9b9458a91591fe0653420f5cc400238603921f86e472d3d92ab4028342e4ad9eb2396b4d2e
+  data.tar.gz: 3974f6c3a73e2efbbb6aeb603c2ab4ddfd65a88eb23d10353fe94ef50746f38fc4c5c7abceec862f2eb53e8b26f710d3a7b9e274f3889132d83c48874d984e3d

data/README.md

@@ -4,7 +4,7 @@ A Ruby DSL for SQL window functions in ActiveRecord. Write expressive window fun
 
 ```ruby
 # Fluent API
-User.row_number.partition_by(:department).order(:salary).as(:rank)
+User.row_number.partition_by(:department).window_order(:salary).as(:rank)
 
 # Hash API
 User.window(row_number: { partition: :department, order: :salary, as: :rank })
@@ -41,17 +41,25 @@ ActiveWindows provides two equivalent APIs: a **fluent API** with chainable meth
 
 ### Fluent API
 
-Every window function method returns a chainable object with `.partition_by()`, `.order()`, and `.as()`:
+Every window function method returns a chainable object with `.partition_by()`, `.window_order()`, and `.as()`:
 
 ```ruby
-User.row_number.partition_by(:department).order(:salary).as(:rank)
+User.row_number.partition_by(:department).window_order(:salary).as(:rank)
 ```
 
-All three chain methods are optional. Order can be mixed freely:
+All three chain methods are optional. The fluent API uses `.window_order()` (not `.order()`) to avoid collision with ActiveRecord's `.order()`, which controls the query-level `ORDER BY`. This lets you use both together:
 
 ```ruby
-User.row_number.as(:rn).order(:created_at)
-User.dense_rank.order(:score).as(:position)
+User.row_number.window_order(:salary).as(:rn).order(:name)
+# Window:  OVER (ORDER BY salary)
+# Query:   ORDER BY name
+```
+
+Order can be mixed freely:
+
+```ruby
+User.row_number.as(:rn).window_order(:created_at)
+User.dense_rank.window_order(:score).as(:position)
 ```
 
 ### Hash API
@@ -64,6 +72,8 @@ User.window(
 )
 ```
 
+The hash API uses `order:` as a key (not a method call), so there's no naming conflict with ActiveRecord's `.order()`.
+
 Available options:
 
 | Option | Type | Description |
@@ -82,7 +92,7 @@ Window functions integrate naturally with standard ActiveRecord methods:
 User.where(active: true)
     .row_number
     .partition_by(:department)
-    .order(:salary)
+    .window_order(:salary)
     .as(:rank)
 
 User.select(:name, :salary)
@@ -100,7 +110,7 @@ When no `.select()` is specified, `*` is automatically included so all model col
 Window function values are accessible as attributes on the returned records:
 
 ```ruby
-results = User.row_number.partition_by(:department).order(:salary).as(:rank)
+results = User.row_number.partition_by(:department).window_order(:salary).as(:rank)
 
 results.each do |user|
   puts "#{user.name}: rank #{user.attributes['rank']}"
@@ -113,44 +123,44 @@ end
 
 ```ruby
 # ROW_NUMBER() - sequential integer within partition
-User.row_number.partition_by(:department).order(:salary).as(:rn)
+User.row_number.partition_by(:department).window_order(:salary).as(:rn)
 
 # RANK() - rank with gaps for ties
-User.rank.partition_by(:department).order(:salary).as(:salary_rank)
+User.rank.partition_by(:department).window_order(:salary).as(:salary_rank)
 
 # DENSE_RANK() - rank without gaps for ties
-User.dense_rank.partition_by(:department).order(:salary).as(:dense_salary_rank)
+User.dense_rank.partition_by(:department).window_order(:salary).as(:dense_salary_rank)
 
 # PERCENT_RANK() - relative rank as a fraction (0 to 1)
-User.percent_rank.order(:salary).as(:percentile)
+User.percent_rank.window_order(:salary).as(:percentile)
 
 # CUME_DIST() - cumulative distribution (fraction of rows <= current row)
-User.cume_dist.order(:salary).as(:cumulative)
+User.cume_dist.window_order(:salary).as(:cumulative)
 
 # NTILE(n) - divide rows into n roughly equal buckets
-User.ntile(4).order(:salary).as(:quartile)
+User.ntile(4).window_order(:salary).as(:quartile)
 ```
 
 ### Value Functions
 
 ```ruby
 # LAG(column, offset, default) - value from a preceding row
-User.lag(:salary).order(:hire_date).as(:prev_salary)
-User.lag(:salary, 2).order(:hire_date).as(:two_back)         # custom offset
-User.lag(:salary, 1, 0).order(:hire_date).as(:prev_or_zero)  # with default
+User.lag(:salary).window_order(:hire_date).as(:prev_salary)
+User.lag(:salary, 2).window_order(:hire_date).as(:two_back)         # custom offset
+User.lag(:salary, 1, 0).window_order(:hire_date).as(:prev_or_zero)  # with default
 
 # LEAD(column, offset, default) - value from a following row
-User.lead(:salary).order(:hire_date).as(:next_salary)
-User.lead(:salary, 2, 0).order(:hire_date).as(:two_ahead)
+User.lead(:salary).window_order(:hire_date).as(:next_salary)
+User.lead(:salary, 2, 0).window_order(:hire_date).as(:two_ahead)
 
 # FIRST_VALUE(column) - first value in the window frame
-User.first_value(:name).partition_by(:department).order(:salary).as(:lowest_paid)
+User.first_value(:name).partition_by(:department).window_order(:salary).as(:lowest_paid)
 
 # LAST_VALUE(column) - last value in the window frame
-User.last_value(:name).partition_by(:department).order(:salary).as(:highest_paid)
+User.last_value(:name).partition_by(:department).window_order(:salary).as(:highest_paid)
 
 # NTH_VALUE(column, n) - nth value in the window frame
-User.nth_value(:name, 2).partition_by(:department).order(:salary).as(:second_lowest)
+User.nth_value(:name, 2).partition_by(:department).window_order(:salary).as(:second_lowest)
 ```
 
 ### Aggregate Window Functions
@@ -196,7 +206,7 @@ User.window(sum: {
 ```ruby
 User.rank
     .partition_by(:department)
-    .order(:salary)
+    .window_order(:salary)
     .as(:salary_rank)
 ```
 
@@ -227,14 +237,14 @@ end
 ```ruby
 User.lag(:name)
     .partition_by(:department)
-    .order(:hire_date)
+    .window_order(:hire_date)
     .as(:previous_hire)
 ```
 
 ### Divide employees into salary quartiles
 
 ```ruby
-User.ntile(4).order(:salary).as(:quartile)
+User.ntile(4).window_order(:salary).as(:quartile)
 ```
 
 ### Rank users by total order amount (with joins)
@@ -253,7 +263,7 @@ User.joins(:orders)
 Order.joins(:user)
      .row_number
      .partition_by("users.id")
-     .order(amount: :desc)
+     .window_order(amount: :desc)
      .as(:order_rank)
 
 # Number each user's orders chronologically
@@ -261,7 +271,7 @@ Order.joins(:user)
      .select("orders.*, users.name AS user_name")
      .row_number
      .partition_by(:user_id)
-     .order(:created_at)
+     .window_order(:created_at)
      .as(:order_number)
 ```
 

data/lib/active_windows/active_record_extensions.rb

@@ -25,7 +25,7 @@ module ActiveWindows
       self
     end
 
-    def order(*columns)
+    def window_order(*columns)
       @order_columns = columns.flatten
       self
     end
@@ -46,7 +46,7 @@ module ActiveWindows
 
     # Delegate common relation/query methods so the chain is transparent
     delegate :to_sql, :to_a, :to_ary, :load, :loaded?, :each, :map, :first, :last, :count,
-             :where, :select, :joins, :group, :having, :limit, :offset, :reorder, :pluck,
+             :where, :select, :joins, :group, :having, :order, :limit, :offset, :reorder, :pluck,
              :find_each, :find_in_batches, :inspect, :exists?, :any?, :none?, :empty?,
              to: :to_relation
   end

data/lib/active_windows/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_windows
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Andrei Andriichuk