domain_extractor 0.1.8 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bc4d6ad831692d1251048f8b21820bb0efb10ed5b3cce641441b31afb5308b4
-  data.tar.gz: 67a96b33dc3544847af271c8bd837dbc592031bff5dac126022a147c2281460c
+  metadata.gz: 9be08df3b44102d414007ad7fc6865166cb89061a09340d5e49de211165c963f
+  data.tar.gz: a334da0e7a8dc42335b9710aaf9d601d9fc85323ca2e328359de9593a340abc3
 SHA512:
-  metadata.gz: 02bca764446a3391461695cfeeaef9c6e7920308bc78768b062ae676005d3610b09733133cb10c34cd5e29dc35169f770b4789f418fd554cba762a6d5a19022a
-  data.tar.gz: eeaaa8356b306feba33e08e54c8da2926f7e052ebac5d6920f0a6f26c0dacd3bfbb0d4f863fa694377d87441564a2c1eecff764d756ce4efde0569fabf573ee2
+  metadata.gz: 297852adc140faba6fc64b7589402c1f3b032be344d13ad781ede5ff2a1c1ba867480edbebaca488708da46d68152bf3ee80c02da36d6f8afbf97a74361960ae
+  data.tar.gz: 6b0191d8bfb2458a23e3c56c382f495c9eebf86715a16c8f2936e6804d4adc0643835485e100e42f3bcd3f4d83344d7d60aac47dee60f72214fd95297f714334

data/README.md

@@ -65,6 +65,10 @@ end
 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
@@ -74,6 +78,7 @@ DomainExtractor now returns a `ParsedURL` object that supports three accessor st
 ### Method Accessor Styles
 
 #### 1. Default Methods (Silent Nil)
+
 Returns the value or `nil` - perfect for exploratory code or when handling invalid data gracefully.
 
 ```ruby
@@ -89,6 +94,7 @@ 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
@@ -98,6 +104,7 @@ 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
@@ -150,6 +157,28 @@ 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
@@ -235,7 +264,7 @@ hash = result.to_h
 # }
 ```
 
-**See [docs/PARSED_URL_API.md](docs/PARSED_URL_API.md) for comprehensive documentation and real-world examples.**
+**[Comprehensive documentation and real-world examples of parsed URL quick start guide](https://github.com/opensite-ai/domain_extractor/blob/master/docs/PARSED_URL_QUICK_START.md)**
 
 ## Usage Examples
 
@@ -300,31 +329,38 @@ DomainExtractor.parse('not-a-url')
 
 ## API Reference
 
-### `DomainExtractor.parse(url_string)`
-
-Parses a URL string and extracts domain components.
+```ruby
+DomainExtractor.parse(url_string)
 
-**Returns:** Hash with keys `:subdomain`, `:domain`, `:tld`, `:root_domain`, `:host`, `:path`
+# => Parses a URL string and extracts domain components.
 
-**Raises:** `DomainExtractor::InvalidURLError` when the URL fails validation
+# Returns: Hash with keys :subdomain, :domain, :tld, :root_domain, :host, :path
+# Raises: DomainExtractor::InvalidURLError when the URL fails validation
+```
 
-### `DomainExtractor.parse_batch(urls)`
+```ruby
+DomainExtractor.parse_batch(urls)
 
-Parses multiple URLs efficiently.
+# => Parses multiple URLs efficiently.
 
-**Returns:** Array of parsed results
+# Returns: Array of parsed results
+```
 
-### `DomainExtractor.valid?(url_string)`
+```ruby
+DomainExtractor.valid?(url_string)
 
-Checks if a URL can be parsed successfully without raising.
+# => Checks if a URL can be parsed successfully without raising.
 
-**Returns:** `true` or `false`
+# Returns: true or false
+```
 
-### `DomainExtractor.parse_query_params(query_string)`
+```ruby
+DomainExtractor.parse_query_params(query_string)
 
-Parses a query string into a hash of parameters.
+# => Parses a query string into a hash of parameters.
 
-**Returns:** Hash of query parameters
+# Returns: Hash of query parameters
+```
 
 ## Use Cases
 

data/lib/domain_extractor/version.rb

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

data/lib/domain_extractor.rb

@@ -15,10 +15,21 @@ 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.
+    # 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 [ParsedURL]
     def parse(url)
+      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?
 

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

data/spec/parsed_url_spec.rb

@@ -127,8 +127,8 @@ RSpec.describe DomainExtractor::ParsedURL do
       end
     end
 
-    context 'with invalid URL' do
-      let(:parsed) { DomainExtractor::ParsedURL.new(nil) }
+    context 'with invalid URL input' do
+      let(:parsed) { DomainExtractor.parse('invalid_url_value') }
 
       describe 'default accessor methods' do
         it 'returns nil for subdomain' do
@@ -189,6 +189,50 @@ RSpec.describe DomainExtractor::ParsedURL do
         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
@@ -208,7 +252,7 @@ RSpec.describe DomainExtractor::ParsedURL do
     end
 
     it 'returns false for invalid URL' do
-      parsed = DomainExtractor::ParsedURL.new(nil)
+      parsed = DomainExtractor.parse('invalid_url_value')
       expect(parsed.www_subdomain?).to be false
     end
   end
@@ -220,7 +264,7 @@ RSpec.describe DomainExtractor::ParsedURL do
     end
 
     it 'returns false for invalid URL' do
-      parsed = DomainExtractor::ParsedURL.new(nil)
+      parsed = DomainExtractor.parse('invalid_url_value')
       expect(parsed.valid?).to be false
     end
 
@@ -299,8 +343,7 @@ RSpec.describe DomainExtractor::ParsedURL do
 
     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)
+      parsed = DomainExtractor.parse('invalid_url_value')
       expect(parsed.domain).to be_nil
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: domain_extractor
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.2.0
 platform: ruby
 authors:
 - OpenSite AI
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-10-31 00:00:00.000000000 Z
+date: 2025-11-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: public_suffix