pgoutput-decoder 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc6535189e67a471cc685b43e61aa084fd8e5b109cbbff682494a49a936164e6
-  data.tar.gz: 93858268fe2519951b33561b5deec1da508f32b7d2fa00f1c364731d5c6715b7
+  metadata.gz: 3a963632f6c43a96fee216f4f66e7ac5743f7b4374dec2a61bf5d5ab6c0111fe
+  data.tar.gz: 283c438cd2b5bc332483ba79a313fdbf5feda5134200f0478e8b283339fd1a68
 SHA512:
-  metadata.gz: 1fbac46c86f50fa10ccdb623cd301ce12b12f72bd271915d0fa567e4605f758b2961cfb466661c1e59918ef89829a8bf367d3e771bcd9d55ec31dbf3d6a2bea3
-  data.tar.gz: 3978a4c40f0939917ca97f129130995682602cadf2254b92bee9fa1fe56608baab401112efefc756ed5dc23ce9db837c6702ca9dbb5c71e403db23a1909c5bd1
+  metadata.gz: 05d855963feccb5872525b81318f80b58152153e344abeade63b20ede94e76e2c71932566e1ae3b8213695e2946a6b5cbb54df45e947745c0885b0d063feb7df
+  data.tar.gz: 07e90807168a43c177e448b47005b6e668d6bd1bee18b0f5e0665ed70f245d9734a22fee40a82f0162731b28c8f16ea38eecf34bdbec13c6a776ed3bc77bfff3

data/CHANGELOG.md

@@ -1,17 +1,46 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+## [Unreleased]
 
-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).
+## 0.2.0 - 2026-07-17
 
-## [Unreleased]
+### Fixed
 
-### Added
+* Decode UPDATE and DELETE old-key tuples using relation key-column flags.
+* Preserve composite and non-`id` keys while omitting non-key placeholders from
+  full-width PostgreSQL tuples.
+* Restored SimpleCov result finalization, HTML report generation, and minimum
+  line/branch coverage enforcement.
+
+### Documentation
+
+* Documented exact replica-key tuple behavior.
+
+## 0.1.1 - 2026-06-17
+
+### Fixed
 
-- Placeholder for future development.
+* Curated RBS signatures shipped with the gem.
+* Fixed duplicate `Pgoutput::Decoder` type declarations that caused Steep/RBS environment loading failures.
+* Corrected decoder type signatures to align with actual runtime behavior.
+* Improved `TypeRegistry` type annotations and value narrowing.
+* Fixed Steep type-checking issues around decoder lookup, JSON decoding, UUID decoding, and numeric value decoding.
+* Added missing standard library type dependencies required by Steep.
+* Improved compatibility with downstream consumers using:
 
----
+  * `library "pgoutput-decoder"`
+  * `bundle exec steep check`
+
+### Documentation
+
+* Refined shipped type definitions to better reflect the public API surface.
+
+### Internal
+
+* No runtime behavior changes.
+* No protocol decoding changes.
+* No public API changes.
+* This release focuses on RBS, Steep, and developer tooling correctness.
 
 ## [0.1.0] - 2026-06-01
 
@@ -32,8 +61,3 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added RBS signatures.
 - Added README documentation.
 - Added CI and release workflow templates.
-
----
-
-[Unreleased]: https://github.com/kanutocd/pgoutput-decoder/compare/v0.1.0...HEAD
-[0.1.0]: https://github.com/kanutocd/pgoutput-decoder/releases/tag/v0.1.0

data/README.md

@@ -1,5 +1,10 @@
 # pgoutput-decoder
 
+[![Gem Version](https://badge.fury.io/rb/pgoutput-decoder.svg)](https://badge.fury.io/rb/pgoutput-decoder)
+[![CI](https://github.com/kanutocd/pgoutput-decoder/workflows/CI/badge.svg)](https://github.com/kanutocd/pgoutput-decoder/actions)
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.4-ruby.svg)](https://www.ruby-lang.org/en/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 A high-level PostgreSQL `pgoutput` logical replication value decoder for Ruby.
 
 `pgoutput-decoder` is the companion layer to [`pgoutput-parser`](https://rubygems.org/gems/pgoutput-parser). It accepts immutable protocol messages produced by `pgoutput-parser` and turns tuple payloads into application-friendly Ruby row-change events.
@@ -234,6 +239,11 @@ delete.old_values
 # => { ... } or nil
 ```
 
+`old_key` contains only columns marked as replica-key columns by the preceding
+`Relation` message. Composite and non-`id` identities retain their declared
+column order; full-width tuples with non-key placeholders do not leak those
+placeholders into the decoded key.
+
 ---
 
 ## Ractor Safety
@@ -257,10 +267,11 @@ The decoder instance itself is stateful and should not be shared across Ractors.
 bundle exec rake test
 ```
 
-With coverage:
+The test task generates line and branch coverage in `coverage/` and enforces
+the configured minimums:
 
 ```bash
-COVERAGE=true bundle exec rake test
+bundle exec rake test
 ```
 
 ---
@@ -275,4 +286,4 @@ bundle exec steep check
 
 ## License
 
-MIT.
+[MIT](LICENSE.txt).

data/lib/pgoutput/decoder/row_builder.rb

@@ -19,11 +19,34 @@ module Pgoutput
       # @param tuple [Array<Pgoutput::Messages::TupleValue>]
       # @return [Hash<String, Object>]
       def build(relation, tuple)
-        row = {}
+        build_columns(relation.columns, tuple)
+      end
+
+      # Build a decoded replica-key hash.
+      #
+      # PostgreSQL may encode an old-key tuple at full relation width with
+      # placeholders for non-key columns, while compact protocol fixtures may
+      # contain only key values. Relation flags determine the exact key columns
+      # in both representations.
+      #
+      # @param relation [Pgoutput::Messages::Relation]
+      # @param tuple [Array<Pgoutput::Messages::TupleValue>]
+      # @return [Hash<String, Object>]
+      def build_key(relation, tuple)
+        key_columns = relation.columns.select { |column| key_column?(column) }
+        columns = tuple.length == relation.columns.length ? relation.columns : key_columns
+        build_columns(columns, tuple, key_only: true)
+      end
+
+      private
+
+      def build_columns(columns, tuple, key_only: false)
+        row = {} # : Hash[String, untyped]
 
         tuple.each_with_index do |tuple_value, index|
-          column = relation.columns[index]
+          column = columns[index]
           next unless column
+          next if key_only && !key_column?(column)
 
           normalized_value = normalize_oid(tuple_value, column.oid)
           row[column.name] = @value_decoder.decode(normalized_value)
@@ -32,7 +55,9 @@ module Pgoutput
         Ractor.make_shareable(row.freeze)
       end
 
-      private
+      def key_column?(column)
+        column.flags.allbits?(1)
+      end
 
       def normalize_oid(tuple_value, oid)
         return tuple_value unless tuple_value.oid.nil?

data/lib/pgoutput/decoder/type_registry.rb

@@ -79,7 +79,7 @@ module Pgoutput
           VARCHAR => ->(raw, _format) { raw.dup.freeze },
           FLOAT4 => ->(raw, format) { decode_float(raw, format, 4, "g") },
           FLOAT8 => ->(raw, format) { decode_float(raw, format, 8, "G") },
-          NUMERIC => ->(raw, format) { format == :text ? BigDecimal(raw) : raw.dup.freeze },
+          NUMERIC => ->(raw, format) { format == :text ? Kernel.BigDecimal(raw) : raw.dup.freeze },
           JSON => ->(raw, format) { format == :text ? ::JSON.parse(raw) : raw.dup.freeze },
           JSONB => ->(raw, format) { decode_jsonb(raw, format) },
           UUID => ->(raw, format) { format == :text ? raw.dup.freeze : decode_uuid_binary(raw) },
@@ -107,7 +107,7 @@ module Pgoutput
       def decode(oid, raw, format)
         return nil if raw.nil?
 
-        decoder = @decoders[oid]
+        decoder = oid ? @decoders[oid] : nil
         decoded = decoder ? decoder.call(raw, format) : raw.dup.freeze
         Ractor.make_shareable(decoded)
       end
@@ -129,24 +129,27 @@ module Pgoutput
       class << self
         private
 
+        # This decodes a PostgreSQL boolean value; it is not an object predicate.
+        # rubocop:disable Naming/PredicateMethod
         def decode_bool(raw, format)
           return raw == "t" if format == :text
 
           raw.unpack1("C") == 1
         end
+        # rubocop:enable Naming/PredicateMethod
 
         def decode_int(raw, format, expected_length, template)
           return raw.to_i if format == :text
           return raw.dup.freeze unless raw.bytesize == expected_length
 
-          raw.unpack1(template)
+          Integer(raw.unpack1(template))
         end
 
         def decode_float(raw, format, expected_length, template)
           return Float(raw) if format == :text
           return raw.dup.freeze unless raw.bytesize == expected_length
 
-          raw.unpack1(template)
+          Float(raw.unpack1(template))
         end
 
         def decode_jsonb(raw, format)
@@ -156,13 +159,13 @@ module Pgoutput
           # current on-wire format; the remaining bytes contain JSON text.
           return raw.dup.freeze unless raw.bytesize >= 2 && raw.getbyte(0) == 1
 
-          ::JSON.parse(raw.byteslice(1..))
+          ::JSON.parse(raw.byteslice(1..).to_s)
         end
 
         def decode_uuid_binary(raw)
           return raw.dup.freeze unless raw.bytesize == 16
 
-          hex = raw.unpack1("H*")
+          hex = raw.unpack1("H*").to_s
           "#{hex[0, 8]}-#{hex[8, 4]}-#{hex[12, 4]}-#{hex[16, 4]}-#{hex[20, 12]}".freeze
         end
       end

data/lib/pgoutput/decoder/version.rb

@@ -3,6 +3,6 @@
 module Pgoutput
   class Decoder
     # Gem version.
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/pgoutput/decoder.rb

@@ -120,7 +120,7 @@ module Pgoutput
           message.relation_id,
           relation.schema,
           relation.table,
-          optional_row(relation, message.old_key_tuple),
+          optional_row(relation, message.old_key_tuple, key: true),
           optional_row(relation, message.old_tuple),
           @row_builder.build(relation, message.new_tuple)
         )
@@ -137,14 +137,15 @@ module Pgoutput
           message.relation_id,
           relation.schema,
           relation.table,
-          optional_row(relation, message.old_key_tuple),
+          optional_row(relation, message.old_key_tuple, key: true),
           optional_row(relation, message.old_tuple)
         )
       )
     end
 
-    def optional_row(relation, tuple)
+    def optional_row(relation, tuple, key: false)
       return nil if tuple.nil?
+      return @row_builder.build_key(relation, tuple) if key
 
       @row_builder.build(relation, tuple)
     end

data/sig/pgoutput_decoder.rbs

@@ -2,6 +2,9 @@ module Pgoutput
   class Decoder
     VERSION: String
 
+    type parser_message = untyped
+    type relation = untyped
+    type tuple = Array[untyped]
     type event =
       Events::Begin |
       Events::Commit |
@@ -9,10 +12,31 @@ module Pgoutput
       Events::Update |
       Events::Delete
 
+    @type_registry: TypeRegistry
+    @relations: RelationCache
+    @row_builder: RowBuilder
+    @current_transaction_id: Integer?
+    @current_final_lsn: Integer?
+    @current_commit_timestamp: Integer?
+
     def initialize: (?type_registry: TypeRegistry) -> void
-    def decode: (untyped message) -> event?
+    def decode: (parser_message message) -> event?
     def type_registry: () -> TypeRegistry
 
+    private
+
+    def decode_begin: (parser_message message) -> Events::Begin
+    def decode_commit: (parser_message message) -> Events::Commit
+    def decode_insert: (parser_message message) -> Events::Insert
+    def decode_update: (parser_message message) -> Events::Update
+    def decode_delete: (parser_message message) -> Events::Delete
+    def optional_row: (relation relation, tuple? tuple, ?key: bool) -> Hash[String, untyped]?
+    def relation_for: (Integer relation_id) -> relation
+    def require_transaction_id: () -> Integer
+    def clear_transaction!: () -> nil
+    def parser_messages: () -> untyped
+    def share: [T] (T object) -> T
+
     class Error < StandardError
     end
 
@@ -93,27 +117,52 @@ module Pgoutput
       UUID: Integer
       JSONB: Integer
 
+      type decoder = ^(String raw, Symbol format) -> untyped
+
+      @decoders: Hash[Integer, decoder]
+
       def self.default: () -> TypeRegistry
-      def self.default_decoders: () -> Hash[Integer, Proc]
-      def initialize: (?Hash[Integer, Proc] decoders) -> void
+      def self.default_decoders: () -> Hash[Integer, decoder]
+      def initialize: (?Hash[Integer, decoder] decoders) -> void
       def decode: (Integer? oid, String? raw, Symbol format) -> untyped?
       def with_decoder: (Integer oid) { (String raw, Symbol format) -> untyped } -> TypeRegistry
+
+      private
+
+      def self.decode_bool: (String raw, Symbol format) -> bool
+      def self.decode_int: (String raw, Symbol format, Integer expected_length, String template) -> (Integer | String)
+      def self.decode_float: (String raw, Symbol format, Integer expected_length, String template) -> (Float | String)
+      def self.decode_jsonb: (String raw, Symbol format) -> untyped
+      def self.decode_uuid_binary: (String raw) -> String
     end
 
     class ValueDecoder
+      @type_registry: TypeRegistry
+
       def initialize: (?type_registry: TypeRegistry) -> void
       def decode: (untyped tuple_value) -> untyped?
     end
 
     class RelationCache
+      @relations: Hash[Integer, relation]
+
       def initialize: () -> void
-      def store: (untyped relation) -> untyped
-      def fetch: (Integer relation_id) -> untyped
+      def store: (relation relation) -> relation
+      def fetch: (Integer relation_id) -> relation
     end
 
     class RowBuilder
+      @value_decoder: ValueDecoder
+
       def initialize: (?type_registry: TypeRegistry) -> void
-      def build: (untyped relation, Array[untyped] tuple) -> Hash[String, untyped]
+      def build: (relation relation, tuple tuple) -> Hash[String, untyped]
+      def build_key: (relation relation, tuple tuple) -> Hash[String, untyped]
+
+      private
+
+      def build_columns: (Array[untyped] columns, tuple tuple, ?key_only: bool) -> Hash[String, untyped]
+      def key_column?: (untyped column) -> bool
+      def normalize_oid: (untyped tuple_value, Integer oid) -> untyped
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgoutput-decoder
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -10,117 +10,33 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: pgoutput-parser
+  name: bigdecimal
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '4.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.27'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.27'
-- !ruby/object:Gem::Dependency
-  name: pry
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.16.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.16.0
+        version: '4.1'
 - !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.4'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.4'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.87'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.87'
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.22.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.22.0
-- !ruby/object:Gem::Dependency
-  name: steep
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.10'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.10'
-- !ruby/object:Gem::Dependency
-  name: yard
+  name: pgoutput-parser
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.44
-  type: :development
+        version: '0.1'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.44
+        version: '0.1'
 description: Decodes pgoutput-parser protocol messages into immutable Ruby row-change
   events.
 email:
@@ -141,7 +57,6 @@ files:
 - lib/pgoutput/decoder/value_decoder.rb
 - lib/pgoutput/decoder/version.rb
 - lib/pgoutput_decoder.rb
-- sig/pgoutput/decoder.rbs
 - sig/pgoutput_decoder.rbs
 homepage: https://github.com/kanutocd/pgoutput-decoder
 licenses:

data/sig/pgoutput/decoder.rbs

@@ -1,6 +0,0 @@
-module Pgoutput
-  module Decoder
-    VERSION: String
-    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-  end
-end