graphiti-activegraph 0.2.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba0c3b914198cabc31276a535e428887a5ff15ff557d3dbf1f40f7ef63d463ce
-  data.tar.gz: 29c6bcff84e546779872c7cd197727f8ecaad1a12ece312a5032e93cd90c3060
+  metadata.gz: c387f138fe40ab7a304c5d587a0281258e2bf4e8304d7e0f0967295adeeef6d7
+  data.tar.gz: 6154b76796fef327e488b722d1075b05f448be9fd499e4b8525e58b3544399d0
 SHA512:
-  metadata.gz: 5d930274a4203b73d77a50281c1091e4a4e5cf0bb0b467398dab4b3e2edd59daa60e63d31250941f1c373d04e9136a46bcb2c80b7cd2a0b29dfd685691e4c64f
-  data.tar.gz: bb3211192ac37a29c578ab71076e57995ddb7768f233a571428c9088989e8b773d36536f6a8f1d9f4d13154c0bfe53aedd3e5916507451641aded67b83f7d36a
+  metadata.gz: 16cf1d53448e132be9dd3c45dc755f933f434114dc13d7414b3670becaf97c4696ba0c57e3f10075f984b60516d1286d3ccee01bad8baa4bc2bad1143ea1d1f4
+  data.tar.gz: 69a336f08b80474be83a0d0111e74a7cfbed451e5dc3ca2dba41318e3212c0e10565f799be327fdc9a26eed111b7ef1a7a46d90f24e85151a4f0d1e719b909d9

data/.github/workflows/specs.yml

@@ -18,20 +18,34 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby-version: [ jruby, ruby ]
+        ruby-version: [ ruby-3.4.2, ruby-3.3.7, ruby-3.2.7 ] # Removed 'jruby' till https://github.com/jruby/jruby/issues/8642 is fixed
+        neo4j: [ 5.23.0 ]
+        include:
+          - ruby: jruby
+            java-version: 17
     env:
       JRUBY_OPTS: --debug -J-Xmx1280m -Xcompile.invokedynamic=false -J-XX:+TieredCompilation -J-XX:TieredStopAtLevel=1 -J-noverify -Xcompile.mode=OFF
     steps:
+      - name: Start neo4j
+        run: docker run --name neo4j --env NEO4J_AUTH=neo4j/password --env NEO4J_ACCEPT_LICENSE_AGREEMENT=yes --env NEO4J_dbms_directories_import= -p7687:7687 -p7474:7474 -v `pwd`/tmp:/var/lib/neo4j/import --rm neo4j:${{ matrix.neo4j }}-enterprise &
+
       - uses: actions/checkout@v3
+
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby-version }}
           bundler-cache: true
+
       - name: Set up Java
-        uses: actions/setup-java@v3
+        uses: actions/setup-java@v4
+        if: matrix.java-version
         with:
           distribution: 'temurin'
-          java-version: 17
+          java-version: ${{ matrix.java-version }}
+
+      - name: Wait for neo4j
+        run: while [ $((curl localhost:7474/ > /dev/null 2>&1); echo $?) -ne 0 ]; do sleep 1; done
+
       - name: Run tests
         run: bundle exec rspec

data/.gitignore

@@ -52,5 +52,8 @@ build-iPhoneSimulator/
 # unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
 .rvmrc
 
+# RubyMine project files
+.idea
+
 # Used by RuboCop. Remote config files pulled in from inherit_from directive.
 # .rubocop-https?--*

data/CHANGELOG.md

@@ -1,80 +1,35 @@
-## Unreleased
+# Changelog
 
--
+All notable changes to this project will be documented in this file.
 
-## 0.1.8 (09-06-2021)
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-Features:
+## [Unreleased]
 
-- Added support for polymorphic relationship.
+## [1.1.0] - 2025-05-2
 
-## 0.1.13 (21-12-2021)
+### Added
 
