guide-rail 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 64fe06eb07e4fc4e1e9865e8f7474185539e90bd2b695c102ea9771045d741b6
+  data.tar.gz: cb166474c8ae652c3b0ee6ce95b6deb655f8b1270b65d0fe661dc3acbf1e2905
+SHA512:
+  metadata.gz: 7aa7500eb8a49610ac77071bc42ed51b5711801293c85f418e6106fc8ed218dab4800ed6ec1c6b0025ea7a00a2a1e780a52999b01d31c71359b7b43020332b39
+  data.tar.gz: d6077ef99145c833e73a3f485094ee658ab1c9c924a1ec34f46d634f5d67b3618d187f010d8d19c2bf2cdba3d5759171fd4d1551ff1546ed0c9f5f0a4ef338ab

data/.editorconfig

@@ -0,0 +1,5 @@
+[*]
+indent_size = 2
+indent_style = space
+trim_trailing_whitespace = true
+insert_final_newline = true

data/.rubocop.yml

@@ -0,0 +1,5 @@
+require:
+  - standard
+
+inherit_gem:
+  standard: config/base.yml

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.1

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+## [0.1.0] - 2025-07-05
+
+- Initial release
+
+## [0.0.0] - 2025-06-29
+
+- concept

data/LICENSE

@@ -0,0 +1,9 @@
+Copyright 2025 wtnabe
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,147 @@
+# GuideRail
+
+[![Gem Version](https://badge.fury.io/rb/guide-rail.svg)](https://badge.fury.io/rb/guide-rail)
+[![CI](https://github.com/wtnabe/guide-rail/actions/workflows/test.yml/badge.svg)](https://github.com/wtnabe/guide-rail/actions/workflows/test.yml)
+
+**GuideRail** is a opinionated powerful factory library for Ruby that transforms various data sources into safe, immutable `Data` objects. By leveraging the robust validation capabilities of `dry-schema`, it provides a clear and declarative way to define, validate, and instantiate your data structures.
+
+It acts as a "guide rail," ensuring that data flowing into your application (e.g., from controller params or API responses) is valid and conforms to a defined structure before being used in your domain logic or views.
+
+## Key Features
+
+- **Powerful Validation**: Built on top of `dry-schema` for comprehensive data validation and coercion. The generated Data object can be guaranteed to have the expected attribute. ( If you specify required )
+- **Immutable Data Objects**: Generates instances of Ruby's native `Data` class, preventing accidental state mutations.
+- **Flexible Input**: Accepts various data sources, including Hashes, Structs, and ActiveModel-like objects.
+- **Simple and Extendable Factory Class**: A concise and intuitive DSL for defining data factories.
+- **View-Friendly Rendering**: An optional `renderable` mode provides `nil`-safe default values, perfect for views.
+- **Functional-Programming-Friendly**: An optional `monadic` mode provides integration with functional programming paradigms by returning `Dry::Monads::Result` objects.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'guide-rail'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+or
+
+```bash
+$ bundle add guide-rail
+```
+
+## Usage
+
+### Most Simple
+
+```ruby
+require "guide-rail"
+
+SimpleNonNullableSchema = Dry::Schema.Params do
+  required(:name).filled(:string)
+end
+
+class SimpleNonNullableCreator
+  extend GuideRail
+
+  schema SimpleNonNullableSchema
+  class_name :SimpleNonNullable
+end
+
+SimpleNonNullableCreator.from(name: nil) # => #<Dry::Schema::Result{name: nil} errors={name: ["must be filled"]} path=[]>
+SimpleNonNullableCreator.from(name: "John") # => #<data SimpleNonNullable name="John">
+SimpleNonNullableCreator.from({}) # => #<Dry::Schema::Result{} errors={name: ["is missing"]} path=[]>
+```
+
+### Nullable Object with `renderable` option
+
+```ruby
+SimpleNullableSchema = Dry::Schema.Params do
+  required(:name).maybe(:string)
+end
+
+class SimpleRenderableCreator
+  extend GuideRail
+
+  schema SimpleNullableSchema
+  class_name :SimpleRenderable
+  renderable true
+end
+
+SimpleRenderableCreator.from(name: nil) # => #<data SimpleRenderable name="">
+SimpleRenderableCreator.from(name: "John") # => #<data SimpleRenderable name="John">
+SimpleRenderableCreator.from({}) # => #<Dry::Schema::Result{} errors={name: ["is missing"]} path=[]>
+```
+
+### extendable Data class
+
+You can give a block to Creator class, the generated Data class can be extended by the block ( applying to `define` class method ).
+
+This can be used to define decorator methods and conversion processes, so the generated Data class can also be used as a so-called ViewModel.
+
+```ruby
+OptionalSchema = Dry::Schema.Params do
+  optional(:name).filled(:string)
+end
+
+class OptionalAndYieldAccepter
+  extend GuideRail
+
+  class_name :ExtendedData
+  schema OptionalSchema
+  renderable true
+
+  yield_block do
+    alias_method :name_orig, :name
+    define_method :name do
+      "decorated #{name_orig}"
+    end
+  end
+end
+
+OptionalAndYieldAccepter.from({}).name.start_with? "decorated" # => true
+```
+
+### Monadic mode
+
+```ruby
+SimpleNonNullableSchema = Dry::Schema.Params do
+  required(:name).filled(:string)
+end
+
+class SimpleNonNullableMonadicCreator
+  extend GuideRail
+
+  schema SimpleNonNullableSchema
+  class_name :SimpleNonNullableMonadic
+  monadic true
+end
+
+SimpleNonNullableMonadicCreator.from({}).either(
+  ->(e) { e.value! },
+  ->(e) { e.errors.to_h }
+)
+# => {name: ["is missing"]}
+```
+
+## Not Implemented
+
+ * i18n support
+ * Railtie support
+ * Transparent conversion of errors
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/wtnabe/guide-rail.

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create(:spec) do |t|
+  t.libs << "spec"
+  t.test_globs = ["spec/**/*_spec.rb"]
+end
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/lib/guide-rail.rb

@@ -0,0 +1 @@
+require_relative "guide_rail"

data/lib/guide_rail/version.rb

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

data/lib/guide_rail.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "dry/schema"
+require "dry/monads"
+require_relative "guide_rail/version"
+
+Dry::Schema.load_extensions(:monads)
+
+module GuideRail
+  include Dry::Monads[:result]
+
+  #
+  # @param [String|Symbol] klass
+  #
+  def class_name(klass)
+    @_class = klass
+  end
+
+  #
+  # @param [Dry::Schema::Params] schema
+  #
+  def schema(schema)
+    @_schema = schema
+  end
+
+  #
+  # @param [bool] bool
+  #
+  def monadic(bool)
+    @_monadic = bool
+  end
+
+  #
+  # @param [bool] bool
+  #
+  def renderable(bool)
+    @_renderable = bool
+  end
+
+  #
+  # @param [Proc] block
+  #
+  def yield_block(&block)
+    @_block = block
+  end
+
+  #
+  # @return [Data]
+  #
+  def create_class!
+    Object.const_get @_class
+  rescue NameError
+    @_attrs = @_schema.key_map.to_a.map { |k| k.name.to_sym }
+    klass = Data.define(*@_attrs, &@_block)
+    Object.const_set(@_class, klass)
+    klass
+  end
+
+  #
+  # @param [Hash] data
+  # @return [Data|Dry::Schema::Result|Dry::Monads::Result<Data|Dry::Schema::Result>]
+  #
+  def from(data)
+    acceptance = accept(data)
+    create_class!
+    result = @_schema.call(acceptance)
+    Object.const_get @_class
+
+    if result.success?
+      new_value = Object.const_get(@_class).new(
+        *(
+          if @_renderable
+            to_renderable(acceptance)
+          else
+            acceptance
+          end
+        ).values_at(*@_attrs).map(&:freeze)
+      )
+
+      @_monadic ? Success(new_value) : new_value
+    else
+      @_monadic ? result.to_monad : result
+    end
+  end
+
+  #
+  # @param [untyped] data
+  # @return [Hash]
+  #
+  def accept(data)
+    if data.respond_to? :attributes
+      # ActiveModel
+      data.attributes.transform_keys(&:to_sym)
+    elsif data.respond_to? :to_h
+      # Struct, OpenStruct, Hashie, etc...
+      data.to_h
+    elsif data.is_a? Hash
+      data
+    elsif data.respond_to? :to_hash
+      # Hash convertible
+      data.to_hash
+    end
+  end
+
+  #
+  # @param [Hash] original
+  # @param [Hash] default
+  # @return [Hash]
+  #
+  def to_renderable(original, default = renderable_default)
+    default.merge(original) { |key, d_val, o_val|
+      o_val.nil? ? d_val : o_val
+    }
+  end
+
+  #
+  # @param [Array] key_map
+  # @return [Hash]
+  #
+  def renderable_default(key_map = @_schema.key_map.dump)
+    Hash[*key_map.map { |e|
+      case e
+      when Hash
+        [e.keys.first.to_sym, renderable_default(e.values.first)]
+      when String
+        [e.to_sym, ""]
+      end
+    }.flatten]
+  end
+end

data/sig/guide-rail.rbs

@@ -0,0 +1,11 @@
+module GuideRail
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  def class_name: (klass: String | Symbol) -> String | Symbol
+  def schema: (schema: Dry::Schema::Params) -> Dry::Schema::Params
+  def renderable: (bool: bool) -> bool
+  def yield_block: { } -> void
+  def create_class!: () -> Data
+  def from: (data: Hash) -> Data | Dry::Schema::Result | Dry::Monads::Result<Data | Dry::Schema::Result>
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: guide-rail
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- wtnabe
+bindir: exe
+cert_chain: []
+date: 2025-07-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-schema
+  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'
+- !ruby/object:Gem::Dependency
+  name: dry-monads
+  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: GuideRail transforms various data sources into safe, immutable `Data`
+  objects. By leveraging the robust validation capabilities of `dry-schema`, it provides
+  a clear and declarative way to define, validate, and instantiate your data structures.
+email:
+- 18510+wtnabe@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".editorconfig"
+- ".rubocop.yml"
+- ".standard.yml"
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/guide-rail.rb
+- lib/guide_rail.rb
+- lib/guide_rail/version.rb
+- sig/guide-rail.rbs
+homepage: https://github.com/wtnabe/guide-rail
+licenses: []
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/wtnabe/guide-rail
+  source_code_uri: https://github.com/wtnabe/guide-rail
+  changelog_uri: https://github.com/wtnabe/guide-rail/blob/main/CHANGELOG.md
+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: 3.6.2
+specification_version: 4
+summary: A factory library to create safe, immutable Data objects from various sources
+  using dry-schema and Data ( Ruby 3.2+ ).
+test_files: []