pgoutput-source-adapter 0.0.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c0d3598bffe622103beb9a3f48c750476dcb06ec81b6d675d3a9b4628d61d1d
-  data.tar.gz: b4ab4d056f6d9f34620c88d78d28ddc6ccf678463b9975b3e4ad02328d7a61cb
+  metadata.gz: ab9b7c87b7ede5dd583ae9457f30fe30fdfcf1dd55b2ca33e08162d23f36601b
+  data.tar.gz: 5c7a7b1a081f8a67a07397ecd8034a462e679e636dd2a51d71b9512e90333c85
 SHA512:
-  metadata.gz: 80770110f68b77ac080ebd48fe637f8bf7cb3e054e9c9345523535c27f3f8ab35f0c8e4d3ea5387aedbd6bdfc959795556644e2b5a18685c6749dd541ff2b3a7
-  data.tar.gz: '08b336516e7466179039bbc9a1a8874e96d70d3f9511566ae520e2417a373817ba716bbb20226e606ab532da1f6e00805bdb0da9a025f4d02f1a064bbb1bfdcd'
+  metadata.gz: 3a19f060ba7f5552dec37471a114fa4ee30f0c960d20a27c82676f888753c53fe76c4473038170185806dda76988217ab882cf90f5186fdfa28d5dfef438c12a
+  data.tar.gz: 00f2d815d0ff8f2d8b9865ecdbee82c528fba3341ecf0125c8f32ddc930365c669bb28ad0cc3c1274c7208089a4eca9ff05bf6d47a9061b234563c92b9c3fd18

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.1'
   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.1
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -37,8 +37,16 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.1'
-description: Normalizes pgoutput decoded events into downstream change-event platform
-  primitives, including CDC::Core.
+description: |
+  pgoutput-source-adapter provides source adapters that normalize
+  decoded PostgreSQL pgoutput events into downstream event models.
+
+  The gem currently includes a CDC::Core adapter that transforms
+  pgoutput decoder events into ChangeEvent and TransactionEnvelope
+  primitives while preserving transaction and metadata context.
+
+  This package forms the normalization boundary between the
+  pgoutput family of gems and downstream change-event platforms.
 email:
 - kenneth.c.demanawa@gmail.com
 executables: []
@@ -52,6 +60,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 +68,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
@@ -84,5 +95,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Source adapters for pgoutput decoded events.
+summary: Source adapters that normalize pgoutput decoded events into downstream change-event
+  platforms.
 test_files: []