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.
- checksums.yaml +4 -4
- data/.claude-plugin/marketplace.json +13 -0
- data/.claude-plugin/plugin.json +9 -0
- data/AGENTS.md +47 -54
- data/CHANGELOG.md +53 -640
- data/LICENSE.txt +21 -0
- data/README.md +33 -628
- data/USAGE.md +771 -715
- data/docs/getting_started.md +139 -325
- data/lib/field_struct/base.rb +241 -1149
- data/lib/field_struct/class_macros.rb +163 -0
- data/lib/field_struct/describer.rb +167 -0
- data/lib/field_struct/errors.rb +182 -62
- data/lib/field_struct/exceptions.rb +40 -0
- data/lib/field_struct/field.rb +69 -135
- data/lib/field_struct/field_builder.rb +110 -0
- data/lib/field_struct/field_checks.rb +50 -0
- data/lib/field_struct/introspection.rb +199 -0
- data/lib/field_struct/json_codec.rb +240 -0
- data/lib/field_struct/metadata.rb +65 -260
- data/lib/field_struct/model_name.rb +27 -27
- data/lib/field_struct/option_checker.rb +121 -0
- data/lib/field_struct/partial.rb +49 -0
- data/lib/field_struct/presence.rb +45 -0
- data/lib/field_struct/rbs.rb +151 -271
- data/lib/field_struct/registered_option.rb +113 -0
- data/lib/field_struct/registry.rb +40 -50
- data/lib/field_struct/restrictions.rb +90 -0
- data/lib/field_struct/scaffold.rb +274 -301
- data/lib/field_struct/suggestion.rb +33 -0
- data/lib/field_struct/types/array.rb +147 -126
- data/lib/field_struct/types/base.rb +113 -124
- data/lib/field_struct/types/big_decimal.rb +59 -55
- data/lib/field_struct/types/binary.rb +18 -25
- data/lib/field_struct/types/boolean.rb +74 -97
- data/lib/field_struct/types/builtin.rb +32 -0
- data/lib/field_struct/types/date.rb +23 -137
- data/lib/field_struct/types/datetime.rb +30 -139
- data/lib/field_struct/types/element_options.rb +51 -0
- data/lib/field_struct/types/email.rb +27 -38
- data/lib/field_struct/types/float.rb +58 -56
- data/lib/field_struct/types/format_presets.rb +30 -0
- data/lib/field_struct/types/hash.rb +144 -0
- data/lib/field_struct/types/immutable_string.rb +16 -9
- data/lib/field_struct/types/integer.rb +74 -102
- data/lib/field_struct/types/nested.rb +57 -58
- data/lib/field_struct/types/preset_resolver.rb +9 -24
- data/lib/field_struct/types/rfc3339_format.rb +70 -153
- data/lib/field_struct/types/string.rb +48 -46
- data/lib/field_struct/types/symbol.rb +23 -20
- data/lib/field_struct/types/temporal.rb +232 -0
- data/lib/field_struct/types/time.rb +32 -145
- data/lib/field_struct/types/union.rb +111 -65
- data/lib/field_struct/types/union_pick.rb +139 -0
- data/lib/field_struct/types/url.rb +24 -35
- data/lib/field_struct/types/uuid.rb +24 -35
- data/lib/field_struct/types/value.rb +14 -9
- data/lib/field_struct/types/zone.rb +118 -0
- data/lib/field_struct/version.rb +3 -3
- data/lib/field_struct.rb +102 -122
- data/sig/field_struct.rbs +1180 -2300
- data/sig/manifest.yaml +6 -0
- data/skills/field-struct/SKILL.md +73 -159
- metadata +37 -28
- data/CODE_OF_CONDUCT.md +0 -132
- data/UPGRADING.md +0 -743
- data/lib/field_struct/error.rb +0 -48
- data/lib/field_struct/types/temporal_parser.rb +0 -93
- data/lib/field_struct/types/time_format_resolver.rb +0 -54
- 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
|
-
#
|
|
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
|
|
6
|
+
# @return [String] the full class name
|
|
13
7
|
attr_reader :name
|
|
14
|
-
|
|
15
|
-
|
|
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
|
-
# @
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
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
|
-
|
|
29
|
+
name
|
|
36
30
|
end
|
|
37
31
|
|
|
38
|
-
|
|
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
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
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
|