dbwatcher 0.1.5 → 1.0.0

data/lib/dbwatcher/storage/concerns/timestampable.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Dbwatcher
+  module Storage
+    module Concerns
+      # Provides timestamping capabilities for storage objects
+      #
+      # This concern adds created_at and updated_at functionality to storage
+      # objects, following Rails conventions for timestamp management.
+      #
+      # @example
+      #   class SessionStorage < BaseStorage
+      #     include Concerns::Timestampable
+      #   end
+      module Timestampable
+        def self.included(base)
+          base.attr_reader :created_at, :updated_at
+        end
+
+        # Sets initial timestamps on creation
+        #
+        # @return [void]
+        def initialize_timestamps
+          now = current_time
+          @created_at = now
+          @updated_at = now
+        end
+
+        # Updates the updated_at timestamp
+        #
+        # @return [Time] the new updated_at timestamp
+        def touch_updated_at
+          @updated_at = current_time
+        end
+
+        # Calculates age since creation
+        #
+        # @return [Float] age in seconds since creation
+        def age
+          current_time - created_at
+        end
+
+        # Checks if the object was recently created
+        #
+        # @param threshold [Integer] threshold in seconds (default: 1 hour)
+        # @return [Boolean] true if created within threshold
+        def recently_created?(threshold = 3600)
+          age < threshold
+        end
+
+        # Checks if the object was recently updated
+        #
+        # @param threshold [Integer] threshold in seconds (default: 1 hour)
+        # @return [Boolean] true if updated within threshold
+        def recently_updated?(threshold = 3600)
+          (current_time - updated_at) < threshold
+        end
+
+        private
+
+        # Returns current time (compatible with and without Rails)
+        #
+        # @return [Time] current time
+        def current_time
+          if defined?(Time.current)
+            Time.current
+          else
+            Time.now
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dbwatcher/storage/concerns/validatable.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Dbwatcher
+  module Storage
+    module Concerns
+      # Provides validation capabilities for storage classes
+      #
+      # This concern adds common validation methods and patterns used
+      # across different storage implementations.
+      #
+      # @example
+      #   class MyStorage < BaseStorage
+      #     include Concerns::Validatable
+      #
+      #     def save(data)
+      #       validate_presence!(data, :id, :name)
+      #       # save logic
+      #     end
+      #   end
+      module Validatable
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        module ClassMethods
+          # Defines required attributes for validation
+          #
+          # @param attributes [Array<Symbol>] list of required attributes
+          # @return [void]
+          def validates_presence_of(*attributes)
+            @required_attributes = attributes
+          end
+
+          # Returns list of required attributes
+          #
+          # @return [Array<Symbol>] required attributes
+          def required_attributes
+            @required_attributes || []
+          end
+        end
+
+        # Validates presence of required attributes
+        #
+        # @param data [Hash] data to validate
+        # @param attributes [Array<Symbol>] specific attributes to check
+        # @raise [ValidationError] if any required attribute is missing
+        # @return [void]
+        def validate_presence!(data, *attributes)
+          attrs_to_check = attributes.any? ? attributes : self.class.required_attributes
+
+          attrs_to_check.each do |attr|
+            next if data.key?(attr) && !blank_value?(data[attr])
+
+            raise ValidationError, "#{attr} is required but was #{data[attr].inspect}"
+          end
+        end
+
+        # Validates that an ID is present and valid
+        #
+        # @param id [String, Integer, nil] ID to validate
+        # @raise [ValidationError] if ID is invalid
+        # @return [void]
+        def validate_id!(id)
+          return unless id.nil? || id.to_s.strip.empty?
+
+          raise ValidationError, "ID cannot be nil or empty"
+        end
+
+        # Validates that a name is present and valid
+        #
+        # @param name [String, nil] name to validate
+        # @raise [ValidationError] if name is invalid
+        # @return [void]
+        def validate_name!(name)
+          return unless name.nil? || name.to_s.strip.empty?
+
+          raise ValidationError, "Name cannot be nil or empty"
+        end
+
+        # Checks if an ID is valid
+        #
+        # @param id [String, Integer, nil] ID to check
+        # @return [Boolean] true if ID is valid
+        def valid_id?(id)
+          !id.nil? && !id.to_s.strip.empty?
+        end
+
+        # Checks if a name is valid
+        #
+        # @param name [String, nil] name to check
+        # @return [Boolean] true if name is valid
+        def valid_name?(name)
+          !name.nil? && !name.to_s.strip.empty?
+        end
+
+        private
+
+        # Checks if a value should be considered blank
+        #
+        # @param value [Object] value to check
+        # @return [Boolean] true if value is blank
+        def blank_value?(value)
+          case value
+          when String
+            value.strip.empty?
+          when Array, Hash
+            value.empty?
+          when NilClass
+            true
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dbwatcher/storage/date_helper.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Dbwatcher
+  module Storage
+    module DateHelper
+      DEFAULT_CLEANUP_DAYS = 30
+
+      def format_date(timestamp)
+        timestamp.strftime("%Y-%m-%d")
+      end
+
+      def cleanup_cutoff_date(days_to_keep = DEFAULT_CLEANUP_DAYS)
+        Time.now - (days_to_keep * 24 * 60 * 60)
+      end
+
+      def date_file_path(base_path, date)
+        File.join(base_path, "#{date}.json")
+      end
+    end
+  end
+end

data/lib/dbwatcher/storage/errors.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Dbwatcher
+  module Storage
+    # Base storage error class
+    #
+    # All storage-related errors inherit from this class to provide
+    # consistent error handling across the storage module.
+    class StorageError < StandardError; end
+
+    # Raised when validation fails on storage operations
+    class ValidationError < StorageError; end
+
+    # Raised when a requested session cannot be found
+    class SessionNotFoundError < StorageError; end
+
+    # Raised when a requested query cannot be found
+    class QueryNotFoundError < StorageError; end
+
+    # Raised when a requested table cannot be found
+    class TableNotFoundError < StorageError; end
+
+    # Raised when storage data becomes corrupted
+    class CorruptedDataError < StorageError; end
+
+    # Raised when storage permissions are insufficient
+    class PermissionError < StorageError; end
+
+    # Provides error handling capabilities for storage operations
+    #
+    # This module can be included in storage classes to provide
+    # standardized error handling and logging capabilities.
+    #
+    # @example
+    #   class MyStorage
+    #     include ErrorHandler
+    #
+    #     def risky_operation
+    #       safe_operation("my operation") do
+    #         # potentially failing code
+    #       end
+    #     end
+    #   end
+    module ErrorHandler
+      # Executes a block with error handling and optional default return value
+      #
+      # @param operation_name [String] description of the operation for logging
+      # @param default_value [Object] value to return if operation fails
+      # @yield [] the block to execute safely
+      # @return [Object] the result of the block or default_value on error
+      def safe_operation(operation_name, default_value = nil, &block)
+        block.call
+      rescue JSON::ParserError => e
+        log_error("JSON parsing failed in #{operation_name}", e)
+        default_value
+      rescue StandardError => e
+        log_error("#{operation_name} failed", e)
+        default_value
+      end
+
+      # Executes a block with error handling that raises StorageError on failure
+      #
+      # @param operation [String] description of the operation
+      # @yield [] the block to execute
+      # @return [Object] the result of the block
+      # @raise [StorageError] if the operation fails
+      def with_error_handling(operation, &block)
+        block.call
+      rescue StandardError => e
+        warn "Storage #{operation} failed: #{e.message}"
+        raise StorageError, "#{operation} failed: #{e.message}"
+      end
+
+      private
+
+      # Logs an error message with exception details
+      #
+      # @param message [String] the error message
+      # @param error [Exception] the exception that occurred
+      # @return [void]
+      def log_error(message, error)
+        warn "#{message}: #{error.message}"
+      end
+    end
+  end
+end

data/lib/dbwatcher/storage/file_manager.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Dbwatcher
+  module Storage
+    # Manages file system operations for storage classes
+    #
+    # This class provides a centralized interface for file operations
+    # including JSON serialization, directory management, and file
+    # system utilities used throughout the storage module.
+    #
+    # @example
+    #   manager = FileManager.new("/path/to/storage")
+    #   manager.write_json("data.json", { key: "value" })
+    #   data = manager.read_json("data.json")
+    class FileManager
+      # @return [String] the base storage path
+      attr_reader :storage_path
+
+      # Initializes file manager with storage path
+      #
+      # Creates the base storage directory if it doesn't exist.
+      #
+      # @param storage_path [String] base path for file operations
+      def initialize(storage_path)
+        @storage_path = storage_path
+        ensure_directories
+      end
+
+      # Writes data to a JSON file
+      #
+      # Serializes the provided data as pretty-printed JSON and writes
+      # it to the specified file path.
+      #
+      # @param file_path [String] path to write the JSON file
+      # @param data [Object] data to serialize as JSON
+      # @return [Integer] number of bytes written
+      # @raise [JSON::GeneratorError] if data cannot be serialized
+      def write_json(file_path, data)
+        # Ensure parent directory exists
+        ensure_directory(File.dirname(file_path))
+        File.write(file_path, JSON.pretty_generate(data))
+      end
+
+      # Reads and parses a JSON file
+      #
+      # Reads the specified file and parses it as JSON with symbolized keys.
+      # Returns empty array if file doesn't exist.
+      #
+      # @param file_path [String] path to the JSON file
+      # @return [Object] parsed JSON data with symbolized keys
+      # @raise [JSON::ParserError] if file contains invalid JSON
+      def read_json(file_path)
+        return default_empty_result unless File.exist?(file_path)
+
+        JSON.parse(File.read(file_path), symbolize_names: true)
+      end
+
+      # Checks if a file exists
+      #
+      # @param file_path [String] path to check
+      # @return [Boolean] true if file exists
+      def file_exists?(file_path)
+        File.exist?(file_path)
+      end
+
+      # Deletes a file
+      #
+      # @param file_path [String] path to file to delete
+      # @return [Integer] number of files deleted (1 or 0)
+      def delete_file(file_path)
+        File.delete(file_path)
+      end
+
+      # Deletes a directory and its contents
+      #
+      # @param dir_path [String] path to directory to delete
+      # @return [Boolean] true if directory was deleted, false if it didn't exist
+      def delete_directory(dir_path)
+        return false unless Dir.exist?(dir_path)
+
+        FileUtils.rm_rf(dir_path)
+        true
+      rescue Errno::ENOENT
+        false
+      end
+
+      # Returns files matching a glob pattern
+      #
+      # @param pattern [String] glob pattern to match
+      # @return [Array<String>] array of matching file paths
+      def glob_files(pattern)
+        Dir.glob(pattern)
+      end
+
+      # Ensures a directory exists
+      #
+      # Creates the directory and any necessary parent directories.
+      #
+      # @param path [String] directory path to create
+      # @return [Array, nil] array of created directories or nil if already exists
+      def ensure_directory(path)
+        FileUtils.mkdir_p(path)
+      end
+
+      private
+
+      # Creates the base storage directory
+      #
+      # @return [Array, nil] array of created directories or nil if already exists
+      def ensure_directories
+        FileUtils.mkdir_p(@storage_path)
+      end
+
+      # Default return value for empty JSON files
+      #
+      # @return [Array] empty array as default
+      def default_empty_result
+        []
+      end
+    end
+  end
+end

data/lib/dbwatcher/storage/null_session.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Dbwatcher
+  module Storage
+    class NullSession
+      def self.instance
+        @instance ||= new
+      end
+
+      def id
+        nil
+      end
+
+      def name
+        "Unknown Session"
+      end
+
+      def changes
+        []
+      end
+
+      def started_at
+        nil
+      end
+
+      def ended_at
+        nil
+      end
+
+      def present?
+        false
+      end
+
+      def nil?
+        true
+      end
+    end
+  end
+end