activerecord-ghosts 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8dc5ffdd3fb04d90505d3c72d29ee3e244eceb3878d01281350c585dcaaa2b6
-  data.tar.gz: 77a1e2db341038581297964bf01b01965664f3f88f71daa298b6e7e3d599b253
+  metadata.gz: fe8b3f46f4b831bfcd1d4888fe2144cdb52c215ea813ea27f26c6dcf2fd3d149
+  data.tar.gz: 9ad32054f18d87b1e8093ca59c5224e5c9e338eb339a84ea6fcf1a7f70d1ff2f
 SHA512:
-  metadata.gz: 545d6e2147b78734a9b2748b1655a8483f979d0eda33c01a3a753fb2058b3fa0d34ca92b62903ca0f42d0b5b649abf7fcc4bdf8d7c3cf75542b223623e4836d3
-  data.tar.gz: 9792de752eca66c581f6bd910164261f89c957980e70710782f280da875d2b6e9b27724b0e7310a6d68e4ba079bc2bb2558971dc586c43fd793cbf47559ce1f3
+  metadata.gz: 56ee0da960929690055279b63f855cbb1eb3589e96c1d49a09455cba153b9355cdd3a7c9a202ca16b378f45a2c78dd2593283c44949f0f85983c5df3bd512c78
+  data.tar.gz: 841c0cf442f89b45db533a340c8b66ad3e1c1e8057e572160959098f756e66de29cadfda9192b1b1d4dce15610530c88018c248a0776b245a1e08d5e9b24afec

data/.rubocop.yml

@@ -1,25 +1,109 @@
-inherit_gem:
-  standard: config/base.yml
+plugins:
+  - rubocop-rspec
 
 AllCops:
   TargetRubyVersion: 3.4
   NewCops: enable
+  SuggestExtensions: false
   Exclude:
     - 'vendor/**/*'
-    - 'tmp/**/*'
     - 'bin/**/*'
+    - 'tmp/**/*'
+    - 'spec/dummy/**/*'
+
+# Disable some overly strict rules
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
 
-# Allow longer lines in specs
 Layout/LineLength:
+  Max: 120
   Exclude:
     - 'spec/**/*'
+    - '*.gemspec'
 
-# Allow longer blocks in specs
 Metrics/BlockLength:
   Exclude:
     - 'spec/**/*'
+    - '*.gemspec'
+    - 'Rakefile'
+  AllowedMethods:
+    - 'class_methods'
 
-# Allow longer methods in specs
 Metrics/MethodLength:
+  Max: 30
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/ClassLength:
+  Max: 120
   Exclude:
     - 'spec/**/*'
+
+Metrics/AbcSize:
+  Max: 40
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 15
+
+# RSpec specific
+RSpec/ExampleLength:
+  Max: 30
+
+RSpec/MultipleExpectations:
+  Max: 10
+
+RSpec/NestedGroups:
+  Max: 4
+
+RSpec/DescribeClass:
+  Exclude:
+    - 'spec/integration/**/*'
+    - 'spec/**/*compatibility*'
+    - 'spec/**/*integration*'
+
+RSpec/SpecFilePathFormat:
+  Enabled: false
+
+RSpec/IndexedLet:
+  Enabled: false
+
+RSpec/StubbedMock:
+  Enabled: false
+
+RSpec/MessageSpies:
+  Enabled: false
+
+RSpec/IdenticalEqualityAssertion:
+  Enabled: false
+
+RSpec/ExpectActual:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+# Disable gemspec cops that conflict with gem practices
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+Gemspec/RequireMFA:
+  Enabled: false
+
+# Allow predicate method names
+Naming/PredicateName:
+  Enabled: false
+
+Naming/VariableNumber:
+  Enabled: false

data/CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.2] - 2025-08-26
+
+- Minor fixes of dependencies
+
 ## [0.0.1] - 2025-08-25
 
 ### Added
@@ -23,7 +27,3 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Works with ActiveRecord associations and scopes
 - Efficient batching for large datasets via enumerators
 - Custom inspect output for ghost records
-
-## [0.0.1] - 2025-08-25
-
-- Initial release

data/README.md

@@ -1,18 +1,13 @@
 # ActiveRecord::Ghosts 👻
 
 "Virtual rows" for ActiveRecord models.
