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
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 02cc3b3e1caf64e1065d794d12fea26ac7ed803b63c885a1f504135260ded56f
|
|
4
|
+
data.tar.gz: 1f81800a6a3e1ed0a23ff1208f11f32fdc6e19f056b327dbd7c595c3dc6bdd2d
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 9547d189893eefca7ea0896f2823331709e94e0f9e4ba370234f08b0ec03a340df879ada14dfe4da6e41cd5aad04bb1c9ea0620bfb7ba095d08a7345d8e87b14
|
|
7
|
+
data.tar.gz: 5df7b25530165495ba2c0c26d730f670c5d8be36e911b0ffc10eb27dc31fb0d41c81dea9eca476c20a6f2140900e82ba838024864d45f777e37bb927e95e09e6
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "field-struct",
|
|
3
|
+
"owner": {
|
|
4
|
+
"name": "Adrian Madrid"
|
|
5
|
+
},
|
|
6
|
+
"plugins": [
|
|
7
|
+
{
|
|
8
|
+
"name": "field-struct",
|
|
9
|
+
"source": "./",
|
|
10
|
+
"description": "Skill for defining, debugging and typing Ruby models built with the field_struct gem."
|
|
11
|
+
}
|
|
12
|
+
]
|
|
13
|
+
}
|
data/AGENTS.md
CHANGED
|
@@ -1,58 +1,51 @@
|
|
|
1
|
-
#
|
|
1
|
+
# AGENTS.md
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
coercion and validation). This file routes AI coding agents to the right docs and the
|
|
5
|
-
things most often gotten wrong. (For *contributing to the gem itself*, see
|
|
6
|
-
`CLAUDE.md`.)
|
|
3
|
+
Guide for coding agents using the `field_struct` gem. Short on purpose; the details live in the files below.
|
|
7
4
|
|
|
8
5
|
## Read these
|
|
9
6
|
|
|
10
|
-
-
|
|
11
|
-
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
- Ask a type what options it accepts (name, value shape, presets): `FieldStruct.types.lookup(:date).option_schema`.
|
|
56
|
-
- Type your models for Steep/Solargraph: `FieldStruct::RBS.generate(Klass)`.
|
|
57
|
-
- "Update" an immutable or frozen instance: `record.with(field: value)` returns a changed copy.
|
|
58
|
-
- Payment/API input: `unknown_attributes :raise` on every struct that reads it, `strict: true` on money and id fields, `sensitive: true` on card data. See [USAGE](USAGE.md#payment-and-api-boundaries-unknown_attributes-raise).
|
|
7
|
+
- [USAGE.md](USAGE.md): the reference. Every type, option and macro, with examples. Read it once before writing a model.
|
|
8
|
+
- [docs/getting_started.md](docs/getting_started.md): task-to-API map, what each error means and how to fix it, common mistakes, Rails.
|
|
9
|
+
- [README.md](README.md): overview and the type and option tables.
|
|
10
|
+
- [skills/field-struct/SKILL.md](skills/field-struct/SKILL.md): the same guidance as a Claude Code skill.
|
|
11
|
+
|
|
12
|
+
## A model in four lines
|
|
13
|
+
|
|
14
|
+
```ruby
|
|
15
|
+
class Plant < FieldStruct::Base
|
|
16
|
+
required :species, :string
|
|
17
|
+
optional :leaves, :integer, in: 1..5000
|
|
18
|
+
end
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Gotchas
|
|
22
|
+
|
|
23
|
+
1. **Setters are permissive.** A bad value is stored as given and recorded in `errors`. Nothing raises unless the class
|
|
24
|
+
says `coercion_policy :raise`. Always check `valid?`.
|
|
25
|
+
2. **`required` doesn't mean non-nil.** It means `valid?` fails when the value is missing. An unset required field reads
|
|
26
|
+
as `nil`.
|
|
27
|
+
3. **Whitespace-only strings, empty arrays and empty hashes are missing** for `required` (not for `:binary` or `:value`).
|
|
28
|
+
4. **`of:` is required** on `:array`, `:hash` and `:union`. A missing one raises at declaration.
|
|
29
|
+
5. **Options are scoped to types.** `round:` is for numbers, `format:` for strings and dates, `enum:` for strings and
|
|
30
|
+
symbols. Options for array elements go in `element: {...}`.
|
|
31
|
+
6. **Cross-field rules go to `errors[:base]`**, from a `validate` method or block.
|
|
32
|
+
7. **JSON goes through Oj.** Use `to_json`, `as_json` and `from_json`; don't use `JSON.generate` on a struct.
|
|
33
|
+
8. **Unknown keys are ignored** by default. Use `unknown_attributes :raise` to fail on them.
|
|
34
|
+
9. **Messages never echo the value**, only its class. `inspect` does show values unless the field is `sensitive: true`.
|
|
35
|
+
10. **Validity goes stale.** It's computed on assignment. Mutating a nested object in place doesn't refresh the parent.
|
|
36
|
+
11. **Copy with `with(**changes)`.** It takes keywords, returns a new object, and is the way to "change" an
|
|
37
|
+
`immutable!` or `frozen!` one.
|
|
38
|
+
|
|
39
|
+
## Working on this gem
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
bundle exec rake # specs and RuboCop (fast)
|
|
43
|
+
bundle exec rake release:check # adds doctests, signature checks, the docs check and the YARD build
|
|
44
|
+
bundle exec rake sigs:generate # after changing any YARD comment: regenerate sig/field_struct.rbs and commit it
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Public methods need short YARD comments with types. Inside `FieldStruct::Types`, write stdlib names with a leading `::`
|
|
48
|
+
(`::String`, `::Hash{::Symbol=>::Object}`). The signature file is generated, never edited by hand.
|
|
49
|
+
A change to `lib/` needs a CHANGELOG entry under `[Unreleased]`. The docs check fails when a public method or a field
|
|
50
|
+
option isn't named in code on USAGE.md and the site reference; a method that is public only for the gem's own use gets
|
|
51
|
+
`# @api private` instead.
|