hash_with_field_validation 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b82063b5a2c11b94105d32b760ba9b3033dea4a833c4f67f1e88a2f64a4308ab
+  data.tar.gz: bcde13510ea967e22f64c703b311a4719e584d63a1e5d622e4e7a9235f11bbdf
+SHA512:
+  metadata.gz: 55aab9213de1a42184f497001573aa264b82577e76d4b164277f41d89720576094a694cf2f57bfd8ab1ae6b30f154b7f67bd813d21756c1c99e835f6effcc5d5
+  data.tar.gz: e6b772e7e61c6c4fde88d18a74a48fc0256c28c2af1c45737b7300db9065330352eb11dc078fcd4cf41d2f1f1b46d80e29fd2bf62f5ffc3465d5df86307a4230

data/README.md

@@ -0,0 +1,136 @@
+# HashWithFieldValidation
+
+HashWithFieldValidation is a Ruby library designed to simplify the creation and manipulation of domain-specific data models, supporting type checking, data validation, and JSON deserialization. This library takes advantage of Ruby's dynamic nature, providing a fluent and intuitive interface to define domain models.
+
+## Features
+
+- Dynamic model creation with a flexible field declaration syntax.
+- Type checking and enforcement to ensure model validity.
+- Simple JSON to Model deserialization.
+- Easy access to model data using accessor methods.
+- Nullability, enumerations, lists, and other constraints.
+- Custom model matching classes for extending the library's capabilities.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hash_with_field_validation'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install hash_with_field_validation
+
+## Usage
+
+Here is a basic usage example:
+
+```ruby
+require 'hash_with_field_validation'
+
+class User < HashWithFieldValidation
+  field :name, type: String
+  field :age, type: 1..100
+end
+
+user = User.from_json('{"name": "Alice", "age": 30}')
+user = User.new(name: "Alice", age: 30)
+
+user.name = 'Bob'
+user.age = 120 # => raises RuntimeError: expected age to be 1..100, got 120
+```
+
+You can define the following types of fields:
+
+- Basic types (e.g. `String`, `Integer`, `Float`, `Symbol`, `Boolean`)
+- Enumerations (e.g. `enum(:admin, :user, :guest)`)
+- Lists of certain type (e.g. `list(String)`, `list(User)`)
+- Nullable fields (e.g. `nullable(String)`, `nullable(User)`)
+- Positive value fields (e.g. `positive(Integer)`, `positive(Float)`)
+- Regular expressions (e.g. `/\A\d\d\d\d-\d\d-\d\d\z/` for matching dates)
+- Ranges (e.g. `1..100` for matching integers between 1 and 100)
+
+More complex nested models can be created:
+
+```ruby
+class Post < HashWithFieldValidation
+  field :title, type: String
+  field :content, type: String
+  field :created_at, type: Timestamp
+  field :tags, type: list(String)
+end
+
+class User < HashWithFieldValidation
+  field :name, type: String
+  field :friends, type: list(User)
+  field :posts, type: list(Post)
+end
+```
+
+## Notes
+
+A model has type-checked fields.
+
+This class can be used to create a flexible and type-safe representation of
+JSON data. It provides a convenient way to create and validate data models
+in Ruby, making it easier to build complex applications.
+
+The Model class extends the built-in Hash class and is designed to enforce
+type constraints on data objects that can be created from JSON snapshots. It
+defines custom syntax for declaring and validating fields, with support for
+common data types suchs enums, lists, and nullable types.
+
+Example usage
+
+    class Person < Model
+      field %{name}, type: String
+      field %{gender}, type: (enum :male, :female)
+      field %{age}, type: 1..100
+    end
+
+    anna = Person.new(
+      name: 'Anna',
+      gender: :female,
+      age: 29,
+    )
+
+Type checking in the Model framework is based on a combination of built-in
+Ruby functionality and custom matchers that are optimized for working with
+complex data structures.
+
+- The framework relies on the === operator, which is a built-in method in
+  Ruby that checks whether a given value is a member of a class or matches
+  a pattern, such as a regular-expression or a range of numbers
+- In addition the framework provides a set of custom matchers that are
+  optimized for working with more complex data structures. These matchers
+  include support for lists, nullable types, enumerations, and more.
+
+Another way to extend the type checking capabilities is by subclassing the
+Matcher class. This allows developers to create custom matchers that can
+validate complex data structures or enforce domain-specific rules on the
+values of fields in a model. This provides a powerful extension point that
+allows developers to meet the needs of their specific use cases, and can
+help ensure data quality and consistency in their applications.
+
+Customizing serialization is an important aspect of working with data models,
+and the Model framework provides a flexible way to achieve this through the
+to_json and from_snapshot methods. These methods allow developers to control
+how data is represented in JSON format, which can be important ensure that
+the serialized data is compatible with external systems or APIs.
+
+In summary, the Model framework provides a powerful and flexible way to
+define and enforce the structure of data models in a Ruby application, and
+offers a variety of extension points for customizing the behavior of the
+framework to meet the needs of specific use cases.
+
+Hackety hacking, frens!
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [link to GitHub repo](https://github.com/akuhn/hash_with_field_validation).  This project encourages collaboration and appreciates contributions. Feel free to contribute to the project by reporting bugs or submitting pull requests.

data/lib/hash_with_field_validation/field.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+
+class HashWithFieldValidation < Hash
+
+  class Field
+    def initialize(type)
+      @type = type
+    end
+
+    def initialize_options(options)
+    end
+
+    def ===(value)
+      @type === value
+    end
+
+    def default_value
+      nil
+    end
+
+    def to_s
+      @type.to_s
+    end
+
+    def from_snapshot(data, options = nil)
+      if @type == Symbol
+        data.to_sym if data
+      elsif Class === @type && @type.respond_to?(:from_snapshot)
+        @type.from_snapshot(data, options)
+      else
+        data
+      end
+    end
+  end
+
+  class EnumField < Field
+    def initialize(*symbols)
+      super symbols
+    end
+
+    def ===(value)
+      @type.any? { |each| each === value }
+    end
+
+    def to_s
+      "enum(#{@type.map(&:inspect).join(?,)})"
+    end
+
+    def from_snapshot(data, options)
+      String === data ? data.to_sym : data
+    end
+  end
+
+  class ListField < Field
+    def initialize_options(options)
+      @option_empty = options.fetch(:empty, true)
+    end
+
+    def ===(value)
+      return false unless Array === value
+      return false if value.empty? unless @option_empty
+      value.all? { |each| @type === each }
+    end
+
+    def default_value
+      []
+    end
+
+    def to_s
+      "list(#{@type}#{', empty: false' unless @option_empty})"
+    end
+
+    def from_snapshot(data, options)
+      data && data.map { |each| super(each, options) }
+    end
+  end
+
+  class NullableField < Field
+    def ===(value)
+      @type === value || value.nil?
+    end
+
+    def to_s
+      "nullable(#{@type})"
+    end
+  end
+end

data/lib/hash_with_field_validation/model.rb

@@ -0,0 +1,3 @@
+require 'hash_with_field_validation'
+
+Model = HashWithFieldValidation

data/lib/hash_with_field_validation/version.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+class HashWithFieldValidation < Hash
+  VERSION = "1.0.0"
+end
+
+__END__
+
+# Major version bump when breaking changes or new features
+# Minor version bump when backward-compatible changes or enhancements
+# Patch version bump when backward-compatible bug fixes, security updates etc
+
+1.0.0
+
+- Renamed to hash_with_field_validation
+- Make the former model class the top-level element
+- Removed enumerable extensions, see another gem
+- New function Model#error_messages
+- Reorganize tests and write more tests
+
+0.3.1
+
+- Rename check_types to valid? and validate_fields!
+- Reorganize tests and write more tests
+
+0.3.0
+
+- Rename Matcher class to Field class
+- Rename Model.register_matcher to Model.register_type
+
+0.2.0
+
+- Require 'hamachi/model' to import model as top-level constant
+- Require 'hamachi/ext' to extend arrays and other enumerables
+- New function Model.register_matcher
+
+0.1.0
+
+- Initial import from internal project.

data/lib/hash_with_field_validation.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'hash_with_field_validation/version'
+require 'hash_with_field_validation/field'
+
+
+class HashWithFieldValidation < Hash
+
+  # ------- schema declaration ---------------------------------------
+
+  def self.fields
+    @fields ||= {}
+  end
+
+  def self.field(name, options)
+    raise ArgumentError, "method ##{name} already defined" if method_defined?(name)
+    raise ArgumentError, "method ##{name}= already defined" if method_defined?("#{name}=")
+
+    field = options.fetch(:type)
+    field = Field.new(field) unless Field === field
+    field.initialize_options(options).freeze
+    self.fields[name.to_sym] = field
+
+    class_eval %{
+      def #{name}
+        self[:#{name}]
+      end
+    }
+
+    class_eval %{
+      def #{name}=(value)
+        field = self.class.fields[:#{name}]
+        if not field === value
+          raise "expected #{name} to be \#{field}, got \#{value.inspect}"
+        end
+        self[:#{name}] = value
+      end
+    }
+
+    return self
+  end
+
+  def self.schema(&block) # for anonymous inline models
+    Class.new HashWithFieldValidation, &block
+  end
+
+  def self.to_s
+    name ? name : "schema(#{fields.map { |name, field| "#{name}:#{field}"}.join(',')})"
+  end
+
+  def self.register_type(name, field_class)
+    singleton_class.send(:define_method, name) do |*args|
+      field_class.new(*args)
+    end
+  end
+
+  register_type :list, ListField
+  register_type :nullable, NullableField
+  register_type :enum, EnumField
+
+  Boolean = enum(true, false)
+
+
+  # ------- initialization -------------------------------------------
+
+  def initialize(snapshot, options = {})
+    update(snapshot) if options.fetch(:include_unknown_fields, true)
+
+    self.class.fields.each do |name, field|
+      value = snapshot.fetch(name, field.default_value)
+      self[name] = field.from_snapshot(value, options)
+    end
+
+    validate_fields! if options.fetch(:validate_fields, true)
+    freeze if options.fetch(:freeze, false)
+  end
+
+  def self.from_snapshot(snapshot, options = {})
+    return snapshot unless Hash === snapshot
+    self.new snapshot, options
+  end
+
+  def self.parse(string, options = {})
+    snapshot = JSON.parse(string, symbolize_names: true)
+    if Array === snapshot
+      snapshot.map { |each| from_snapshot each, options }
+    else
+      from_snapshot snapshot, options
+    end
+  end
+
+
+  # ------- validation -----------------------------------------------
+
+  def valid?
+    gen_error_messages { return false }
+    return true
+  end
+
+  def validate_fields!
+    gen_error_messages { |error| raise error }
+  end
+
+  def error_messages
+    enum_for(:gen_error_messages).entries
+  end
+
+  private
+
+  def gen_error_messages
+    self.class.fields.each do |name, field|
+      if not field === self[name]
+        yield "expected #{name} to be #{field}, got #{self[name].inspect}"
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: hash_with_field_validation
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- A Kuhn
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-03-14 00:00:00.000000000 Z
+dependencies: []
+description: 
+email:
+- akuhn@iam.unibe.ch
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/hash_with_field_validation.rb
+- lib/hash_with_field_validation/field.rb
+- lib/hash_with_field_validation/model.rb
+- lib/hash_with_field_validation/version.rb
+homepage: https://github.com/akuhn/hash_with_field_validation
+licenses: []
+metadata:
+  homepage_uri: https://github.com/akuhn/hash_with_field_validation
+  source_code_uri: https://github.com/akuhn/hash_with_field_validation
+  changelog_uri: https://github.com/akuhn/hash_with_field_validation/blob/master/lib/hash_with_field_validation/version.rb
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Flexible and type-safe representation of JSON data.
+test_files: []