typesensual 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9231d4598d045c7089f290474867722966f4c4e720cc34a8de0ef960b5ac650a
+  data.tar.gz: 6b9400c0f282f3df2b3bec0f310f453b3383ddd05846894a1390176db60b206e
+SHA512:
+  metadata.gz: 7ebec05f05e05762734582d0b5080844a567002313aff70b4009642da0aeb20874fbe7a12e9b523dcc2f702bf0b98c24342f3f23dcf751582b42399f21542114
+  data.tar.gz: 709890ec4af5c9da8b680910c865d4900d0eae090cd9cc471bfb50c0860e486854cbcb01ee934aac1bfa124da6722771b2154d2a80b7a911416876ff9598257e

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,293 @@
+require:
+  - rubocop-rspec
+  - rubocop-performance
+AllCops:
+  NewCops: enable
+  DisplayCopNames: false
+  DisplayStyleGuide: true
+  StyleGuideCopsOnly: false
+  TargetRubyVersion: 2.7
+Layout/ArgumentAlignment:
+  EnforcedStyle: with_fixed_indentation
+Style/BlockDelimiters:
+  EnforcedStyle: braces_for_chaining
+Style/CollectionMethods:
+  PreferredMethods:
+    collect: map
+    collect!: map!
+    inject: reduce
+    detect: find
+    find_all: select
+Style/CommentAnnotation:
+  Enabled: true
+  Keywords:
+    - TODO
+    - FIXME
+    - OPTIMIZE
+    - HACK
+    - REVIEW
+    - DEPRECATED
+Layout/DotPosition:
+  EnforcedStyle: leading
+Layout/EmptyLineAfterGuardClause:
+  Enabled: false
+Style/FormatString:
+  Enabled: true
+  EnforcedStyle: format
+Style/FrozenStringLiteralComment:
+  SafeAutoCorrect: true
+  Enabled: true
+Style/GlobalVars:
+  Enabled: false
+Style/GuardClause:
+  Enabled: true
+  MinBodyLength: 3
+Style/IfUnlessModifier:
+  Enabled: true
+Layout/FirstArrayElementIndentation:
+  EnforcedStyle: consistent
+Layout/FirstHashElementIndentation:
+  EnforcedStyle: consistent
+Style/LambdaCall:
+  Enabled: true
+Style/Next:
+  Enabled: true
+  MinBodyLength: 3
+Style/NumericLiterals:
+  Enabled: true
+  MinDigits: 5
+Style/PercentLiteralDelimiters:
+  Enabled: true
+  PreferredDelimiters:
+    '%': '[]'
+    '%i': '[]'
+    '%q': '[]'
+    '%Q': '[]'
+    '%r': '{}'
+    '%s': '()'
+    '%w': '[]'
+    '%W': '[]'
+    '%x': '[]'
+Style/RaiseArgs:
+  Enabled: true
+  EnforcedStyle: exploded
+Style/SingleLineMethods:
+  Enabled: true
+  AllowIfMethodIsEmpty: true
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+Layout/SpaceAroundEqualsInParameterDefault:
+  Enabled: true
+  EnforcedStyle: space
+Layout/SpaceBeforeBlockBraces:
+  Enabled: true
+  EnforcedStyle: space
+Layout/SpaceInsideBlockBraces:
+  Enabled: true
+  EnforcedStyle: space
+  EnforcedStyleForEmptyBraces: no_space
+  SpaceBeforeBlockParameters: true
+Layout/SpaceInsideHashLiteralBraces:
+  Enabled: true
+  EnforcedStyle: space
+  EnforcedStyleForEmptyBraces: no_space
+Style/SymbolProc:
+  Enabled: true
+Layout/TrailingEmptyLines:
+  Enabled: true
+  EnforcedStyle: final_newline
+Style/TrailingCommaInArguments:
+  Enabled: true
+  EnforcedStyleForMultiline: no_comma
+Style/TrailingCommaInArrayLiteral:
+  Enabled: true
+  EnforcedStyleForMultiline: no_comma
+Style/TrailingCommaInHashLiteral:
+  Enabled: true
+  EnforcedStyleForMultiline: no_comma
+Style/TrivialAccessors:
+  Enabled: true
+  AllowDSLWriters: true
+Naming/VariableName:
+  Enabled: true
+  EnforcedStyle: snake_case
+Style/WordArray:
+  Enabled: true
+  MinSize: 2
+Metrics/AbcSize:
+  Enabled: false
+Metrics/BlockNesting:
+  Enabled: true
+  Max: 5
+Metrics/BlockLength:
+  Enabled: false
+Metrics/ClassLength:
+  Enabled: true
+  CountComments: false
+  Max: 500
+Metrics/ModuleLength:
+  Enabled: true
+  CountComments: false
+  Max: 500
+Metrics/CyclomaticComplexity:
+  Enabled: false
+Layout/LineLength:
+  Enabled: true
+  Max: 100
+  AllowURI: true
+  IgnoreCopDirectives: true
+  Exclude:
+    - config/routes.rb
+Metrics/MethodLength:
+  Enabled: true
+  CountComments: false
+  Max: 100
+Metrics/ParameterLists:
+  Enabled: true
+  Max: 5
+  CountKeywordArgs: false
+Metrics/PerceivedComplexity:
+  Enabled: false
+Lint/AssignmentInCondition:
+  Enabled: true
+  AllowSafeAssignment: true
+Style/InlineComment:
+  Enabled: false
+Style/MethodCalledOnDoEndBlock:
+  Enabled: true
+Style/SymbolArray:
+  Enabled: true
+Naming/AccessorMethodName:
+  Enabled: true
+Style/Alias:
+  Enabled: true
+  EnforcedStyle: prefer_alias_method
+Style/ArrayJoin:
+  Enabled: true
+Style/AsciiComments:
+  Enabled: false
+Naming/AsciiIdentifiers:
+  Enabled: true
+Style/Attr:
+  Enabled: true
+Style/BlockComments:
+  Enabled: true
+Style/ColonMethodCall:
+  Enabled: true
+Style/Documentation:
+  Enabled: false
+Style/EmptyLiteral:
+  Enabled: true
+Style/EvenOdd:
+  Enabled: true
+Lint/FlipFlop:
+  Enabled: true
+Style/IfWithSemicolon:
+  Enabled: true
+Style/Lambda:
+  EnforcedStyle: literal
+  # HACK: Until Rubocop is released with EnforcedStyle
+  Enabled: true
+Layout/LeadingCommentSpace:
+  Enabled: true
+Style/MultilineBlockChain:
+  Enabled: true
+Style/MultilineTernaryOperator:
+  Enabled: true
+Style/NegatedIf:
+  Enabled: true
+Style/NestedTernaryOperator:
+  Enabled: true
+Style/NilComparison:
+  Enabled: true
+Style/Not:
+  Enabled: true
+Style/OneLineConditional:
+  Enabled: true
+Style/PerlBackrefs:
+  Enabled: true
+Style/RedundantBegin:
+  Enabled: true
+Style/RedundantSelf:
+  Enabled: true
+Style/RescueModifier:
+  Enabled: true
+Style/SelfAssignment:
+  Enabled: true
+Style/ClassAndModuleChildren:
+  Enabled: true
+  Exclude:
+    - app/graphql/**/*
+Style/HashEachMethods:
+  Enabled: true
+Style/HashTransformKeys:
+  Enabled: true
+Style/HashTransformValues:
+  Enabled: true
+Layout/SpaceBeforeFirstArg:
+  Enabled: true
+Layout/SpaceAfterColon:
+  Enabled: true
+Layout/SpaceAfterComma:
+  Enabled: true
+Layout/SpaceAroundKeyword:
+  Enabled: true
+Layout/SpaceAfterMethodName:
+  Enabled: true
+Layout/SpaceAfterNot:
+  Enabled: true
+Layout/SpaceAfterSemicolon:
+  Enabled: true
+Layout/SpaceBeforeComma:
+  Enabled: true
+Layout/SpaceBeforeComment:
+  Enabled: true
+Layout/SpaceBeforeSemicolon:
+  Enabled: true
+Layout/SpaceAroundOperators:
+  Enabled: true
+Layout/SpaceInsideParens:
+  Enabled: true
+Layout/SpaceInsideRangeLiteral:
+  Enabled: true
+Style/SpecialGlobalVars:
+  Enabled: true
+Layout/TrailingWhitespace:
+  Enabled: true
+Style/UnlessElse:
+  Enabled: true
+Style/VariableInterpolation:
+  Enabled: true
+Style/WhenThen:
+  Enabled: true
+Lint/Debugger:
+  Enabled: true
+Lint/DeprecatedClassMethods:
+  Enabled: true
+Security/Eval:
+  Enabled: true
+Lint/SuppressedException:
+  Enabled: true
+Lint/LiteralInInterpolation:
+  Enabled: true
+Lint/Loop:
+  Enabled: true
+Lint/ParenthesesAsGroupedExpression:
+  Enabled: true
+Lint/RequireParentheses:
+  Enabled: false
+Lint/UnderscorePrefixedVariableName:
+  Enabled: true
+Lint/UselessSetterCall:
+  Enabled: true
+RSpec/ExampleLength:
+  Max: 20
+RSpec/ImplicitSubject:
+  EnforcedStyle: single_statement_only
+  Enabled: true
+RSpec/NamedSubject:
+  Enabled: false
+RSpec/NestedGroups:
+  Max: 4
+RSpec/Focus:
+  AutoCorrect: false

data/.ruby-version

@@ -0,0 +1 @@
+3.1.4

data/.yardopts

@@ -0,0 +1,2 @@
+--markup markdown
+--markup-provider commonmarker

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [Unreleased]
+
+- Initial release

data/Gemfile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in typesensual.gemspec
+gemspec
+
+gem 'rake'
+gem 'rspec'
+gem 'rubocop'
+gem 'rubocop-performance'
+gem 'rubocop-rspec'
+gem 'simplecov'
+
+# Documentation
+gem 'commonmarker'
+gem 'rack'
+gem 'webrick'
+gem 'yard'

data/Gemfile.lock

@@ -0,0 +1,111 @@
+PATH
+  remote: .
+  specs:
+    typesensual (0.1.0)
+      activesupport (>= 6.1.5)
+      paint (>= 2.0.0)
+      typesense (>= 0.13.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (7.0.5)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+    ast (2.4.2)
+    commonmarker (0.23.9)
+    concurrent-ruby (1.2.2)
+    diff-lcs (1.5.0)
+    docile (1.4.0)
+    ethon (0.16.0)
+      ffi (>= 1.15.0)
+    ffi (1.15.5)
+    i18n (1.13.0)
+      concurrent-ruby (~> 1.0)
+    json (2.6.3)
+    minitest (5.18.0)
+    oj (3.14.3)
+    paint (2.3.0)
+    parallel (1.23.0)
+    parser (3.2.2.1)
+      ast (~> 2.4.1)
+    rack (2.2.7)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.8.0)
+    rexml (3.2.5)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.2)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.0)
+    rubocop (1.51.0)
+      json (~> 2.3)
+      parallel (~> 1.10)
+      parser (>= 3.2.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.28.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.28.1)
+      parser (>= 3.2.1.0)
+    rubocop-capybara (2.18.0)
+      rubocop (~> 1.41)
+    rubocop-factory_bot (2.23.1)
+      rubocop (~> 1.33)
+    rubocop-performance (1.18.0)
+      rubocop (>= 1.7.0, < 2.0)
+      rubocop-ast (>= 0.4.0)
+    rubocop-rspec (2.22.0)
+      rubocop (~> 1.33)
+      rubocop-capybara (~> 2.17)
+      rubocop-factory_bot (~> 2.22)
+    ruby-progressbar (1.13.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.4)
+    typesense (0.14.1)
+      oj (~> 3.11)
+      typhoeus (~> 1.4)
+    typhoeus (1.4.0)
+      ethon (>= 0.9.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (2.4.2)
+    webrick (1.7.0)
+    yard (0.9.34)
+
+PLATFORMS
+  x86_64-darwin-19
+  x86_64-darwin-22
+
+DEPENDENCIES
+  commonmarker
+  rack
+  rake
+  rspec
+  rubocop
+  rubocop-performance
+  rubocop-rspec
+  simplecov
+  typesensual!
+  webrick
+  yard
+
+BUNDLED WITH
+   2.3.13

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Emma Lejeck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,160 @@
+# Typesensual
+
+Typesensual is a small wrapper around the [Typesense Ruby client][typesense-gem] which provides a
+more familiar, rubyish interface for interacting with [Typesense][typesense-website]. Similar to
+[Chewy][chewy-gem], it provides a DSL for defining your schema, manages the life-cycle of your
+collections, and provides a simple interface for indexing, searching, and deleting documents.
+
+Unlike Chewy, it does *not* handle loading, denormalizing, or formatting your data for search
+purposes. It can be combined with an ORM such as ActiveRecord or Sequel, or even used with plain SQL
+queries, but that integration is left to you. This is a concious decision, since loading and
+transforming data is often a complex and application-specific task that is best left to the
+application developer, since you know best.
+
+[typesense-gem]: https://github.com/typesense/typesense-ruby
+[typesense-website]: https://typesense.org/
+[chewy-gem]: https://github.com/toptal/chewy
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'typesensual'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install typesensual
+
+## Usage
+
+### Configuring the client
+
+The first step is to configure the client. This is done by calling `Typesensual.configure` and
+passing a block to configure your parameters:
+
+```ruby
+# config/initializers/typesensual.rb
+Typesensual.configure do |config|
+  # The nodes in your cluster to connect to
+  config.nodes = [{ host: 'localhost', port: 8108, protocol: 'http' }]
+  # The API key to use for authentication
+  config.api_key = 'xyz'
+  # The environment you are running in (in Rails, this is set automatically)
+  config.env = 'test'
+end
+```
+
+### Creating your first index
+
+Once the client is configured, you can create your first index. This is done by creating a subclass
+of `Typesensual::Index` and defining your schema and how to load the data. For example, the
+following index might be used to index movies from an ActiveRecord model:
+
+```ruby
+# app/indices/movie_index.rb
+class MoviesIndex < Typesensual::Index
+  # The schema of the collection
+  schema do
+    enable_nested_fields
+
+    field 'title', type: 'string'
+    field 'release_date\..*', type: 'int32', facet: true
+    field 'average_rating', type: 'float', facet: true
+    field 'user_count', type: 'int32'
+    field 'genres', type: 'string[]', facet: true
+  end
+
+  def index_one(id)
+    movie = Movie.find(id).includes(:genres)
+
+    {
+      id: movie.id,
+      title: movie.title,
+      release_date: {
+        year: movie.release_date.year,
+        month: movie.release_date.month,
+        day: movie.release_date.day
+      },
+      average_rating: movie.average_rating,
+      user_count: movie.user_count,
+      genres: movie.genres.map(&:name)
+    }
+  end
+
+  def index_many(ids)
+    Movies.where(id: ids).includes(:genres).find_each do |movie|
+      yield {
+        id: movie.id,
+        title: movie.title,
+        release_date: {
+          year: movie.release_date.year,
+          month: movie.release_date.month,
+          day: movie.release_date.day
+        },
+        average_rating: movie.average_rating,
+        user_count: movie.user_count,
+        genres: movie.genres.map(&:name)
+      }
+    end
+  end
+end
+```
+
+### Loading data into your index
+
+Once you have defined your index, you can load data into it and update the alias to point to the
+indexed data. Typesensual provides rake tasks for this purpose if you use ActiveRecord:
+
+```console
+$ bundle exec rake typesensual:load[MoviesIndex,Movie]
+==> Indexing Movie into MoviesIndex (Version 1690076097)
+
+$ bundle exec rake typesensual:update_alias[MoviesIndex,1690076097]
+==> Alias for MoviesIndex
+Old: None (N/A)
+New: 1690076097 (2023-05-07 18:01:37)
+```
+
+Otherwise you can do similar to the following:
+
+```ruby
+collection = MoviesIndex.create!
+collection.index_many(Movie.ids, collection: collection)
+MoviesIndex.update_alias(collection)
+```
+
+### Searching your index
+
+Now that you have data in your index, you can search it! Typesensual provides a simple interface for
+this purpose, including pagination support:
+
+```ruby
+query = MoviesIndex.search(query: 'Your Name', query_by: 'title')
+query.per(10).page(2).load
+```
+
+The full interface for this is documented in the `Search`, `Results`, and `Hit` classes.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports, feature requests, and pull requests are welcome on [our GitHub][github].
+
+[github]: https://github.com/hummingbird-me/typesensual
+
+## License
+
+The gem is available as open source under the terms of the [MIT License][mit-license].
+
+[mit-license]: https://opensource.org/licenses/MIT

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/tasks/typesensual.rake

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+namespace :typesensual do
+  desc 'List typesensual indices and their collections'
+  task list: :environment do
+    Typesensual::RakeHelper.list_collections
+  end
+
+  desc 'Update the alias for an index'
+  task :update_alias, %i[index version] => :environment do |_, args|
+    Typesensual::RakeHelper.update_alias(
+      index: args[:index],
+      version: args[:version]
+    )
+  end
+
+  desc 'Index all records from a model into an index'
+  task :index, %i[index model] => :environment do |_, args|
+    Typesensual::RakeHelper.index(
+      index: args[:index],
+      model: args[:model]
+    )
+  end
+end

data/lib/typesensual/callbacks.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class Typesensual
+  class Callbacks
+    def initialize(index, should_update: ->(_record) { true })
+      @index = index
+      @should_update = should_update
+    end
+
+    def after_create_commit(record)
+      @index.index_one(record.id)
+    end
+
+    def after_update_commit(record)
+      @should_update.call(record) && @index.index_one(record.id)
+    end
+
+    def after_destroy_commit(record)
+      @index.remove_one(record.id)
+    end
+  end
+end