optionoids 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 000744ac00ebed3c85f06c226f38081e42a8a9c5f4bfb8954eea52b6da6c1a90
+  data.tar.gz: 771c45f7822b2c74ade3fc89ce8467a910dee5e64736bd2eaad33ca31fe64cef
+SHA512:
+  metadata.gz: 46d34d1c17906cb257b207394611ecff3bb37756e30f554c301b6cffb4b603d0cfde79e24299fbe5d68e90dd41060540133c9c27f75121bc14adac885a3f1a86
+  data.tar.gz: f300123a79410fca5c3e0fa24db59828604980a9f1087bc181c063fd37996873d0b2655786c7c8fbee8327c53336c3e49767c64a564d145d63b9a23e21c37e76

data/.rspec

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

data/.rubocop.yml

@@ -0,0 +1,34 @@
+plugins:
+  - rubocop-rake
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.0
+  SuggestExtensions: false
+  NewCops: enable
+  Exclude:
+    - "bin/**/*"
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/AbcSize:
+  Exclude:
+    - "spec/**/*"
+
+Metrics/CyclomaticComplexity:
+  Exclude:
+    - "spec/**/*"
+
+Metrics/MethodLength:
+  Exclude:
+    - "spec/**/*"
+
+RSpec/MultipleExpectations:
+  Max: 2

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-06-28
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 drewthorp
+
+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,335 @@
+# Optionoids
+_(Terrible name, I know)_
+
+Optionoids provides a simple, flexible, and concise method of validating option hashes passed to methods. Failures of validation can either raise an error or return an array of the errors. Checks can be chained together to create complex validations, and can be used to validate presence, population, types, and counts.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add optionoids
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install optionoids
+
+## Usage
+
+Optionoids provides two methods on the Hash class. The `expecting` method is used for hard validations that will raise an error if the validation fails, while the `checking` method is used for soft validations that will provide an array of errors if the validation fails.
+
+```ruby
+require 'optionoids'
+
+class MyClass
+  def my_method(name, options = {})
+    expecting = options.expecting.with_params(name: name)
+      .only_these(%i[name address age])
+    expecting.that(%i[name address]).required.of_type(String)
+             .and.that(:age).of_type(Integer)
+  end
+end
+```
+
+## Initialization
+
+To start a hard validation, call `expecting` on the hash you want to validate. This will return an instance of `Optionoids::Checker`.
+
+```ruby
+options = { name: 'John', age: 30 }
+checker = options.expecting
+```
+
+To start a soft validation, call `checking` on the hash you want to validate. This will return an instance of `Optionoids::Checker`.
+
+```ruby
+options = { name: 'John', age: 30 }
+checker = options.checking
+```
+
+Both methods accept a `keys:` argument to specify an initial key filtering state (see below). The keys argument can be a single key or an array of keys.
+
+```ruby
+options = { name: 'John', age: 30, email: 'bob@foo.com' }
+checker = options.expecting(keys: :name)
+# or
+checker = options.checking(keys: [:name, :age])
+```
+
+### Additional Parameters
+
+In addition to the pairs in the hash, additional pairs can be added for validation with the `with_params` method.
+
+```ruby
+options.expecting.with_params(name: 'John', age: 30)
+```
+
+## Filtering
+
+The key/value pairs that a check will be performed on can be filtered to only include certain keys. Once a filter is set, all subsequent checks will only be performed on the keys that are in the filter until the filter is altered or cleared. By default, there is no filter set, and all keys in the hash will be checked. An initial filter can be set when the checker is created by passing a `keys:` argument to the `expecting` or `checking` methods.
+
+### `that(keys)` Method
+
+Sets a set of keys that subsequent checks will be performed on.
+
+```ruby
+checker = options.expecting.that(%i[name address age])
+checker.keys # => [:name, :address, :age]
+```
+
+### `plus(keys)` Method
+
+Adds keys to the current filter.
+
+```ruby
+checker = options.expecting.that(%i[name address]).plus(:age)
+checker.keys # => [:name, :address, :age]
+```
+
+### `minus(keys)` Method
+
+Removes keys from the current filter.
+
+```ruby
+checker = options.expecting.that(%i[name address age]).minus(:address)
+checker.keys # => [:name, :age]
+```
+
+### `and` Method
+
+Clears the current filter.
+
+```ruby
+expecting = options.expecting.that(%i[name address age])
+expecting.that(:name).required.and.that(:age).populated
+```
+
+Alias: _`all`_
+
+```ruby
+expecting = options.expecting.that(%i[name address age])
+expecting.that(:name).required
+expecting.all.populated
+```
+
+## Checks
+
+Checks are methods that can be chained together to perform validations on the keys and values in the options hash. The checks can be used to validate presence, population, types, and counts. Depending on how the checker was initialized, the checks will either raise an error or add to an array of errors (See `#errors` for accessing the array).
+
+### `only_these(keys)` Method
+
+Checks that only the keys provided are present in the options hash. If any other keys are present, an error will be raised or added to the errors array.
+
+```ruby
+expecting = options.expecting.only_these(%i[name address age])
+```
+
+Error raised/logged: _Optionoids::Errors::UnexpectedKeys_
+
+### `exist` Method
+
+Checks that all the currently set filter keys are present in the current option Hash. If there are no entries in the current option Hash, an error is raised. If any of the keys are missing, an error is raised.
+
+```ruby
+expecting = options.expecting.that(:name).exist
+```
+
+Errors raised/logged:
+- Empty hash - _Optionoids::Errors::RequiredDataUnavailable_
+- Missing keys - _Optionoids::Errors::MissingKeys_
+
+### `populated` Method
+
+Checks that all the filter keys in the hash are not nil or empty. If any of the keys are nil or empty, an error is raised or added to the errors array. It does not error if the keys do not exist in the hash.
+
+```ruby
+expecting = options.expecting.that(:name).populated
+```
+
+Error raised/logged: _Optionoids::Errors::UnexpectedBlankValue_
+
+Alias: _`all_populated`_
+
+### `blank` Method
+
+Checks that all the filter keys in the hash are nil or empty. If any of the keys are not nil or empty, an error is raised or added to the errors array. It does not error if the keys do not exist in the hash.
+
+```ruby
+expecting = options.expecting.that(:name).blank
+```
+
+Error raised/logged: _Optionoids::Errors::UnexpectedPopulatedValue_
+
+Alias: _`all_blank`_
+
+### `not_nil_values` Method
+
+Checks that all the filter keys in the hash are not nil. If any of the keys are nil, an error is raised or added to the errors array. It does not error if the keys do not exist in the hash.
+
+```ruby
+expecting = options.expecting.that(:name).not_nil_values
+```
+
+Error raised/logged: _Optionoids::Errors::UnexpectedNilValue_
+
+### `nil_values` Method
+
+Checks that all the filter keys in the hash are nil. If any of the keys are not nil, an error is raised or added to the errors array. It does not error if the keys do not exist in the hash.
+
+```ruby
+expecting = options.expecting.that(:name).nil_values
+```
+
+Error raised/logged: _Optionoids::Errors::UnexpectedNotNilValue_
+
+### `one_or_none` Method
+
+Checks that at most one of the filter keys in the hash are present. If more than one of the keys are present, an error is raised or added to the errors array. It does not consider values, only the presence of the keys.
+
+```ruby
+expecting = options.expecting.that(%i[name age]).one_or_none
+```
+
+Error raised/logged: _Optionoids::Errors::UnexpectedMultipleKeys_
+
+### `just_one` Method
+
+Checks that exactly one of the filter keys in the hash are present. If none or more than one of the keys are present, an error is raised or added to the errors array. It does not consider values, only the presence of the keys.
+
+```ruby
+expecting = options.expecting.that(%i[name age]).just_one
+```
+
+Errors raised/logged:
+- Empty hash - _Optionoids::Errors::RequiredDataUnavailable_
+- None or more than one keys - _Optionoids::Errors::UnexpectedMultipleKeys_
+
+### `one_or_more` Method
+
+Checks that at least one of the filter keys in the hash are present. If none of the keys are present, an error is raised or added to the errors array. It does not consider values, only the presence of the keys.
+
+```ruby
+expecting = options.expecting.that(%i[name age]).one_or_more
+```
+
+Error raised/logged: _Optionoids::Errors::ExpectedMultipleKeys_
+
+### `of_types(types)` Method
+
+Checks that the values of the filter keys in the hash are of the types provided. If any of the values are not of the expected type, an error is raised or added to the errors array. It does not error if the keys do not exist in the hash or if the value is nil.
+
+```ruby
+expecting = options.expecting.that(:name).of_types(String, Symbol)
+```
+
+Error raised/logged: _Optionoids::Errors::UnexpectedValueType_
+
+Alias: _`of_type`_, _`types`_, _`type`_
+
+### `possible_values(variants)` Method
+
+Checks that the values of the filter keys in the hash are one of the possible values provided. If any of the values are not one of the possible values, an error is raised or added to the errors array. It does not error if the keys do not exist in the hash or if the value is nil.
+
+```ruby
+expecting = options.expecting.that(:name).possible_values('John', 'Jane', 'Doe')
+```
+
+Error raised/logged: _Optionoids::Errors::UnexpectedValueVariant_
+
+## Convenience Methods
+
+The `Optionoids::Checker` class provides several convenience methods to make it easier to perform common checks. These methods are available on both hard and soft checkers.
+
+### `identifier` Method
+
+Checks that the value of the filter key is a valid identifier. A valid identifier is a populated String or Symbol.
+
+```ruby
+expecting = options.expecting.that(:name).identifier
+```
+
+Errors raised/logged:
+- If the wrong type: _Optionoids::Errors::UnexpectedValueType_
+- If the value is nil or empty: _Optionoids::Errors::UnexpectedBlankValue_
+
+### `flag` Method
+
+Checks that the value of the filter key is a populated boolean. A boolean is either `true` or `false`.
+
+```ruby
+expecting = options.expecting.that(:active).flag
+```
+
+Errors raised/logged:
+- If the wrong type: _Optionoids::Errors::UnexpectedValueType_
+- If the value is nil or empty: _Optionoids::Errors::UnexpectedBlankValue_
+
+### `required` Method
+
+Checks that the filter key is present and populated in the options hash.
+
+```ruby
+expecting = options.expecting.that(:name).required
+```
+
+Errors raised/logged:
+- If the hash is empty: _Optionoids::Errors::RequiredDataUnavailable_
+- Not present: _Optionoids::Errors::MissingKeys_
+- If the value is nil or empty: _Optionoids::Errors::UnexpectedBlankValue_
+
+## Soft Errors
+
+If the checker was initialized with `checking`, the errors will be collected in an array. You can access the errors using the `errors` method. A predicate method `failed?` is also available to check if there are any errors.
+
+```ruby
+checker = options.checking.that(:name).required
+checker.errors # => ["Missing keys: name", "Unexpected blank value for key: name"]
+checker.failed? # => true
+```
+
+## Data Access / Debugging
+
+### `current_options` Method
+
+Returns the current filtered options Hash that is being checked.
+
+```ruby
+checker = options.expecting.that(:name).current_options
+# => { name: 'John' }
+```
+
+### `global_options` Method
+
+Returns the original options Hash that was passed to the checker. Options added with `with_params` are included in this hash.
+
+```ruby
+checker = options.expecting.with_params(name: 'John').global_options
+# => { name: 'John', age: 30 }
+```
+
+### `keys` Method
+
+Returns the keys that are currently being checked. This is useful to see which keys are in the current filter.
+
+```ruby
+checker = options.expecting.that(:name, :age).keys
+# => [:name, :age]
+```
+
+## Future Enhancements
+
+- Add support for regex checks on values.
+- Add common checks using regex (e.g., email, URL).
+- Add support for range checks on numeric & date values.
+- Implement a similar API for cleaning the options hash.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/optionoids. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/optionoids/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Optionoids project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/optionoids/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

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