-Fill in the gaps in your sequencFor best performance, ensure the ghosted column (e.g. `:level`) has an **index**.
-If it doesn't, you'll see a warning:
-
-```
-[activerecord-ghosts] ⚠️ Column :level on progress_levels has no leading index. Ghost queries may be slow.
-``` work with **ghost records** that behave like AR objects but aren’t persisted.
+Fill in the gaps in your sequences and work with **ghost records** that behave like AR objects but aren't persisted.
 
 ---
 
 ## ✨ Features
 
-- Define a sequence column (like `number`).
+- Define a sequence column (like `level`, `number`).
 - Query with a range and get **real + ghost records**.
 - Chain with `where` / scopes.
 - Works with `Enumerator` for infinite series.
@@ -24,13 +19,13 @@ If it doesn't, you'll see a warning:
 
 **Requirements:**
 - Ruby 3.4.0+
-- Rails 7.0+
+- Rails 7.2+
 
 Add to your Gemfile:
 
 ```ruby
 gem "activerecord-ghosts"
-````
+```
 
 and run:
 
@@ -40,83 +35,205 @@ bundle install
 
 ---
 
-## 🛠 Usage
+## 🏗 Setup
+
+### Database Schema
+
+Your model needs an **integer column** for the sequence field. This column should be indexed for performance.
 
-### 1. Enable ghosts on your model
+```ruby
+# Example migration
+class CreateProgressLevels < ActiveRecord::Migration[7.2]
+  def change
+    create_table :progress_levels do |t|
+      t.references :user, null: false, foreign_key: true
+      t.integer :level, null: false  # ← Ghost sequence column
+      t.integer :points, default: 0
+      t.timestamps
+    end
+
+    # Index for performance (IMPORTANT!)
+    add_index :progress_levels, [:user_id, :level], unique: true
+    # OR simple index if no associations:
+    # add_index :progress_levels, :level
+  end
+end
+```
+
+### Model Configuration
 
 ```ruby
 class ProgressLevel < ApplicationRecord
   belongs_to :user
-  has_ghosts :level
+
+  # Enable ghosts on the integer sequence column
+  has_ghosts :level, start: 1  # Optional: custom start value (default: 1)
+
+  validates :level, presence: true, uniqueness: { scope: :user_id }
+end
+
+# Alternative start values:
+class Invoice < ApplicationRecord
+  has_ghosts :number, start: 1000  # Start from 1000 instead of 1
 end
+
+# Usage with custom start:
+Invoice.ghosts.take(3)  # Will generate ghosts starting from 1000, 1001, 1002...
 ```
 
+**Requirements:**
+- ✅ Ghost column must be **integer type**
+- ✅ Ghost column should have an **index** (composite or simple)
+- ✅ Index should have ghost column as **leading column** for best performance
+
 ---
 
-### 2. Generate a ghost series
+## 🛠 Usage
+
+### 1. Basic ghost series
 
 ```ruby
-ProgressLevel.ghosts(1..5).map { |level| [level.level, level.ghost?] }
-# => [[1, false], [2, false], [3, true], [4, true], [5, true]]
+# Assuming you have levels 1, 2, 5 in database
+ProgressLevel.ghosts(1..6).map { |level| [level.level, level.ghost?] }
+# => [[1, false], [2, false], [3, true], [4, true], [5, false], [6, true]]
 ```
 
-Here:
-
-* Levels `1` and `2` exist in DB → `ghost? == false`
-* Levels `3..5` don't exist → ghost objects (`ghost? == true`)
-
 ---
 
