active_windows 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b393a3c07582141b6656bbf2f9ffe55193f6fd32c3505af7875a9e6f76fec7d0
-  data.tar.gz: 7571dfc93bc77a96e495b2c74799100320e7bf6666809ceb754ec5fc64efffc9
+  metadata.gz: 78306f0ad28382b0fd83cc679dcfd418fc72a5e0c0a26e1e812ab0cdf3a289e2
+  data.tar.gz: a155a298bc07f13ead19b25764df4256996b995918b2362f518512066cccb4f8
 SHA512:
-  metadata.gz: 8380c1b66b1a1a3c31f9e9c5a9035c43ff7689e499254b4bd7d9b250fbfaeb36054c8a012e49f4f84756a0a6ab8c42bf3a931bad82fda768b07556f955bdac3a
-  data.tar.gz: 92128ba7625b79177654e2f09a76f163d5901ddf2105f84174fe591d81dd020d276fdddb428d76649c0648ac7127f2bfcbee4b539c007221c74be1c6d231ae85
+  metadata.gz: 2c2bb59c2105382c024acc58192266edd835c08422bc6a13221d480f634320185395af8eb3a742ff92a53ca123ed4775d50b765da48e7d9256f1f5ba3f397044
+  data.tar.gz: d9821806ab2b43d4ce12955f7311d0582b1312f76dd126255465c088e3a1bd9417c1d4fb870fc6a986361229e984253ffd6d67e587c001234a157a38a82ba545

data/README.md

@@ -4,10 +4,10 @@ A Ruby DSL for SQL window functions in ActiveRecord. Write expressive window fun
 
 ```ruby
 # Fluent API
-User.row_number.partition_by(:department).window_order(:salary).as(:rank)
+User.row_number.partition_by(:department).order_by(:salary).as(:rank)
 
 # Hash API
-User.window(row_number: { partition: :department, order: :salary, as: :rank })
+User.window(row_number: { partition: :department, order_by: :salary, as: :rank })
 
 # Both produce:
 # SELECT "users".*, ROW_NUMBER() OVER (PARTITION BY "users"."department" ORDER BY "users"."salary") AS rank
@@ -41,16 +41,16 @@ ActiveWindows provides two equivalent APIs: a **fluent API** with chainable meth
 
 ### Fluent API
 
-Every window function method returns a chainable object with `.partition_by()`, `.window_order()`, and `.as()`:
+Every window function method returns a chainable object with `.partition_by()`, `.order_by()`, and `.as()`:
 
 ```ruby
-User.row_number.partition_by(:department).window_order(:salary).as(:rank)
+User.row_number.partition_by(:department).order_by(:salary).as(:rank)
 ```
 
-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:
+All three chain methods are optional. `.order_by()` sets the window's `ORDER BY`, while ActiveRecord's `.order()` controls the query-level `ORDER BY`. You can use both together:
 
 ```ruby
-User.row_number.window_order(:salary).as(:rn).order(:name)
+User.row_number.order_by(:salary).as(:rn).order(:name)
 # Window:  OVER (ORDER BY salary)
 # Query:   ORDER BY name
 ```
@@ -58,8 +58,8 @@ User.row_number.window_order(:salary).as(:rn).order(:name)
 Order can be mixed freely:
 
 ```ruby
-User.row_number.as(:rn).window_order(:created_at)
-User.dense_rank.window_order(:score).as(:position)
+User.row_number.as(:rn).order_by(:created_at)
+User.dense_rank.order_by(:score).as(:position)
 ```
 
 ### Hash API
@@ -68,33 +68,44 @@ Pass one or more window function definitions as a hash:
 
 ```ruby
 User.window(
-  row_number: { partition: :department, order: :salary, as: :rank }
+  row_number: { partition: :department, order_by: :salary, as: :rank }
 )
 ```
 
-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 |
 |--------|------|-------------|
 | `:partition` | `Symbol`, `Array` | Column(s) for `PARTITION BY` |
-| `:order` | `Symbol`, `Array` | Column(s) for `ORDER BY` |
+| `:order_by` | `Symbol`, `Array` | Column(s) for `ORDER BY` |
 | `:as` | `Symbol` | Alias for the result column |
 | `:frame` | `String` | Raw SQL frame clause (e.g. `"ROWS BETWEEN 1 PRECEDING AND 1 FOLLOWING"`) |
 | `:value` | `Symbol`, `String`, `Array` | Expression(s) passed as function arguments |
 
 ### Association Names
 
-You can use `belongs_to` association names instead of foreign key columns. ActiveWindows automatically resolves them:
+You can use association names instead of raw column names. ActiveWindows automatically resolves them:
+
+**`belongs_to`** — resolves to the foreign key on the current table:
 
 ```ruby
 # These are equivalent:
