alchemy-json_api 8.2.1 → 8.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db35a5d154653883deecbcc687597d88f6379f0d0d0374614d01c39d6c9584f3
-  data.tar.gz: 4214bdae6140ef97bd196573ca8565c4d5fded379ee79c6b12566f3cb61a0f27
+  metadata.gz: 19d116a1abd43f5bf4c00da09863cfdb28f2db3452dae76c6490519c144d0858
+  data.tar.gz: 91fe9df9c85dc9bb2982045a51191cbe64c03ac68425859ed0249dfe11c7ae50
 SHA512:
-  metadata.gz: d699c4291b17ad92015adb2e8987a6328265ef4f1dddb1b76ba191634fd94bb1234379c749bf5a0de49422973cf915b70775dc3c6ca0852637cc07d14e74a40b
-  data.tar.gz: 17176fb1926e846e4567c9f6243efa877d2c3f5dbef99b65611476bf8a67afd45f29b02cedceb81925e1efcb2d5b6795254667e8c41e5c28bb8243b58443a39d
+  metadata.gz: c77e4838a15daaaec7884190d1e60552a76a4af744aab59f1e78c78a4189a0205fb8ec794b15e219b7296982f396400e87b63ecf20273adba93e296fb8330bcd
+  data.tar.gz: d974acb9954a11dc9b60a3c401dc1353b47f4fbef9720d7f879d29c060bf7c8f4be6e3861aad6ae347e5544787442cac8a9d3b9f7498459711071dd36d4941f1

data/README.md

@@ -1,5 +1,7 @@
 # Alchemy::JsonApi
 