-### 3. Combine with conditions
+### 2. With associations and scoping
 
 For a specific user:
 
 ```ruby
 user = User.find(1)
-user.progress_levels.ghosts(1..5).map { |level| [level.level, level.user_id, level.ghost?] }
-# => [
-#   [1, 1, false],
-#   [2, 1, false],
-#   [3, 1, true],
-#   [4, 1, true],
-#   [5, 1, true]
-# ]
+
+# Get levels 1-5 for this user (mix of real + ghost records)
+user.progress_levels.ghosts(1..5).each do |level|
+  puts "Level #{level.level}: #{level.ghost? ? 'Missing' : 'Completed'} (#{level.points} points)"
+end
+# Output:
+# Level 1: Completed (100 points)
+# Level 2: Completed (150 points)
+# Level 3: Missing (0 points)      ← Ghost inherits default values
+# Level 4: Missing (0 points)      ← Ghost inherits default values
+# Level 5: Missing (0 points)      ← Ghost inherits default values
 
 # Alternative syntax:
-ProgressLevel.where(user_id: user.id).ghosts(1..5).map { |level| [level.level, level.user_id, level.ghost?] }
+ProgressLevel.where(user_id: user.id).ghosts(1..5)
 ```
 
-Ghosts automatically inherit `where` conditions as defaults.
+**Key insight:** Ghost records automatically inherit `where` conditions and model defaults!
 
 ---
 
-### 4. Infinite series
+### 3. Infinite series
 
-Without arguments, `.ghosts` returns an **Enumerator**:
+Without arguments, `.ghosts` returns an **Enumerator** that starts from the `start` value:
 
 ```ruby
+# With default start: 1
 ProgressLevel.ghosts.take(3).map { |level| [level.level, level.ghost?] }
 # => [[1, false], [2, false], [3, true]]
+
+# With custom start: 1000
+class Invoice < ApplicationRecord
+  has_ghosts :number, start: 1000
+end
+
+Invoice.ghosts.take(3).map { |inv| [inv.number, inv.ghost?] }
+# => [[1000, true], [1001, true], [1002, true]]  # Starts from 1000!
 ```
 
-You can `each`, `each_slice`, etc.
-Records are lazily loaded batch by batch.
+You can `each`, `each_slice`, etc. Records are lazily loaded batch by batch.
+
+---
+
+## 📋 Supported Column Types & Limitations
+
+### ✅ Supported Ghost Columns
+- **Integer columns only** - `t.integer :level`, `t.bigint :number`, etc.
+- Must contain **sequential numeric values** (1, 2, 3... or 10, 20, 30...)
+- Works with any integer range (`1..100`, `0..10`, `-5..5`)
+
+### ❌ Not Supported
+- String columns (`t.string :name`)
+- Date/DateTime columns (`t.date :created_on`)
+- UUID columns (`t.uuid :external_id`)
+- Non-sequential data
+
+### 🎯 Perfect Use Cases
+```ruby
+# ✅ Game levels (1, 2, 3, 4, 5...)
+class PlayerLevel
+  has_ghosts :level  # integer column
+end
+
+# ✅ Invoice numbers (1, 2, 3... or 1000, 1001, 1002...)
+class Invoice
+  has_ghosts :number  # integer column
+end
+
+# ✅ Chapter numbers in a book
+class Chapter
+  has_ghosts :chapter_number  # integer column
+end
+
+# ❌ Don't use for non-sequential data
+class User
+  has_ghosts :email  # ❌ String - won't work
+  has_ghosts :created_at  # ❌ DateTime - not sequential
+end
+```
 
 ---
 
 ## ⚠️ Performance note
 
-For best performance, ensure the ghosted column (e.g. `:number`) has an **index**.
-If it doesn’t, you’ll see a warning:
+For best performance, ensure the ghosted column (e.g. `:level`) has an **index**.
+If it doesn't, you'll see a warning:
 
 ```
-[activerecord-ghosts] ⚠️ Column :number on invoices has no leading index. Ghost queries may be slow.
+[activerecord-ghosts] ⚠️ Column :level on progress_levels has no leading index. Ghost queries may be slow.
 ```
 
 Composite indexes are fine if your ghost column is the **leading** column.
 
 ---
 
+## ❓ FAQ
+
+### Q: Can I use string/UUID columns as ghost fields?
+**A:** No, only integer columns are supported. Ghost records fill numeric gaps in sequences.
+
+### Q: Do ghost records get saved to the database?
+**A:** No! Ghost records exist only in memory. They behave like ActiveRecord objects but `.persisted?` returns `false`.
+
+### Q: Can I modify ghost records?
+**A:** Yes! You can call `.save!` on a ghost record to persist it to the database. After saving, `.ghost?` will return `false`.
+
+### Q: How do I handle gaps in my sequence?
+**A:** That's exactly what this gem does! It fills gaps with virtual records.
+
+```ruby
+# You have records [1, 2, 5, 8] in database
+Model.ghosts(1..10).map(&:id)
+# Returns: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+# Where 3, 4, 6, 7, 9, 10 are ghosts
+```
+
+### Q: What about performance with large ranges?
+**A:** Use the enumerator version for infinite sequences:
+
+```ruby
+# ✅ Memory efficient - loads in batches
+Model.ghosts.take(1000)
+
+# ❌ Avoid large ranges - loads all at once
+Model.ghosts(1..1000000)
+```
+
+---
+
 ## 📦 Development
 
 Clone and setup:
@@ -145,8 +262,6 @@ This gem uses **RubyGems.org Trusted Publishing** for secure, automated releases
 2. Commit and create tag: `git tag v0.1.1 && git push --tags`
 3. GitHub Actions automatically publishes to RubyGems.org
 
-See [TRUSTED_PUBLISHING.md](TRUSTED_PUBLISHING.md) for setup details.
-
 ### Running Tests
 
 ```bash

data/Rakefile

@@ -2,9 +2,9 @@
 
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require "rubocop/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
 
-require "standard/rake"
-
-task default: %i[spec standard]
+task default: %i[spec rubocop]

data/lib/activerecord/ghosts/has_ghosts.rb

@@ -11,9 +11,10 @@ module ActiveRecord
         def has_ghosts(field_name, start: 1)
           include ActiveRecord::Ghosts::GhostRecord
 
-          # ⚠️ Проверка индекса (leading column)
+          # ⚠️ Check index (leading column)
           unless connection.indexes(table_name).any? { |i| i.columns.first == field_name.to_s }
-            warn "[activerecord-ghosts] ⚠️ Column :#{field_name} on #{table_name} has no leading index. Ghost queries may be slow."
+            warn "[activerecord-ghosts] ⚠️ Column :#{field_name} on #{table_name} has no leading index. " \
+                 "Ghost queries may be slow."
           end
 
           define_singleton_method(:ghosts) do |*args, **opts|
@@ -30,7 +31,7 @@ module ActiveRecord
         def ghosts_implementation(relation, field_name, start, *args, **opts)
           range = extract_range(args, opts)
 
-          # 1) Без range → бесконечный Enumerator
+          # 1) No range → infinite Enumerator
           unless range
             return Enumerator.new do |yielder|
               n = start
@@ -52,7 +53,7 @@ module ActiveRecord
             end
           end
 
-          # 2) С range → фиксированный массив
+          # 2) With range → fixed array
           records = relation.where(field_name => range).index_by(&field_name)
           defaults = relation.where_values_hash.symbolize_keys.merge(opts[:default] || {})
 
@@ -70,6 +71,7 @@ module ActiveRecord
         def extract_range(args, opts)
           return args.first if args.first.is_a?(Range)
           return (opts[:from]..opts[:to]) if opts[:from] && opts[:to]
+
           nil
         end
       end

data/lib/activerecord/ghosts/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveRecord
   module Ghosts
-    VERSION = "0.0.1"
+    VERSION = "0.0.2"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-ghosts
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Ilya Kovalenko
@@ -15,132 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.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: rspec-rails
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rails
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '7.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '9.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '7.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '9.0'
-- !ruby/object:Gem::Dependency
-  name: sqlite3
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.4'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.4'
-- !ruby/object:Gem::Dependency
-  name: database_cleaner-active_record
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: factory_bot
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.21'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.21'
-- !ruby/object:Gem::Dependency
-  name: standard
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.35.1
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.35.1
+        version: '7.2'
 description: ActiveRecord::Ghosts allows you to define a sequence column and query
   with ranges to get real + ghost records. Ghost records behave like AR objects but
   aren't persisted, perfect for filling gaps in sequences like levels, numbers, etc.
@@ -152,7 +34,6 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".rubocop.yml"
-- ".standard.yml"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
@@ -186,7 +67,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Virtual rows for ActiveRecord models - fill in the gaps in your sequences
   with ghost records

data/.standard.yml

@@ -1,3 +0,0 @@
-# For available configuration options, see:
-#   https://github.com/standardrb/standard
-ruby_version: 3.4