disposita 0.1.0

data/lib/disposita/types.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Disposita
+  # Configuration-oriented type helpers used by schema declarations.
+  #
+  # Disposita intentionally does not implement a general-purpose runtime type
+  # system. Ruby classes such as +String+ and +Integer+ are accepted directly;
+  # these helpers cover configuration-specific shapes that Ruby does not express
+  # conveniently, such as booleans, finite enums and homogeneous arrays.
+  #
+  # Types participate in both validation and coercion. This matters especially
+  # for environment variables, where every input starts as a String.
+  #
+  # @example
+  #   Disposita.define(:app) do
+  #     setting :enabled, type: Disposita::Types.boolean, default: true
+  #     setting :transport, type: Disposita::Types.enum(:ssh, :https)
+  #     setting :hosts, type: Disposita::Types.array(String), default: []
+  #   end
+  module Types
+    # Boolean configuration type supporting conventional textual forms.
+    #
+    # Resolved values are strictly +true+ or +false+. Coercion accepts common
+    # ENV-friendly strings such as +"true"+, +"yes"+, +"1"+, +"false"+,
+    # +"no"+ and +"0"+ case-insensitively.
+    class Boolean
+      # @param value [Object] candidate resolved value.
+      # @return [Boolean] whether +value+ is exactly +true+ or +false+.
+      def self.valid?(value) = [true, false].include?(value)
+
+      # Coerces conventional string representations to a Ruby boolean.
+      #
+      # @param value [Object] raw configuration value.
+      # @return [Boolean]
+      # @raise [ArgumentError] when no unambiguous boolean conversion exists.
+      def self.coerce(value)
+        return value if valid?(value)
+        return true if value.is_a?(String) && %w[true 1 yes on].include?(value.strip.downcase)
+        return false if value.is_a?(String) && %w[false 0 no off].include?(value.strip.downcase)
+
+        raise ArgumentError, "cannot coerce #{value.inspect} to boolean"
+      end
+
+      # @return [String] concise name used in schema diagnostics.
+      def self.inspect = "Boolean"
+    end
+
+    # Type representing a finite set of accepted configuration values.
+    #
+    # String inputs may be coerced to Symbol members, which makes enums useful
+    # for values arriving from ENV or YAML while preserving symbolic runtime
+    # APIs.
+    class Enum
+      # @return [Array<Object>] allowed values.
+      attr_reader :values
+
+      # @param values [Array<Object>] finite non-empty set of allowed values.
+      # @raise [ArgumentError] if the set is empty.
+      def initialize(values)
+        raise ArgumentError, "enum requires at least one value" if values.empty?
+
+        @values = values.freeze
+        freeze
+      end
+
+      # @param value [Object] candidate value.
+      # @return [Boolean] whether +value+ belongs to the enum.
+      def valid?(value) = values.include?(value)
+
+      # Coerces a String to a matching Symbol member when possible.
+      #
+      # @param value [Object] raw configuration value.
+      # @return [Object] matching enum member.
+      # @raise [ArgumentError] when +value+ cannot match any allowed member.
+      def coerce(value)
+        return value if valid?(value)
+
+        if value.is_a?(String)
+          symbol = value.to_sym
+          return symbol if values.include?(symbol)
+          return value if values.include?(value)
+        end
+
+        raise ArgumentError, "expected one of #{values.map(&:inspect).join(', ')}"
+      end
+
+      # @return [String] human-readable representation used in diagnostics.
+      def inspect = "enum(#{values.map(&:inspect).join(', ')})"
+    end
+
+    # Type representing an Array whose members share another declared type.
+    #
+    # Member types use the same adapter rules as top-level settings, so Ruby
+    # classes and other Disposita type helpers can be nested.
+    class ArrayOf
+      # @return [Object] declared member type.
+      attr_reader :member_type
+
+      # @param member_type [Object] type expected for every array member.
+      def initialize(member_type)
+        @member_type = member_type
+        freeze
+      end
+
+      # @param value [Object] candidate array.
+      # @return [Boolean] whether +value+ is an Array and every member is valid.
+      def valid?(value)
+        value.is_a?(Array) && value.all? { |member| Internal::TypeAdapter.valid?(member_type, member) }
+      end
+
+      # Coerces every array member using the declared member type.
+      #
+      # @param value [Object] raw configuration value.
+      # @return [Array] coerced members.
+      # @raise [ArgumentError] if +value+ is not an Array or a member cannot be
+      #   coerced.
+      def coerce(value)
+        raise ArgumentError, "expected Array" unless value.is_a?(Array)
+
+        value.map { |member| Internal::TypeAdapter.coerce(member_type, member) }
+      end
+
+      # @return [String] human-readable representation used in diagnostics.
+      def inspect = "Array[#{member_type.inspect}]"
+    end
+
+    module_function
+
+    # Returns the built-in boolean type object.
+    #
+    # @return [Class<Disposita::Types::Boolean>]
+    def boolean = Boolean
+
+    # Builds a finite enum type.
+    #
+    # @param values [Array<Object>] accepted runtime values.
+    # @return [Disposita::Types::Enum]
+    # @raise [ArgumentError] when no values are supplied.
+    # @example
+    #   type = Disposita::Types.enum(:ssh, :https)
+    #   type.coerce("https") # => :https
+    def enum(*values) = Enum.new(values)
+
+    # Builds a homogeneous array type.
+    #
+    # @param member_type [Object] type required for every member.
+    # @return [Disposita::Types::ArrayOf]
+    # @example
+    #   Disposita::Types.array(String)
+    def array(member_type) = ArrayOf.new(member_type)
+  end
+end

data/lib/disposita/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Disposita
+  # Current Disposita version.
+  VERSION = "0.1.0"
+end

data/lib/disposita.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "disposita/version"
+require_relative "disposita/error"
+require_relative "disposita/internal/definition"
+require_relative "disposita/internal/type_adapter"
+require_relative "disposita/internal/schema_builder"
+require_relative "disposita/internal/deep_merge"
+require_relative "disposita/internal/hash_tools"
+require_relative "disposita/types"
+require_relative "disposita/source"
+require_relative "disposita/formats/yaml"
+require_relative "disposita/sources/hash"
+require_relative "disposita/sources/environment"
+require_relative "disposita/sources/file"
+require_relative "disposita/paths"
+require_relative "disposita/configuration"
+require_relative "disposita/schema"
+
+# Declarative, typed and layered configuration infrastructure for Ruby.
+#
+# Disposita lets a library or application own the meaning of its settings while
+# delegating schema definition, coercion, validation, source precedence and
+# persistence to a reusable configuration engine. Defining a schema does not
+# read files, inspect ENV or mutate global state; consumers explicitly choose
+# which sources participate when configuration is resolved.
+#
+# @example Define and resolve a small schema
+#   AppConfig = Disposita.define(:app, version: 1) do
+#     namespace :server do
+#       setting :host, type: String, default: "localhost"
+#       setting :port, type: Integer, default: 3000
+#     end
+#   end
+#
+#   config = AppConfig.resolve([])
+#   config.server.host # => "localhost"
+#   config.server.port # => 3000
+#
+# @example Combine a file layer with environment overrides
+#   schema.load(
+#     sources: [Disposita::Sources::File.new(".app.yml", name: :project)],
+#     env: ENV,
+#     env_prefix: "APP"
+#   )
+#
+# @see Disposita::Schema
+# @see Disposita::Configuration
+# @see Disposita::Source
+module Disposita
+  module_function
+
+  # Defines an independent configuration schema owned by the caller.
+  #
+  # The block is evaluated by Disposita's schema DSL. A schema is only a
+  # description until the caller explicitly resolves it against one or more
+  # sources, so this method is safe to use while loading a gem or application.
+  #
+  # @param name [String, Symbol] stable logical name of the consumer-owned
+  #   configuration domain.
+  # @param version [Integer] version of the persisted schema format. Versioning
+  #   belongs to the consumer and is independent from Disposita's gem version.
+  # @yield DSL used to declare namespaces and settings.
+  # @return [Disposita::Schema] immutable schema that can be resolved, inspected
+  #   and used to validate writes.
+  # @raise [Disposita::SchemaError] if no block is supplied or the DSL contains
+  #   an invalid schema definition.
+  #
+  # @example
+  #   SCMConfig = Disposita.define(:scm, version: 1) do
+  #     namespace :git do
+  #       setting :remote, type: String, default: "origin"
+  #       setting :transport,
+  #               type: Disposita::Types.enum(:ssh, :https),
+  #               default: :ssh
+  #     end
+  #   end
+  def define(name, version: 1, &block)
+    raise SchemaError, "a schema block is required" unless block
+
+    builder = Internal::SchemaBuilder.new
+    builder.instance_eval(&block)
+    Schema.new(name: name, version: version, settings: builder.settings)
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: disposita
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Rubcraft
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Disposita provides consumer-owned configuration schemas, typed values,
+  coercion, validation, layered resolution, safe YAML persistence,
+  environment overrides, cross-platform paths and secret-aware diagnostics.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/disposita.rb
+- lib/disposita/configuration.rb
+- lib/disposita/error.rb
+- lib/disposita/formats/yaml.rb
+- lib/disposita/internal/deep_merge.rb
+- lib/disposita/internal/definition.rb
+- lib/disposita/internal/hash_tools.rb
+- lib/disposita/internal/schema_builder.rb
+- lib/disposita/internal/type_adapter.rb
+- lib/disposita/paths.rb
+- lib/disposita/schema.rb
+- lib/disposita/source.rb
+- lib/disposita/sources/environment.rb
+- lib/disposita/sources/file.rb
+- lib/disposita/sources/hash.rb
+- lib/disposita/types.rb
+- lib/disposita/version.rb
+homepage: https://github.com/Rubcraft/disposita
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/Rubcraft/disposita
+  changelog_uri: https://github.com/Rubcraft/disposita/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Rubcraft/disposita/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Declarative, typed and layered configuration for Ruby
+test_files: []