graphql_relay_identifier 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 56aa2e3f2f181b151ea6e740ccb5c5aec1668585b9e6d6bff687af76bc7ae29c
+  data.tar.gz: 67aec04391bd3f0513df0e26a47f84430555cb2af07620422a6e03d2b3703007
+SHA512:
+  metadata.gz: b721ad621ccb01c5409d5a7c38464c5ff8eefbea2b4715e6e5161a4b8934e209350f598f6b7811875b6e07632f43930631a4e1d57289ecceccc205fdf5e63bb5
+  data.tar.gz: 7aa148816743945383413b9de8113c743cf70c6be06a7ddc873c3349e3bc5afae4567615815ff256d623631a8963956d11493a0631971204bf2a2771dc81660a

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-06-19
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Mark Faga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,120 @@
+# GraphQL::Relay::Identifier
+
+This gem provides an implementation the Relay Global Object Identification specification in Ruby,
+ensuring compatibility with GraphQL Federation. It allows you to define and resolve global
+identifiers for your GraphQL objects, making it easier to work with Relay and GraphQL Federation in
+your applications.
+
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem 'graphql_relay_identifier', require: 'graphql/relay/identifier/global_object_identifier'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install graphql_relay_identifier
+```
+
+## Usage
+
+1. Update your schema to overide the `id_from_object` and `object_from_id` methods and use the
+   `GraphQL::Relay::Identifier::GlobalObjectIdentifier` module to handle global identifiers.
+
+   ```ruby
+   class ApplicationSchema < GraphQL::Schema
+     # ... other configuration
+
+     def self.id_from_object(object, type, _query_ctx)
+       GraphQL::Relay::Identifier::GlobalObjectIdentifier.to_relay_id(object, type)
+     end
+
+     def self.object_from_id(node_id, _query_ctx)
+       GraphQL::Relay::Identifier::GlobalObjectIdentifier.from_relay_id(node_id)
+     end
+   end
+   ```
+
+2. _RECOMMENDED_: Set the `GraphQL::Schema::UniqueWithinType.default_id_separator` to a `:` (colon).
+   This is used to deliminate the GraphQL type name from the identifier fields in the global object
+   identifier.
+
+   ```ruby
+   # config/initializers/graphql.rb
+    GraphQL::Schema::UniqueWithinType.default_id_separator = ':'
+   ```
+
+3. _ADVANCED CONFIGURATION_: Introduce an initializer to set up any custom identifier configurations
+   for your models and types, as needed.
+
+   _NOTE: This is only necessary if you have models that do not use the default `id` field as their
+   primary key._
+
+   ```ruby
+   # config/initializers/graphql_relay_identifier.rb
+   GraphQL::Relay::Identifier::GlobalObjectIdentifier.add_identifier 'BlogPost', :slug
+   GraphQL::Relay::Identifier::GlobalObjectIdentifier.add_identifier 'ModelWithComplexKey', :field1, :field2,
+   GraphQL::Relay::Identifier::GlobalObjectIdentifier.add_identifier 'ModelWithVirtualAttribute', :id, virtual_attribute_names: %i[some_virtual_attribute]
+   ```
+
+### `GraphQL::Relay::Identifier::GlobalObjectIdentifier.add_identifier`
+
+This method allows you to define a global identifier for a specific model when the default (`id`) is
+not suitable.
+
+You can specify one or more fields to be used as the identifier, and optionally, you can define
+virtual attributes that should be included in the identifier. Virtual attributes are not persisted
+in the database but play a role in how a model instance behaves and is identified.
+
+### Format of a GraphQL Relay Identifier
+
+Suppose you have a model `BlogPost` with a `slug` field that is used as the primary key for the
+model. Assuming the GraphQL Type for this model is `BlogPost`, the identifier for a specific
+instance of this model with a `slug` value of `my-awesome-blog-post` would be represented as:
+
+```
+Base64.strict_encode64('BlogPost:{"v":1,"klass":"BlogPost","slug":"my-awesome-blog-post"}')
+```
+
+This identifier can be used in GraphQL queries to uniquely identify the `BlogPost` instance with:
+
+- An encoding version of 1 (the default version)
+- A model name of `BlogPost`
+- A single field `slug` with the unique value `my-awesome-blog-post`
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run
+the tests. You can also run `bin/console` for an interactive prompt that will allow you to
+experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new
+version, update the version number in `version.rb`, and then run `bundle exec rake release`, which
+will create a git tag for the version, push git commits and the created tag, and push the `.gem`
+file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/mjfaga/graphql_relay_identifier. This project is intended to be a safe, welcoming
+space for collaboration, and contributors are expected to adhere to the
+[code of conduct](https://github.com/mjfaga/graphql_relay_identifier/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](./LICENSE.txt).
+
+## Code of Conduct
+
+Everyone interacting in the GraphQL::Relay::Identifier project's codebases, issue trackers, chat
+rooms and mailing lists is expected to follow the
+[code of conduct](https://github.com/mjfaga/graphql_relay_identifier/blob/main/CODE_OF_CONDUCT.md).

data/lib/graphql/relay/identifier/global_object_identifier.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "graphql"
+
+module GraphQL
+  module Relay
+    module Identifier
+      # GlobalObjectIdentifier is a utility class that provides a way to create and manage unique identifiers for
+      # entities implementing a Node in a GraphQL schema.
+      #
+      # This implementation is ORM-agnostic but assumes certain methods like find_by! are available
+      # on your model classes. You may need to customize the find method based on your actual ORM.
+      class GlobalObjectIdentifier
+        class << self
+          private
+
+          def identifiers
+            @identifiers ||= Hash.new { |h, klass| h[klass] = Identifier.build_for(klass) }
+          end
+
+          attr_writer :identifiers
+        end
+
+        # Identifier is a class that represents a unique identifier for a specific class in the GraphQL schema.
+        class Identifier
+          class << self
+            attr_writer :attribute_names, :virtual_attribute_names, :version
+
+            attr_accessor :klass
+
+            def attribute_names
+              @attribute_names ||= %i[id]
+            end
+
+            def version
+              @version ||= 1
+            end
+
+            def virtual_attribute_names
+              @virtual_attribute_names ||= %i[]
+            end
+          end
+
+          def self.as_json(object)
+            attributes = attribute_names.each_with_object({}) do |key, hash|
+              hash[key] = object.public_send(key)
+              hash
+            end
+            virtual_attributes = virtual_attribute_names.each_with_object({}) do |key, hash|
+              hash[key] = object.public_send(key)
+              hash
+            end
+
+            {
+              v: version,
+              klass:,
+              **attributes,
+              **virtual_attributes
+            }
+          end
+
+          def self.build_for(klass, *args)
+            const_set(klass.gsub("::", ""), Class.new(self)).tap do |identifier_class|
+              attribute_names = []
+              virtual_attribute_names = []
+              args.each do |attribute_name|
+                if attribute_name.is_a?(Symbol)
+                  attribute_names << attribute_name
+                elsif attribute_name.is_a?(Hash) && attribute_name.key?(:virtual_attribute_names)
+                  virtual_attr_names = attribute_name[:virtual_attribute_names]
+                  virtual_attr_names = [virtual_attr_names] unless virtual_attr_names.is_a?(Array)
+                  virtual_attr_names.each do |inner_attribute_name|
+                    virtual_attribute_names << inner_attribute_name
+                  end
+                end
+              end
+
+              identifier_class.klass = klass
+              identifier_class.attribute_names = attribute_names unless attribute_names.empty?
+              identifier_class.virtual_attribute_names = virtual_attribute_names unless virtual_attribute_names.empty?
+              identifier_class.define_attribute_methods
+            end
+          end
+
+          def self.define_attribute_methods
+            attribute_names.each do |attribute_name|
+              define_method(attribute_name) { @hash[attribute_name.to_s] }
+            end
+
+            virtual_attribute_names.each do |attribute_name|
+              define_method(attribute_name) { @hash[attribute_name.to_s] }
+            end
+          end
+
+          def self.remove_for(klass)
+            remove_const(klass.gsub("::", ""))
+          end
+
+          def initialize(hash)
+            @hash = hash
+          end
+
+          def attributes
+            self.class.attribute_names.each_with_object({}) do |key, hash|
+              hash[key] = public_send(key)
+              hash
+            end
+          end
+
+          def find
+            # Convert string class name to actual constant
+            klass_constant = self.class.klass.split("::").inject(Object) do |mod, class_name|
+              mod.const_get(class_name)
+            end
+
+            # This implementation assumes the class has a find_by! method that accepts
+            # attributes as keyword arguments. If using a different ORM or data access
+            # pattern, you'll need to customize this method.
+            instance = klass_constant.find_by!(**attributes)
+
+            # Assign virtual attributes if any exist
+            unless virtual_attributes.empty?
+              virtual_attributes.each do |key, value|
+                instance.public_send("#{key}=", value) if instance.respond_to?("#{key}=")
+              end
+            end
+
+            instance
+          end
+
+          def virtual_attributes
+            self.class.virtual_attribute_names.each_with_object({}) do |key, hash|
+              hash[key] = public_send(key)
+              hash
+            end
+          end
+        end
+
+        class << self
+          def add_identifier(klass, *attribute_names)
+            identifiers[klass] = Identifier.build_for(klass, *attribute_names)
+          end
+
+          def from_relay_id(node_id)
+            parse(node_id)&.find
+          end
+
+          def parse(node_id)
+            _typename, json = GraphQL::Schema::UniqueWithinType.decode(node_id)
+
+            return unless json
+
+            hash = JSON.parse(json)
+            klass = hash["klass"]
+
+            identifiers[klass].new(hash)
+          rescue JSON::ParserError, GraphQL::ExecutionError
+            nil
+          end
+
+          def remove_identifier(klass)
+            identifiers.delete(klass)
+            Identifier.remove_for(klass)
+          end
+
+          def to_relay_id(object, type)
+            unsafe_to_relay_id(object, graphql_name: type.graphql_name, object_class_name: object.class.name)
+          end
+
+          def unsafe_to_relay_id(object, graphql_name:, object_class_name:)
+            # This allows us to get relay ids for types without having to access the GraphQL type, but without the safety
+            # or consistency of the GraphQL type. Used by external callers (e.g. the API) to generate relay ids.
+            GraphQL::Schema::UniqueWithinType.encode(
+              graphql_name,
+              identifiers[object_class_name].as_json(object).to_json
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/relay/identifier/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Relay
+    module Identifier
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/graphql/relay/identifier.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Relay
+    # Library module for GraphQL Relay Identifier
+    module Identifier
+    end
+  end
+end

data/lib/graphql_relay_identifier.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "graphql/relay/identifier/global_object_identifier"

data/sig/graphql/relay/identifier/global_object_identifier.rbs

@@ -0,0 +1,42 @@
+module GraphQL
+  module Relay
+    module Identifier
+      class GlobalObjectIdentifier
+        # Class methods
+        def self.add_identifier: (String klass, *Symbol | Hash[Symbol, Array[Symbol] | Symbol] attribute_names) -> Identifier
+        def self.from_relay_id: (String node_id) -> untyped
+        def self.parse: (String node_id) -> Identifier?
+        def self.remove_identifier: (String klass) -> void
+        def self.to_relay_id: (untyped object, untyped type) -> String
+        def self.unsafe_to_relay_id: (untyped object, graphql_name: String, object_class_name: String) -> String
+
+        private
+        def self.identifiers: () -> Hash[String, Identifier]
+        def self.identifiers=: (Hash[String, Identifier]) -> void
+
+        # Identifier class
+        class Identifier
+          # Class methods
+          def self.attribute_names: () -> Array[Symbol]
+          def self.attribute_names=: (Array[Symbol]) -> void
+          def self.version: () -> Integer
+          def self.version=: (Integer) -> void
+          def self.virtual_attribute_names: () -> Array[Symbol]
+          def self.virtual_attribute_names=: (Array[Symbol]) -> void
+          def self.klass: () -> String
+          def self.klass=: (String) -> void
+          def self.as_json: (untyped object) -> Hash[Symbol | String, untyped]
+          def self.build_for: (String klass, *Symbol | Hash[Symbol, Array[Symbol] | Symbol]) -> Identifier
+          def self.define_attribute_methods: () -> void
+          def self.remove_for: (String klass) -> void
+
+          # Instance methods
+          def initialize: (Hash[String, untyped] hash) -> void
+          def attributes: () -> Hash[Symbol, untyped]
+          def find: () -> untyped
+          def virtual_attributes: () -> Hash[Symbol, untyped]
+        end
+      end
+    end
+  end
+end

data/sig/graphql/relay/identifier.rbs

@@ -0,0 +1,7 @@
+module GraphQL
+  module Relay
+    module Identifier
+      VERSION: String
+    end
+  end
+end

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification
+name: graphql_relay_identifier
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mark Faga
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: graphql
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: This gem provides an implementation the Relay Global Object Identification
+  specification in Ruby, ensuring compatibility with GraphQL Federation. It allows
+  you to define and resolve global identifiers for your GraphQL objects, making it
+  easier to work with Relay and Federation in your applications.
+email:
+- mjfaga@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/graphql/relay/identifier.rb
+- lib/graphql/relay/identifier/global_object_identifier.rb
+- lib/graphql/relay/identifier/version.rb
+- lib/graphql_relay_identifier.rb
+- sig/graphql/relay/identifier.rbs
+- sig/graphql/relay/identifier/global_object_identifier.rbs
+homepage: https://github.com/mjfaga/graphql_relay_identifier
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/mjfaga/graphql_relay_identifier
+  source_code_uri: https://github.com/mjfaga/graphql_relay_identifier
+  changelog_uri: https://github.com/mjfaga/graphql_relay_identifier/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/mjfaga/graphql_relay_identifier/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: A GraphQL Relay Global Object Identification implementation for Ruby that
+  is Federation compatible.
+test_files: []