-Order.row_number.partition_by(:user).window_order(:amount).as(:rn)
-Order.row_number.partition_by(:user_id).window_order(:amount).as(:rn)
+Order.row_number.partition_by(:user).order_by(:amount).as(:rn)
+Order.row_number.partition_by(:user_id).order_by(:amount).as(:rn)
 
 # Works in the hash API too:
-Order.window(row_number: { partition: :user, order: :amount, as: :rn })
+Order.window(row_number: { partition: :user, order_by: :amount, as: :rn })
+```
+
+**`has_one`** — auto-joins the associated table and references its primary key:
+
+```ruby
+# User has_one :profile
+# Automatically joins profiles and partitions by profiles.id
+User.row_number.partition_by(:profile).order_by(:salary).as(:rn)
+
+# Equivalent to:
+User.joins(:profile).row_number.partition_by("profiles.id").order_by(:salary).as(:rn)
 ```
 
 ### Chaining with ActiveRecord
@@ -105,14 +116,14 @@ Window functions integrate naturally with standard ActiveRecord methods:
 User.where(active: true)
     .row_number
     .partition_by(:department)
-    .window_order(:salary)
+    .order_by(:salary)
     .as(:rank)
 
 User.select(:name, :salary)
-    .window(row_number: { order: :salary, as: :rn })
+    .window(row_number: { order_by: :salary, as: :rn })
 
 User.where(department: "Engineering")
-    .window(rank: { order: :salary, as: :salary_rank })
+    .window(rank: { order_by: :salary, as: :salary_rank })
     .limit(10)
 ```
 
@@ -123,7 +134,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).window_order(:salary).as(:rank)
+results = User.row_number.partition_by(:department).order_by(:salary).as(:rank)
 
 results.each do |user|
   puts "#{user.name}: rank #{user.attributes['rank']}"
@@ -136,44 +147,44 @@ end
 
 ```ruby
 # ROW_NUMBER() - sequential integer within partition
-User.row_number.partition_by(:department).window_order(:salary).as(:rn)
+User.row_number.partition_by(:department).order_by(:salary).as(:rn)
 
 # RANK() - rank with gaps for ties
-User.rank.partition_by(:department).window_order(:salary).as(:salary_rank)
+User.rank.partition_by(:department).order_by(:salary).as(:salary_rank)
 
 # DENSE_RANK() - rank without gaps for ties
-User.dense_rank.partition_by(:department).window_order(:salary).as(:dense_salary_rank)
+User.dense_rank.partition_by(:department).order_by(:salary).as(:dense_salary_rank)
 
 # PERCENT_RANK() - relative rank as a fraction (0 to 1)
-User.percent_rank.window_order(:salary).as(:percentile)
+User.percent_rank.order_by(:salary).as(:percentile)
 
 # CUME_DIST() - cumulative distribution (fraction of rows <= current row)
-User.cume_dist.window_order(:salary).as(:cumulative)
+User.cume_dist.order_by(:salary).as(:cumulative)
 
 # NTILE(n) - divide rows into n roughly equal buckets
-User.ntile(4).window_order(:salary).as(:quartile)
+User.ntile(4).order_by(:salary).as(:quartile)
 ```
 
 ### Value Functions
 
 ```ruby
 # LAG(column, offset, default) - value from a preceding row
-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
+User.lag(:salary).order_by(:hire_date).as(:prev_salary)
+User.lag(:salary, 2).order_by(:hire_date).as(:two_back)         # custom offset
+User.lag(:salary, 1, 0).order_by(:hire_date).as(:prev_or_zero)  # with default
 
 # LEAD(column, offset, default) - value from a following row
-User.lead(:salary).window_order(:hire_date).as(:next_salary)
-User.lead(:salary, 2, 0).window_order(:hire_date).as(:two_ahead)
+User.lead(:salary).order_by(:hire_date).as(:next_salary)
+User.lead(:salary, 2, 0).order_by(:hire_date).as(:two_ahead)
 
 # FIRST_VALUE(column) - first value in the window frame
-User.first_value(:name).partition_by(:department).window_order(:salary).as(:lowest_paid)
+User.first_value(:name).partition_by(:department).order_by(:salary).as(:lowest_paid)
 
 # LAST_VALUE(column) - last value in the window frame
-User.last_value(:name).partition_by(:department).window_order(:salary).as(:highest_paid)
+User.last_value(:name).partition_by(:department).order_by(:salary).as(:highest_paid)
 
 # NTH_VALUE(column, n) - nth value in the window frame
-User.nth_value(:name, 2).partition_by(:department).window_order(:salary).as(:second_lowest)
+User.nth_value(:name, 2).partition_by(:department).order_by(:salary).as(:second_lowest)
 ```
 
 ### Aggregate Window Functions
@@ -206,7 +217,7 @@ Pass a raw SQL frame clause via the hash API:
 User.window(sum: {
   value: :salary,
   partition: :department,
-  order: :hire_date,
+  order_by: :hire_date,
   frame: "ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW",
   as: :running_total
 })
@@ -219,7 +230,7 @@ User.window(sum: {
 ```ruby
 User.rank
     .partition_by(:department)
-    .window_order(:salary)
+    .order_by(:salary)
     .as(:salary_rank)
 ```
 
@@ -228,7 +239,7 @@ User.rank
 ```ruby
 User.window(sum: {
   value: :salary,
-  order: :hire_date,
+  order_by: :hire_date,
   frame: "ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW",
   as: :running_total
 })
@@ -250,14 +261,14 @@ end
 ```ruby
 User.lag(:name)
     .partition_by(:department)
-    .window_order(:hire_date)
+    .order_by(:hire_date)
     .as(:previous_hire)
 ```
 
 ### Divide employees into salary quartiles
 
 ```ruby
-User.ntile(4).window_order(:salary).as(:quartile)
+User.ntile(4).order_by(:salary).as(:quartile)
 ```
 
 ### Rank users by total order amount (with joins)
@@ -266,7 +277,7 @@ User.ntile(4).window_order(:salary).as(:quartile)
 User.joins(:orders)
     .group(:id)
     .select("users.*, SUM(orders.amount) AS total_spent")
-    .window(rank: { order: "total_spent", as: :spending_rank })
+    .window(rank: { order_by: "total_spent", as: :spending_rank })
 ```
 
 ### Window function on joined data
@@ -276,7 +287,7 @@ User.joins(:orders)
 Order.joins(:user)
      .row_number
      .partition_by("users.id")
-     .window_order(amount: :desc)
+     .order_by(amount: :desc)
      .as(:order_rank)
 
 # Number each user's orders chronologically
@@ -284,7 +295,7 @@ Order.joins(:user)
      .select("orders.*, users.name AS user_name")
      .row_number
      .partition_by(:user_id)
-     .window_order(:created_at)
+     .order_by(:created_at)
      .as(:order_number)
 ```
 
@@ -297,7 +308,7 @@ Order.joins(:user)
      .window(sum: {
        value: :amount,
        partition: :user_id,
-       order: :created_at,
+       order_by: :created_at,
        frame: "ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW",
        as: :running_total
      })

data/lib/active_windows/active_record_extensions.rb

@@ -25,7 +25,7 @@ module ActiveWindows
       self
     end
 
-    def window_order(*columns)
+    def order_by(*columns)
       @order_columns = columns.flatten
       self
     end
@@ -33,7 +33,7 @@ module ActiveWindows
     def to_window_hash
       options = {}
       options[:partition] = @partition_columns unless @partition_columns.empty?
-      options[:order] = @order_columns unless @order_columns.empty?
+      options[:order_by] = @order_columns unless @order_columns.empty?
       options[:as] = @alias_name if @alias_name
       options[:value] = @function_args unless @function_args.empty?
       { @function => options }
@@ -65,7 +65,7 @@ module ActiveWindows
   end
 
   module QueryMethods
-    VALID_WINDOW_OPTIONS = %i[value partition order frame as].freeze
+    VALID_WINDOW_OPTIONS = %i[value partition order_by frame as].freeze
 
     # Non-mutating: returns a new relation with window function projections
     def window(*args)
@@ -78,7 +78,7 @@ module ActiveWindows
       # Auto-join has_one associations referenced in partition/order
       joins_needed = processed.flat_map do |_name, options|
         next [] unless options.is_a?(Hash)
-        association_joins_for(options[:partition]) + association_joins_for(options[:order])
+        association_joins_for(options[:partition]) + association_joins_for(options[:order_by])
       end.uniq
       result = result.joins(*joins_needed) if joins_needed.any?
 
@@ -166,7 +166,7 @@ module ActiveWindows
       window = Arel::Nodes::Window.new
 
       apply_window_partition(window, options[:partition])
-      apply_window_order(window, options[:order])
+      apply_window_order(window, options[:order_by])
       apply_window_frame(window, options[:frame]) if options[:frame]
 
       expressions = extract_window_value(options[:value])

data/lib/active_windows/version.rb

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

metadata

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