event_system 0.1.0

data/lib/event_system/storage/file_store.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require_relative 'base'
+
+module EventSystem
+  module Storage
+    # File-based event storage implementation
+    # Events are stored in JSONL (JSON Lines) format, one event per line
+    class FileStore < Base
+      attr_reader :current_session, :storage_path
+
+      # Initialize a new file-based event store
+      # @param directory [String] The directory to store event files in
+      # @param session_id [String, nil] Optional session ID, defaults to timestamp
+      def initialize(directory = "event_logs", session_id = nil)
+        @directory = directory
+        @storage_path = directory
+        @current_session = session_id || Time.now.strftime("%Y%m%d_%H%M%S")
+        @current_file = nil
+
+        FileUtils.mkdir_p(@directory) unless Dir.exist?(@directory)
+      end
+
+      # Store an event to disk
+      # @param event [EventSystem::Event] The event to store
+      # @return [void]
+      def store(event)
+        ensure_file_open
+        @current_file.puts(event.to_json)
+        @current_file.flush # Ensure data is written immediately
+      end
+
+      # Query for events based on options
+      # This implementation loads the session and filters in memory
+      # For more advanced querying needs, consider using a database
+      # @param options [Hash] Query options
+      #   - type: [String] Filter by event type
+      #   - start_time: [Time] Filter events after this time
+      #   - end_time: [Time] Filter events before this time
+      #   - session_id: [String] Filter by session ID
+      #   - limit: [Integer] Limit number of results
+      # @return [Array<EventSystem::Event>] Matching events
+      def query(options = {})
+        session_id = options[:session_id] || @current_session
+        events = load_session(session_id)
+
+        # Filter by type
+        if options[:type]
+          events = events.select { |e| e.type == options[:type] }
+        end
+
+        # Filter by time range
+        if options[:start_time]
+          events = events.select { |e| e.timestamp >= options[:start_time] }
+        end
+
+        if options[:end_time]
+          events = events.select { |e| e.timestamp <= options[:end_time] }
+        end
+
+        # Sort by timestamp (oldest first)
+        events = events.sort_by(&:timestamp)
+
+        # Limit results
+        if options[:limit]
+          events = events.last(options[:limit])
+        end
+
+        events
+      end
+
+      # Load all events from a session
+      # @param session_id [String, nil] Session ID to load, or current session if nil
+      # @return [Array<EventSystem::Event>] Events from the session
+      def load_session(session_id = nil)
+        session_id ||= @current_session
+        events = []
+
+        # Try different filename patterns for backward compatibility
+        filename = find_session_file(session_id)
+        return [] unless filename && File.exist?(filename)
+
+        File.open(filename, "r") do |file|
+          file.each_line do |line|
+            next if line.strip.empty?
+
+            begin
+              events << EventSystem::Event.from_json(line)
+            rescue JSON::ParserError => e
+              # Skip malformed lines but log the error
+              warn "Skipping malformed event line: #{e.message}"
+            end
+          end
+        end
+
+        events
+      end
+
+      # List available sessions
+      # @return [Array<String>] List of session IDs
+      def list_sessions
+        Dir.glob(File.join(@directory, "events_*.jsonl")).map do |file|
+          File.basename(file).gsub(/^events_/, "").gsub(/\.jsonl$/, "")
+        end.sort
+      end
+
+      # Get the current session ID
+      # @return [String] Current session ID
+      def current_session
+        @current_session
+      end
+
+      # Switch to a different session
+      # @param session_id [String] The session ID to switch to
+      # @return [void]
+      def switch_session(session_id)
+        close_current_file
+        @current_session = session_id
+      end
+
+      # Create a new session
+      # @param session_id [String, nil] Optional session ID, defaults to timestamp
+      # @return [String] The new session ID
+      def create_session(session_id = nil)
+        close_current_file
+        @current_session = session_id || Time.now.strftime("%Y%m%d_%H%M%S")
+        @current_session
+      end
+
+      # Close the file handle
+      # @return [void]
+      def close
+        close_current_file
+      end
+
+      # Get storage statistics
+      # @return [Hash] Storage statistics
+      def stats
+        super.merge(
+          directory: @directory,
+          current_session_file: current_session_file,
+          total_sessions: list_sessions.length
+        )
+      end
+
+      private
+
+      # Ensure the file is open for writing
+      # @return [void]
+      def ensure_file_open
+        return if @current_file && !@current_file.closed?
+
+        @current_file = File.open(current_session_file, "a")
+      end
+
+      # Get the current session file path
+      # @return [String] Path to the current session file
+      def current_session_file
+        File.join(@directory, "events_#{@current_session}.jsonl")
+      end
+
+      # Close the current file if it's open
+      # @return [void]
+      def close_current_file
+        @current_file&.close
+        @current_file = nil
+      end
+
+      # Find the session file using different naming patterns
+      # @param session_id [String] The session ID to find
+      # @return [String, nil] Path to the session file or nil if not found
+      def find_session_file(session_id)
+        # Try with events_ prefix first
+        filename = File.join(@directory, "events_#{session_id}.jsonl")
+        return filename if File.exist?(filename)
+
+        # Try without events_ prefix for backward compatibility
+        filename = File.join(@directory, "#{session_id}.jsonl")
+        return filename if File.exist?(filename)
+
+        nil
+      end
+    end
+  end
+end

