classy-yaml 1.7.0 → 1.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afbd609fcea95d0b745fe2aa147dc38e2f34b22d18fe315ef905d75988d21555
-  data.tar.gz: 7862d4e6f955b973052b53ebeeca9fa879101594e47673a8940ea10baaeb4634
+  metadata.gz: 94e216b419acc7e44aa7a69c78c127319dcfa402c15104c529f68ea1b841ab93
+  data.tar.gz: 335441bc701254faa6a92bda5e682f57234761908ec4c4af2d3209f6115f8b70
 SHA512:
-  metadata.gz: d42aa732b1e4c1feeff22ffc8cb3b0f47ea31a48be7b1bf5b26141e6e8f3a9c9047cd6c9aaba8f302e2eb61a42cc3c0dc50f0e0f8d5b942755207fb842f7545a
-  data.tar.gz: cd52524424ae4e255044a54de0f6b94cf76e67dea5ffc823a3829b7b897f6b4ff32d90c576e5d76f3afa90cc8054328e6734916f14ca5a3da980d15dece785d4
+  metadata.gz: 006251bb6ddbd941c5bfe7f08a75cbafe7400178ac1550c316acf1499b100764f26ae9255d2acf14731db4028750c3b67af814cec277fb0907fd9d4e52ff305b
+  data.tar.gz: 4a04bb0454b7e3ad8d1165b41923b87ff49df5c52051295c032396ceb13b91d986dc18466e731ca06617530a81cea7b51317444aa8a1ab5cdabde8443c9adf0a

data/README.md

@@ -101,6 +101,10 @@ In your views or components:
 <div class="px-4 py-2 rounded font-medium bg-blue-500 text-white hover:bg-blue-600 m-4"></div>
 ```
 
+The helper reads argument hashes and arrays without changing them. You can reuse frozen arguments across calls. The `add` option also works when no YAML file exists.
+
+Classy YAML checks component files, extra files, the default file, and engine files in that priority order. Base classes and specific classes fall back independently. Control options such as `skip_base` and `classy_files` are not YAML lookup keys.
+
 ### ViewComponent Integration
 
 Include the component helpers in your ViewComponent:
@@ -138,12 +142,20 @@ btn:
 Classy YAML detects if [tailwind_merge](https://github.com/gjtorikian/tailwind_merge) is installed and will leverage it when fetching classes with `yass`. Please read their documentation for installation and benefits.
 
 
+## Caching and development reloads
+
+Classy YAML reuses parsed YAML when file metadata has not changed. In development and tests, each call checks the default, engine, extra, and component files. Edits, additions, and deletions take effect on the next call without a restart.
+
+In production, the default and engine YAML remain cached until configuration resets or the process restarts. Extra and component files still receive metadata checks. `Classy::Yaml.setup` clears the YAML caches.
+
+When `tailwind_merge` is available, Classy YAML reuses one merger per process in all environments. A lock protects the merger cache during concurrent calls.
+
 ## Configuration Options
 
 | Option | Default | Description |
 |--------|---------|-------------|
 | `default_file` | `"config/utility_classes.yml"` | Path to the main YAML file |
-| `extra_files` | `[]` | Array of additional YAML files (highest priority) |
+| `extra_files` | `[]` | Array of additional YAML files (above default and engine files; below component files) |
 | `engine_files` | `[]` | Array of engine YAML files (lowest priority) |
 | `override_tag_helpers` | `false` | Automatically process class symbols/hashes in Rails tag helpers |
 

data/lib/classy/yaml/component_helpers.rb

@@ -2,8 +2,9 @@ module Classy
   module Yaml
     module ComponentHelpers
       def yass(*args)
-        calling_path = Object.const_source_location(self.class.name).first.split("/")[0...-1].join("/")
-        calling_file = Object.const_source_location(self.class.name).first.split("/").last.split(".").first
+        source_file = Object.const_source_location(self.class.name).first
+        calling_path = File.dirname(source_file)
+        calling_file = File.basename(source_file).split(".").first
         component_name = self.class.name.underscore.split("/").last.split(".").first
 
         classy_files = [ "#{calling_path}/#{component_name}.yml",
@@ -11,7 +12,7 @@ module Classy
                         "#{calling_path}/#{calling_file}/#{component_name}.yml" ]
 
         if args.first.is_a?(Hash)
-          args.first.merge!({ classy_files: classy_files.uniq })
+          args[0] = args.first.merge(classy_files: classy_files.uniq)
         else
           args << { classy_files: classy_files.uniq }
         end

data/lib/classy/yaml/helpers.rb

@@ -3,14 +3,15 @@ module Classy
     module Helpers
       # Fetches utility classes from YAML files based on the provided keys.
       # The method follows a priority order:
-      # 1. Extra files (highest priority)
-      # 2. Default YAML
-      # 3. ViewComponent YAMLs (lowest priority)
+      # 1. Component files (highest priority)
+      # 2. Extra files
+      # 3. Default YAML
+      # 4. Engine files (lowest priority)
       #
       # @param args [Array] Array of keys to look up in the YAML files
       # @return [String] Space-separated list of CSS classes
       def yass(*args)
-        # Start with ViewComponent YAMLs (lowest priority)
+        # Start with engine YAMLs (lowest priority)
         classy_yamls = Classy::Yaml.cached_engine_yamls.dup
 
         # Add default YAML (next priority)
@@ -23,16 +24,14 @@ module Classy
         end
 
         # Add classy_files (highest priority)
-        classy_files_hash = args.find { |arg| arg.is_a?(Hash) && arg.keys.include?(:classy_files) } || { classy_files: [] }
+        classy_files_hash = args.find { |arg| arg.is_a?(Hash) && arg.key?(:classy_files) } || { classy_files: [] }
         classy_files_hash[:classy_files].each do |file_path|
           load_yaml_file(file_path, classy_yamls, "classy")
         end
 
-        return "" if classy_yamls.blank?
-
-        skip_base_hash = args.find { |arg| arg.is_a?(Hash) && arg.keys.include?(:skip_base) } || {}
+        skip_base_hash = args.find { |arg| arg.is_a?(Hash) && arg.key?(:skip_base) } || {}
         keys, add_classes = flatten_args(values: args)
-        classes = fetch_classes(keys, classy_yamls: classy_yamls, skip_base: skip_base_hash[:skip_base])
+        classes = fetch_classes(keys.uniq, classy_yamls: classy_yamls, skip_base: skip_base_hash[:skip_base])
         classes += add_classes
 
         # Use tailwind_merge if available, otherwise fall back to simple join
@@ -49,7 +48,7 @@ module Classy
 
         if tailwind_merge_available?
           # Use tailwind_merge for intelligent class merging
-          TailwindMerge::Merger.new.merge(classes)
+          Classy::Yaml.merge_classes(classes)
         else
           # Fall back to simple space-joined classes
           classes.join(" ")
@@ -73,18 +72,8 @@ module Classy
       # @param classy_yamls [Array] Array to add the parsed YAML to
       # @param file_type [String] Type of file being loaded (for error messages)
       def load_yaml_file(file_path, classy_yamls, file_type)
-        begin
-          path_obj = file_path.is_a?(Pathname) ? file_path : Rails.root.join(file_path)
-          if File.exist?(path_obj)
-            content = File.read(path_obj, encoding: "UTF-8")
-            parsed_yaml = YAML.safe_load(content, permitted_classes: [ Symbol, String, Array, Hash ], aliases: true)
-            classy_yamls << parsed_yaml if parsed_yaml && parsed_yaml.is_a?(Hash)
-          end
-        rescue Psych::SyntaxError => e
-          Rails.logger.error "Classy::Yaml (yass helper): Failed to parse #{file_type} YAML file #{file_path}: #{e.message}"
-        rescue => e
-          Rails.logger.error "Classy::Yaml (yass helper): Error loading #{file_type} YAML file #{file_path}: #{e.message}"
-        end
+        parsed_yaml = Classy::Yaml.cached_yaml_file(file_path, file_type)
+        classy_yamls << parsed_yaml if parsed_yaml
       end
 
       # Flattens the arguments into keys and classes
@@ -94,27 +83,27 @@ module Classy
       # @param added_classes [Array] Array to store found classes
       # @return [Array] Tuple of [keys, added_classes]
       def flatten_args(root: [], values: [], keys: [], added_classes: [])
+        parent_keys = []
         values.each do |value|
-          if value.is_a?(Hash)
-            if value.has_key? :add
-              added_classes << value[:add]
-              value.except! :add
-            end
-
-            value.keys.each do |key|
-              values << (root + [ key.to_s ])
-              flatten_args(root: root + [ key.to_s ], values: [ value[key] ], keys: keys, added_classes: added_classes)
+          case value
+          when Hash
+            added_classes << value[:add] if value.key?(:add)
+            value.each do |key, child|
+              next if key == :add
+              next if root.empty? && [ :skip_base, :classy_files ].include?(key)
+
+              path = root + [ key.to_s ]
+              parent_keys << path
+              flatten_args(root: path, values: [ child ], keys: keys, added_classes: added_classes)
             end
+          when Array
+            flatten_args(root: root, values: value, keys: keys, added_classes: added_classes)
           else
-            if value.is_a?(Array)
-              flatten_args(root: root, values: value, keys: keys, added_classes: added_classes)
-            else
-              keys << (root + [ value.to_s ])
-            end
+            keys << (root + [ value.to_s ])
           end
         end
-
-        return keys, added_classes
+        keys.concat(parent_keys)
+        [ keys, added_classes ]
       end
 
       # Fetches classes from the YAML files based on the provided keys
@@ -125,42 +114,30 @@ module Classy
       def fetch_classes(keys, classy_yamls: [], skip_base: false)
         classes = []
 
-        keys.map do |key|
+        keys.each do |key|
           base_classes = nil
           fetched_classes = nil
 
           classy_yamls.reverse_each do |classy_yaml|
-            # Base Class Lookup
-            unless skip_base == true
-              begin
-                value_at_key = classy_yaml.send(:dig, *key)
-                base_value = if value_at_key.is_a?(Hash)
-                               classy_yaml.send(:dig, *(key + [ "base" ]))
+            begin
+              value = classy_yaml.dig(*key)
+              unless skip_base == true || base_classes
+                base_value = if value.is_a?(Hash)
+                  value["base"]
                 elsif key.length > 1
-                               classy_yaml.send(:dig, *(key[0...-1] + [ "base" ]))
-                else
-                               nil
+                  classy_yaml.dig(*(key[0...-1] + [ "base" ]))
                 end
-                normalized_base = normalize_original(base_value)
-                base_classes ||= normalized_base
-              rescue
-                Rails.logger.warn(Classy::Yaml::InvalidKeyError.new(data: key))
+                base_classes = normalize_original(base_value).presence
               end
-            end
 
-            # Specific Key Class Lookup
-            begin
-              value = classy_yaml.send(:dig, *key)
-              unless value.is_a?(Hash)
-                normalized_fetched = normalize_original(value)
-                fetched_classes ||= normalized_fetched
+              unless fetched_classes || value.is_a?(Hash)
+                fetched_classes = normalize_original(value).presence
               end
-            rescue
+            rescue StandardError
               Rails.logger.warn(Classy::Yaml::InvalidKeyError.new(data: key))
             end
 
-            base_classes = nil if base_classes.blank?
-            fetched_classes = nil if fetched_classes.blank?
+            break if fetched_classes && (skip_base == true || base_classes)
           end
 
           classes << base_classes unless base_classes.blank?

data/lib/classy/yaml/version.rb

@@ -1,5 +1,5 @@
 module Classy
   module Yaml
-    VERSION = "1.7.0"
+    VERSION = "1.7.1"
   end
 end

data/lib/classy/yaml.rb

@@ -25,6 +25,9 @@ module Classy
     @cached_engine_yamls = nil
     @cached_default_yaml = nil
     @load_lock = Mutex.new # Prevent race conditions during lazy loading
+    @file_cache = {}
+    @file_lock = Mutex.new
+    @merger_lock = Mutex.new
 
     # -- Configuration Setters with Path Resolution --
     def self.engine_files=(value)
@@ -34,7 +37,7 @@ module Classy
 
     def self.extra_files=(value)
       @@extra_files = Array.wrap(value).reject(&:blank?).map { |file| Rails.root.join(file) }
-      # Note: extra_files are not cached globally by default
+      # Parsed files use the shared file cache.
     end
 
     def self.default_file=(value)
@@ -49,7 +52,7 @@ module Classy
 
     # -- Cached Data Accessors (Lazy Loading) --
     def self.cached_engine_yamls
-      # Bypass cache in development and test environments
+      # Check file metadata in development and test environments
       return load_engine_yamls if Rails.env.development? || Rails.env.test?
 
       # Use cache in other environments
@@ -63,7 +66,7 @@ module Classy
     end
 
     def self.cached_default_yaml
-      # Bypass cache in development and test environments
+      # Check file metadata in development and test environments
       return load_default_yaml if Rails.env.development? || Rails.env.test?
 
       # Use cache in other environments
@@ -81,6 +84,7 @@ module Classy
       # Clear all caches when configuration changes
       @cached_engine_yamls = nil
       @cached_default_yaml = nil
+      @file_lock.synchronize { @file_cache.clear }
       # Apply tag helper override if enabled
       apply_tag_helper_override if @@override_tag_helpers
     end
@@ -106,37 +110,49 @@ module Classy
     end
 
     def self.load_engine_yamls
-      yamls = []
-      self.engine_files.each do |file_path|
+      engine_files.map { |path| cached_yaml_file(path, "engine") }.compact
+    end
+
+    def self.load_default_yaml
+      cached_yaml_file(default_file, "default")
+    end
+
+    # Check metadata on each access so edits do not require a Rails reload.
+    def self.cached_yaml_file(file_path, file_type)
+      @file_lock.synchronize do
         begin
-          if File.exist?(file_path)
-            content = File.read(file_path, encoding: "UTF-8")
-            parsed_yaml = YAML.safe_load(content, permitted_classes: [ Symbol, String, Array, Hash ], aliases: true)
-            yamls << parsed_yaml if parsed_yaml && parsed_yaml.is_a?(Hash)
-          end
+          path = Rails.root.join(file_path).to_s
+          stat = File.stat(path)
+          signature = [ stat.mtime, stat.ctime, stat.size, stat.ino, stat.dev ]
+          cached = @file_cache[path]
+          return cached[:yaml] if cached && cached[:signature] == signature
+
+          content = File.read(path, encoding: "UTF-8")
+          parsed = YAML.safe_load(content, permitted_classes: [ Symbol, String, Array, Hash ], aliases: true)
+          yaml = parsed.is_a?(Hash) ? parsed : nil
+          @file_cache[path] = { signature: signature, yaml: yaml }
+          yaml
+        rescue Errno::ENOENT, Errno::ENOTDIR
+          @file_cache.delete(path)
+          nil
         rescue Psych::SyntaxError => e
-          Rails.logger.error "Classy::Yaml: Failed to parse engine YAML file #{file_path}: #{e.message}"
+          @file_cache.delete(path)
+          Rails.logger.error "Classy::Yaml: Failed to parse #{file_type} YAML file #{file_path}: #{e.message}"
+          nil
         rescue => e
-          Rails.logger.error "Classy::Yaml: Error loading engine YAML file #{file_path}: #{e.message}"
+          @file_cache.delete(path)
+          Rails.logger.error "Classy::Yaml: Error loading #{file_type} YAML file #{file_path}: #{e.message}"
+          nil
         end
       end
-      yamls
     end
 
-    def self.load_default_yaml
-      default_path = Rails.root.join(self.default_file)
-      begin
-        if File.exist?(default_path)
-          content = File.read(default_path, encoding: "UTF-8")
-          parsed_yaml = YAML.safe_load(content, permitted_classes: [ Symbol, String, Array, Hash ], aliases: true)
-          return parsed_yaml if parsed_yaml && parsed_yaml.is_a?(Hash)
-        end
-      rescue Psych::SyntaxError => e
-        Rails.logger.error "Classy::Yaml: Failed to parse default YAML file #{default_path}: #{e.message}"
-      rescue => e
-        Rails.logger.error "Classy::Yaml: Error loading default YAML file #{default_path}: #{e.message}"
+    # The merger cache is mutable, so concurrent calls must use the same lock.
+    def self.merge_classes(classes)
+      @merger_lock.synchronize do
+        @merger ||= TailwindMerge::Merger.new
+        @merger.merge(classes)
       end
-      nil # Return nil if file doesn't exist or fails to load/parse
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: classy-yaml
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.7.1
 platform: ruby
 authors:
 - Tonksthebear
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport