domain_extractor 0.1.7 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ada4e5f18e79e144f7fc82e53c4f9cffc5b750f32ac579e5533ad50a3c4ee07b
-  data.tar.gz: 7213bcce37c9956ff164411433e929ad7ae8f0953e3101a2bd93d7f761ab37dc
+  metadata.gz: 2b919b52fe3fda7edf9738141e66e2acbcb2458d276800cb62b48c4c34d3b914
+  data.tar.gz: be02cf195da3a6a9da51136140f1487e96c026b22f1a300825d15733eb493acf
 SHA512:
-  metadata.gz: 9eb86f40c167428966581ee0446db8ef03994680904c7712f22b75e4117304bce59928ef16ba29143da6ad2046011f0cc5f428a54405922cfeab21e06ea9a06f
-  data.tar.gz: cae58aa85a024e3e10a236041476775e887896d1bb96af35a6e6a14f5cb97f2f2caefff7a2804c02ec9885fbcb4e92e48cdef2bbc2e9bfcfecd7a6b58e47e6ad
+  metadata.gz: 981d228483ba55b85834c38df3146a47018be6b7456053add7356a74f15d33cd27038d50682e5488f14ff9dfd09ef463bee1bbd6f7c486d9e9698dd305543738
+  data.tar.gz: e320e6d216196664de8f73b18be95746863b60fba99e496dc166ebd2f051afdf475d56f7d7a30dc6910e66d380e5b03b7d472730698905ed5b83e87aba3eb4e5

data/CHANGELOG.md

@@ -7,6 +7,32 @@ 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

data/README.md

@@ -60,8 +60,209 @@ if DomainExtractor.valid?(url)
 else
   # handle invalid input
 end
+
+# New intuitive method-style access
+result.subdomain      # => 'www'
+result.domain         # => 'example'
+result.host           # => 'www.example.co.uk'
+
+# Opt into strict parsing when needed
+DomainExtractor.parse!('notaurl')
+# => raises DomainExtractor::InvalidURLError: Invalid URL Value
+```
+
+## 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
+
 ```
 
+#### Handling Unknown or Invalid Data
+
+```ruby
+# Default accessors fail silently with nil
+DomainExtractor.parse(nil).domain                 # => nil
+DomainExtractor.parse('').host                    # => nil
+DomainExtractor.parse('asdfasdfds').domain        # => nil
+
+# Boolean checks never raise
+DomainExtractor.parse(nil).subdomain?             # => false
+DomainExtractor.parse('').domain?                 # => false
+DomainExtractor.parse('https://dashtrack.com').subdomain? # => false
+
+# Bang methods raise when a component is missing
+DomainExtractor.parse('').host!                   # => raises DomainExtractor::InvalidURLError
+DomainExtractor.parse('asdfasdfds').domain!       # => raises DomainExtractor::InvalidURLError
+
+# Strict parsing helper mirrors legacy behaviour
+DomainExtractor.parse!('asdfasdfds')              # => raises DomainExtractor::InvalidURLError
+```
+
+#### 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

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.
@@ -14,12 +15,12 @@ module DomainExtractor
 
     def call(raw_url)
       components = extract_components(raw_url)
-      return unless components
+      return ParsedURL.new(nil) unless components
 
       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)

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.7'
+  VERSION = '0.1.9'
 end

data/lib/domain_extractor.rb

@@ -5,6 +5,7 @@ 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'
 
@@ -13,11 +14,26 @@ require_relative 'domain_extractor/query_params'
 module DomainExtractor
   class << self
     # Parse an individual URL and extract domain attributes.
-    # Raises DomainExtractor::InvalidURLError when the URL fails validation.
+    # Returns a ParsedURL object that supports hash-style access and method calls.
+    # For invalid inputs the returned ParsedURL will be marked invalid and all
+    # accessors (without bang) will evaluate to nil/false.
     # @param url [String, #to_s]
-    # @return [Hash]
+    # @return [ParsedURL]
     def parse(url)
-      Parser.call(url) || raise(InvalidURLError)
+      Parser.call(url)
+    end
+
+    # Parse an individual URL and raise when extraction fails.
+    # This mirrors the legacy behaviour of .parse while giving callers an
+    # explicit opt-in to strict validation.
+    # @param url [String, #to_s]
+    # @return [ParsedURL]
+    # @raise [InvalidURLError]
+    def parse!(url)
+      result = Parser.call(url)
+      raise InvalidURLError unless result.valid?
+
+      result
     end
 
     # Determine if a URL is considered valid by the parser.
@@ -28,12 +44,16 @@ module DomainExtractor
     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| Parser.call(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,40 +142,42 @@ RSpec.describe DomainExtractor do
     end
 
     context 'with invalid URLs' do
-      it 'raises InvalidURLError for malformed URLs' do
-        expect { described_class.parse('http://') }.to raise_error(
-          DomainExtractor::InvalidURLError,
-          'Invalid URL Value'
-        )
+      let(:invalid_inputs) { ['http://', 'not_a_url', '192.168.1.1', '[2001:db8::1]', '', nil] }
+
+      it 'returns an invalid ParsedURL that safely yields nil values' do
+        invalid_inputs.each do |input|
+          result = described_class.parse(input)
+
+          expect(result).to be_a(DomainExtractor::ParsedURL)
+          expect(result.valid?).to be(false)
+          expect(result.domain).to be_nil
+          expect(result.domain?).to be(false)
+          expect(result.host).to be_nil
+          expect(result.host?).to be(false)
+        end
       end
 
-      it 'raises InvalidURLError for invalid domains' do
-        expect { described_class.parse('not_a_url') }.to raise_error(
-          DomainExtractor::InvalidURLError,
-          'Invalid URL Value'
-        )
-      end
+      it 'allows bang accessors to raise explicit errors' do
+        result = described_class.parse('not_a_url')
 
-      it 'raises InvalidURLError for IP addresses' do
-        expect { described_class.parse('192.168.1.1') }.to raise_error(
+        expect { result.domain! }.to raise_error(
           DomainExtractor::InvalidURLError,
-          'Invalid URL Value'
+          'domain not found or invalid'
         )
-      end
 
-      it 'raises InvalidURLError for IPv6 addresses' do
-        expect { described_class.parse('[2001:db8::1]') }.to raise_error(
+        expect { result.host! }.to raise_error(
           DomainExtractor::InvalidURLError,
-          'Invalid URL Value'
+          'host not found or invalid'
         )
       end
 
-      it 'raises InvalidURLError for empty string' do
-        expect { described_class.parse('') }.to raise_error(DomainExtractor::InvalidURLError, 'Invalid URL Value')
-      end
-
-      it 'raises InvalidURLError for nil' do
-        expect { described_class.parse(nil) }.to raise_error(DomainExtractor::InvalidURLError, 'Invalid URL Value')
+      it 'provides strict parsing via parse!' do
+        invalid_inputs.each do |input|
+          expect { described_class.parse!(input) }.to raise_error(
+            DomainExtractor::InvalidURLError,
+            'Invalid URL Value'
+          )
+        end
       end
     end
   end
@@ -300,7 +302,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,465 @@
+# 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 input' do
+      let(:parsed) { DomainExtractor.parse('invalid_url_value') }
+
+      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
+
+    context 'with nil input' do
+      let(:parsed) { DomainExtractor.parse(nil) }
+
+      it 'returns nil for default accessors' do
+        expect(parsed.domain).to be_nil
+        expect(parsed.host).to be_nil
+        expect(parsed.subdomain).to be_nil
+      end
+
+      it 'returns false for question accessors' do
+        expect(parsed.domain?).to be false
+        expect(parsed.host?).to be false
+        expect(parsed.subdomain?).to be false
+      end
+
+      it 'raises for bang accessors' do
+        expect { parsed.domain! }.to raise_error(
+          DomainExtractor::InvalidURLError,
+          'domain not found or invalid'
+        )
+      end
+    end
+
+    context 'with empty string input' do
+      let(:parsed) { DomainExtractor.parse('') }
+
+      it 'returns nil for default accessors' do
+        expect(parsed.domain).to be_nil
+        expect(parsed.host).to be_nil
+      end
+
+      it 'returns false for question accessors' do
+        expect(parsed.domain?).to be false
+        expect(parsed.host?).to be false
+      end
+
+      it 'raises for bang accessors' do
+        expect { parsed.host! }.to raise_error(
+          DomainExtractor::InvalidURLError,
+          'host not found or invalid'
+        )
+      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.parse('invalid_url_value')
+      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.parse('invalid_url_value')
+      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
+      parsed = DomainExtractor.parse('invalid_url_value')
+      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.7
+  version: 0.1.9
 platform: ruby
 authors:
 - OpenSite AI
@@ -43,12 +43,14 @@ files:
 - 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: