active_cached_resource 0.0.1.pre → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79a99847e99b1a38ac556a5cb2f103284937d2372263b0e1c9ff37103be05220
-  data.tar.gz: 1e36a963664ef05cabe2484e1cc313dced4025c0f7538fcfee2720d979d3034b
+  metadata.gz: 5fbe9addf18997d8c80d81b8660cc87b5da170816bdfa5015d905478ee1b92d4
+  data.tar.gz: 5e01c4a110ee3727a66ae1474bdd2757436f0042579f2207bd0e0d6e19a57e5f
 SHA512:
-  metadata.gz: 32bb3d94315f838ddd854b95b2adfd2844facbbdb06cd2504c7e4f2f01b724d64457c0e15158ed8db33b8bca5a4d892a35fbb7a737a5f8b0c06575ba42d7d3a4
-  data.tar.gz: b7ff531f4882e9c0d9fb70ec2cac5b79be0cde557accc9536220216689476cf31b8aa67406a2f3632f5619d21f9ee03848020fbf2aff46ec5e9a3cbaf5453fa0
+  metadata.gz: 4a33b4446dfdf4aa9feba9b603382f08d1367035a1cb0e2a1387d54b695524084c56d1f57a98f79e77d18284268d06a2d2654a2972b8e4b2415c5314fb632122
+  data.tar.gz: 19e006d900db205641c937a415e989eeb08a74063a126d1caa53d14bf6746399a887f67a116494b839704f3728d0a989e57e67bd59aff568256e253528e5d420

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
+## [0.1.1] - 2024-12-17
+
+- Added ruby yard documentation
+- Added LICENSE
+- Improved gemspec
+
+
 ## [0.1.0] - 2024-12-16
 
 - Initial release

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2024] [Jean Luis Urena]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/lib/active_cached_resource/caching.rb

@@ -13,6 +13,105 @@ module ActiveCachedResource
     end
 
     module ClassMethods
+      # Finds resources similarly to ActiveRecord's +find+ method, with caching support.
+      #
+      # This method is also called internally by the `where` method. When you use `where` to filter results,
+      # it translates the query conditions into parameters and delegates to this method.
+      #
+      # Depending on the first argument provided, this method retrieves:
+      #
+      # * `:one`  - A single resource.
+      # * `:first` - The first resource in the result set.
+      # * `:last`  - The last resource in the result set.
+      # * `:all`   - An array of all matching resources.
+      #
+      # If an Integer or String ID is provided instead of a symbol, it attempts to find a single resource by that ID.
+      #
+      # @overload find_with_cache(scope, options = {})
+      #   @param scope [Symbol, Integer, String]
+      #     The scope of the query or the ID of the resource to find.
+      #     Can be `:one`, `:first`, `:last`, `:all`, or a specific ID.
+      #   @param options [Hash] Additional query options.
+      #   @option options [String, Symbol] :from
+      #     The path or custom endpoint from which to fetch resources.
+      #   @option options [Hash] :params
+      #     Query and prefix (nested URL) parameters.
+      #
+      # @return [Object, Array<Object>, nil]
+      #   * Returns a single resource object if `:one`, `:first`, `:last`, or an ID is given.
+      #   * Returns an array of resources if `:all` is given.
+      #   * Returns `nil` if no data is found for `:one`, `:first`, `:last`, or `:all` queries.
+      #
+      # @raise [ResourceNotFound]
+      #   Raises if the requested resource by ID cannot be found.
+      #
+      # @note
+      #   If the `:reload` option is passed (e.g. `:reload => true`), the cache will be bypassed, and
+      #   the resource(s) will be fetched directly from the server.
+      #
+      # @example Find a single resource by ID
+      #   Person.find(1)
+      #   # GET /people/1.json
+      #
+      # @example Find all resources
+      #   Person.find(:all)
+      #   # GET /people.json
+      #
+      # @example Find all resources with query parameters
+      #   Person.find(:all, params: { title: "CEO" })
+      #   # GET /people.json?title=CEO
+      #
+      # @example Find the first resource from a custom endpoint
+      #   Person.find(:first, from: :managers)
+      #   # GET /people/managers.json
+      #
+      # @example Find the last resource from a custom endpoint
+      #   Person.find(:last, from: :managers)
+      #   # GET /people/managers.json
+      #
+      # @example Find all resources from a nested URL
+      #   Person.find(:all, from: "/companies/1/people.json")
+      #   # GET /companies/1/people.json
+      #
+      # @example Find a single resource from a custom endpoint
+      #   Person.find(:one, from: :leader)
+      #   # GET /people/leader.json
+      #
+      # @example Find all developers speaking Ruby
+      #   Person.find(:all, from: :developers, params: { language: 'ruby' })
+      #   # GET /people/developers.json?language=ruby
+      #
+      # @example Find a single resource from a nested URL
+      #   Person.find(:one, from: "/companies/1/manager.json")
+      #   # GET /companies/1/manager.json
+      #
+      # @example Find a resource with nested prefix parameters
+      #   StreetAddress.find(1, params: { person_id: 1 })
+      #   # GET /people/1/street_addresses/1.json
+      #
+      # When `where` is used, it automatically builds the query parameters and calls `find_with_cache(:all, ...)`:
+      #
+      # @example Using `where` with parameters
+      #   Person.where(title: "CEO")
+      #   # Under the hood: Person.find_with_cache(:all, params: { title: "CEO" })
+      #   # => GET /people.json?title=CEO
+      #
+      #   Person.where(language: 'ruby').where(from: :developers)
+      #   # Under the hood: Person.find_with_cache(:all, from: :developers, params: { language: 'ruby' })
+      #   # => GET /people/developers.json?language=ruby
+      #
+      # == Failure or missing data
+      # A failure to find the requested object by ID raises a ResourceNotFound exception.
+      # With any other scope, find returns nil when no data is returned.
+      #
+      #   Person.find(1)
+      #   # => raises ResourceNotFound
+      #
+      #   Person.find(:all)
+      #   Person.find(:first)
+      #   Person.find(:last)
+      #   # => nil
+      #
       def find_with_cache(*orig_args)
         args = orig_args.deep_dup # Avoid mutating original arguments
         options = extract_options(*args)
@@ -35,7 +134,11 @@ module ActiveCachedResource
         should_reload ? find_via_reload(*args) : find_via_cache(*args)
       end
 
-      # Clear the cache.
+      # Clears all cache matching the cache key prefix of the model.
+      #
+      # This method clears all cached entries that match the cache key prefix.
+      #
+      # @return [void]
       def clear
         cached_resource.cache.clear("#{cache_key_prefix}/")
       end

data/lib/active_cached_resource/configuration.rb

@@ -8,11 +8,26 @@ module ActiveCachedResource
   class Configuration < OpenStruct
     CACHING_STRATEGIES = {
       active_record: ActiveCachedResource::CachingStrategies::SQLCache,
-      active_support: ActiveCachedResource::CachingStrategies::ActiveSupportCache
+      active_support_cache: ActiveCachedResource::CachingStrategies::ActiveSupportCache
     }
 
     OPTIONS = %i[cache_key_prefix logger enabled ttl]
 
+    # Initializes a new configuration for the given model with the specified options.
+    #
+    # @param model [Class] The model class for which the configuration is being set.
+    # @param options [Hash] A hash of options to customize the configuration.
+    # @option options [Symbol] :cache_store The cache store to be used.
+    # @option options [Symbol] :cache_strategy The cache strategy to be used. One of :active_record or :active_support_cache.
+    # @option options [String] :cache_key_prefix The prefix for cache keys (default: model name underscored).
+    # @option options [Logger] :logger The logger instance to be used (default: ActiveCachedResource::Logger).
+    # @option options [Boolean] :enabled Whether caching is enabled (default: true).
+    # @option options [Integer] :ttl The time-to-live for cache entries in seconds (default: 86400).
+    #
+    # @return [ActiveCachedResource::Configuration] The configuration instance.
+    #
+    # @note If `cache_store` is provided and is a CachingStrategies::Base instance, it will be used as the cache strategy.
+    #  Otherwise, `cache_strategy` must be provided to determine the cache strategy.
     def initialize(model, options = {})
       super(
         {
@@ -25,10 +40,16 @@ module ActiveCachedResource
       )
     end
 
+    # Enables caching.
+    #
+    # @return [void]
     def on!
       self.enabled = true
     end
 
+    # Disables caching.
+    #
+    # @return [void]
     def off!
       self.enabled = false
     end

data/lib/active_cached_resource/logger.rb

@@ -2,6 +2,15 @@ require "logger"
 
 module ActiveCachedResource
   class Logger < ::Logger
+    # @!constant COLORS
+    #   @return [Hash] A hash that maps log levels to their corresponding ANSI color codes.
+    #   @example
+    #     COLORS[:debug] # => "\e[36m" (Blue)
+    #     COLORS[:info]  # => "\e[0m"  (Default)
+    #     COLORS[:warn]  # => "\e[33m" (Yellow)
+    #     COLORS[:error] # => "\e[31m" (Red)
+    #     COLORS[:fatal] # => "\e[31m" (Red)
+    #     COLORS[:reset] # => "\e[0m"  (Reset)
     COLORS = {
       debug: "\e[36m",   # Blue
       info: "\e[0m",     # Default
@@ -11,6 +20,11 @@ module ActiveCachedResource
       reset: "\e[0m"     # Reset
     }
 
+    # Initializes a new logger instance for the specified model.
+    #
+    # @param model_name [String] the name of the model to be logged
+    #
+    # @return [void]
     def initialize(model_name)
       super($stdout)
       @model_name = model_name

data/lib/active_cached_resource/model.rb

@@ -11,23 +11,41 @@ module ActiveCachedResource
       class << self
         attr_accessor :cached_resource
 
+        # Sets up caching for an ActiveResource model.
+        #
+        # @param options [Hash] A hash of options to customize the configuration.
+        # @option options [Symbol] :cache_store The cache store to be used. Must be a CachingStrategies::Base instance.
+        # @option options [Symbol] :cache_strategy The cache strategy to be used. One of :active_record or :active_support_cache.
+        # @option options [String] :cache_key_prefix The prefix for cache keys (default: model name underscored).
+        # @option options [Logger] :logger The logger instance to be used (default: ActiveCachedResource::Logger).
+        # @option options [Boolean] :enabled Whether caching is enabled (default: true).
+        # @option options [Integer] :ttl The time-to-live for cache entries in seconds (default: 86400).
+        #
+        # @return [ActiveCachedResource::Configuration] The configuration instance.
+        #
+        # @note If `cache_store` is provided and is a CachingStrategies::Base instance, it will be used as the cache strategy.
+        #  Otherwise, `cache_strategy` must be provided to determine the cache strategy.
         def cached_resource(options = {})
           @cached_resource || setup_cached_resource!(options)
         end
 
+        # :nodoc:
         def setup_cached_resource!(options)
           @cached_resource = ActiveCachedResource::Configuration.new(self, options)
           include ActiveCachedResource::Caching
           @cached_resource
         end
+        # :nodoc:
       end
     end
 
+    # :nodoc:
     module ClassMethods
       def inherited(child)
         child.cached_resource = cached_resource if defined?(@cached_resource)
         super
       end
     end
+    # :nodoc:
   end
 end

data/lib/active_cached_resource/version.rb

@@ -1,12 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveCachedResource
-  module VERSION
-    MAJOR = 0
-    MINOR = 0
-    TINY = 1
-    PRE = "pre"
-
-    STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")
-  end
+  VERSION = "0.1.1"
 end

data/lib/activeresource/lib/active_resource/collection.rb

@@ -6,7 +6,16 @@ require "active_support/inflector"
 module ActiveResource # :nodoc:
   class Collection # :nodoc:
     include Enumerable
-    delegate :to_yaml, *Array.public_instance_methods(false), to: :request_resources!
+    delegate :==, :[], :&, :*, :+, :-, :<=>, :all?, :any?, :as_json, :at, :assoc, :blank?, :bsearch, :bsearch_index,
+         :collect, :combination, :compact, :count, :cycle, :deconstruct, :deep_dup, :dig, :difference, :drop,
+         :drop_while, :each, :each_index, :empty?, :eql?, :excluding, :filter, :fifth, :find_index, :first,
+         :flatten, :forty_two, :fourth, :from, :hash, :include?, :including, :index, :inspect, :intersect?,
+         :intersection, :join, :last, :length, :map, :max, :min, :minmax, :none?, :one?, :pack, :permutation,
+         :pretty_print_cycle, :present?, :product, :reject, :repeated_combination, :repeated_permutation,
+         :rassoc, :reverse, :reverse_each, :rindex, :rotate, :sample, :second, :second_to_last, :select,
+         :shelljoin, :shuffle, :size, :slice, :sort, :sum, :take, :take_while, :third, :third_to_last, :to,
+         :to_a, :to_ary, :to_fs, :to_formatted_s, :to_h, :to_param, :to_query, :to_s, :to_sentence, :to_xml,
+         :transpose, :union, :uniq, :values_at, :without, :zip, to: :request_resources!
 
     attr_accessor :resource_class, :query_params, :path_params
     attr_writer :prefix_options
@@ -175,6 +184,10 @@ module ActiveResource # :nodoc:
       resource_class.where(new_clauses)
     end
 
+    def each(&block)
+      request_resources!.each(&block)
+    end
+
     private
       def query_string(options)
         "?#{options.to_query}" unless options.nil? || options.empty?

data/lib/activeresource/lib/active_resource/railtie.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "active_resource"
+require_relative "../active_resource"
 require "rails"
 
 module ActiveResource
@@ -17,7 +17,7 @@ module ActiveResource
 
     initializer "active_resource.add_active_job_serializer" do |app|
       if app.config.try(:active_job).try(:custom_serializers)
-        require "active_resource/active_job_serializer"
+        require_relative "../active_resource/active_job_serializer"
         app.config.active_job.custom_serializers << ActiveResource::ActiveJobSerializer
       end
     end

data/lib/activeresource/lib/active_resource.rb

@@ -46,4 +46,4 @@ module ActiveResource
   autoload :Validations, "#{__dir__}/active_resource/validations.rb"
 end
 
-require "active_resource/railtie" if defined?(Rails.application)
+require_relative "active_resource/railtie" if defined?(Rails.application)