enumancer 1.0.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 442028382a920f907a919270d86ec0504c846189b4feb4977a61ac037b73d926
-  data.tar.gz: '0619ee83dc5601322b699abe16aef370fbe0d818af78cf01f251405eef035ed7'
+  metadata.gz: 6c69c7e9a39930f42d98b2601e5fd6d2632ce25a19bfdbe2d6f1ee49a6b6a0e1
+  data.tar.gz: b7a8f6cdda9dddf00e54453d259e4355c1f3cc4d67b38a92f4c5c7fe811e2a5f
 SHA512:
-  metadata.gz: afdeb22fd58d8783f5d77cc7e5302f9daf7f6fbab7ae5a9ef0f0040700e15ad0be2da640b2397d73de6e8875743282040819db6cfa981181f45a7240fd03cd29
-  data.tar.gz: e6d94d75572491201eedeb486131f16cc23b2e1541632606cc09517c73612b81783e127f71632ec76e7f8c90a7854b54a0294c9417d6bdfdfbd0f2e3553804e7
+  metadata.gz: e2b678ef32d096a61d4d437d132ad47f471356c7ae9611d123af956a82ce0c56fea5078f5785258596f8cda042e7d0064020605f9f1a0bb5403ff3848a1218f5
+  data.tar.gz: 52037fa4302e276ae517e718f55ba8bd9c02a15d943d2457c4641e2129f2fbdbb15aa4082729fda9f3a9d91490e2d34428adfdc267cb0d9b91499afd31a69a13

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 2.0.0
+
+- Require Ruby 4.0 or newer.
+- Replace enum inheritance with `Enumancer.define` and automatically closed types.
+- Support plain enums, backed enums, and typed algebraic data types through one definition API.
+- Generate frozen `Data` classes for variants, with canonical instances for variants without fields.
+- Add exhaustive `match` and reusable `matcher` with unknown, duplicate, and missing branch checks before dispatch.
+- Add recursive field constraints through `Enumancer::Self`.
+- Support native Ruby patterns and JSON serialization, including nested declared types.
+- Remove mutable registries, unregistered instances, and non-strict fallbacks.
+
+This release intentionally breaks compatibility with 1.x. Replace subclasses of
+`Enumancer::Enum` with `Enumancer.define`, `entry` with `variant`, and
+`type Integer` with `backing: Integer`. See the README for examples.

data/LICENSE

@@ -0,0 +1,16 @@
+BSD 3-Clause License with Attribution
+
+Copyright (c) 2025, saikinmirai@gmail.com
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Attribution must be preserved. You must retain the original copyright notice, this list of conditions, and the following attribution clause in all copies or substantial portions of the Software.
+
+2. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+3. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE.
+
+Attribution: This software includes code developed by Łasačka (saikinmirai@gmail.com).

data/lib/enumancer/definition.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Enumancer
+  module Names
+    def self.normalize(name)
+      unless name.is_a?(String) || name.is_a?(Symbol)
+        raise TypeError, 'Names must be strings or symbols'
+      end
+
+      name.to_sym
+    end
+  end
+
+  Definition = Data.define(:name, :fields, :backing)
+
+  class DefinitionBuilder
+    def initialize(backing:)
+      @backed = backing
+      @definitions = {}
+    end
+
+    def variant(name, *values, **fields)
+      name = Names.normalize(name)
+      unless /\A[a-z][a-z0-9]*(?:_[a-z0-9]+)*\z/.match?(name.to_s)
+        raise DefinitionError, "Invalid variant name: #{name.inspect}"
+      end
+      raise DefinitionError, "Duplicate variant: #{name}" if @definitions.key?(name)
+
+      if @backed
+        raise DefinitionError, 'Backed variants require exactly one value' unless values.length == 1
+        raise DefinitionError, 'Backed variants cannot have fields' unless fields.empty?
+      elsif !values.empty?
+        raise DefinitionError, 'Backing values require a backing type'
+      end
+
+      normalized = {}
+      fields.each do |field, constraint|
+        field = Names.normalize(field)
+        unless /\A[a-z][a-z0-9]*(?:_[a-z0-9]+)*\z/.match?(field.to_s)
+          raise DefinitionError, "Invalid field name: #{field.inspect}"
+        end
+        raise DefinitionError, "Duplicate field: #{field}" if normalized.key?(field)
+
+        unless constraint.is_a?(Module) || constraint.equal?(Self)
+          raise DefinitionError, "Invalid type for field #{field}: #{constraint.inspect}"
+        end
+        normalized[field] = constraint
+      end
+
+      @definitions[name] = Definition.new(name, normalized.freeze, values.first)
+      nil
+    end
+
+    def finish
+      raise DefinitionError, 'At least one variant is required' if @definitions.empty?
+
+      @definitions.freeze
+      freeze
+      @definitions.values.freeze
+    end
+  end
+
+  module BackingSnapshot
+    def self.copy(value, visiting = {}.compare_by_identity)
+      raise DefinitionError, 'Backing values cannot contain cycles' if visiting.key?(value)
+
+      visiting[value] = true
+      case value
+      when String
+        value.dup.freeze
+      when Array
+        value.dup.map! { |item| copy(item, visiting) }.freeze
+      when Hash
+        value.each_with_object(value.dup.clear) do |(key, item), result|
+          result[copy(key, visiting)] = copy(item, visiting)
+        end.freeze
+      else
+        raise DefinitionError, 'Custom backing values must be frozen' unless value.frozen?
+
+        value
+      end
+    ensure
+      visiting.delete(value)
+    end
+  end
+
+  private_constant :Names, :Definition, :DefinitionBuilder, :BackingSnapshot
+end

data/lib/enumancer/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Enumancer
+  class DefinitionError < ArgumentError; end
+  class UnknownVariantError < KeyError; end
+  class MatchError < ArgumentError; end
+  class DuplicateBranchError < MatchError; end
+  class NonExhaustiveMatchError < MatchError; end
+end

data/lib/enumancer/matcher.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Enumancer
+  class MatchBuilder
+    def initialize(names)
+      @names = names
+      @handlers = {}
+    end
+
+    def on(name, &handler)
+      name = Names.normalize(name)
+      raise UnknownVariantError, "Unknown variant: #{name}" unless @names.include?(name)
+      raise DuplicateBranchError, "Duplicate branch: #{name}" if @handlers.key?(name)
+      raise MatchError, "A handler is required for #{name}" unless handler
+
+      @handlers[name] = handler
+      nil
+    end
+
+    def finish
+      missing = @names - @handlers.keys
+      unless missing.empty?
+        raise NonExhaustiveMatchError, "Missing branches: #{missing.join(', ')}"
+      end
+
+      @handlers.freeze
+      freeze
+      @handlers
+    end
+  end
+
+  class Matcher
+    def initialize(type, &block)
+      raise MatchError, 'A match block is required' unless block
+
+      @type = type
+      builder = MatchBuilder.new(type.variants)
+      builder.instance_eval(&block)
+      @handlers = builder.finish
+      freeze
+    end
+
+    def call(value)
+      raise TypeError, 'The value does not belong to this type' unless @type === value
+
+      @handlers.fetch(value.tag).call(value)
+    end
+  end
+
+  private_constant :MatchBuilder
+end

data/lib/enumancer/serialization.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Enumancer
+  module Serialization
+    def self.dump(value, visiting = {}.compare_by_identity)
+      with_visit(value, visiting) do
+        data = { name: value.tag }
+        if value.type.backed?
+          data[:value] = encode(value.value, visiting)
+        elsif !value.members.empty?
+          data[:fields] = value.to_h.transform_values { |field| encode(field, visiting) }
+        end
+        data
+      end
+    end
+
+    def self.encode(value, visiting = {}.compare_by_identity)
+      case value
+      when Value then dump(value, visiting)
+      when Array
+        with_visit(value, visiting) { value.map { |item| encode(item, visiting) } }
+      when Hash
+        with_visit(value, visiting) { value.transform_values { |item| encode(item, visiting) } }
+      when String, Symbol, Integer, Float, TrueClass, FalseClass, NilClass then value
+      else
+        raise TypeError, "Unsupported JSON value: #{value.class}"
+      end
+    end
+
+    def self.with_visit(value, visiting)
+      raise ArgumentError, 'Circular JSON value' if visiting.key?(value)
+
+      visiting[value] = true
+      begin
+        yield
+      ensure
+        visiting.delete(value)
+      end
+    end
+
+    def self.load(type, data)
+      raise ArgumentError, 'Expected a JSON object' unless data.is_a?(Hash)
+      raise ArgumentError, "Missing 'name' in JSON" unless data['name'].is_a?(String)
+
+      name = Names.normalize(data['name'])
+      schema = type.send(:definition_for, name)
+      allowed = ['name']
+      allowed << 'value' if type.backed?
+      allowed << 'fields' unless schema.fields.empty?
+      unknown = data.keys - allowed
+      raise ArgumentError, "Unknown JSON keys: #{unknown.join(', ')}" unless unknown.empty?
+
+      if type.backed?
+        instance = type[name]
+        if data.key?('value') && !JSON.parse(JSON.generate(encode(instance.value))).eql?(data['value'])
+          raise ArgumentError, 'The backing value does not match the variant'
+        end
+        return instance
+      end
+
+      attributes = data.fetch('fields', {})
+      raise ArgumentError, "Expected a JSON object for 'fields'" unless attributes.is_a?(Hash)
+
+      decoded = attributes.to_h do |field, value|
+        key = Names.normalize(field)
+        constraint = schema.fields[key]
+        [key, decode(constraint, value)]
+      end
+      type[name, **decoded]
+    end
+
+    def self.decode(constraint, value)
+      if constraint.is_a?(Type)
+        load(constraint, value)
+      elsif constraint.equal?(Symbol) && value.is_a?(String)
+        value.to_sym
+      else
+        value
+      end
+    end
+  end
+
+  private_constant :Serialization
+end

