field_struct 0.15.0 → 1.0.0.pre1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. checksums.yaml +4 -4
  2. data/.claude-plugin/marketplace.json +13 -0
  3. data/.claude-plugin/plugin.json +9 -0
  4. data/AGENTS.md +47 -54
  5. data/CHANGELOG.md +53 -640
  6. data/LICENSE.txt +21 -0
  7. data/README.md +33 -628
  8. data/USAGE.md +771 -715
  9. data/docs/getting_started.md +139 -325
  10. data/lib/field_struct/base.rb +241 -1149
  11. data/lib/field_struct/class_macros.rb +163 -0
  12. data/lib/field_struct/describer.rb +167 -0
  13. data/lib/field_struct/errors.rb +182 -62
  14. data/lib/field_struct/exceptions.rb +40 -0
  15. data/lib/field_struct/field.rb +69 -135
  16. data/lib/field_struct/field_builder.rb +110 -0
  17. data/lib/field_struct/field_checks.rb +50 -0
  18. data/lib/field_struct/introspection.rb +199 -0
  19. data/lib/field_struct/json_codec.rb +240 -0
  20. data/lib/field_struct/metadata.rb +65 -260
  21. data/lib/field_struct/model_name.rb +27 -27
  22. data/lib/field_struct/option_checker.rb +121 -0
  23. data/lib/field_struct/partial.rb +49 -0
  24. data/lib/field_struct/presence.rb +45 -0
  25. data/lib/field_struct/rbs.rb +151 -271
  26. data/lib/field_struct/registered_option.rb +113 -0
  27. data/lib/field_struct/registry.rb +40 -50
  28. data/lib/field_struct/restrictions.rb +90 -0
  29. data/lib/field_struct/scaffold.rb +274 -301
  30. data/lib/field_struct/suggestion.rb +33 -0
  31. data/lib/field_struct/types/array.rb +147 -126
  32. data/lib/field_struct/types/base.rb +113 -124
  33. data/lib/field_struct/types/big_decimal.rb +59 -55
  34. data/lib/field_struct/types/binary.rb +18 -25
  35. data/lib/field_struct/types/boolean.rb +74 -97
  36. data/lib/field_struct/types/builtin.rb +32 -0
  37. data/lib/field_struct/types/date.rb +23 -137
  38. data/lib/field_struct/types/datetime.rb +30 -139
  39. data/lib/field_struct/types/element_options.rb +51 -0
  40. data/lib/field_struct/types/email.rb +27 -38
  41. data/lib/field_struct/types/float.rb +58 -56
  42. data/lib/field_struct/types/format_presets.rb +30 -0
  43. data/lib/field_struct/types/hash.rb +144 -0
  44. data/lib/field_struct/types/immutable_string.rb +16 -9
  45. data/lib/field_struct/types/integer.rb +74 -102
  46. data/lib/field_struct/types/nested.rb +57 -58
  47. data/lib/field_struct/types/preset_resolver.rb +9 -24
  48. data/lib/field_struct/types/rfc3339_format.rb +70 -153
  49. data/lib/field_struct/types/string.rb +48 -46
  50. data/lib/field_struct/types/symbol.rb +23 -20
  51. data/lib/field_struct/types/temporal.rb +232 -0
  52. data/lib/field_struct/types/time.rb +32 -145
  53. data/lib/field_struct/types/union.rb +111 -65
  54. data/lib/field_struct/types/union_pick.rb +139 -0
  55. data/lib/field_struct/types/url.rb +24 -35
  56. data/lib/field_struct/types/uuid.rb +24 -35
  57. data/lib/field_struct/types/value.rb +14 -9
  58. data/lib/field_struct/types/zone.rb +118 -0
  59. data/lib/field_struct/version.rb +3 -3
  60. data/lib/field_struct.rb +102 -122
  61. data/sig/field_struct.rbs +1180 -2300
  62. data/sig/manifest.yaml +6 -0
  63. data/skills/field-struct/SKILL.md +73 -159
  64. metadata +37 -28
  65. data/CODE_OF_CONDUCT.md +0 -132
  66. data/UPGRADING.md +0 -743
  67. data/lib/field_struct/error.rb +0 -48
  68. data/lib/field_struct/types/temporal_parser.rb +0 -93
  69. data/lib/field_struct/types/time_format_resolver.rb +0 -54
  70. data/lib/field_struct/types/zone_option.rb +0 -267
@@ -1,17 +1,24 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require_relative 'string'
4
-
5
3
  module FieldStruct
6
4
  module Types
7
- # Like {Types::String}, but the coerced value is frozen. Useful when
8
- # downstream code must not mutate a stored string.
9
- class ImmutableString < FieldStruct::Types::String
10
- # @param value [#to_s, nil] anything stringable; +nil+ stays +nil+
11
- # @return [::String, nil] frozen string, or +nil+ if input is +nil+
5
+ # Text like {String}, but the result is a frozen copy; the input is never touched.
6
+ class ImmutableString < String
7
+ # @param value [::Object]
8
+ # @return [::String, nil] a frozen copy
12
9
  def coerce(value, **)
13
- result = super
14
- result.nil? ? nil : result.dup.freeze
10
+ text = super
11
+ text&.dup&.freeze
12
+ end
13
+
14
+ # Internal: {#coerce} with the options as one Hash, no keyword splat (see Types::Base.positional_coerce?).
15
+ #
16
+ # @param value [::Object]
17
+ # @param options [::Hash{::Symbol=>::Object}]
18
+ # @return [::String, nil]
19
+ # @api private
20
+ def coerce_positional(value, options)
21
+ super&.dup&.freeze
15
22
  end
16
23
  end
17
24
  end
@@ -1,132 +1,104 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require_relative 'base'
4
-
5
3
  module FieldStruct
6
4
  module Types
7
- # Integer type. Strings parse in base 10 unless the field declares a
8
- # +base:+, so "010" is ten (not octal eight) and "0x1A" is refused rather
9
- # than read as hex. Float-shaped strings like "3.14" raise rather than
10
- # silently truncate. Float numerics, by contrast, are truncated — that
11
- # matches +Kernel#Integer+'s own behavior on numeric input — unless the
12
- # field declares +strict: true+, which refuses any non-integral value.
5
+ # Whole numbers. Strings are base 10 unless +base:+ says otherwise; floats truncate.
13
6
  class Integer < Base
14
- # The radixes +Kernel#Integer+ accepts for a +base:+ option.
15
- # @return [::Range<::Integer>]
16
- BASES = (2..36)
17
-
18
- # Native options: an +in:+ Array or Range of allowed values, a
19
- # +base:+ Integer radix (2..36) for string input, and a +strict:+
20
- # Boolean.
21
- #
22
- # @return [::Hash{::Symbol => ::Hash{::Symbol => Object}}]
23
- def self.own_option_schema
24
- {
25
- in: option(type: [::Array, ::Range]),
26
- base: option(type: [::Integer]),
27
- strict: option(type: [::TrueClass, ::FalseClass])
28
- }
29
- end
7
+ # Largest integer part, in decimal digits, accepted from a BigDecimal.
8
+ # @return [::Integer]
9
+ MAX_DECIMAL_DIGITS = 4300
30
10
 
31
- # Refuse a +base:+ outside 2..36 at field-declaration time. A
32
- # non-Integer +base:+ is left for the option-shape check to report.
33
- #
34
- # @param options [::Hash{::Symbol => Object, nil}] the per-field options hash
35
- # @return [::Hash{::Symbol => Object, nil}] the options, unchanged
36
- # @raise [ArgumentError] when +base:+ is an Integer outside 2..36
37
- def self.resolve_options(options)
38
- base = options[:base]
39
- if base.is_a?(::Integer) && !BASES.cover?(base)
40
- raise ArgumentError, "base: on Integer expects an Integer from 2 to 36, got #{base}"
11
+ class << self
12
+ # @return [::Hash{::Symbol=>::Hash{::Symbol=>::Object}}]
13
+ def own_option_schema
14
+ {
15
+ in: option(type: [::Array, ::Range]),
16
+ base: option(type: ::Integer),
17
+ strict: option(type: [::TrueClass, ::FalseClass])
18
+ }
41
19
  end
42
-
43
- options
44
20
  end
45
21
 
46
- # @param value [::Integer, Numeric, ::String, nil] +nil+ → +nil+;
47
- # +Integer+ passes through; a String parses in +base+ (surrounding
48
- # whitespace and digit underscores allowed; float-shaped or
49
- # out-of-base strings raise ArgumentError); other numerics flow
50
- # through +Kernel#Integer+ — Floats are truncated;
51
- # Symbols/Booleans/Arrays raise TypeError.
52
- # @param base [::Integer, nil] radix (2..36) for String input; +nil+
53
- # means 10
54
- # @param strict [Boolean, nil] when true, refuse a value that is not a
55
- # whole number (+12.7+, a +Time+) instead of truncating it; an
56
- # integral one (+12.0+) still becomes its Integer
57
- # @return [::Integer, nil] +nil+ for +nil+ input, otherwise the parsed integer
58
- # @raise [ArgumentError, TypeError] when the value cannot be coerced,
59
- # including a NaN or ±Infinity Numeric (Float, BigDecimal) and a
60
- # Complex with an imaginary part
61
- def coerce(value, base: 10, strict: false, **)
62
- return nil if value.nil?
63
- return value if value.is_a?(::Integer)
64
- return parse_string(value, base || 10) if value.is_a?(::String)
65
- if value.is_a?(::Numeric) && !value.finite?
66
- # The class, never the value — see Types::Time#coerce.
67
- raise ArgumentError, "Integer fields expect a finite number, got a non-finite #{value.class}"
22
+ class << self
23
+ # Checks that +base:+ names a usable radix.
24
+ #
25
+ # @param options [::Hash{::Symbol=>::Object}]
26
+ # @return [::Hash{::Symbol=>::Object}]
27
+ # @raise [ArgumentError] when +base:+ is outside 2..36
28
+ def resolve_options(options, **)
29
+ base = options[:base]
30
+ return options if base.nil? || (2..36).cover?(base)
31
+
32
+ raise ::ArgumentError, "base: on Integer expects an Integer from 2 to 36, got #{base}"
68
33
  end
34
+ end
69
35
 
70
- refuse_huge_decimal!(value)
71
-
72
- whole = begin
73
- ::Kernel.Integer(value)
74
- rescue ::RangeError
75
- # A Complex with an imaginary part; Kernel's message echoes the value.
76
- raise ArgumentError, "Integer fields could not read a #{value.class} as a number", cause: nil
77
- end
78
- refuse_inexact!(value, whole) if strict
79
- whole
36
+ # @param value [::Object]
37
+ # @param base [::Integer, nil] radix for String input (default 10)
38
+ # @param strict [Boolean, nil] accept only whole numbers
39
+ # @return [::Integer, nil]
40
+ # @raise [ArgumentError, TypeError] when the value cannot be read
41
+ def coerce(value, base: nil, strict: false, **)
42
+ coerce_with(value, base, strict)
80
43
  end
81
44
 
82
- # The most integer digits a decimal may expand to. +BigDecimal('1e10000000')+
83
- # is 11 bytes, but its Integer takes seconds to build, so untrusted JSON
84
- # could burn CPU. The same limit as Python's int/str conversion
85
- # (CVE-2020-10735).
45
+ # Internal: {#coerce} with the options as one Hash, no keyword splat (see Types::Base.positional_coerce?).
86
46
  #
87
- # @return [::Integer]
88
- MAX_DECIMAL_DIGITS = 4300
47
+ # @param value [::Object]
48
+ # @param options [::Hash{::Symbol=>::Object}]
49
+ # @return [::Integer, nil]
50
+ # @api private
51
+ def coerce_positional(value, options)
52
+ coerce_with(value, options[:base], options[:strict])
53
+ end
89
54
 
90
- # @return [Class] the top-level +::Integer+ class
55
+ # @return [::Class]
91
56
  def ruby_type
92
57
  ::Integer
93
58
  end
94
59
 
95
60
  private
96
61
 
97
- # @param value [Object]
98
- # @return [void]
99
- # @raise [ArgumentError] when +value+ is a decimal whose integer part has
100
- # more than {MAX_DECIMAL_DIGITS} digits
101
- def refuse_huge_decimal!(value)
102
- return unless defined?(::BigDecimal) && value.is_a?(::BigDecimal)
103
- return if value.exponent <= MAX_DECIMAL_DIGITS
62
+ def coerce_with(value, base, strict)
63
+ return nil if value.nil?
64
+ return parse_string(value, base || 10) if value.is_a?(::String)
104
65
 
105
- raise ArgumentError, "Integer fields read a decimal of at most #{MAX_DECIMAL_DIGITS} digits, " \
106
- "got a larger #{value.class}"
66
+ guard_number(value)
67
+ strict ? whole_number(value) : convert(value)
107
68
  end
108
69
 
109
- # @param value [Object] the input, already read by +Kernel#Integer+
110
- # @param whole [::Integer] what +Kernel#Integer+ made of it
111
- # @return [void]
112
- # @raise [ArgumentError] unless +whole+ equals +value+ — i.e. the read
113
- # truncated a fraction, or went through +to_i+ on a non-number
114
- def refuse_inexact!(value, whole)
115
- return if whole == value
70
+ def parse_string(text, radix)
71
+ Integer(text, radix, exception: false) ||
72
+ raise(::ArgumentError, "Integer fields expect a base-#{radix} integer, got a String that is not one")
73
+ end
74
+
75
+ def guard_number(value)
76
+ return unless value.is_a?(::Float) || value.is_a?(::BigDecimal)
77
+
78
+ raise ::ArgumentError, "Integer fields expect a finite number, got a non-finite #{value.class}" unless value.finite?
79
+ return unless value.is_a?(::BigDecimal) && value.exponent > MAX_DECIMAL_DIGITS
116
80
 
117
- # The class, never the value — see Types::Time#coerce.
118
- raise ArgumentError, "Integer fields with strict: true expect a whole number, got a #{value.class} that is not one"
81
+ raise ::ArgumentError, "Integer fields read a decimal of at most #{MAX_DECIMAL_DIGITS} digits, got a larger BigDecimal"
119
82
  end
120
83
 
121
- # @param value [::String]
122
- # @param base [::Integer]
123
- # @return [::Integer]
124
- # @raise [ArgumentError] when the string is not an integer in +base+
125
- def parse_string(value, base)
126
- ::Kernel.Integer(value, base)
127
- rescue ::ArgumentError
128
- # The class, never the value — see Types::Time#coerce.
129
- raise ArgumentError, "Integer fields expect a base-#{base} integer, got a String that is not one", cause: nil
84
+ def convert(value)
85
+ Integer(value)
86
+ rescue ::RangeError, ::ArgumentError
87
+ raise ::ArgumentError, "Integer fields could not read #{class_phrase(value)} as a number", cause: nil
88
+ end
89
+
90
+ def whole_number(value)
91
+ result = value.is_a?(::Numeric) ? attempt(value) : nil
92
+ return result if result && result == value
93
+
94
+ raise ::ArgumentError,
95
+ "Integer fields with strict: true expect a whole number, got #{class_phrase(value)} that is not one"
96
+ end
97
+
98
+ def attempt(value)
99
+ Integer(value)
100
+ rescue ::RangeError, ::ArgumentError, ::TypeError
101
+ nil
130
102
  end
131
103
  end
132
104
  end
@@ -1,81 +1,80 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require_relative 'base'
4
-
5
3
  module FieldStruct
6
4
  module Types
7
- # Type wrapper for nested FieldStruct fields.
8
- #
9
- # class Address < FieldStruct::Base
10
- # required :street, :string
11
- # required :city, :string
12
- # end
13
- #
14
- # class Person < FieldStruct::Base
15
- # required :address, Address
16
- # end
17
- #
18
- # Built and held per-Field by the DSL when it sees a class argument
19
- # that descends from {FieldStruct::Base}. Each instance is
20
- # parameterized by its target +struct_class+; instances are not
21
- # interchangeable across different nested classes.
5
+ # A field whose value is itself a FieldStruct::Base. Built by the DSL; not registered under a name.
22
6
  class Nested < Base
