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
data/lib/field_struct.rb CHANGED
@@ -1,159 +1,139 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'oj'
3
+ require 'date'
4
+ require 'time'
4
5
  require 'pathname'
6
+ require 'pp'
7
+ require 'bigdecimal'
8
+ require 'oj'
9
+
5
10
  require_relative 'field_struct/version'
6
- require_relative 'field_struct/error'
7
- require_relative 'field_struct/model_name'
11
+ require_relative 'field_struct/exceptions'
12
+ require_relative 'field_struct/errors'
13
+ require_relative 'field_struct/suggestion'
14
+ require_relative 'field_struct/registry'
8
15
  require_relative 'field_struct/types/base'
9
16
  require_relative 'field_struct/types/preset_resolver'
10
- require_relative 'field_struct/types/temporal_parser'
11
- require_relative 'field_struct/types/rfc3339_format'
12
- require_relative 'field_struct/types/time_format_resolver'
13
- require_relative 'field_struct/types/zone_option'
14
17
  require_relative 'field_struct/types/string'
15
18
  require_relative 'field_struct/types/immutable_string'
16
19
  require_relative 'field_struct/types/integer'
17
20
  require_relative 'field_struct/types/float'
18
21
  require_relative 'field_struct/types/big_decimal'
19
22
  require_relative 'field_struct/types/boolean'
23
+ require_relative 'field_struct/types/rfc3339_format'
24
+ require_relative 'field_struct/types/zone'
25
+ require_relative 'field_struct/types/temporal'
20
26
  require_relative 'field_struct/types/date'
21
27
  require_relative 'field_struct/types/time'
22
28
  require_relative 'field_struct/types/datetime'
23
- require_relative 'field_struct/types/value'
24
- require_relative 'field_struct/types/array'
25
- require_relative 'field_struct/types/nested'
26
29
  require_relative 'field_struct/types/symbol'
30
+ require_relative 'field_struct/types/format_presets'
27
31
  require_relative 'field_struct/types/uuid'
28
32
  require_relative 'field_struct/types/url'
29
33
  require_relative 'field_struct/types/email'
30
- require_relative 'field_struct/types/union'
31
34
  require_relative 'field_struct/types/binary'
32
- require_relative 'field_struct/registry'
35
+ require_relative 'field_struct/types/value'
36
+ require_relative 'field_struct/types/nested'
37
+ require_relative 'field_struct/types/element_options'
38
+ require_relative 'field_struct/types/array'
39
+ require_relative 'field_struct/types/hash'
40
+ require_relative 'field_struct/types/union_pick'
41
+ require_relative 'field_struct/types/union'
42
+ require_relative 'field_struct/types/builtin'
43
+ require_relative 'field_struct/restrictions'
44
+ require_relative 'field_struct/describer'
33
45
  require_relative 'field_struct/field'
46
+ require_relative 'field_struct/option_checker'
34
47
  require_relative 'field_struct/metadata'
35
- require_relative 'field_struct/errors'
48
+ require_relative 'field_struct/model_name'
49
+ require_relative 'field_struct/field_builder'
50
+ require_relative 'field_struct/registered_option'
51
+ require_relative 'field_struct/class_macros'
52
+ require_relative 'field_struct/partial'
53
+ require_relative 'field_struct/json_codec'
54
+ require_relative 'field_struct/presence'
55
+ require_relative 'field_struct/field_checks'
36
56
  require_relative 'field_struct/base'
37
- require_relative 'field_struct/rbs'
38
57
  require_relative 'field_struct/scaffold'
58
+ require_relative 'field_struct/introspection'
59
+ require_relative 'field_struct/rbs'
39
60
 
40
- # Typed PORO foundation: declare fields with enforced types, presence checks,
41
- # and per-field validation. Subclass {FieldStruct::Base} to get a value object
42
- # whose attributes coerce, validate on assignment, and introspect cleanly.
61
+ # Typed plain Ruby objects with declared, coerced, validated fields.
43
62
  module FieldStruct
44
- # What {Base#inspect} renders in place of a +sensitive: true+ field's
45
- # value (the placeholder ActiveSupport's parameter filter uses).
46
- #
47
- # @return [String]
63
+ # Placeholder printed by +inspect+ in place of sensitive values.
64
+ # @return [::String]
48
65
  FILTERED = '[FILTERED]'
49
66
 
50
- # The library's root directory — the parent of +lib/+. Computed from this
51
- # file's location, so it resolves to the repo root in development and to the
52
- # installed gem directory when packaged.
53
- #
54
- # FieldStruct.root.join('lib', 'field_struct.rb') # => #<Pathname …>
55
- #
56
- # @return [Pathname] absolute path to the gem root
57
- def self.root
58
- @root ||= Pathname.new(File.expand_path('..', __dir__))
59
- end
67
+ class << self
68
+ # The directory that contains +lib/+.
69
+ #
70
+ # @return [Pathname]
71
+ def root
72
+ @root ||= Pathname.new(__dir__).parent
73
+ end
60
74
 
61
- # Build a new {Registry}, parented to +parent+ (defaults to
62
- # {FieldStruct.types}), and optionally configure it with a block
63
- # evaluated in the new registry's instance scope.
64
- #
65
- # module Acme
66
- # def self.field_types
67
- # @field_types ||= FieldStruct.new_registry do
68
- # register :money, Acme::Types::Money
69
- # end
70
- # end
71
- # end
72
- #
73
- # Equivalent to the longhand:
74
- #
75
- # FieldStruct::Registry.new(FieldStruct.types).tap do |r|
76
- # r.register :money, Acme::Types::Money
77
- # end
78
- #
79
- # Pass +parent: nil+ for an unparented registry (no fallback chain).
80
- #
81
- # @param parent [Registry, nil] the parent registry; defaults to
82
- # {FieldStruct.types}. Pass +nil+ explicitly for no parent.
83
- # @yield evaluated in the new registry's instance scope, so methods
84
- # like +register+ / +lookup+ / +key?+ work without an explicit receiver
85
- # @return [Registry]
86
- def self.new_registry(parent = types, &block)
87
- registry = Registry.new(parent)
88
- registry.instance_eval(&block) if block
89
- registry
90
- end
75
+ # The memoized base registry, seeded with every built-in type.
76
+ #
77
+ # @return [FieldStruct::Registry]
78
+ def types
79
+ @types ||= Types.install(Registry.new)
80
+ end
91
81
 
92
- # The base type registry, seeded with every v1 scalar type and the
93
- # +:decimal+ alias for +:big_decimal+. Namespace registries should be
94
- # built with this as their parent (see {Registry}).
95
- #
96
- # @return [Registry]
97
- def self.types
98
- @types ||= Registry.new.tap do |r|
99
- r.register :string, Types::String
100
- r.register :immutable_string, Types::ImmutableString
101
- r.register :integer, Types::Integer
102
- r.register :float, Types::Float
103
- r.register :big_decimal, Types::BigDecimal
104
- r.register :decimal, :big_decimal
105
- r.register :boolean, Types::Boolean
106
- r.register :date, Types::Date
107
- r.register :time, Types::Time
108
- r.register :datetime, Types::DateTime
109
- r.register :value, Types::Value
110
- r.register :array, Types::Array
111
- r.register :symbol, Types::Symbol
112
- r.register :uuid, Types::UUID
113
- r.register :url, Types::URL
114
- r.register :email, Types::Email
115
- r.register :union, Types::Union
116
- r.register :binary, Types::Binary
82
+ # Builds a registry, evaluating the block with the new registry as +self+.
83
+ #
84
+ # @param parent [FieldStruct::Registry, nil] where unknown names fall through to
85
+ # @yield evaluated with the registry as +self+
86
+ # @return [FieldStruct::Registry]
87
+ def new_registry(parent = types, &block)
88
+ registry = Registry.new(parent)
89
+ registry.instance_eval(&block) if block
90
+ registry
117
91
  end
118
- end
119
92
 
120
- # Opt-in short alias for the +FieldStruct+ module.
121
- #
122
- # Defines a top-level constant (default: +FS+) that points back to
123
- # +FieldStruct+, *and* swaps the prefix used by every +#inspect+
124
- # method in the library so IRB output reads with the short name too:
125
- #
126
- # FieldStruct.use_alias!
127
- # FS::Base # => FieldStruct::Base
128
- # User.metadata.inspect # => "#<FS::Metadata fields=[...]>"
129
- #
130
- # Off by default — the user has to ask for it. Idempotent. If the
131
- # chosen constant is already defined to something other than
132
- # FieldStruct, raises +NameError+ rather than clobbering.
133
- #
134
- # @param name [Symbol] the top-level constant to define (default +:FS+)
135
- # @return [self] for chaining
136
- # @raise [NameError] when the constant already points at something else
137
- def self.use_alias!(name = :FS)
138
- sym = name.to_sym
139
- if Object.const_defined?(sym, false)
140
- existing = Object.const_get(sym)
141
- unless existing.equal?(self)
142
- raise ::NameError, "::#{sym} is already defined (#{existing.inspect}); not aliasing FieldStruct"
93
+ # Defines a top-level constant for FieldStruct and switches every +inspect+ prefix to it.
94
+ #
95
+ # @param name [Symbol, String] the constant name
96
+ # @return [Module] FieldStruct
97
+ # @raise [NameError] when the constant already names something else
98
+ def use_alias!(name = :FS)
99
+ name = name.to_sym
100
+ if Object.const_defined?(name, false)
101
+ existing = Object.const_get(name, false)
102
+ raise NameError, "::#{name} is already defined (#{existing.inspect}); not aliasing FieldStruct" unless existing.equal?(self)
103
+ else
104
+ Object.const_set(name, self)
143
105
  end
144
- else
145
- Object.const_set(sym, self)
106
+ @inspect_namespace = name.to_s
107
+ self
108
+ end
109
+
110
+ # Makes +name+ a known field option, so declaring it on a field doesn't raise (FS-B10a). Adapters call this
111
+ # for the keys they read; an app can too. Registering the same name, type and owner again does nothing.
112
+ #
113
+ # @example
114
+ # FieldStruct.register_option(:catalog, type: Hash, owner: 'my_app')
115
+ #
116
+ # @param name [Symbol] the option key
117
+ # @param type [Class, Array<Class>] what a declared value must be an instance of (+nil+ is always allowed)
118
+ # @param owner [String] the gem or app that reads the option, named in error messages
119
+ # @return [Symbol] +name+
120
+ # @raise [ArgumentError] for a universal or built-in native key, or a name already registered differently
121
+ def register_option(name, type:, owner:)
122
+ OptionRegistry.register(name, type, owner)
123
+ end
124
+
125
+ # Every registered field option, by name, in registration order.
126
+ #
127
+ # @return [Hash{Symbol=>FieldStruct::RegisteredOption}] frozen
128
+ def registered_options
129
+ OptionRegistry.entries
146
130
  end
147
- @short_alias = sym.to_s
148
- self
149
- end
150
131
 
151
- # The current prefix that library +#inspect+ methods should render.
152
- # Defaults to +"FieldStruct"+; flipped to the alias string (e.g.
153
- # +"FS"+) by {.use_alias!}.
154
- #
155
- # @return [String]
156
- def self.inspect_namespace
157
- @short_alias || 'FieldStruct'
132
+ # The prefix library +inspect+ output uses.
133
+ #
134
+ # @return [String] +'FieldStruct'+ or the alias name
135
+ def inspect_namespace
136
+ @inspect_namespace || 'FieldStruct'
137
+ end
158
138
  end
159
139
  end