familia 2.11.1 → 2.11.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 515d7050ae261290c4e85c6757a68edaa2aae60e21e05b9a6d1fd0457d90fad5
-  data.tar.gz: 653efc3da9a21910e7e071ae3065ab06e730334226d8f4820c0ed692fbec8453
+  metadata.gz: d7b0eed1c3632c68c8c4c91617830f0b15a10907da5c7af0bbc14b9cf67a5336
+  data.tar.gz: 4a123b805e826b8ede218675c16781f428fab6c3194968c5a3840323b949b28e
 SHA512:
-  metadata.gz: 9e82443e034e2a2457bdc5366edcc18586d5df1f1ef4e60dc8c50d3d7431850c8899c42e15200d8ad0638455f13f2024a357b5e904f424fc9315312194329cce
-  data.tar.gz: 5eed6b2a2017510bac669b43602a1960b0719fa839eb8e61114be27df7010ea4d90eb73abdefc202b86e6c05d0e9dc674087e90e8c828dd649aaad4c446d38a4
+  metadata.gz: 6c245370d354eaa0d8af0b0994cd44ea10f8dec3b260c9750d3cceb66563c51ee8f4390062429c8aced6cd578d919c7a806a0eef2e5be0f9d90bbc00dcf87b06
+  data.tar.gz: a824edcd1af5d3535168600d90a3e189b0203c884fe17c7382cafb22ebc6c19a36c68011a468e9dd8b16fed386b902eac16709625004f73b7f4085b0ae0a601e

data/.github/workflows/ci.yml

@@ -53,7 +53,7 @@ jobs:
           bundler-cache: true
 
       - name: Setup tmate session
-        uses: mxschmitt/action-tmate@7b6a61a73bbb9793cb80ad69b8dd8ac19261834c # v3
+        uses: mxschmitt/action-tmate@35b54afac29c97fb54faba5b513f8fbd1882f113 # v3
         if: ${{ github.event_name == 'workflow_dispatch' && inputs.debug_enabled }}
         with:
           detached: true

data/.github/workflows/release-gem.yml

@@ -158,4 +158,4 @@ jobs:
           echo "Releasing familia ${gem_version} from tag ${RELEASE_TAG}"
 
       - name: Build and push gem to RubyGems
-        uses: rubygems/release-gem@6317d8d1f7e28c24d28f6eff169ea854948bd9f7 # v1.2.0
+        uses: rubygems/release-gem@052cc82692552de3ef2b81fd670e41d13cba8092 # v1.4.0

data/.github/workflows/ruby-lint.yml

@@ -49,7 +49,7 @@ jobs:
           bundler-cache: true
 
       - name: Setup tmate session
-        uses: mxschmitt/action-tmate@7b6a61a73bbb9793cb80ad69b8dd8ac19261834c # v3
+        uses: mxschmitt/action-tmate@35b54afac29c97fb54faba5b513f8fbd1882f113 # v3
         if: ${{ github.event_name == 'workflow_dispatch' && inputs.debug_enabled }}
         with:
           detached: true

data/CHANGELOG.rst

@@ -7,6 +7,40 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.11.2:
+
+2.11.2 — 2026-07-05
+===================
+
+
+Changed
+-------
+
+- ``to_h_for_storage`` omits nil fields; every write path removes a field that has
+  become nil. ``save``/``commit_fields`` do a full overwrite (the stored hash
+  matches the in-memory object, so a field nil in memory is deleted);
+  ``save_fields``/``multi_field_update``/``multi_field_fast_write`` delete a named
+  field passed as nil. ``to_h`` still returns every declared field, nils included.
+
+- Claim caveat: a full ``save``/``commit_fields`` of a stale copy clears a field
+  another writer claimed via ``HSETNX``. To claim and update without disturbing
+  it, use the targeted writers or ``refresh!`` first.
+
+Fixed
+-----
+
+- Nil-valued fields are no longer stored as the JSON string ``"null"``. Because a
+  hash has no native NULL, this left declared fields perpetually present, breaking
+  ``HSETNX``/``HEXISTS`` atomic-claim patterns and wasting memory. Nil fields are
+  now omitted, and clearing a field to nil removes it from storage (``HDEL``), so
+  absence again means "no value". No migration required: stale ``"null"`` values
+  are cleaned up on the next save and already decode back to ``nil`` on read.
+
+AI Assistance
+-------------
+
+- Investigation, implementation, and tryouts coverage produced with Claude Code.
+
 .. _changelog-2.11.1:
 
 2.11.1 — 2026-07-04

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.11.1)
+    familia (2.11.2)
       concurrent-ruby (~> 1.3)
       connection_pool (>= 2.4, < 4.0)
       csv (~> 3.3)
@@ -9,7 +9,7 @@ PATH
       logger (~> 1.7)
       oj (~> 3.16)
       redis (>= 5.0, < 6.0)
-      stringio (~> 3.1.1)
+      stringio (>= 3.1.1, < 3.3.0)
       uri-valkey (~> 1.4)
 
 GEM
@@ -166,7 +166,7 @@ GEM
     ruby-progressbar (1.13.0)
     simpleidn (0.2.3)
     stackprof (0.2.28)
-    stringio (3.1.9)
+    stringio (3.2.0)
     timecop (0.9.11)
     tryouts (3.7.1)
       concurrent-ruby (~> 1.0, < 2)

data/familia.gemspec

@@ -26,7 +26,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'logger', '~> 1.7'
   spec.add_dependency 'oj', '~> 3.16'
   spec.add_dependency 'redis', '>= 5.0', '< 6.0'
-  spec.add_dependency 'stringio', '~> 3.1.1'
+  spec.add_dependency 'stringio', '>= 3.1.1', '< 3.3.0'
   spec.add_dependency 'uri-valkey', '~> 1.4'
 
   spec.metadata['rubygems_mfa_required'] = 'true'

data/lib/familia/horreum/database_commands.rb

@@ -157,8 +157,14 @@ module Familia
       #
       # @param hsh [Hash] Hash of field-value pairs to set
       # @return [String] 'OK' on success
-      def hmset(hsh = {})
+      def hmset(hsh = nil)
         hsh ||= to_h_for_storage
+        # An empty hash means there is nothing to persist -- e.g. an object whose
+        # only non-nil field would be a Proc-derived identifier, so no declared
+        # field is written. HMSET with zero field/value pairs is a Redis error,
+        # so treat it as a successful no-op rather than crashing the save.
+        return 'OK' if hsh.empty?
+
         Familia.trace :HMSET, nil, hsh if Familia.debug?
         dbclient.hmset dbkey(suffix), hsh
       end

data/lib/familia/horreum/persistence.rb

@@ -88,6 +88,15 @@ module Familia
       # @example Single-expression short-circuit
       #   user.save && AuditLog.record(:user_updated, user.identifier)
       #
+      # @note This is a FULL-OVERWRITE of the object's scalar state: afterwards
+      #   the stored hash matches the in-memory object exactly. Non-nil fields are
+      #   written and fields that are nil in memory are removed from storage. A
+      #   field managed out of band -- e.g. one claimed by another actor via
+      #   HSETNX while this (possibly stale) copy still holds nil for it -- is
+      #   therefore cleared by a full save. To update an object without disturbing
+      #   such fields, use the targeted writers ({#save_fields},
+      #   {#multi_field_update}, {#multi_field_fast_write}) or {#refresh!} first.
+      #
       # @see #save_if_not_exists! For conditional saves
       # @see #transaction For atomic operations after save
       #
@@ -319,17 +328,24 @@ module Familia
         Familia.debug "[commit_fields] Begin #{self.class} #{dbkey} #{prepared_value} (exp: #{update_expiration})"
 
         result = transaction do |_conn|
-          # Set all fields atomically
-          result = hmset(prepared_value)
+          # Set all non-nil fields atomically
+          hmset_result = hmset(prepared_value)
+
+          # Remove any fields cleared to nil so their prior stored value is not
+          # left stale (HMSET never deletes omitted fields).
+          remove_stale_nil_fields
 
           # Update expiration in same transaction to ensure atomicity
-          self.update_expiration if result && update_expiration
+          self.update_expiration if hmset_result && update_expiration
 
-          # Touch instances timeline so the object is visible
-          # to list-based enumeration (instances.to_a, count, etc.)
-          touch_instances! if result
+          # Touch instances timeline so the object is visible to list-based
+          # enumeration (instances.to_a, count, etc.). Skip it when nothing was
+          # persisted and no hash key exists -- otherwise the identifier is
+          # registered in `instances` pointing at a missing hash (see
+          # {#persist_to_storage}).
+          touch_instances! if hmset_result && !prepared_value.empty?
 
-          result
+          hmset_result
         end
 
         # Clear dirty tracking after successful commit
@@ -376,10 +392,15 @@ module Familia
         Familia.trace :MULTI_FIELD_UPDATE, nil, fields.keys if Familia.debug?
 
         result = transaction do |_conn|
-          # 1. Update all fields atomically (Redis only, no in-memory mutation)
+          # 1. Update all fields atomically (Redis only, no in-memory mutation).
+          # A nil value deletes the field rather than storing "null", so absence
+          # stays authoritative (see Serialization#to_h_for_storage).
           fields.each do |field, value|
-            prepared_value = serialize_value(value)
-            hset field, prepared_value
+            if value.nil?
+              remove_field(field)
+            else
+              hset field, serialize_value(value)
+            end
           end
 
           # 2. Update expiration in same transaction
@@ -434,15 +455,24 @@ module Familia
 
         Familia.trace :MULTI_FIELD_FAST_WRITE, nil, fields.keys if Familia.debug?
 
-        # Serialize values before the transaction (read-only on instance)
+        # Serialize values before the transaction (read-only on instance).
+        # A nil value deletes the field rather than storing "null" (see
+        # Serialization#to_h_for_storage), so split writes from removals.
         serialized = {}
+        nil_fields = []
         fields.each do |field, value|
-          serialized[field] = serialize_value(value)
+          if value.nil?
+            nil_fields << field.to_s
+          else
+            serialized[field] = serialize_value(value)
+          end
         end
 
         result = transaction do |_conn|
           hmset(serialized)
 
+          dbclient.hdel(dbkey, *nil_fields) unless nil_fields.empty?
+
           update_expiration if update_exp
 
           touch_instances!
@@ -478,20 +508,29 @@ module Familia
         Familia.trace :SAVE_FIELDS, nil, field_names if Familia.debug?
 
         result = transaction do |_conn|
-          # Build hash of field names to serialized values
+          # Build hash of non-nil field values; collect nil'd fields for removal.
+          # A nil field is deleted rather than stored as "null" so that absence
+          # stays authoritative (see Serialization#to_h_for_storage).
           fields_hash = {}
+          nil_fields = []
           field_names.each do |field|
             field_sym = field.to_sym
             raise ArgumentError, "Unknown field: #{field}" unless respond_to?(field_sym)
 
             value = send(field_sym)
-            prepared_value = serialize_value(value)
-            fields_hash[field] = prepared_value
+            if value.nil?
+              nil_fields << field.to_s
+            else
+              fields_hash[field] = serialize_value(value)
+            end
           end
 
-          # Set all fields at once using hmset
+          # Set all non-nil fields at once (hmset no-ops on an empty hash)
           hmset(fields_hash)
 
+          # Remove any nil'd fields so their prior stored value does not linger
+          dbclient.hdel(dbkey, *nil_fields) unless nil_fields.empty?
+
           # Update expiration in same transaction
           self.update_expiration if update_expiration
 
@@ -959,6 +998,46 @@ module Familia
       end
       private :prepare_for_save
 
+      # Names (as strings) of declared persistent fields whose current in-memory
+      # value is nil. These are omitted from {Serialization#to_h_for_storage}, so
+      # on an update their previously-stored value must be explicitly deleted.
+      #
+      # @return [Array<String>]
+      #
+      def nil_persistent_field_names
+        self.class.persistent_fields.each_with_object([]) do |field, names|
+          field_type = self.class.field_types[field]
+          names << field.to_s if send(field_type.method_name).nil?
+        end
+      end
+      private :nil_persistent_field_names
+
+      # Deletes any now-nil persistent fields from the object hash so a value
+      # cleared to nil does not leave a stale entry behind. This is what keeps
+      # "absent" and "nil" the same observable state after a round trip, and
+      # what makes HSETNX/HEXISTS on a nil'd field behave correctly.
+      #
+      # Because it removes every field that is nil in memory, save/commit_fields
+      # are a full-overwrite of scalar state (see {#save}). A field managed out of
+      # band (e.g. an HSETNX claim) that is still nil on this in-memory copy is
+      # cleared by a full save; use the targeted writers or {#refresh!} to avoid
+      # that.
+      #
+      # Intended to run inside the save/commit transaction. HDEL of an absent
+      # field is a harmless no-op, so it is safe on both the create and update
+      # paths (and queues cleanly inside MULTI/EXEC).
+      #
+      # @return [void]
+      #
+      def remove_stale_nil_fields
+        names = nil_persistent_field_names
+        return if names.empty?
+
+        Familia.trace :HDEL, nil, names if Familia.debug?
+        dbclient.hdel(dbkey, *names)
+      end
+      private :remove_stale_nil_fields
+
       # Persists the object's data to storage within a transaction.
       #
       # This is the primary code path that adds an object to the class-level
@@ -975,18 +1054,34 @@ module Familia
       # @return [Object] The result of the hmset operation
       #
       def persist_to_storage(update_expiration)
-        # 1. Save all fields to hashkey at once
+        # 1. Save all non-nil fields to hashkey at once
         prepared_h = to_h_for_storage
         hmset_result = hmset(prepared_h)
 
+        # 1b. Remove any fields cleared to nil so a nil'd value does not linger
+        # in storage. HMSET only sets the fields it is given; it never deletes
+        # omitted ones, so an update that clears a field to nil would otherwise
+        # leave the prior value behind. Harmless no-op on the create path.
+        remove_stale_nil_fields
+
         # 2. Set expiration in same transaction
         self.update_expiration if update_expiration
 
         # 3. Update class-level indexes
         auto_update_class_indexes
 
-        # 4. Touch instances timeline (delegates to touch_instances!)
-        touch_instances!
+        # 4. Touch instances timeline (delegates to touch_instances!).
+        #
+        # Skip it when there is genuinely nothing stored and no hash key exists.
+        # prepared_h is empty only when every declared persistent field is nil
+        # AND the identifier is not itself a stored field (a Proc-derived
+        # identifier) -- hmset no-op'd and no key was created. Registering the
+        # identifier in `instances` in that case would leave a dangling
+        # reference: the identifier would list in instances.to_a while exists?
+        # (check_size: true) returns false and any load follows a dead pointer.
+        # In the ubiquitous `identifier_field :id; field :id` pattern the id
+        # keeps prepared_h non-empty, so this only skips the degenerate case.
+        touch_instances! unless prepared_h.empty?
 
         hmset_result
       end

data/lib/familia/horreum/serialization.rb

@@ -22,7 +22,9 @@ module Familia
       #   # Note: Returns actual Ruby types, not JSON strings
       #
       # @note Only loggable fields are included. Encrypted fields are excluded.
-      # @note Nil values are excluded from the returned hash (storage optimization)
+      # @note Every persistent field appears, including those whose value is nil.
+      #   This differs from {#to_h_for_storage}, which omits nil fields so that
+      #   absence -- not a stored "null" -- represents "no value" in Valkey/Redis.
       #
       def to_h
         self.class.persistent_fields.each_with_object({}) do |field, hsh|
@@ -55,13 +57,25 @@ module Familia
       #   # Note: Strings are JSON-encoded with quotes
       #
       # @note This is an internal method used by commit_fields and hmset
-      # @note Nil values are excluded to optimize Redis storage
+      # @note Nil-valued fields are omitted so that field *absence* -- not a
+      #   stored "null" -- represents "no value" in the Valkey/Redis hash. This
+      #   is what keeps HSETNX/HEXISTS-based claim patterns usable and avoids
+      #   materializing every declared field. Fields cleared to nil are actively
+      #   removed from storage on save; see {Persistence#remove_stale_nil_fields}.
       #
       def to_h_for_storage
         self.class.persistent_fields.each_with_object({}) do |field, hsh|
           field_type = self.class.field_types[field]
 
           val = send(field_type.method_name)
+
+          # Omit nil fields entirely. A Valkey/Redis hash has no NULL: absence is
+          # the native "no value". Persisting nil as the JSON string "null" would
+          # make declared fields perpetually present, defeating HSETNX/HEXISTS and
+          # wasting memory. Round-trips are unaffected -- deserialize_value already
+          # returns nil for an absent field.
+          next if val.nil?
+
           prepared = serialize_value(val)
 
           if Familia.debug?

data/lib/familia/version.rb

@@ -2,5 +2,5 @@
 
 module Familia
   # Version information for the Familia
-  VERSION = '2.11.1'.freeze
+  VERSION = '2.11.2'.freeze
 end

data/try/features/encrypted_fields/re_encrypt_fields_try.rb

@@ -127,13 +127,13 @@ result = @partial_fresh.re_encrypt_fields!
 
 raw_token = Familia.dbclient.hget(@partial_fresh.dbkey, 'token')
 raw_secret = Familia.dbclient.hget(@partial_fresh.dbkey, 'secret')
-# Nil encrypted fields are stored as the JSON literal "null" by Familia's
-# scalar serializer -- not as an encrypted envelope. The contract we care
-# about here is: re_encrypt_fields! must not turn a nil field into
-# ciphertext. Parsing "null" yields nil, so we assert that directly.
-token_parsed = JSON.parse(raw_token) rescue :unparseable
-[result, token_parsed, JSON.parse(raw_secret)['key_version']]
-#=> [true, nil, 'v2']
+# A nil field is not persisted at all -- in a Redis hash, absence *is* the
+# representation of "no value" -- so the token field simply does not exist in
+# storage (hget returns nil). The contract we care about here is: re_encrypt_fields!
+# must not turn a nil field into ciphertext; an absent field trivially satisfies
+# that, and is now directly observable via HEXISTS/hget being nil.
+[result, raw_token.nil?, JSON.parse(raw_secret)['key_version']]
+#=> [true, true, 'v2']
 
 ## is idempotent when current key is unchanged
 # Calling re_encrypt_fields! twice without rotating must succeed both times

data/try/integration/database_consistency_try.rb

@@ -67,10 +67,11 @@ key_parts = dbkey.split(':')
 expected_fields = @serial_test.class.persistent_fields.length
 redis_field_count = Familia.dbclient.hlen(@serial_test.dbkey)
 actual_object_fields = @serial_test.to_h.keys.length
-# The JSON Serializer stores all fields (including nil as "null")
-# Expected fields (5) >= redis count (5) >= to_h count (5, even though email is nil)
+# Storage omits nil fields (absence represents "no value"), so only the single
+# non-nil field (id) is written even though the class declares 5 persistent
+# fields. to_h still reports every declared field, including the nil ones.
 [expected_fields, redis_field_count, actual_object_fields]
-#=> [5, 5, 5]
+#=> [5, 1, 5]
 
 ## Memory vs persistence state consistency after save
 @consistency_obj = ConsistencyTestModel.new(id: next_test_id, name: 'Memory Test', email: 'test@example.com')

data/try/integration/nil_field_absence_try.rb

@@ -0,0 +1,160 @@
+# try/integration/nil_field_absence_try.rb
+#
+# frozen_string_literal: true
+#
+# Nil-valued declared fields are ABSENT from the Valkey/Redis hash rather than
+# stored as the JSON literal "null". Field absence is the native representation
+# of "no value" in a hash, and it is what makes HSETNX/HEXISTS-based claim
+# patterns work and keeps "unset" and "nil" the same observable state after a
+# round trip.
+
+require_relative '../support/helpers/test_helpers'
+
+class NilAbsenceModel < Familia::Horreum
+  identifier_field :id
+  field :id
+  field :name
+  field :claimed_at # nil until atomically claimed via HSETNX
+  field :note
+end
+
+# Identifier derived from a NON-persistent attribute (a Proc), so every declared
+# persistent field can be nil while the object still has a usable identifier.
+# This exercises the degenerate "nothing to persist" path.
+class ProcIdAbsenceModel < Familia::Horreum
+  identifier_field ->(obj) { obj.probe_id }
+  field :name
+  field :note
+
+  attr_accessor :probe_id
+end
+
+# Clean up any prior test data
+begin
+  existing = Familia.dbclient.keys('nilabsencemodel:*')
+  Familia.dbclient.del(*existing) if existing.any?
+rescue StandardError
+  # ignore cleanup errors
+end
+
+@id_counter = 0
+def next_id
+  @id_counter += 1
+  "nil-absence-#{Familia.now.to_i}-#{@id_counter}"
+end
+
+## A nil declared field is not written to storage (HEXISTS is false)
+@obj = NilAbsenceModel.new(id: next_id, name: 'has name')
+@obj.save
+Familia.dbclient.hexists(@obj.dbkey, 'claimed_at')
+#=> false
+
+## Only the non-nil fields are stored in the hash
+@obj.hgetall.keys.sort
+#=> ["id", "name"]
+
+## to_h still reports every declared field, including the nil ones
+@obj.to_h.keys.sort
+#=> ["claimed_at", "id", "name", "note"]
+
+## The nil field round-trips as nil after refresh (absent == nil)
+@obj.refresh!
+@obj.claimed_at
+#=> nil
+
+## HSETNX succeeds on a nil declared field -- the field is genuinely absent
+@claim = NilAbsenceModel.new(id: next_id, name: 'claimant')
+@claim.save
+@claim.hsetnx('claimed_at', Familia.now.to_i.to_s)
+#=> true
+
+## A second HSETNX fails: the field now holds a value (first-writer-wins)
+@claim.hsetnx('claimed_at', Familia.now.to_i.to_s)
+#=> false
+
+## Clearing a previously-set field to nil and saving REMOVES it from storage
+@edit = NilAbsenceModel.new(id: next_id, name: 'edit me', note: 'temporary')
+@edit.save
+@edit.note = nil
+@edit.save
+Familia.dbclient.hexists(@edit.dbkey, 'note')
+#=> false
+
+## After clearing, HSETNX can claim the freed field again
+@edit.hsetnx('note', 'reclaimed')
+#=> true
+
+## An object whose only non-nil field is its identifier still exists
+@bare = NilAbsenceModel.new(id: next_id)
+@bare.save
+@bare.exists?
+#=> true
+
+## commit_fields also removes a field cleared to nil
+@commit = NilAbsenceModel.new(id: next_id, name: 'keep', note: 'drop me')
+@commit.save
+@commit.note = nil
+@commit.commit_fields
+Familia.dbclient.hexists(@commit.dbkey, 'note')
+#=> false
+
+## multi_field_update with a nil value deletes the field
+@mfu = NilAbsenceModel.new(id: next_id, name: 'mfu', note: 'present')
+@mfu.save
+@mfu.multi_field_update(note: nil)
+Familia.dbclient.hexists(@mfu.dbkey, 'note')
+#=> false
+
+## save_fields with a nil value deletes the named field
+@sf = NilAbsenceModel.new(id: next_id, name: 'sf', note: 'present')
+@sf.save
+@sf.note = nil
+@sf.save_fields(:note)
+Familia.dbclient.hexists(@sf.dbkey, 'note')
+#=> false
+
+## multi_field_fast_write with a nil value deletes the named field
+@mffw = NilAbsenceModel.new(id: next_id, name: 'mffw', note: 'present')
+@mffw.save
+@mffw.multi_field_fast_write(note: nil)
+Familia.dbclient.hexists(@mffw.dbkey, 'note')
+#=> false
+
+## multi_field_fast_write also clears the in-memory value
+@mffw.note
+#=> nil
+
+## A Proc-identifier object with all-nil fields does not create a ghost instances entry
+# Nothing is persisted (hmset no-ops), so no hash key is created; the identifier
+# must NOT be registered in the instances timeline, or it would dangle -- listed
+# in instances.to_a while exists? reports false and any load follows a dead ref.
+@ghost = ProcIdAbsenceModel.new
+@ghost.probe_id = "proc-#{Familia.now.to_i}-#{@id_counter += 1}"
+@ghost.save
+[@ghost.exists?, ProcIdAbsenceModel.instances.to_a.include?(@ghost.identifier)]
+#=> [false, false]
+
+## Once a Proc-identifier object has a real field value, it persists and registers normally
+@ghost.name = 'now real'
+@ghost.save
+[@ghost.exists?, ProcIdAbsenceModel.instances.to_a.include?(@ghost.identifier)]
+#=> [true, true]
+
+## Legacy data: a field stored as the JSON literal "null" is cleaned up on save
+@legacy = NilAbsenceModel.new(id: next_id, name: 'legacy')
+@legacy.save
+# Simulate a hash written by the pre-fix serializer, which stored nil as "null"
+Familia.dbclient.hset(@legacy.dbkey, 'claimed_at', 'null')
+@legacy.refresh! # deserialize_value turns "null" back into nil
+@legacy.save     # the now-nil field is actively removed
+Familia.dbclient.hexists(@legacy.dbkey, 'claimed_at')
+#=> false
+
+# Final cleanup
+begin
+  leftover = Familia.dbclient.keys('nilabsencemodel:*')
+  leftover.concat(Familia.dbclient.keys('procidabsencemodel:*'))
+  Familia.dbclient.del(*leftover) if leftover.any?
+rescue StandardError
+  # ignore cleanup errors
+end

data/try/unit/horreum/serialization_try.rb

@@ -66,9 +66,12 @@ Familia.dbclient.set('debug:ending_save_if_not_exists_tests', Familia.now.to_s)
 #=> "John Doe"
 
 ## multi_field_update can update multiple fields atomically, to_h
+# email was never set before the initial save, so under nil-omitting storage it
+# was not persisted; this HSET therefore CREATES the field (returns 1) whereas
+# name already exists (returns 0).
 @result = @customer.multi_field_update(name: 'Jane Windows', email: 'jane@example.com')
 @result.to_h
-#=> {:success=>true, :results=>[0, 0, false, true]}
+#=> {:success=>true, :results=>[0, 1, false, true]}
 
 ## multi_field_update returns successful result, successful?
 @result.successful?
@@ -76,11 +79,11 @@ Familia.dbclient.set('debug:ending_save_if_not_exists_tests', Familia.now.to_s)
 
 ## multi_field_update returns successful result, tuple
 @result.tuple
-#=> [true, [0, 0, false, true]]
+#=> [true, [0, 1, false, true]]
 
 ## multi_field_update returns successful result, to_a
 @result.to_a
-#=> [true, [0, 0, false, true]]
+#=> [true, [0, 1, false, true]]
 
 ## multi_field_update updates object fields in memory, confirm fields changed
 [@customer.name, @customer.email]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: familia
 version: !ruby/object:Gem::Version
-  version: 2.11.1
+  version: 2.11.2
 platform: ruby
 authors:
 - Delano Mandelbaum
@@ -123,16 +123,22 @@ dependencies:
   name: stringio
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 3.1.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 3.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 3.1.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 3.3.0
 - !ruby/object:Gem::Dependency
   name: uri-valkey
   requirement: !ruby/object:Gem::Requirement
@@ -548,6 +554,7 @@ files:
 - try/integration/models/customer_try.rb
 - try/integration/models/datatype_base_try.rb
 - try/integration/models/familia_object_try.rb
+- try/integration/nil_field_absence_try.rb
 - try/integration/persistence_operations_try.rb
 - try/integration/relationships_persistence_round_trip_try.rb
 - try/integration/save_methods_consistency_try.rb