Build your own adapter
Let’s write a small adapter that turns a struct into a TypeScript interface, in about 60 lines. The same steps work for any target, like a docs table, a GraphQL type or a SQL definition, and the first-party adapters follow them too.
1. Look at what the walk gives you
Section titled “1. Look at what the walk gives you”FieldStruct::Introspection.properties lists a struct’s fields in order. Every property carries the external key, the field itself, and a node that says what kind of type it has. Here is a struct with one of each kind.
class Waypoint < FieldStruct::Base optional :label, :stringend
class Trek < FieldStruct::Base required :name, :string required :days, :integer, in: 1..30 optional :waypoints, :array, of: Waypoint optional :tags, :array, of: :string optional :permit, :union, of: %i[integer string] optional :starts, :date optional :fees, :hash, of: :big_decimal serialize :json, days: 'dayCount'end
properties = FieldStruct::Introspection.properties(Trek)properties.map(&:key) # => ["name", "dayCount", "waypoints", "tags", "permit", "starts", "fees"]properties.map { |p| p.node.class.name.split('::').last }# => ["ScalarNode", "ScalarNode", "ArrayNode", "ArrayNode", "UnionNode", "ScalarNode", "MapNode"]properties[1].node.options # => {in: 1..30}properties[2].node.element.klass # => Waypointproperties[4].node.members.map { |m| m.type.class }.map { |c| c.name.split('::').last } # => ["Integer", "String"]properties[6].node.element.type.class # => FieldStruct::Types::BigDecimalNodes come in five kinds: scalar, array, map, union and struct. A struct node is a reference to the class and is never expanded, so nesting and recursion are yours to handle. The walk reports declarations and nothing else, which leaves what required means, what a missing value is and how types map up to your adapter. Every member is in the introspection reference.
2. Write the adapter
Section titled “2. Write the adapter”The adapter is a single module function. It dispatches on the node class with case, since the node classes have no common base, and it matches scalar types by the node’s type class.
module TypeScript Types = FieldStruct::Types SCALARS = { Types::Integer => 'number', Types::Float => 'number', Types::Boolean => 'boolean', Types::BigDecimal => 'number', Types::Value => 'unknown' }.freeze
# Returns the interface source for +klass+ and every struct it refers to. def self.generate(klass, serialization: :json) out = {} declare(klass, serialization, out) out.values.join("\n") end
def self.declare(klass, serialization, out) name = klass.name.split('::').last return if out.key?(name)
out[name] = nil # reserve the name first, so a recursive struct stops here lines = FieldStruct::Introspection.properties(klass, serialization: serialization).map do |prop| type = prop.field.options[:ts] || type_for(prop.node, serialization, out) optional = prop.field.required? ? '' : '?' " #{prop.key}#{optional}: #{type}#{' | null' unless prop.field.required?};" end out.delete(name) # re-insert at the end, so nested interfaces come first out[name] = "interface #{name} {\n#{lines.join("\n")}\n}\n" end
def self.type_for(node, serialization, out) case node when FieldStruct::Introspection::StructNode declare(node.klass, serialization, out) node.klass.name.split('::').last when FieldStruct::Introspection::ArrayNode "#{node.element ? type_for(node.element, serialization, out) : 'unknown'}[]" when FieldStruct::Introspection::MapNode "Record<string, #{type_for(node.element, serialization, out)}>" when FieldStruct::Introspection::UnionNode node.members.map { |member| type_for(member, serialization, out) }.uniq.join(' | ') else scalar(node) end end
def self.scalar(node) return SCALARS.fetch(node.type.class) if SCALARS.key?(node.type.class)
enum = node.options[:enum] enum ? enum.map { |value| "'#{value}'" }.join(' | ') : 'string' endendA field turns into one line. An optional field gets ? and | null, because to_json writes null for a missing value. A struct node declares its nested interface first and then refers to it by name, and a map becomes a Record with String keys. Decimals are number, because to_json writes them as JSON numbers. Dates, times, UUIDs and the rest of the string family fall through to string, which is what to_json writes for them.
3. Run it
Section titled “3. Run it”TypeScript.generate(Trek) # => "interface Waypoint {\n label?: string | null;\n}\n\ninterface Trek {\n name: string;\n dayCount: number;\n waypoints?: Waypoint[] | null;\n tags?: string[] | null;\n permit?: number | string | null;\n starts?: string | null;\n fees?: Record<string, number> | null;\n}\n"The key dayCount comes from the serialize :json mapping. Pass serialization: to get another format’s names.
4. Let fields override the mapping
Section titled “4. Let fields override the mapping”The generator looks at prop.field.options[:ts] before anything else. Register the key once with FieldStruct.register_option, and a field can state what it wants: field_struct stores the value untouched and needs no other change. Without the registration, ts: would raise as an unknown option.
FieldStruct.register_option(:ts, type: String, owner: 'type_script')
class Hut < FieldStruct::Base required :code, :string optional :season, :symbol, enum: %i[summer winter year_round] optional :places, :integer, ts: 'bigint'end
TypeScript.generate(Hut) # => "interface Hut {\n code: string;\n season?: 'summer' | 'winter' | 'year_round' | null;\n places?: bigint | null;\n}\n"A registered option belongs to the whole field. An array element can’t carry one, so an override covers the entire field.
5. Handle recursion and anonymous structs
Section titled “5. Handle recursion and anonymous structs”A recursive struct would loop if the generator expanded nodes. Struct nodes are references, though, and the generator reserves the name before it walks the fields.
class Junction < FieldStruct::Base required :label, :string optional :branches, :array, of: Junctionend
TypeScript.generate(Junction) # => "interface Junction {\n label: string;\n branches?: Junction[] | null;\n}\n"FieldStruct::Introspection.named?(Junction) # => trueFieldStruct::Introspection.named?(Class.new(FieldStruct::Base)) # => falseIntrospection.named? says whether a class can serve as a definition name. An anonymous class can’t, so a real adapter should either raise a clear error for it or inline it.
6. Test it
Section titled “6. Test it”Test the output as text, one struct per example, and test the claim you make about the data. Here the claim is that the interface lists exactly the keys to_json writes.
keys = Oj.load(Trek.new(name: 'Haute Route', days: 7).to_json).keysdeclared = TypeScript.generate(Trek).scan(/^ (\w+)\??:/).flatten.drop(1)declared == keys # => truedeclared drops the first match, which is label from the nested Waypoint. In a spec that becomes expect(declared).to eq(keys), with one example per type and one per override.
7. Package it as a gem
Section titled “7. Package it as a gem”Copy the shape of the first-party adapters.
Gem::Specification.new do |spec| spec.name = 'field_struct-typescript' spec.version = '1.0.0' spec.summary = 'TypeScript interfaces for field_struct classes' spec.authors = ['Your Name'] spec.license = 'MIT' spec.required_ruby_version = '>= 3.3' spec.files = Dir['lib/**/*.rb', 'README.md', 'LICENSE.txt'] spec.add_dependency 'field_struct', '>= 1.0.0.pre1', '< 2'end- The entry point is
lib/field_struct/typescript.rb, with an explicitrequire_relativeper file. - Module functions come first. Add an opt-in
Methodsmodule only if people wantKlass.to_typescript. - Requiring the gem must leave your users’ classes alone.
- For anything you can’t map, raise
ArgumentErrornaming the class and field, and don’t guess. - Depend on
field_structalone. Any third-party library your format needs becomes a dependency of your gem.
See also
Section titled “See also”- Introspection reference
- How adapters work: why adapters are shaped this way
- JSON Schema: a finished adapter to read
FieldStruct, Actionable and their adapters are open source under the MIT license.