data/lib/hash_expecting.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Extends the Hash class to support optionoid option parsing.
+class Hash
+  # Perform hard checking on the Hash. Hard checking will raise an error if the Hash does not
+  # conform to the expectations.
+  def expecting(keys = nil)
+    Optionoids::Checker.new(self, keys: keys)
+  end
+
+  # Perform soft checking on the Hash.  Soft checking will not raise an error.  Errors are logged
+  # and can be checked with errors and failed? methods.
+  def checking(keys = nil)
+    Optionoids::Checker.new(self, keys: keys, hard: false)
+  end
+end

data/lib/optionoids/checker.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/object/blank'
+require 'hash_expecting'
+require 'optionoids/errors'
+
+module Optionoids
+  # Class to wrap an options Hash and perform checks on the keys and values.  All method return
+  # the same instance of the Checker, allowing for method chaining.
+  class Checker
+    attr_reader :hard, :keys
+
+    # @param options [Hash] The options Hash to check against.
+    # @param keys [Array<String, Symbol>] The keys to initially check in the options Hash. If nil,
+    #                            all keys are checked.
+    def initialize(options, keys: nil, hard: true)
+      @options = options
+      @keys = [keys].flatten.compact
+      @params = {}
+      @hard = hard
+      clip_options
+    end
+
+    # A set of additional options to check against.  This is useful for checking other none optional
+    # parameters that are not part of the options Hash.
+    def with_params(params)
+      @params = params.is_a?(Hash) ? params : params.to_h
+      clip_options
+      self
+    end
+
+    # Returns the current 'filtered' option Hash.
+    def current_options
+      @clipped_options
+    end
+
+    # Returns the 'unfiltered' options Hash.
+    def global_options
+      @options.merge(@params)
+    end
+
+    ## FILTERING ##
+
+    # Removes all option Hash filtering.
+    def and
+      @keys = []
+      clip_options
+      self
+    end
+
+    alias all and
+
+    # Add a key set filter to the current option Hash.  The keys provided do not have to exist in the
+    # option Hash, but only those that do will be checked.  Filters are not cumulative, so calling
+    # this method will replace any previous key filters.
+    def that(*keys)
+      @keys = keys.flatten.compact
+      clip_options
+      self
+    end
+
+    # Removes the keys from the current option Hash filter.  No error will be raised if the given
+    # keys are not present in the current option Hash.
+    def minus(*keys)
+      @keys -= keys
+      clip_options
+      self
+    end
+
+    # Adds the given keys to the current option Hash filter.  No error will be raised if the given
+    # keys are not present in the current option Hash.
+    def plus(*keys)
+      @keys |= keys.flatten.compact.uniq
+      clip_options
+      self
+    end
+
+    ## KEY PRESENCE CHECKS ##
+
+    # Checks that the current option Hash contains only the given keys.  If any unexpected keys are
+    # present, an error is raised.  If no keys are given, the current option Hash is not checked.
+    # Error: Optionoids::Errors::UnexpectedKeys
+    def only_these(keys)
+      unexpected_keys = @clipped_options.keys - [keys].flatten
+      _error_or_log(Errors::UnexpectedKeys.new(nil, keys: unexpected_keys)) if unexpected_keys.any?
+
+      self
+    end
+
+    # Checks that all the currently set filter keys are present in the current option Hash.  If there
+    # are no entries in the current option Hash an error (Optionoids::Errors::RequiredDataUnavailable)
+    # is raised.  If any of the keys are missing, an error (Optionoids::Errors::MissingKeys) is raised.
+    def exist
+      return _error_or_log(Errors::RequiredDataUnavailable.new(nil, check: 'present')) if @keys.empty?
+
+      missing_keys = @keys - @clipped_options.keys
+      return self if missing_keys.empty?
+
+      _error_or_log(Errors::MissingKeys.new(nil, keys: missing_keys))
+    end
+
+    ## VALUE POPULATION CHECKS ##
+
+    # Checks that the current option Hash entries all have non-blank values.  If any of the values
+    # are blank, an error (Optionoids::Errors::UnexpectedBlankValue) is raised.
+    def populated
+      _error_on_check(:blank?, Errors::UnexpectedBlankValue)
+      self
+    end
+
+    alias all_populated populated
+
+    # Checks that the current option Hash entries all have blank values.  If any of the values are
+    # populated, an error (Optionoids::Errors::UnexpectedPopulatedValue) is raised.
+    def blank
+      _error_on_check(:present?, Errors::UnexpectedPopulatedValue)
+      self
+    end
+
+    alias all_blank blank
+
+    # Checks that the current option Hash entries all have non-nil values.  If any of the values are
+    # nil, an error (Optionoids::Errors::UnexpectedNilValue) is raised.
+    def not_nil_values
+      _error_on_check(:nil?, Errors::UnexpectedNilValue)
+      self
+    end
+
+    # Checks that the current option Hash entries all have nil values.  If any of the values are
+    # not nil, an error (Optionoids::Errors::UnexpectedNonNilValue) is raised.
+    def nil_values
+      failed_keys = @clipped_options.compact.keys
+      return self if failed_keys.empty?
+
+      _error_or_log(Errors::UnexpectedNonNilValue.new(nil, keys: failed_keys))
+    end
+
+    ## KEY COUNT CHECKS ##
+
+    # Checks that the current option Hash contains no more that one key.  If more than one  key id
+    # present, an error (Optionoids::Errors::UnexpectedMultipleKeys) is raised.  If there are no keys
+    # present, no error is raised.
+    def one_or_none
+      msg = "Expected a maximum or one key, but found: #{@clipped_options.keys.to_sentence}"
+      _error_or_log(Errors::UnexpectedMultipleKeys.new(msg, keys: @clipped_options.keys)) if @clipped_options.count > 1
+
+      self
+    end
+
+    # Checks that the current option Hash contains exactly one key.  If no keys are present, an error
+    # (Optionoids::Errors::RequiredDataUnavailable) is raised.  If more than one key is present, an error
+    # (Optionoids::Errors::UnexpectedMultipleKeys) is raised.
+    def just_one
+      _error_or_log(Errors::RequiredDataUnavailable.new(nil, check: 'one_required')) if @clipped_options.empty?
+      return self if @clipped_options.one?
+
+      msg = "Expected exactly one key, but found: #{@clipped_options.keys.to_sentence}"
+      _error_or_log(Errors::UnexpectedMultipleKeys.new(msg, keys: @clipped_options.keys))
+    end
+
+    # Checks that the current option Hash contains one or more keys.  If no keys are present, an error
+    # (Optionoids::Errors::ExpectedMultipleKeys).
+    def one_of_more
+      return self if @clipped_options.count >= 1
+
+      _error_or_log(Errors::ExpectedMultipleKeys.new)
+    end
+
+    ## TYPE CHECKS ##
+
+    # Checks that the current option Hash entries are of the given types.  If any of the values are
+    # not of the given types, an error (Optionoids::Errors::UnexpectedValueType) is raised. 'nil'
+    # values are ignored in the type check.
+    def of_types(*types)
+      pairs = @clipped_options.compact.select { |_k, v| types.none? { |t| v.is_a?(t) } }
+      return self if pairs.empty?
+
+      _error_or_log(Errors::UnexpectedValueType.new(nil, keys: pairs.keys, types: types.map(&:name)))
+    end
+
+    alias of_type of_types
+    alias types of_types
+    alias type of_types
+
+    ## VALUE CHECKS ##
+
+    # Checks that the current option Hash entries are one of the given variants.  If any of the
+    # values are not one of the given variants, an error (Optionoids::Errors::UnexpectedValueVariant).
+    # If a value is nil it is ignored in the check.
+    def possible_values(variants)
+      pairs = @clipped_options.compact.select { |_k, v| variants.none? { |variant| v == variant } }
+      return self if pairs.empty?
+
+      _error_or_log(Errors::UnexpectedValueVariant.new(nil, keys: pairs.keys, variants: variants))
+    end
+
+    ## COMPOSITE CHECKS ##
+
+    # Checks that the current option Hash entries are usable as identifiers.  This means that the
+    # values are either Strings or Symbols and are not blank.
+    def identifier
+      of_type(String, Symbol).populated
+    end
+
+    # Checks that the current option Hash entries are usable as flags.  This means that the values
+    # are either TrueClass or FalseClass and are not blank.
+    def flag
+      # Populated check mist use not nil because false is never 'present?'
+      of_type(TrueClass, FalseClass).not_nil_values
+    end
+
+    # Checks that the current option Hash entries ate both present and populated.
+    def required
+      exist.populated
+    end
+
+    ## SOFT ERROR HANDLING ##
+
+    def errors
+      @errors ||= []
+    end
+
+    def failed?
+      errors.any?
+    end
+
+    private
+
+    def _error_or_log(error)
+      raise error if @hard
+
+      errors << error
+      self
+    end
+
+    def _error_on_check(check, error_class)
+      failed_keys = _keys_for_check(check)
+      return if failed_keys.empty?
+
+      _error_or_log(error_class.new(nil, keys: failed_keys))
+    end
+
+    def _keys_for_check(check)
+      @clipped_options.select { |_k, v| v.send(check) }.to_h.keys
+    end
+
+    def clip_options
+      @clipped_options = @options.merge(@params)
+      return if @keys.empty?
+
+      @clipped_options = @clipped_options.slice(*@keys)
+    end
+  end
+end

data/lib/optionoids/errors.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/array/conversions'
+
+module Optionoids
+  # Errors module contains custom error classes for the Optionoids library.
+  module Errors
+    # Custom error class to indicate that a checker requires keys in #keys or key/values in the
+    # current option Hash, but none were provided.
+    class RequiredDataUnavailable < StandardError
+      attr_reader :check
+
+      def initialize(message = nil, check: nil)
+        msg = message || "Required data is unavailable for the check '#{check}'"
+        @check = check
+        super(msg)
+      end
+    end
+
+    # Custom error class to indicate the expected keys are not present in the current option Hash
+    class MissingKeys < StandardError
+      attr_reader :keys
+
+      def initialize(message = nil, keys: [])
+        @keys = keys
+        msg = message || "Missing required keys: #{keys.to_sentence}"
+        super(msg)
+      end
+    end
+
+    # Custom error class to indicate that unexpected keys are in the current option Hash
+    class UnexpectedKeys < StandardError
+      attr_reader :keys
+
+      def initialize(message = nil, keys: [])
+        @keys = keys
+        msg = message || "Unexpected keys found: #{keys.to_sentence}"
+        super(msg)
+      end
+    end
+
+    # Custom error class to indicate that some values ate unexpectedly blank or nil
+    class UnexpectedBlankValue < StandardError
+      attr_reader :keys
+
+      def initialize(message = nil, keys: [])
+        @keys = keys
+        msg = message || "Unexpected blank values for keys: #{keys.to_sentence}"
+        super(msg)
+      end
+    end
+
+    # Custom error class to indicate that some values are unexpectedly populated (not blank)
+    class UnexpectedPopulatedValue < StandardError
+      attr_reader :keys
+
+      def initialize(message = nil, keys: [])
+        @keys = keys
+        msg = message || "Unexpected populated values for keys: #{keys.to_sentence}"
+        super(msg)
+      end
+    end
+
+    # Custom error class to indicate that some values are unexpectedly not nil
+    class UnexpectedNonNilValue < StandardError
+      attr_reader :keys
+
+      def initialize(message = nil, keys: [])
+        @keys = keys
+        msg = message || "Unexpected non-nil values for keys: #{keys.to_sentence}"
+        super(msg)
+      end
+    end
+
+    # Custom error class to indicate that some values are unexpectedly nil
+    class UnexpectedNilValue < StandardError
+      attr_reader :keys
+
+      def initialize(message = nil, keys: [])
+        @keys = keys
+        msg = message || "Unexpected nil values for keys: #{keys.to_sentence}"
+        super(msg)
+      end
+    end
+
+    # Custom error class to indicate that only one key is expected, but multiple keys are present
+    class UnexpectedMultipleKeys < StandardError
+      attr_reader :keys
+
+      def initialize(message = nil, keys: [])
+        @keys = keys
+        msg = message || "Multiple keys present when only one is expected: #{keys.to_sentence}"
+        super(msg)
+      end
+    end
+
+    # Custom error class to indicate that the values for the keys are not of the expected types
+    class UnexpectedValueType < StandardError
+      attr_reader :keys, :types
+
+      def initialize(message = nil, keys: [], types: [])
+        @keys = keys
+        @types = types
+        msg = message || "Unexpected value types for keys: #{keys.to_sentence}. " \
+                         "Expected types: #{types.to_sentence}"
+        super(msg)
+      end
+    end
+
+    # Custom error class to indicate that a values in the current option Hash are not of the
+    # expected variants
+    class UnexpectedValueVariant < StandardError
+      attr_reader :keys, :variants
+
+      def initialize(message = nil, keys: [], variants: [])
+        @keys = keys
+        @variants = variants
+        msg = message || "Unexpected value variants for keys: #{keys.to_sentence}. " \
+                         "Expected variants: #{variants.to_sentence}"
+        super(msg)
+      end
+    end
+
+    # Custom error class to indicate that a checker expected multiple keys but none were provided
+    class ExpectedMultipleKeys < StandardError
+      def initialize(message = nil)
+        msg = message || 'Expected multiple keys but none were provided'
+        super(msg)
+      end
+    end
+  end
+end

data/lib/optionoids/version.rb

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

data/lib/optionoids.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'optionoids/version'
+require_relative 'optionoids/checker'

data/sig/optionoids.rbs

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

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: optionoids
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- drewthorp
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-07-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+description: Optionoids is a Ruby gem designed to provide a simple and flexible way
+  to validate and check the content of option hashes. It allows developers to define
+  checks for required keys, unexpected keys, and value conditions, making it easier
+  to work with configuration options in Ruby applications.
+email:
+- gems@fishfur.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/hash_expecting.rb
+- lib/optionoids.rb
+- lib/optionoids/checker.rb
+- lib/optionoids/errors.rb
+- lib/optionoids/version.rb
+- sig/optionoids.rbs
+homepage: https://github.com/Fish-Fur/optionoids
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Fish-Fur/optionoids
+  source_code_uri: https://github.com/Fish-Fur/optionoids
+  changelog_uri: https://github.com/Fish-Fur/optionoids
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: A Ruby gem for checking content of option hashes.
+test_files: []