chore: misc updates

mattkhan · mattkhan · commit e9eb26cf26f3 · 2025-02-14T18:08:32.000-08:00
diff --git a/README.md b/README.md
@@ -1,264 +1,30 @@
 # JSON:API Resource Schema Generation: Anchor
 
+[Documentation](https://anchor-gem.vercel.app/docs)
+
 Easily generate TypeScript schemas, JSON Schemas, or any schema of your choice
 from [cerebris/jsonapi-resources](https://github.com/cerebris/jsonapi-resources)
 `JSONAPI::Resource` classes.
 
 Ideally, API schemas have the types of each payload fully specified.
 
-To conveniently reach that ideal in a Ruby codebase that doesn't have static
-type signatures, `Anchor` automates type inference for attributes and
-relationships via the underlying ActiveRecord model of the `JSONAPI::Resource`.
-
-If a type for an attribute or relationship can't be inferred or you'd like to
-specify it statically, you can annotate the `attribute` or `relationship` via
-types defined in `Anchor::Types`, see [Annotations](#annotations).
-
-This gem provides TypeScript and JSON Schema generators with
-`Anchor::TypeScript::SchemaGenerator` and `Anchor::JSONSchema::SchemaGenerator`.
-
-See the [example](./spec/example) Rails app for a fully functional example using
-`Anchor`. See
-[example_schema_snapshot_spec.rb](./spec/anchor/example_schema_snapshot_spec.rb)
-for `Schema` generation examples.
-
-## Inference
-
-### Attributes
-
-`JSONAPI::Resource` attributes are inferred via introspection of the resource's
-underlying ActiveRecord model (`JSONAPI::Resources._model_class`).
-
-`ActiveRecord::Base.columns_hash[attribute]` is used to get the SQL type and is
-then mapped to an `Anchor::Type` in
-`Anchor::Types::Inference::ActiveRecord::SQL.from`.
-
-- `Anchor.config.ar_column_to_type` allows custom mappings, see
-  [spec/example/config/initializers/anchor.rb](./spec/example/config/initializers/anchor.rb)
-- `Anchor.config.use_active_record_presence` can be set to `true` to infer
-  nullable attributes (i.e. fields that do not specify `null: false` in
-  schema.rb) as non-null when an unconditional
-  `validates :attribute_name, presence: true` is present on the model
-
-### Relationships
-
-`JSONAPI::Resource` relationships refer to other `JSONAPI::Resource` classes, so
-the `JSONAPI::Resource.anchor_schema_name` of the related relationship is used
-as a reference in the TypeScript and JSON Schema adapters.
-
-`Anchor` infers whether the associated resource is nullable or an array via
-`JSONAPI::Resource._model_class.reflections[name]` where `name` is the first
-element of the `JSONAPI::Resource._relationships` `[name, relationship]` tuples.
-
-| ActiveRecord Association               | Inferred `Anchor::Type` |
-| -------------------------------------- | ----------------------- |
-| `belongs_to :relation`                 | `Relation`              |
-| `belongs_to :relation, optional: true` | `Maybe<Relation>`       |
-| `has_one :relation`                    | `Maybe<Relation>`       |
-| `has_many :relations`                  | `Array<Relation>`       |
-| `has_and_belogs_to_many :relations`    | `Array<Relation>`       |
-
-- set `Anchor.config.infer_nullable_relationships_as_optional` to `true` to
-  infer that the property associated with a nullable relationship will not be
-  present if it's null
-  - e.g. in TypeScript, setting the config to true will infer
-    `{ relation?: Relation }` over `{ relation: Maybe<Relation> }`
-
-## Annotations
-
-The APIs of `JSONAPI::Resource.attribute` and `JSONAPI::Resource.relationship`
-have been modified to take in an optional type parameter.
-
-If the type can be inferred from the underlying ActiveRecord model the type
-argument isn't required.
-
-If there is no type argument and the type cannot be inferred, then the type of
-the property will default to `unknown`.
-
-The type argument has precedence over the inferred type.
-
-For `.attribute`:
-
-- after the `name` argument, specify any type from the table in
-  [Anchor::Types](#anchortypes)
-
-For `.relationship`:
-
-- after the `name` argument, specify a `Anchor::Types::Relationship`
-
-The APIs of `JSONAPI::Resource.attribute` and `JSONAPI::Resource.relationship`
-remain the same if a type argument is not given.
-
-If a type argument is given, the `options` for each will be the third argument.
-
-### Descriptions
-
-If the `description` key is present in the options to `.attribute` or
-`.relationship`, it will be used in the provided TypeScript Schema generator as
-a comment for the property. The comment should show up in the LSP hover info.
-
-With `Anchor.config.use_active_record_presence = true`, a default `description`
-will be inferred from the ActiveRecord column comment if it exists. Examples of
-both in
-[spec/example/app/resources/exhaustive_resource.rb](./spec/example/app/resources/exhaustive_resource.rb)
-and its resulting [TypeScript schema](./spec/example/test/files/schema.ts).
-
-## Generators
-
-This gem provides generators for JSON Schema and TypeScript schemas via
-`Schema.generate(adapter: :type_script | :json_schema)`.
-
-### Custom Generator
-
-You can create your own generator by providing it to
-`Schema.generate(adapter: MyGenerator)`.
-
-It should inherit from `Anchor::SchemaGenerator`, e.g.
-
-```rb
-class MyGenerator < Anchor::SchemaGenerator
-  def call
-    raise NotImplementedError
-  end
-end
-```
-
-See `Anchor::TypeScript::Resource`, `Anchor::TypeScript::Serializer`, and
-`Anchor::TypeScript::SchemaGenerator` and the equivalents under
-`Anchor::JSONSchema` for examples.
-
-## Configuration
-
-| Name                                       | Type                         | Description                                                                                                                                        |
-| ------------------------------------------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `field_case`                               | `:camel \| :snake \| :kebab` | Case format for `attributes` and `relationships` properties.                                                                                       |
-| `ar_column_to_type`                        | `Proc`                       | `ActiveRecord::Base.columns_hash[attribute]` to `Anchor::Type`                                                                                     |
-| `use_active_record_comment`                | `Boolean`                    | whether to use ActiveRecord comments as default value of `description` option                                                                      |
-| `use_active_record_presence`               | `Boolean`                    | check presence of unconditional `validates :attribute, presence: true` to infer database nullable attribute as non-null                            |
-| `infer_nullable_relationships_as_optional` | `Boolean`                    | `true` infers nullable relationships as optional. e.g. in TypeScript, `true` infers `{ relation?: Relation }` over `{ relation: Maybe<Relation> }` |
-
-## Guides
-
-### Create a schema serializable resource
-
-```rb
-class ApplicationResource
-  include Anchor::SchemaSerializable
-end
-
-class SomeScope::UserResource < ApplicaionResource
-  # optional anchor_schema_name definition
-  # defaults to part of the string after the last :: (or class name itself if not nested) and removes Resource, in this case User
-  anchor_schema_name "SpecialUser"
-
-  attribute :name
-  attribute :role, Anchor::Types::String
-
-  relationship :profile, to: :one
-  relationship :group, Anchor::Types::Relationship.new(resource: GroupResource, null: true), to: :one
-end
-```
-
-### `Anchor::Schema`
-
-```rb
-class Schema < Anchor::Schema
-  resource CommentResource # register resources
-  resource UserResource
-  resource PostResource
-
-  enum UserRoleEnum # register enums
-end
-```
-
-`Schema.generate` will return the schema in a `String`.
-
-Note: Currently, dependent resources and enums do not have their types
-generated. _All_ resources and enums must be registered as part of the schema.
-
-### `Anchor::Types`
-
-| `Anchor (type = Types::...)` | TypeScript type expression                                                |
-| ---------------------------- | ------------------------------------------------------------------------- |
-| `Types::String`              | `string`                                                                  |
-| `Types::Integer`             | `number`                                                                  |
-| `Types::Float`               | `number`                                                                  |
-| `Types::BigDecimal`          | `string`                                                                  |
-| `Types::Boolean`             | `boolean`                                                                 |
-| `Types::Null`                | `null`                                                                    |
-| `Types::Unknown`             | `unknown`                                                                 |
-| `Types::Maybe.new(T)`        | `Maybe<T>`                                                                |
-| `Types::Array.new(T)`        | `Array<T>`                                                                |
-| `Types::Record`              | `Record<string, unknown>`                                                 |
-| `Types::Record.new(T)`       | `Record<string, T>`                                                       |
-| `Types::Reference.new(name)` | `name` (directly used as type identifier)                                 |
-| `Types::Literal.new(value)`  | `"#{value}"` if `string`, else `value.to_s`                               |
-| `Types::Enum`                | `Enum.anchor_schema_name` (directly used as type identifier)              |
-| `Types::Union.new(Ts)`       | `Ts[0] \| Ts[1] \| ...`                                                   |
-| `Types::Object.new(props)`   | `{ [props[0].name]: props[0].type, [props[1].name]: props[1].type, ... }` |
-
-Note: The TypeScript type expression is derived from the
-`Anchor::TypeScript::Serializer` this gem provides for TypeScript schema
-generation. See `Anchor::JSONSchema::Serializer` for the given JSON Schema
-generator.
-
-```rb
-module Anchor::Types
-  # @!attribute [r] resource
-  #   @return [JSONAPI::Resource, NilClass] the associated resource
-  # @!attribute [r] resources
-  #   @return [Array<JSONAPI::Resource>, NilClass] union of associated resources
-  # @!attribute [r] null
-  #   @return [Boolean] whether the relationship can be `null`
-  # @!attribute [r] null_elements
-  #   @return [Boolean] whether the elements in a _many_ relationship can be `null`
-  Relationship = Struct.new(:resource, :resources, :null, :null_elements, keyword_init: true)
-end
-```
-
-#### `Anchor::Types::Object`
-
-```rb
-class CustomPayload < Anchor::Types::Object
-  property :id, Anchor::Types::String, optional: true, description: "ID of payload."
-end
-```
-
-#### `Anchor::Types::Enum`
-
-```rb
-class UserRoleEnum < Anchor::Types::Enum
-  anchor_schema_name "UserRole" # optional, similar logic to Resource but removes Enum
-
-  # First argument is the enum member identifier that gets camelized
-  # Second argument is the value
-  value :admin, "admin"
-  value :content_creator, "content_creator"
-  value :external, "external"
-  value :guest, "guest"
-  value :system, "system"
-end
+`jsonapi-resources-anchor` provides:
 
-# alternatively
-class User < ApplicationRecord
-  enum :role, {
-    admin: "admin",
-    conent_creator: "content_creator",
-    external: "external",
-    guest: "guest",
-    system: "system",
-  }
-end
-
-class UserRoleEnum < Anchor::Types::Enum
-  User.roles.each { |key, val| value key, val }
-end
-```
+- [Type inference](https://anchor-gem.vercel.app/docs/Features/type_inference)
+  via the underlying ActiveRecord model of a resource
+- [Type annotation](https://anchor-gem.vercel.app/docs/Features/type_annotation),
+  e.g. `attribute :name_length, Anchor::Types::Integer`
+- [Configuration](https://anchor-gem.vercel.app/docs/API/configuration), e.g.
+  setting the case (camel, snake, etc.) of properties and deriving TypeScript
+  comments from database comments
+- TypeScript and JSON Schema generators via
+  `Anchor::TypeScript::SchemaGenerator` and
+  `Anchor::JSONSchema::SchemaGenerator`
 
-Very similar to
-[rmosolgo/graphql-ruby](https://github.com/rmosolgo/graphql-ruby) enums.
+See the [example](./spec/example) Rails app for a fully functional app using
+`Anchor`.
 
-## Example
+## TypeScript Demo
 
 Given:
 
@@ -299,7 +65,8 @@ ActiveRecord Schema:
 `JSONAPI::Resource` classes:
 
 ```rb
-class ApplicaionResource
+class ApplicationResource < JSONAPI::Resource
+  abstract
   include Anchor::SchemaSerializable
 end
 
@@ -348,8 +115,8 @@ class Schema < Anchor::Schema
 end
 ```
 
-`Schema.generate(adapter: :type_script)` will return the schema below in a
-`String`:
+`Anchor::TypeScript::SchemaGenerator.call(register: Schema.register)` will
+return the schema below in a `String`:
 
 ```ts
 type Maybe<T> = T | null;
diff --git a/lib/anchor/config.rb b/lib/anchor/config.rb
@@ -11,7 +11,7 @@ class Config
     def initialize
       @ar_column_to_type = nil
       @field_case = nil
-      @use_active_record_presence = nil
+      @use_active_record_presence = true
       @use_active_record_comment = nil
       @infer_nullable_relationships_as_optional = nil
       @empty_relationship_type = nil
diff --git a/lib/anchor/json_schema/schema_generator.rb b/lib/anchor/json_schema/schema_generator.rb
@@ -2,6 +2,13 @@ module Anchor::JSONSchema
   class SchemaGenerator < Anchor::SchemaGenerator
     delegate :type_property, to: Anchor::JSONSchema::Serializer
 
+    def initialize(register:, context: {}, include_all_fields: false, exclude_fields: nil) # rubocop:disable Lint/MissingSuper
+      @register = register
+      @context = context
+      @include_all_fields = include_all_fields
+      @exclude_fields = exclude_fields
+    end
+
     def call
       result = {
         "$schema" => "https://json-schema.org/draft-07/schema",
diff --git a/lib/anchor/resource.rb b/lib/anchor/resource.rb
@@ -162,7 +162,7 @@ def anchor_relationships_properties(included_fields:)
     # @param rel [Relationship]
     # @param resource_klass [Anchor::Resource]
     # @param name [String, Symbol]
-    # @return [Anchor::Types::Reference, Anchor::Types::Array<Anchor::Types::Reference>, Anchor::Types::Maybe<Anchor::Types::Reference>]
+    # @return [Anchor::Types::Reference, Anchor::Types::Array<Anchor::Types::Reference>, Anchor::Types::Maybe<Anchor::Types::Reference>, Anchor::Types::Union<Anchor::Types::Reference>]
     def relationship_type_for(rel, resource_klass, name)
       rel_type = if rel.polymorphic? && rel.respond_to?(:polymorphic_types) # 0.11.0.beta2
         resource_klasses = rel.polymorphic_types.map { |t| resource_klass_for(t) }
diff --git a/lib/anchor/schema.rb b/lib/anchor/schema.rb
@@ -16,21 +16,6 @@ def enum(enum)
         @enums ||= []
         @enums.push(enum)
       end
-
-      def generate(context: {}, adapter: :type_script, include_all_fields: false, exclude_fields: nil)
-        adapter = case adapter
-        when :type_script then Anchor::TypeScript::SchemaGenerator
-        when :json_schema then Anchor::JSONSchema::SchemaGenerator
-        else adapter
-        end
-
-        adapter.call(
-          register:,
-          context:,
-          include_all_fields:,
-          exclude_fields:,
-        )
-      end
     end
   end
 end
diff --git a/lib/anchor/type_script/schema_generator.rb b/lib/anchor/type_script/schema_generator.rb
@@ -1,5 +1,12 @@
 module Anchor::TypeScript
   class SchemaGenerator < Anchor::SchemaGenerator
+    def initialize(register:, context: {}, include_all_fields: false, exclude_fields: nil) # rubocop:disable Lint/MissingSuper
+      @register = register
+      @context = context
+      @include_all_fields = include_all_fields
+      @exclude_fields = exclude_fields
+    end
+
     def call
       maybe_type = "type Maybe<T> = T | null;"
 
diff --git a/spec/anchor/example_schema_snapshot_spec.rb b/spec/anchor/example_schema_snapshot_spec.rb
@@ -18,10 +18,18 @@ def self.snapshot_test(filename, generate)
     end
   end
 
-  snapshot_test "schema.ts", -> { Schema.generate(include_all_fields: true) }
-  snapshot_test "test_schema.ts", -> { Schema.generate(context: { role: "test" }) }
-  snapshot_test "all_fields_false_schema.ts", -> { Schema.generate }
-  snapshot_test "excluded_fields_schema.ts", -> { Schema.generate(exclude_fields: { User: [:name, :posts] }) }
-  snapshot_test "json_schema.json", -> { Schema.generate(adapter: :json_schema, include_all_fields: true) }
+  snapshot_test "schema.ts", -> {
+    Anchor::TypeScript::SchemaGenerator.call(register: Schema.register, include_all_fields: true)
+  }
+  snapshot_test "test_schema.ts", -> {
+    Anchor::TypeScript::SchemaGenerator.call(register: Schema.register, context: { role: "test" })
+  }
+  snapshot_test "all_fields_false_schema.ts", -> { Anchor::TypeScript::SchemaGenerator.call(register: Schema.register) }
+  snapshot_test "excluded_fields_schema.ts", -> {
+    Anchor::TypeScript::SchemaGenerator.call(register: Schema.register, exclude_fields: { User: [:name, :posts] })
+  }
+  snapshot_test "json_schema.json", -> {
+    Anchor::JSONSchema::SchemaGenerator.call(register: Schema.register, include_all_fields: true)
+  }
 end
 # rubocop:enable RSpec/EmptyExampleGroup
diff --git a/spec/example/lib/tasks/anchor.rake b/spec/example/lib/tasks/anchor.rake