+[![Test](https://github.com/AlchemyCMS/alchemy-json_api/actions/workflows/ci.yml/badge.svg)](https://github.com/AlchemyCMS/alchemy-json_api/actions/workflows/ci.yml) [![JavaScript](https://github.com/AlchemyCMS/alchemy-json_api/actions/workflows/javascript.yml/badge.svg)](https://github.com/AlchemyCMS/alchemy-json_api/actions/workflows/javascript.yml)
+
 A JSON-API based API for AlchemyCMS
 
 ## Installation
@@ -26,13 +28,9 @@ $ gem install alchemy-json_api
 
 ### In your JS/Frontend app
 
-Run this in your application:
-
-```
-npm install @alchemy_cms/json_api --save
-```
-
-or with the package manager of your choice
+A JavaScript/TypeScript deserializer is published as
+[`@alchemy_cms/json_api`](https://www.npmjs.com/package/@alchemy_cms/json_api).
+See [`javascript/README.md`](javascript/README.md) for installation and usage.
 
 ## Usage
 
@@ -47,20 +45,6 @@ mount Alchemy::JsonApi::Engine => "/jsonapi/"
 
 > __NOTE__ Pick any path you like. This will be the **prefix** of your API URLs
 
-### In your frontend app
-
-This repo provides an NPM package with deserializers to help you convert the response into JS objects.
-
-```js
-import { deserializePages } from "@alchemy_cms/json_api"
-
-const response = await fetch("/jsonapi/pages.json")
-const data = await response.json()
-const pages = deserializePages(data)
-
-console.log(pages[0].name) // => Homepage
-```
-
 ## HTTP Caching
 
 Alchemy::JsonApi allows for caching API responses. It respects the caching configuration of your Rails app and of your Alchemy configuration and settings in the pages page layout configuration. Restricted pages are never cached.

data/app/controllers/alchemy/json_api/admin/layout_pages_controller.rb

@@ -4,6 +4,8 @@ module Alchemy
   module JsonApi
     module Admin
       class LayoutPagesController < JsonApi::Admin::PagesController
+        include FindLayoutPageByPageLayout
+
         private
 
         def page_scope

data/app/controllers/alchemy/json_api/layout_pages_controller.rb

@@ -3,6 +3,8 @@
 module Alchemy
   module JsonApi
     class LayoutPagesController < JsonApi::PagesController
+      include FindLayoutPageByPageLayout
+
       private
 
       def page_scope

data/app/controllers/concerns/alchemy/json_api/find_layout_page_by_page_layout.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Alchemy
+  module JsonApi
+    # Lets the layout pages show endpoints find a page by its page layout
+    # name in addition to its id or urlname, e.g. +/jsonapi/layout_pages/footer+.
+    #
+    # Layout pages are usually referenced by their page layout, because their
+    # urlname is derived from a name editors can change. Before, clients had
+    # to use the index endpoint with a +page_layout_eq+ filter to get them.
+    #
+    # Lookups by id and urlname take precedence. If more than one layout page
+    # with the same page layout exists in a language (i.e. the layout is not
+    # +unique+), the first one is returned.
+    module FindLayoutPageByPageLayout
+      private
+
+      def load_page_for_cache_key
+        super
+      rescue ActiveRecord::RecordNotFound
+        @page = page_scope.find_by!(page_layout: params[:path])
+      end
+
+      def load_page_by_urlname
+        super || page_scope_with_includes.find_by(page_layout: params[:path])
+      end
+    end
+  end
+end

data/app/serializers/alchemy/json_api/element_serializer.rb

@@ -6,9 +6,7 @@ module Alchemy
       attributes(
         :name,
         :fixed,
-        :position,
-        :created_at,
-        :updated_at
+        :position
       )
 
       cache_options store: Rails.cache, namespace: "alchemy-jsonapi"
@@ -18,10 +16,13 @@ module Alchemy
       end
 
       has_many :ingredients,
+        lazy_load_data: true,
         serializer: ->(record) do
           "Alchemy::JsonApi::Ingredient#{record.type.demodulize}Serializer".constantize
         end
 
+      # Eager: the element tree (all_elements -> nested_elements) is recursive
+      # and can't be expressed as an `include`, so its linkage is always present.
       has_many :nested_elements, record_type: :element, serializer: self
     end
   end

data/app/serializers/alchemy/json_api/ingredient_node_serializer.rb

@@ -11,7 +11,7 @@ module Alchemy
         ingredient.node&.name
       end
 
-      belongs_to :node, record_type: :node, serializer: ::Alchemy::JsonApi::NodeSerializer
+      belongs_to :node, record_type: :node, serializer: ::Alchemy::JsonApi::NodeSerializer, lazy_load_data: true
 
       with_options if: proc { |ingredient| ingredient.node } do
         attribute :name do |ingredient|

data/app/serializers/alchemy/json_api/ingredient_page_serializer.rb

@@ -19,7 +19,7 @@ module Alchemy
         ingredient.page&.url_path
       end
 
-      has_one :page, record_type: :page, serializer: PageSerializer do |ingredient|
+      has_one :page, record_type: :page, serializer: PageSerializer, lazy_load_data: true do |ingredient|
         Alchemy::JsonApi::Page.new(ingredient.page) if ingredient.page
       end
     end

data/app/serializers/alchemy/json_api/language_serializer.rb

@@ -10,13 +10,13 @@ module Alchemy
         :locale
       )
 
-      has_many :menu_items, record_type: :node, serializer: ::Alchemy::JsonApi::NodeSerializer, object_method_name: :nodes, id_method_name: :node_ids
+      has_many :menu_items, record_type: :node, serializer: ::Alchemy::JsonApi::NodeSerializer, object_method_name: :nodes, id_method_name: :node_ids, lazy_load_data: true
 
-      has_many :menus, record_type: :node, serializer: ::Alchemy::JsonApi::NodeSerializer do |language|
+      has_many :menus, record_type: :node, serializer: ::Alchemy::JsonApi::NodeSerializer, lazy_load_data: true do |language|
         language.nodes.select { |n| n.parent.nil? }
       end
-      has_many :pages
-      has_one :root_page, record_type: :page, serializer: ::Alchemy::JsonApi::PageSerializer
+      has_many :pages, lazy_load_data: true
+      has_one :root_page, record_type: :page, serializer: ::Alchemy::JsonApi::PageSerializer, lazy_load_data: true
     end
   end
 end

data/app/serializers/alchemy/json_api/node_serializer.rb

@@ -8,18 +8,19 @@ module Alchemy
       attribute :link_title, &:title
       attribute :link_nofollow, &:nofollow
 
-      belongs_to :parent, record_type: :node, serializer: self
+      belongs_to :parent, record_type: :node, serializer: self, lazy_load_data: true
 
       belongs_to(
         :page,
         record_type: :page,
         if: ->(node) { node.page },
-        serializer: ::Alchemy::JsonApi::PageSerializer
+        serializer: ::Alchemy::JsonApi::PageSerializer,
+        lazy_load_data: true
       ) do |node|
         ::Alchemy::JsonApi::Page.new(node.page)
       end
 
-      has_many :children, record_type: :node, serializer: self
+      has_many :children, record_type: :node, serializer: self, lazy_load_data: true
     end
   end
 end

data/app/serializers/alchemy/json_api/page_serializer.rb

@@ -13,7 +13,9 @@ module Alchemy
         :language_code,
         :created_at,
         :updated_at,
-        :restricted
+        :restricted,
+        :robot_index,
+        :robot_follow
       )
 
       cache_options store: Rails.cache, namespace: "alchemy-jsonapi"
@@ -33,24 +35,28 @@ module Alchemy
         end
       end
 
-      belongs_to :language, record_type: :language, serializer: ::Alchemy::JsonApi::LanguageSerializer
+      belongs_to :language, record_type: :language, serializer: ::Alchemy::JsonApi::LanguageSerializer, lazy_load_data: true
 
-      has_many :ancestors, record_type: :page, serializer: self do |page|
+      has_many :ancestors, record_type: :page, serializer: self, lazy_load_data: true do |page|
         page.ancestors.map do |ancestor|
           Alchemy::JsonApi::Page.new(ancestor, page_version_type: page.page_version_type)
         end
       end
 
       # All public elements of this page regardless of if they are fixed or nested.
-      # Used for eager loading and should be used as the +include+ parameter of your query
+      # Used for eager loading and should be used as the +include+ parameter of your query.
+      # Eager: paired with the recursive nested_elements linkage to build the element
+      # tree, which can't be expressed as an `include`.
       has_many :all_elements, record_type: :element, serializer: ELEMENT_SERIALIZER
 
       # The top level public, non-fixed elements of this page that - if present -
-      # contains their nested_elements.
+      # contains their nested_elements. Eager: the roots of the element tree
+      # (see all_elements above).
       has_many :elements, record_type: :element, serializer: ELEMENT_SERIALIZER
 
       # The top level public, fixed elements of this page that - if present -
-      # contains their nested_elements.
+      # contains their nested_elements. Eager: the roots of the element tree
+      # (see all_elements above).
       has_many :fixed_elements, record_type: :element, serializer: ELEMENT_SERIALIZER
     end
   end

data/lib/alchemy/json_api/engine.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 require "jsonapi"
+# Fixes jsonapi-serializer's `lazy_load_data` for nested includes. Loaded at
+# boot (rather than via an autoloader) because it patches a gem constant.
+require "alchemy/json_api/patches/fast_jsonapi/serialization_core_patch"
 
 module Alchemy
   module JsonApi

data/lib/alchemy/json_api/ingredient_serializer.rb

@@ -6,12 +6,11 @@ module Alchemy
       def self.included(klass)
         klass.attributes(
           :role,
-          :value,
-          :created_at,
-          :updated_at
+          :value
         )
 
         klass.attribute :deprecated, &:deprecated?
+        klass.cache_options store: Rails.cache, namespace: "alchemy-jsonapi"
       end
     end
   end

data/lib/alchemy/json_api/patches/fast_jsonapi/serialization_core_patch.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "jsonapi/serializer"
+
+module Alchemy
+  module JsonApi
+    module Patches
+      module FastJsonapi
+        # Makes jsonapi-serializer's `lazy_load_data` honour *nested* includes.
+        #
+        # With `lazy_load_data: true` a relationship only emits its linkage when
+        # it was requested, which upstream (jsonapi-serializer 2.2.0) decides
+        # with `includes_list.include?(key)`. Two things break that for any
+        # sideloaded (nested) resource:
+        #
+        #   1. the includes are dotted paths (`primary_taxon.ancestors`), so
+        #      `include?(:primary_taxon)` never matches; and
+        #   2. `get_included_records` hands each sideloaded record the *parent's*
+        #      includes_list instead of the scoped remainder, so a nested
+        #      resource judges its own relationships against the wrong paths.
+        #
+        # Together these suppress linkage for *every* relationship of a nested
+        # resource -- even requested ones -- making lazy_load_data unusable
+        # beyond top-level relationships.
+        #
+        # The two overrides below fix each half: `relationships_hash` matches the
+        # base key of every requested path, and `get_included_records` threads
+        # the scoped remainder into each sideloaded record. Relationships that do
+        # not set `lazy_load_data` are unaffected (their linkage always emits).
+        # Prepended onto the shared SerializationCore, so every serializer gets it.
+        module SerializationCorePatch
+          # Upstream tests `includes_list.include?(key)` verbatim. Normalising the
+          # list to the set of base keys first makes that check match dotted paths,
+          # so the rest of upstream's implementation can stand.
+          def relationships_hash(record, relationships = nil, fieldset = nil, includes_list = nil, params = {})
+            super(record, relationships, fieldset, base_include_keys(includes_list), params)
+          end
+
+          # Verbatim copy of FastJsonapi::SerializationCore 2.2.0 with a single
+          # change, flagged inline below -- keep it diffable against upstream.
+          def get_included_records(record, includes_list, known_included_objects, fieldsets, params = {})
+            return unless includes_list.present?
+            return [] unless relationships_to_serialize
+
+            includes_list = parse_includes_list(includes_list)
+
+            includes_list.each_with_object([]) do |include_item, included_records|
+              relationship_item = relationships_to_serialize[include_item.first]
+
+              next unless relationship_item&.include_relationship?(record, params)
+
+              included_objects = Array(relationship_item.fetch_associated_object(record, params))
+              next if included_objects.empty?
+
+              static_serializer = relationship_item.static_serializer
+              static_record_type = relationship_item.static_record_type
+
+              included_objects.each do |inc_obj|
+                serializer = static_serializer || relationship_item.serializer_for(inc_obj, params)
+                record_type = static_record_type || serializer.record_type
+
+                if include_item.last.any?
+                  serializer_records = serializer.get_included_records(inc_obj, include_item.last, known_included_objects, fieldsets, params)
+                  included_records.concat(serializer_records) unless serializer_records.empty?
+                end
+
+                code = "#{record_type}_#{serializer.id_from_record(inc_obj, params)}"
+                next if known_included_objects.include?(code)
+
+                known_included_objects << code
+
+                # CHANGED vs upstream: pass this include's remainder rather than
+                # the parent's parsed includes_list, so the sideloaded record
+                # scopes its own relationships correctly.
+                included_records << serializer.record_hash(inc_obj, fieldsets[record_type], include_item.last, params)
+              end
+            end
+          end
+
+          private
+
+          # The base relationship keys requested at this level, e.g.
+          # `[:primary_taxon.ancestors, :author]` -> Set[:primary_taxon, :author].
+          def base_include_keys(includes_list)
+            return Set.new if includes_list.blank?
+
+            includes_list.map { |path| path.to_s.split(".", 2).first.to_sym }.to_set
+          end
+
+          ::FastJsonapi::SerializationCore::ClassMethods.prepend(self)
+        end
+      end
+    end
+  end
+end

data/lib/alchemy/json_api/test_support/ingredient_serializer_behaviour.rb

@@ -5,14 +5,8 @@ RSpec.shared_examples "an ingredient serializer" do
     subject { serializer.serializable_hash[:data][:attributes] }
 
     it "has the right transformed keys and values" do
-      transform_method = FastJsonapi::ObjectSerializer::TRANSFORMS_MAPPING[Alchemy::JsonApi.key_transform]
-      transformed_keys = %w[created_at updated_at].map { |k| k.send(*transform_method).to_sym }
-
       expect(subject).to have_key(:role)
       expect(subject).to have_key(:value)
-      transformed_keys.each do |transformed_key|
-        expect(subject).to have_key(transformed_key)
-      end
       expect(subject[:deprecated]).to be(false)
     end
 

data/lib/alchemy/json_api/version.rb

@@ -2,6 +2,6 @@
 
 module Alchemy
   module JsonApi
-    VERSION = "8.2.1"
+    VERSION = "8.4.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: alchemy-json_api
 version: !ruby/object:Gem::Version
-  version: 8.2.1
+  version: 8.4.0
 platform: ruby
 authors:
 - Martin Meyerhoff
@@ -16,7 +16,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 8.2.0.a
+        version: 8.3.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '9'
@@ -26,7 +26,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 8.2.0.a
+        version: 8.3.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '9'
@@ -122,6 +122,7 @@ files:
 - app/controllers/alchemy/json_api/layout_pages_controller.rb
 - app/controllers/alchemy/json_api/nodes_controller.rb
 - app/controllers/alchemy/json_api/pages_controller.rb
+- app/controllers/concerns/alchemy/json_api/find_layout_page_by_page_layout.rb
 - app/models/alchemy/json_api/page.rb
 - app/serializers/alchemy/json_api/base_serializer.rb
 - app/serializers/alchemy/json_api/element_serializer.rb
@@ -147,6 +148,7 @@ files:
 - lib/alchemy/json_api.rb
 - lib/alchemy/json_api/engine.rb
 - lib/alchemy/json_api/ingredient_serializer.rb
+- lib/alchemy/json_api/patches/fast_jsonapi/serialization_core_patch.rb
 - lib/alchemy/json_api/test_support/ingredient_serializer_behaviour.rb
 - lib/alchemy/json_api/version.rb
 - lib/tasks/alchemy/json_api_tasks.rake