dotlyte 0.1.1

data/lib/dotlyte/validator.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module Dotlyte
+  # Schema rule for a single config key.
+  class SchemaRule
+    attr_accessor :type, :required, :format, :pattern, :enum_values,
+                  :min, :max, :default_value, :sensitive, :doc
+
+    def initialize(**kwargs)
+      @type = kwargs[:type]
+      @required = kwargs.fetch(:required, false)
+      @format = kwargs[:format]
+      @pattern = kwargs[:pattern]
+      @enum_values = kwargs[:enum_values]
+      @min = kwargs[:min]
+      @max = kwargs[:max]
+      @default_value = kwargs[:default_value]
+      @sensitive = kwargs.fetch(:sensitive, false)
+      @doc = kwargs[:doc]
+    end
+  end
+
+  # A single schema violation.
+  class SchemaViolation
+    attr_reader :key, :message, :rule
+
+    def initialize(key:, message:, rule:)
+      @key = key
+      @message = message
+      @rule = rule
+    end
+
+    def to_s
+      "[#{rule}] #{key}: #{message}"
+    end
+  end
+
+  # Schema validation engine for DOTLYTE v2.
+  module Validator
+    FORMAT_PATTERNS = {
+      "email" => /\A[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}\z/,
+      "uuid"  => /\A[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\z/,
+      "date"  => /\A\d{4}-\d{2}-\d{2}\z/,
+      "ipv4"  => /\A\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\z/
+    }.freeze
+
+    # Validate config data against a schema.
+    #
+    # @param data [Hash] the config data
+    # @param schema [Hash<String, SchemaRule>] the schema
+    # @param strict [Boolean] reject unknown keys
+    # @return [Array<SchemaViolation>]
+    def self.validate(data, schema, strict: false)
+      violations = []
+
+      schema.each do |key, rule|
+        val = get_nested(data, key)
+
+        if val.nil?
+          if rule.required
+            violations << SchemaViolation.new(
+              key: key, message: "required key '#{key}' is missing", rule: "required"
+            )
+          end
+          next
+        end
+
+        # Type check
+        if rule.type && !check_type(val, rule.type)
+          violations << SchemaViolation.new(
+            key: key,
+            message: "expected type '#{rule.type}', got #{val.class}",
+            rule: "type"
+          )
+        end
+
+        # Format check
+        if rule.format && val.is_a?(String) && !check_format(val, rule.format)
+          violations << SchemaViolation.new(
+            key: key,
+            message: "value '#{val}' does not match format '#{rule.format}'",
+            rule: "format"
+          )
+        end
+
+        # Pattern check
+        if rule.pattern && val.is_a?(String) && !val.match?(Regexp.new(rule.pattern))
+          violations << SchemaViolation.new(
+            key: key,
+            message: "value '#{val}' does not match pattern '#{rule.pattern}'",
+            rule: "pattern"
+          )
+        end
+
+        # Enum check
+        if rule.enum_values && !rule.enum_values.include?(val)
+          violations << SchemaViolation.new(
+            key: key,
+            message: "value #{val} not in allowed values: #{rule.enum_values}",
+            rule: "enum"
+          )
+        end
+
+        # Min/Max
+        if val.is_a?(Numeric)
+          if rule.min && val < rule.min
+            violations << SchemaViolation.new(
+              key: key, message: "value #{val} is less than minimum #{rule.min}", rule: "min"
+            )
+          end
+          if rule.max && val > rule.max
+            violations << SchemaViolation.new(
+              key: key, message: "value #{val} is greater than maximum #{rule.max}", rule: "max"
+            )
+          end
+        end
+      end
+
+      # Strict mode
+      if strict
+        flat_keys = flatten_keys(data)
+        flat_keys.each do |k|
+          unless schema.key?(k)
+            violations << SchemaViolation.new(
+              key: k, message: "unknown key '#{k}' (strict mode)", rule: "strict"
+            )
+          end
+        end
+      end
+
+      violations
+    end
+
+    # Apply schema defaults to data.
+    def self.apply_defaults(data, schema)
+      schema.each do |key, rule|
+        next if rule.default_value.nil?
+        next unless get_nested(data, key).nil?
+
+        set_nested(data, key, rule.default_value)
+      end
+    end
+
+    # Get all sensitive keys from schema.
+    def self.sensitive_keys(schema)
+      schema.select { |_, rule| rule.sensitive }.keys
+    end
+
+    # Assert valid — raises ValidationError on failure.
+    def self.assert_valid!(data, schema, strict: false)
+      violations = validate(data, schema, strict: strict)
+      return if violations.empty?
+
+      msg = "Schema validation failed:\n" +
+            violations.map { |v| "  - #{v}" }.join("\n")
+      raise ValidationError.new(msg, violations: violations)
+    end
+
+    # Get a nested value via dot-notation key.
+    def self.get_nested(data, key)
+      parts = key.to_s.split(".")
+      current = data
+      parts.each do |part|
+        return nil unless current.is_a?(Hash)
+
+        current = current.key?(part) ? current[part] : current[part.to_sym]
+        return nil if current.nil?
+      end
+      current
+    end
+
+    # Set a nested value via dot-notation key.
+    def self.set_nested(data, key, value)
+      parts = key.to_s.split(".")
+      current = data
+      parts[0..-2].each do |part|
+        current[part] ||= {}
+        current[part] = {} unless current[part].is_a?(Hash)
+        current = current[part]
+      end
+      current[parts.last] = value
+    end
+
+    class << self
+      private
+
+      def check_type(val, expected)
+        case expected
+        when "string"  then val.is_a?(String)
+        when "number"  then val.is_a?(Numeric)
+        when "boolean" then [true, false].include?(val)
+        when "array"   then val.is_a?(Array)
+        when "hash", "object" then val.is_a?(Hash)
+        else true
+        end
+      end
+
+      def check_format(val, fmt)
+        case fmt
+        when "url"
+          val.start_with?("http://") || val.start_with?("https://")
+        when "ip", "ipv4"
+          FORMAT_PATTERNS["ipv4"].match?(val)
+        when "port"
+          p = Integer(val, exception: false)
+          p && p >= 1 && p <= 65_535
+        when "email"
+          FORMAT_PATTERNS["email"].match?(val)
+        when "uuid"
+          FORMAT_PATTERNS["uuid"].match?(val)
+        when "date"
+          FORMAT_PATTERNS["date"].match?(val)
+        else
+          val.match?(Regexp.new(fmt))
+        end
+      end
+
+      def flatten_keys(data, prefix = "", out = [])
+        data.each do |key, value|
+          full_key = prefix.empty? ? key.to_s : "#{prefix}.#{key}"
+          if value.is_a?(Hash)
+            flatten_keys(value, full_key, out)
+          else
+            out << full_key
+          end
+        end
+        out
+      end
+    end
+  end
+end

data/lib/dotlyte/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Dotlyte
+  VERSION = "0.1.1"
+end

data/lib/dotlyte/watcher.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Dotlyte
+  # Polling-based file watcher for DOTLYTE v2.
+  class ConfigWatcher
+    # Information about a detected change.
+    ChangeEvent = Struct.new(:path, :changed_keys, keyword_init: true)
+
+    # @param files [Array<String>] files to watch
+    # @param debounce_ms [Integer] polling interval in milliseconds
+    def initialize(files:, debounce_ms: 300)
+      @files = files
+      @interval = [debounce_ms, 100].max / 1000.0
+      @last_modified = {}
+      @on_change = nil
+      @key_watchers = {}
+      @on_error = nil
+      @previous_data = nil
+      @running = false
+      @thread = nil
+
+      @files.each do |f|
+        @last_modified[f] = File.mtime(f).to_f if File.exist?(f)
+      end
+    end
+
+    # Register general change callback.
+    def on_change(&block)
+      @on_change = block
+    end
+
+    # Watch a specific key for changes.
+    def watch_key(key, &block)
+      @key_watchers[key] = block
+    end
+
+    # Register error callback.
+    def on_error(&block)
+      @on_error = block
+    end
+
+    # Start watching with a reload proc.
+    #
+    # @param reload_fn [Proc] called to reload config, must return Hash
+    def start(reload_fn)
+      return if @running
+
+      @running = true
+      @thread = Thread.new do
+        while @running
+          poll(reload_fn)
+          sleep @interval
+        end
+      end
+      @thread.abort_on_exception = false
+    end
+
+    # Stop watching.
+    def stop
+      @running = false
+      @thread&.join(2)
+      @thread = nil
+    end
+
+    private
+
+    def poll(reload_fn)
+      changed_file = nil
+
+      @files.each do |f|
+        next unless File.exist?(f)
+
+        mtime = File.mtime(f).to_f
+        prev = @last_modified[f]
+        if prev.nil? || prev != mtime
+          @last_modified[f] = mtime
+          changed_file = f
+          break
+        end
+      end
+
+      return unless changed_file
+
+      new_data = reload_fn.call
+      return unless new_data
+
+      changed_keys = if @previous_data
+                       diff_maps(@previous_data, new_data)
+                     else
+                       flatten_keys(new_data)
+                     end
+
+      @on_change&.call(ChangeEvent.new(path: changed_file, changed_keys: changed_keys))
+
+      if @previous_data
+        changed_keys.each do |key|
+          watcher = @key_watchers[key]
+          next unless watcher
+
+          old_val = Validator.get_nested(@previous_data, key)
+          new_val = Validator.get_nested(new_data, key)
+          watcher.call(old_val, new_val)
+        end
+      end
+
+      @previous_data = new_data
+    rescue StandardError => e
+      @on_error&.call(e)
+    end
+
+    def diff_maps(old_map, new_map)
+      old_flat = flatten_map(old_map)
+      new_flat = flatten_map(new_map)
+      changed = Set.new
+
+      new_flat.each do |k, v|
+        changed.add(k) if old_flat[k] != v
+      end
+      old_flat.each_key do |k|
+        changed.add(k) unless new_flat.key?(k)
+      end
+
+      changed.to_a
+    end
+
+    def flatten_map(data, prefix = "", out = {})
+      data.each do |key, value|
+        full_key = prefix.empty? ? key.to_s : "#{prefix}.#{key}"
+        if value.is_a?(Hash)
+          flatten_map(value, full_key, out)
+        else
+          out[full_key] = value
+        end
+      end
+      out
+    end
+
+    def flatten_keys(data, prefix = "", out = [])
+      data.each do |key, value|
+        full_key = prefix.empty? ? key.to_s : "#{prefix}.#{key}"
+        if value.is_a?(Hash)
+          flatten_keys(value, full_key, out)
+        else
+          out << full_key
+        end
+      end
+      out
+    end
+  end
+end

data/lib/dotlyte.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "set"
+require "dotlyte/version"
+require "dotlyte/errors"
+require "dotlyte/coercion"
+require "dotlyte/merger"
+require "dotlyte/interpolation"
+require "dotlyte/validator"
+require "dotlyte/encryption"
+require "dotlyte/masking"
+require "dotlyte/config"
+require "dotlyte/loader"
+require "dotlyte/watcher"
+
+# DOTLYTE — The universal configuration library (v2).
+#
+# @example
+#   config = Dotlyte.load
+#   config.port           # automatically Integer
+#   config.debug          # automatically Boolean
+#   config.database.host  # dot-notation access
+#
+# @example Advanced
+#   config = Dotlyte.load(
+#     env: "production",
+#     schema: { "port" => Dotlyte::SchemaRule.new(type: "number", required: true) },
+#     strict: true,
+#     find_up: true
+#   )
+module Dotlyte
+  # Load configuration from all available sources.
+  #
+  # @param files [Array<String>, nil] Explicit files to load.
+  # @param prefix [String, nil] Environment variable prefix to strip.
+  # @param defaults [Hash, nil] Default values (lowest priority).
+  # @param sources [Array<String>, nil] Custom source order.
+  # @param env [String, nil] Environment name.
+  # @param schema [Hash<String, SchemaRule>, nil] Validation schema.
+  # @param strict [Boolean] Reject unknown keys.
+  # @param interpolate_vars [Boolean] Enable ${VAR} interpolation (default: true).
+  # @param overrides [Hash, nil] Override values (highest priority).
+  # @param debug [Boolean] Enable debug output.
+  # @param find_up [Boolean] Walk up directories to find config files.
+  # @param root_markers [Array<String>] Markers for root directory detection.
+  # @param cwd [String, nil] Working directory override.
+  # @param allow_all_env_vars [Boolean] Import all env vars without filtering.
+  # @param watch [Boolean] Watch files for changes.
+  # @param debounce_ms [Integer] Polling interval for watcher.
+  # @param custom_sources [Array<#load>] Custom source objects.
+  # @return [Config] Merged configuration object.
+  def self.load(**options)
+    Loader.new(**{
+      defaults: options[:defaults] || {}
+    }.merge(options)).load
+  end
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: dotlyte
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- DOTLYTE Contributors
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-03-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: One API to load .env, YAML, JSON, TOML, environment variables, and defaults
+  with automatic type coercion, layered priority, AES-256-GCM encryption, schema validation,
+  variable interpolation, sensitive value masking, and file watching.
+email:
+- hello@dotlyte.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/dotlyte.rb
+- lib/dotlyte/coercion.rb
+- lib/dotlyte/config.rb
+- lib/dotlyte/encryption.rb
+- lib/dotlyte/errors.rb
+- lib/dotlyte/interpolation.rb
+- lib/dotlyte/loader.rb
+- lib/dotlyte/masking.rb
+- lib/dotlyte/merger.rb
+- lib/dotlyte/validator.rb
+- lib/dotlyte/version.rb
+- lib/dotlyte/watcher.rb
+homepage: https://dotlyte.dev
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://dotlyte.dev
+  source_code_uri: https://github.com/dotlyte-io/dotlyte/tree/main/langs/ruby
+  changelog_uri: https://github.com/dotlyte-io/dotlyte/blob/main/langs/ruby/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: The universal .env and configuration library with encryption, validation,
+  and more.
+test_files: []