pgoutput-source-adapter 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c0d3598bffe622103beb9a3f48c750476dcb06ec81b6d675d3a9b4628d61d1d
-  data.tar.gz: b4ab4d056f6d9f34620c88d78d28ddc6ccf678463b9975b3e4ad02328d7a61cb
+  metadata.gz: b2fb472b0d96fc532dd1fc6f1f4dfae6cc9938975379509ebf96966ad885eb55
+  data.tar.gz: 24bf3dcfa578a525de9269f14652f1f12c688231f7a6656bfbc5534e48d8dd4c
 SHA512:
-  metadata.gz: 80770110f68b77ac080ebd48fe637f8bf7cb3e054e9c9345523535c27f3f8ab35f0c8e4d3ea5387aedbd6bdfc959795556644e2b5a18685c6749dd541ff2b3a7
-  data.tar.gz: '08b336516e7466179039bbc9a1a8874e96d70d3f9511566ae520e2417a373817ba716bbb20226e606ab532da1f6e00805bdb0da9a025f4d02f1a064bbb1bfdcd'
+  metadata.gz: 220075b2c70a17079e6b56a65735d491539196c8bc2fa0adf631cadf955d5f52080cf1efef4498a40f5478a71fb087b5e9b7a4fbe000238db1c3d61e8f3aa8bf
+  data.tar.gz: ec89c4a27b1ac3eab75d4376e827f64dc423370b633780b663d3ac0615e036273b1cc2237790363922aa9d280c12c76dfcf6ce54a961c8dd47d9f8264d7b1eb8

data/CHANGELOG.md

@@ -1,8 +1,34 @@
 ## [Unreleased]
 
-## [0.1.0] - 2026-06-08
+## [0.1.0] - 2026-06-16
 
-- Initial CDC source adapter implementation.
-- Added `Pgoutput::SourceAdapter::Cdc`.
-- Added normalization from `Pgoutput::Decoder::Events` to `CDC::Core::ChangeEvent`.
-- Added transaction batch normalization to `CDC::Core::TransactionEnvelope`.
+### Added
+
+- Initial release of pgoutput-source-adapter.
+- CDC::Core source adapter implementation.
+- Normalization of decoded pgoutput Insert events into CDC::Core::ChangeEvent.
+- Normalization of decoded pgoutput Update events into CDC::Core::ChangeEvent.
+- Normalization of decoded pgoutput Delete events into CDC::Core::ChangeEvent.
+- Normalization of transaction boundaries into CDC::Core::TransactionEnvelope.
+- Configurable primary key resolution.
+- Configurable metadata generation.
+- Namespace compatibility aliases.
+
+### Documentation
+
+- Expanded YARD documentation.
+- Added architecture and usage examples.
+- Improved API documentation coverage.
+- Added descriptions for public YARD tags.
+
+### Quality
+
+- Added comprehensive unit tests.
+- Added SimpleCov line and branch coverage reporting.
+- Added Steep type checking support.
+- Added RuboCop integration.
+
+### Coverage
+
+- Line Coverage: 97.62%
+- Branch Coverage: 91.18%

data/Rakefile

@@ -17,6 +17,7 @@ end
 
 YARD::Rake::YardocTask.new(:yard)
 
+desc 'Validate rbs sig files'
 task :steep do
   sh 'bundle exec steep check'
 end

data/Steepfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Steepfile
+target :lib do
+  signature 'sig'
+  check 'lib'
+
+  library 'cdc-core'
+end

data/lib/pgoutput/source_adapter/cdc.rb

@@ -49,6 +49,7 @@ module Pgoutput
       #   nil for transaction boundary events.
       # @raise [Pgoutput::SourceAdapter::Error] when the decoded event type is
       #   unsupported.
+      # rubocop:disable Metrics/MethodLength
       def normalize(event)
         case event_name(event)
         when 'Insert'
@@ -85,6 +86,7 @@ module Pgoutput
           raise Error, "unsupported pgoutput decoded event: #{event.class}"
         end
       end
+      # rubocop:enable Metrics/MethodLength
 
       # Normalize a sequence of decoded pgoutput events.
       #
@@ -97,11 +99,15 @@ module Pgoutput
       #   normalized row changes and transaction envelopes in input order.
       # @raise [Pgoutput::SourceAdapter::Error] when any decoded event type is
       #   unsupported.
+      # rubocop:disable Metrics/AbcSize
+      # rubocop:disable Metrics/PerceivedComplexity
+      # rubocop:disable Metrics/CyclomaticComplexity
+      # rubocop:disable Metrics/MethodLength
       def normalize_many(events)
-        results = [] # : [Array[CDC::Core::ChangeEvent, CDC::Core::TransactionEnvelope]]
+        results = [] # : Array[CDC::Core::ChangeEvent | CDC::Core::TransactionEnvelope]
         transaction_id = nil
-        transaction_events = []
-        transaction_metadata = {}
+        transaction_events = [] # : Array[CDC::Core::ChangeEvent]
+        transaction_metadata = {} # : Hash[String, untyped]
 
         events.each do |event|
           case event_name(event)
@@ -140,6 +146,10 @@ module Pgoutput
         results.concat(transaction_events) if transaction_id && !transaction_events.empty?
         share(results.freeze)
       end
+      # rubocop:enable Metrics/AbcSize
+      # rubocop:enable Metrics/PerceivedComplexity
+      # rubocop:enable Metrics/CyclomaticComplexity
+      # rubocop:enable Metrics/MethodLength
 
       private
 

data/lib/pgoutput/source_adapter/version.rb

@@ -5,6 +5,6 @@ module Pgoutput
     # Current pgoutput-source-adapter gem version.
     #
     # @return [String] semantic version published to RubyGems.
-    VERSION = '0.0.0'
+    VERSION = '0.1.0'
   end
 end

data/sig/pgoutput/source_adapter/cdc.rbs

@@ -0,0 +1,81 @@
+module Pgoutput
+  module SourceAdapter
+    # Normalizes Pgoutput::Decoder::Events into CDC::Core primitives.
+    #
+    # This adapter is intentionally located under the Pgoutput namespace because
+    # it adapts pgoutput decoded events. The target is CDC::Core, so this class
+    # depends on cdc-core while the lower-level pgoutput-client, pgoutput-parser,
+    # and pgoutput-decoder gems remain standalone.
+    #
+    # @example Normalize a decoded insert event
+    #   adapter = Pgoutput::SourceAdapter::Cdc.new
+    #   change_event = adapter.normalize(decoded_insert)
+    #
+    # @example Normalize a decoded transaction event batch
+    #   envelope = adapter.normalize_many([begin_event, insert_event, commit_event]).first
+    #
+    # @api public
+    class Cdc < CDC::Core::SourceAdapter
+      @primary_key_resolver: untyped
+
+      @metadata_builder: untyped
+
+      SOURCE_NAME: "pgoutput"
+
+      # @param primary_key_resolver [#call, nil] optional callable used to infer
+      #   primary keys from decoded row values when pgoutput does not provide an
+      #   old-key tuple.
+      # @param metadata_builder [#call, nil] optional callable that can return
+      #   extra metadata for each decoded event.
+      def initialize: (?primary_key_resolver: untyped?, ?metadata_builder: untyped?) -> void
+
+      # Normalize one decoded pgoutput event.
+      #
+      # Transaction boundary events return nil because they do not represent a
+      # row-level change by themselves. Use #normalize_many when transaction
+      # envelopes are desired.
+      #
+      # @param event [Object] a Pgoutput::Decoder::Events object.
+      # @return [CDC::Core::ChangeEvent, nil]
+      def normalize: (untyped event) -> untyped
+
+      # Normalize a sequence of decoded pgoutput events.
+      #
+      # If the sequence contains transaction boundaries, row changes between a
+      # Begin and Commit are grouped into CDC::Core::TransactionEnvelope. If no
+      # transaction boundaries are present, row changes are returned individually.
+      #
+      # @param events [Enumerable<Object>] decoded pgoutput events.
+      # @return [Array<CDC::Core::ChangeEvent, CDC::Core::TransactionEnvelope>]
+      def normalize_many: (untyped events) -> untyped
+
+      private
+
+      attr_reader primary_key_resolver: untyped
+
+      attr_reader metadata_builder: untyped
+
+      def change_event: (untyped event, operation: untyped, old_values: untyped, new_values: untyped, primary_key: untyped) -> untyped
+
+      def transaction_envelope: (untyped event, transaction_id: untyped, events: untyped, metadata: untyped) -> untyped
+
+      def primary_key_for: (untyped event, untyped values) -> untyped
+
+      def default_primary_key: (untyped _event, untyped values) -> (nil | untyped)
+
+      def metadata_for: (untyped event) -> untyped
+
+      def relation_id_for: (untyped event) -> (untyped | nil)
+
+      def event_name: (untyped event) -> untyped
+
+      def lsn_string: (untyped lsn) -> untyped
+
+      def stringify_keys: (untyped hash) -> untyped
+
+      def compact: (untyped hash) -> untyped
+
+      def share: (untyped object) -> untyped
+    end
+  end
+end

data/sig/pgoutput/source_adapter/version.rbs

@@ -0,0 +1,6 @@
+module Pgoutput
+  module SourceAdapter
+    # Current pgoutput-source-adapter gem version.
+    VERSION: String
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgoutput-source-adapter
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -52,6 +52,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- Steepfile
 - lib/pgoutput/source/adapter.rb
 - lib/pgoutput/source_adapter.rb
 - lib/pgoutput/source_adapter/cdc.rb
@@ -59,6 +60,8 @@ files:
 - mise.toml
 - sig/pgoutput/source/adapter.rbs
 - sig/pgoutput/source_adapter.rbs
+- sig/pgoutput/source_adapter/cdc.rbs
+- sig/pgoutput/source_adapter/version.rbs
 homepage: https://github.com/kanutocd/pgoutput-source-adapter
 licenses:
 - MIT