verse-schema 1.0.0

data/lib/verse/schema/selector.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require_relative "./base"
+
+module Verse
+  module Schema
+    class Selector < Base
+      attr_accessor :values
+
+      # Initialize a new selector schema.
+      # Selector schema will select a subset of the input based on the provided values.
+      #
+      # @param values [Hash<Symbol, Class|Array<Class>>] Selected values of the selector schema.
+      # @param post_processors [PostProcessor] The post processors to apply.
+      #
+      # @return [Selector] The new dictionary.
+      def initialize(values:, post_processors: nil)
+        super(post_processors:)
+
+        @values = values.transform_values{ |v| v.is_a?(Array) ? v : [v] }
+      end
+
+      def validate(input, error_builder: nil, locals: {})
+        locals = locals.dup # Ensure they are not modified
+
+        error_builder = \
+          case error_builder
+          when String
+            ErrorBuilder.new(error_builder)
+          when ErrorBuilder
+            error_builder
+          else
+            ErrorBuilder.new
+          end
+
+        locals[:__path__] ||= []
+
+        validate_selector(input, error_builder, locals)
+      end
+
+      def dup
+        Selector.new(
+          values: @values.dup,
+          post_processors: @post_processors&.dup
+        )
+      end
+
+      def inherit?(parent_schema)
+        # Check if parent_schema is a Base and if all parent fields are present in this schema
+        return false unless parent_schema.is_a?(Selector)
+
+        @values.all? do |key, value|
+          # Check if the key exists in the parent schema and if the value is a subclass of the parent value
+          parent_value = parent_schema.values[key]
+          next false unless parent_value
+
+          (parent_value & value).size == parent_schema.size
+        end
+      end
+
+      def <=(other)
+        other == self || inherit?(other)
+      end
+
+      def <(other)
+        other != self && inherit?(other)
+      end
+
+      # rubocop:disable Style/InverseMethods
+      def >(other)
+        !self.<=(other)
+      end
+      # rubocop:enable Style/InverseMethods
+
+      # Aggregation of two schemas.
+      def +(other)
+        raise ArgumentError, "aggregate must be a selector" unless other.is_a?(Selector)
+
+        new_classes = @values.merge(other.values) do |_key, old_value, new_value|
+          # Merge the arrays of classes
+          (old_value + new_value).uniq
+        end
+
+        new_post_processors = @post_processors&.dup
+
+        if other.post_processors
+          if new_post_processors
+            new_post_processors.attach(other.post_processors)
+          else
+            new_post_processors = other.post_processors.dup
+          end
+        end
+
+        Selector.new(
+          values: new_classes,
+          post_processors: new_post_processors
+        )
+      end
+
+      def dataclass_schema
+        return @dataclass_schema if @dataclass_schema
+
+        @dataclass_schema = dup
+
+        @dataclass_schema.values = @dataclass_schema.values.transform_values do |value|
+          if value.is_a?(Array)
+            value.map do |v|
+              if v.is_a?(Base)
+                v.dataclass_schema
+              else
+                v
+              end
+            end
+          elsif value.is_a?(Base)
+            value.dataclass_schema
+          else
+            value
+          end
+        end
+
+        @dataclass_schema
+      end
+
+      protected
+
+      def validate_selector(input, error_builder, locals)
+        output = {}
+
+        selector = locals.fetch(:selector) do
+          error_builder.add(
+            nil, "selector not provided for this schema", **locals
+          )
+
+          return Result.new(nil, error_builder.errors)
+        end
+
+        fetched_values = @values.fetch(selector) do
+          @values.fetch(:__else__) do
+            error_builder.add(
+              nil,
+              "selector `#{selector}` is not valid for this schema",
+              **locals
+            )
+
+            return Result.new(output, error_builder.errors)
+          end
+        end
+
+        coalesced_value = nil
+
+        begin
+          coalesced_value =
+            Coalescer.transform(
+              input,
+              fetched_values,
+              nil,
+              locals:
+            )
+
+          if coalesced_value.is_a?(Result)
+            error_builder.combine(nil, coalesced_value.errors)
+            coalesced_value = coalesced_value.value
+          end
+        rescue Coalescer::Error => e
+          error_builder.add(nil, e.message, **locals)
+        end
+
+        Result.new(coalesced_value, error_builder.errors)
+      end
+    end
+  end
+end

