Enhance as_json for pointer collections and objects

Adds support for the :pointers_only option to PointerCollectionProxy#as_json, allowing serialization of full objects or pointers as needed. Parse::Object#as_json now always includes identification fields (objectId, className, __type, id) when using :only, unless :strict is true. Introduces :exclude as an alias for :except in as_json. Updates tests to cover new behaviors and documents changes in the changelog. Bumps version to 3.2.3.

Author: AdrianCurtin

CHANGELOG.md

@@ -1,5 +1,54 @@
 ## Parse-Stack Changelog
 
+### 3.2.3
+
+#### Improvements
+
+- **IMPROVED**: `PointerCollectionProxy#as_json` now supports the `pointers_only` option. By default it returns pointers (preserving backward compatibility), but you can set `pointers_only: false` to serialize objects with their fetched fields. This is useful when returning `has_many :through => :array` relationships in webhook responses.
+
+  When `pointers_only: false`:
+  - Partially hydrated objects serialize only their fetched fields (no autofetch triggered)
+  - Pointer-only objects (unfetched) remain as pointers
+  - Fully hydrated objects serialize all their fields
+
+```ruby
+# Default behavior - pointers for storage (backward compatible)
+capture.assets.as_json
+# => [{"__type"=>"Pointer", "className"=>"Asset", "objectId"=>"abc"}, ...]
+
+# Serialize with fetched fields (no autofetch, pointers stay as pointers)
+capture.assets.as_json(pointers_only: false)
+# => [{"objectId"=>"abc", "file"=>{...}, "caption"=>"My photo", ...}, ...]
+
+# In webhooks, manually override assets serialization:
+cloud_results.map do |capture|
+  json = capture.as_json
+  json['assets'] = capture.assets.as_json(pointers_only: false) if capture.assets.any?
+  json
+end
+```
+
+- **IMPROVED**: `Parse::Object#as_json` with `:only` option now automatically includes identification fields (`objectId`, `className`, `__type`, `id`) so serialized objects can always be properly identified. Use `strict: true` to disable this behavior for pure strict filtering.
+
+```ruby
+# Default: identification fields are always included
+song.as_json(only: [:title, :artist])
+# => {"objectId"=>"abc", "className"=>"Song", "__type"=>"Object", "title"=>"...", "artist"=>"..."}
+
+# With strict: true, only exactly specified fields are included
+song.as_json(only: [:title, :artist], strict: true)
+# => {"title"=>"...", "artist"=>"..."}
+```
+
+- **NEW**: Added `:exclude` as an alias for `:except` in `as_json` for more intuitive field exclusion.
+
+```ruby
+# All three are equivalent:
+song.as_json(except: [:acl, :created_at])
+song.as_json(exclude_keys: [:acl, :created_at])
+song.as_json(exclude: [:acl, :created_at])
+```
+
 ### 3.2.2
 
 #### Improvements

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    parse-stack (3.2.1)
+    parse-stack (3.2.3)
       activemodel (>= 5, < 9)
       activesupport (>= 5, < 9)
       faraday (~> 2.0)

lib/parse/model/associations/pointer_collection_proxy.rb

@@ -96,9 +96,39 @@ def fetch
       collection.fetch_objects
     end
 
-    # Encode the collection as a JSON object of Parse::Pointers.
+    # Encode the collection as JSON.
+    # By default, returns Parse::Pointers for backward compatibility when saving.
+    # Set `pointers_only: false` to get full hydrated objects for API responses.
+    # @param opts [Hash] options for serialization
+    # @option opts [Boolean] :pointers_only (true) When true (default), converts all
+    #   Parse objects to pointer format. Set to false to serialize full objects.
+    # @option opts [Boolean] :only_fetched (true) When true (default when pointers_only
+    #   is false), only serialize fields that were actually fetched. This prevents
+    #   autofetch from being triggered during serialization of partially hydrated objects.
+    # @example Default - pointers for storage
+    #   capture.assets.as_json
+    #   # => [{"__type"=>"Pointer", "className"=>"Asset", "objectId"=>"abc"}, ...]
+    # @example Full objects for API responses (only fetched fields, no autofetch)
+    #   capture.assets.as_json(pointers_only: false)
+    #   # => [{"objectId"=>"abc", "file"=>{...}, "caption"=>"...", ...}, ...]
     def as_json(opts = nil)
-      parse_pointers.as_json(opts)
+      opts ||= {}
+
+      # Normalize string keys to symbols to avoid conflicts with defaults
+      opts = opts.transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
+
+      # Check if pointers_only was explicitly set, otherwise default to true
+      pointers_only = opts.fetch(:pointers_only, true)
+
+      # Default to pointers_only: true for backward compatibility
+      # When pointers_only is false, default only_fetched to true to prevent
+      # autofetch during serialization of partially hydrated objects
+      defaults = { pointers_only: true }
+      unless pointers_only
+        defaults[:only_fetched] = true unless opts.key?(:only_fetched)
+      end
+      opts = defaults.merge(opts)
+      super(opts)
     end
   end
 end

lib/parse/model/object.rb

@@ -733,20 +733,41 @@ def self.roles_for_user(user)
 
     # @!endgroup
 
+    # Core identification fields that are always included in serialization
+    # unless strict: true is specified
+    IDENTIFICATION_FIELDS = %w[id objectId __type className].freeze
+
     # @return [Hash] a json-hash representing this object.
     # @param opts [Hash] options for serialization
     # @option opts [Boolean] :only_fetched when true (or when Parse.serialize_only_fetched_fields
     #   is true and this option is not explicitly set to false), only serialize fields that
     #   were fetched for partially fetched objects. This prevents autofetch during serialization.
-    # @option opts [Array<Symbol,String>] :only limit serialization to these fields
+    # @option opts [Array<Symbol,String>] :only limit serialization to these fields. By default,
+    #   identification fields (objectId, className, __type, id) are always included for proper
+    #   object identification. Use strict: true to disable this behavior.
     # @option opts [Array<Symbol,String>] :except exclude these fields from serialization
     # @option opts [Array<Symbol,String>] :exclude_keys alias for :except
+    # @option opts [Array<Symbol,String>] :exclude alias for :except
+    # @option opts [Boolean] :strict when true with :only, performs strict filtering without
+    #   automatically including identification fields. Default is false.
     def as_json(opts = nil)
       opts ||= {}
 
-      # Normalize :exclude_keys to :except (alias support)
-      if opts[:exclude_keys] && !opts[:except]
-        opts = opts.merge(except: opts[:exclude_keys])
+      # Normalize :exclude_keys and :exclude to :except (alias support)
+      if !opts[:except]
+        if opts[:exclude_keys]
+          opts = opts.merge(except: opts[:exclude_keys])
+        elsif opts[:exclude]
+          opts = opts.merge(except: opts[:exclude])
+        end
+      end
+
+      # When :only is specified without :strict, automatically include identification fields
+      # so the serialized object can be properly identified
+      if opts[:only] && !opts[:strict]
+        only_keys = Array(opts[:only]).map(&:to_s)
+        only_keys |= IDENTIFICATION_FIELDS
+        opts = opts.merge(only: only_keys)
       end
 
       # For selectively fetched objects (partial fetch), serialize only the fetched fields.
@@ -764,7 +785,8 @@ def as_json(opts = nil)
           # Use the local field names which match the attribute methods
           only_keys = fetched_keys.map(&:to_s)
           # Always include Parse metadata fields for proper object identification
-          only_keys |= %w[id objectId __type className created_at updated_at]
+          only_keys |= IDENTIFICATION_FIELDS
+          only_keys |= %w[created_at updated_at]
           opts = opts.merge(only: only_keys)
         end
 

lib/parse/stack/version.rb

@@ -6,6 +6,6 @@ module Parse
   # The Parse Server SDK for Ruby
   module Stack
     # The current version.
-    VERSION = "3.2.2"
+    VERSION = "3.2.3"
   end
 end

test/lib/parse/collection_proxy_as_json_test.rb

@@ -170,3 +170,204 @@ def test_as_json_pointers_only_with_string_key
     assert_equal "Pointer", result[0]["__type"]
   end
 end
+
+# Test model for pointer collection proxy testing with has_many :through => :array
+class PointerCollectionTestCapture < Parse::Object
+  parse_class "PointerCollectionTestCapture"
+  property :title, :string
+  has_many :assets, through: :array, as: :pointer_collection_test_asset
+end
+
+class PointerCollectionTestAsset < Parse::Object
+  parse_class "PointerCollectionTestAsset"
+  property :caption, :string
+  property :file_url, :string
+  property :thumbnail_url, :string
+end
+
+class PointerCollectionProxyAsJsonTest < Minitest::Test
+  def setup
+    # Create "fetched" objects with timestamps (not pointer state)
+    @asset1 = PointerCollectionTestAsset.new(
+      "objectId" => "asset123",
+      "caption" => "Photo 1",
+      "fileUrl" => "https://example.com/photo1.jpg",
+      "thumbnailUrl" => "https://example.com/thumb1.jpg",
+      "createdAt" => "2024-01-01T00:00:00.000Z",
+      "updatedAt" => "2024-01-01T00:00:00.000Z"
+    )
+    @asset2 = PointerCollectionTestAsset.new(
+      "objectId" => "asset456",
+      "caption" => "Photo 2",
+      "fileUrl" => "https://example.com/photo2.jpg",
+      "thumbnailUrl" => "https://example.com/thumb2.jpg",
+      "createdAt" => "2024-01-01T00:00:00.000Z",
+      "updatedAt" => "2024-01-01T00:00:00.000Z"
+    )
+    @pointer_only = PointerCollectionTestAsset.new("asset789") # Pointer-only (just objectId)
+  end
+
+  # === Default behavior (backward compatible - returns pointers) ===
+
+  def test_as_json_default_returns_pointers
+    proxy = Parse::PointerCollectionProxy.new([@asset1, @asset2])
+
+    result = proxy.as_json
+
+    # Default: should return pointers for backward compatibility
+    assert_equal 2, result.length
+    result.each do |item|
+      assert_equal "Pointer", item["__type"]
+      assert_equal "PointerCollectionTestAsset", item["className"]
+    end
+  end
+
+  def test_as_json_default_with_single_object
+    proxy = Parse::PointerCollectionProxy.new([@asset1])
+
+    result = proxy.as_json
+
+    assert_equal 1, result.length
+    assert_equal "Pointer", result[0]["__type"]
+    assert_equal "PointerCollectionTestAsset", result[0]["className"]
+    assert_equal "asset123", result[0]["objectId"]
+  end
+
+  # === pointers_only: false (serialize full objects) ===
+
+  def test_as_json_pointers_only_false_returns_full_objects
+    proxy = Parse::PointerCollectionProxy.new([@asset1, @asset2])
+
+    result = proxy.as_json(pointers_only: false)
+
+    # Should serialize full objects, not pointers
+    assert_equal 2, result.length
+    result.each do |item|
+      assert item.is_a?(Hash)
+      # Should NOT have __type: Pointer
+      refute_equal "Pointer", item["__type"]
+      # Should have objectId
+      assert item["objectId"].present?
+    end
+  end
+
+  def test_as_json_pointers_only_false_includes_fetched_fields
+    proxy = Parse::PointerCollectionProxy.new([@asset1])
+
+    result = proxy.as_json(pointers_only: false)
+
+    assert_equal 1, result.length
+    item = result[0]
+
+    # Should include the fields that were set
+    assert_equal "asset123", item["objectId"]
+    assert_equal "Photo 1", item["caption"]
+    assert_equal "https://example.com/photo1.jpg", item["fileUrl"]
+    assert_equal "https://example.com/thumb1.jpg", item["thumbnailUrl"]
+  end
+
+  def test_as_json_pointers_only_false_with_pointer_only_object_returns_pointer
+    proxy = Parse::PointerCollectionProxy.new([@pointer_only])
+
+    result = proxy.as_json(pointers_only: false)
+
+    # Pointer-only objects should still return as pointers
+    assert_equal 1, result.length
+    item = result[0]
+    assert_equal "Pointer", item["__type"]
+    assert_equal "PointerCollectionTestAsset", item["className"]
+    assert_equal "asset789", item["objectId"]
+  end
+
+  def test_as_json_pointers_only_false_mixed_hydrated_and_pointers
+    proxy = Parse::PointerCollectionProxy.new([@asset1, @pointer_only, @asset2])
+
+    result = proxy.as_json(pointers_only: false)
+
+    assert_equal 3, result.length
+
+    # First item: hydrated object
+    assert_equal "asset123", result[0]["objectId"]
+    assert_equal "Photo 1", result[0]["caption"]
+    refute_equal "Pointer", result[0]["__type"]
+
+    # Second item: pointer-only, should remain a pointer
+    assert_equal "Pointer", result[1]["__type"]
+    assert_equal "asset789", result[1]["objectId"]
+
+    # Third item: hydrated object
+    assert_equal "asset456", result[2]["objectId"]
+    assert_equal "Photo 2", result[2]["caption"]
+    refute_equal "Pointer", result[2]["__type"]
+  end
+
+  # === pointers_only: true (explicit) ===
+
+  def test_as_json_pointers_only_true_returns_pointers
+    proxy = Parse::PointerCollectionProxy.new([@asset1, @asset2])
+
+    result = proxy.as_json(pointers_only: true)
+
+    assert_equal 2, result.length
+    result.each do |item|
+      assert_equal "Pointer", item["__type"]
+    end
+  end
+
+  # === only_fetched option (prevents autofetch) ===
+
+  def test_as_json_pointers_only_false_defaults_only_fetched_true
+    # Create a partially fetched object by setting selective keys
+    partial_asset = PointerCollectionTestAsset.new(
+      "objectId" => "partial123",
+      "caption" => "Partial Photo"
+    )
+    # Mark it as selectively fetched (uses @_fetched_keys internally)
+    partial_asset.instance_variable_set(:@_fetched_keys, Set.new([:id, :caption]))
+
+    proxy = Parse::PointerCollectionProxy.new([partial_asset])
+
+    # With pointers_only: false, only_fetched defaults to true
+    result = proxy.as_json(pointers_only: false)
+
+    assert_equal 1, result.length
+    item = result[0]
+    # Should include fetched fields
+    assert_equal "partial123", item["objectId"]
+    assert_equal "Partial Photo", item["caption"]
+  end
+
+  def test_as_json_can_override_only_fetched
+    proxy = Parse::PointerCollectionProxy.new([@asset1])
+
+    # Explicitly set only_fetched: false
+    result = proxy.as_json(pointers_only: false, only_fetched: false)
+
+    assert_equal 1, result.length
+    assert_equal "Photo 1", result[0]["caption"]
+  end
+
+  # === String option keys work ===
+
+  def test_as_json_pointers_only_false_with_string_key
+    proxy = Parse::PointerCollectionProxy.new([@asset1])
+
+    result = proxy.as_json("pointers_only" => false)
+
+    assert_equal 1, result.length
+    refute_equal "Pointer", result[0]["__type"]
+    assert_equal "Photo 1", result[0]["caption"]
+  end
+
+  # === Empty collection ===
+
+  def test_as_json_empty_collection
+    proxy = Parse::PointerCollectionProxy.new([])
+
+    result_default = proxy.as_json
+    result_full = proxy.as_json(pointers_only: false)
+
+    assert_equal [], result_default
+    assert_equal [], result_full
+  end
+end