Skip to content

A platform for community discussion. Free, open, simple.

DEV: Declare writable JSON:API attributes for service contracts

Loïc Guitaute188e9571fed
diff --git a/lib/json_api_kit/declarations/attribute.rb b/lib/json_api_kit/declarations/attribute.rb
index a77ec314da9..6034b26eee8 100644
--- a/lib/json_api_kit/declarations/attribute.rb
+++ b/lib/json_api_kit/declarations/attribute.rb
@@ -3,16 +3,21 @@
module JsonApiKit
module Declarations
class Attribute
- attr_reader :name
+ attr_reader :name, :type
delegate :readable_by?, :readable_for?, to: :readable
- def initialize(name, readable: Readable::ALWAYS, &value)
+ def initialize(name, type = nil, readable: Readable::ALWAYS, writable: false, &value)
@name = name.to_s
+ @type = type.try { ActiveModel::Type.lookup(it) }
+ @writable = writable
@readable = Readable.for(readable)
@value = value
+ verify!
end
+ def writable? = @writable
+
def value_for(record)
return value.call(record) if value
record.public_send(name)
@@ -26,6 +31,15 @@ module JsonApiKit
private
attr_reader :readable, :value
+
+ def verify!
+ if [true, false].exclude?(@writable)
+ raise ArgumentError, "#{name}: writable must be true or false."
+ end
+ if writable? && type.nil?
+ raise ArgumentError, "#{name}: a writable attribute requires a type."
+ end
+ end
end
end
end
diff --git a/lib/json_api_kit/resource/fields.rb b/lib/json_api_kit/resource/fields.rb
index 4e30820ae5e..29da5514908 100644
--- a/lib/json_api_kit/resource/fields.rb
+++ b/lib/json_api_kit/resource/fields.rb
@@ -33,6 +33,8 @@ module JsonApiKit
def attribute_names = declared_attributes.map(&:name)
+ def writable_attributes = declared_attributes.select(&:writable?)
+
def relationships = Declarations::Relationships.new(declared_relationships)
def fields(names = nil, guardian:)
@@ -61,7 +63,12 @@ module JsonApiKit
end
end
- delegate :attribute_names, :relationships, :fields, :resolves?, to: :class
+ delegate :attribute_names,
+ :writable_attributes,
+ :relationships,
+ :fields,
+ :resolves?,
+ to: :class
def attribute_value(name, record:)
unless name.type == type && attribute_names.include?(name.value)
diff --git a/spec/lib/json_api_kit/declarations/attribute_spec.rb b/spec/lib/json_api_kit/declarations/attribute_spec.rb
index ef024a0eac3..052a9c44f95 100644
--- a/spec/lib/json_api_kit/declarations/attribute_spec.rb
+++ b/spec/lib/json_api_kit/declarations/attribute_spec.rb
@@ -5,6 +5,51 @@ RSpec.describe JsonApiKit::Declarations::Attribute do
fab!(:topic) { Fabricate(:topic, title: "A field rendered from a record") }
+ describe ".new" do
+ subject(:attribute) { described_class.new(:title, type, **options) }
+
+ let(:type) { :string }
+ let(:options) { { writable: true } }
+
+ context "when a writable attribute has no type" do
+ let(:type) { nil }
+
+ it "requires a type" do
+ expect { attribute }.to raise_error(ArgumentError, /title.*type/)
+ end
+ end
+
+ context "when the type is unknown" do
+ let(:type) { :unknown }
+
+ it "refuses the declaration" do
+ expect { attribute }.to raise_error(ArgumentError, /Unknown type/)
+ end
+ end
+
+ context "when writability is not a boolean" do
+ let(:options) { super().merge(writable: "false") }
+
+ it "requires a boolean" do
+ expect { attribute }.to raise_error(ArgumentError, /writable.*true or false/)
+ end
+ end
+ end
+
+ describe "#type" do
+ subject(:type) { attribute.type }
+
+ it "leaves the type unspecified" do
+ expect(type).to be_nil
+ end
+ end
+
+ describe "#writable?" do
+ it "defaults to read-only" do
+ expect(attribute).not_to be_writable
+ end
+ end
+
describe "#name" do
subject(:name) { attribute.name }
diff --git a/spec/lib/json_api_kit/resource_spec.rb b/spec/lib/json_api_kit/resource_spec.rb
index eaa5e7b75b0..0cc90bd100e 100644
--- a/spec/lib/json_api_kit/resource_spec.rb
+++ b/spec/lib/json_api_kit/resource_spec.rb
@@ -376,6 +376,27 @@ RSpec.describe JsonApiKit::Resource do
)
end
+ context "when the attribute declares a type" do
+ before { topic_resource.attribute(:views, :string, writable: true) }
+
+ it "preserves the record's value" do
+ expect(attribute_values).to include(
+ JsonApiKit::Name::Field.new(value: "views", type: topic_resource.type) => topic.views,
+ )
+ end
+ end
+
+ context "when a typed attribute declares a reader" do
+ before { topic_resource.attribute(:view_count, :integer, writable: true) { it.views.to_s } }
+
+ it "preserves the reader's value" do
+ expect(attribute_values).to include(
+ JsonApiKit::Name::Field.new(value: "view_count", type: topic_resource.type) =>
+ topic.views.to_s,
+ )
+ end
+ end
+
context "when the resource declares one more after a reading" do
before do
topic_resource.fields(guardian:).attributes
@@ -390,6 +411,64 @@ RSpec.describe JsonApiKit::Resource do
end
end
+ describe ".writable_attributes" do
+ subject(:writable_attributes) { resource.writable_attributes }
+
+ let(:resource) do
+ Class.new(described_class) do
+ attribute :title, :string, writable: true
+ attribute :tags, :array, writable: true
+ attribute :created_at, :datetime
+ attribute :views, :integer, writable: false
+ attribute :closed
+ end
+ end
+
+ it "returns the names and types of writable declarations" do
+ expect(writable_attributes.map { [it.name, it.type] }).to contain_exactly(
+ ["title", an_instance_of(ActiveModel::Type::String)],
+ ["tags", an_instance_of(ActiveSupportTypeExtensions::Array)],
+ )
+ end
+
+ context "when an attribute is unreadable" do
+ before { resource.attribute(:password, :string, writable: true, readable: ->(_) { false }) }
+
+ it "includes the writable declaration" do
+ expect(writable_attributes.map(&:name)).to include("password")
+ end
+ end
+
+ context "when a declaration follows an earlier lookup" do
+ before do
+ resource.writable_attributes
+ resource.attribute(:excerpt, :string, writable: true)
+ end
+
+ it "includes the new declaration" do
+ expect(writable_attributes.map(&:name)).to include("excerpt")
+ end
+ end
+
+ context "when a subclass adds a writable attribute" do
+ let(:child_resource) { Class.new(resource) }
+
+ before { child_resource.attribute(:excerpt, :string, writable: true) }
+
+ it "includes inherited declarations in the subclass" do
+ expect(child_resource.writable_attributes.map(&:name)).to contain_exactly(
+ "title",
+ "tags",
+ "excerpt",
+ )
+ end
+
+ it "preserves the parent's declarations" do
+ expect(writable_attributes.map(&:name)).to contain_exactly("title", "tags")
+ end
+ end
+ end
+
describe ".has_one" do
subject(:user_relationships) { topic_resource.fields(guardian:).relationships.pick(%w[user]) }
@@ -668,4 +747,10 @@ RSpec.describe JsonApiKit::Resource do
end
end
end
+
+ describe "#writable_attributes" do
+ subject(:resource) { topic_resource.new(guardian:) }
+
+ it { is_expected.to delegate_method(:writable_attributes).to(:class) }
+ end
end