hquery 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7bb53d5ee3e79e1de862b0d74ecd772407093472ecda2affed913488583d6700
+  data.tar.gz: 6810348afbde8e4a3ba8659b9cb8d9615704e21de183ff73e4cf8276249aebb9
+SHA512:
+  metadata.gz: ff9d72ae2a9b43791f1e6f7a4dd5d77e51ad5f2f6d26f4cc99af00f526196e8aa06a3cdd46fd706c036e69a0d10de084e9b1d6739fd7f94a24433860b95dc143
+  data.tar.gz: cc26ce9baac650712d18ea4cf4d94a3def8b14593b31956f50b45d38276ad435e76973e43323b5ec903335b78f09d0eaa4aedd5ab4eab7fec1f214a75bf41af8

data/CHANGELOG.md

@@ -0,0 +1,133 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [1.0.1] - 2025-11-01
+
+### 🐛 Fixed
+* Fixed a bug where using `.or_where` as the very first clause in a query chain would fail.
+* Ensured `.count` and `.size` correctly respect any applied `.limit()` and `.offset()` chains.
+
+## [1.0.0] - 2025-10-28
+
+This is the first stable 1.0 release! It introduces auto-loading and finalizes the presenter and relationship APIs.
+
+### ✨ Added
+* **`Hq.load_from(directory_path)`:** A new, convenient way to auto-load all data definitions from a specified directory (e.g., `data/`).
+* **`Hq.reload_from(directory_path)`:** A helper for development to reload all definitions, perfect for use with tools like `listen`.
+
+### 💥 Changed
+* Query results (`Hq::InstanceWrapper` objects) are now fully **immutable** and **frozen** to prevent accidental mutation and improve thread-safety.
+* Improved type-coercion in `.order` to more robustly handle sorting columns with mixed data types (e.g., `Integer` and `String`).
+
+### ⛔ Removed
+* Removed the deprecated `item { ... }` block inside `Hq.define`. Please use the new `Hq.present(:model_name) { ... }` API introduced in `0.9.0`.
+
+## [0.9.0] - 2025-10-05
+
+### ✨ Added
+* **New Presenter API:** Introduced `Hq.present(:model_name) { ... }` as the new, cleaner way to define presenter methods. This uses standard `def` syntax and keeps presentation logic separate from data definition.
+* Instance wrappers now dynamically define accessor methods for all hash keys (e.g., `post.title`), which can be used within presenter methods. Presenter methods take precedence over key accessors.
+* Added `Hq.reload` helper for hot-reloading data in development environments.
+
+### ⚠️ Deprecated
+* The `item { ... }` block within `Hq.define` is now deprecated in favor of `Hq.present`. It will be removed in version 1.0.
+
+## [0.8.0] - 2025-09-15
+
+### ✨ Added
+* **Pagination:** Added `.limit()` and `.offset()` for basic pagination.
+* **Advanced Pagination:** Introduced the `.paginate(per_page: N)` method. This returns an enumerable `Hq::Page` object with helpers like `.current_page`, `.total_pages`, `.total_items`, `.next_page`, `.prev_page`, `is_first_page?`, and `is_last_page?`.
+
+## [0.7.0] - 2025-08-25
+
+### ✨ Added
+* **Many-to-Many Relationships:** Added support for `has_many :through` relationships.
+
+### 🐛 Fixed
+* `belongs_to` relationships now correctly return `nil` if the foreign key is missing or `nil`, rather than raising an error.
+* `has_many` relationships now correctly work with custom `primary_key` definitions on the target model.
+
+## [0.6.0] - 2025-07-30
+
+### ✨ Added
+* **Relationships:** Initial support for data relationships!
+    * `belongs_to`
+    * `has_many`
+    * `has_one`
+* Relationships support overrides for `class_name`, `foreign_key`, `primary_key`, and `owner_key`.
+* Related objects are returned as `Hq::InstanceWrapper` (`belongs_to`, `has_one`) or a new chainable `Hq::Query` (`has_many`).
+
+## [0.5.0] - 2025-07-10
+
+### ✨ Added
+* **`OR` Logic:** Added `.or_where` for building `OR` queries.
+* **Grouped Conditions:** Added block support to `where` and `or_where` for creating nested logical groups (e.g., `where { |q| q.where(a: 1).or_where(b: 2) }`).
+* **New Operators:** Added new hash condition operators:
+    * `:not` (e.g., `where(published: { not: true })`)
+    * `:in` and `:not_in` (e.g., `where(id: { in: [1, 3, 5] })`)
+    * `:exists` (for non-nil values)
+    * `:empty` (for `nil`, `""`, or `[]`)
+
+## [0.4.0] - 2025-06-15
+
+### ✨ Added
+* **Advanced `where` Operators:** `where` now supports more than just simple equality.
+    * `:greater_than` / `:gt`
+    * `:less_than` / `:lt`
+    * `:greater_than_or_equal` / `:gte`
+    * `:less_than_or_equal` / `:lte`
+    * `:contains` (for strings and arrays)
+    * `:starts_with` and `:ends_with` (for strings)
+* **Ranges:** `where` now accepts a Ruby `Range` (e.g., `where(views: 100..500)`).
+* **Ordering:** `.order` now accepts a second argument, `desc: true`, for descending sorts.
+* **Helpers:** Added `.find_by(...)` as a shortcut for `.where(...).first`.
+
+### 🐛 Fixed
+* `.order` now gracefully handles mixed-type comparisons (e.g., `String` and `Date`) without crashing.
+
+## [0.3.0] - 2025-05-20
+
+### ✨ Added
+* **Scopes:** Added support for reusable query scopes via `scope({...})` inside the `Hq.define` block.
+* Scopes can accept arguments (e.g., `scope recent: ->(n=5) { order(:created_at, desc: true).limit(n) }`).
+* Scopes are chainable with `where`, `order`, and other scopes.
+
+## [0.2.1] - 2025-05-01
+
+### 🐛 Fixed
+* `load` glob pattern now sorts files alphabetically before loading to ensure a predictable and consistent data order.
+* `Hq.configure` now correctly resolves paths relative to the application root.
+
+## [0.2.0] - 2025-04-25
+
+### ✨ Added
+* **File-Based Data:** Added `load 'path/to/*.rb'` loader. Data can now be loaded from individual Ruby files that return a hash.
+* Added `Hq.configure(data_path: '...')` to set a base directory for data files.
+* Added `Hq.defined_models` to inspect which models have been registered.
+
+### 💥 Changed
+* `Hq.define` is now lazy. Data from files is not loaded into memory until the first query is performed on that model.
+
+## [0.1.1] - 2025-04-12
+
+### 🐛 Fixed
+* Fixed a `NoMethodError` when using `.order` on a key where some records had a `nil` value. Nils are now always sorted last by default.
+* `hq(:model).first` on an empty dataset now correctly returns `nil` instead of raising an error.
+
+## [0.1.0] - 2025-04-10
+
+### ✨ Added
+* **Initial Release!**
+* `Hq.define(:model_name)` block.
+* `from_array([...])` data source.
+* Global `hq()` helper for easy querying.
+* Basic `.where(key: value)` for exact matching.
+* `.order(:key)` for ascending sort.
+* Query execution methods: `.to_a`, `.first`, `.last`, `.each`.
+* Results are wrapped in `Hq::InstanceWrapper` for hash-like access (`record[:key]`).

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 activestylus
+
+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.