blockster 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f573ec1a6938fea0284ebeec0c97680e3a365a68166527d2ee9681bec9de1542
+  data.tar.gz: 89d2f15d91f0dd0754170462c79aca096c9c53eb4f9e0ad9417937373b96fa29
+SHA512:
+  metadata.gz: 674b8b8e9679c1984b2dfac1cb3bec01d9280dbe213f9ded443929a5125919762e92d9ef9052530c12ba4ec55c6c710078edeeb54a46b33edc3765454cf0020d
+  data.tar.gz: 83125b455d636b8c8f96404c5aa700bc7ef94eaf0c90a870c967bdbc11248e0aa2738886c2e5e4205338ea25718ae9576197678773ef47cc0024597c6bd11b19

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,13 @@
+AllCops:
+  TargetRubyVersion: 2.6
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-11-20
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 TODO: Write your name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,398 @@
+# Blockster
+
+Blockster is a flexible Ruby gem that provides a clean DSL for defining and initializing objects with nested attributes. It's particularly useful when working with params from complex form objects, API wrappers, or any scenario where you need to dynamically define object attributes.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'blockster'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install blockster
+```
+
+## Usage
+
+### Basic Usage
+
+```ruby
+class UserForm
+  include ActiveModel::Model
+  include ActiveModel::Attributes
+end
+
+wrapper = Blockster::Wrapper.new(UserForm)
+user = wrapper.with(username: 'js_bach', email: 'js@bach.music') do
+  attribute :username, :string
+  attribute :email, :string
+end
+
+user.username # => 'js_bach'
+user.email    # => 'js@bach.music'
+```
+
+### Root Node and Nested Attributes
+
+```ruby
+params = {
+  'user' => {
+    'username' => 'js_bach',
+    'email' => {
+      'address' => 'js@bach.music',
+      'notifications' => true
+    },
+    'preferences' => {
+      'theme' => 'dark',
+      'language' => 'en'
+    }
+  }
+}
+
+user = wrapper.with(params) do
+  root :user do
+    attribute :username, :string
+    
+    nested :email do
+      attribute :address, :string
+      attribute :notifications, :boolean
+    end
+    
+    nested :preferences do
+      attribute :theme, :string
+      attribute :language, :string
+    end
+  end
+end
+
+user.username                 # => 'js_bach'
+user.email.address           # => 'js@bach.music'
+user.preferences.theme       # => 'dark'
+```
+
+## Hash-like Behavior & ActiveRecord Integration
+
+Blockster objects behave like hashes and integrate seamlessly with ActiveRecord. This makes them perfect for form objects and API wrappers.
+
+### Hash Conversion
+
+```ruby
+params = {
+  'user' => {
+    'username' => 'js_bach',
+    'email' => {
+      'address' => 'js@bach.music',
+      'notifications' => 'true'
+    }
+  }
+}
+
+form = Blockster::Wrapper.new(UserForm).with(params) do
+  root :user do
+    attribute :username, :string
+    nested :email do
+      attribute :address, :string
+      attribute :notifications, :boolean
+    end
+  end
+end
+
+# Convert to hash
+form.to_h
+# => {
+#      username: "js_bach",
+#      email: {
+#        address: "js@bach.music",
+#        notifications: true
+#      }
+#    }
+
+# Use hash-like methods
+form.keys           # => [:username, :email]
+form.empty?         # => false
+form.each_pair do |key, value|
+  puts "#{key}: #{value}"
+end
+```
+
+### ActiveRecord Integration
+
+Blockster objects can be used directly with ActiveRecord methods thanks to proper hash conversion:
+
+```ruby
+# Create records
+user = User.create(form)
+
+# Update records
+user.update(form)
+
+# Mass assignment
+user.assign_attributes(form)
+
+# Form objects
+class UserRegistrationForm
+  include ActiveModel::Model
+  include ActiveModel::Attributes
+end
+
+class UsersController < ApplicationController
+  def create
+    # Works seamlessly with ActiveRecord
+    @user = User.new(create_params)
+    
+    if @user.save
+      redirect_to @user
+    else
+      render :new
+    end
+  end
+
+  private
+
+  def create_params
+    Blockster::Wrapper.new(UserRegistrationForm).with(user_params) do
+      root :user do
+        attribute :username, :string
+        attribute :email, :string
+        
+        nested :profile do
+          attribute :first_name, :string
+          attribute :last_name, :string
+        end
+        
+        nested :preferences do
+          attribute :theme, :string
+          attribute :notifications, :boolean
+        end
+      end
+    end
+  end
+end
+```
+
+### Nested Forms with ActiveRecord Relations
+
+```ruby
+class OrderForm
+  include ActiveModel::Model
+  include ActiveModel::Attributes
+end
+
+form = Blockster::Wrapper.new(OrderForm).with(params) do
+  root :order do
+    attribute :number, :string
+    attribute :total, :decimal
+    
+    nested :line_items do
+      attribute :product_id, :integer
+      attribute :quantity, :integer
+      attribute :price, :decimal
+    end
+    
+    nested :shipping_address do
+      attribute :street, :string
+      attribute :city, :string
+      attribute :postal_code, :string
+    end
+  end
+end
+
+# Create order with nested attributes
+order = Order.create(form)
+
+# Update existing order
+order.update(form)
+
+# Use with accepts_nested_attributes_for
+class Order < ApplicationRecord
+  has_many :line_items
+  has_one :shipping_address
+  accepts_nested_attributes_for :line_items, :shipping_address
+end
+
+# Form's hash structure matches nested attributes requirements
+order.assign_attributes(form)
+```
+
+### Working with APIs
+
+The hash conversion makes it easy to work with APIs:
+
+```ruby
+class ApiWrapper
+  include ActiveModel::Model
+  include ActiveModel::Attributes
+end
+
+response = Blockster::Wrapper.new(ApiWrapper).with(api_response) do
+  attribute :status, :string
+  
+  nested :data do
+    attribute :id, :integer
+    attribute :type, :string
+    
+    nested :attributes do
+      attribute :title, :string
+      attribute :description, :text
+      attribute :published_at, :datetime
+    end
+  end
+end
+
+# Renders as properly formatted JSON
+render json: response
+
+# Or use directly in ActiveRecord
+record = Record.create(response.data.attributes)
+```
+
+### JSON Serialization
+
+Blockster objects work seamlessly with Rails' JSON rendering:
+
+```ruby
+class Api::UsersController < ApplicationController
+  def show
+    user_data = UserService.fetch(params[:id])
+    
+    response = Blockster::Wrapper.new(ApiResponse).with(user_data) do
+      attribute :id, :integer
+      attribute :username, :string
+      
+      nested :profile do
+        attribute :first_name, :string
+        attribute :last_name, :string
+        attribute :avatar_url, :string
+      end
+      
+      nested :stats do
+        attribute :posts_count, :integer
+        attribute :followers_count, :integer
+        attribute :following_count, :integer
+      end
+    end
+
+    # Works directly with render :json
+    render json: response
+  end
+end
+```
+
+You can also explicitly convert to JSON:
+
+```ruby
+# Convert to hash first
+response.as_json
+# => { id: 1, username: "js_bach", profile: { first_name: "Johann", ... } }
+
+# Convert directly to JSON string
+response.to_json
+# => '{"id":1,"username":"js_bach","profile":{"first_name":"Johann",...}}'
+
+# Works with complex nested structures
+form = Blockster::Wrapper.new(ComplexForm).with(data) do
+  attribute :name, :string
+  nested :settings do
+    attribute :theme, :string
+    attribute :notifications, :array
+  end
+  nested :permissions do
+    attribute :roles, :array
+    nested :features do
+      attribute :enabled, :array
+    end
+  end
+end
+
+# Renders as properly formatted JSON
+render json: form
+```
+
+The JSON serialization maintains all nested structures and array values, making it perfect for API responses and client-side consumption.
+
+
+### Debugging
+
+Blockster objects have a readable inspect output that shows their current state:
+
+```ruby
+form = Blockster::Wrapper.new(UserForm).with(params) do
+  root :user do
+    attribute :username, :string
+    nested :email do
+      attribute :address, :string
+    end
+  end
+end
+
+puts form.inspect
+# => {:username=>"js_bach", :email=>{:address=>"js@bach.music"}}
+```
+
+This makes debugging in Rails console and logging much more convenient.
+
+### Configuration
+
+You can configure a default class to be used when initializing wrappers, if you are using rails, this would be a great way to configure, since the attributes api is part of rails:
+
+```ruby
+# config/initializers/blockster.rb (in Rails)
+Blockster.configure do |config|
+  config.default_class = Class.new do
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+  end
+end
+
+# Now you can initialize wrappers without providing a class
+wrapper = Blockster::Wrapper.new
+```
+
+Or use an existing class:
+
+```ruby
+class DefaultFormObject
+  include ActiveModel::Model
+  include ActiveModel::Attributes
+  
+  # Your default setup here
+end
+
+Blockster.configure do |config|
+  config.default_class = DefaultFormObject
+end
+```
+
+When initializing a wrapper, you can still override the default class:
+
+```ruby
+# Uses default class
+wrapper = Blockster::Wrapper.new
+
+# Overrides default class
+wrapper = Blockster::Wrapper.new(CustomClass)
+```
+
+Note: Either a class must be provided to the wrapper or a default class must be configured.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/yourusername/blockster.
+
+## License
+
+The gem is available as open source under the terms of the MIT License.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/blockster/configuration.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Blockster
+  class Configuration
+    attr_accessor :default_class
+
+    def initialize
+      @default_class = nil
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def default_class
+      configuration.default_class
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/blockster/context.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Blockster
+  class Context
+    def initialize(temp_class, wrapper)
+      @temp_class = temp_class
+      @wrapper = wrapper
+      @temp_class.class_eval do
+        class << self
+          attr_accessor :nested_attributes
+        end
+        @nested_attributes = {}
+      end
+    end
+
+    def root(key, &block)
+      @wrapper.instance_variable_set("@root_key", key)
+      instance_eval(&block)
+    end
+
+    def attribute(name, type, **_options)
+      @temp_class.attribute(name, type)
+    end
+
+    def nested(name, &block)
+      @temp_class.nested_attributes[name] = block
+    end
+
+    def method_missing(method_name, *args, &block)
+      if @temp_class.respond_to?(method_name, true)
+        @temp_class.send(method_name, *args, &block)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      @temp_class.respond_to?(method_name, include_private) || super
+    end
+  end
+end

data/lib/blockster/version.rb

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

data/lib/blockster/wrapper.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Blockster
+  class Wrapper
+    extend Forwardable
+    def_delegators :to_h, :each_pair, :each, :empty?, :keys
+
+    def initialize(klass = nil)
+      @klass = klass || Blockster.default_class
+      raise ArgumentError, "No class provided and no default_class configured" unless @klass
+      @root_key = nil
+    end
+
+    def with(attributes = {}, &block)
+      raise ArgumentError, "Attributes must be a hash" unless attributes.is_a?(Hash)
+
+      temp_class = Class.new(@klass)
+      context = Context.new(temp_class, self)
+      context.instance_eval(&block) if block_given?
+
+      attributes = attributes[@root_key.to_s] if @root_key && attributes.key?(@root_key.to_s)
+
+      @instance = temp_class.new
+      set_nested_attributes(symbolize_keys(attributes))
+      self
+    end
+
+    def to_h
+      return {} unless @instance
+
+      collected_attributes = {}
+
+      # Get defined attributes
+      if @instance.class.respond_to?(:attribute_types)
+        @instance.class.attribute_types.keys.each do |attr_name|
+          value = @instance.public_send(attr_name)
+          collected_attributes[attr_name.to_sym] = convert_value_to_hash(value)
+        end
+      end
+
+      # Get nested attributes
+      if @instance.class.respond_to?(:nested_attributes)
+        @instance.class.nested_attributes.each_key do |attr_name|
+          nested_value = instance_variable_get("@#{attr_name}")
+          collected_attributes[attr_name.to_sym] = nested_value&.to_h || {}
+        end
+      end
+
+      collected_attributes
+    end
+
+    def inspect
+      to_h.inspect
+    end
+
+    def to_hash
+      to_h
+    end
+
+    def as_json(options = nil)
+      to_h
+    end
+
+    def to_json(options = nil)
+      as_json(options).to_json
+    end
+
+    private
+
+    def convert_value_to_hash(value)
+      case value
+      when Wrapper
+        value.to_h
+      when Array
+        value.map { |v| convert_value_to_hash(v) }
+      else
+        value
+      end
+    end
+
+    def set_nested_attributes(attributes)
+      return unless attributes.is_a?(Hash)
+
+      @instance.class.nested_attributes&.each do |name, config|
+        # Define accessor method for nested attribute on the wrapper
+        define_singleton_method(name) do
+          instance_variable_get("@#{name}")
+        end
+
+        if attributes.key?(name)
+          klass = Class.new(@klass)
+
+          nested_wrapper = self.class.new(klass)
+          nested_wrapper.with(attributes[name], &config)
+
+          instance_variable_set("@#{name}", nested_wrapper)
+        else
+          # Initialize empty wrapper even if no attributes provided
+          klass = Class.new(@klass)
+          nested_wrapper = self.class.new(klass)
+          nested_wrapper.with({}, &config)
+          instance_variable_set("@#{name}", nested_wrapper)
+        end
+      end
+
+      # Set regular attributes
+      attributes.each do |key, value|
+        next if @instance.class.nested_attributes&.key?(key)
+        setter = "#{key}="
+        @instance.send(setter, value) if @instance.respond_to?(setter)
+      end
+    end
+
+    def symbolize_keys(hash)
+      return {} unless hash.is_a?(Hash)
+      hash.transform_keys { |key| key.to_sym rescue key }
+    end
+
+    def method_missing(method_name, *args, &block)
+      if @instance&.respond_to?(method_name)
+        result = @instance.send(method_name, *args, &block)
+        if result == @instance
+          self
+        else
+          result
+        end
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      @instance&.respond_to?(method_name, include_private) || super
+    end
+  end
+end

data/lib/blockster.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "json"
+
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+module Blockster
+  class Error < StandardError; end
+end

data/sig/blockster.rbs

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

metadata

@@ -0,0 +1,155 @@
+--- !ruby/object:Gem::Specification
+name: blockster
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Toby
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-11-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description:
+email:
+- toby@darkroom.tech
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/blockster.rb
+- lib/blockster/configuration.rb
+- lib/blockster/context.rb
+- lib/blockster/version.rb
+- lib/blockster/wrapper.rb
+- sig/blockster.rbs
+homepage: https://github.com/tobyond/blockster
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/tobyond/blockster
+  source_code_uri: https://github.com/tobyond/blockster
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: Wrap classes in a block for easy access
+test_files: []