-Features:
+- **Deep sideloading**: introduced Include scoping class to support deep sideloading using single query (e.g. include='author.posts')
+- **Deep sorting**: added SortNormalizer to support sorting by deep sideloaded resource's attribute (e.g. sort='author.posts.title')
+- **Links control**: Control the links(pagination and resource) in response via request query params (pagination_links=true|false, links=true|false)
 
-- Supports Jruby-9.3.2.0
+## [1.0.0] - 2025-03-18
 
-## 0.1.14 (21-12-2021)
+### Added
 
-Features:
+- **MRI Support**: Introduced compatibility with MRI (Matz's Ruby Interpreter), expanding the gem's usability beyond JRuby (#38).
+- **Documentation Updates**: Expanded the README to provide clearer guidance on gem usage and integration (#38).
+- **Sideloading Workflow**: Enhanced scoping mechanisms and added support for eager loading associations to improve data retrieval efficiency and flexibility (#38).
 
-- Adding unpaginated query to resource proxy with preloaded records. This will help in getting count on API.
+### Changed
+- **Resource Class**: Instead of modifying the `Graphiti::Resource` class, we now define `Graphiti::ActiveGraph::Resource`,  
+  which must be inherited in all resource classes to enable ActiveGraph support (#38).
 
-## 0.1.15 (21-06-2022)
+---
 
-Features:
+*Note: For details on changes prior to version 1.0.0, please refer to the [`CHANGELOG_PRE_1.0.0.md`](CHANGELOG_PRE_1.0.0.md) file.*
 
-- Relationships mentioned in sparse field param (and not in include), will now be returned in relationship block of response
-
-## 0.1.20
-
-Features:
-
-- With graphiti config variable "allow_sidepost" you can allow/disallow sideposting, by default it is allowed.
-
-## 0.1.21
-
-Fixes:
-
-- Runner#proxy keyword arguments
-
-## 0.1.22
-
-Fixes:
-
-- when rendering preloaded resources, we were not applying scoping. Now we are skipping around_scoping callback too.
-
-## 0.1.23 (29-04-2024)
-
-Features:
-
-- Added support for UUID
-
-## 0.1.24 (18-06-2024)
-
-Features:
-
-- Added preliminary support for Sideload backed by function instead of model association
-
-## 0.1.25 (04-12-2024)
-
-Features:
-
-- Added support to preload extra_fields for the main resource, replacing N+1 queries with a single query. This does not apply to sideloaded resources.
-
-## 0.2.0 (01-24-2025)
-
-Features:
-
-- Added MRI support
-- Added support for rails 8
-
-Breaking changes:
-
-- Removed support for graphiti <= 1.6.3
-
-<!-- ### [version (DD-MM-YYYY)] -->
-<!-- Breaking changes:-->
-<!-- Features:-->
-<!-- Fixes:-->
-<!-- Misc:-->
+[unreleased]: https://github.com/mrhardikjoshi/graphiti-activegraph/compare/v1.0.0...master
+[1.0.0]: https://github.com/mrhardikjoshi/graphiti-activegraph/compare/9f837108ae57287c65b0f6fd2609dd56a95cd461...v1.0.0

data/CHANGELOG_PRE_1.0.0.md

@@ -0,0 +1,70 @@
+## 0.1.8 (09-06-2021)
+
+Features:
+
+- Added support for polymorphic relationship.
+
+## 0.1.13 (21-12-2021)
+
+Features:
+
+- Supports Jruby-9.3.2.0
+
+## 0.1.14 (21-12-2021)
+
+Features:
+
+- Adding unpaginated query to resource proxy with preloaded records. This will help in getting count on API.
+
+## 0.1.15 (21-06-2022)
+
+Features:
+
+- Relationships mentioned in sparse field param (and not in include), will now be returned in relationship block of response
+
+## 0.1.20
+
+Features:
+
+- With graphiti config variable "allow_sidepost" you can allow/disallow sideposting, by default it is allowed.
+
+## 0.1.21
+
+Fixes:
+
+- Runner#proxy keyword arguments
+
+## 0.1.22
+
+Fixes:
+
+- when rendering preloaded resources, we were not applying scoping. Now we are skipping around_scoping callback too.
+
+## 0.1.23 (29-04-2024)
+
+Features:
+
+- Added support for UUID
+
+## 0.1.24 (18-06-2024)
+
+Features:
+
+- Added preliminary support for Sideload backed by function instead of model association
+
+## 0.1.25 (04-12-2024)
+
+Features:
+
+- Added support to preload extra_fields for the main resource, replacing N+1 queries with a single query. This does not apply to sideloaded resources.
+
+## 0.2.0 (01-24-2025)
+
+Features:
+
+- Added MRI support
+- Added support for rails 8
+
+Breaking changes:
+
+- Removed support for graphiti <= 1.6.3

data/README.md

@@ -0,0 +1,81 @@
+# Graphiti ActiveGraph
+
+[![Gem Version](https://badge.fury.io/rb/graphiti-activegraph.svg)](https://badge.fury.io/rb/graphiti-activegraph) [![Build Status](https://github.com/mrhardikjoshi/graphiti-activegraph/actions/workflows/specs.yml/badge.svg?branch=master)](https://github.com/mrhardikjoshi/graphiti-activegraph/actions?query=branch%3Amaster) [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+
+An adapter to make Graphiti work with the ActiveGraph(former Neo4jrb) OGM. This gem allows you to easily build [jsonapi.org](https://jsonapi.org) compatible APIs for GraphDB using [Graphiti](https://www.graphiti.dev) and [ActiveGraph](https://github.com/neo4jrb/activegraph). 
+
+## Installation
+Add this line to your application's `Gemfile`:
+```ruby
+gem 'graphiti-activegraph'
+```
+
+And then execute:
+```shell
+bundle install
+```
+
+Or install it yourself as:
+```shell
+gem install graphiti-activegraph
+```
+
+## Usage
+While defining a Resource class, inherit it from `Graphiti::ActiveGraph::Resource`
+```ruby
+class PlanetResource < Graphiti::ActiveGraph::Resource
+```
+
+For model backed by `ApplicationRelationship` instead of `ApplicationNode`, we have to set `relationship_resource` to `true` while defining resource class.
+```ruby
+class RelationshipBackedResource < Graphiti::ActiveGraph::Resource
+  self.relationship_resource = true
+end
+```
+
+## Documentation
+### Key Differences from Graphiti
+#### Efficient Sideloading:
+Unlike Graphiti, which executes multiple queries for sideloading, graphiti-activegraph leverages `with_ordered_associations` from ActiveGraph to fetch sideloaded data in a single query, improving performance.
+
+#### Sideposting Behavior:
+graphiti-activegraph allows assigning and unassigning relationships via sideposting but does not support modifying a resource’s attributes through sideposting.
+
+#### Thread Context Handling:
+Graphiti stores context using `Thread.current[]`, which does not persist across different fibers within the same thread. In graphiti-activegraph, when running on MRI (non-JRuby environments), the gem uses `thread_variable_get` and `thread_variable_set`. Ensuring the context remains consistent across different fibers in the same thread.
+
+### New Features in graphiti-activegraph
+#### Rendering Preloaded Objects Without Extra Queries
+graphiti-activegraph introduces two new methods on the Graphiti resource class:
+`with_preloaded_obj(record, params)` – Renders a single preloaded ActiveGraph object without querying the database.
+`all_with_preloaded(records, params)` – Renders multiple preloaded ActiveGraph objects without additional queries.
+**Note:** These methods assume that the provided records are final and will not apply Graphiti’s filtering, sorting, or scoping logic.
+
+#### Efficient Deep Sorting
+Graphiti does not natively support deep sorting (i.e., sorting based on attributes of associated resources), `graphiti-activegraph` adds this feature by allowing you to chain associations using dot (.) notation.
+For example, to sort Post records based on their Author's Country's name, you can use following query string:
+```
+sort=author.country.name&include=author.country
+```
+Here, `Author` and `Country` are associated resources, and `name` is an attribute on `Country`. The posts will be sorted by the country's name. You can chain any number of associations in this way to achieve deep sorting.
+Note: The `include` parameter must be present and include the full association path (`author.country`) for the sorting to work correctly.
+
+#### Response Payload Links control
+Control the links in response payload via request query params:
+- `pagination_links=true|false` — toggle top-level pagination links
+- `links=true|false` — toggle links inside each resource object
+
+## Contributing
+Bug reports and pull requests are welcome on GitHub at https://github.com/mrhardikjoshi/graphiti-activegraph. This project is intended to be a safe, welcoming space for collaboration.
+
+## Release
+1. Make sure version file is updated/incremented in master branch
+2. git checkout master
+3. git pull origin master
+4. git tag v1.2.3
+5. git push origin v1.2.3
+6. gem build graphiti-activegraph.gemspec
+7. gem push graphiti-activegraph-1.2.3.gem
+
+## License
+The gem is available as open-source under the terms of the MIT License.

data/graphiti-activegraph.gemspec

@@ -19,10 +19,14 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency 'graphiti', '>= 1.6.4'
   spec.add_dependency 'activegraph', '>= 12.0.0.beta.5'
+  spec.add_dependency 'parslet', '>= 2.0.0'
+  spec.add_dependency 'activegraph-extensions', '>= 0.1.0'
 
   spec.add_development_dependency 'graphiti_spec_helpers', '>= 1.0.0'
   spec.add_development_dependency 'standard'
   spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'ffaker'
+  spec.add_development_dependency 'factory_bot_rails'
   spec.add_development_dependency 'rake', '>= 10.0'
   spec.add_development_dependency 'rspec', '>= 3.9.0'
 end

data/lib/graphiti/active_graph/adapters/active_graph.rb

@@ -1,6 +1,6 @@
 module Graphiti::ActiveGraph
   module Adapters
-    class ActiveGraph < ::Graphiti::Adapters::Abstract
+    class ActiveGraph < Graphiti::Adapters::Abstract
       def self.sideloading_classes
         {
           has_many: Graphiti::ActiveGraph::Adapters::ActiveGraph::HasManySideload,

data/lib/graphiti/active_graph/extensions/context.rb

@@ -0,0 +1,17 @@
+module Graphiti::ActiveGraph::Extensions
+  require 'ostruct' if RUBY_PLATFORM != 'java'
+
+  module Context
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def context
+        Thread.current.thread_variable_get(:context) || {}.tap(&method(:context=))
+      end
+
+      def context=(val)
+        Thread.current.thread_variable_set(:context, val)
+      end
+    end
+  end
+end

data/lib/graphiti/active_graph/extensions/resources/authorizationable.rb

@@ -0,0 +1,29 @@
+module Graphiti::ActiveGraph::Extensions::Resources
+  module Authorizationable
+    extend ActiveSupport::Concern
+
+    included do
+      class << self
+        attr_reader :authorize_attributes
+      end
+    end
+
+    class_methods do
+      def attribute_authorization
+        @authorize_attributes = true
+      end
+
+      def authorize_attributes?
+        @authorize_attributes
+      end
+
+      def readable_attributes
+        attributes.select { |_attr_name, options_map| options_map[:readable] }
+      end
+
+      def readable_sideloads
+        sideloads.select { |_sideloads_name, sideload_obj| sideload_obj.readable? }
+      end
+    end
+  end
+end

data/lib/graphiti/active_graph/extensions/resources/payload_combinable.rb

@@ -0,0 +1,24 @@
+module Graphiti::ActiveGraph::Extensions::Resources
+  module PayloadCombinable
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def combine(attributes, relationships)
+        attributes.merge(relationship_attributes(relationships))
+      end
+
+      def relationship_attributes(relationships)
+        relationships.map { |k, v| [k, extract_ids(v)] }.to_h
+      end
+
+      def extract_ids(object)
+        object.is_a?(Array) ? object.map { |o| extract_ids(o) } : object[:attributes][:id]
+      end
+
+      def remove_undeclared_attributes(attr_map)
+        permitted_attrs = all_attributes.keys
+        attr_map.select! { |attr_name, _value| permitted_attrs.include?(attr_name.to_sym) }
+      end
+    end
+  end
+end

data/lib/graphiti/active_graph/extensions/resources/preloadable.rb

@@ -0,0 +1,19 @@
+module Graphiti::ActiveGraph::Extensions::Resources
+  module Preloadable
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def with_preloaded_obj(obj, params)
+        id = params[:data].try(:[], :id) || params.delete(:id)
+        params[:filter] ||= {}
+        params[:filter][:id] = id if id
+
+        build(params, nil, raise_on_missing: false, preloaded: obj)
+      end
+
+      def all_with_preloaded(obj_arr, params)
+        build(params, nil, single: false, raise_on_missing: false, preloaded: obj_arr)
+      end
+    end
+  end
+end

data/lib/graphiti/active_graph/extensions/resources/rel.rb

@@ -0,0 +1,19 @@
+module Graphiti::ActiveGraph::Extensions::Resources
+  module Rel
+    extend ActiveSupport::Concern
+
+    def relation_resource?
+      self.class.relation_resource?
+    end
+
+    class_methods do
+      def relation_resource?
+        config[:relation_resource] || false
+      end
+
+      def relationship_resource=(value)
+        config[:relation_resource] = value
+      end
+    end
+  end
+end

data/lib/graphiti/active_graph/jsonapi_ext/include_directive.rb

@@ -0,0 +1,66 @@
+module Graphiti::ActiveGraph::JsonapiExt
+  class IncludeDirective < JSONAPI::IncludeDirective
+    attr_accessor :length, :retain_rel_limit
+
+    def initialize(include_args, options = {})
+      include_hash = JSONAPI::IncludeDirective::Parser.parse_include_args(include_args)
+      @retain_rel_limit = options.delete(:retain_rel_limit)
+      @hash = formulate_hash(include_hash, options)
+      @options = options
+    end
+
+    def keys
+      super.select(&method(:key?))
+    end
+
+    alias get []
+
+    def key?(key)
+      super && get(key).valid_length?
+    end
+
+    def [](key)
+      super&.descend(key) || {}
+    end
+
+    def descend(key)
+      length && length != '' ? dup.tap { |dup| dup.add_self_reference(key, length.to_i - 1) } : self
+    end
+
+    def valid_length?
+      length.nil? || length == '' || length.to_i.positive?
+    end
+
+    def to_hash
+      @hash.each_with_object({}) do |(key, value), hash|
+        key = "#{key}*#{value.length}".to_sym if value.length
+        hash[key] = value.to_hash unless value == self
+      end
+    end
+
+    def add_self_reference(key, length)
+      @hash = @hash.merge(key => self)
+      self.length = length
+    end
+
+    private
+
+    def formulate_hash(include_hash, options)
+      include_hash.each_with_object({}) do |(key, value), hash|
+        rel_name, rel_length = extract_rel_meta(key)
+
+        hash[rel_name] = self.class.new(value, options_with_retain_rel_limit(options)).tap do |directive|
+          directive.add_self_reference(rel_name, rel_length) if key.to_s.match?(/.+\*(\d*)\z/)
+        end
+      end
+    end
+
+    def extract_rel_meta(key)
+      Graphiti::ActiveGraph::Util::Transformers::RelationParam.new(key).split_rel_length(retain_rel_limit)
+    end
+
+    def options_with_retain_rel_limit(options)
+      options.merge(retain_rel_limit:)
+    end
+  end
+end

data/lib/graphiti/active_graph/query.rb

@@ -36,12 +36,39 @@ module Graphiti::ActiveGraph
       []
     end
 
+    def include_directive
+      @include_directive ||= Graphiti::ActiveGraph::JsonapiExt::IncludeDirective.new(@include_param, retain_rel_limit: true)
+    end
+
     def parse_sort_criteria_hash(hash)
       hash.map { |key, value| [key.to_s.split('.').map(&:to_sym), value] }.to_h
     end
 
+    def links?
+      [:json, :xml, 'json', 'xml'].exclude?(params[:format]) && show_resource_links?
+    end
+
+    def pagination_links?
+      action != :find && show_pagination_links?
+    end
+
     private
 
+    def show_pagination_links?
+      return @show_pagination_links unless @show_pagination_links.nil?
+      @show_pagination_links = read_link_params(:pagination_links)
+    end
+
+    def show_resource_links?
+      return @show_resource_links unless @show_resource_links.nil?
+
+      @show_resource_links = read_link_params(:links)
+    end
+
+    def read_link_params(name)
+      ActiveModel::Type::Boolean.new.cast(params[name]) != false
+    end
+
     def sort_criteria(sort)
       sort.split(',').map(&method(:sort_hash)).map(&method(:parse_sort_criteria_hash))
     end

data/lib/graphiti/active_graph/resource.rb

@@ -1,41 +1,52 @@
 module Graphiti
   module ActiveGraph
-    module Resource
-      def relation_resource?
-        config[:relation_resource] || false
+    class Resource < Graphiti::Resource
+      include Extensions::Resources::Authorizationable
+      include Extensions::Resources::PayloadCombinable
+      include Extensions::Resources::Preloadable
+      include Extensions::Resources::Rel
+
+      self.adapter = Adapters::ActiveGraph
+      self.abstract_class = true
+
+      def self.use_uuid
+        define_singleton_method(:inherited) do |klass|
+          super(klass)
+          klass.attribute :id, :uuid
+        end
       end
 
-      def relationship_resource=(value)
-        config[:relation_resource] = value
+      def self.guard_nil_id!(params)
       end
 
-      def with_preloaded_obj(obj, params)
-        id = params[:data].try(:[], :id) || params.delete(:id)
-        params[:filter] ||= {}
-        params[:filter][:id] = id if id
+      def self.extra_attribute?(name)
+        extra_attributes.has_key?(name)
+      end
 
-        build(params, nil, raise_on_missing: false, preloaded: obj)
+      def self.sideload_config(sideload_name)
+        config[:sideloads][sideload_name]
       end
 
-      def all_with_preloaded(obj_arr, params)
-        build(params, nil, single: false, raise_on_missing: false, preloaded: obj_arr)
+      def self.sideload_resource_class(sideload_name)
+        sideload_config(sideload_name)&.resource_class
       end
 
-      def guard_nil_id!(params)
+      def self.custom_eagerload(sideload_name)
+        sideload_config(sideload_name)&.custom_eagerload
       end
 
       def extra_attribute?(name)
-        extra_attributes.has_key?(name)
+        self.class.extra_attribute?(name)
       end
-    end
 
-    module ResourceInstanceMethods
-      def relation_resource?
-        self.class.relation_resource?
+      def build_scope(base, query, opts = {})
+        scoping_class.new(base, self, query, opts)
       end
 
-      def extra_attribute?(name)
-        self.class.extra_attribute?(name)
+      def handle_includes(scope, includes, sorts, **opts)
+        includes_str = JSONAPI::IncludeDirective.new(includes, retain_rel_limit: true).to_string.split(',')
+        options = opts.merge(max_page_size:).merge!(authorize_scope_params)
+        scope.with_ordered_associations(includes_str, sorts, options)
       end
 
       def sideload_name_arr(query)
@@ -68,6 +79,20 @@ module Graphiti
           raise Errors::TypecastFailed.new(self, name, value, e, type_name)
         end
       end
+
+      def authorize_scope_params
+        {}
+      end
+
+      private
+
+      def scoping_class
+        Scope
+      end
+
+      def update_foreign_key(*)
+        true
+      end
     end
   end
 end

data/lib/graphiti/active_graph/{resource → resources}/interface.rb

@@ -1,5 +1,5 @@
 module Graphiti::ActiveGraph
-  module Resource
+  module Resources
     module Interface
       extend ActiveSupport::Concern
       class_methods do

data/lib/graphiti/active_graph/{resource → resources}/persistence.rb

@@ -1,5 +1,5 @@
 module Graphiti::ActiveGraph
-  module Resource
+  module Resources
     module Persistence
       def update(update_params, meta = nil)
         model_instance = nil