data/lib/event_system/storage/memory_store.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module EventSystem
+  module Storage
+    # In-memory event storage implementation
+    # Perfect for testing, development, or short-lived applications
+    class MemoryStore < Base
+      attr_reader :current_session
+
+      # Initialize a new memory-based event store
+      # @param session_id [String, nil] Optional session ID, defaults to timestamp
+      def initialize(session_id = nil)
+        @events = []
+        @current_session = session_id || Time.now.strftime("%Y%m%d_%H%M%S")
+        @sessions = { @current_session => [] }
+      end
+
+      # Store an event in memory
+      # @param event [EventSystem::Event] The event to store
+      # @return [void]
+      def store(event)
+        @events << event
+        @sessions[@current_session] << event
+      end
+
+      # Query for events based on options
+      # @param options [Hash] Query options
+      #   - type: [String] Filter by event type
+      #   - start_time: [Time] Filter events after this time
+      #   - end_time: [Time] Filter events before this time
+      #   - session_id: [String] Filter by session ID
+      #   - limit: [Integer] Limit number of results
+      # @return [Array<EventSystem::Event>] Matching events
+      def query(options = {})
+        # Use session-specific events by default, or global events if no session specified
+        if options[:session_id]
+          events = @sessions[options[:session_id]] || []
+        else
+          # For backward compatibility, use global events when no session specified
+          events = @events.dup
+        end
+
+        # Filter by type
+        if options[:type]
+          events = events.select { |e| e.type == options[:type] }
+        end
+
+        # Filter by time range
+        if options[:start_time]
+          events = events.select { |e| e.timestamp >= options[:start_time] }
+        end
+
+        if options[:end_time]
+          events = events.select { |e| e.timestamp <= options[:end_time] }
+        end
+
+        # Sort by timestamp (oldest first)
+        events = events.sort_by(&:timestamp)
+
+        # Limit results
+        if options[:limit]
+          events = events.last(options[:limit])
+        end
+
+        events
+      end
+
+      # Load all events from a session
+      # @param session_id [String, nil] Session ID to load, or current session if nil
+      # @return [Array<EventSystem::Event>] Events from the session
+      def load_session(session_id = nil)
+        session_id ||= @current_session
+        @sessions[session_id] || []
+      end
+
+      # List available sessions
+      # @return [Array<String>] List of session IDs
+      def list_sessions
+        @sessions.keys.sort
+      end
+
+      # Get the current session ID
+      # @return [String] Current session ID
+      def current_session
+        @current_session
+      end
+
+      # Switch to a different session
+      # @param session_id [String] The session ID to switch to
+      # @return [void]
+      def switch_session(session_id)
+        @current_session = session_id
+        @sessions[session_id] ||= []
+      end
+
+      # Create a new session
+      # @param session_id [String, nil] Optional session ID, defaults to timestamp
+      # @return [String] The new session ID
+      def create_session(session_id = nil)
+        session_id ||= Time.now.strftime("%Y%m%d_%H%M%S")
+        @sessions[session_id] = []
+        @current_session = session_id
+        session_id
+      end
+
+      # Clear all events from memory
+      # @return [void]
+      def clear!
+        @events.clear
+        @sessions.clear
+        @current_session = Time.now.strftime("%Y%m%d_%H%M%S")
+        @sessions[@current_session] = []
+      end
+
+      # Get total number of events stored
+      # @return [Integer] Total event count
+      def size
+        @events.length
+      end
+
+      # Get storage statistics
+      # @return [Hash] Storage statistics
+      def stats
+        super.merge(
+          total_events: @events.length,
+          sessions: @sessions.keys.length,
+          current_session_events: @sessions[@current_session]&.length || 0
+        )
+      end
+    end
+  end
+end

data/lib/event_system/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module EventSystem
+  VERSION = "0.1.0"
+end

data/lib/event_system/visualization/timeline_generator.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'time'
+
+module EventSystem
+  module Visualization
+    # A utility class for generating HTML timeline visualizations of events
+    class TimelineGenerator
+      attr_reader :storage
+
+      # Initialize a new timeline generator
+      # @param storage [EventSystem::Storage::Base] The storage to read events from
+      def initialize(storage)
+        @storage = storage
+      end
+
+      # Generates HTML timeline visualization for a session
+      # @param session_id [String, nil] The session ID to visualize, or latest if nil
+      # @param output_file [String, nil] The HTML file path to write, or auto-generated if nil
+      # @return [String, nil] The path to the generated HTML file, or nil if no events
+      def generate_timeline(session_id = nil, output_file = nil)
+        session_id ||= latest_session_id
+        output_file ||= "event_timeline_#{session_id}.html"
+
+        events = @storage.load_session(session_id)
+        return nil if events.empty?
+
+        html = generate_html(events, session_id)
+
+        FileUtils.mkdir_p('event_visualizations')
+        output_path = File.join('event_visualizations', output_file)
+        File.write(output_path, html)
+
+        output_path
+      end
+
+      # Find the most recent session ID
+      # @return [String, nil] The latest session ID, or nil if no sessions
+      def latest_session_id
+        sessions = @storage.list_sessions
+        return nil if sessions.empty?
+
+        sessions.max
+      end
+
+      # Generate a summary of events by type
+      # @param session_id [String, nil] The session ID to analyze, or latest if nil
+      # @return [Hash] Summary statistics by event type
+      def event_summary(session_id = nil)
+        session_id ||= latest_session_id
+        events = @storage.load_session(session_id)
+
+        summary = Hash.new(0)
+        events.each do |event|
+          summary[event.type] += 1
+        end
+
+        summary
+      end
+
+      # Generate a timeline data structure (for custom visualizations)
+      # @param session_id [String, nil] The session ID to analyze, or latest if nil
+      # @return [Array<Hash>] Timeline data structure
+      def timeline_data(session_id = nil)
+        session_id ||= latest_session_id
+        events = @storage.load_session(session_id)
+
+        events.map do |event|
+          {
+            id: event.id,
+            type: event.type,
+            timestamp: event.timestamp.iso8601(3),
+            source: event.source_to_string,
+            data: event.data,
+            duration: calculate_duration(event, events)
+          }
+        end
+      end
+
+      private
+
+      # Generate HTML visualization
+      # @param events [Array<EventSystem::Event>] The events to visualize
+      # @param session_id [String] The session ID
+      # @return [String] HTML content
+      def generate_html(events, session_id)
+        timeline_data = events.map do |event|
+          {
+            id: event.id,
+            type: event.type,
+            timestamp: event.timestamp.iso8601(3),
+            source: event.source_to_string,
+            data: event.data
+          }
+        end
+
+        <<~HTML
+          <!DOCTYPE html>
+          <html lang="en">
+          <head>
+              <meta charset="UTF-8">
+              <meta name="viewport" content="width=device-width, initial-scale=1.0">
+              <title>Event Timeline - #{session_id}</title>
+              <style>
+                  body { font-family: Arial, sans-serif; margin: 20px; background-color: #f5f5f5; }
+                  .container { max-width: 1200px; margin: 0 auto; background: white; padding: 20px; border-radius: 8px; box-shadow: 0 2px 10px rgba(0,0,0,0.1); }
+                  .header { text-align: center; margin-bottom: 30px; }
+                  .stats { display: flex; justify-content: space-around; margin-bottom: 30px; padding: 20px; background: #f8f9fa; border-radius: 5px; }
+                  .stat { text-align: center; }
+                  .stat-number { font-size: 2em; font-weight: bold; color: #007bff; }
+                  .stat-label { color: #666; }
+                  .timeline { position: relative; }
+                  .timeline-item { margin: 20px 0; padding: 15px; border-left: 4px solid #007bff; background: #f8f9fa; border-radius: 0 5px 5px 0; }
+                  .timeline-item:hover { background: #e9ecef; }
+                  .event-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 10px; }
+                  .event-type { font-weight: bold; color: #007bff; font-size: 1.1em; }
+                  .event-time { color: #666; font-size: 0.9em; }
+                  .event-source { color: #28a745; font-weight: 500; }
+                  .event-data { background: white; padding: 10px; border-radius: 3px; margin-top: 10px; font-family: monospace; font-size: 0.9em; }
+                  .event-id { color: #6c757d; font-size: 0.8em; }
+                  .filter-controls { margin-bottom: 20px; padding: 15px; background: #e9ecef; border-radius: 5px; }
+                  .filter-controls input, .filter-controls select { margin: 0 10px; padding: 5px; }
+                  .no-events { text-align: center; color: #666; font-style: italic; padding: 40px; }
+              </style>
+          </head>
+          <body>
+              <div class="container">
+                  <div class="header">
+                      <h1>Event Timeline</h1>
+                      <p>Session: #{session_id}</p>
+                  </div>
+                  
+                  <div class="stats">
+                      <div class="stat">
+                          <div class="stat-number">#{events.length}</div>
+                          <div class="stat-label">Total Events</div>
+                      </div>
+                      <div class="stat">
+                          <div class="stat-number">#{events.map(&:type).uniq.length}</div>
+                          <div class="stat-label">Event Types</div>
+                      </div>
+                      <div class="stat">
+                          <div class="stat-number">#{events.map(&:source).uniq.length}</div>
+                          <div class="stat-label">Sources</div>
+                      </div>
+                  </div>
+
+                  <div class="filter-controls">
+                      <label>Filter by type:</label>
+                      <select id="typeFilter">
+                          <option value="">All Types</option>
+                          #{events.map(&:type).uniq.map { |type| "<option value=\"#{type}\">#{type}</option>" }.join}
+                      </select>
+                      <label>Search:</label>
+                      <input type="text" id="searchFilter" placeholder="Search events...">
+                  </div>
+
+                  <div class="timeline" id="timeline">
+                      #{events.empty? ? '<div class="no-events">No events found</div>' : events.map { |event| generate_event_html(event) }.join}
+                  </div>
+              </div>
+
+              <script>
+                  const events = #{timeline_data.to_json};
+                  
+                  function filterEvents() {
+                      const typeFilter = document.getElementById('typeFilter').value;
+                      const searchFilter = document.getElementById('searchFilter').value.toLowerCase();
+                      const timeline = document.getElementById('timeline');
+                      
+                      const filteredEvents = events.filter(event => {
+                          const typeMatch = !typeFilter || event.type === typeFilter;
+                          const searchMatch = !searchFilter || 
+                              event.type.toLowerCase().includes(searchFilter) ||
+                              event.source.toLowerCase().includes(searchFilter) ||
+                              JSON.stringify(event.data).toLowerCase().includes(searchFilter);
+                          return typeMatch && searchMatch;
+                      });
+                      
+                      timeline.innerHTML = filteredEvents.length === 0 ? 
+                          '<div class="no-events">No events match the current filters</div>' :
+                          filteredEvents.map(event => generateEventHTML(event)).join('');
+                  }
+                  
+                  function generateEventHTML(event) {
+                      return `
+                          <div class="timeline-item">
+                              <div class="event-header">
+                                  <span class="event-type">${event.type}</span>
+                                  <span class="event-time">${new Date(event.timestamp).toLocaleString()}</span>
+                              </div>
+                              <div class="event-source">Source: ${event.source}</div>
+                              <div class="event-data">${JSON.stringify(event.data, null, 2)}</div>
+                              <div class="event-id">ID: ${event.id}</div>
+                          </div>
+                      `;
+                  }
+                  
+                  document.getElementById('typeFilter').addEventListener('change', filterEvents);
+                  document.getElementById('searchFilter').addEventListener('input', filterEvents);
+              </script>
+          </body>
+          </html>
+        HTML
+      end
+
+      # Generate HTML for a single event
+      # @param event [EventSystem::Event] The event to generate HTML for
+      # @return [String] HTML for the event
+      def generate_event_html(event)
+        <<~HTML
+          <div class="timeline-item">
+              <div class="event-header">
+                  <span class="event-type">#{event.type}</span>
+                  <span class="event-time">#{event.timestamp.strftime('%Y-%m-%d %H:%M:%S.%3N')}</span>
+              </div>
+              <div class="event-source">Source: #{event.source_to_string}</div>
+              <div class="event-data">#{JSON.pretty_generate(event.data)}</div>
+              <div class="event-id">ID: #{event.id}</div>
+          </div>
+        HTML
+      end
+
+      # Calculate duration between events (for timeline visualization)
+      # @param event [EventSystem::Event] The current event
+      # @param all_events [Array<EventSystem::Event>] All events for context
+      # @return [Float, nil] Duration in seconds, or nil if not applicable
+      def calculate_duration(event, all_events)
+        # This is a placeholder for more sophisticated duration calculation
+        # Could be enhanced to calculate time between related events
+        nil
+      end
+    end
+  end
+end

data/lib/event_system.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "event_system/version"
+require_relative "event_system/event"
+require_relative "event_system/event_subscriber"
+require_relative "event_system/configuration"
+require_relative "event_system/event_manager"
+require_relative "event_system/storage/base"
+require_relative "event_system/storage/memory_store"
+require_relative "event_system/storage/file_store"
+require_relative "event_system/visualization/timeline_generator"
+
+module EventSystem
+  class Error < StandardError; end
+
+  # Create a new event manager with default configuration
+  # @param config [Hash, EventSystem::Configuration, nil] Configuration options
+  # @return [EventSystem::EventManager] A new event manager instance
+  def self.create_manager(config = nil)
+    EventManager.new(config)
+  end
+
+  # Create a new event
+  # @param type [String, Symbol] The event type
+  # @param source [Object] The event source
+  # @param data [Hash] Event data
+  # @return [EventSystem::Event] A new event instance
+  def self.create_event(type, source = nil, data = {})
+    Event.new(type, source, data)
+  end
+
+  # Get the current version
+  # @return [String] The current version
+  def self.version
+    VERSION
+  end
+end