data/lib/enumancer/type.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Enumancer
+  class Type < Module
+    attr_reader :variants
+
+    def initialize(definitions, backing:)
+      super()
+      @backing_type = backing
+      @definitions = {}
+      @classes = {}
+      @class_names = {}.compare_by_identity
+      @singletons = {}
+      @value_index = {}
+      include Value
+
+      definitions.each { |definition| install(definition) }
+      @variants = @definitions.keys.freeze
+      [@definitions, @classes, @class_names, @singletons, @value_index].each(&:freeze)
+      freeze
+    end
+
+    def backed? = !@backing_type.equal?(UNSET)
+
+    def ===(value)
+      @class_names.key?(value.class)
+    end
+
+    def [](name, **attributes)
+      name = Names.normalize(name)
+      definition_for(name)
+      @classes.fetch(name).new(**attributes)
+    end
+
+    def all
+      unless @singletons.length == @definitions.length
+        raise TypeError, 'Types with fields cannot enumerate all values; use variants'
+      end
+
+      @singletons.values.freeze
+    end
+
+    def values
+      raise TypeError, 'This type has no backing values' unless backed?
+
+      @definitions.values.map(&:backing).freeze
+    end
+
+    def from_value(value)
+      raise TypeError, 'This type has no backing values' unless backed?
+
+      @value_index.fetch(value) { raise KeyError, "Unknown backing value: #{value.inspect}" }
+    end
+
+    def matcher(&block)
+      Matcher.new(self, &block)
+    end
+
+    def match(value, &block)
+      matcher(&block).call(value)
+    end
+
+    def from_json(json)
+      Serialization.load(self, JSON.parse(json))
+    end
+
+    private
+
+    def initialize_copy(_other)
+      raise TypeError, 'Enumancer types cannot be copied'
+    end
+
+    def definition_for(name)
+      @definitions.fetch(name) { raise UnknownVariantError, "Unknown variant: #{name}" }
+    end
+
+    def install(definition)
+      name = definition.name
+      raise DefinitionError, "Reserved variant name: #{name}" if respond_to?(name, true)
+
+      constant = name.to_s.split('_').map(&:capitalize).join
+      raise DefinitionError, "Duplicate variant constant: #{constant}" if const_defined?(constant, false)
+
+      fields = definition.fields.transform_values { |constraint| constraint.equal?(Self) ? self : constraint }.freeze
+      reserved = fields.keys & (Data.instance_methods + Data.private_instance_methods + Value.instance_methods)
+      raise DefinitionError, "Reserved fields: #{reserved.join(', ')}" unless reserved.empty?
+
+      backing = prepare_backing(definition.backing) if backed?
+      definition = Definition.new(name, fields, backing)
+      klass = build_class(definition)
+      @definitions[name] = definition
+      @classes[name] = klass
+      @class_names[klass] = name
+      const_set(constant, klass)
+
+      if fields.empty?
+        instance = klass.new
+        @singletons[name] = instance
+        @value_index[backing] = instance if backed?
+        constructor = lambda do |*args, **attributes|
+          unless args.empty? && attributes.empty?
+            raise ArgumentError, "#{name} does not accept fields"
+          end
+
+          instance
+        end
+        klass.define_singleton_method(:new, &constructor)
+        klass.define_singleton_method(:[], &constructor)
+      end
+
+      define_singleton_method(name) { |**attributes| self[name, **attributes] }
+      klass.freeze
+    end
+
+    def prepare_backing(value)
+      unless @backing_type === value
+        raise TypeError, "Expected backing type #{@backing_type}, got #{value.class}"
+      end
+
+      snapshot = BackingSnapshot.copy(value)
+      raise DefinitionError, "Duplicate backing value: #{value.inspect}" if @value_index.key?(snapshot)
+
+      snapshot
+    end
+
+    def build_class(definition)
+      owner = self
+      fields = definition.fields
+      klass = Data.define(*fields.keys) do
+        include owner
+
+        define_method(:initialize) do |**attributes|
+          missing = fields.keys - attributes.keys
+          unknown = attributes.keys - fields.keys
+          raise ArgumentError, "Missing fields: #{missing.join(', ')}" unless missing.empty?
+          raise ArgumentError, "Unknown fields: #{unknown.join(', ')}" unless unknown.empty?
+
+          fields.each do |field, constraint|
+            unless constraint === attributes[field]
+              raise TypeError, "Invalid type for #{field}: expected #{constraint}, got #{attributes[field].class}"
+            end
+          end
+          super(**attributes)
+        end
+      end
+      klass.define_singleton_method(:enum_type) { owner }
+      klass.define_singleton_method(:variant_name) { definition.name }
+      klass.define_singleton_method(:inherited) { |_child| raise TypeError, 'Variants cannot be subclassed' }
+      klass.define_method(:value) { definition.backing } if backed?
+      klass.private_class_method(:allocate)
+      klass
+    end
+  end
+end

data/lib/enumancer/value.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Enumancer
+  module Value
+    def type = self.class.enum_type
+    def tag = self.class.variant_name
+    def to_sym = tag
+    def to_s = tag.to_s
+
+    def match(&block)
+      type.match(self, &block)
+    end
+
+    def deconstruct_keys(keys)
+      fields = super(keys&.reject { |key| key == :tag })
+      keys.nil? || keys.include?(:tag) ? fields.merge(tag: tag) : fields
+    end
+
+    def to_json(*args)
+      Serialization.dump(self).to_json(*args)
+    end
+  end
+
+  private_constant :Value
+end

data/lib/enumancer.rb

@@ -1 +1,26 @@
-require_relative 'enum'
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'enumancer/errors'
+require_relative 'enumancer/definition'
+require_relative 'enumancer/matcher'
+require_relative 'enumancer/value'
+require_relative 'enumancer/serialization'
+require_relative 'enumancer/type'
+
+module Enumancer
+  Self = Object.new.freeze
+  UNSET = Object.new.freeze
+  private_constant :UNSET
+
+  def self.define(backing: UNSET, &block)
+    raise ArgumentError, 'A definition block is required' unless block
+    unless backing.equal?(UNSET) || backing.is_a?(Module)
+      raise TypeError, 'The backing type must be a class or module'
+    end
+
+    builder = DefinitionBuilder.new(backing: !backing.equal?(UNSET))
+    builder.instance_eval(&block)
+    Type.new(builder.finish, backing: backing)
+  end
+end

