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,48 +1,48 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module FieldStruct
4
- # Minimal ActiveModel::Name-shaped value for {Base.model_name}.
5
- #
6
- # We mirror only what Rails-adjacent callers commonly reach for:
7
- # +name+, +singular+, +plural+, +element+, and string coercion.
8
- # No ActiveModel code is reused; pluralization is naive +s+-suffix
9
- # English. If a richer Name is needed, a downstream gem can build on
10
- # this without changing the surface.
4
+ # Naming helpers in the shape Rails-adjacent code expects. Obtained from +Base.model_name+.
11
5
  class ModelName
12
- # @return [String] the fully-qualified class name (or "" for anonymous classes)
6
+ # @return [String] the full class name
13
7
  attr_reader :name
14
-
15
- # @return [String] last segment, snake_case (e.g. "user_account")
8
+ # @return [String] snake_case of the last name segment
9
+ attr_reader :element
10
+ # @return [String] same as {#element}
16
11
  attr_reader :singular
17
-
18
- # @return [String] naive +s+-suffixed plural of {#singular}
12
+ # @return [String] {#element} plus +"s"+ (no inflection)
19
13
  attr_reader :plural
14
+ # @return [String] same as {#singular}: the key Rails' +form_with model:+ nests the fields under
15
+ attr_reader :param_key
20
16
 
21
- # @return [String] same as {#singular} (the AM convention for last segment)
22
- attr_reader :element
23
-
24
- # @param class_name [String, nil]
25
- def initialize(class_name)
26
- @name = class_name.to_s
27
- base = @name.split('::').last.to_s
28
- @element = camel_to_snake(base)
17
+ # @param name [String] the full class name
18
+ def initialize(name)
19
+ @name = name
20
+ @element = snake_case(name.split('::').last)
29
21
  @singular = @element
30
22
  @plural = "#{@element}s"
23
+ @param_key = @singular
24
+ freeze
31
25
  end
32
26
 
33
- # @return [String]
27
+ # @return [String] the full class name
34
28
  def to_s
35
- @name
29
+ name
36
30
  end
37
31
 
38
- alias to_str to_s
32
+ # Same as {#to_s}, so a ModelName converts implicitly to a String.
33
+ #
34
+ # @return [String]
35
+ def to_str
36
+ to_s
37
+ end
39
38
 
40
39
  private
41
40
 
42
- # @param str [String] a bare class name
43
- # @return [String] its snake_case form
44
- def camel_to_snake(str)
45
- str.gsub(/([a-z\d])([A-Z])/, '\\1_\\2').gsub(/([A-Z]+)([A-Z][a-z])/, '\\1_\\2').downcase
41
+ def snake_case(segment)
42
+ segment
43
+ .gsub(/(?<=[a-z\d])(?=[A-Z])/, '_')
44
+ .gsub(/(?<=[A-Z])(?=[A-Z][a-z])/, '_')
45
+ .downcase
46
46
  end
47
47
  end
48
48
  end
@@ -0,0 +1,121 @@
1
+ # frozen_string_literal: true
2
+
3
+ module FieldStruct
4
+ # Declaration-time option checks (steps 3 to 7 of the declaration order): wrong-type keys, required options,
5
+ # shapes, the type's own +resolve_options+ and the +format:+ prefill. Raises ArgumentError at the first failure.
6
+ module OptionChecker
7
+ # @param type_class [Class] the field's type class
8
+ # @param options [Hash{Symbol=>Object}] every non-universal option, as declared
9
+ # @param registry [FieldStruct::Registry] the registry chain the field's type was resolved through
10
+ # @param field_name [Symbol]
11
+ # @param label [String] how errors name the field: +Class#field+, or +field :name+ for an anonymous class
12
+ # @return [Hash{Symbol=>Object}] the options to store: presets resolved, +format:+ prefilled
13
+ def self.call(type_class, options, registry:, field_name:, label: "field #{field_name.inspect}")
14
+ check_keys(type_class, options, registry, label)
15
+ check_required(type_class, options)
16
+ check_shapes(type_class, options)
17
+ check_length(type_class, options[:length])
18
+ check_json(type_class, options[:json])
19
+ resolved = resolve(type_class, options, registry, field_name)
20
+ prefill_format(type_class, resolved)
21
+ end
22
+
23
+ # The checks an array's +element:+ options get: shapes, then the element type's +resolve_options+.
24
+ # (Keys are checked by the caller, which words the errors for elements.)
25
+ #
26
+ # @param type_class [Class] the element type's class
27
+ # @param options [Hash{Symbol=>Object}]
28
+ # @param registry [FieldStruct::Registry]
29
+ # @param field_name [Symbol]
30
+ # @return [Hash{Symbol=>Object}]
31
+ def self.element(type_class, options, registry:, field_name:)
32
+ check_shapes(type_class, options)
33
+ check_length(type_class, options[:length])
34
+ check_json(type_class, options[:json])
35
+ resolve(type_class, options, registry, field_name)
36
+ end
37
+
38
+ # Short class name used in messages ("Float", "ImmutableString").
39
+ #
40
+ # @param klass [Class]
41
+ # @return [String]
42
+ def self.short(klass)
43
+ klass.name ? klass.name.split('::').last : klass.to_s
44
+ end
45
+
46
+ def self.check_keys(type_class, options, registry, label)
47
+ schema = type_class.option_schema
48
+ options.each do |key, value|
49
+ next if schema.key?(key)
50
+
51
+ owners = registry.type_classes.select { |candidate| candidate.option_schema.key?(key) }
52
+ if owners.empty?
53
+ check_registered(type_class, key, value, label)
54
+ next
55
+ end
56
+
57
+ raise ::ArgumentError, "#{key}: option does not apply to #{type_class.short_name} fields. " \
58
+ "It applies to: #{owners.map(&:short_name).join(', ')}."
59
+ end
60
+ end
61
+
62
+ # A key no type declares must be registered (FS-B10), and its value is shape-checked like a native one (FS-B10a).
63
+ def self.check_registered(type_class, key, value, label)
64
+ entry = OptionRegistry.entries[key]
65
+ raise ::ArgumentError, OptionRegistry.unknown_message(key, label, type_class.option_schema.keys) unless entry
66
+
67
+ check_shape(type_class, key, value, entry.type)
68
+ end
69
+
70
+ def self.check_required(type_class, options)
71
+ type_class.option_schema.each do |key, descriptor|
72
+ raise ::ArgumentError, type_class.required_option_message(key) if descriptor[:required] && options[key].nil?
73
+ end
74
+ end
75
+
76
+ def self.check_shapes(type_class, options)
77
+ type_class.option_schema.each { |key, descriptor| check_shape(type_class, key, options[key], descriptor[:type]) }
78
+ end
79
+
80
+ def self.check_shape(type_class, key, value, classes)
81
+ return if value.nil? || classes.any? { |klass| value.is_a?(klass) }
82
+
83
+ expected = classes.map { |klass| short(klass) }.join(' or ')
84
+ raise ::ArgumentError, "#{key}: on #{type_class.short_name} expects #{expected}, got #{value.class} (#{value.inspect})"
85
+ end
86
+
87
+ # +length:+ on the string family takes a Range of whole numbers from 0, open at one end at most (FS-B37a).
88
+ def self.check_length(type_class, bounds)
89
+ return unless bounds.is_a?(::Range) && type_class <= Types::String && !Restrictions.usable_length?(bounds)
90
+
91
+ raise ::ArgumentError, "length: on #{type_class.short_name} takes a Range of whole numbers from 0, " \
92
+ "like 3..40 or ..40, got #{bounds.inspect}"
93
+ end
94
+
95
+ # +json:+ on a decimal is +:number+ or +:string+ (FS-B106a).
96
+ def self.check_json(type_class, mode)
97
+ return unless mode.is_a?(::Symbol) && type_class <= Types::BigDecimal && !%i[number string].include?(mode)
98
+
99
+ raise ::ArgumentError, "json: on #{type_class.short_name} takes :number or :string, got #{mode.inspect}"
100
+ end
101
+
102
+ # Calls the type's hook, passing +registry:+ and +field_name:+ only if it declares them (4.9.1 says
103
+ # +resolve_options(options)+, and a custom type may keep that signature).
104
+ def self.resolve(type_class, options, registry, field_name)
105
+ accepted = type_class.method(:resolve_options).parameters
106
+ extras = { registry: registry, field_name: field_name }.select do |name, _|
107
+ accepted.any? { |kind, param| kind == :keyrest || (kind == :key && param == name) || (kind == :keyreq && param == name) }
108
+ end
109
+ type_class.resolve_options(options, **extras)
110
+ end
111
+
112
+ def self.prefill_format(type_class, options)
113
+ return options unless type_class.respond_to?(:default_format) && !options.key?(:format)
114
+
115
+ options.merge(format: type_class.default_format)
116
+ end
117
+
118
+ private_class_method :check_keys, :check_registered, :check_required, :check_shapes, :check_shape, :check_length,
119
+ :check_json, :resolve, :prefill_format
120
+ end
121
+ end
@@ -0,0 +1,49 @@
1
+ # frozen_string_literal: true
2
+
3
+ module FieldStruct
4
+ # INTERNAL. Builds the class +Klass.partial+ returns (FS-B104b): a sibling of +Klass+ with every field optional.
5
+ module PartialBuilder
6
+ # @param source [Class] the +FieldStruct::Base+ subclass to copy
7
+ # @return [Class] the new class, already named +<source>::Partial+
8
+ # @raise [ArgumentError] when +source+ already has its own +Partial+ constant
9
+ def self.call(source)
10
+ label = source.display_name
11
+ if source.const_defined?(:Partial, false)
12
+ raise ArgumentError, "#{label}::Partial is already defined; #{label}.partial would replace it"
13
+ end
14
+
15
+ copy = Class.new(Base)
16
+ source.metadata.each do |field|
17
+ loose = loosened(field)
18
+ copy.metadata.add(loose)
19
+ copy.send(:define_accessors, loose)
20
+ end
21
+ source.metadata.serializations.each { |format, mapping| copy.metadata.add_serialization(format, mapping) }
22
+ copy_policies(source, copy)
23
+ source.const_set(:Partial, copy)
24
+ end
25
+
26
+ # The same field, optional, not nullable, with no default.
27
+ #
28
+ # @param field [FieldStruct::Field]
29
+ # @return [FieldStruct::Field]
30
+ def self.loosened(field)
31
+ Field.new(name: field.name, type: field.type, type_instance: field.type_instance, required: false, nullable: false,
32
+ default: nil, coercion_policy: field.coercion_policy, description: field.description,
33
+ rbs_type: field.rbs_type, sensitive: field.sensitive?, **field.options)
34
+ end
35
+
36
+ # @param source [Class]
37
+ # @param copy [Class]
38
+ # @return [void]
39
+ def self.copy_policies(source, copy)
40
+ copy.coercion_policy(source.coercion_policy)
41
+ copy.unknown_attributes(source.unknown_attributes)
42
+ copy.json_omit(:unset)
43
+ copy.immutable! if source.immutable?
44
+ copy.frozen! if source.frozen_on_construct?
45
+ end
46
+
47
+ private_class_method :loosened, :copy_policies
48
+ end
49
+ end
@@ -0,0 +1,45 @@
1
+ # frozen_string_literal: true
2
+
3
+ module FieldStruct
4
+ # Which fields the caller gave (FS-B34a), and what that means for a nullable field (FS-B34). Included into {Base}.
5
+ module Presence
6
+ # What +given_fields+ returns before anything was given; shared, so a struct built with no input allocates nothing.
7
+ NOTHING_GIVEN = [].freeze
8
+ private_constant :NOTHING_GIVEN
9
+
10
+ # The fields the caller gave, through the input, +with+ or a writer; defaults don't count (FS-B34a).
11
+ #
12
+ # @return [Array<Symbol>] frozen, in declaration order
13
+ def given_fields
14
+ given = @__given__
15
+ return NOTHING_GIVEN if given.nil?
16
+
17
+ self.class.attribute_names.select { |name| given.include?(name) }.freeze
18
+ end
19
+
20
+ private
21
+
22
+ # The defaults pass runs setters too; the flag keeps it from marking fields as given (FS-B34a).
23
+ def fs_apply_defaults(input)
24
+ @__defaulting__ = true
25
+ fs_default_each(input)
26
+ ensure
27
+ @__defaulting__ = false
28
+ end
29
+
30
+ def fs_mark_given(name)
31
+ given = (@__given__ ||= [])
32
+ given << name unless given.include?(name)
33
+ end
34
+
35
+ def fs_given?(name)
36
+ given = @__given__
37
+ given ? given.include?(name) : false
38
+ end
39
+
40
+ # A given nil on a nullable field is an answer, not a missing value (FS-B34).
41
+ def fs_null_answer?(field, value)
42
+ field.nullable? && value.nil? && fs_given?(field.name)
43
+ end
44
+ end
45
+ end