23
- # @return [Class] the FieldStruct::Base subclass this type wraps
7
+ # Carries an ArgumentError, TypeError or RangeError raised by an inner +new+ out through the
8
+ # setter untouched: errors inside a nested record are structural and bypass the parent's policy (FS-B31).
9
+ class Rejection < FieldStruct::Error
10
+ # @return [Exception] the original error
11
+ attr_reader :original
12
+
13
+ # @param original [Exception]
14
+ def initialize(original)
15
+ super(original.message)
16
+ @original = original
17
+ end
18
+ end
19
+
20
+ # @return [::Class] the nested struct class
24
21
  attr_reader :struct_class
25
22
 
26
- # @param struct_class [Class] a FieldStruct::Base subclass
27
- def initialize(struct_class)
23
+ # @param struct_class [::Class] a +FieldStruct::Base+ subclass
24
+ # @param reads [Boolean] whether a mirror class reads other objects (a union member doesn't, FS-B167)
25
+ def initialize(struct_class, reads: true)
28
26
  super()
29
27
  @struct_class = struct_class
28
+ @reads = reads
30
29
  end
31
30
 
32
- # Coerce input into a {#struct_class} instance.
33
- #
34
- # - +nil+ → +nil+
35
- # - already a {#struct_class} (or subclass) instance → passthrough
36
- # - +Hash+ → +struct_class.new(hash)+
37
- # - anything else → +TypeError+ (which the parent's coercion_policy
38
- # handles like any shape-level coercion failure)
39
- #
40
- # Errors raised inside +struct_class.new+ (e.g.
41
- # {UnknownAttributeError}, {CoercionError}) propagate to the caller
42
- # rather than being caught by the parent's policy — those are
43
- # structural rejections of the nested record's input, not parent-
44
- # shape coercion failures.
45
- #
46
- # @param value [FieldStruct::Base, ::Hash{::Symbol, ::String => Object, nil}, nil] +nil+ → +nil+; an
47
- # instance of {#struct_class} (or subclass) → passthrough; a
48
- # +Hash+ → constructs via +struct_class.new(hash)+. Anything
49
- # else raises TypeError.
50
- # @return [FieldStruct::Base, nil]
51
- # @raise [TypeError] when input is non-nil and neither a
52
- # {#struct_class} instance nor a Hash
31
+ # @param value [::Object] nil, an instance of the struct, a Hash, or for a mirror any source object
32
+ # @return [FieldStruct::Base, nil] the same instance, or a new one built from the Hash or read from the source
33
+ # @raise [TypeError] for anything else
53
34
  def coerce(value, **)
54
- return nil if value.nil?
55
- return value if value.is_a?(@struct_class)
56
- return @struct_class.new(value) if value.is_a?(::Hash)
35
+ return value if value.nil? || value.is_a?(struct_class)
36
+ return build(value) if value.is_a?(::Hash)
37
+ return build(read(value)) if @reads && struct_class.mirror?
57
38
 
58
- raise ::TypeError, "expected #{@struct_class} or Hash, got #{value.class}"
39
+ raise ::TypeError, "expected #{struct_class.display_name} or Hash, got #{value.class}"
59
40
  end
60
41
 
61
- # @param value [Object]
62
- # @return [Boolean] true only when value is nil — an instance with
63
- # all required fields missing is not "missing" here, it is just
64
- # invalid. Invalidity is surfaced by the parent's validate_field.
65
- def missing?(value)
66
- value.nil?
42
+ # Internal: {#coerce} with the options as one Hash, no keyword splat (see Types::Base.positional_coerce?).
43
+ #
44
+ # @param value [::Object]
45
+ # @param _options [::Hash{::Symbol=>::Object}] unused: this type takes no options
46
+ # @return [FieldStruct::Base, nil]
47
+ # @api private
48
+ def coerce_positional(value, _options)
49
+ coerce(value)
67
50
  end
