cdc-core 0.1.2 → 0.1.3

data/sig/cdc/core/processor_result.rbs

@@ -1,137 +1,44 @@
 module CDC
   module Core
-    # Result returned by processors and pipelines.
-    #
-    # ProcessorResult standardizes processor outcomes so callers can distinguish
-    # successful processing, skipped events, and failures without relying on
-    # processor-specific return values.
     class ProcessorResult
-      VALID_STATUSES: untyped
-      @status: untyped
+      VALID_STATUSES: ::Array[Symbol]
+      EMPTY_METADATA: metadata_hash
 
-      @event: untyped
-
-      @value: untyped
-
-      @error: untyped
-
-      @metadata: untyped
-
-      # @return [Symbol] result status
-      # @return [ChangeEvent, nil] event associated with the result
-      # @return [Exception, nil] failure error, when status is :failure
-      # @return [EventMetadata] result metadata
-      attr_reader status: untyped
-
-      # @return [Symbol] result status
-      # @return [ChangeEvent, nil] event associated with the result
-      # @return [Exception, nil] failure error, when status is :failure
-      # @return [EventMetadata] result metadata
+      attr_reader status: Symbol
       attr_reader event: untyped
-
-      # @return [Object, nil] value produced by the processor
       attr_reader value: untyped
-
-      # @return [Symbol] result status
-      # @return [ChangeEvent, nil] event associated with the result
-      # @return [Exception, nil] failure error, when status is :failure
-      # @return [EventMetadata] result metadata
-      attr_reader error: untyped
-
-      # @return [Symbol] result status
-      # @return [ChangeEvent, nil] event associated with the result
-      # @return [Exception, nil] failure error, when status is :failure
-      # @return [EventMetadata] result metadata
-      attr_reader metadata: untyped
-
-      # Build a successful result.
-      #
-      # @param event [ChangeEvent, nil] processed event
-      # @param metadata [Hash, EventMetadata] result metadata
-      # @return [ProcessorResult]
-      def self.success: (?untyped? event, ?metadata: ::Hash[untyped, untyped], ?value: untyped?) -> untyped
-
-      # Build a failure result.
-      #
-      # @param error [Exception] processor error
-      # @param event [ChangeEvent, nil] event being processed
-      # @param reason [String, nil] human-readable failure reason
-      # @param retryable [Boolean, nil] whether the failure can be retried
-      # @param processor [String, nil] processor name associated with the failure
-      # @param failed_at [String, nil] timestamp for when the failure occurred
-      # @param metadata [Hash, EventMetadata] result metadata
-      # @return [ProcessorResult]
-      def self.failure: (untyped error, ?event: untyped?, ?reason: untyped?, ?retryable: untyped?, ?processor: untyped?, ?failed_at: untyped?, ?metadata: untyped) -> untyped
-
-      # Build a skipped result.
-      #
-      # @param event [ChangeEvent, nil] skipped event
-      # @param metadata [Hash, EventMetadata] result metadata
-      # @return [ProcessorResult]
-      def self.skipped: (?untyped? event, ?metadata: ::Hash[untyped, untyped]) -> untyped
-
-      # Build a processor result with an explicit status.
-      #
-      # @param status [#to_sym] result status
-      # @param event [ChangeEvent, nil] associated event
-      # @param error [Exception, nil] associated failure
-      # @param metadata [Hash, EventMetadata] result metadata
-      def initialize: (untyped status, ?event: untyped?, ?error: untyped?, ?metadata: ::Hash[untyped, untyped], ?value: untyped?) -> void
-
-      # @return [Boolean] true when status is :success
-      def success?: () -> untyped
-
-      # @return [Boolean] true when status is :failure
-      def failure?: () -> untyped
-
-      # @return [Boolean] true when status is :skipped
-      def skipped?: () -> untyped
-
-      # Human-readable failure reason, when present.
-      #
-      # @return [String, nil]
-      def failure_reason: () -> untyped
-
-      # Whether the failure is retryable.
-      #
-      # @return [Boolean]
+      attr_reader error: ::Exception?
+      attr_reader metadata: EventMetadata
+
+      def self.success: (?untyped event, ?metadata: EventMetadata | metadata_hash, ?value: untyped) -> ProcessorResult
+      def self.failure: (
+        ::Exception error,
+        ?event: untyped,
+        ?reason: String?,
+        ?retryable: bool?,
+        ?processor: String?,
+        ?failed_at: String?,
+        ?metadata: EventMetadata | metadata_hash?
+      ) -> ProcessorResult
+      def self.skipped: (?untyped event, ?metadata: EventMetadata | metadata_hash) -> ProcessorResult
+
+      def initialize: (Symbol | String status, ?event: untyped, ?error: ::Exception?, ?metadata: EventMetadata | metadata_hash, ?value: untyped) -> void
+      def success?: () -> bool
+      def failure?: () -> bool
+      def skipped?: () -> bool
+      def failure_reason: () -> String?
       def retryable?: () -> bool
-
-      # Name of the processor associated with the failure, when present.
-      #
-      # @return [String, nil]
-      def processor_name: () -> untyped
-
-      # Timestamp for when the failure occurred, when present.
-      #
-      # @return [String, nil]
-      def failed_at: () -> untyped
-
-      # Error class name, when present.
-      #
-      # @return [String, nil]
-      def error_class: () -> untyped
-
-      # Error message, when present.
-      #
-      # @return [String, nil]
-      def error_message: () -> untyped
-
-      # Error backtrace, when present.
-      #
-      # @return [Array<String>]
-      def error_backtrace: () -> untyped
-
-      # Convert the result into a shareable hash.
-      #
-      # @return [Hash{String=>Object,nil}]
-      def to_h: () -> untyped
+      def processor_name: () -> String?
+      def failed_at: () -> String?
+      def error_class: () -> String?
+      def error_message: () -> String?
+      def error_backtrace: () -> ::Array[String]
+      def to_h: () -> shareable_hash
 
       private
-
-      def make_shareable_when_possible: () -> untyped
-
-      def normalize_status: (untyped status) -> untyped
+      
+      def make_shareable_when_possible: () -> self?
+      def normalize_status: (Symbol | String status) -> Symbol
     end
   end
 end

data/sig/cdc/core/router.rbs

@@ -1,24 +1,23 @@
 module CDC
   module Core
-    # Routes CDC work items to the appropriate handler.
     class Router
-      @processor: untyped
-      @transaction_processor: untyped
-      @observer: untyped
+      attr_reader processor: _RoutableProcessor
+      attr_reader transaction_processor: _ProcessorLike?
+      attr_reader observer: Observer
 
-      attr_reader processor: untyped
-      attr_reader transaction_processor: untyped
-      attr_reader observer: untyped
-
-      def initialize: (processor: untyped, ?transaction_processor: untyped?, ?observer: untyped?) -> void
-      def process: (untyped item) -> untyped
+      def initialize: (
+        processor: _RoutableProcessor,
+        ?transaction_processor: _ProcessorLike?,
+        ?observer: Observer?
+      ) -> void
+      
+      def process: (work_item item) -> untyped
 
       private
 
-      def route_transaction: (untyped transaction) -> untyped
-      def route_many: (untyped items) -> untyped
+      def route_transaction: (TransactionEnvelope transaction) -> untyped
+      def route_many: (::Array[untyped] items) -> untyped
       def observe_result: (untyped result) -> untyped
-      def observe_results: (untyped results) -> untyped
     end
   end
 end

data/sig/cdc/core/source_adapter.rbs

@@ -1,10 +1,8 @@
-# Base class for source adapters that normalize upstream payloads into CDC
-# core domain objects.
 module CDC
   module Core
     class SourceAdapter
-      def normalize: (untyped input) -> untyped
-      def normalize_many: (untyped inputs) -> ::Array[untyped]
+      def normalize: (untyped input) -> normalized_object
+      def normalize_many: (::Enumerable[untyped] inputs) -> ::Array[ChangeEvent | TransactionEnvelope]
     end
   end
 end

data/sig/cdc/core/transaction_envelope.rbs

@@ -1,79 +1,25 @@
 module CDC
   module Core
-    # Immutable group of change events committed in one transaction.
-    #
-    # TransactionEnvelope is useful when a downstream processor needs transaction
-    # boundaries instead of isolated row-level events. The contained events and
-    # metadata are Ractor-shareable when construction succeeds.
     class TransactionEnvelope
-      @transaction_id: untyped
+      EMPTY_METADATA: metadata_hash
 
-      @events: untyped
-
-      @commit_lsn: untyped
-
-      @committed_at: untyped
-
-      @metadata: untyped
-
-      # @return [Object] transaction identifier
-      # @return [Array<ChangeEvent>] events committed by the transaction
-      # @return [String, nil] commit log sequence number
-      # @return [Time, nil] commit timestamp
-      # @return [EventMetadata] transaction metadata
       attr_reader transaction_id: untyped
-
-      # @return [Object] transaction identifier
-      # @return [Array<ChangeEvent>] events committed by the transaction
-      # @return [String, nil] commit log sequence number
-      # @return [Time, nil] commit timestamp
-      # @return [EventMetadata] transaction metadata
-      attr_reader events: untyped
-
-      # @return [Object] transaction identifier
-      # @return [Array<ChangeEvent>] events committed by the transaction
-      # @return [String, nil] commit log sequence number
-      # @return [Time, nil] commit timestamp
-      # @return [EventMetadata] transaction metadata
-      attr_reader commit_lsn: untyped
-
-      # @return [Object] transaction identifier
-      # @return [Array<ChangeEvent>] events committed by the transaction
-      # @return [String, nil] commit log sequence number
-      # @return [Time, nil] commit timestamp
-      # @return [EventMetadata] transaction metadata
-      attr_reader committed_at: untyped
-
-      # @return [Object] transaction identifier
-      # @return [Array<ChangeEvent>] events committed by the transaction
-      # @return [String, nil] commit log sequence number
-      # @return [Time, nil] commit timestamp
-      # @return [EventMetadata] transaction metadata
-      attr_reader metadata: untyped
-
-      # Build a transaction envelope.
-      #
-      # @param transaction_id [Object] upstream transaction identifier
-      # @param events [Array<ChangeEvent>] committed events
-      # @param commit_lsn [#to_s, nil] commit log sequence number
-      # @param committed_at [Time, nil] commit timestamp
-      # @param metadata [Hash, EventMetadata] transaction metadata
-      def initialize: (transaction_id: untyped, events: untyped, ?commit_lsn: untyped?, ?committed_at: untyped?, ?metadata: ::Hash[untyped, untyped]) -> void
-
-      # Whether the envelope has no events.
-      #
-      # @return [Boolean]
-      def empty?: () -> untyped
-
-      # Number of events in the envelope.
-      #
-      # @return [Integer]
-      def size: () -> untyped
-
-      # Convert the transaction envelope into a Ractor-shareable hash.
-      #
-      # @return [Hash{String=>Object,nil}]
-      def to_h: () -> untyped
+      attr_reader events: ::Array[ChangeEvent]
+      attr_reader commit_lsn: String?
+      attr_reader committed_at: ::Time?
+      attr_reader metadata: EventMetadata
+
+      def initialize: (
+        transaction_id: untyped,
+        events: ::Array[ChangeEvent],
+        ?commit_lsn: String?,
+        ?committed_at: ::Time?,
+        ?metadata: EventMetadata | metadata_hash
+      ) -> void
+
+      def empty?: () -> bool
+      def size: () -> Integer
+      def to_h: () -> shareable_hash
     end
   end
 end

data/sig/cdc/core/version.rbs

@@ -1,6 +1,5 @@
 module CDC
   module Core
-    # Current gem version.
-    VERSION: "0.1.0"
+    VERSION: String
   end
 end

data/sig/cdc/core.rbs

@@ -1,11 +1,32 @@
-# Top-level namespace for Change Data Capture libraries.
 module CDC
-  # Database-agnostic Change Data Capture domain primitives.
-  #
-  # CDC::Core intentionally contains only lightweight runtime abstractions:
-  # events, metadata, processors, filters, pipelines, and processor results.
-  # Transport, PostgreSQL protocol parsing, and value decoding live in sibling
-  # gems so this layer can remain independently useful.
   module Core
+    type metadata_hash = ::Hash[untyped, untyped]
+    type metric_tags = ::Hash[String, untyped]
+    type shareable_hash = ::Hash[untyped, untyped]
+    type event_values = ::Hash[String, untyped]
+    type core_object = ChangeEvent | TransactionEnvelope
+    type normalized_object = ChangeEvent | TransactionEnvelope | ::Array[ChangeEvent] | ::Array[TransactionEnvelope]
+    type work_item = ChangeEvent | TransactionEnvelope | ::Array[ChangeEvent]
+
+    interface _ProcessorLike
+      def class: () -> singleton(::Object)
+      def respond_to?: (Symbol | String method_name, ?bool include_private) -> bool
+      def ractor_safe?: () -> bool
+      def process: (untyped input) -> untyped
+    end
+
+    interface _RoutableProcessor
+      def class: () -> singleton(::Object)
+      def respond_to?: (Symbol | String method_name, ?bool include_private) -> bool
+      def process: (untyped input) -> untyped
+      def process_many: (::Array[untyped] inputs) -> untyped
+    end
+    interface _BatchProcessorLike
+      def process_many: (::Enumerable[untyped] inputs) -> untyped
+    end
+
+    interface _FilterLike
+      def match?: (ChangeEvent event) -> bool
+    end
   end
 end

data/sig/cdc_core.rbs

@@ -0,0 +1,4 @@
+module CDC
+  module Core
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cdc-core
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -92,5 +92,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Source-agnostic Change Data Capture contracts and domain primitives for Ruby..
+summary: Source-agnostic Change Data Capture contracts and domain primitives for Ruby.
 test_files: []