domain_extractor 0.1.6 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 917b77910cd8c96304a71f1bfe4609ab9ec2a75e15eada0481cf4a1019a4d90f
-  data.tar.gz: 8a46bc97ff626af7fc835ab07c4c1efb29714e3e50a16ab7f928e33bd9ef1f32
+  metadata.gz: 4bc4d6ad831692d1251048f8b21820bb0efb10ed5b3cce641441b31afb5308b4
+  data.tar.gz: 67a96b33dc3544847af271c8bd837dbc592031bff5dac126022a147c2281460c
 SHA512:
-  metadata.gz: fdd1aca915f4a991c0dd6d1ad3cb8e1f0d2f831fa54f0c7424180cbd23da9b6cc2aa6302ca396b630f0ed70231c59a588f52bc458f4b4917abb9daf8dd8b921d
-  data.tar.gz: 7ea38ed35b6eadc2d81e8b827ef1c6d938090f177983e49f5a1347cdfc0700daa58458ecccf0c292f924b77f354a571aa4436923b307233ca2d0d0fec09454e7
+  metadata.gz: 02bca764446a3391461695cfeeaef9c6e7920308bc78768b062ae676005d3610b09733133cb10c34cd5e29dc35169f770b4789f418fd554cba762a6d5a19022a
+  data.tar.gz: eeaaa8356b306feba33e08e54c8da2926f7e052ebac5d6920f0a6f26c0dacd3bfbb0d4f863fa694377d87441564a2c1eecff764d756ce4efde0569fabf573ee2

data/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.8] - 2025-10-31
+
+### Implemented Declarative Method-style Accessors
+
+#### Added
+
+- **ParsedURL API**: Introduced intuitive method-style accessors with three variants:
+  - Default methods (e.g., `result.subdomain`) - Returns value or nil
+  - Bang methods (e.g., `result.subdomain!`) - Returns value or raises `InvalidURLError`
+  - Question methods (e.g., `result.subdomain?`) - Returns boolean true/false
+- Added `www_subdomain?` helper method to check if subdomain is specifically 'www'
+- Added `valid?` method to check if parsed result contains valid data
+- Added `to_h` and `to_hash` methods for hash conversion
+- Comprehensive documentation in `docs/PARSED_URL_API.md`
+
+#### Changed
+
+- `DomainExtractor.parse` now returns `ParsedURL` object instead of plain Hash (backward compatible via `[]` accessor)
+- `DomainExtractor.parse_batch` now returns array of `ParsedURL` objects (or nil for invalid URLs)
+
+#### Maintained
+
+- Full backward compatibility with hash-style access using `[]`
+- All existing tests continue to pass
+- No breaking changes to existing API
+
+## [0.1.7] - 2025-10-31
+
+### Added valid? method and enhanced error handling
+
+- Added `DomainExtractor.valid?` helper to allow safe URL pre-checks without raising.
+- `DomainExtractor.parse` now raises `DomainExtractor::InvalidURLError` with a clear `"Invalid URL Value"` message when the input cannot be parsed.
+
 ## [0.1.6] - 2025-10-31
 
 ### Integrate Rakefile for Release and Task Workflow Refactors

data/README.md

@@ -52,8 +52,191 @@ result[:domain]       # => 'example'
 result[:tld]          # => 'co.uk'
 result[:root_domain]  # => 'example.co.uk'
 result[:host]         # => 'www.example.co.uk'