data/readme.md

@@ -0,0 +1,241 @@
+# Enumancer
+
+[![Gem Version](https://img.shields.io/gem/v/enumancer?include_prereleases&logo=rubygems&logoColor=%23e0e0e0&label=version&labelColor=%23FF748C&color=pink&style=for-the-badge)](https://rubygems.org/gems/enumancer)
+
+Closed enums and algebraic data types for **Ruby 4.0+**, with typed fields and
+exhaustive matching. No runtime dependencies outside the Ruby standard library.
+
+## Installation
+
+```ruby
+gem 'enumancer', '~> 2.0'
+```
+
+```sh
+bundle install
+```
+
+## Plain enums
+
+```ruby
+require 'enumancer'
+
+Color = Enumancer.define do
+  variant :red
+  variant :green
+  variant :blue
+end
+
+Color.red.equal?(Color[:red]) # => true
+Color.red.tag                # => :red
+Color.red.to_sym             # => :red
+Color.red.to_s               # => "red"
+Color.red.type               # => Color
+Color === Color.red          # => true
+Color.variants               # => [:red, :green, :blue]
+Color.all                    # => [Color.red, Color.green, Color.blue]
+```
+
+Each variant has its own generated `Data` class, such as `Color::Red`.
+Variants without fields return canonical frozen instances and store no payload
+or tag fields in those instances. Plain enum instances have no `value` method.
+
+Names can be symbols or strings. Variant and field names must be lowercase
+snake_case identifiers. Names that conflict with existing type or instance
+methods are rejected during definition.
+
+## Backed enums
+
+```ruby
+Status = Enumancer.define(backing: Integer) do
+  variant :draft, 0
+  variant :published, 1
+end
+
+Status.draft.value   # => 0
+Status.from_value(1) # => Status.published
+Status.values        # => [0, 1]
+Status.backed?       # => true
+```
+
+Every variant must have exactly one unique backing value matching the declared
+class or module. Backed variants cannot have payload fields. `nil` is a backing
+value when the declared type accepts it; it does not mean an omitted value.
+
+Reverse lookup uses `eql?` and `hash`, so `1` and `1.0` are distinct backing
+values. Unknown values raise `KeyError`.
+
+Strings, arrays, and hashes used as backing values are copied and recursively
+frozen without freezing the caller's objects. Cyclic backing values are rejected.
+Custom backing objects must already be frozen; their nested state must remain
+stable for reverse lookup.
+
+## Algebraic data types
+
+```ruby
+Result = Enumancer.define do
+  variant :pending
+  variant :ok, value: Integer
+  variant :error, message: String
+end
+
+result = Result.ok(value: 42)
+result.value                  # => 42
+result.tag                    # => :ok
+Result[:error, message: 'Failed'].message # => "Failed"
+Result.variants               # => [:pending, :ok, :error]
+```
+
+Field constraints accept classes, modules, and other Enumancer types. All fields
+are required. Missing and unknown fields raise `ArgumentError`; invalid values
+raise `TypeError`. Checks also apply to generated class constructors and `with`:
+
+```ruby
+result.with(value: 43)         # => Result.ok(value: 43)
+Result::Ok.new(value: 'wrong') # raises TypeError
+```
+
+Records use `Data` equality and hashing: equal records must have the same variant
+class and equal fields. Types with fields cannot enumerate every possible value;
+use `variants` instead of `all`.
+
+Records are shallowly immutable, following Ruby's `Data` semantics. Nested
+payload objects remain shared with the caller. Freeze or copy mutable payloads
+before using records as hash keys.
+
+## Exhaustive matching
+
+```ruby
+result.match do
+  on(:pending) { 'Waiting' }
+  on(:ok)      { |ok| ok.value.to_s }
+  on(:error)   { |error| error.message }
+end
+```
+
+Each handler receives the entire variant instance. The selected handler's return
+value becomes the match result, including `nil` and `false`.
+
+The outer block runs in a branch-builder context. It collects handlers without
+executing them. Every variant must be covered exactly once before any handler
+runs:
+
+- Missing branches raise `Enumancer::NonExhaustiveMatchError`.
+- Duplicate branches raise `Enumancer::DuplicateBranchError`.
+- Unknown variants raise `Enumancer::UnknownVariantError`.
+- Missing handler blocks raise `Enumancer::MatchError`.
+
+There is no wildcard branch. Completeness is checked at runtime against the
+closed definition, including when the current value belongs to a covered branch.
+Handler exceptions propagate normally.
+
+For reuse, build a matcher once. Completeness is checked when it is built:
+
+```ruby
+render = Result.matcher do
+  on(:pending) { 'Waiting' }
+  on(:ok)      { |ok| ok.value.to_s }
+  on(:error)   { |error| error.message }
+end
+
+render.call(Result.ok(value: 42)) # => "42"
+```
+
+`Result.match(result) { ... }` also supports direct type-level dispatch.
+Passing a value from another type to a matcher raises `TypeError`.
+
+## Recursive types
+
+```ruby
+Expr = Enumancer.define do
+  variant :number, value: Integer
+  variant :add, left: Enumancer::Self, right: Enumancer::Self
+end
+
+evaluate = Expr.matcher do
+  on(:number) { |number| number.value }
+  on(:add)    { |add| evaluate.call(add.left) + evaluate.call(add.right) }
+end
+
+tree = Expr.add(left: Expr.number(value: 2), right: Expr.number(value: 3))
+evaluate.call(tree) # => 5
+```
+
+`Enumancer::Self` resolves to the type being defined. Recursive fields reject
+values from other types.
+
+## Native Ruby patterns
+
+Generated classes also support native patterns:
+
+```ruby
+case result
+in Result::Ok(value:)
+  puts value
+in { tag: :error, message: }
+  warn message
+end
+```
+
+`deconstruct_keys` exposes payload fields and `tag`. Use Enumancer's `match`
+when every variant must have a handler.
+
+## JSON
+
+```ruby
+Color.red.to_json
+# => '{"name":"red"}'
+
+Status.draft.to_json
+# => '{"name":"draft","value":0}'
+
+Result.ok(value: 42).to_json
+# => '{"name":"ok","fields":{"value":42}}'
+
+Result.from_json('{"name":"ok","fields":{"value":42}}')
+# => Result.ok(value: 42)
+```
+
+Deserialization validates variant names, envelope keys, field names, and field
+types. Plain and backed enums return their canonical instances. Backed input
+may omit `value`; if present, it must match the named variant's JSON value.
+
+Fields explicitly constrained to another Enumancer type, including `Self`, are
+decoded recursively. Fields declared as `Symbol` are restored from JSON strings.
+Unparameterized `Array`, `Hash`, and `Object` fields follow ordinary JSON
+semantics: collection element types, symbol keys, and nested enum identities
+cannot be inferred from those constraints. Custom objects require conversion to
+supported JSON values; arbitrary classes are not instantiated by deserialization.
+Circular payloads are rejected.
+
+## Closed definitions
+
+After the definition block finishes, the type, variant classes, and registry are
+frozen. Variants cannot be added, removed, or subclassed. Unknown names raise
+`Enumancer::UnknownVariantError`; there is no `:unknown` fallback. Type objects
+cannot be copied.
+
+## Migrating from 1.x
+
+Version 2 intentionally breaks compatibility with the inheritance API:
+
+```ruby
+Status = Enumancer.define(backing: Integer) do
+  variant :draft, 0
+  variant :published, 1
+end
+```
+
+Replace `class Status < Enumancer::Enum` with the factory, `type Integer` with
+`backing: Integer`, and `entry` with `variant`. Remove `strict:` options: names
+and types are always checked. Replace `name_for(value)` with
+`from_value(value).tag`, and `keys` with `variants`. Runtime registration,
+`remove`, unregistered instances, and inheritance are no longer supported.
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+gem build enumancer.gemspec
+```

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: enumancer
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Łasačka
@@ -10,22 +10,30 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: |2
-      Enumancer provides a predictable, type-safe registry for named values.
-      Each entry is unique by both name and value, with optional type constraints and strict mode.
+      Enumancer provides plain enums, backed enums, and algebraic data types
+      with typed fields and exhaustive matching.
 email: saikinmirai@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/enum.rb
+- CHANGELOG.md
+- LICENSE
 - lib/enumancer.rb
+- lib/enumancer/definition.rb
+- lib/enumancer/errors.rb
+- lib/enumancer/matcher.rb
+- lib/enumancer/serialization.rb
+- lib/enumancer/type.rb
+- lib/enumancer/value.rb
+- readme.md
 homepage: https://github.com/lasaczka/enumancer
 licenses:
 - BSD-3-Clause-Attribution
 metadata:
   changelog_uri: https://github.com/lasaczka/enumancer/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/lasaczka/enumancer/issues
-  documentation_uri: https://rubydoc.info/gems/enumancer/1.0.1
+  documentation_uri: https://rubydoc.info/gems/enumancer/2.0.0
 rdoc_options: []
 require_paths:
 - lib
@@ -33,14 +41,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: '4.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.8.0.dev
+rubygems_version: 4.0.20
 specification_version: 4
-summary: Easy to use typed enums.
+summary: Closed enums and algebraic data types for Ruby.
 test_files: []

data/lib/enum.rb

@@ -1,222 +0,0 @@
-# frozen_string_literal: true
-
-# Enumancer::Enum provides a declarative, type-safe registry for named values.
-# Each entry is unique by both name and value. Values can be of any type,
-# but you may optionally declare a type constraint using `type`.
-# If type is defined, values are strictly checked.
-#
-# Enum entries are registered via `.entry(name, value)` and accessed via `.name` or `[]`.
-# Each entry becomes a singleton method of the class and returns an instance of the enum.
-#
-# You may enable strict mode via `type Klass, strict: true`, which disables fallbacks
-# and raises errors when accessing unknown names or values.
-#
-# @example Define an enum
-#   class MyEnum < Enumancer::Enum
-#     type Integer, strict: true
-#     entry :low, 1
-#     entry :high, 2
-#   end
-#
-# @example Access values
-#   MyEnum[:low].value         # => 1
-#   MyEnum.high.to_sym         # => :low
-#   MyEnum.low == MyEnum[:low] # => true
-#
-# @example Serialize to JSON
-#   MyEnum.low.to_json         # => '{"name":"low","value":1}'
-#
-# @example Deserialize from JSON
-#   MyEnum.from_json('{"name":"low"}') # => MyEnum.low
-
-require 'json'
-
-module Enumancer
-  class Enum
-    attr_reader :value
-
-    def initialize(value)
-      @value = value
-    end
-
-    # Returns the symbolic name of the value as a string
-    #
-    # @return [String]
-    def to_s
-      to_sym.to_s
-    end
-
-    # Returns the symbolic name of the value as a symbol
-    #
-    # @return [Symbol]
-    def to_sym
-      name = self.class.name_for(value)
-      raise KeyError, "Unregistered enum value: #{value.inspect}" if name.nil? && self.class.strict?
-      name || :unknown
-    end
-
-    # Returns a debug-friendly string representation
-    #
-    # @return [String]
-    def inspect
-      "#<#{self.class.name} #{to_sym.inspect}:#{value.inspect}>"
-    end
-
-    # Equality based on class and value
-    #
-    # @param other [Object]
-    # @return [Boolean]
-    def ==(other)
-      other.is_a?(self.class) && other.value == value
-    end
-
-    alias eql? ==
-    def hash = value.hash
-
-    # Serializes the enum to JSON
-    #
-    # @return [String]
-    def to_json(*args)
-      { name: to_sym, value: value }.to_json(*args)
-    end
-
-    class << self
-      # Called when subclassing Enum
-      #
-      # @param subclass [Class]
-      # @return [void]
-      def inherited(subclass)
-        subclass.instance_variable_set(:@registry, {})
-        subclass.instance_variable_set(:@values, {})
-        subclass.instance_variable_set(:@strict_mode, false)
-      end
-
-      # Declares the expected type of all enum values
-      #
-      # @param klass [Class] the type constraint for values
-      # @param strict [Boolean] whether to enable strict mode
-      # @return [void]
-      def type(klass, strict: false)
-        unless klass.is_a?(Class)
-          raise ArgumentError, "Expected a Class, got #{klass.inspect}"
-        end
-        @value_type = klass
-        @strict_mode = strict
-      end
-
-      # Returns whether strict mode is enabled
-      #
-      # @return [Boolean]
-      def strict?
-        @strict_mode == true
-      end
-
-      # Registers a new enum entry with a unique name and value
-      #
-      # @param name [Symbol, String] symbolic name of the entry
-      # @param value [Object] value of the entry
-      # @raise [ArgumentError] if name or value is already registered
-      # @raise [TypeError] if value does not match declared type
-      # @return [void]
-      def entry(name, value)
-        name = name.to_sym
-
-        if defined?(@value_type) && !value.is_a?(@value_type)
-          raise TypeError, "Invalid value type for #{name}: expected #{@value_type}, got #{value.class}"
-        end
-
-        if @values.key?(value)
-          existing = @values[value]
-          raise ArgumentError, "Duplicate value #{value.inspect} for #{name}; already assigned to #{existing}"
-        end
-
-        if @registry.key?(name)
-          raise ArgumentError, "Duplicate name #{name}; already registered with value #{@registry[name].value.inspect}"
-        end
-
-        instance = new(value)
-        @registry[name] = instance
-        @values[value] = name
-
-        define_singleton_method(name) { instance }
-      end
-
-      # Retrieves an enum instance by name
-      #
-      # @param name [Symbol, String]
-      # @return [Enumancer::Enum, nil]
-      def [](name)
-        @registry[name.to_sym]
-      end
-
-      # Retrieves an enum instance by name, raising if not found
-      #
-      # @param name [Symbol, String]
-      # @return [Enumancer::Enum]
-      # @raise [KeyError]
-      def fetch(name)
-        @registry.fetch(name.to_sym)
-      end
-
-      # Resolves the symbolic name for a given value
-      #
-      # @param value [Object]
-      # @return [Symbol, nil]
-      def name_for(value)
-        @values[value]
-      end
-
-      # Returns all registered enum instances
-      #
-      # @return [Array<Enumancer::Enum>]
-      def all
-        @registry.values
-      end
-
-      # Returns all registered names
-      #
-      # @return [Array<Symbol>]
-      def keys
-        @registry.keys
-      end
-
-      # Returns all raw values
-      #
-      # @return [Array<Object>]
-      def values
-        @registry.values.map(&:value)
-      end
-
-      # Removes an enum entry by name
-      #
-      # @param name [Symbol, String]
-      # @return [Enumancer::Enum, nil] the removed entry or nil
-      def remove(name)
-        name = name.to_sym
-        entry = @registry.delete(name)
-        if entry
-          @values.delete(entry.value)
-          singleton_class.undef_method(name) if respond_to?(name)
-        end
-        entry
-      end
-
-      # Deserializes an enum from JSON
-      #
-      # @param json [String]
-      # @return [Enumancer::Enum, nil]
-      # @raise [KeyError] if strict and name is unknown
-      def from_json(json)
-        data = JSON.parse(json, symbolize_names: true)
-        name = data[:name]
-        raise KeyError, "Missing 'name' key in JSON" if name.nil?
-
-        entry = self[name]
-        if strict? && entry.nil?
-          raise KeyError, "Unregistered enum name: #{name.inspect}"
-        end
-        entry
-      end
-    end
-  end
-end