typemap 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 61fe63803b92dfed0c5185092a5880c13fe0aaa9ac65103340607e903528b984
+  data.tar.gz: 76ba972e18d00eec9dcd8dbd2ff887fcf356f8a2017ebfca2808bbb2202f287f
+SHA512:
+  metadata.gz: d79a8b6ffaa31bda300e49a4d016132db737223a4f1fedbdac6c24f8fea7c7150b577d1ab7ae95bea1cd7b1fdc7527cf0616db49681540fa846e5aa3ac31d565
+  data.tar.gz: bc41895ff023194ab431a442fb17a63b23a07fcbfc5f9535fcc358656ada131dde5316d112109ccfd509b74c01757e18d76944d7b2a71b1c44ac1387660f9390

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+<!-- An entry is one sentence — `Add` / `Fix` / `**Breaking:**`, the symbol, what changed, ≈40
+     words; a breaking entry earns a second sentence for the migration only. -->
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-02
+
+- Add `Typemap::Mapper#load` and `#dump`: a Hash onto a data class or an accessor class and back, strictly typed, then validated — limits, required keys, the class's own `validate` — the first problem raised as a `Typemap::DataError` with the value's path.
+- Add frozen data-class results: after `load`, every Array, Hash and String a data object holds is frozen in place, defaults and the caller's Strings included, so `config.engines << "x"` raises; an accessor class's values stay mutable.
+- Add a suggestion for a misspelled key, `rasie_at_percent: unknown key, did you mean raise_at_percent?`, and limits in words, `must be at least 1, got 0` rather than `0 is not in 1..`.
+- Add a hint at the fix for a classic mistake, worded for `load`'s `source:` — `:toml`'s `write [[server]], not [server]`, `:json`'s `wrap it in [ ]`, `:yaml`, or the default `:ruby`'s `got Integer 70` — and a class named without its namespace, `expected Array[Server]`.
+- Add an array entry's name to an error path: a class method `entry_name(raw)`, given the entry as a Hash with String keys, turns `server[1].url: required` into `server[1] "grok".url: required`; a blank result leaves the bare index.
+- Add required keys: a data class's keyword without a default, or an accessor class's `constrain :name, type: "T?", required: true`; one missing raises `name: required`, nested ones with their full path.
+- Add the `Object` type: plain data — String, Integer, Float, bool, Array, Hash with String keys, `nil` nested inside — passed through on load and checked on dump, so `Hash[String, Object]` holds keys sent somewhere verbatim.
+- Add whole-number loading: an `Integer` property takes `70.0` as `70`, a `Float` property takes `1` as `1.0`; `70.5`, NaN and an Integer a Float would round still raise.
+- Add the `unique: true` and `unique_by:` limits for an Array — `unique_by: :id` names a property of the entries, `unique_by: ->(m) { m.url.downcase }` a function — reported at the second entry, `server[2] "local".id: duplicate of server[0], both "local"`.
+- Add the `not_blank: true` limit for a String, which refuses `""` and `"  "`, and `not_empty: true` for an Array or a Hash; a miss reads `url: must not be blank`, the path down to the key.
+- Add `Typemap::Constrain` — `constrain :name, type: "Integer", in: 1..100, format: /…/` and `ignore :name`, metadata the mapper reads, defining nothing on the class.
+- Add a class's own unknown-key policy, `unknown :ignore` or `unknown :raise`, which wins over `load`'s `unknown:` for that class's keys wherever it appears — a table another program owns stays lenient in an otherwise strict file.
+- Add `Typemap::Mapper::BasicTypes`, the default type strategy (types from `constrain type:`), and `Typemap::Mapper::RBSTypes` (types from `sig/*.rbs`, with the app's `rbs` gem).
+- Add `Typemap::DefinitionError`, like `DataError` a `Typemap::Error`, raised the first time the mapper reads a class it cannot map — no type, a default the type rejects, a limit the type cannot take.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Martin Vysny
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,419 @@
+# Typemap
+
+Typemap maps a Hash onto a Ruby class you already wrote, and back, checking every value on the
+way: `"70"` is never 70, and the data never names a class. Your class stays yours — a
+`Data.define` or a plain class with `attr_accessor`s, typed by `constrain` lines or by your RBS
+signatures. Reading and writing TOML, JSON or YAML, and finding the file, stay with the app;
+Typemap owns the mapping and the checking, and does that one thing well.
+
+Pre-release. Requires Ruby 3.3+; no runtime dependencies.
+
+## A quick look
+
+```ruby
+require "typemap"
+require "tomlrb"
+
+class Ballooning < Data.define(:raise_at_percent, :shrink_at_percent, :pinned_vms)
+  extend Typemap::Constrain
+
+  constrain :raise_at_percent, :shrink_at_percent, type: "Integer", in: 1..100
+  constrain :pinned_vms, type: "Array[String]"
+
+  def initialize(raise_at_percent: 65, shrink_at_percent: 55, pinned_vms: []) = super
+
+  def validate
+    raise "raise_at_percent must be above shrink_at_percent" unless raise_at_percent > shrink_at_percent
+  end
+end
+
+mapper = Typemap::Mapper.new
+ballooning = mapper.load(Ballooning, Tomlrb.load_file("ballooning.toml"), source: :toml)
+```
+
+A file that does not fit raises `Typemap::DataError`, with the path of the offending value and,
+for a classic mistake, the fix in the file's own syntax:
+
+```
+raise_at_percent: expected Integer, got "70"; remove the quotes
+raise_at_percent: must be 1 to 100, got 170
+pinned_vms: expected Array[String], got a single String; wrap it in [ ]
+pinned_vms[1]: expected String, got 7; quote it to make it a string
+rasie_at_percent: unknown key, did you mean raise_at_percent?
+rasie: unknown key; Ballooning has raise_at_percent, shrink_at_percent, pinned_vms
+raise_at_percent must be above shrink_at_percent
+```
+
+> **Always pass `source:` when the Hash came from a file.** The messages above speak TOML because
+> the load says `source: :toml`. Leave it out and the default, `:ruby`, words them for a Hash
+> built in code — `got Integer 7`, `wrap it in an array` — which tells a user editing a file
+> nothing about what to type. See [Naming the source](#naming-the-source).
+
+## Loading and saving
+
+```ruby
+mapper = Typemap::Mapper.new
+
+config = mapper.load(Config, Tomlrb.load_file(path), source: :toml)                # Tomlrb, JSON, YAML.safe_load: any Hash
+state  = mapper.load(State, JSON.load_file(path), source: :json, unknown: :ignore)  # drop keys a newer version wrote
+File.write(path, JSON.pretty_generate(mapper.dump(state)))            # String keys, nested objects as Hashes
+```
+
+- **A key present replaces the default; a key absent keeps it.** A nested Hash loads onto the
+  default's nested object, so a file that sets one nested key keeps the other nested defaults.
+- **An unknown key raises**, unless `unknown: :ignore`; a class may set its own policy
+  ([Unknown keys](#unknown-keys)).
+- **Keys may be Strings or Symbols** (`JSON.load_file(path, symbolize_names: true)` works).
+- **`dump` writes properties in declaration order** and checks every value as `load` would — its
+  type, its limits, a required key, the class's `validate` — so a bug that put a wrong value in
+  an object is caught before it reaches the file.
+- **Every object in the result is validated**, the ones the file left out included: a default
+  nested object must pass its limits and `validate` too.
+- **A data class comes back frozen all the way down.** Every Array, Hash and String it holds is
+  frozen, defaults included, so `config.engines << "x"` raises `FrozenError`; mutate a copy,
+  `config.engines.dup`. An accessor class's values stay mutable, being meant to change.
+  Typemap freezes in place: a String from your Hash that a data object ends up holding is frozen
+  there too, and so is a constant a default names (`engines: DEFAULT_ENGINES`). Your Arrays and
+  Hashes never are; the result holds Typemap's own.
+- **The first problem raises.** Typemap does not collect every error.
+- **A mapper is safe to share between threads**; it works out each class once and remembers it.
+
+### Naming the source
+
+`load`'s `source:` names where the Hash came from — `:toml`, `:json`, `:yaml`, or `:ruby`, the
+default, for a Hash built in code — and a load error words its fix in that syntax. The mistake is
+the same in every source; only the advice changes:
+
+| `source:` | `[server]` where an array belongs | `7` where a String belongs |
+|---|---|---|
+| `:ruby` (default) | `wrap it in an array` | `got Integer 7` |
+| `:toml` | `write [[server]], not [server], or server = [{…}]` | `got 7; quote it to make it a string` |
+| `:json` | `wrap it in [ ]` | `got 7; quote it to make it a string` |
+| `:yaml` | `put "- " before it` | `got 7; quote it to make it a string` |
+
+The default is `:ruby` because Typemap does not know where your Hash came from; when it came
+from a file, say so, or the user who edits that file reads Ruby class names instead of the fix.
+
+## Your class
+
+Two shapes of class map. A bare `new` is the default instance: every key the file leaves out
+keeps its value there.
+
+- **A data class**, `Data.define`: its properties are its members. Give a member a default with
+  `def initialize(a: 1, b: "x") = super`; a member without one is a [required key](#required-keys).
+- **An accessor class**, mutable: its properties are its **public reader + writer pairs** —
+  `attr_accessor`s, or a hand-written `def foo` / `def foo=(value)`, inherited ones included.
+  It is built with a bare `new`, then a setter per property.
+
+```ruby
+class State
+  extend Typemap::Constrain
+
+  attr_accessor :system_pane_visible, :log_pane_visible
+  attr_accessor :on_change                  # a listener, not a setting
+  attr_reader :path                         # a reader alone is not a property
+
+  constrain :system_pane_visible, :log_pane_visible, type: "bool"
+  ignore :on_change
+
+  def initialize
+    @system_pane_visible = true
+    @log_pane_visible = true
+  end
+end
+```
+
+An accessor that is not a setting goes `private`, or stays public under `ignore`. Left public, it
+has no type, and Typemap raises when it first reads the class — it never serializes it quietly.
+
+**Validation across properties** goes in the class's own `validate`, which Typemap calls on
+every object once the whole result is built, nested objects first, on `load` and on `dump`;
+whatever it raises becomes a `Typemap::DataError` carrying the object's path.
+
+### `constrain` at a glance
+
+`extend Typemap::Constrain` gives the class three macros. `constrain` declares a property's type
+and limits, `ignore` leaves a public accessor out of the mapping, and `unknown` says what a load
+does with a key the class has no property for ([Unknown keys](#unknown-keys)). None of them
+defines anything on the class.
+
+| Option | Takes | On | A miss reads |
+|---|---|---|---|
+| `type:` | an RBS type String: `"Integer"`, `"String?"`, `"Array[Server]"` ([Types](#types)) | every property, unless its type comes from [RBS](#types-from-rbs-signatures) | `expected Integer, got "70"` |
+| `in:` | a Range: `1..100`, `(1..)` | a number | `must be 1 to 100, got 170` |
+| `in:` | an Array of allowed values: `%w[short verbose]` | a number or a String | `must be one of "short", "verbose", got "x"` |
+| `format:` | a Regexp | a String | `"ab" does not match /\A[a-z]\z/` |
+| `not_blank:` | `true` | a String | `must not be blank` |
+| `not_empty:` | `true` | an Array or a Hash | `must not be empty` |
+| `unique:` | `true` | an Array | `tags[2]: duplicate of tags[0], both "a"` |
+| `unique_by:` | a property, `:id`, or a function, `->(s) { s.url.downcase }` | an Array | `server[2] "local".id: duplicate of server[0], both "local"` |
+| `required:` | `true` | an accessor class's `T?` defaulting to `nil` ([Required keys](#required-keys)) | `api_key: required` |
+
+```ruby
+constrain :raise_at_percent, :shrink_at_percent, type: "Integer"   # several properties at once
+constrain :raise_at_percent, in: 1..100                             # a later call adds to the first
+ignore :on_change                                                   # a listener, not a setting
+```
+
+- **Calls for one property merge**, and an option given twice for it raises `ArgumentError`, as
+  does a misspelled option the moment the class body runs.
+- **A limit the type cannot take** is a `Typemap::DefinitionError`, raised when the mapper first
+  reads the class: `format:` on an Integer, `unique:` on a Hash, `unique_by: :idd` on a class
+  with no `idd`.
+- **A subclass inherits its superclass's constraints** and may add to them. Where both give the
+  same option, the subclass's wins.
+- **A `nil` passes every limit**, so on a `String?`, `not_blank: true` means "if given, not
+  blank". The exception is a `nil` entry in an array, which `unique:` and `unique_by:` compare
+  like any other value.
+
+### Required keys
+
+A key the file must give, one with no sensible default, such as an API key:
+
+```ruby
+class Llm < Data.define(:api_key, :model)
+  extend Typemap::Constrain
+
+  constrain :api_key, :model, type: "String"
+
+  def initialize(api_key:, model: "gpt-5") = super   # api_key has no default: required
+end
+
+class Secret                                          # an accessor class
+  extend Typemap::Constrain
+
+  attr_accessor :api_key
+
+  constrain :api_key, type: "String?", required: true
+
+  def initialize = @api_key = nil
+end
+```
+
+- **A data class: a keyword without a default.** `api_key` stays a non-nil `String`. A plain
+  `Data.define(:a, :b)` requires every member. `required:` on a data class raises.
+- **An accessor class: `required: true` on a `T?` defaulting to `nil`.** A bare `new` sets every
+  property, so the type admits the `nil` and the app handles it (`config.api_key or raise`). For
+  a non-nil type, use a data class.
+- **A missing key raises with its full path**, `llm.api_key: required`, also when the file leaves
+  out the whole `[llm]` table. An accessor class refuses an explicit JSON `null` too; a data
+  class's `String?` keyword takes it.
+- **`dump` raises** on a required accessor still `nil`, since the file would not load back.
+
+### Unknown keys
+
+A key the class has no property for raises, unless `load` gets `unknown: :ignore`. That is all
+or nothing for one file. A file shared by several programs often needs both: strict everywhere,
+except for a table another program owns, which may gain keys tomorrow that this app doesn't
+read. `unknown` sets the policy on that table's class:
+
+```ruby
+class UiTable < Data.define(:show_thinking)
+  extend Typemap::Constrain
+
+  constrain :show_thinking, type: "bool"
+  unknown :ignore              # the TUI owns [ui]; a key it adds must not stop this app from starting
+
+  def initialize(show_thinking: true) = super
+end
+```
+
+- **The class's policy wins over `load`'s, both ways.** `unknown` takes `load`'s two values,
+  `:ignore` and `:raise`; a class that gives neither follows `load`'s `unknown:`.
+- **It covers the class's own keys, wherever the class appears**: a table, or each entry of an
+  array. A class nested in it keeps its own policy, or `load`'s. A subclass inherits it.
+- **An ignored key is dropped silently.** Typemap does not report which keys it dropped.
+- **`unknown :raise` inside an `unknown: :ignore` load** brings back the failure `:ignore` avoids:
+  a newer version of the app that adds a key to that class's table breaks this one.
+- **A value other than `:raise` or `:ignore`**, or `unknown` given twice in one class, raises
+  `ArgumentError` the moment the class body runs.
+
+### Naming an array entry
+
+An error inside an array names the entry by its index, `server[1].url: required`. A class
+method `entry_name` adds the name the file gave it, so nobody counts `[[server]]` headers:
+
+```ruby
+class Server < Data.define(:id, :url)
+  extend Typemap::Constrain
+
+  constrain :id, :url, type: "String"
+
+  def self.entry_name(raw) = raw["id"]   # or "#{raw["host"]}:#{raw["port"]}", anything
+end
+```
+
+```
+server[1] "grok".url: required
+```
+
+- **`raw` is the entry as a file would hold it**: a Hash with String keys, its values not yet
+  checked. Once the entry is built, for a later check or a `dump`, it is the entry dumped, defaults
+  included.
+- **The name is the result's `to_s`, stripped**: an Integer id names the entry too, and
+  `" grok "` prints as `"grok"`. **No name, just the index**, when that comes out empty — `nil`,
+  `""`, `"  "`. When `entry_name` raises, Typemap warns and raises the original error unnamed.
+
+## Types
+
+Every property needs a declared type: from `constrain type:`, or from your RBS signatures (below).
+The default never supplies one — a default of `65` would otherwise reject `65.5` from the file.
+
+| Type | Takes | Rejects |
+|---|---|---|
+| `Integer` | `70`; `70.0`, loaded as `70` | `"70"`, `70.5` |
+| `Float` | `0.5`; `1`, loaded as `1.0` | `"0.5"` |
+| `String` | `"a"` | `:a` |
+| `bool` | `true`, `false` | `0`, `"yes"` |
+| `T?` | `nil`, or a `T` | |
+| `"short" \| "verbose"` | one of the literals | anything else; `1 \| 2` rejects `1.0` |
+| `Array[T]` | an Array of `T` | |
+| `Hash[String, T]` | a Hash of `T` | |
+| `Ballooning` | a Hash, loaded into your class | |
+| `Object` | plain data, passed through as the file holds it | a `Time`, a `Proc`, a key that is no String |
+
+That is the whole list: any other type raises `Typemap::DefinitionError` when the mapper first
+reads the class. `Object` is for a value whose meaning is someone else's, such as extra keys an
+app sends to a server verbatim (`Hash[String, Object]`). Typemap checks only that it is plain
+data — a String, Integer, Float, bool, Array or Hash, `nil` nested inside — on `load` and on
+`dump`, and turns every Symbol key into a String.
+
+Types are RBS strings, never Ruby classes: `"Integer"` does not take `nil`, `"Integer?"` does. A
+name resolves the way Ruby resolves it in the code beside it — `"Size"` inside `module App` finds
+`App::Size` first; `"::Size"` or `"Other::Size"` says exactly which.
+
+**Limits** narrow a type:
+
+```ruby
+constrain :raise_at_percent, type: "Integer", in: 1..100   # a range, for a number
+constrain :min_gib, type: "Integer", in: (1..)              # an endless range: parenthesize it
+constrain :mode, type: "String", in: %w[short verbose]      # a list of values
+constrain :name, type: "String", format: /\A[a-z]+\z/       # a pattern, for a String
+constrain :url, type: "String", not_blank: true             # not "", not "  "
+constrain :command, type: "Array[String]", not_empty: true  # at least one element; a Hash too
+constrain :tags, type: "Array[String]", unique: true        # no two entries equal
+constrain :server, type: "Array[Server]", unique_by: :id    # no two entries share an id
+constrain :mirror, type: "Array[Mirror]", unique_by: ->(m) { m.url.downcase }
+```
+
+`unique_by:` takes a property of the entries' class, or a function of the entry for anything
+more. A duplicate is reported at the second entry, which is named like any entry error, and
+the detail gives the first entry's index:
+
+```
+server[2] "local".id: duplicate of server[0], both "local"
+```
+
+`unique: true` on entries of your own class compares them with `eql?`. A data class has value
+equality; on a class that only compares by identity, `unique: true` raises. Two `nil`s are
+duplicates, as `nil == nil` is in Ruby.
+
+Parenthesize an endless range at the end of a line: `in: 1..` followed by a newline makes Ruby
+read the next line as the range's end.
+
+A miss reads `must be 1 to 100, got 170`, `must be at least 1, got 0`, `must not be blank`. A
+`format:` miss prints the pattern, which the person editing the file may not read; for a message
+in your own words, raise it from `validate` instead. Every option, in one table:
+[`constrain` at a glance](#constrain-at-a-glance).
+
+## Problems in the class itself
+
+A class Typemap cannot map raises `Typemap::DefinitionError` the first time the mapper reads it —
+before it looks at any file, so a gap never waits for a user to set that key:
+
+```
+Config#name: no type: give it `constrain :name, type: "…"` (…)
+Config#port: its default nil does not fit Integer
+Config#port: format: /x/ limits only a String, not Integer
+Config#ratio: unsupported type: Set[…]
+Config: constrain names prot, not a property
+Config#api_key: required: on String, which can never be missing; required: takes a String? defaulting to nil
+Config: must build with a bare new, its default instance (wrong number of arguments (given 0, expected 1))
+Config#initialize takes [[:keyrest, :opts]]; Typemap reads which keys are required only from `name:` and `name: default` keywords
+```
+
+Both `Typemap::DataError` and `Typemap::DefinitionError` are `Typemap::Error`s.
+
+## Types from RBS signatures
+
+A project that keeps `sig/*.rbs` can take its types from there instead of `constrain type:`:
+
+```ruby
+mapper = Typemap::Mapper.new(types: Typemap::Mapper::RBSTypes.new)
+```
+
+- A property's type is its reader's: `attr_reader` / `attr_accessor name: T`, or
+  `def name: () -> T`, along the class's ancestors.
+- `RBSTypes` finds the `sig/` directory beside the class's own source, walking up from its file;
+  `RBSTypes.new(sig: ["sig/app.rbs"])` names the files instead.
+- `constrain` still gives limits; a `constrain type:` for a property the signatures already type
+  raises, since a type declared twice drifts.
+- It needs the `rbs` gem — add `gem "rbs"` to your Gemfile. Typemap itself never depends on it.
+
+[sord](https://github.com/AaronC81/sord) writes `sig/*.rbs` from YARD tags
+(`sord gen sig/app.rbs --rbs`). A data class is typed with YARD's `@!attribute` directive, in the
+`class X < Data.define(…)` form:
+
+```ruby
+# @!attribute [r] raise_at_percent
+#   @return [Integer] grow the guest above this share of its memory
+class Ballooning < Data.define(:raise_at_percent)
+```
+
+## Example: config and state files on Linux
+
+Typemap does not find files; your app does. The simple Linux case, by the
+[XDG Base Directory spec](https://specifications.freedesktop.org/basedir-spec/latest/) —
+config read from the first file found, state written whole and renamed into place:
+
+```ruby
+require "json"
+require "fileutils"
+require "tomlrb"
+require "typemap"
+
+module Paths
+  # An XDG variable, or its default when unset, empty or relative (the spec calls that invalid).
+  def self.xdg(var, default) = ENV[var].to_s.start_with?("/") ? ENV[var] : File.join(Dir.home, default)
+
+  def self.config_file(app)
+    dirs = [xdg("XDG_CONFIG_HOME", ".config"), *ENV.fetch("XDG_CONFIG_DIRS", "/etc/xdg").split(":"), "/etc"]
+    dirs.map { |dir| File.join(dir, app, "config.toml") }.find { |file| File.exist?(file) }
+  end
+
+  def self.state_file(app) = File.join(xdg("XDG_STATE_HOME", ".local/state"), app, "state.json")
+end
+
+MAPPER = Typemap::Mapper.new
+
+def load_config
+  file = Paths.config_file("myapp")
+  MAPPER.load(Config, file ? Tomlrb.load_file(file) : {}, source: :toml)   # no file: the defaults, or `api_key: required`
+rescue Typemap::DataError => e
+  abort "#{file || "config.toml"}: #{e.message}"   # ~/.config/myapp/config.toml: port: expected Integer, got "80"; remove the quotes
+end
+
+def load_state
+  file = Paths.state_file("myapp")
+  File.exist?(file) ? MAPPER.load(State, JSON.load_file(file), source: :json, unknown: :ignore) : State.new
+end
+
+def save_state(state)
+  file = Paths.state_file("myapp")
+  FileUtils.mkdir_p(File.dirname(file))
+  File.write("#{file}.tmp", JSON.pretty_generate(MAPPER.dump(state)))
+  File.rename("#{file}.tmp", file)   # a crash mid-write never leaves a truncated file
+end
+```
+
+That is as far as Typemap goes. Merging several config files, `config.d/` fragments, env-var
+overrides, macOS and Windows locations are the app's call, or another gem's.
+
+## Design
+
+Why Typemap is shaped this way — and why not dry-struct, ActiveModel or `T::Struct` — is in
+[design/decisions.md](design/decisions.md).
+
+## License
+
+MIT; see [LICENSE.txt](LICENSE.txt).

data/lib/typemap/constrain.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module Typemap
+  # The class-side annotations the mapper reads: `extend Typemap::Constrain`, then
+  #
+  #     constrain :raise_at_percent, :shrink_at_percent, type: "Integer", in: 1..100
+  #     constrain :pinned_vms, type: "Array[String]"
+  #     constrain :api_key, type: "String?", required: true   # an accessor class's nil default
+  #     constrain :url, type: "String", not_blank: true        # not "" and not "  "
+  #     constrain :servers, type: "Array[Server]", unique_by: :id
+  #     ignore :on_change
+  #     unknown :ignore                                         # keys this app does not read
+  #
+  # Each call records metadata and defines nothing — no accessor, no default, no `initialize`;
+  # the class stays as written (`D_constrain_macro`). An unknown option is Ruby's own
+  # `ArgumentError` the moment the class body runs.
+  module Constrain
+    # What `constrain` recorded for one property.
+    #
+    # @!attribute [r] type
+    #   @return [String, nil] the RBS type string, `nil` when the type comes from elsewhere
+    # @!attribute [r] type_owner
+    #   @return [Module, nil] the class that gave `type:`; its namespace resolves the names in it
+    # @!attribute [r] in
+    #   @return [Range, Array, nil] the allowed range, or the allowed values
+    # @!attribute [r] format
+    #   @return [Regexp, nil] the pattern a String must match
+    # @!attribute [r] not_blank
+    #   @return [true, nil] a String must hold more than whitespace
+    # @!attribute [r] not_empty
+    #   @return [true, nil] an Array or a Hash must hold at least one element
+    # @!attribute [r] unique
+    #   @return [true, nil] no two entries of an Array may be equal
+    # @!attribute [r] unique_by
+    #   @return [Symbol, Proc, nil] what of an Array's entry no two entries may share
+    # @!attribute [r] required
+    #   @return [Boolean, nil] whether a loaded or dumped object must hold a non-nil value
+    Constraint = Data.define(:type, :type_owner, :in, :format, :not_blank, :not_empty, :unique, :unique_by,
+                             :required)
+
+    # Records a type and limits for one or more properties; several calls for one property merge,
+    # but one option given twice raises.
+    #
+    # @param names [Array<Symbol>] the properties
+    # @param type [String, nil] an RBS type string, `"Integer"`, `"String?"`, `"Array[String]"`;
+    #   never a Ruby class, so nil-ability is always spelled out (`D_types_declared`)
+    # @param in [Range, Array, nil] the allowed range of a number, or the allowed values
+    # @param format [Regexp, nil] the pattern a String must match
+    # @param not_blank [true, nil] `true`: a String must hold more than whitespace (`strip.empty?`
+    #   fails it). Bean Validation's `@NotBlank`, except that a `String?`'s `nil` passes.
+    # @param not_empty [true, nil] `true`: an Array or a Hash must hold an element; a String
+    #   takes `not_blank:` instead
+    # @param unique [true, nil] `true`: no two entries of an Array may be equal (`eql?`), `nil`s
+    #   included; entries of a class need value equality, as a data class has
+    # @param unique_by [Symbol, Proc, nil] what no two entries of an Array may share: a property
+    #   of the entries' class, `:id`, or a function of the entry, `->(s) { s.url.downcase }`
+    # @param required [Boolean, nil] `true`: the file must give this key, on an accessor class
+    #   whose property is a `T?` defaulting to `nil` — a loaded or dumped object still holding
+    #   `nil` raises. A data class says it by a keyword without a default instead.
+    # @return [void]
+    # @raise [ArgumentError] on no names, nothing to record, a wrongly typed option, `unique:` and
+    #   `unique_by:` together, or an option already given for that property
+    def constrain(*names, type: nil, in: nil, format: nil, not_blank: nil, not_empty: nil, unique: nil,
+                  unique_by: nil, required: nil)
+      given = { type: type, in: binding.local_variable_get(:in), format: format, not_blank: not_blank,
+                not_empty: not_empty, unique: unique, unique_by: unique_by, required: required }.compact
+      check_constrain_args(names, given)
+      given[:type_owner] = self if type
+      names.each do |name|
+        entry = typemap_constraints[name] ||= {}
+        given.each do |key, value|
+          raise ArgumentError, "constrain :#{name}: #{key}: given twice" if entry.key?(key)
+
+          entry[key] = value
+        end
+      end
+    end
+
+    # Leaves public accessors out of the mapping — a listener the app sets from outside, say. A
+    # private or protected accessor is left out already.
+    #
+    # @param names [Array<Symbol>] the accessors to skip
+    # @return [void]
+    # @raise [ArgumentError] on no names, or a name that is not a Symbol
+    def ignore(*names)
+      raise ArgumentError, "ignore: name at least one property" if names.empty?
+
+      names.each do |name|
+        raise ArgumentError, "ignore: #{name.inspect} is not a Symbol" unless name.is_a?(Symbol)
+      end
+      typemap_ignored.concat(names - typemap_ignored)
+    end
+
+    # Sets what a load does with a key of this class that names no property, overriding `load`'s
+    # `unknown:` both ways:
+    #
+    #     unknown :ignore   # a table another program owns, which may grow keys this app doesn't read
+    #
+    # Only this class's own keys: a class nested in it keeps its own policy, or `load`'s. A
+    # subclass inherits it.
+    #
+    # @param policy [Symbol] `:raise` or `:ignore`, the values `load`'s `unknown:` takes
+    # @return [void]
+    # @raise [ArgumentError] on another value, or a second call in one class
+    def unknown(policy)
+      unless %i[raise ignore].include?(policy)
+        raise ArgumentError, "unknown: must be :raise or :ignore, got #{policy.inspect}"
+      end
+      raise ArgumentError, "unknown: given twice" if typemap_unknown
+
+      @typemap_unknown = policy
+    end
+
+    # @api private
+    # @return [Hash{Symbol => Hash}] what `constrain` recorded on this class itself
+    def typemap_constraints
+      @typemap_constraints ||= {}
+    end
+
+    # @api private
+    # @return [Array<Symbol>] what `ignore` recorded on this class itself
+    def typemap_ignored
+      @typemap_ignored ||= []
+    end
+
+    # @api private
+    # @return [Symbol, nil] what `unknown` recorded on this class itself
+    def typemap_unknown = @typemap_unknown
+
+    # The constraints of `klass` and its ancestors, a subclass's option winning over its
+    # superclass's.
+    #
+    # @param klass [Class]
+    # @return [Hash{Symbol => Constraint}]
+    def self.constraints_for(klass)
+      merged = {}
+      klass.ancestors.reverse_each do |mod|
+        next unless mod.singleton_class.include?(Constrain)
+
+        mod.typemap_constraints.each { |name, options| (merged[name] ||= {}).merge!(options) }
+      end
+      merged.transform_values do |options|
+        Constraint.new(type: options[:type], type_owner: options[:type_owner], in: options[:in],
+                       format: options[:format], not_blank: options[:not_blank],
+                       not_empty: options[:not_empty], unique: options[:unique],
+                       unique_by: options[:unique_by], required: options[:required])
+      end
+    end
+
+    # @param klass [Class]
+    # @return [Array<Symbol>] the names `klass` and its ancestors `ignore`
+    def self.ignored_for(klass)
+      klass.ancestors.select { |mod| mod.singleton_class.include?(Constrain) }.flat_map(&:typemap_ignored).uniq
+    end
+
+    # @param klass [Class]
+    # @return [Symbol, nil] the `unknown` policy of `klass` or its nearest ancestor that gives one;
+    #   `nil` when none does, leaving it to `load`'s `unknown:`
+    def self.unknown_for(klass)
+      klass.ancestors.each do |mod|
+        return mod.typemap_unknown if mod.singleton_class.include?(Constrain) && mod.typemap_unknown
+      end
+      nil
+    end
+
+    private
+
+    def check_constrain_args(names, given)
+      raise ArgumentError, "constrain: name at least one property" if names.empty?
+
+      names.each do |name|
+        raise ArgumentError, "constrain: #{name.inspect} is not a Symbol" unless name.is_a?(Symbol)
+      end
+      if given.empty?
+        raise ArgumentError,
+              "constrain #{names.inspect}: give type:, in:, format:, not_blank:, not_empty:, unique:, " \
+              "unique_by: or required:"
+      end
+      given.each { |key, value| check_constrain_option(key, value) }
+      return unless given.key?(:unique) && given.key?(:unique_by)
+
+      raise ArgumentError, "constrain: unique: and unique_by: together; unique_by: alone says what to compare"
+    end
+
+    def check_constrain_option(key, value)
+      expected = case key
+                 when :type then "an RBS type String" unless value.is_a?(String)
+                 when :in then "a Range or an Array" unless value.is_a?(Range) || value.is_a?(Array)
+                 when :format then "a Regexp" unless value.is_a?(Regexp)
+                 when :unique_by then "a Symbol or a Proc" unless value.is_a?(Symbol) || value.is_a?(Proc)
+                 when :required then "true or false" unless [true, false].include?(value)
+                 # A switch: `false` would mean what leaving it out does — for the negated names, a
+                 # double negative.
+                 else "true, or left out" unless value == true
+                 end
+      raise ArgumentError, "constrain: #{key}: must be #{expected}, got #{value.inspect}" if expected
+    end
+  end
+end