data/lib/verse/schema/struct.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+require_relative "./field"
+require_relative "./result"
+require_relative "./error_builder"
+require_relative "./post_processor"
+require_relative "./invalid_schema_error"
+
+module Verse
+  module Schema
+    class Struct < Base
+      attr_accessor :fields
+
+      # Initialize a new schema.
+      #
+      # @param fields [Array<Field>] The fields of the schema.
+      # @param post_processors [PostProcessor] The post processors to apply.
+      # @param extra_fields [Boolean] Whether to allow extra fields.
+      # @param block [Proc] The block to evaluate (DSL).
+      #
+      # @return [Struct] The new schema.
+      def initialize(
+        fields: [],
+        post_processors: nil,
+        extra_fields: false,
+
+        &block
+      )
+        super(post_processors:)
+        @fields            = fields
+        @extra_fields      = extra_fields
+
+        instance_eval(&block) if block_given?
+      end
+
+      # delegated method useful to write clean DSL
+      def define(from = nil, &block)
+        Verse::Schema.define(from, &block)
+      end
+
+      def field(field_name, type = Object, **opts, &block)
+        @cache_field_name = nil
+
+        if opts[:over] && @fields.none?{ |f| f.name == opts[:over] }
+          # Ensure the `over` field exists and is
+          # already defined.
+          # There is some dependencies in validation,
+          # and I think that's the best trade-off to
+          # raise error early during schema definition.
+          raise ArgumentError, "over field #{opts[:over]} must be defined before #{field_name}"
+        end
+
+        field = Field.new(field_name, type, opts, &block)
+        @fields << field
+        field
+      end
+
+      def field?(field_name, type = Object, **opts, &block)
+        field(field_name, type, **opts, &block).optional
+      end
+
+      # rubocop:disable Style/OptionalBooleanParameter
+      def extra_fields(value = true)
+        @extra_fields = !!value
+      end
+      # rubocop:enable Style/OptionalBooleanParameter
+
+      def extra_fields? = @extra_fields
+
+      def valid?(input) = validate(input).success?
+
+      def validate(input, error_builder: nil, locals: {})
+        error_builder = \
+          case error_builder
+          when String
+            ErrorBuilder.new(error_builder)
+          when ErrorBuilder
+            error_builder
+          else
+            ErrorBuilder.new
+          end
+
+        unless input.is_a?(Hash)
+          error_builder.add(nil, "must be a hash")
+          return Result.new({}, error_builder.errors)
+        end
+
+        locals = locals.dup # Ensure they are not modified
+
+        validate_hash(input, error_builder, locals)
+      end
+
+      def dup
+        Struct.new(
+          fields: @fields.map(&:dup),
+          extra_fields: @extra_fields,
+          post_processors: @post_processors&.dup
+        )
+      end
+
+      def inherit?(parent_schema)
+        # Check if parent_schema is a Struct and if all parent fields are present in this schema
+        parent_schema.is_a?(Struct) &&
+          parent_schema.fields.all? { |parent_field|
+            child_field = @fields.find { |f2| f2.name == parent_field.name }
+            child_field&.inherit?(parent_field)
+          }
+      end
+
+      def <=(other)
+        other == self || inherit?(other)
+      end
+
+      def <(other)
+        other != self && inherit?(other)
+      end
+
+      # rubocop:disable Style/InverseMethods
+      def >(other)
+        !self.<=(other)
+      end
+      # rubocop:enable Style/InverseMethods
+
+      # Aggregation of two schemas.
+      def +(other)
+        raise ArgumentError, "aggregate must be a schema" unless other.is_a?(Struct)
+
+        new_schema = dup
+
+        other.fields.each do |f|
+          field_index = new_schema.fields.find_index{ |f2| f2.name == f.name }
+
+          if field_index
+            field = new_schema.fields[field_index]
+
+            field_type = \
+              if field.type == f.type
+                field.type
+              else
+                [field.type, f.type].flatten.uniq
+              end
+
+            if f.post_processors
+              if field.post_processors
+                field.post_processors.attach(f.post_processors)
+              else
+                field.post_processors = f.post_processors
+              end
+            end
+
+            new_schema.fields[field_index] = Field.new(
+              field.name,
+              field_type,
+              field.opts.merge(f.opts),
+              post_processors: field.post_processors
+            )
+          else
+            new_schema.fields << f.dup
+          end
+        end
+
+        new_schema
+      end
+
+      def dataclass_schema
+        return @dataclass_schema if @dataclass_schema
+
+        @dataclass_schema = dup
+
+        @dataclass_schema.fields = @dataclass_schema.fields.map do |field|
+          type = field.type
+
+          if type.is_a?(Array)
+            Field.new(
+              field.name,
+              type.map do |t|
+                next t unless t.is_a?(Base)
+
+                t.dataclass_schema
+              end,
+              field.opts.dup,
+              post_processors: field.post_processors&.dup
+            )
+          elsif type.is_a?(Base)
+            Field.new(
+              field.name,
+              type.dataclass_schema,
+              field.opts.dup,
+              post_processors: field.post_processors&.dup
+            )
+          else
+            field.dup
+          end
+        end
+
+        this = self
+        fields_map = fields.map(&:name)
+
+        @dataclass_schema.transform do |value|
+          next value unless value.is_a?(Hash)
+
+          if this.extra_fields?
+            standard_fields = value.slice(*fields_map)
+            extra_fields = value.except(*fields_map)
+
+            this.dataclass.from_raw(**standard_fields, extra_fields:)
+          else
+            this.dataclass.from_raw(**value)
+          end
+        end
+      end
+
+      # Create a value object class from the schema.
+      def dataclass(&block)
+        return @dataclass if @dataclass
+
+        fields = @fields.map(&:name)
+
+        dataclass_schema = self.dataclass_schema
+
+        fields << :extra_fields if extra_fields?
+
+        # Special case for empty schema (yeah, I know, it happens in my production code...)
+        if fields.empty?
+          @dataclass = Class.new do
+            def self.from_raw(*)=new
+            def self.schema = dataclass_schema
+
+            class_eval(&block) if block
+          end
+        else
+          @dataclass = ::Struct.new(*fields, keyword_init: true) do
+            # Redefine new method
+            define_singleton_method(:from_raw, &method(:new))
+
+            define_singleton_method(:new) do |*args, **kwargs|
+              # Use the schema to generate the hash for our record
+              if args.size > 1
+                raise ArgumentError, "You cannot pass more than one argument"
+              end
+
+              if args.size == 1
+                if kwargs.any?
+                  raise ArgumentError, "You cannot pass both a hash and keyword arguments"
+                end
+
+                kwargs = args.first
+              end
+
+              dataclass_schema.new(kwargs)
+            end
+
+            define_singleton_method(:schema){ dataclass_schema }
+
+            class_eval(&block) if block
+          end
+        end
+      end
+
+      def inspect
+        fields_string = @fields.map do |field|
+          if field.type.is_a?(Array)
+            type_str = field.type.map(&:inspect).join("|")
+          else
+            type_str = field.type.inspect
+          end
+
+          optional_marker = field.optional? ? "?" : ""
+          "#{field.name}#{optional_marker}: #{type_str}"
+        end.join(", ")
+
+        extra = @extra_fields ? ", ..." : ""
+
+        "#<struct{#{fields_string}#{extra}} 0x#{object_id.to_s(16)}>"
+      end
+
+      protected
+
+      def validate_hash(input, error_builder, locals)
+        locals[:__path__] ||= []
+
+        input = input.transform_keys(&:to_sym)
+        output = @extra_fields ? input : {}
+
+        @cache_field_name ||= @fields.map(&:key)
+
+        @fields.each do |field|
+          key_sym = field.key
+
+          exists = true
+          value = input.fetch(key_sym) { exists = false }
+
+          if (over = field.opts[:over])
+            locals[:selector] = output[over]
+          end
+
+          if exists
+            field.apply(value, output, error_builder, locals)
+          elsif field.default?
+            field.apply(field.default, output, error_builder, locals)
+          elsif field.required?
+            error_builder.add(field.key, "is required")
+          end
+        end
+
+        if @post_processors && error_builder.errors.empty?
+          output = @post_processors.call(output, nil, error_builder, **locals)
+        end
+
+        Result.new(output, error_builder.errors)
+      end
+
+    end
+  end
+end

