frecency 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7aab993d01164ab48259918ae024ae2e9ad84cf6eb9d78f9a30fc285cccfec47
-  data.tar.gz: 86f6f40ad889a5fe3b965993e1f94ba8bfcbd33349d3675a432f2060515ceb53
+  metadata.gz: 68b015488db5d54d0fde0ff3dc9661fd4f9a643e303a29a8d8bd2faec11ba6a2
+  data.tar.gz: 93cec50e9536db1945fc2accf73407c9be0698a48a911ed5d454e4cd81d3ce1e
 SHA512:
-  metadata.gz: 75f3870f0f645bc85df251b9b238454f8d998539ed90c7994b9a485799e746a4529a3c825c91573a1299e3a98b625baf47e5951d74945a55742ab756285e1212
-  data.tar.gz: f9ea4351abd5f43484bc67d27993d518f8658a16b9361c6e7a99878002677ad24dadd45ac79d4ec0ff49bb9dcbde34097233f9f24d2d2990292c84747f91fb83
+  metadata.gz: d03879d1c8a3a795566cf3c9214efb844ab90fa60efefccb779f0a59e76c92dcc58ef4ea42c0ef6d05d5be5c1f766a5d4e595734282ff5ef7671acf60f861d4f
+  data.tar.gz: b83de9e702435dbc67bc274170d34a6283075e34b2e3b81db6526dd88810bde1e6ce74fe2881cefc7da66f5ddb46920551da2ae158d6cf65b2e1f77adc99403e

data/README.md

@@ -1,44 +1,116 @@
 # Frecency
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/frecency`. To experiment with that code, run `bin/console` for an interactive prompt.
+## Overview
 
-TODO: Delete this and the text above, and describe your gem
+Frecency is a Ruby on Rails gem that provides a way to sort models based on a combination of frequency and recency, also known as "frecency." This allows for more relevant sorting of records by considering both how often and how recently an item has been accessed or updated.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+To install the `frecency` gem, add it to your Gemfile in your Rails application:
 
 ```ruby
 gem 'frecency'
 ```
 
-And then execute:
+Then, run the following command to install the gem:
 
-    $ bundle install
+```sh
+bundle install
+```
+
+## Configuration
+
+### Initializer Configuration
+
+You need to configure your frecency gem in an initializer. Create a file named `frecency.rb` in your `config/initializers` directory:
+
+```ruby
+# config/initializers/frecency.rb
+Frecency.configure do |config|
+  config.default_frequency_column = :views_count  # Default column for frequency
+  config.default_recency_column = :updated_at     # Default column for recency
+  config.default_custom_frequency_scope = nil     # Default custom frequency scope (optional)
+end
+```
 
-Or install it yourself as:
+### Model Configuration
+
+Next, configure the models that you want to utilize frecency sorting. You can do this by adding the necessary configuration to each model. Here’s how you can configure a model:
+
+#### Basic Configuration
+
+For basic configuration using default settings:
+
+```ruby
+class Product < ApplicationRecord
+  configure_frecency(
+    frequency: :views_count,        # Column calculating frequency
+    recency: :updated_at      # Column calculating recency
+  )
+end
+```
 
-    $ gem install frecency
+#### Custom Frequency Scope
+
+If you need a custom frequency scope, you can specify it:
+
+```ruby
+class Order < ApplicationRecord
+  belongs_to :product
+
+  configure_frecency(
+    frequency: :dynamic,      # Use dynamic frequency calculation
+    recency: :created_at,     # Column calculating recency
+    custom_frequency_scope: -> { 
+      select("#{table_name}.*, COUNT(orders.id) as frequency")
+      .joins(:orders)
+      .group("#{table_name}.id")
+    }
+  )
+end
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+After configuring the gem, you can use the `frecency` method to fetch records sorted by frecency:
 
-## Development
+### Basic Usage
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+To retrieve top 10 products sorted by frecency:
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```ruby
+top_products = Product.frecency(10)
+```
 
-## Contributing
+### Advanced Usage
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/frecency. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/frecency/blob/master/CODE_OF_CONDUCT.md).
+You can define more complex configuration and filtering:
 
+```ruby
+class CustomModel < ApplicationRecord
+  configure_frecency(
+    frequency: :custom_count,               # Custom column for frequency
+    recency: :last_accessed_at,             # Custom column for recency
+    custom_frequency_scope: -> { 
+      select("#{table_name}.*, custom_logic() as frequency")
+    }
+  )
+end
+
+top_records = CustomModel.frecency(20)
+```
 
-## License
+## Contributing
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+1. Fork the repository on GitHub.
+2. Clone your forked repository.
+3. Create a new branch for your feature or bug fix.
+4. Write tests for your feature or bug fix.
+5. Make your changes.
+6. Run RSpec tests (or your preferred test suite).
+7. Commit your changes and push to your fork.
+8. Create a pull request on GitHub.
 
-## Code of Conduct
+## License
 
-Everyone interacting in the Frecency project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/frecency/blob/master/CODE_OF_CONDUCT.md).
+This gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/frecency/configuration.rb

@@ -0,0 +1,11 @@
+module Frecency
+  class Configuration
+    attr_accessor :default_frequency_column, :default_recency_column, :default_custom_frequency_scope
+
+    def initialize
+      @default_frequency_column = :views
+      @default_recency_column = :updated_at
+      @default_custom_frequency_scope = nil
+    end
+  end
+end

data/lib/frecency/frecency_methods.rb

@@ -0,0 +1,40 @@
+module Frecency
+  module FrecencyMethods
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :frecency_frequency_column, instance_accessor: false, default: Frecency.configuration.default_frequency_column
+      class_attribute :frecency_recency_column, instance_accessor: false, default: Frecency.configuration.default_recency_column
+      class_attribute :frecency_custom_frequency_scope, instance_accessor: false, default: Frecency.configuration.default_custom_frequency_scope
+    end
+
+    class_methods do
+      def configure_frecency(frequency: nil, recency: nil, custom_frequency_scope: nil)
+        self.frecency_frequency_column = frequency || Frecency.configuration.default_frequency_column
+        self.frecency_recency_column = recency || Frecency.configuration.default_recency_column
+        self.frecency_custom_frequency_scope = custom_frequency_scope || Frecency.configuration.default_custom_frequency_scope
+      end
+
+      def frecency(limit = 10)
+        frequency_column = frecency_frequency_column
+        recency_column = frecency_recency_column
+        custom_frequency_scope = frecency_custom_frequency_scope
+
+        if custom_frequency_scope
+          scope = custom_frequency_scope.call
+          frequency_column = "frequency"
+        else
+          scope = where.not("#{recency_column}" => nil).where.not("#{frequency_column}" => nil)
+        end 
+
+        # Example frecency query, modify based on your database (PostgreSQL example)
+        scope
+          .select("#{table_name}.*, 
+                  ((log(#{frequency_column} + 1) * 100) + 
+                  (extract(epoch from age(current_timestamp, #{recency_column})) / 86400)) AS frecency_score")
+          .order('frecency_score DESC')
+          .limit(limit)
+      end
+    end
+  end
+end

data/lib/frecency/version.rb

@@ -1,3 +1,3 @@
 module Frecency
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/lib/frecency.rb

@@ -1,13 +1,15 @@
 require "frecency/version"
-require 'frecency/configuration'
-require 'frecency/frecency_methods'
-require 'active_support'
+require "frecency/configuration"
+require "frecency/frecency_methods"
+require "active_support"
 
 module Frecency
   class Error < StandardError; end
 
+  # Initialize configuration
+  @configuration = Frecency::Configuration.new
+
   def self.configure
-    @configuration ||= Frecency::Configuration.new
     yield(@configuration)
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: frecency
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Debobroto
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-06-22 00:00:00.000000000 Z
+date: 2024-06-24 00:00:00.000000000 Z
 dependencies: []
 description: This gem allows Rails models to be sorted based on a combination of how
   frequently and how recently they have been accessed or used.
@@ -26,8 +26,12 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- frecency-0.1.0.gem
+- frecency-0.1.1.gem
 - frecency.gemspec
 - lib/frecency.rb
+- lib/frecency/configuration.rb
+- lib/frecency/frecency_methods.rb
 - lib/frecency/version.rb
 homepage: https://github.com/debobroto/frecency
 licenses: