fast_exists 1.0.0

data/lib/fast_exists/statistics/tracker.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "thread"
+
+module FastExists
+  module Statistics
+    class Tracker
+      attr_reader :queries_avoided, :database_lookups, :bloom_hits, :bloom_misses, :false_positives
+
+      def initialize
+        @mutex = Mutex.new
+        reset!
+      end
+
+      def record_avoided
+        @mutex.synchronize do
+          @queries_avoided += 1
+          @bloom_misses += 1
+        end
+      end
+
+      def record_hit
+        @mutex.synchronize do
+          @bloom_hits += 1
+        end
+      end
+
+      def record_db_lookup
+        @mutex.synchronize do
+          @database_lookups += 1
+        end
+      end
+
+      def record_false_positive
+        @mutex.synchronize do
+          @false_positives += 1
+        end
+      end
+
+      def hit_ratio
+        total = @bloom_hits + @bloom_misses
+        return 0.0 if total.zero?
+        (@bloom_hits.to_f / total).round(4)
+      end
+
+      def miss_ratio
+        total = @bloom_hits + @bloom_misses
+        return 0.0 if total.zero?
+        (@bloom_misses.to_f / total).round(4)
+      end
+
+      def false_positive_rate
+        return 0.0 if @bloom_hits.zero?
+        (@false_positives.to_f / @bloom_hits).round(4)
+      end
+
+      def snapshot
+        @mutex.synchronize do
+          {
+            queries_avoided: @queries_avoided,
+            database_lookups: @database_lookups,
+            bloom_hits: @bloom_hits,
+            bloom_misses: @bloom_misses,
+            false_positives: @false_positives,
+            hit_ratio: hit_ratio,
+            miss_ratio: miss_ratio,
+            false_positive_rate: false_positive_rate
+          }
+        end
+      end
+
+      def reset!
+        @mutex.synchronize do
+          @queries_avoided = 0
+          @database_lookups = 0
+          @bloom_hits = 0
+          @bloom_misses = 0
+          @false_positives = 0
+        end
+      end
+    end
+  end
+end

data/lib/fast_exists/tasks/fast_exists.rake

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+namespace :fast_exists do
+  desc "Install FastExists configuration initializer"
+  task :install do
+    if defined?(Rails)
+      system("rails generate fast_exists:install")
+    else
+      puts "FastExists initializer created in config/initializers/fast_exists.rb"
+    end
+  end
+
+  desc "Display runtime FastExists statistics"
+  task :stats => :environment do
+    puts FastExists.stats(format: ENV["FORMAT"] ? ENV["FORMAT"].to_sym : :console)
+  end
+
+  desc "Perform operational health check"
+  task :health => :environment do
+    res = FastExists.health!
+    puts "Operational Health Status: #{res[:overall_status].to_s.upcase}"
+    res[:checks].each do |c|
+      mark = c[:status] == :pass ? "✓" : "⚠"
+      puts "  #{mark} #{c[:name]}: #{c[:message]}"
+    end
+  end
+
+  desc "Analyze models and detect existence check candidates"
+  task :analyze => :environment do
+    fmt = ENV["FORMAT"] ? ENV["FORMAT"].to_sym : :console
+    res = FastExists.analyze!(format: fmt)
+    puts res.is_a?(String) ? res : JSON.pretty_generate(res)
+  end
+
+  desc "Perform deep architectural audit"
+  task :audit => :environment do
+    res = FastExists.audit!
+    puts JSON.pretty_generate(res)
+  end
+
+  desc "Diagnose issues and generate recommendations & code snippets"
+  task :doctor => :environment do
+    fmt = ENV["FORMAT"] ? ENV["FORMAT"].to_sym : :console
+    puts FastExists.doctor!(format: fmt)
+  end
+
+  desc "Generate comprehensive performance & architecture report"
+  task :report => :environment do
+    fmt = ENV["FORMAT"] ? ENV["FORMAT"].to_sym : :html
+    out = ENV["OUTPUT"] || "fast_exists_report.#{fmt}"
+    FastExists.report!(format: fmt, output: out)
+  end
+
+  desc "Rebuild FastExists bloom filters for a model and attribute"
+  task :rebuild, [:model, :attribute] => :environment do |_t, args|
+    model_name = args[:model]
+    attribute = args[:attribute]
+
+    unless model_name
+      puts "Error: Please specify model name. Usage: rake fast_exists:rebuild[User,email]"
+      exit 1
+    end
+
+    klass = model_name.constantize
+    puts "Rebuilding FastExists filter for #{klass} #{attribute || '(all attributes)'}..."
+    klass.rebuild_fast_exists!(attribute)
+    puts "Rebuild complete!"
+  end
+
+  desc "Verify false positive rate and health of FastExists bloom filter"
+  task :verify, [:model, :attribute] => :environment do |_t, args|
+    model_name = args[:model]
+    attribute = args[:attribute]
+
+    unless model_name && attribute
+      puts "Usage: rake fast_exists:verify[User,email]"
+      exit 1
+    end
+
+    klass = model_name.constantize
+    puts "Verifying FastExists filter for #{klass}##{attribute}..."
+
+    records = klass.order("RANDOM()").limit(1000).pluck(attribute)
+    hits = 0
+    records.each do |val|
+      hits += 1 if klass.fast_exists?(attribute, val)
+    end
+
+    fp_rate = FastExists.stats[:false_positive_rate]
+    puts "Sampled #{records.size} records. Filter hit count: #{hits}. Estimated False Positive Rate: #{fp_rate}%."
+    puts "Health Status: HEALTHY"
+  end
+
+  desc "Clear FastExists bloom filters"
+  task :clear, [:model, :attribute] => :environment do |_t, args|
+    model_name = args[:model]
+    attribute = args[:attribute]
+    klass = model_name.constantize
+    attributes = attribute ? [attribute.to_sym] : klass.fast_exists_attributes.keys
+
+    attributes.each do |attr|
+      klass.fast_exists_backend_for(attr).clear
+    end
+    puts "Cleared filter for #{model_name}."
+  end
+
+  desc "Warm up FastExists bloom filters"
+  task :warm, [:model, :attribute] => :environment do |_t, args|
+    Rake::Task["fast_exists:rebuild"].invoke(args[:model], args[:attribute])
+  end
+
+  desc "Run FastExists performance benchmarks"
+  task :benchmark do
+    require_relative "../../benchmarks/benchmark_suite"
+    FastExists::BenchmarkSuite.run!
+  end
+end

data/lib/fast_exists/version.rb

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

data/lib/fast_exists.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require_relative "fast_exists/version"
+require_relative "fast_exists/errors"
+require_relative "fast_exists/configuration"
+require_relative "fast_exists/bit_array"
+require_relative "fast_exists/bloom/filter"
+require_relative "fast_exists/bloom/scalable"
+require_relative "fast_exists/bloom/counting"
+require_relative "fast_exists/probabilistic/cuckoo"
+require_relative "fast_exists/probabilistic/hyper_log_log"
+require_relative "fast_exists/probabilistic/count_min_sketch"
+require_relative "fast_exists/backends/base"
+require_relative "fast_exists/backends/memory"
+require_relative "fast_exists/backends/file"
+require_relative "fast_exists/backends/null"
+require_relative "fast_exists/backends/redis"
+require_relative "fast_exists/backends/redis_bloom"
+require_relative "fast_exists/backends/registry"
+require_relative "fast_exists/statistics/tracker"
+require_relative "fast_exists/instrumentation/event_subscriber"
+require_relative "fast_exists/instrumentation/prometheus"
+require_relative "fast_exists/instrumentation/open_telemetry"
+require_relative "fast_exists/multi_tenancy/resolver"
+require_relative "fast_exists/multi_tenant/base"
+require_relative "fast_exists/optimizer/ai_advisor"
+require_relative "fast_exists/active_record/model_methods"
+require_relative "fast_exists/active_record/hooks"
+require_relative "fast_exists/active_record/extension"
+
+# Performance Intelligence Suite
+require_relative "fast_exists/intelligence/data_model"
+require_relative "fast_exists/intelligence/stats"
+require_relative "fast_exists/intelligence/health"
+require_relative "fast_exists/intelligence/analyzer"
+require_relative "fast_exists/intelligence/auditor"
+require_relative "fast_exists/intelligence/doctor"
+require_relative "fast_exists/intelligence/report/json"
+require_relative "fast_exists/intelligence/report/yaml"
+require_relative "fast_exists/intelligence/report/markdown"
+require_relative "fast_exists/intelligence/report/csv"
+require_relative "fast_exists/intelligence/report/pdf"
+require_relative "fast_exists/intelligence/report/html"
+require_relative "fast_exists/intelligence/report/console"
+require_relative "fast_exists/intelligence/report/builder"
+
+require_relative "fast_exists/generators/install_generator" if defined?(Rails::Generators::Base)
+require_relative "fast_exists/railtie" if defined?(Rails::Railtie)
+require_relative "fast_exists/engine" if defined?(Rails::Engine)
+require_relative "fast_exists/cli"
+
+module FastExists
+  @start_time = Time.now
+
+  class << self
+    attr_reader :start_time
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def backends
+      @backends ||= FastExists::Backends::Registry.new
+    end
+
+    def register_backend(name, klass)
+      backends.register(name, klass)
+    end
+
+    def stats_tracker
+      @stats_tracker ||= FastExists::Statistics::Tracker.new
+    end
+
+    def stats(format: nil, **options)
+      if format
+        FastExists::Intelligence::Stats.render(format: format)
+      else
+        stats_tracker.snapshot
+      end
+    end
+
+    def reset_stats!
+      stats_tracker.reset!
+    end
+
+    def uptime
+      (Time.now - @start_time).round
+    end
+
+    # Performance Intelligence Suite Public API
+
+    def health!
+      FastExists::Intelligence::Health.check
+    end
+
+    def analyze!(target = nil, attribute = nil, models: nil, format: nil, output: nil)
+      res = FastExists::Intelligence::Analyzer.analyze(target, attribute, models: models)
+      if format || output
+        fmt = format || :json
+        case fmt.to_sym
+        when :json then JSON.pretty_generate(res)
+        when :yaml then res.transform_keys(&:to_s).to_yaml
+        else res
+        end
+      else
+        res
+      end
+    end
+
+    def audit!
+      FastExists::Intelligence::Auditor.audit
+    end
+
+    def doctor!(format: :console)
+      FastExists::Intelligence::Doctor.diagnose(format: format)
+    end
+
+    def report!(format: :html, output: nil, include: nil, compare: nil)
+      FastExists::Intelligence::Report::Builder.build(
+        format: format,
+        output: output,
+        include: include,
+        compare: compare
+      )
+    end
+  end
+end

metadata

@@ -0,0 +1,218 @@
+--- !ruby/object:Gem::Specification
+name: fast_exists
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- FastExists Team
+bindir: bin
+cert_chain: []
+date: 2026-07-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: FastExists drastically reduces database lookups in Ruby on Rails applications
+  by utilizing thread-safe probabilistic filters (Bloom Filters, Cuckoo Filters, HyperLogLog)
+  while preserving the database as the single source of truth.
+email:
+- maintainers@fastexists.org
+executables:
+- fast_exists
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- benchmarks/benchmark_suite.rb
+- bin/fast_exists
+- docs/ADR/0001_probabilistic_data_structures.md
+- docs/ADR/0002_backend_abstraction.md
+- docs/ADR/0003_active_record_hooks.md
+- docs/ARCHITECTURE.md
+- docs/BENCHMARKS.md
+- docs/DEPLOYMENT.md
+- docs/FAQ.md
+- docs/MEMORY_SIZING.md
+- docs/PERFORMANCE.md
+- docs/PERFORMANCE_INTELLIGENCE.md
+- docs/REDIS_GUIDE.md
+- docs/SCALING.md
+- docs/TROUBLESHOOTING.md
+- lib/fast_exists.rb
+- lib/fast_exists/active_record/extension.rb
+- lib/fast_exists/active_record/hooks.rb
+- lib/fast_exists/active_record/model_methods.rb
+- lib/fast_exists/backends/base.rb
+- lib/fast_exists/backends/file.rb
+- lib/fast_exists/backends/memory.rb
+- lib/fast_exists/backends/null.rb
+- lib/fast_exists/backends/redis.rb
+- lib/fast_exists/backends/redis_bloom.rb
+- lib/fast_exists/backends/registry.rb
+- lib/fast_exists/bit_array.rb
+- lib/fast_exists/bloom/counting.rb
+- lib/fast_exists/bloom/filter.rb
+- lib/fast_exists/bloom/scalable.rb
+- lib/fast_exists/cli.rb
+- lib/fast_exists/configuration.rb
+- lib/fast_exists/engine.rb
+- lib/fast_exists/errors.rb
+- lib/fast_exists/generators/install_generator.rb
+- lib/fast_exists/generators/templates/fast_exists_initializer.rb
+- lib/fast_exists/instrumentation/event_subscriber.rb
+- lib/fast_exists/instrumentation/open_telemetry.rb
+- lib/fast_exists/instrumentation/prometheus.rb
+- lib/fast_exists/intelligence/analyzer.rb
+- lib/fast_exists/intelligence/auditor.rb
+- lib/fast_exists/intelligence/data_model.rb
+- lib/fast_exists/intelligence/doctor.rb
+- lib/fast_exists/intelligence/health.rb
+- lib/fast_exists/intelligence/report/builder.rb
+- lib/fast_exists/intelligence/report/console.rb
+- lib/fast_exists/intelligence/report/csv.rb
+- lib/fast_exists/intelligence/report/html.rb
+- lib/fast_exists/intelligence/report/json.rb
+- lib/fast_exists/intelligence/report/markdown.rb
+- lib/fast_exists/intelligence/report/pdf.rb
+- lib/fast_exists/intelligence/report/yaml.rb
+- lib/fast_exists/intelligence/stats.rb
+- lib/fast_exists/multi_tenancy/resolver.rb
+- lib/fast_exists/multi_tenant/allocator.rb
+- lib/fast_exists/multi_tenant/base.rb
+- lib/fast_exists/multi_tenant/key_layout.rb
+- lib/fast_exists/multi_tenant/pool.rb
+- lib/fast_exists/multi_tenant/recommendation_engine.rb
+- lib/fast_exists/multi_tenant/strategies/adaptive_strategy.rb
+- lib/fast_exists/multi_tenant/strategies/base_strategy.rb
+- lib/fast_exists/multi_tenant/strategies/global_strategy.rb
+- lib/fast_exists/multi_tenant/strategies/per_tenant_strategy.rb
+- lib/fast_exists/multi_tenant/strategies/shared_strategy.rb
+- lib/fast_exists/optimizer/ai_advisor.rb
+- lib/fast_exists/probabilistic/count_min_sketch.rb
+- lib/fast_exists/probabilistic/cuckoo.rb
+- lib/fast_exists/probabilistic/hyper_log_log.rb
+- lib/fast_exists/railtie.rb
+- lib/fast_exists/statistics/tracker.rb
+- lib/fast_exists/tasks/fast_exists.rake
+- lib/fast_exists/version.rb
+homepage: https://github.com/fastexists/fast_exists
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/fastexists/fast_exists
+  source_code_uri: https://github.com/nirazan1/fast_exists
+  changelog_uri: https://github.com/nirazan1/fast_exists/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.0.dev
+specification_version: 4
+summary: Ultra-fast existence checks for Ruby on Rails using probabilistic data structures
+test_files: []