data/lib/verse/schema/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Verse
+  module Schema
+    VERSION = "1.0.0"
+  end
+end

data/lib/verse/schema.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "schema/version"
+
+module Verse
+  module Schema
+    module_function
+
+    require_relative "schema/base"
+    require_relative "schema/coalescer"
+    require_relative "schema/post_processor"
+
+    def define(from = nil, &block)
+      if from
+        schema = from.dup
+        schema.instance_eval(&block) if block_given?
+        schema
+      else
+        Struct.new(&block)
+      end
+    end
+
+    # Define the schema as an array of values
+    def array(*values, &block)
+      if block_given?
+        raise ArgumentError, "array of value cannot be used with a block" unless values.empty?
+
+        Collection.new(values: [define(&block)])
+      else
+        raise ArgumentError, "block or type is required" if values.empty?
+
+        Collection.new(values:)
+      end
+    end
+
+    def dictionary(*values, &block)
+      if block_given?
+        raise ArgumentError, "array of value cannot be used with a block" unless values.empty?
+
+        Dictionary.new(values: [define(&block)])
+      else
+        raise ArgumentError, "block or type is required" if values.empty?
+
+        Dictionary.new(values:)
+      end
+    end
+
+    def scalar(*values) = Scalar.new(values:)
+    def selector(**values) = Selector.new(values:)
+
+    def empty
+      @empty ||= begin
+        empty_schema = Verse::Schema.define
+        empty_schema.dataclass # Generate the dataclass
+        empty_schema.freeze # Freeze to avoid modification
+        empty_schema
+      end
+    end
+
+    def rule(message, &block)
+      PostProcessor.new do |value, error|
+        case block.arity
+        when 1, -1, -2
+          error.add(opts[:key], message) unless block.call(value)
+        when 2
+          error.add(opts[:key], message) unless block.call(value, error)
+        else
+          raise ArgumentError, "invalid block arity"
+        end
+
+        value
+      end
+    end
+  end
+end

data/sig/verse/schema.rbs

@@ -0,0 +1,6 @@
+module Verse
+  module Schema
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

data/templates/README.md.erb

@@ -0,0 +1,73 @@
+# Verse::Schema
+
+## Summary
+
+Verse::Schema is a Ruby gem that provides a DSL for data validation and coercion.
+
+It is designed to be used in a context where you need to validate and coerce data coming from external sources (e.g. HTTP requests, database, etc...).
+
+Verse was initially using [dry-validation](https://dry-rb.org/gems/dry-validation/) for this purpose, but we found it too complex to use and to extend. Autodocumentation was almost impossible, and the different concepts (Schema, Params, Contract...) was not really clear in our opinion.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+  gem 'verse-schema'
+```
+
+## Concept
+
+Verse::Schema provides a flexible and opinionated way to define data structures, validate input, and coerce values. The core philosophy revolves around clear, explicit definitions and predictable transformations.
+
+**Key Principles:**
+
+*   **Validation and Coercion:** The primary goal is to ensure incoming data conforms to a defined structure and type, automatically coercing values where possible (e.g., string "123" to integer 123).
+*   **Explicit Definitions:** Schemas are defined using a clear DSL, making the expected data structure easy to understand.
+*   **Symbolized Keys:** By design, all hash keys within validated data are converted to symbols for consistency.
+*   **Coalescing:** The library attempts to intelligently convert input values to the target type defined in the schema. This simplifies handling data from various sources (like JSON strings, form parameters, etc.).
+*   **Extensibility:** While opinionated, the library allows for custom rules, post-processing transformations, and schema inheritance.
+
+**Schema Types (Wrappers):**
+
+Verse::Schema offers several base schema types to handle different data structures:
+
+*   **`Verse::Schema::Struct`:** The most common type, used for defining hash-like structures with fixed keys and specific types for each value. This is the default when using `Verse::Schema.define { ... }`. It validates the presence, type, and rules for each defined field. It can optionally allow extra fields not explicitly defined.
+*   **`Verse::Schema::Collection`:** Used for defining arrays where each element must conform to a specific type or schema. Created using `Verse::Schema.array(TypeOrSchema)` or `field(:name, Array, of: TypeOrSchema)`.
+*   **`Verse::Schema::Dictionary`:** Defines hash-like structures where keys are symbols and values must conform to a specific type or schema. Useful for key-value stores or maps. Created using `Verse::Schema.dictionary(TypeOrSchema)` or `field(:name, Hash, of: TypeOrSchema)`.
+*   **`Verse::Schema::Scalar`:** Represents a single value that can be one of several specified scalar types (e.g., String, Integer, Boolean). Created using `Verse::Schema.scalar(Type1, Type2, ...)`.
+*   **`Verse::Schema::Selector`:** A powerful type that allows choosing which schema or type to apply based on the value of another field (the "selector" field) or a provided `selector` local variable. This enables handling polymorphic data structures. Created using `Verse::Schema.selector(key1: TypeOrSchema1, key2: TypeOrSchema2, ...)` or `field(:name, { key1: TypeOrSchema1, ... }, over: :selector_field_name)`.
+
+These building blocks can be nested and combined to define complex data validation and coercion rules.
+
+
+## Usage
+
+These examples are extracted directly from the gem's specs, ensuring they are accurate and up-to-date. You can run each example directly in IRB.
+
+### Table of Contents
+
+<% chapters.each do |chapter_name, sections| %>
+- [<%= chapter_name %>](#<%= chapter_name.downcase.gsub(/[^a-z0-9\s-]/, '').gsub(/\s+/, '-') %>)
+  <% sections.each do |section_name, _| %>
+  - [<%= section_name %>](#<%= section_name.downcase.gsub(/[^a-z0-9\s-]/, '').gsub(/\s+/, '-') %>)
+  <% end %>
+<% end %>
+
+<% chapters.each do |chapter_name, sections| %>
+## <%= chapter_name %>
+
+<% sections.each do |section_name, section_examples| %>
+### <%= section_name %>
+
+<% section_examples.each do |example| %>
+```ruby
+<%= example %>
+```
+<% end %>
+<% end %>
+<% end %>
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/verse-rb/verse-schema.