mongory 0.6.3 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78a3d73e3c078b41aeeeb727445229e4edce85ff089de2d7412c9e64bfc613c0
-  data.tar.gz: d7a9191a78a75b00f7a3ef7aa5d0b8e5ed8e8cb53e6a839e0873548da341849f
+  metadata.gz: 479d442ab8a04a0b6901af9c4833c89babb9acea2a4a8d93756115ee4ebfbf5c
+  data.tar.gz: e796d56379b2d116d802d6b23b90caed2659e3761f5cfe315a37ce089e37ccd5
 SHA512:
-  metadata.gz: 6cc1387d67ccf0559a5f12d2140b2f0349a16b8461ae3e6992a3ba199a1824b178236d91cd8fe31bdbd73a85d056074efac32440ef8827bb31e9aebb6fd544bf
-  data.tar.gz: 8f34cab007b5c692b48634686aa2931036b3f928da72004512b7e0de744dbe009656cac108f9f2d6d3d59b8d6d7e997b1b1b3f3a5865998bc83168c2dce60ea0
+  metadata.gz: 072eab3cbdb45d9b0a28f42201eddcf3a542518f7b37af2bc7b58f529989b28fb12f5b4df30a7677b5b864db542d8dfbf7fe218065e1f1e0450c076cff63ba82
+  data.tar.gz: fcc7d74ffd269bf477d2013112bc8a777b527130208fe4b464234446c7364f217c0ae3bac1d4dcd73dcc93e2d1bfc407e0d389cc9c8b53e8a7d71b7391656c25

data/.rubocop.yml

@@ -5,6 +5,8 @@ AllCops:
     - 'vendor/**/*'
     - 'node_modules/**/*'
     - 'tmp/**/*'
+    - 'examples/**/*'
+    - 'ext/**/*'
   TargetRubyVersion: 2.6
 
 Style/StringLiterals:

data/CHANGELOG.md

@@ -1,4 +1,46 @@
 # Changelog
+
+## [0.7.0] - 2025-08-17
+
+### Major Changes
+- Introduced Clang bridge for the C extension, wiring Ruby DSL to `mongory-core` via `Mongory::CMatcher` and `CQueryBuilder`.
+
+### Features
+- New `Mongory::CMatcher` with `match?`, `explain`, `trace`, `enable_trace`, `disable_trace`, and `print_trace`.
+- New `QueryBuilder#c` to switch a Ruby query into the C fast path seamlessly.
+- Regex bridging uses Ruby's `Regexp` under the hood for compatibility.
+- Custom matcher bridge: core can delegate to Ruby matchers (build/match/lookup) when needed.
+- Context bridge: shares `Utils::Context` between Ruby and C during matching.
+
+### Performance
+- Significant speedups for large datasets when using `CMatcher`/`CQueryBuilder`.
+
+### Build & Tooling
+- `ext/mongory_ext/extconf.rb` compiles `mongory-core` sources directly and normalizes GCC/Clang flags.
+- Added explicit submodule build rules to avoid copying/linking extra artifacts.
+
+### Docs
+- Updated README to document Clang bridge usage, availability checks, and examples.
+
+## [0.6.3] - 2025-05-27
+
+### Major Changes
+- Introduced `AbstractMultiMatcher` to unify logic for compound matchers (`$and`, `$or`, `$nor`)
+- Matchers are now sorted by `priority` to improve performance (early exit in `$and`, etc.)
+
+### Features
+- Each matcher can define its own `priority` to participate in execution optimization
+- `$in` and `$nin` matchers now normalize `Range` conditions into consistent matcher structures
+
+### Fixes
+- Explicitly use `::Hash` and `::Array` in `converted.rb` to avoid namespace conflicts
+
+### Tests
+- Added edge case specs for `$in` and `$nin` with `nil` and empty values
+
+### Chores
+- Ignore `.vscode/` in `.gitignore`
+
 ## [0.6.1] - 2025-04-24
 
 ### Major Changes

data/README.md

@@ -4,31 +4,52 @@ A Mongo-like in-memory query DSL for Ruby.
 
 Mongory lets you filter and query in-memory collections using syntax and semantics similar to MongoDB. It is designed for expressive chaining, symbolic operators, and composable matchers.
 
-## Positioning
-
-Mongory is designed to serve two types of users:
-
-1. For MongoDB users:
-   - Seamless integration with familiar query syntax
-   - Extends query capabilities for non-indexed fields
-   - No additional learning cost
-
-2. For non-MongoDB users:
-   - Initial learning cost for MongoDB-style syntax
-   - Long-term benefits:
-     - Improved code readability
-     - Better development efficiency
-     - Lower maintenance costs
-   - Ideal for teams valuing code quality and maintainability
+## Table of Contents
+
+- Overview & Positioning
+  - [Positioning](#positioning)
+- Getting Started
+  - [Requirements](#requirements)
+  - [Installation & Quick Start](#installation--quick-start)
+  - [Integration with MongoDB](#integration-with-mongodb)
+- Usage & Concepts
+  - [Core Concepts & API Reference](#core-concepts--api-reference)
+  - [Handling Dots in Field Names](docs/field_names.md)
+  - [Advanced Usage](docs/advanced_usage.md)
+  - [Debugging](#debugging)
+  - [Clang Bridge (C Extension)](docs/clang_bridge.md)
+- Performance
+  - [Performance & Benchmarks](docs/performance.md)
+  - [Supported Operators](#supported-operators)
+- Guides
+  - [Best Practices](#best-practices)
+  - [Limitations](#limitations)
+  - [FAQ](#faq)
+  - [Troubleshooting](#troubleshooting)
+  - [Migration Guide](docs/migration.md)
+- Project
+  - [Contributing](#contributing)
+  - [Code of Conduct](#code-of-conduct)
+  - [License](#license)
 
 ## Requirements
 
 - Ruby >= 2.6.0
 - No external database required
 
-## Quick Start
+## Installation & Quick Start
 
 ### Installation
+Install manually:
+```bash
+gem install mongory
+```
+
+Or add to your Gemfile:
+```ruby
+gem 'mongory'
+```
+
 #### Rails Generator
 
 You can install a starter configuration with:
@@ -42,16 +63,6 @@ This will generate `config/initializers/mongory.rb` and set up:
 - Class registration (e.g. `Array`, `ActiveRecord::Relation`, etc.)
 - Custom value/key converters for your ORM
 
-Or install manually:
-```bash
-gem install mongory
-```
-
-Or add to your Gemfile:
-```ruby
-gem 'mongory'
-```
-
 ### Basic Usage
 ```ruby
 records = [
@@ -73,6 +84,47 @@ limited = records.mongory
   .where(:age.gte => 18)       # Conditions apply to limited set
 ```
 
+### C Extension (Optional but Recommended)
+
+Mongory-rb includes an optional high-performance C extension powered by [mongory-core](https://github.com/mongoryhq/mongory-core):
+
+**System Dependencies:**
+- C99-compatible compiler (gcc/clang)
+- CMake >= 3.12 (optional; only needed if you want to build `mongory-core` standalone or run its native tests)
+
+**Installation:**
+```bash
+# macOS
+brew install cmake
+
+# Ubuntu/Debian
+sudo apt install cmake build-essential
+
+# CentOS/RHEL
+sudo yum install cmake gcc make
+```
+
+The C extension provides significant performance improvements for large datasets. If not available, Mongory-rb automatically falls back to pure Ruby implementation.
+
+Note: The Ruby C extension is built via Ruby's `mkmf` (see `ext/mongory_ext/extconf.rb`) and compiles `mongory-core` sources directly. You do not need CMake for normal gem installation.
+
+## Positioning
+
+Mongory is designed to serve two types of users:
+
+1. For MongoDB users:
+   - Seamless integration with familiar query syntax
+   - Extends query capabilities for non-indexed fields
+   - No additional learning cost
+
+2. For non-MongoDB users:
+   - Initial learning cost for MongoDB-style syntax
+   - Long-term benefits:
+     - Improved code readability
+     - Better development efficiency
+     - Lower maintenance costs
+   - Ideal for teams valuing code quality and maintainability
+
 ### Integration with MongoDB
 
 Mongory is designed to complement MongoDB, not replace it. Here's how to use them together:
@@ -149,77 +201,7 @@ Mongory::Matchers.register(:class_in, '$classIn', ClassInMatcher)
 You can define any matcher behavior and attach it to a `$operator` of your choice.
 Matchers can be composed, validated, and traced just like built-in ones.
 
-### Handling Dots in Field Names
-
-Mongory supports field names containing dots, which require escaping:
-
-```ruby
-# Sample data
-records = [
-  { "user.name" => "John", "age" => 25 },  # Field name contains a dot
-  { "user" => { "name" => "Bob" }, "age" => 30 }  # Nested field
-]
-
-# Field name contains a dot
-records.mongory.where("user\\.name" => "John")  # Two backslashes needed with double quotes
-# => [{ "user.name" => "John", "age" => 25 }]
-
-# or
-records.mongory.where('user\.name' => "John")   # One backslash needed with single quotes
-# => [{ "user.name" => "John", "age" => 25 }]
-
-# Nested field (no escaping needed)
-records.mongory.where("user.name" => "Bob")
-# => [{ "user" => { "name" => "Bob" }, "age" => 30 }]
-```
-
-Note:
-- With double quotes, backslashes need to be escaped (`\\`)
-- With single quotes, backslashes don't need to be escaped (`\`)
-- This behavior is consistent with MongoDB's query syntax
-- The escaped dot pattern (`\.`) matches fields where the dot is part of the field name
-- The unescaped dot pattern (`.`) matches nested fields in the document structure
-
-### Advanced Usage
-
-#### Complex Queries
-```ruby
-# Nested conditions
-users.mongory
-  .where(
-    :age.gte => 18,
-    :$or => [
-      { :status => 'active' },
-      { :status => 'pending', :created_at.gte => 1.week.ago }
-    ]
-  )
-
-# Using any_of for nested OR conditions
-users.mongory
-  .where(:age.gte => 18)
-  .any_of(
-    { :status => 'active' },
-    { :status => 'pending', :created_at.gte => 1.week.ago }
-  )
-
-# Array operations
-posts.mongory
-  .where(:tags.elem_match => { :name => 'ruby', :priority.gt => 5 })
-  .where(:comments.every => { :approved => true })
-```
-
-#### Integration with ActiveRecord
-```ruby
-class User < ActiveRecord::Base
-  def active_friends
-    friends.mongory
-      .where(:status => 'active')
-      .where(:last_seen.gte => 1.day.ago)
-  end
-end
-```
-
-### Query API Reference
+## Core Concepts & API Reference
 #### Registering Models
 
 To allow calling `.mongory` on collections, use `register`:
@@ -262,7 +244,7 @@ records.mongory
 This will share a mutatable, but stable context object to all matchers in matcher tree.
 To get your custom option, using `@context.config` in your custom matcher.
 
-### Debugging Queries
+## Debugging
 
 You can use `explain` to visualize the matcher tree structure:
 ```ruby
@@ -324,52 +306,6 @@ The debug output includes:
 - Field names highlighted in gray background
 - Detailed matching process for each record
 
-### Performance Considerations
-
-1. **Memory Usage**
-   - Mongory operates entirely in memory
-   - Consider your data size and memory constraints
-   - Proc-based implementation reduces memory usage
-   - Context system provides better memory management
-
-2. **Query Optimization**
-   - Complex conditions are evaluated in sequence
-   - Use `explain` to analyze query performance
-   - Empty conditions are optimized with cached Procs
-   - Context system allows fine-grained control over conversion
-
-3. **Benchmarks**
-  ```ruby
-    # Simple query (1000 records)
-    records.mongory.where(:age.gte => 18) # ~0.8ms
-
-    # Complex query (1000 records)
-    records.mongory.where(:$or => [{:age.gte => 18}, {:status => 'active'}]) # ~0.9ms
-
-    # Simple query (10000 records)
-    records.mongory.where(:age.gte => 18) # ~6.5ms
-
-    # Complex query (10000 records)
-    records.mongory.where(:$or => [{:age.gte => 18}, {:status => 'active'}]) # ~7.5ms
-
-    # Simple query (100000 records)
-    records.mongory.where(:age.gte => 18) # ~64.7ms
-
-    # Complex query (100000 records)
-    records.mongory.where(:$or => [{:age.gte => 18}, {:status => 'active'}]) # ~75.0ms
-
-    # Complex query with fast mode (100000 records)
-    records.mongory.where(:$or => [{:age.gte => 18}, {:status => 'active'}]).fast # ~42.8ms, about 3x of plain ruby
-  ```
-
-   Note: Performance varies based on:
-   - Data size
-   - Query complexity
-   - Hardware specifications
-   - Ruby version
-
-   Test in your environment to determine if performance meets your needs.
-
 ### Supported Operators
 
 | Category     | Operators                           |
@@ -387,6 +323,7 @@ Note: Some operators are Mongory-specific and not available in MongoDB:
   - Example: `where(:name.present => true)`
 - `$every`: Checks if all elements in an array match the given condition
   - Similar to `$elemMatch` but requires all elements to match
+  - At least one element in an array, or returns false
   - Example: `where(:tags.every => { :priority.gt => 5 })`
 
 Example:
@@ -496,37 +433,6 @@ end
    - All operations are performed in memory
    - Consider memory constraints
 
-## Migration Guide
-
-1. **From Array#select**
-  ```ruby
-    # Before
-    records.select { |r| r['age'] >= 18 && r['status'] == 'active' }
-
-    # After
-    records.mongory.where(:age.gte => 18, status: 'active')
-  ```
-
-2. **From ActiveRecord**
-  ```ruby
-    # Before
-    indexed_query.where("age >= ? AND status = ?", 18, 'active')
-
-    # After
-    indexed_query.mongory.where(:age.gte => 18, status: 'active')
-  ```
-
-3. **From MongoDB**
-  ```ruby
-    # Before (MongoDB)
-    users.where(:age.gte => 18, status: 'active')
-
-    # After (Mongory)
-    users.mongory.where(:age.gte => 18, status: 'active')
-
-    # Just the same.
-  ```
-
 ## Contributing
 
 Contributions are welcome! Here's how you can help:

data/Rakefile

@@ -9,4 +9,81 @@ require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new
 
+# Add support for rake-compiler if available
+begin
+  require 'rake/extensiontask'
+
+  Rake::ExtensionTask.new('mongory_ext') do |ext|
+    ext.lib_dir = 'ext/mongory_ext'
+    ext.ext_dir = 'ext/mongory_ext'
+    ext.source_pattern = '*.c'
+  end
+
+  # Add tasks for building with submodule
+  namespace :submodule do
+    desc 'Initialize/update the mongory-core submodule'
+    task :init do
+      sh 'git submodule update --init --recursive'
+    end
+
+    desc 'Update the mongory-core submodule to latest'
+    task :update do
+      sh 'git submodule update --remote'
+    end
+
+    desc 'Build mongory-core submodule'
+    task :build do
+      core_dir = 'ext/mongory_ext/mongory-core'
+      if Dir.exist?(core_dir)
+        Dir.chdir(core_dir) do
+          if File.exist?('build.sh')
+            sh 'chmod +x build.sh && ./build.sh'
+          else
+            sh 'mkdir -p build && cd build && cmake .. && make'
+          end
+        end
+      else
+        puts 'mongory-core submodule not found. Run rake submodule:init first.'
+      end
+    end
+  end
+
+  desc 'Build the project (without standalone mongory-core build)'
+  task build_all: ['submodule:init', :compile]
+
+  desc 'Clean all build artifacts including submodule'
+  task clean_all: :clean do
+    sh 'rm -rf ext/mongory_ext/mongory-core/build' if Dir.exist?('ext/mongory_ext/mongory-core/build')
+  end
+rescue LoadError
+  puts 'rake-compiler not available. Install it with: gem install rake-compiler'
+
+  # Fallback tasks without rake-compiler
+  desc 'Build the C extension manually'
+  task :compile do
+    Dir.chdir('ext/mongory_ext') do
+      sh 'ruby extconf.rb && make'
+    end
+  end
+
+  desc 'Clean the C extension manually'
+  task :clean do
+    Dir.chdir('ext/mongory_ext') do
+      sh 'make clean' if File.exist?('Makefile')
+      sh 'rm -f Makefile *.o foundations/*.o matchers/*.o mongory_ext.so'
+    end
+  end
+end
+
+# Custom build task using our build script
+desc 'Build using the custom build script'
+task :build_with_script do
+  sh 'scripts/build_with_core.sh'
+end
+
+desc 'Build in debug mode'
+task :build_debug do
+  sh 'scripts/build_with_core.sh --debug'
+end
+
 task default: %i(spec rubocop)