68
51
 
69
- # @return [Class] the +struct_class+ itself, so introspection sees
70
- # the actual nested type rather than a generic FieldStruct::Base
52
+ # @return [::Class] the struct class
71
53
  def ruby_type
72
- @struct_class
54
+ struct_class
55
+ end
56
+
57
+ private
58
+
59
+ # One public reader per declared field, all checked before any is called (FS-B167).
60
+ def read(source)
61
+ names = struct_class.metadata.map(&:name)
62
+ missing = names.reject { |name| source.respond_to?(name) }
63
+ raise Rejection, ::ArgumentError.new(missing_readers(source, missing)) unless missing.empty?
64
+
65
+ names.to_h { |name| [name, source.public_send(name)] }
66
+ end
67
+
68
+ def missing_readers(source, missing)
69
+ label = source.class.name || source.class.inspect
70
+ noun = missing.size == 1 ? 'reader' : 'readers'
71
+ "#{struct_class.display_name} mirrors #{label}, but #{label} has no public #{noun} for #{missing.map(&:inspect).join(', ')}"
73
72
  end
74
73
 
75
- # @return [::String]
76
- def inspect
77
- name = @struct_class.name || 'AnonymousFieldStruct'
78
- "#<#{FieldStruct.inspect_namespace}::Types::Nested struct_class=#{name}>"
74
+ def build(hash)
75
+ struct_class.new(hash)
76
+ rescue ::ArgumentError, ::TypeError, ::RangeError => e
77
+ raise Rejection, e
79
78
  end
80
79
  end
81
80
  end
@@ -2,35 +2,20 @@
2
2
 
3
3
  module FieldStruct
4
4
  module Types
5
- # Generic preset resolution for a single named option on a single
6
- # type. Symbol values are looked up in the supplied presets hash;
7
- # anything else passes through. Unknown preset names raise
8
- # +ArgumentError+ at field-declaration time.
9
- #
10
- # Used by string-shaped types (Email/UUID/URL) for +format:+ and by
11
- # time-shaped types (Date/Time/DateTime) via {TimeFormatResolver}
12
- # (which adds a stricter set of allowed value types).
5
+ # Replaces a preset Symbol in an options Hash by the preset's value.
13
6
  module PresetResolver
14
- # Resolve +options[key]+ when it's a Symbol preset name, leaving other
15
- # values untouched.
16
- #
17
- # @param options [::Hash{::Symbol => Object, nil}] the per-field options
18
- # @param key [::Symbol] the option to resolve (e.g. +:format+)
19
- # @param presets [::Hash{::Symbol => Object}] preset name → concrete value
20
- # @param label [::String] used in the unknown-preset error message
21
- # @return [::Hash{::Symbol => Object, nil}] options with +key+ resolved (a copy when changed)
22
- # @raise [ArgumentError] when +options[key]+ names an unknown preset
7
+ # @param options [::Hash{::Symbol=>::Object}]
8
+ # @param key [::Symbol] the option to resolve
9
+ # @param presets [::Hash{::Symbol=>::Object}] preset name to value
10
+ # @param label [::String] what the preset is for, used in the error message
11
+ # @return [::Hash{::Symbol=>::Object}] a new Hash; non-Symbol values and absent keys pass through
12
+ # @raise [ArgumentError] for an unknown preset name
23
13
  def self.call(options, key, presets, label:)
24
- return options unless options.key?(key)
25
-
26
14
  value = options[key]
27
15
  return options unless value.is_a?(::Symbol)
16
+ raise ::ArgumentError, "unknown #{label} preset #{value.inspect}. Available: #{presets.keys.inspect}" unless presets.key?(value)
28
17
 
29
- resolved = presets.fetch(value) do
30
- raise ArgumentError,
31
- "unknown #{label} preset #{value.inspect}. Available: #{presets.keys.inspect}"
32
- end
33
- options.merge(key => resolved)
18
+ options.merge(key => presets.fetch(value))
34
19
  end
35
20
  end
36
21
  end