searchcraft 0.4.0 → 0.4.1

data/.gem_rbs_collection/rainbow/3.0/.rbs_meta.yaml

@@ -0,0 +1,9 @@
+---
+name: rainbow
+version: '3.0'
+source:
+  type: git
+  name: ruby/gem_rbs_collection
+  revision: 3e93a59bd5da185b68187991630ac9a54a2468a7
+  remote: https://github.com/ruby/gem_rbs_collection.git
+  repo_dir: gems

data/.gem_rbs_collection/rainbow/3.0/global.rbs

@@ -0,0 +1,7 @@
+module Rainbow
+  def self.enabled: () -> bool
+
+  def self.enabled=: (bool value) -> bool
+
+  def self.uncolor: (String string) -> String
+end

data/.gem_rbs_collection/rainbow/3.0/presenter.rbs

@@ -0,0 +1,209 @@
+module Rainbow
+  class Presenter < String
+    # Sets color of this text.
+    def color: (*Symbol values) -> instance
+
+    alias foreground color
+
+    alias fg color
+
+    # Sets background color of this text.
+    def background: (*Symbol values) -> instance
+
+    alias bg background
+
+    # Resets terminal to default colors/backgrounds.
+    #
+    # It shouldn't be needed to use this method because all methods
+    # append terminal reset code to end of string.
+    def reset: () -> instance
+
+    # Turns on bright/bold for this text.
+    def bright: () -> instance
+
+    alias bold bright
+
+    # Turns on faint/dark for this text (not well supported by terminal
+    # emulators).
+    def faint: () -> instance
+
+    # Turns on italic style for this text (not well supported by terminal
+    # emulators).
+    def italic: () -> instance
+
+    # Turns on underline decoration for this text.
+    def underline: () -> instance
+
+    # Turns on blinking attribute for this text (not well supported by terminal
+    # emulators).
+    def blink: () -> instance
+
+    # Inverses current foreground/background colors.
+    def inverse: () -> instance
+
+    # Hides this text (set its color to the same as background).
+    def hide: () -> instance
+
+    def black: () -> instance
+
+    def red: () -> instance
+
+    def green: () -> instance
+
+    def yellow: () -> instance
+
+    def blue: () -> instance
+
+    def magenta: () -> instance
+
+    def cyan: () -> instance
+
+    def white: () -> instance
+
+    # We take care of X11 color method call here.
+    # Such as #aqua, #ghostwhite.
+    def method_missing: (untyped method_name, *untyped args) -> untyped
+
+    def respond_to_missing?: (untyped method_name, *untyped args) -> bool
+
+    def wrap_with_sgr: (untyped codes) -> instance
+
+    def aliceblue: () -> instance
+    def antiquewhite: () -> instance
+    def aqua: () -> instance
+    def aquamarine: () -> instance
+    def azure: () -> instance
+    def beige: () -> instance
+    def bisque: () -> instance
+    def blanchedalmond: () -> instance
+    def blueviolet: () -> instance
+    def brown: () -> instance
+    def burlywood: () -> instance
+    def cadetblue: () -> instance
+    def chartreuse: () -> instance
+    def chocolate: () -> instance
+    def coral: () -> instance
+    def cornflower: () -> instance
+    def cornsilk: () -> instance
+    def crimson: () -> instance
+    def darkblue: () -> instance
+    def darkcyan: () -> instance
+    def darkgoldenrod: () -> instance
+    def darkgray: () -> instance
+    def darkgreen: () -> instance
+    def darkkhaki: () -> instance
+    def darkmagenta: () -> instance
+    def darkolivegreen: () -> instance
+    def darkorange: () -> instance
+    def darkorchid: () -> instance
+    def darkred: () -> instance
+    def darksalmon: () -> instance
+    def darkseagreen: () -> instance
+    def darkslateblue: () -> instance
+    def darkslategray: () -> instance
+    def darkturquoise: () -> instance
+    def darkviolet: () -> instance
+    def deeppink: () -> instance
+    def deepskyblue: () -> instance
+    def dimgray: () -> instance
+    def dodgerblue: () -> instance
+    def firebrick: () -> instance
+    def floralwhite: () -> instance
+    def forestgreen: () -> instance
+    def fuchsia: () -> instance
+    def gainsboro: () -> instance
+    def ghostwhite: () -> instance
+    def gold: () -> instance
+    def goldenrod: () -> instance
+    def gray: () -> instance
+    def greenyellow: () -> instance
+    def honeydew: () -> instance
+    def hotpink: () -> instance
+    def indianred: () -> instance
+    def indigo: () -> instance
+    def ivory: () -> instance
+    def khaki: () -> instance
+    def lavender: () -> instance
+    def lavenderblush: () -> instance
+    def lawngreen: () -> instance
+    def lemonchiffon: () -> instance
+    def lightblue: () -> instance
+    def lightcoral: () -> instance
+    def lightcyan: () -> instance
+    def lightgoldenrod: () -> instance
+    def lightgray: () -> instance
+    def lightgreen: () -> instance
+    def lightpink: () -> instance
+    def lightsalmon: () -> instance
+    def lightseagreen: () -> instance
+    def lightskyblue: () -> instance
+    def lightslategray: () -> instance
+    def lightsteelblue: () -> instance
+    def lightyellow: () -> instance
+    def lime: () -> instance
+    def limegreen: () -> instance
+    def linen: () -> instance
+    def maroon: () -> instance
+    def mediumaquamarine: () -> instance
+    def mediumblue: () -> instance
+    def mediumorchid: () -> instance
+    def mediumpurple: () -> instance
+    def mediumseagreen: () -> instance
+    def mediumslateblue: () -> instance
+    def mediumspringgreen: () -> instance
+    def mediumturquoise: () -> instance
+    def mediumvioletred: () -> instance
+    def midnightblue: () -> instance
+    def mintcream: () -> instance
+    def mistyrose: () -> instance
+    def moccasin: () -> instance
+    def navajowhite: () -> instance
+    def navyblue: () -> instance
+    def oldlace: () -> instance
+    def olive: () -> instance
+    def olivedrab: () -> instance
+    def orange: () -> instance
+    def orangered: () -> instance
+    def orchid: () -> instance
+    def palegoldenrod: () -> instance
+    def palegreen: () -> instance
+    def paleturquoise: () -> instance
+    def palevioletred: () -> instance
+    def papayawhip: () -> instance
+    def peachpuff: () -> instance
+    def peru: () -> instance
+    def pink: () -> instance
+    def plum: () -> instance
+    def powderblue: () -> instance
+    def purple: () -> instance
+    def rebeccapurple: () -> instance
+    def rosybrown: () -> instance
+    def royalblue: () -> instance
+    def saddlebrown: () -> instance
+    def salmon: () -> instance
+    def sandybrown: () -> instance
+    def seagreen: () -> instance
+    def seashell: () -> instance
+    def sienna: () -> instance
+    def silver: () -> instance
+    def skyblue: () -> instance
+    def slateblue: () -> instance
+    def slategray: () -> instance
+    def snow: () -> instance
+    def springgreen: () -> instance
+    def steelblue: () -> instance
+    def tan: () -> instance
+    def teal: () -> instance
+    def thistle: () -> instance
+    def tomato: () -> instance
+    def turquoise: () -> instance
+    def violet: () -> instance
+    def webgray: () -> instance
+    def webgreen: () -> instance
+    def webmaroon: () -> instance
+    def webpurple: () -> instance
+    def wheat: () -> instance
+    def whitesmoke: () -> instance
+    def yellowgreen: () -> instance
+  end
+end

data/.gem_rbs_collection/rainbow/3.0/rainbow.rbs

@@ -0,0 +1,5 @@
+class Object
+  private
+
+  def Rainbow: (String) -> Rainbow::Presenter
+end

data/.gem_rbs_collection/rake/13.0/.rbs_meta.yaml

@@ -0,0 +1,9 @@
+---
+name: rake
+version: '13.0'
+source:
+  type: git
+  name: ruby/gem_rbs_collection
+  revision: 3e93a59bd5da185b68187991630ac9a54a2468a7
+  remote: https://github.com/ruby/gem_rbs_collection.git
+  repo_dir: gems

data/.gem_rbs_collection/rake/13.0/manifest.yaml

@@ -0,0 +1,2 @@
+dependencies:
+  - name: fileutils

data/.gem_rbs_collection/rake/13.0/rake.rbs

@@ -0,0 +1,28 @@
+module Rake
+  class TaskLib
+    include Rake::DSL
+  end
+
+  module DSL
+    private
+
+    include FileUtils
+
+    def desc: (String description) -> void
+    def directory: (*untyped args) ?{ () -> void } -> void
+    def file: (*untyped args) ?{ () -> void } -> void
+    def file_create: (*untyped args) ?{ () -> void } -> void
+    def import: (*String fns) -> void
+    def multitask: (*untyped args) ?{ () -> void } -> void
+    def namespace: (?untyped name) ?{ () -> void } -> void
+    def rule: (*untyped args) ?{ () -> void } -> void
+    def task: (*untyped args) ?{ () -> void } -> void
+  end
+end
+
+module FileUtils
+  def sh: (*String cmd, **untyped options) ?{ (bool, Process::Status) -> void } -> void
+  def ruby: (*String args, **untyped options) ?{ (bool, Process::Status) -> void } -> void
+  def safe_ln: (*untyped args, **untyped options) -> void
+  def split_all: (String path) -> Array[String]
+end

data/.gem_rbs_collection/thor/1.2/.rbs_meta.yaml

@@ -0,0 +1,9 @@
+---
+name: thor
+version: '1.2'
+source:
+  type: git
+  name: ruby/gem_rbs_collection
+  revision: 3e93a59bd5da185b68187991630ac9a54a2468a7
+  remote: https://github.com/ruby/gem_rbs_collection.git
+  repo_dir: gems

data/.gem_rbs_collection/thor/1.2/manifest.yaml

@@ -0,0 +1,7 @@
+# manifest.yaml describes dependencies which do not appear in the gemspec.
+# If this gem includes such dependencies, comment-out the following lines and
+# declare the dependencies.
+# If all dependencies appear in the gemspec, you should remove this file.
+#
+# dependencies:
+#   - name: pathname

data/.gem_rbs_collection/thor/1.2/thor.rbs

@@ -0,0 +1,15 @@
+class Thor
+  class Group
+  end
+
+  module Actions
+    class CreateFile
+    end
+
+    def create_file: (String destination, String data, ?verbose: bool) -> String
+                   | (String destination, ?verbose: bool) { () -> String } -> String
+  end
+
+  class Error
+  end
+end

data/.overcommit.yml

@@ -18,10 +18,20 @@
 verify_signatures: false
 
 PreCommit:
+  Signatures:
+    enabled: true
+    required: true
+    command: ['bundle', 'exec', 'steep', 'check']
+    flags: []
   StandardRB:
     enabled: true
     required: true
     command: ['bundle', 'exec', 'standardrb'] # Invoke within Bundler context
+  Tests:
+    enabled: true
+    required: true
+    command: ['bundle', 'exec', 'rake', 'test']
+    flags: []
   ErbLint:
     enabled: true
     required: true
@@ -32,30 +42,3 @@ PreCommit:
         '--enable-linters',
         'space_around_erb_tag,extra_newline',
       ]
-#  RustyWind:
-#    enabled: true
-#    required: true
-#    command: ['yarn', 'run', 'rustywind-fix']
-
-# PrePush:
-#   RSpec:
-#     enabled: true
-#     required: true
-#     command: ['bundle', 'exec', 'rspec']
-
-#PreCommit:
-#  RuboCop:
-#    enabled: true
-#    on_warn: fail # Treat all warnings as failures
-#
-#  TrailingWhitespace:
-#    enabled: true
-#    exclude:
-#      - '**/db/structure.sql' # Ignore trailing whitespace in generated files
-#
-#PostCheckout:
-#  ALL: # Special hook name that customizes all hooks of this type
-#    quiet: true # Change all post-checkout hooks to only display output on failure
-#
-#  IndexTags:
-#    enabled: true # Generate a tags file with `ctags` each time HEAD changes

data/.standard.yml

@@ -1,3 +1,3 @@
 # For available configuration options, see:
 #   https://github.com/testdouble/standard
-ruby_version: 2.6
+ruby_version: 3.0

data/CHANGELOG.md

@@ -1,5 +1,20 @@
-## [Unreleased]
+## [0.4.1] - 2023-11-01
 
-## [0.1.0] - 2023-08-19
+- [`SearchCraft::TextSearch`](lib/searchcraft/text_search.rb) module added to `Builder` which provides `tsvector` helpers. See [`test_text_search.rb`](test/searchcraft/builder/test_text_search.rb) for examples.
+- RBS type signatures
+- Convenience `Config.explicit_builder_classes = {"Builder" => "Model"}` if you need to explicitly describe your Builder + Model classes and they are 1:1
+- Override default table name for `ViewHashStore` with:
 
-- Initial release
+    ```ruby
+    SearchCraft.configure do |config|
+      config.view_hash_store_table_name = "'my_schema'.'my_table_name'"`
+    end
+    ```
+
+Fixes:
+
+- Fixes for users of `SearchCraft.config.explicit_model_class_names` on initialization
+
+## [0.4.0] - 2023-10-24
+
+- Initial public release

data/README.md

@@ -18,7 +18,7 @@ See [demo app](https://ykdnr.hatchboxapp.com/searchcraft/products?category_id=54
 
 Add lightning quick search capabilities to your Rails apps without external systems like ElasticSearch. It's now magically simple to craft the ActiveRecord/Arel expressions we already know and love, and convert them into SQL materialized views: ready to be queried and composed with ActiveRecord. Everything you love about Rails, but faster.
 
-**What makes Rails slow for search?** Large tables, lots of joins, subqueries, missing or unused indexes, and complex queries.
+**What makes Rails slow for search?** Large tables, lots of joins, subqueries, missing or unused indexes, and complex queries. Also slow? Coordinating data from multiple external systems through Ruby to produce search results.
 
 SearchCraft makes it trivial to write and use powerful **SQL materialized views** to pre-calculate the results of your search and reporting queries. It's like a database index, but for complex queries.
 
@@ -134,6 +134,88 @@ Number.all
 [#<Number number: 1>, #<Number number: 2>, #<Number number: 3>, #<Number number: 4>, #<Number number: 5>]
 ```
 
+### Indexes
+
+A wonderful feature of materialized views is you can add indexes to them; even unique indexes.
+
+Currently the mechanism for adding indexes is to add a `view_indexes` method to your builder class.
+
+For example, we can add a unique index on `NumberBuilder`'s `number` column:
+
+```ruby
+class NumberBuilder < SearchCraft::Builder
+  def view_indexes
+    {
+      number: {columns: ["number"], unique: true}
+    }
+  end
+```
+
+Or several indexes on the `ProductSearchBuilder` from earlier:
+
+```ruby
+class ProductSearchBuilder < SearchCraft::Builder
+  def view_indexes
+    {
+      id: {columns: ["product_id"], unique: true},
+      product_name: {columns: ["product_name"]},
+      reviews_count: {columns: ["reviews_count"]},
+      reviews_average: {columns: ["reviews_average"]}
+    }
+  end
+end
+```
+
+By default the indexes will be `using: :btree` indexing method. You can also use other indexing methods available in rails, such as `:gin`, `:gist`, or if you're using the `trigram` extension you can use `:gin_trgm_ops`. These can be useful when you're looking at setting up text search, as discussed below.
+
+### Search
+
+Another benefit of materialized views is we can create columns that are optimised for search. For example above, since we've precalculated the `reviews_average` in `ProductSearchBuilder`, we can easily find products with a certain average rating.
+
+```ruby
+ProductSearch.where("reviews_average > 4")
+```
+
+### Associations
+
+A fabulous feature of ActiveRecord is the ability to join queries together. Since our materialized views are native ActiveRecord models, we can join them together with other queries.
+
+Let's setup an association between our MV's `ProductSearch#product_id` and the table `Product#id` primary key:
+
+```ruby
+class ProductSearch < ActiveRecord::Base
+  include SearchCraft::Model
+
+  belongs_to :product, foreign_key: :product_id, primary_key: :id
+end
+```
+
+We can now join, or eager load, the tables together with ActiveRecord queries. To following returns a relation of `ProductSearch` objects, with each of their `ProductSearch#product` association preloaded.
+
+```ruby
+ProductSearch.includes(:product).where("reviews_average > 4")
+```
+
+The following returns `Product` objects, based on seaching the `ProductSearch` materialized view:
+
+```ruby
+class Product
+  has_one :product_search, foreign_key: :product_id, primary_key: :id, class_name: "ProductSearch"
+end
+
+Product.joins(:product_searches).merge(
+  ProductSearch.where("reviews_average > 4")
+)
+```
+
+### Text search
+
+PostgreSQL comes with a solution for [text search](https://www.postgresql.org/docs/current/textsearch.html) using a combination of functions such as `to_tsvector`, `ts_rank`, and `websearch_to_tsquery`.
+
+Pending more docs, see the [`test/searchcraft/builder/test_text_search.rb`](test/searchcraft/builder/test_text_search.rb) for an example of how to use these functions in your materialized views.
+
+I'm still working on extracting this solution from our code at [Store Connect](https://getstoreconnect.com).
+
 ### Dependencies between views
 
 Once you have one SearchCraft materialized view, you might want to create another that depends upon it. You can do this too with the `depends_on` method.
@@ -383,6 +465,7 @@ SearchCraft.load_tasks
 * Annotates models whenever materialized view is updated, if `annotate` gem is installed
 * Namespaced models/builders will use the full namesapce + classname for the materialized view name
 * Rake tasks to refresh all materialized views `rake searchcraft:refresh`, and check if any views need to be recreated `rake searchcraft:rebuild`
+* Rubygem contains RBS type signatures
 
 ## Development
 
@@ -419,5 +502,6 @@ Everyone interacting in the Searchcraft project's codebases, issue trackers, cha
 
 ## Credits
 
+* Thanks to [Store Connect](https://getstoreconnect.com/) for assisting the ideation and development of this project.
 * [scenic](https://github.com/scenic-views/scenic) gem first allowed me to use materialized views in Rails, but I was iterating on my view schema so frequently that their migration approach - `rails db:rollback`, rebuild migration SQL, `rails db:migrate`, and then test - became slow. It also introduced bugs - I would forget to run the steps, and then see odd behaviour. If you have relatively static views or materialized views, and want to use Rails migrations, please try out `scenic` gem. This `searchcraft` gem still depends on `scenic` for its view `refresh` feature, and adding views into `schema.rb`.
 * [activerecord](https://github.com/rails/rails) has been one of the most wonderful gifts to the universe since its inception. As a bonus, it allowed me to become "Dr Nic" in 2006 when I performed silly tricks with it in a rubygem called "Dr Nic's Magic Models". I've made many dear friends and had a wonderful career since those days.

data/lib/searchcraft/annotate.rb

@@ -1,6 +1,4 @@
 module SearchCraft::Annotate
-  extend ActiveSupport::Concern
-
   # If using annotate gem, then automatically annotate models after rebuilding views
   # TODO: I'm suspicious this is not working for dependent Builders, e.g. demo_app's OnsaleSearchBuilder
   def annotate_models!

data/lib/searchcraft/builder.rb

@@ -1,7 +1,9 @@
 class SearchCraft::Builder
   extend SearchCraft::Annotate
   include SearchCraft::DependsOn
+  extend SearchCraft::DependsOn::ClassMethods
   include SearchCraft::DumpSchema
+  include SearchCraft::TextSearch
 
   # Subclass must implement view_scope or view_select_sql
   def view_scope
@@ -75,7 +77,7 @@ class SearchCraft::Builder
         Dir.glob("#{load_path}/**/*.rb").each do |file|
           File.readlines(file).each do |line|
             if (match = line.match(/class\s+([\w:]+)\s*<\s*#{potential_superclass_regex}/))
-              class_name = match[1]
+              class_name = match[1].to_s
               warn "Found #{class_name} in #{file}" unless known_subclass_names.include?(class_name)
               subclass_names << class_name
             end
@@ -119,6 +121,7 @@ class SearchCraft::Builder
     end
     return unless dependencies_ready?
 
+    @@dependencies ||= {}
     dependencies_changed = (@@dependencies[self.class.name] || []) & builders_changed.map(&:name)
     return false unless dependencies_changed.any? ||
       SearchCraft::ViewHashStore.changed?(builder: self)
@@ -176,7 +179,7 @@ class SearchCraft::Builder
 
   # ProductSearchBuilder name becomes product_searches
   def base_sql_name
-    self.class.name.gsub(/Builder$/, "").tableize.tr("/", "_")
+    self.class.name.to_s.gsub(/Builder$/, "").tableize.tr("/", "_")
   end
 
   def base_idx_name

data/lib/searchcraft/configuration.rb

@@ -2,11 +2,30 @@ module SearchCraft
   class Configuration
     attr_accessor :disable_autorebuild
     attr_accessor :debug
+    attr_reader :explicit_builder_classes
     attr_accessor :explicit_builder_class_names
     attr_accessor :explicit_model_class_names
+    attr_reader :view_hash_store_table_name
 
     def autorebuild?
       !disable_autorebuild
     end
+
+    # If you need to explicitly list the builder + model classes you want to use,
+    # then set this to a hash of builder class names => model class names.
+    # {
+    #   "Search::Builder::ContentArticleSearchBuilder" => "Search::ContentArticleSearch",
+    #   "Search::Builder::ContentPageSearchBuilder" => "Search::ContentPageSearch"
+    # }
+    def explicit_builder_classes=(builders_and_models)
+      @explicit_builder_classes = builders_and_models
+      @explicit_builder_class_names = builders_and_models.keys
+      @explicit_model_class_names = builders_and_models.values
+    end
+
+    def view_hash_store_table_name=(table_name)
+      @view_hash_store_table_name = table_name
+      SearchCraft::ViewHashStore.table_name = table_name
+    end
   end
 end

data/lib/searchcraft/depends_on.rb

@@ -1,20 +1,11 @@
 module SearchCraft::DependsOn
-  extend ActiveSupport::Concern
-
-  class_methods do
+  module ClassMethods
     @@dependencies = {}
 
     def depends_on(*builder_names)
       @@dependencies[name] = builder_names
     end
 
-    # TODO: implement .add_index instead of #view_indexes below
-    def add_index(index_name, columns, unique: false, name: nil)
-      @indexes ||= {}
-      # TODO: also get indexes from @@dependencies[name]
-      @indexes[index_name] = {columns: columns, unique: unique, name: name}
-    end
-
     def sort_builders_by_dependency
       sorted = []
       visited = {}
@@ -27,7 +18,7 @@ module SearchCraft::DependsOn
     end
 
     def visit(builder, visited, sorted)
-      return if visited[builder.name]
+      return if visited[builder.name.to_s]
 
       dependency_names = @@dependencies[builder.name] || []
       dependency_names.each do |dependency_name|
@@ -35,8 +26,10 @@ module SearchCraft::DependsOn
         visit(dependency, visited, sorted)
       end
 
-      visited[builder.name] = true
+      visited[builder.name.to_s] = true
       sorted << builder
     end
   end
+
+  extend ClassMethods
 end

data/lib/searchcraft/dump_schema.rb

@@ -1,6 +1,4 @@
 module SearchCraft::DumpSchema
-  extend ActiveSupport::Concern
-
   # If in Rails, dump schema.rb after rebuilding views
   def dump_schema!
     return unless Rails.env.development?