mongory 0.6.2 → 0.7.0

data/ext/mongory_ext/mongory-core/src/matchers/existance_matcher.c

@@ -0,0 +1,144 @@
+/**
+ * @file existance_matcher.c
+ * @brief Implements $exists and $present matchers.
+ * This is an internal implementation file for the matcher module.
+ */
+#include "existance_matcher.h"
+#include "base_matcher.h"                   // For mongory_matcher_base_new
+#include "mongory-core/foundations/array.h" // For value->data.a->count
+#include "mongory-core/foundations/error.h" // For mongory_error types
+#include "mongory-core/foundations/table.h" // For value->data.t->count
+#include "mongory-core/foundations/value.h" // For mongory_value types
+#include <mongory-core.h>                   // General include
+
+/**
+ * @brief Validates that the condition for an existence/presence matcher is a
+ * boolean.
+ * @param condition The `mongory_value` condition to validate.
+ * @return True if `condition` is not NULL and is of type `MONGORY_TYPE_BOOL`,
+ * false otherwise.
+ */
+static bool mongory_matcher_validate_bool_condition(mongory_value *condition) {
+  if (condition == NULL) {
+    return false; // Condition itself must exist.
+  }
+  if (condition->type != MONGORY_TYPE_BOOL) {
+    return false; // Condition must be a boolean value.
+  }
+  return true;
+}
+
+/**
+ * @brief Match function for the $exists matcher.
+ *
+ * Compares the existence of the input `value` (i.e., `value != NULL`)
+ * with the boolean `matcher->condition->data.b`.
+ * - If `condition` is true, matches if `value` is not NULL.
+ * - If `condition` is false, matches if `value` is NULL.
+ *
+ * @param matcher The $exists matcher instance. Its condition must be boolean.
+ * @param value The value whose existence is being checked. This is typically
+ *              the result of a field lookup.
+ * @return True if the existence matches the condition, false otherwise.
+ */
+static inline bool mongory_matcher_exists_match(mongory_matcher *matcher, mongory_value *value) {
+  // The condition for $exists is a boolean (e.g., field: {$exists: true})
+  bool condition_expects_existence = matcher->condition->data.b;
+  bool actual_value_exists = (value != NULL);
+
+  return condition_expects_existence == actual_value_exists;
+}
+
+mongory_matcher *mongory_matcher_exists_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx) {
+  if (!mongory_matcher_validate_bool_condition(condition)) {
+    pool->error = MG_ALLOC_PTR(pool, mongory_error);
+    if (pool->error) {
+      pool->error->type = MONGORY_ERROR_INVALID_ARGUMENT;
+      pool->error->message = "$exists condition must be a boolean value.";
+    }
+    return NULL;
+  }
+  mongory_matcher *matcher = mongory_matcher_base_new(pool, condition, extern_ctx);
+  if (!matcher) {
+    return NULL;
+  }
+  matcher->match = mongory_matcher_exists_match;
+  matcher->original_match = mongory_matcher_exists_match;
+  matcher->name = mongory_string_cpy(pool, "Exists");
+  return matcher;
+}
+
+/**
+ * @brief Match function for the $present matcher.
+ *
+ * Determines if a `value` is "present" based on its type and content,
+ * and compares this with the boolean `matcher->condition->data.b`.
+ * - NULL value: Present if condition is false.
+ * - Array: Present if non-empty and condition is true.
+ * - Table: Present if non-empty and condition is true.
+ * - String: Present if non-NULL, non-empty, and condition is true.
+ * - MONGORY_TYPE_NULL: Not present (matches if condition is false).
+ * - Boolean: Present if its value matches the condition.
+ * - Other non-NULL types: Considered present if condition is true.
+ *
+ * @param matcher The $present matcher. Its condition must be boolean.
+ * @param value The value to check for presence.
+ * @return True if the presence status matches the condition, false otherwise.
+ */
+static inline bool mongory_matcher_present_match(mongory_matcher *matcher, mongory_value *value) {
+  bool condition_expects_presence = matcher->condition->data.b;
+
+  if (value == NULL) {
+    // A NULL value (field does not exist) is "present" if condition_expects_presence is false.
+    return !condition_expects_presence;
+  }
+
+  bool actual_value_is_present;
+  switch (value->type) {
+  case MONGORY_TYPE_ARRAY:
+    actual_value_is_present = (value->data.a != NULL && value->data.a->count > 0);
+    break;
+  case MONGORY_TYPE_TABLE:
+    actual_value_is_present = (value->data.t != NULL && value->data.t->count > 0);
+    break;
+  case MONGORY_TYPE_STRING:
+    actual_value_is_present = (value->data.s != NULL && *(value->data.s) != '\0');
+    break;
+  case MONGORY_TYPE_NULL:
+    actual_value_is_present = false; // An explicit BSON-style Null is not "present".
+    break;
+  case MONGORY_TYPE_BOOL:
+    // For a boolean value, "present" means its own value matches the condition.
+    // e.g. {$present: true} on a true boolean is true.
+    //      {$present: false} on a true boolean is false.
+    //      {$present: true} on a false boolean is false.
+    //      {$present: false} on a false boolean is true.
+    return value->data.b == condition_expects_presence;
+  default:
+    // For other types (int, double, pointer, regex, unsupported), if they are
+    // not NULL (checked above), they are considered "present".
+    actual_value_is_present = true;
+    break;
+  }
+
+  return condition_expects_presence == actual_value_is_present;
+}
+
+mongory_matcher *mongory_matcher_present_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx) {
+  if (!mongory_matcher_validate_bool_condition(condition)) {
+    pool->error = MG_ALLOC_PTR(pool, mongory_error);
+    if (pool->error) {
+      pool->error->type = MONGORY_ERROR_INVALID_ARGUMENT;
+      pool->error->message = "$present condition must be a boolean value.";
+    }
+    return NULL;
+  }
+  mongory_matcher *matcher = mongory_matcher_base_new(pool, condition, extern_ctx);
+  if (!matcher) {
+    return NULL;
+  }
+  matcher->match = mongory_matcher_present_match;
+  matcher->original_match = mongory_matcher_present_match;
+  matcher->name = mongory_string_cpy(pool, "Present");
+  return matcher;
+}

data/ext/mongory_ext/mongory-core/src/matchers/existance_matcher.h

@@ -0,0 +1,48 @@
+#ifndef MONGORY_MATCHER_EXISTANCE_H
+#define MONGORY_MATCHER_EXISTANCE_H
+
+/**
+ * @file existance_matcher.h
+ * @brief Defines constructors for existence and presence matchers ($exists,
+ * $present). This is an internal header for the matcher module.
+ */
+
+#include "base_matcher.h"
+#include "mongory-core/foundations/memory_pool.h"
+#include "mongory-core/foundations/value.h"
+#include "mongory-core/matchers/matcher.h" // For mongory_matcher structure
+
+/**
+ * @brief Creates an "exists" ($exists) matcher.
+ *
+ * This matcher checks for the existence of a field (i.e., if a value is
+ * non-NULL when retrieved from a table or array). The `condition` for this
+ * matcher must be a boolean `mongory_value`.
+ * - If `condition` is true, it matches if the field exists (value is not NULL).
+ * - If `condition` is false, it matches if the field does not exist (value is
+ * NULL).
+ *
+ * @param pool Memory pool for allocation.
+ * @param condition A `mongory_value` of type `MONGORY_TYPE_BOOL`.
+ * @return A new `$exists` matcher, or NULL on failure or invalid condition.
+ */
+mongory_matcher *mongory_matcher_exists_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+/**
+ * @brief Creates a "present" ($present) matcher.
+ *
+ * This matcher provides a more nuanced check than `$exists`. It considers a
+ * value "present" based on its type and content (e.g., non-empty array/table,
+ * non-empty string). The `condition` for this matcher must be a boolean
+ * `mongory_value`.
+ * - If `condition` is true, it matches if the value is considered "present".
+ * - If `condition` is false, it matches if the value is not "present" (e.g.,
+ * NULL, empty array/table/string).
+ *
+ * @param pool Memory pool for allocation.
+ * @param condition A `mongory_value` of type `MONGORY_TYPE_BOOL`.
+ * @return A new `$present` matcher, or NULL on failure or invalid condition.
+ */
+mongory_matcher *mongory_matcher_present_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+#endif /* MONGORY_MATCHER_EXISTANCE_H */

data/ext/mongory_ext/mongory-core/src/matchers/external_matcher.c

@@ -0,0 +1,121 @@
+/**
+ * @file external_matcher.c
+ * @brief Implements the $regex matcher.
+ * This is an internal implementation file for the matcher module.
+ */
+#include "external_matcher.h"
+#include "../foundations/config_private.h"   // For mongory_internal_regex_adapter
+#include "base_matcher.h"                    // For mongory_matcher_base_new
+#include "mongory-core/foundations/config.h" // For mongory_string_cpy
+#include "mongory-core/foundations/error.h"  // For MONGORY_ERROR_INVALID_ARGUMENT
+#include "mongory-core/foundations/memory_pool.h"
+#include "mongory-core/foundations/value.h"
+#include "matcher_explainable.h"
+#include "matcher_traversable.h"
+
+/**
+ * @brief Match function for the $regex matcher.
+ *
+ * Checks if the input `value` (which must be a string) matches the regex
+ * pattern stored in `matcher->condition`. The actual regex matching is
+ * performed by the function pointed to by
+ * `mongory_internal_regex_adapter->match_func`.
+ *
+ * @param matcher The $regex matcher instance.
+ * @param value The `mongory_value` to test; must be of type
+ * `MONGORY_TYPE_STRING`.
+ * @return True if the string value matches the regex, false otherwise or if
+ * input is not a string.
+ */
+static inline bool mongory_matcher_regex_match(mongory_matcher *matcher, mongory_value *value) {
+  if (!value || value->type != MONGORY_TYPE_STRING) {
+    return false; // Regex matching applies only to strings.
+  }
+  if (!mongory_internal_regex_adapter || !mongory_internal_regex_adapter->match_func) {
+    return false; // Regex adapter or function not configured.
+  }
+
+  // Delegate to the configured regex function.
+  return mongory_internal_regex_adapter->match_func(matcher->pool, matcher->condition, value);
+}
+
+/**
+ * @brief Validates that the condition for a $regex matcher is valid.
+ * The condition must be non-NULL and either a `MONGORY_TYPE_STRING` (pattern)
+ * or `MONGORY_TYPE_REGEX` (pre-compiled regex object).
+ * @param condition The `mongory_value` condition to validate.
+ * @return True if the condition is valid for a regex matcher, false otherwise.
+ */
+static inline bool mongory_matcher_regex_condition_validate(mongory_value *condition) {
+  return condition != NULL && (condition->type == MONGORY_TYPE_STRING || condition->type == MONGORY_TYPE_REGEX);
+}
+
+mongory_matcher *mongory_matcher_regex_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx) {
+  if (!mongory_matcher_regex_condition_validate(condition)) {
+    pool->error = MG_ALLOC_PTR(pool, mongory_error);
+    if (pool->error) {
+      pool->error->type = MONGORY_ERROR_INVALID_ARGUMENT;
+      pool->error->message = "$regex condition must be a string or a regex object.";
+    }
+    return NULL;
+  }
+
+  mongory_matcher *matcher = mongory_matcher_base_new(pool, condition, extern_ctx);
+  if (!matcher) {
+    return NULL;
+  }
+  matcher->match = mongory_matcher_regex_match;
+  matcher->original_match = mongory_matcher_regex_match;
+  matcher->name = mongory_string_cpy(pool, "Regex");
+  return matcher;
+}
+
+typedef struct mongory_custom_matcher {
+  mongory_matcher base;
+  void *external_matcher;
+} mongory_custom_matcher;
+
+/**
+ * @brief The match function for a custom matcher.
+ * @param matcher The matcher to match against.
+ * @param value The value to match.
+ * @return True if the value matches the matcher, false otherwise.
+ */
+bool mongory_matcher_custom_match(mongory_matcher *matcher, mongory_value *value) {
+  if (mongory_custom_matcher_adapter == NULL || mongory_custom_matcher_adapter->match == NULL) {
+    return false; // Custom matcher adapter not initialized.
+  }
+  mongory_custom_matcher *custom_matcher = (mongory_custom_matcher *)matcher;
+  return mongory_custom_matcher_adapter->match(custom_matcher->external_matcher, value);
+}
+
+/**
+ * @brief Creates a new custom matcher instance.
+ *
+ * @param pool The memory pool to use for the matcher's allocations.
+ * @param key The key for the custom matcher.
+ * @param condition The `mongory_value` representing the condition for this
+ * matcher.
+ * @return mongory_matcher* A pointer to the newly created custom matcher, or
+ * NULL on failure.
+ */
+mongory_matcher *mongory_matcher_custom_new(mongory_memory_pool *pool, char *key, mongory_value *condition, void *extern_ctx) {
+  if (mongory_custom_matcher_adapter == NULL || mongory_custom_matcher_adapter->build == NULL)
+    return NULL; // Custom matcher adapter not initialized.
+  mongory_custom_matcher *matcher = MG_ALLOC_PTR(pool, mongory_custom_matcher);
+  if (matcher == NULL)
+    return NULL;
+  mongory_matcher_custom_context *context = mongory_custom_matcher_adapter->build(key, condition, extern_ctx);
+  if (context == NULL)
+    return NULL;
+  matcher->base.pool = pool;
+  matcher->base.condition = condition;
+  matcher->base.name = context->name;
+  matcher->base.match = mongory_matcher_custom_match;
+  matcher->base.original_match = mongory_matcher_custom_match;
+  matcher->base.explain = mongory_matcher_base_explain;
+  matcher->base.traverse = mongory_matcher_leaf_traverse;
+  matcher->base.extern_ctx = extern_ctx;
+  matcher->external_matcher = context->external_matcher;
+  return (mongory_matcher *)matcher;
+}

data/ext/mongory_ext/mongory-core/src/matchers/external_matcher.h

@@ -0,0 +1,46 @@
+#ifndef MONGORY_MATCHER_EXTERNAL_H
+#define MONGORY_MATCHER_EXTERNAL_H
+
+/**
+ * @file external_matcher.h
+ * @brief Defines the constructor for matchers that are not built-in.
+ * This is an internal header for the matcher module.
+ */
+
+#include "base_matcher.h"
+#include "mongory-core/foundations/memory_pool.h"
+#include "mongory-core/foundations/value.h"
+#include "mongory-core/matchers/matcher.h" // For mongory_matcher structure
+
+/**
+ * @brief Creates a regular expression ($regex) matcher.
+ *
+ * This matcher tests if an input string `mongory_value` matches a given regular
+ * expression. The regular expression itself is provided in the `condition`
+ * value, which can be either a `MONGORY_TYPE_STRING` (the pattern) or a
+ * `MONGORY_TYPE_REGEX` (a pre-compiled regex object, if the underlying regex
+ * engine supports it and it's wrapped). The actual regex matching logic is
+ * delegated to a function provided via `mongory_regex_func_set` (see
+ * `foundations/config.h`).
+ *
+ * @param pool Memory pool for allocation.
+ * @param condition A `mongory_value` representing the regex pattern. This
+ * should be of type `MONGORY_TYPE_STRING` or `MONGORY_TYPE_REGEX`.
+ * @return A new $regex matcher, or NULL on failure or if the condition is
+ * invalid.
+ */
+mongory_matcher *mongory_matcher_regex_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+/**
+ * @brief Creates a new custom matcher instance.
+ *
+ * @param pool The memory pool to use for the matcher's allocations.
+ * @param key The key for the custom matcher.
+ * @param condition The `mongory_value` representing the condition for this
+ * matcher.
+ * @return mongory_matcher* A pointer to the newly created custom matcher, or
+ * NULL on failure.
+ */
+mongory_matcher *mongory_matcher_custom_new(mongory_memory_pool *pool, char *key, mongory_value *condition, void *extern_ctx);
+
+#endif /* MONGORY_MATCHER_EXTERNAL_H */

data/ext/mongory_ext/mongory-core/src/matchers/inclusion_matcher.c

@@ -0,0 +1,199 @@
+/**
+ * @file inclusion_matcher.c
+ * @brief Implements $in and $nin matchers for checking value inclusion in an
+ * array. This is an internal implementation file for the matcher module.
+ */
+#include "inclusion_matcher.h"
+#include "base_matcher.h"                   // For mongory_matcher_base_new
+#include "mongory-core/foundations/array.h" // For mongory_array operations
+#include "mongory-core/foundations/error.h" // For mongory_error
+#include "mongory-core/foundations/value.h" // For mongory_value
+#include <mongory-core.h>                   // General include
+
+/**
+ * @struct mongory_matcher_inclusion_context
+ * @brief Context structure used during the inclusion matching process.
+ *
+ * Stores the result of the comparison and the value being searched for.
+ */
+typedef struct mongory_matcher_inclusion_context {
+  bool result;          /**< Stores the outcome (true if found, false otherwise). */
+  mongory_value *value; /**< The value to search for within the condition array or
+                           target array. */
+} mongory_matcher_inclusion_context;
+
+/**
+ * @brief Validates that the condition for an inclusion matcher is a valid
+ * array.
+ * @param condition The `mongory_value` condition to validate.
+ * @return True if `condition` is not NULL, is of type `MONGORY_TYPE_ARRAY`,
+ * and its internal array data `condition->data.a` is not NULL. False otherwise.
+ */
+static inline bool mongory_matcher_validate_array_condition(mongory_value *condition) {
+  if (condition == NULL) {
+    return false; // Condition must exist.
+  }
+  if (condition->type != MONGORY_TYPE_ARRAY) {
+    return false; // Condition must be an array.
+  }
+  if (condition->data.a == NULL) {
+    return false; // The array data within the condition must be valid.
+  }
+  return true;
+}
+
+/**
+ * @brief Callback function for `mongory_array_each` to compare a single value
+ * (`b` from context) against an element (`a`) from the condition array.
+ *
+ * This is used when the value being matched against $in is a scalar.
+ *
+ * @param item_in_condition_array The current item (`a`) from the condition array.
+ * @param acc Pointer to `mongory_matcher_inclusion_context`. `context->value`
+ *            is the scalar value (`b`) being searched for.
+ * @return `false` (stop iteration) if `item_in_condition_array` equals
+ * `context->value`, `true` (continue iteration) otherwise.
+ */
+static inline bool mongory_matcher_inclusion_value_compare(mongory_value *item_in_condition_array, void *acc) {
+  mongory_matcher_inclusion_context *context = (mongory_matcher_inclusion_context *)acc;
+  mongory_value *scalar_value_to_find = context->value;
+
+  if (!item_in_condition_array || !scalar_value_to_find || !item_in_condition_array->comp) {
+    // Cannot compare if item or value is NULL, or if item has no compare function.
+    // Treat as not equal for safety, continue search.
+    return true;
+  }
+
+  // Check if the item from condition array equals the scalar value we're looking for.
+  context->result = (item_in_condition_array->comp(item_in_condition_array, scalar_value_to_find) == 0);
+
+  return !context->result; // Stop if found (result is true), continue if not found.
+}
+
+/**
+ * @brief Callback function for `mongory_array_each` to compare an array (`a`
+ * from context->value) against an element (`b_scalar_in_condition_array`) from
+ * the condition array.
+ *
+ * This is used when the value being matched against $in is an array itself.
+ * It checks if `b_scalar_in_condition_array` exists in the input array `a`.
+ *
+ * @param b_scalar_in_condition_array The current scalar item (`b`) from the condition array.
+ * @param acc Pointer to `mongory_matcher_inclusion_context`. `context->value`
+ *            is the input array (`a`) being checked.
+ * @return `false` (stop iteration) if `b_scalar_in_condition_array` is found
+ * in `context->value` (the input array), `true` (continue) otherwise.
+ */
+static inline bool mongory_matcher_inclusion_array_compare(mongory_value *b_scalar_in_condition_array, void *acc) {
+  mongory_matcher_inclusion_context *outer_context = (mongory_matcher_inclusion_context *)acc;
+  // outer_context->value is the input array we are checking.
+  mongory_array *input_array_a = outer_context->value->data.a;
+
+  // We want to find if b_scalar_in_condition_array is present in input_array_a.
+  // Create a new context for searching b_scalar_in_condition_array within input_array_a.
+  mongory_matcher_inclusion_context inner_search_ctx = {false, b_scalar_in_condition_array};
+
+  // Iterate through input_array_a to find b_scalar_in_condition_array.
+  // mongory_matcher_inclusion_value_compare will set inner_search_ctx.result to true if found.
+  // It returns !result, so if found (result=true), it returns false (stop).
+  bool iteration_stopped =
+      !input_array_a->each(input_array_a, &inner_search_ctx, mongory_matcher_inclusion_value_compare);
+
+  if (iteration_stopped && inner_search_ctx.result) {
+    // b_scalar_in_condition_array was found in input_array_a.
+    outer_context->result = true; // Mark overall $in as successful.
+    return false;                 // Stop iterating the outer (condition) array.
+  }
+
+  return true; // b_scalar_in_condition_array was not in input_array_a, continue.
+}
+
+/**
+ * @brief Match function for the $in matcher.
+ *
+ * If `value_to_check` is a scalar, it checks if `value_to_check` is present in
+ * `matcher->condition` (which must be an array).
+ * If `value_to_check` is an array, it checks if any element of `value_to_check`
+ * is present in `matcher->condition` (array intersection).
+ *
+ * @param matcher The $in matcher instance.
+ * @param value_to_check The value to check for inclusion.
+ * @return True if `value_to_check` (or one of its elements) is found in the
+ * condition array, false otherwise.
+ */
+static inline bool mongory_matcher_in_match(mongory_matcher *matcher, mongory_value *value_to_check) {
+  if (!value_to_check || !matcher->condition || !matcher->condition->data.a) {
+    // Invalid inputs or condition is not a proper array.
+    return false;
+  }
+
+  mongory_matcher_inclusion_context ctx = {false, value_to_check};
+  mongory_array *condition_array = matcher->condition->data.a;
+
+  if (value_to_check->type == MONGORY_TYPE_ARRAY) {
+    if (value_to_check->data.a == NULL)
+      return false; // Invalid input array
+    // Case: $in: [c1, c2], input: [a1, a2]
+    // We need to check if any c_i is in [a1, a2] OR if any a_i is in [c1, c2].
+    // The current mongory_matcher_inclusion_array_compare checks if an element from
+    // condition_array is present in value_to_check (the input array).
+    // So, we iterate the condition_array, and for each element, check if it's in value_to_check.
+    condition_array->each(condition_array, &ctx, mongory_matcher_inclusion_array_compare);
+  } else {
+    // Case: $in: [c1, c2], input: scalar_value
+    // Check if scalar_value is any of c_i.
+    condition_array->each(condition_array, &ctx, mongory_matcher_inclusion_value_compare);
+  }
+  return ctx.result; // True if any comparison led to result=true.
+}
+
+mongory_matcher *mongory_matcher_in_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx) {
+  if (!mongory_matcher_validate_array_condition(condition)) {
+    pool->error = MG_ALLOC_PTR(pool, mongory_error);
+    if (pool->error) {
+      pool->error->type = MONGORY_ERROR_INVALID_ARGUMENT;
+      pool->error->message = "$in condition must be a valid array.";
+    }
+    return NULL;
+  }
+  mongory_matcher *matcher = mongory_matcher_base_new(pool, condition, extern_ctx);
+  if (!matcher) {
+    return NULL;
+  }
+  matcher->match = mongory_matcher_in_match;
+  matcher->original_match = mongory_matcher_in_match;
+  matcher->name = mongory_string_cpy(pool, "In");
+  return matcher;
+}
+
+/**
+ * @brief Match function for the $nin (not in) matcher.
+ * Simply negates the result of the $in logic.
+ * @param matcher The $nin matcher instance.
+ * @param value The value to check.
+ * @return True if the value is NOT found according to $in logic, false
+ * otherwise.
+ */
+static inline bool mongory_matcher_not_in_match(mongory_matcher *matcher, mongory_value *value) {
+  // $nin is true if $in is false.
+  return !mongory_matcher_in_match(matcher, value);
+}
+
+mongory_matcher *mongory_matcher_not_in_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx) {
+  if (!mongory_matcher_validate_array_condition(condition)) {
+    pool->error = MG_ALLOC_PTR(pool, mongory_error);
+    if (pool->error) {
+      pool->error->type = MONGORY_ERROR_INVALID_ARGUMENT;
+      pool->error->message = "$nin condition must be a valid array.";
+    }
+    return NULL;
+  }
+  mongory_matcher *matcher = mongory_matcher_base_new(pool, condition, extern_ctx);
+  if (!matcher) {
+    return NULL;
+  }
+  matcher->match = mongory_matcher_not_in_match;
+  matcher->original_match = mongory_matcher_not_in_match;
+  matcher->name = mongory_string_cpy(pool, "Nin");
+  return matcher;
+}

data/ext/mongory_ext/mongory-core/src/matchers/inclusion_matcher.h

@@ -0,0 +1,46 @@
+#ifndef MONGORY_MATCHER_INCLUSION_H
+#define MONGORY_MATCHER_INCLUSION_H
+
+/**
+ * @file inclusion_matcher.h
+ * @brief Defines constructors for inclusion matchers ($in, $nin).
+ * This is an internal header for the matcher module.
+ *
+ * These matchers check if a value is present or not present in a given array
+ * of values.
+ */
+
+#include "base_matcher.h"
+#include "mongory-core/foundations/memory_pool.h"
+#include "mongory-core/foundations/value.h"
+#include "mongory-core/matchers/matcher.h" // For mongory_matcher structure
+
+/**
+ * @brief Creates an "in" ($in) matcher.
+ *
+ * Matches if the input value is equal to any of the values in the `condition`
+ * array. If the input value itself is an array, it matches if any element of
+ * the input array is found in the `condition` array (set intersection).
+ *
+ * @param pool Memory pool for allocation.
+ * @param condition A `mongory_value` of type `MONGORY_TYPE_ARRAY` containing
+ * the set of values to check against.
+ * @return A new `$in` matcher, or NULL on failure or invalid condition.
+ */
+mongory_matcher *mongory_matcher_in_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+/**
+ * @brief Creates a "not in" ($nin) matcher.
+ *
+ * Matches if the input value is not equal to any of the values in the
+ * `condition` array. If the input value itself is an array, it matches if no
+ * element of the input array is found in the `condition` array.
+ *
+ * @param pool Memory pool for allocation.
+ * @param condition A `mongory_value` of type `MONGORY_TYPE_ARRAY` containing
+ * the set of values to check against.
+ * @return A new `$nin` matcher, or NULL on failure or invalid condition.
+ */
+mongory_matcher *mongory_matcher_not_in_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+#endif /* MONGORY_MATCHER_INCLUSION_H */