+
+# Guard a parse with the validity helper
+url = 'https://www.example.co.uk/path?query=value'
+if DomainExtractor.valid?(url)
+  DomainExtractor.parse(url)
+else
+  # handle invalid input
+end
+
+# New intuitive method-style access
+result.subdomain      # => 'www'
+result.domain         # => 'example'
+result.host           # => 'www.example.co.uk'
+```
+
+## ParsedURL API - Intuitive Method Access
+
+DomainExtractor now returns a `ParsedURL` object that supports three accessor styles, making your intent clear and your code more robust:
+
+### Method Accessor Styles
+
+#### 1. Default Methods (Silent Nil)
+Returns the value or `nil` - perfect for exploratory code or when handling invalid data gracefully.
+
+```ruby
+result = DomainExtractor.parse('https://api.example.com')
+result.subdomain    # => 'api'
+result.domain       # => 'example'
+result.host         # => 'api.example.com'
+
+# Without subdomain
+result = DomainExtractor.parse('https://example.com')
+result.subdomain    # => nil (no error)
+result.domain       # => 'example'
+```
+
+#### 2. Bang Methods (!) - Explicit Errors
+Returns the value or raises `InvalidURLError` - ideal for production code where missing data should fail fast.
+
+```ruby
+result = DomainExtractor.parse('https://example.com')
+result.domain!      # => 'example'
+result.subdomain!   # raises InvalidURLError: "subdomain not found or invalid"
+```
+
+#### 3. Question Methods (?) - Boolean Checks
+Always returns `true` or `false` - perfect for conditional logic without exceptions.
+
+```ruby
+DomainExtractor.parse('https://dashtrack.com').subdomain?        # => false
+DomainExtractor.parse('https://api.dashtrack.com').subdomain?   # => true
+DomainExtractor.parse('https://www.dashtrack.com').www_subdomain? # => true
 ```
 
+### Quick Examples
+
+```ruby
+url = 'https://api.staging.example.com/path'
+parsed = DomainExtractor.parse(url)
+
+# Method-style access
+parsed.host           # => 'api.staging.example.com'
+parsed.subdomain      # => 'api.staging'
+parsed.domain         # => 'example'
+parsed.root_domain    # => 'example.com'
+parsed.tld            # => 'com'
+parsed.path           # => '/path'
+
+# Question methods for conditionals
+if parsed.subdomain?
+  puts "Has subdomain: #{parsed.subdomain}"
+end
+
+# Bang methods when values are required
+begin
+  subdomain = parsed.subdomain!  # Safe - has subdomain
+  domain = parsed.domain!        # Safe - has domain
+rescue DomainExtractor::InvalidURLError => e
+  puts "Missing required component: #{e.message}"
+end
+
+# Hash-style access still works (backward compatible)
+parsed[:subdomain]    # => 'api.staging'
+parsed[:host]         # => 'api.staging.example.com'
+```
+
+### Additional Examples
+
+#### Boolean Checks with Question Methods
+
+```ruby
+# Check for subdomain presence
+DomainExtractor.parse('https://dashtrack.com').subdomain?        # => false
+DomainExtractor.parse('https://api.dashtrack.com').subdomain?   # => true
+
+# Check for www subdomain specifically
+DomainExtractor.parse('https://www.dashtrack.com').www_subdomain? # => true
+DomainExtractor.parse('https://api.dashtrack.com').www_subdomain? # => false
+```
+
+#### Safe Batch Processing
+
+```ruby
+urls = [
+  'https://api.example.com',
+  'https://example.com',
+  'https://www.example.com'
+]
+
+urls.each do |url|
+  result = DomainExtractor.parse(url)
+
+  info = {
+    url: url,
+    has_subdomain: result.subdomain?,
+    is_www: result.www_subdomain?,
+    host: result.host
+  }
+
+  puts "#{info[:url]} - subdomain: #{info[:has_subdomain]}, www: #{info[:is_www]}"
+end
+```
+
+#### Production URL Validation
+
+```ruby
+def validate_api_url(url)
+  result = DomainExtractor.parse(url)
+
+  # Ensure all required components exist
+  result.subdomain!  # Must have subdomain
+  result.domain!     # Must have domain
+
+  # Additional validation
+  return false unless result.subdomain.start_with?('api')
+
+  true
+rescue DomainExtractor::InvalidURLError => e
+  puts "Validation failed: #{e.message}"
+  false
+end
+
+validate_api_url('https://api.example.com/endpoint')  # => true
+validate_api_url('https://example.com/endpoint')      # => false (no subdomain)
+validate_api_url('https://www.example.com/endpoint')  # => false (not api subdomain)
+```
+
+#### Guard Clauses with Question Methods
+
+```ruby
+def process_url(url)
+  result = DomainExtractor.parse(url)
+
+  return 'Invalid URL' unless result.valid?
+  return 'No subdomain present' unless result.subdomain?
+  return 'WWW redirect needed' if result.www_subdomain?
+
+  "Processing subdomain: #{result.subdomain}"
+end
+
+process_url('https://api.example.com')  # => "Processing subdomain: api"
+process_url('https://www.example.com')  # => "WWW redirect needed"
+process_url('https://example.com')      # => "No subdomain present"
+```
+
+#### Converting to Hash
+
+```ruby
+url = 'https://api.example.com/path'
+result = DomainExtractor.parse(url)
+
+hash = result.to_h
+# => {
+#   subdomain: "api",
+#   domain: "example",
+#   tld: "com",
+#   root_domain: "example.com",
+#   host: "api.example.com",
+#   path: "/path",
+#   query_params: {}
+# }
+```
+
+**See [docs/PARSED_URL_API.md](docs/PARSED_URL_API.md) for comprehensive documentation and real-world examples.**
+
 ## Usage Examples
 
 ### Basic Domain Parsing
@@ -105,13 +288,25 @@ urls = ['https://example.com', 'https://blog.example.org']
 results = DomainExtractor.parse_batch(urls)
 ```
 
+### Validation and Error Handling
+
+```ruby
+DomainExtractor.valid?('https://www.example.com') # => true
+
+# DomainExtractor.parse raises DomainExtractor::InvalidURLError on invalid input
+DomainExtractor.parse('not-a-url')
+# => raises DomainExtractor::InvalidURLError (message: "Invalid URL Value")
+```
+
 ## API Reference
 
 ### `DomainExtractor.parse(url_string)`
 
 Parses a URL string and extracts domain components.
 
-**Returns:** Hash with keys `:subdomain`, `:domain`, `:tld`, `:root_domain`, `:host`, `:path` or `nil`
+**Returns:** Hash with keys `:subdomain`, `:domain`, `:tld`, `:root_domain`, `:host`, `:path`
+
+**Raises:** `DomainExtractor::InvalidURLError` when the URL fails validation
 
 ### `DomainExtractor.parse_batch(urls)`
 
@@ -119,6 +314,12 @@ Parses multiple URLs efficiently.
 
 **Returns:** Array of parsed results
 
+### `DomainExtractor.valid?(url_string)`
+
+Checks if a URL can be parsed successfully without raising.
+
+**Returns:** `true` or `false`
+
 ### `DomainExtractor.parse_query_params(query_string)`
 
 Parses a query string into a hash of parameters.
@@ -146,8 +347,9 @@ track_event('page_view', source_domain: parsed[:root_domain]) if parsed
 
 ```ruby
 def internal_link?(url, base_domain)
-  parsed = DomainExtractor.parse(url)
-  parsed && parsed[:root_domain] == base_domain
+  return false unless DomainExtractor.valid?(url)
+
+  DomainExtractor.parse(url)[:root_domain] == base_domain
 end
 ```
 

data/lib/domain_extractor/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module DomainExtractor
+  class InvalidURLError < StandardError
+    DEFAULT_MESSAGE = 'Invalid URL Value'
+
+    def initialize(message = DEFAULT_MESSAGE)
+      super
+    end
+  end
+end

data/lib/domain_extractor/parsed_url.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module DomainExtractor
+  # ParsedURL wraps the parsing result and provides convenient accessor methods
+  # with support for bang (!) and question mark (?) variants.
+  #
+  # Examples:
+  #   parsed = DomainExtractor.parse('https://api.example.com')
+  #   parsed.host           # => 'api.example.com'
+  #   parsed.subdomain      # => 'api'
+  #   parsed.subdomain?     # => true
+  #   parsed.www_subdomain? # => false
+  #
+  #   parsed = DomainExtractor.parse('invalid')
+  #   parsed.host           # => nil
+  #   parsed.host?          # => false
+  #   parsed.host!          # raises InvalidURLError
+  class ParsedURL
+    # Expose the underlying hash for backward compatibility
+    attr_reader :result
+
+    # List of valid result keys that should have method accessors
+    RESULT_KEYS = %i[subdomain domain tld root_domain host path query_params].freeze
+
+    def initialize(result)
+      @result = result || {}
+      freeze
+    end
+
+    # Hash-style access for backward compatibility
+    # result[:subdomain], result[:host], etc.
+    def [](key)
+      @result[key]
+    end
+
+    # Check if the parsed result is valid (not nil/empty)
+    def valid?
+      !@result.empty?
+    end
+
+    # Special helper: check if subdomain is specifically 'www'
+    def www_subdomain?
+      @result[:subdomain] == 'www'
+    end
+
+    # Dynamically handle method calls for all result keys
+    # Supports three variants:
+    # - method_name: returns value or nil
+    # - method_name!: returns value or raises InvalidURLError
+    # - method_name?: returns boolean (true if value exists and not nil/empty)
+    def method_missing(method_name, *args, &)
+      method_str = method_name.to_s
+
+      # Handle bang methods (method_name!)
+      return handle_bang_method(method_str) if method_str.end_with?('!')
+
+      # Handle question mark methods (method_name?)
+      return handle_question_method(method_str) if method_str.end_with?('?')
+
+      # Handle regular methods (method_name)
+      key = method_name.to_sym
+      return @result[key] if RESULT_KEYS.include?(key)
+
+      super
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      method_str = method_name.to_s
+
+      # Check for www_subdomain? special case
+      return true if method_name == :www_subdomain?
+
+      # Check if it's a bang or question mark variant
+      if method_str.end_with?('!') || method_str.end_with?('?')
+        key = method_str[0...-1].to_sym
+        return true if RESULT_KEYS.include?(key)
+      end
+
+      # Check if it's a regular method
+      return true if RESULT_KEYS.include?(method_name.to_sym)
+
+      super
+    end
+
+    # Provide hash-like inspection
+    def inspect
+      "#<DomainExtractor::ParsedURL #{@result.inspect}>"
+    end
+
+    def to_s
+      @result.to_s
+    end
+
+    # Allow to_h conversion for hash compatibility
+    def to_h
+      @result.dup
+    end
+
+    # Allow to_hash as well for better Ruby compatibility
+    alias to_hash to_h
+
+    private
+
+    # Handle bang methods that raise errors for missing values
+    def handle_bang_method(method_str)
+      key = method_str[0...-1].to_sym
+      return unless RESULT_KEYS.include?(key)
+
+      value = @result[key]
+      return value if value_present?(value)
+
+      raise InvalidURLError, "#{key} not found or invalid"
+    end
+
+    # Handle question mark methods that return booleans
+    def handle_question_method(method_str)
+      key = method_str[0...-1].to_sym
+      return unless RESULT_KEYS.include?(key)
+
+      value_present?(@result[key])
+    end
+
+    # Check if a value is present (not nil and not empty for strings/hashes)
+    def value_present?(value)
+      return false if value.nil?
+      return !value.empty? if value.respond_to?(:empty?)
+
+      true
+    end
+  end
+end

data/lib/domain_extractor/parser.rb

@@ -6,6 +6,7 @@ require 'public_suffix'
 require_relative 'normalizer'
 require_relative 'result'
 require_relative 'validators'
+require_relative 'parsed_url'
 
 module DomainExtractor
   # Parser orchestrates the pipeline for url normalization, validation, and domain extraction.
@@ -13,16 +14,19 @@ module DomainExtractor
     module_function
 
     def call(raw_url)
-      uri = build_uri(raw_url)
-      return unless uri
-
-      host = uri.host&.downcase
-      return if invalid_host?(host)
+      components = extract_components(raw_url)
+      return ParsedURL.new(nil) unless components
 
-      domain = ::PublicSuffix.parse(host)
+      uri, domain, host = components
       build_result(domain: domain, host: host, uri: uri)
     rescue ::URI::InvalidURIError, ::PublicSuffix::Error
-      nil
+      ParsedURL.new(nil)
+    end
+
+    def valid?(raw_url)
+      !!extract_components(raw_url)
+    rescue ::URI::InvalidURIError, ::PublicSuffix::Error
+      false
     end
 
     def build_uri(raw_url)
@@ -38,6 +42,18 @@ module DomainExtractor
     end
     private_class_method :invalid_host?
 
+    def extract_components(raw_url)
+      uri = build_uri(raw_url)
+      return unless uri
+
+      host = uri.host&.downcase
+      return if invalid_host?(host)
+
+      domain = ::PublicSuffix.parse(host)
+      [uri, domain, host]
+    end
+    private_class_method :extract_components
+
     def build_result(domain:, host:, uri:)
       Result.build(
         subdomain: domain.trd,

data/lib/domain_extractor/result.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'parsed_url'
+
 module DomainExtractor
   # Result encapsulates the final parsed attributes and exposes a hash interface.
   module Result
@@ -10,7 +12,7 @@ module DomainExtractor
     module_function
 
     def build(**attributes)
-      {
+      hash = {
         subdomain: normalize_subdomain(attributes[:subdomain]),
         root_domain: attributes[:root_domain],
         domain: attributes[:domain],
@@ -19,6 +21,8 @@ module DomainExtractor
         path: attributes[:path] || EMPTY_PATH,
         query_params: QueryParams.call(attributes[:query])
       }.freeze
+
+      ParsedURL.new(hash)
     end
 
     def normalize_subdomain(value)

data/lib/domain_extractor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DomainExtractor
-  VERSION = '0.1.6'
+  VERSION = '0.1.8'
 end

data/lib/domain_extractor.rb

@@ -4,6 +4,8 @@ require 'uri'
 require 'public_suffix'
 
 require_relative 'domain_extractor/version'
+require_relative 'domain_extractor/errors'
+require_relative 'domain_extractor/parsed_url'
 require_relative 'domain_extractor/parser'
 require_relative 'domain_extractor/query_params'
 
@@ -12,19 +14,35 @@ require_relative 'domain_extractor/query_params'
 module DomainExtractor
   class << self
     # Parse an individual URL and extract domain attributes.
+    # Returns a ParsedURL object that supports hash-style access and method calls.
+    # Raises DomainExtractor::InvalidURLError when the URL fails validation.
     # @param url [String, #to_s]
-    # @return [Hash, nil]
+    # @return [ParsedURL]
     def parse(url)
-      Parser.call(url)
+      result = Parser.call(url)
+      raise InvalidURLError unless result.valid?
+
+      result
+    end
+
+    # Determine if a URL is considered valid by the parser.
+    # @param url [String, #to_s]
+    # @return [Boolean]
+    def valid?(url)
+      Parser.valid?(url)
     end
 
     # Parse many URLs and return their individual parse results.
+    # Returns nil for invalid URLs to maintain backward compatibility.
     # @param urls [Enumerable<String>]
-    # @return [Array<Hash, nil>]
+    # @return [Array<ParsedURL, nil>]
     def parse_batch(urls)
       return [] unless urls.respond_to?(:map)
 
-      urls.map { |url| parse(url) }
+      urls.map do |url|
+        result = Parser.call(url)
+        result.valid? ? result : nil
+      end
     end
 
     # Convert a query string into a Hash representation.

data/spec/domain_extractor_spec.rb

@@ -142,32 +142,70 @@ RSpec.describe DomainExtractor do
     end
 
     context 'with invalid URLs' do
-      it 'returns nil for malformed URLs' do
-        expect(described_class.parse('http://')).to be_nil
+      it 'raises InvalidURLError for malformed URLs' do
+        expect { described_class.parse('http://') }.to raise_error(
+          DomainExtractor::InvalidURLError,
+          'Invalid URL Value'
+        )
       end
 
-      it 'returns nil for invalid domains' do
-        expect(described_class.parse('not_a_url')).to be_nil
+      it 'raises InvalidURLError for invalid domains' do
+        expect { described_class.parse('not_a_url') }.to raise_error(
+          DomainExtractor::InvalidURLError,
+          'Invalid URL Value'
+        )
       end
 
-      it 'returns nil for IP addresses' do
-        expect(described_class.parse('192.168.1.1')).to be_nil
+      it 'raises InvalidURLError for IP addresses' do
+        expect { described_class.parse('192.168.1.1') }.to raise_error(
+          DomainExtractor::InvalidURLError,
+          'Invalid URL Value'
+        )
       end
 
-      it 'returns nil for IPv6 addresses' do
-        expect(described_class.parse('[2001:db8::1]')).to be_nil
+      it 'raises InvalidURLError for IPv6 addresses' do
+        expect { described_class.parse('[2001:db8::1]') }.to raise_error(
+          DomainExtractor::InvalidURLError,
+          'Invalid URL Value'
+        )
       end
 
-      it 'returns nil for empty string' do
-        expect(described_class.parse('')).to be_nil
+      it 'raises InvalidURLError for empty string' do
+        expect { described_class.parse('') }.to raise_error(DomainExtractor::InvalidURLError, 'Invalid URL Value')
       end
 
-      it 'returns nil for nil' do
-        expect(described_class.parse(nil)).to be_nil
+      it 'raises InvalidURLError for nil' do
+        expect { described_class.parse(nil) }.to raise_error(DomainExtractor::InvalidURLError, 'Invalid URL Value')
       end
     end
   end
 
+  describe '.valid?' do
+    it 'returns true for a normalized domain' do
+      expect(described_class.valid?('dashtrack.com')).to be(true)
+    end
+
+    it 'returns true for a full URL with subdomain and query' do
+      expect(described_class.valid?('https://www.example.co.uk/path?query=value')).to be(true)
+    end
+
+    it 'returns false for malformed URLs' do
+      expect(described_class.valid?('http://')).to be(false)
+    end
+
+    it 'returns false for invalid domains' do
+      expect(described_class.valid?('not_a_url')).to be(false)
+    end
+
+    it 'returns false for IP addresses' do
+      expect(described_class.valid?('192.168.1.1')).to be(false)
+    end
+
+    it 'returns false for nil values' do
+      expect(described_class.valid?(nil)).to be(false)
+    end
+  end
+
   describe '.parse_query_params' do
     it 'converts simple query string to hash' do
       result = described_class.parse_query_params('foo=bar')
@@ -262,7 +300,7 @@ RSpec.describe DomainExtractor do
 
       results = described_class.parse_batch(urls)
 
-      expect(results).to all(be_a(Hash))
+      expect(results).to all(be_a(DomainExtractor::ParsedURL))
       expect(results.map { |result| result[:root_domain] }).to all(eq('example.com'))
     end
 

data/spec/parsed_url_spec.rb

@@ -0,0 +1,422 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe DomainExtractor::ParsedURL do
+  describe 'method accessor styles' do
+    context 'with a valid URL with subdomain' do
+      let(:parsed) { DomainExtractor.parse('https://api.dashtrack.com/path?query=value') }
+
+      describe 'default accessor methods' do
+        it 'returns subdomain' do
+          expect(parsed.subdomain).to eq('api')
+        end
+
+        it 'returns domain' do
+          expect(parsed.domain).to eq('dashtrack')
+        end
+
+        it 'returns tld' do
+          expect(parsed.tld).to eq('com')
+        end
+
+        it 'returns root_domain' do
+          expect(parsed.root_domain).to eq('dashtrack.com')
+        end
+
+        it 'returns host' do
+          expect(parsed.host).to eq('api.dashtrack.com')
+        end
+
+        it 'returns path' do
+          expect(parsed.path).to eq('/path')
+        end
+
+        it 'returns query_params' do
+          expect(parsed.query_params).to eq({ 'query' => 'value' })
+        end
+      end
+
+      describe 'bang (!) accessor methods' do
+        it 'returns subdomain!' do
+          expect(parsed.subdomain!).to eq('api')
+        end
+
+        it 'returns domain!' do
+          expect(parsed.domain!).to eq('dashtrack')
+        end
+
+        it 'returns tld!' do
+          expect(parsed.tld!).to eq('com')
+        end
+
+        it 'returns root_domain!' do
+          expect(parsed.root_domain!).to eq('dashtrack.com')
+        end
+
+        it 'returns host!' do
+          expect(parsed.host!).to eq('api.dashtrack.com')
+        end
+      end
+
+      describe 'question mark (?) accessor methods' do
+        it 'returns true for subdomain?' do
+          expect(parsed.subdomain?).to be true
+        end
+
+        it 'returns true for domain?' do
+          expect(parsed.domain?).to be true
+        end
+
+        it 'returns true for tld?' do
+          expect(parsed.tld?).to be true
+        end
+
+        it 'returns true for root_domain?' do
+          expect(parsed.root_domain?).to be true
+        end
+
+        it 'returns true for host?' do
+          expect(parsed.host?).to be true
+        end
+      end
+    end
+
+    context 'with a valid URL without subdomain' do
+      let(:parsed) { DomainExtractor.parse('https://dashtrack.com') }
+
+      describe 'default accessor methods for nil subdomain' do
+        it 'returns nil for subdomain' do
+          expect(parsed.subdomain).to be_nil
+        end
+
+        it 'returns domain' do
+          expect(parsed.domain).to eq('dashtrack')
+        end
+
+        it 'returns host' do
+          expect(parsed.host).to eq('dashtrack.com')
+        end
+      end
+
+      describe 'bang (!) accessor methods with nil subdomain' do
+        it 'raises InvalidURLError for subdomain!' do
+          expect { parsed.subdomain! }.to raise_error(
+            DomainExtractor::InvalidURLError,
+            'subdomain not found or invalid'
+          )
+        end
+
+        it 'returns domain!' do
+          expect(parsed.domain!).to eq('dashtrack')
+        end
+      end
+
+      describe 'question mark (?) accessor methods with nil subdomain' do
+        it 'returns false for subdomain?' do
+          expect(parsed.subdomain?).to be false
+        end
+
+        it 'returns true for domain?' do
+          expect(parsed.domain?).to be true
+        end
+
+        it 'returns true for host?' do
+          expect(parsed.host?).to be true
+        end
+      end
+    end
+
+    context 'with invalid URL' do
+      let(:parsed) { DomainExtractor::ParsedURL.new(nil) }
+
+      describe 'default accessor methods' do
+        it 'returns nil for subdomain' do
+          expect(parsed.subdomain).to be_nil
+        end
+
+        it 'returns nil for domain' do
+          expect(parsed.domain).to be_nil
+        end
+
+        it 'returns nil for host' do
+          expect(parsed.host).to be_nil
+        end
+
+        it 'returns nil for root_domain' do
+          expect(parsed.root_domain).to be_nil
+        end
+      end
+
+      describe 'bang (!) accessor methods' do
+        it 'raises InvalidURLError for host!' do
+          expect { parsed.host! }.to raise_error(
+            DomainExtractor::InvalidURLError,
+            'host not found or invalid'
+          )
+        end
+
+        it 'raises InvalidURLError for domain!' do
+          expect { parsed.domain! }.to raise_error(
+            DomainExtractor::InvalidURLError,
+            'domain not found or invalid'
+          )
+        end
+
+        it 'raises InvalidURLError for subdomain!' do
+          expect { parsed.subdomain! }.to raise_error(
+            DomainExtractor::InvalidURLError,
+            'subdomain not found or invalid'
+          )
+        end
+      end
+
+      describe 'question mark (?) accessor methods' do
+        it 'returns false for subdomain?' do
+          expect(parsed.subdomain?).to be false
+        end
+
+        it 'returns false for domain?' do
+          expect(parsed.domain?).to be false
+        end
+
+        it 'returns false for host?' do
+          expect(parsed.host?).to be false
+        end
+
+        it 'returns false for root_domain?' do
+          expect(parsed.root_domain?).to be false
+        end
+      end
+    end
+  end
+
+  describe '#www_subdomain?' do
+    it 'returns true when subdomain is www' do
+      parsed = DomainExtractor.parse('https://www.dashtrack.com')
+      expect(parsed.www_subdomain?).to be true
+    end
+
+    it 'returns false when subdomain is not www' do
+      parsed = DomainExtractor.parse('https://api.dashtrack.com')
+      expect(parsed.www_subdomain?).to be false
+    end
+
+    it 'returns false when there is no subdomain' do
+      parsed = DomainExtractor.parse('https://dashtrack.com')
+      expect(parsed.www_subdomain?).to be false
+    end
+
+    it 'returns false for invalid URL' do
+      parsed = DomainExtractor::ParsedURL.new(nil)
+      expect(parsed.www_subdomain?).to be false
+    end
+  end
+
+  describe '#valid?' do
+    it 'returns true for valid URL' do
+      parsed = DomainExtractor.parse('https://dashtrack.com')
+      expect(parsed.valid?).to be true
+    end
+
+    it 'returns false for invalid URL' do
+      parsed = DomainExtractor::ParsedURL.new(nil)
+      expect(parsed.valid?).to be false
+    end
+
+    it 'returns false for empty result' do
+      parsed = DomainExtractor::ParsedURL.new({})
+      expect(parsed.valid?).to be false
+    end
+  end
+
+  describe 'hash-style access for backward compatibility' do
+    let(:parsed) { DomainExtractor.parse('https://www.example.co.uk/path?query=value') }
+
+    it 'supports hash-style access with []' do
+      expect(parsed[:subdomain]).to eq('www')
+      expect(parsed[:domain]).to eq('example')
+      expect(parsed[:tld]).to eq('co.uk')
+      expect(parsed[:root_domain]).to eq('example.co.uk')
+      expect(parsed[:host]).to eq('www.example.co.uk')
+      expect(parsed[:path]).to eq('/path')
+    end
+  end
+
+  describe '#to_h and #to_hash' do
+    let(:parsed) { DomainExtractor.parse('https://api.example.com') }
+
+    it 'converts to hash with to_h' do
+      hash = parsed.to_h
+      expect(hash).to be_a(Hash)
+      expect(hash[:subdomain]).to eq('api')
+      expect(hash[:domain]).to eq('example')
+    end
+
+    it 'converts to hash with to_hash' do
+      hash = parsed.to_hash
+      expect(hash).to be_a(Hash)
+      expect(hash[:subdomain]).to eq('api')
+      expect(hash[:domain]).to eq('example')
+    end
+  end
+
+  describe 'integration examples from requirements' do
+    it 'handles example: DomainExtractor.parse(url).host' do
+      url = 'https://www.example.co.uk/path?query=value'
+      expect(DomainExtractor.parse(url).host).to eq('www.example.co.uk')
+    end
+
+    it 'handles example: DomainExtractor.parse(url).domain' do
+      url = 'https://www.example.co.uk/path?query=value'
+      expect(DomainExtractor.parse(url).domain).to eq('example')
+    end
+
+    it 'handles example: DomainExtractor.parse(url).subdomain' do
+      url = 'https://www.example.co.uk/path?query=value'
+      expect(DomainExtractor.parse(url).subdomain).to eq('www')
+    end
+
+    it 'handles example: no subdomain returns false' do
+      expect(DomainExtractor.parse('https://dashtrack.com').subdomain?).to be false
+    end
+
+    it 'handles example: with subdomain returns true' do
+      expect(DomainExtractor.parse('https://api.dashtrack.com').subdomain?).to be true
+    end
+
+    it 'handles example: www_subdomain? returns true for www' do
+      expect(DomainExtractor.parse('https://www.dashtrack.com').www_subdomain?).to be true
+    end
+
+    it 'handles example: www_subdomain? returns false for non-www' do
+      expect(DomainExtractor.parse('https://dashtrack.com').www_subdomain?).to be false
+    end
+
+    it 'handles example: host returns value for valid URL' do
+      expect(DomainExtractor.parse('https://api.dashtrack.com').host).to eq('api.dashtrack.com')
+    end
+
+    it 'handles example: domain returns nil for invalid URL' do
+      # Parser returns ParsedURL with empty result for invalid URLs
+      # But parse() raises error, so we need to construct directly
+      parsed = DomainExtractor::ParsedURL.new(nil)
+      expect(parsed.domain).to be_nil
+    end
+  end
+
+  describe 'edge cases' do
+    context 'with multi-part TLD' do
+      let(:parsed) { DomainExtractor.parse('shop.example.com.au') }
+
+      it 'correctly identifies subdomain' do
+        expect(parsed.subdomain).to eq('shop')
+      end
+
+      it 'correctly identifies tld' do
+        expect(parsed.tld).to eq('com.au')
+      end
+
+      it 'subdomain? returns true' do
+        expect(parsed.subdomain?).to be true
+      end
+    end
+
+    context 'with nested subdomains' do
+      let(:parsed) { DomainExtractor.parse('api.staging.example.com') }
+
+      it 'returns nested subdomain' do
+        expect(parsed.subdomain).to eq('api.staging')
+      end
+
+      it 'subdomain? returns true' do
+        expect(parsed.subdomain?).to be true
+      end
+
+      it 'subdomain! returns the value' do
+        expect(parsed.subdomain!).to eq('api.staging')
+      end
+    end
+
+    context 'with empty path' do
+      let(:parsed) { DomainExtractor.parse('https://example.com') }
+
+      it 'returns empty string for path' do
+        expect(parsed.path).to eq('')
+      end
+
+      it 'path? returns false for empty path' do
+        expect(parsed.path?).to be false
+      end
+    end
+
+    context 'with query params' do
+      let(:parsed) { DomainExtractor.parse('https://example.com?foo=bar&baz=qux') }
+
+      it 'returns query_params hash' do
+        expect(parsed.query_params).to eq({ 'foo' => 'bar', 'baz' => 'qux' })
+      end
+
+      it 'query_params? returns true' do
+        expect(parsed.query_params?).to be true
+      end
+
+      it 'query_params! returns the hash' do
+        expect(parsed.query_params!).to eq({ 'foo' => 'bar', 'baz' => 'qux' })
+      end
+    end
+
+    context 'with empty query params' do
+      let(:parsed) { DomainExtractor.parse('https://example.com') }
+
+      it 'returns empty hash for query_params' do
+        expect(parsed.query_params).to eq({})
+      end
+
+      it 'query_params? returns false for empty hash' do
+        expect(parsed.query_params?).to be false
+      end
+    end
+  end
+
+  describe '#respond_to_missing?' do
+    let(:parsed) { DomainExtractor.parse('https://api.example.com') }
+
+    it 'responds to valid accessor methods' do
+      expect(parsed).to respond_to(:host)
+      expect(parsed).to respond_to(:domain)
+      expect(parsed).to respond_to(:subdomain)
+    end
+
+    it 'responds to bang methods' do
+      expect(parsed).to respond_to(:host!)
+      expect(parsed).to respond_to(:domain!)
+      expect(parsed).to respond_to(:subdomain!)
+    end
+
+    it 'responds to question mark methods' do
+      expect(parsed).to respond_to(:host?)
+      expect(parsed).to respond_to(:domain?)
+      expect(parsed).to respond_to(:subdomain?)
+    end
+
+    it 'responds to www_subdomain?' do
+      expect(parsed).to respond_to(:www_subdomain?)
+    end
+
+    it 'does not respond to invalid methods' do
+      expect(parsed).not_to respond_to(:invalid_method)
+      expect(parsed).not_to respond_to(:not_a_real_method!)
+    end
+  end
+
+  describe '#inspect' do
+    it 'provides meaningful inspection output' do
+      parsed = DomainExtractor.parse('https://api.example.com')
+      output = parsed.inspect
+      expect(output).to include('DomainExtractor::ParsedURL')
+      expect(output).to include('subdomain')
+      expect(output).to include('api')
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: domain_extractor
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.8
 platform: ruby
 authors:
 - OpenSite AI
@@ -41,13 +41,16 @@ files:
 - LICENSE.txt
 - README.md
 - lib/domain_extractor.rb
+- lib/domain_extractor/errors.rb
 - lib/domain_extractor/normalizer.rb
+- lib/domain_extractor/parsed_url.rb
 - lib/domain_extractor/parser.rb
 - lib/domain_extractor/query_params.rb
 - lib/domain_extractor/result.rb
 - lib/domain_extractor/validators.rb
 - lib/domain_extractor/version.rb
 - spec/domain_extractor_spec.rb
+- spec/parsed_url_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/opensite-ai/domain_extractor
 licenses: