rails_audit_log-graphql 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f64cce54638f8999c6489e0881a1fedfcb447b0b5b8f52270a0d8247719c8f19
-  data.tar.gz: 4b1225952a5a6adce3a5a03b804360765b0c70b9ad9a9688db96ba34139430c5
+  metadata.gz: 6ca2df96cd0a69c6449fc8585832293c9a06d487a7525f40c1d15762c61710b5
+  data.tar.gz: 8262257281bef88c4ab07700ec88b5755ca6b2a095fd879bf5462d403ec1ac00
 SHA512:
-  metadata.gz: 0b54b242a022b49d1917dd3c0370f96bde5ec210dad8959a34bc424132c7efd97aa0e1f781cebd0eaf21056b3b29c2c0c9632c08e94a4b0e2da851afe57044e5
-  data.tar.gz: fb448e67961e641eb6ce89081e832082cfa886856ccbd5f4d5de767d1bd21835d38034e6dd55a4d00b1f633f58da6a094e5d8e4e4886c24a6aece095386023f2
+  metadata.gz: 4598525fe46095cbd1209e9bc3af297950526eb9c7ecfab9e382ee3554f376e73b0db3073986d49cdd05190e42f90e1d09e3f1a00c3ecb948a0f02d04f5ba9f0
+  data.tar.gz: 2069e44509afdccf33c443bcf443da4480e83e60034f73bf24b0a7139ab012910d60e17dd85d06897b0642a6e4cb0d0d548a08c6bfbd5ac8318f6bd787d998b3

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.6.0] - 2026-06-04
+
+### Added
+
+- `AuditLogJsonScalar` (`AuditLogJson`) — custom scalar type for `objectChanges`, `object`, and `metadata` fields; replaces the generic `JSON` scalar with a self-documenting type
+- `RecordByIdSource` — `GraphQL::Dataloader::Source` that batch-loads AR records by class name and ID; eliminates N+1 queries when resolving `actor.record` and `auditedResource.record` on list responses
+- `record` field on `AuditLogActor` and `AuditedResource` — returns the database record as JSON, batch-loaded via dataloader
+- `auditLogReify(itemType:, itemId:, at:)` — reconstructs the attribute state of a record at a given point in time; returns `JSON` or `nil` when the record was destroyed or no entry exists
+- `SchemaPlugin` — include into host schema to apply `max_complexity` (200), `max_depth` (10), `default_max_page_size` (25), and `use GraphQL::Dataloader`; all limits configurable via `RailsAuditLog::Graphql.max_complexity=` etc.
+
 ## [0.5.0] - 2026-06-04
 
 ### Added

data/README.md

@@ -23,6 +23,8 @@ A [graphql-ruby](https://graphql-ruby.org) API layer for the [`rails_audit_log`]
     - [auditLogEntriesCount](#auditlogentriescount-int)
     - [Tenant scoping](#tenant-scoping)
   - [Authentication](#authentication)
+  - [SchemaPlugin](#schemaplugin)
+  - [auditLogReify](#auditlogreify)
   - [Subscriptions](#subscriptions)
     - [AuditLogSubscriptionsMixin](#auditlogsubscriptionsmixin)
     - [auditLogEntryCreated](#auditlogentrycreated)
@@ -259,6 +261,51 @@ If no authenticate block is set, all queries are permitted.
 
 [↑ Back to top](#table-of-contents)
 
+### SchemaPlugin
+
+Include `RailsAuditLog::Graphql::SchemaPlugin` into your schema to enable query protection and dataloader batching in one step:
+
+```ruby
+class MySchema < GraphQL::Schema
+  include RailsAuditLog::Graphql::SchemaPlugin
+  query Types::QueryType
+end
+```
+
+This applies the following defaults (all overridable via `RailsAuditLog::Graphql.*=`):
+
+| Setting | Default | Description |
+|---|---|---|
+| `max_complexity` | `200` | Reject queries whose field-complexity sum exceeds this |
+| `max_depth` | `10` | Reject queries nested deeper than this |
+| `default_max_page_size` | `25` | Assumed page size for connection complexity calculation |
+
+Override in an initializer:
+
+```ruby
+RailsAuditLog::Graphql.max_complexity = 500
+RailsAuditLog::Graphql.max_depth = 15
+```
+
+The plugin also adds `AuditLogActor.record` and `AuditedResource.record` fields — nullable JSON fields that load the actual database record via `RecordByIdSource`, a `GraphQL::Dataloader::Source` that batches loads by class name to eliminate N+1 queries on list responses.
+
+[↑ Back to top](#table-of-contents)
+
+### `auditLogReify(itemType:, itemId:, at:): JSON`
+
+Reconstructs the attribute state of a record at a given point in time. Returns the attributes as JSON, or `nil` when no entry exists at or before `at` or the record was destroyed at that time.
+
+```graphql
+{
+  auditLogReify(itemType: "Post", itemId: "42", at: "2026-01-15T12:00:00Z") {
+    title
+    publishedAt
+  }
+}
+```
+
+[↑ Back to top](#table-of-contents)
+
 ### Subscriptions
 
 Requires Action Cable in the host application.

data/ROADMAP.md

@@ -4,15 +4,6 @@ This gem adds a GraphQL API layer on top of [`rails_audit_log`](https://github.c
 
 ---
 
-## 0.6.0 — Performance & Safety
-
-- **Dataloader batch loading** — batch-resolve polymorphic `actor` and `item` associations using graphql-ruby's `dataloader` to eliminate N+1 queries on list responses
-- **`auditLogReify` query** — `auditLogReify(itemType:, itemId:, at:)` returns the reconstructed object state as JSON at a given point in time, backed by `RailsAuditLog.version_at`
-- **Query complexity & depth limits** — built-in defaults (`max_complexity`, `max_depth`) with a config override (`RailsAuditLogGraphql.max_complexity = 200`) to protect against expensive queries before the API is declared stable
-- **`AuditLogJsonScalar`** — proper JSON scalar type for `objectChanges` and `metadata` fields, replacing opaque String serialization and making the schema self-documenting
-
----
-
 ## 1.0.0 — Stable API
 
 - Full YARD documentation

data/lib/rails_audit_log/graphql/queries/audit_log_entries_query_mixin.rb

@@ -58,6 +58,18 @@ module RailsAuditLog
               description: "Scope to a specific tenant ID. Overrides auto-tenant when RailsAuditLog.current_tenant is configured."
           end
 
+          base.field(
+            :audit_log_reify,
+            GraphQL::Types::JSON,
+            null: true,
+            description: "Reconstruct the attribute state of a record at a given point in time. Returns nil when no entry exists at or before `at`, or when the record was destroyed.",
+            resolver_method: :resolve_audit_log_reify
+          ) do
+            argument :item_type, String, required: true, description: "The audited model class name."
+            argument :item_id, GraphQL::Types::ID, required: true, description: "The audited record ID."
+            argument :at, GraphQL::Types::ISO8601DateTime, required: true, description: "Reconstruct state as of this time."
+          end
+
           base.field(
             :audit_log_entries_count,
             GraphQL::Types::Int,
@@ -89,6 +101,18 @@ module RailsAuditLog
           build_scope(event: event, item_type: item_type, item_id: item_id, actor_id: actor_id, since: since, until_time: until_time, touching: touching, order_by: order_by, for_tenant: for_tenant)
         end
 
+        def resolve_audit_log_reify(item_type:, item_id:, at:)
+          check_authentication!
+          entry = RailsAuditLog::AuditLogEntry
+            .where(item_type: item_type, item_id: item_id)
+            .where("created_at <= ?", at)
+            .order(created_at: :desc, id: :desc)
+            .first
+          return nil if entry.nil? || entry.event == "destroy"
+          to_attrs = (entry.object_changes || {}).transform_values { |v| v[1] }
+          entry.object.present? ? entry.object.merge(to_attrs) : to_attrs
+        end
+
         def resolve_audit_log_entries_count(event: nil, item_type: nil, since: nil)
           check_authentication!
           scope = RailsAuditLog::AuditLogEntry.all

data/lib/rails_audit_log/graphql/schema_plugin.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module RailsAuditLog
+  module Graphql
+    module SchemaPlugin
+      def self.included(base)
+        base.max_complexity(RailsAuditLog::Graphql.max_complexity)
+        base.max_depth(RailsAuditLog::Graphql.max_depth)
+        base.default_max_page_size(RailsAuditLog::Graphql.default_max_page_size)
+        base.use(GraphQL::Dataloader)
+      end
+    end
+  end
+end

data/lib/rails_audit_log/graphql/sources/record_by_id_source.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module RailsAuditLog
+  module Graphql
+    module Sources
+      class RecordByIdSource < GraphQL::Dataloader::Source
+        def initialize(class_name)
+          @class_name = class_name
+        end
+
+        def fetch(ids)
+          klass = @class_name.safe_constantize
+          return ids.map { nil } unless klass
+
+          records = klass.where(id: ids).index_by { |r| r.id.to_s }
+          ids.map { |id| records[id]&.attributes }
+        end
+      end
+    end
+  end
+end

data/lib/rails_audit_log/graphql/types/actor_type.rb

@@ -9,6 +9,8 @@ module RailsAuditLog
 
         field :id, GraphQL::Types::ID, null: false, description: "The actor's ID."
         field :type_name, String, null: false, description: "The actor's model class name (e.g. \"User\")."
+        field :record, GraphQL::Types::JSON, null: true,
+          description: "The actor record loaded from the database, serialized as JSON. Batch-loaded via dataloader."
 
         def id
           object[:id]
@@ -17,6 +19,11 @@ module RailsAuditLog
         def type_name
           object[:type_name]
         end
+
+        def record
+          return nil unless object[:id] && object[:type_name]
+          dataloader.with(Sources::RecordByIdSource, object[:type_name]).load(object[:id].to_s)
+        end
       end
     end
   end

data/lib/rails_audit_log/graphql/types/audit_log_entry_type.rb

@@ -11,9 +11,9 @@ module RailsAuditLog
         field :event, String, null: false
         field :item_type, String, null: false
         field :item_id, GraphQL::Types::ID, null: false
-        field :object_changes, GraphQL::Types::JSON, null: true
-        field :object, GraphQL::Types::JSON, null: true, method_conflict_warning: false
-        field :metadata, GraphQL::Types::JSON, null: true
+        field :object_changes, Types::AuditLogJsonScalar, null: true
+        field :object, Types::AuditLogJsonScalar, null: true, method_conflict_warning: false
+        field :metadata, Types::AuditLogJsonScalar, null: true
         field :reason, String, null: true
         field :whodunnit_snapshot, String, null: true
         field :actor_type, String, null: true

data/lib/rails_audit_log/graphql/types/audit_log_json_scalar.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RailsAuditLog
+  module Graphql
+    module Types
+      class AuditLogJsonScalar < GraphQL::Schema::Scalar
+        graphql_name "AuditLogJson"
+        description "A JSON blob stored on an audit log entry (objectChanges, object, or metadata)."
+
+        def self.coerce_input(value, _ctx)
+          value.is_a?(Hash) ? value : JSON.parse(value)
+        rescue JSON::ParserError
+          raise GraphQL::CoercionError, "#{value.inspect} is not valid JSON"
+        end
+
+        def self.coerce_result(value, _ctx)
+          value
+        end
+      end
+    end
+  end
+end

data/lib/rails_audit_log/graphql/types/audited_resource_type.rb

@@ -9,6 +9,8 @@ module RailsAuditLog
 
         field :id, GraphQL::Types::ID, null: false, description: "The audited record's ID."
         field :type_name, String, null: false, description: "The audited model class name (e.g. \"Post\")."
+        field :record, GraphQL::Types::JSON, null: true,
+          description: "The audited record loaded from the database, serialized as JSON. Batch-loaded via dataloader."
 
         def id
           object[:id]
@@ -17,6 +19,10 @@ module RailsAuditLog
         def type_name
           object[:type_name]
         end
+
+        def record
+          dataloader.with(Sources::RecordByIdSource, object[:type_name]).load(object[:id].to_s)
+        end
       end
     end
   end

data/lib/rails_audit_log/graphql/version.rb

@@ -2,6 +2,6 @@
 
 module RailsAuditLog
   module Graphql
-    VERSION = "0.5.0"
+    VERSION = "0.6.0"
   end
 end

data/lib/rails_audit_log/graphql.rb

@@ -4,6 +4,7 @@ require "graphql"
 require_relative "graphql/version"
 require_relative "graphql/types/base_object"
 require_relative "graphql/types/base_subscription"
+require_relative "graphql/types/audit_log_json_scalar"
 require_relative "graphql/types/diff_type"
 require_relative "graphql/types/actor_type"
 require_relative "graphql/types/audited_resource_type"
@@ -11,13 +12,23 @@ require_relative "graphql/types/audit_log_entry_type"
 require_relative "graphql/types/sort_direction_enum"
 require_relative "graphql/types/audit_log_entry_sort_field_enum"
 require_relative "graphql/input_objects/audit_log_entry_sort_input"
+require_relative "graphql/sources/record_by_id_source"
 require_relative "graphql/queries/audit_log_entries_query_mixin"
 require_relative "graphql/subscriptions/audit_log_entry_created"
 require_relative "graphql/subscriptions/audit_log_subscriptions_mixin"
 require_relative "graphql/subscriptions/broadcaster"
+require_relative "graphql/schema_plugin"
 
 module RailsAuditLog
   module Graphql
     class Error < StandardError; end
+
+    @max_complexity = 200
+    @max_depth = 10
+    @default_max_page_size = 25
+
+    class << self
+      attr_accessor :max_complexity, :max_depth, :default_max_page_size
+    end
   end
 end

data/sig/rails_audit_log/graphql.rbs

@@ -2,6 +2,17 @@ module RailsAuditLog
   module Graphql
     VERSION: String
 
+    @max_complexity: Integer
+    @max_depth: Integer
+    @default_max_page_size: Integer
+
+    def self.max_complexity: () -> Integer
+    def self.max_complexity=: (Integer) -> Integer
+    def self.max_depth: () -> Integer
+    def self.max_depth=: (Integer) -> Integer
+    def self.default_max_page_size: () -> Integer
+    def self.default_max_page_size=: (Integer) -> Integer
+
     module Types
       class BaseObject < GraphQL::Schema::Object
       end
@@ -9,6 +20,11 @@ module RailsAuditLog
       class BaseSubscription < GraphQL::Schema::Subscription
       end
 
+      class AuditLogJsonScalar < GraphQL::Schema::Scalar
+        def self.coerce_input: (untyped value, untyped ctx) -> Hash[String, untyped]
+        def self.coerce_result: (untyped value, untyped ctx) -> untyped
+      end
+
       class DiffType < BaseObject
         def attribute: () -> String
         def from: () -> untyped
@@ -18,11 +34,13 @@ module RailsAuditLog
       class ActorType < BaseObject
         def id: () -> String
         def type_name: () -> String
+        def record: () -> Hash[String, untyped]?
       end
 
       class AuditedResourceType < BaseObject
         def id: () -> String
         def type_name: () -> String
+        def record: () -> Hash[String, untyped]?
       end
 
       class AuditLogEntryType < BaseObject
@@ -54,6 +72,17 @@ module RailsAuditLog
       end
     end
 
+    module Sources
+      class RecordByIdSource < GraphQL::Dataloader::Source
+        def initialize: (String class_name) -> void
+        def fetch: (Array[String] ids) -> Array[Hash[String, untyped]?]
+      end
+    end
+
+    module SchemaPlugin
+      def self.included: (untyped base) -> void
+    end
+
     module Subscriptions
       class AuditLogEntryCreated < Types::BaseSubscription
         def subscribe: (?item_type: String?, ?item_id: String?, ?actor_id: String?) -> :no_response
@@ -104,6 +133,12 @@ module RailsAuditLog
           ?for_tenant: String?
         ) -> untyped
 
+        def resolve_audit_log_reify: (
+          item_type: String,
+          item_id: String,
+          at: Time
+        ) -> Hash[String, untyped]?
+
         def resolve_audit_log_entries_count: (
           ?event: String?,
           ?item_type: String?,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_audit_log-graphql
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -86,12 +86,15 @@ files:
 - lib/rails_audit_log/graphql/input_objects/audit_log_entry_sort_input.rb
 - lib/rails_audit_log/graphql/queries/audit_log_entries_query_mixin.rb
 - lib/rails_audit_log/graphql/release_tooling.rb
+- lib/rails_audit_log/graphql/schema_plugin.rb
+- lib/rails_audit_log/graphql/sources/record_by_id_source.rb
 - lib/rails_audit_log/graphql/subscriptions/audit_log_entry_created.rb
 - lib/rails_audit_log/graphql/subscriptions/audit_log_subscriptions_mixin.rb
 - lib/rails_audit_log/graphql/subscriptions/broadcaster.rb
 - lib/rails_audit_log/graphql/types/actor_type.rb
 - lib/rails_audit_log/graphql/types/audit_log_entry_sort_field_enum.rb
 - lib/rails_audit_log/graphql/types/audit_log_entry_type.rb
+- lib/rails_audit_log/graphql/types/audit_log_json_scalar.rb
 - lib/rails_audit_log/graphql/types/audited_resource_type.rb
 - lib/rails_audit_log/graphql/types/base_object.rb
 - lib/rails_audit_log/graphql/types/base_subscription.rb