mongory 0.6.2 → 0.7.0

data/ext/mongory_ext/mongory-core/src/foundations/array.c

@@ -0,0 +1,246 @@
+/**
+ * @file array.c
+ * @brief Implements the mongory_array dynamic array.
+ *
+ * This file contains the internal implementation details for the mongory_array,
+ * including memory management, resizing, and the core array operations.
+ * It uses a private structure `mongory_array_private` which extends
+ * `mongory_array` with capacity information and the actual item storage.
+ */
+
+#include <string.h>
+#include "array_private.h"
+#include <mongory-core/foundations/array.h>
+#include <mongory-core/foundations/memory_pool.h>
+#include <mongory-core/foundations/value.h>
+
+/**
+ * @def MONGORY_ARRAY_INIT_SIZE
+ * @brief Initial capacity of a newly created mongory_array.
+ */
+#define MONGORY_ARRAY_INIT_SIZE 4
+
+/**
+ * @brief Resizes the internal storage of the array.
+ *
+ * Allocates a new block of memory for items and copies existing items to it.
+ * The old item storage is not explicitly freed here as it's managed by the
+ * memory pool; this function assumes the new allocation replaces the old one
+ * in terms of where `internal->items` points.
+ *
+ * @param self Pointer to the mongory_array instance.
+ * @param size The new capacity (number of elements) for the array.
+ * @return true if resizing was successful, false otherwise (e.g., memory
+ * allocation failure).
+ */
+bool mongory_array_resize(mongory_array *self, size_t size) {
+  mongory_array_private *internal = (mongory_array_private *)self;
+
+  // Allocate a new, larger block of memory for the items.
+  mongory_value **new_items = MG_ALLOC_ARY(self->pool, mongory_value*, size);
+  if (!new_items) {
+    // TODO: Propagate error via self->pool->error.
+    return false;
+  }
+
+  // Copy existing item pointers to the new memory block.
+  memcpy(new_items, internal->items, sizeof(mongory_value *) * self->count);
+
+  internal->items = new_items;
+  internal->capacity = size;
+  return true;
+}
+
+/**
+ * @brief Ensures the array has enough capacity for a given size, growing it if
+ * necessary.
+ *
+ * If the required size is smaller than the current capacity, this function does
+ * nothing. Otherwise, it calculates a new capacity (typically double the
+ * current, or more if needed to fit `size`) and calls mongory_array_resize.
+ *
+ * @param self Pointer to the mongory_array instance.
+ * @param size The minimum number of elements the array needs to accommodate.
+ * @return true if the array has sufficient capacity (or was successfully
+ * grown), false otherwise.
+ */
+// ============================================================================
+// Static Helper Functions
+// ============================================================================
+static inline bool mongory_array_grow_if_needed(mongory_array *self, size_t size) {
+  mongory_array_private *internal = (mongory_array_private *)self;
+  if (size < internal->capacity) {
+    return true;
+  }
+
+  // Calculate new capacity, typically doubling, until it's sufficient.
+  size_t new_capacity = internal->capacity * 2;
+  while (new_capacity <= size) {
+    new_capacity *= 2;
+  }
+
+  return mongory_array_resize(self, new_capacity);
+}
+
+/**
+ * @brief Internal implementation for iterating over array elements.
+ * @param self Pointer to the mongory_array instance.
+ * @param acc Accumulator/context passed to the callback.
+ * @param func Callback function executed for each item.
+ * @return true if iteration completed, false if callback stopped it.
+ */
+static inline bool mongory_array_each(mongory_array *self, void *acc, mongory_array_callback_func func) {
+  mongory_array_private *internal = (mongory_array_private *)self;
+  for (size_t i = 0; i < self->count; i++) {
+    mongory_value *item = internal->items[i];
+    if (!func(item, acc)) {
+      return false; // Callback requested to stop iteration.
+    }
+  }
+  return true;
+}
+
+/**
+ * @brief Internal implementation for adding an element to the end of the array.
+ * Grows the array if necessary.
+ * @param self Pointer to the mongory_array instance.
+ * @param value The mongory_value to add.
+ * @return true if successful, false on failure (e.g., memory allocation).
+ */
+static inline bool mongory_array_push(mongory_array *self, mongory_value *value) {
+  mongory_array_private *internal = (mongory_array_private *)self;
+  // Ensure there's space for one more element (current count).
+  if (!mongory_array_grow_if_needed(self, self->count)) {
+    return false;
+  }
+
+  internal->items[self->count++] = value;
+  return true;
+}
+
+/**
+ * @brief Internal implementation for retrieving an element by index.
+ * @param self Pointer to the mongory_array instance.
+ * @param index The index of the element.
+ * @return Pointer to the mongory_value, or NULL if index is out of bounds.
+ */
+static inline mongory_value *mongory_array_get(mongory_array *self, size_t index) {
+  mongory_array_private *internal = (mongory_array_private *)self;
+  if (index >= self->count) {
+    return NULL; // Index out of bounds.
+  }
+  return internal->items[index];
+}
+
+/**
+ * @brief Internal implementation for setting an element at a specific index.
+ *
+ * Grows the array if necessary. If the index is beyond the current count,
+ * intermediate elements are set to NULL, and the array's count is updated.
+ *
+ * @param self Pointer to the mongory_array instance.
+ * @param index The index at which to set the value.
+ * @param value The mongory_value to set.
+ * @return true if successful, false on failure (e.g., memory allocation).
+ */
+static inline bool mongory_array_set(mongory_array *self, size_t index, mongory_value *value) {
+  mongory_array_private *internal = (mongory_array_private *)self;
+  // Ensure capacity for the given index (index + 1 elements).
+  if (!mongory_array_grow_if_needed(self, index + 1)) {
+    return false;
+  }
+
+  // If setting beyond the current count, fill intermediate spots with NULL.
+  if (index >= self->count) {
+    for (size_t i = self->count; i < index; i++) {
+      internal->items[i] = NULL;
+    }
+    self->count = index + 1; // Update count to include the new element.
+  }
+
+  internal->items[index] = value;
+  return true;
+}
+
+/**
+ * @brief Creates and initializes a new mongory_array.
+ *
+ * Allocates memory for the array structure itself and its initial item storage
+ * using the provided memory pool. Assigns function pointers for array
+ * operations.
+ *
+ * @param pool The memory pool to use for allocations.
+ * @return Pointer to the new mongory_array, or NULL on allocation failure.
+ */
+mongory_array *mongory_array_new(mongory_memory_pool *pool) {
+  // First, allocate the private structure that holds all array metadata.
+  mongory_array_private *internal = MG_ALLOC_PTR(pool, mongory_array_private);
+  if (!internal) {
+    // TODO: Propagate error via pool->error (if pool is not NULL)
+    return NULL;
+  }
+
+  // Then, allocate the initial block of memory for the array items.
+  mongory_value **items = MG_ALLOC_ARY(pool, mongory_value*, MONGORY_ARRAY_INIT_SIZE);
+  if (!items) {
+    // If this fails, the 'internal' struct allocated above will be cleaned up
+    // by the pool, assuming it's a tracing pool.
+    // TODO: Propagate error via pool->error (if pool is not NULL)
+    return NULL;
+  }
+
+  // Initialize the public part of the array structure.
+  internal->base.pool = pool;
+  internal->base.count = 0;
+  internal->base.each = mongory_array_each;
+  internal->base.get = mongory_array_get;
+  internal->base.push = mongory_array_push;
+  internal->base.set = mongory_array_set;
+
+  // Initialize the private part of the array structure.
+  internal->items = items;
+  internal->capacity = MONGORY_ARRAY_INIT_SIZE;
+
+  return &internal->base; // Return pointer to the public structure.
+}
+
+static mongory_value** mongory_array_merge(mongory_memory_pool *pool, mongory_value **left, mongory_value **right, size_t count, void *ctx, size_t(*callback)(mongory_value *value, void *ctx)) {
+  mongory_value **result = MG_ALLOC_ARY(pool, mongory_value*, count);
+  size_t i = 0, j = 0, k = 0;
+  while (i < count / 2 && j < count - count / 2) {
+    if (callback(left[i], ctx) < callback(right[j], ctx)) {
+      result[k++] = left[i++];
+    } else {
+      result[k++] = right[j++];
+    }
+  }
+  while (i < count / 2) {
+    result[k++] = left[i++];
+  }
+  while (j < count - count / 2) {
+    result[k++] = right[j++];
+  }
+  return result;
+}
+
+static mongory_value** mongory_array_merge_sort(mongory_memory_pool *pool, mongory_value **origin_items, size_t count, void *ctx, size_t(*callback)(mongory_value *value, void *ctx)) {
+  if (count <= 1) {
+    return origin_items;
+  }
+  size_t mid = count / 2;
+  mongory_value **left = mongory_array_merge_sort(pool, origin_items, mid, ctx, callback);
+  mongory_value **right = mongory_array_merge_sort(pool, origin_items + mid, count - mid, ctx, callback);
+  return mongory_array_merge(pool, left, right, count, ctx, callback);
+}
+
+mongory_array *mongory_array_sort_by(mongory_array *self, mongory_memory_pool *temp_pool, void *ctx, size_t(*callback)(mongory_value *value, void *ctx)) {
+  mongory_array_private *internal = (mongory_array_private *)self;
+
+  mongory_value **new_items = mongory_array_merge_sort(temp_pool, internal->items, self->count, ctx, callback);
+  mongory_array_private *new_array = (mongory_array_private *)mongory_array_new(self->pool);
+  new_array->capacity = internal->capacity;
+  new_array->base.count = self->count;
+  new_array->items = MG_ALLOC_ARY(self->pool, mongory_value*, new_array->capacity);
+  memcpy(new_array->items, new_items, sizeof(mongory_value *) * self->count);
+  return &new_array->base;
+}

data/ext/mongory_ext/mongory-core/src/foundations/array_private.h

@@ -0,0 +1,18 @@
+#ifndef MONGORY_ARRAY_PRIVATE_H
+#define MONGORY_ARRAY_PRIVATE_H
+#include "mongory-core/foundations/array.h"
+#include "mongory-core/foundations/memory_pool.h"
+#include "mongory-core/foundations/value.h"
+#include <stdbool.h>
+
+bool mongory_array_resize(mongory_array *self, size_t size); // resize array
+
+typedef struct mongory_array_private {
+  mongory_array base;    // public array
+  mongory_value **items; // items pointer
+  size_t capacity;       // capacity
+} mongory_array_private;
+
+mongory_array *mongory_array_sort_by(mongory_array *self, mongory_memory_pool *temp_pool, void *ctx, size_t(*callback)(mongory_value *value, void *ctx));
+
+#endif // MONGORY_ARRAY_PRIVATE_H

data/ext/mongory_ext/mongory-core/src/foundations/config.c

@@ -0,0 +1,406 @@
+/**
+ * @file config.c
+ * @brief Implements global configuration and initialization for the Mongory
+ * library.
+ *
+ * This file manages the lifecycle of global resources such as the internal
+ * memory pool, regex adapter, matcher registration table, and value converters.
+ * It provides the `mongory_init` and `mongory_cleanup` functions, as well as
+ * setters for customizable components and a string copy utility.
+ */
+#include "mongory-core/foundations/config.h"
+#include "../matchers/base_matcher.h"      // For mongory_matcher_build_func
+#include "../matchers/compare_matcher.h"   // For specific matcher constructors
+#include "../matchers/composite_matcher.h" // For specific matcher constructors
+#include "../matchers/existance_matcher.h" // For specific matcher constructors
+#include "../matchers/inclusion_matcher.h" // For specific matcher constructors
+#include "../matchers/literal_matcher.h"   // For specific matcher constructors
+#include "../matchers/external_matcher.h"     // For specific matcher constructors
+#include "config_private.h"                // For mongory_regex_adapter, mongory_value_converter, etc.
+#include "mongory-core/foundations/memory_pool.h"
+#include "mongory-core/foundations/table.h"
+#include "mongory-core/foundations/value.h"
+#include <stdarg.h> // For va_list, va_start, va_end, vsnprintf
+#include <stdio.h>  // For snprintf
+#include <string.h> // For strlen, strcpy
+
+// Global internal memory pool for the library.
+mongory_memory_pool *mongory_internal_pool = NULL;
+// Global adapter for regex operations.
+mongory_regex_adapter *mongory_internal_regex_adapter = NULL;
+// Global table mapping matcher names (e.g., "$eq") to their build functions.
+mongory_table *mongory_matcher_mapping = NULL;
+// Global converter for handling external data types.
+mongory_value_converter *mongory_internal_value_converter = NULL;
+// Global adapter for custom matchers.
+mongory_matcher_custom_adapter *mongory_custom_matcher_adapter = NULL;
+
+/**
+ * @brief Initializes the internal memory pool if it hasn't been already.
+ * This pool is used for allocations by various library components.
+ */
+static inline void mongory_internal_pool_init() {
+  if (mongory_internal_pool != NULL) {
+    return; // Already initialized.
+  }
+  mongory_internal_pool = mongory_memory_pool_new();
+  // TODO: Add error handling if mongory_memory_pool_new returns NULL.
+}
+
+/**
+ * @brief Default regex function that always returns false.
+ * Used if no custom regex function is set via mongory_regex_func_set.
+ * @param pool Unused.
+ * @param pattern Unused.
+ * @param value Unused.
+ * @return Always false.
+ */
+static inline bool mongory_regex_default_func(mongory_memory_pool *pool, mongory_value *pattern, mongory_value *value) {
+  (void)pool;    // Mark as unused to prevent compiler warnings.
+  (void)pattern; // Mark as unused.
+  (void)value;   // Mark as unused.
+  return false;  // Default behavior is no match.
+}
+
+static inline char *mongory_regex_default_stringify_func(mongory_memory_pool *pool, mongory_value *pattern) {
+  (void)pool;    // Mark as unused to prevent compiler warnings.
+  (void)pattern; // Mark as unused.
+  return "//";   // Default behavior is no stringification.
+}
+
+/**
+ * @brief Initializes the internal regex adapter if it hasn't been already.
+ * Allocates the adapter structure from the internal pool and sets the default
+ * regex function.
+ */
+static inline void mongory_internal_regex_adapter_init() {
+  if (mongory_internal_regex_adapter != NULL) {
+    return; // Already initialized.
+  }
+
+  // Ensure the internal pool is initialized first.
+  mongory_internal_pool_init();
+  if (mongory_internal_pool == NULL) {
+    // Cannot proceed if pool initialization failed.
+    return;
+  }
+
+  mongory_internal_regex_adapter = MG_ALLOC_PTR(mongory_internal_pool, mongory_regex_adapter);
+  if (mongory_internal_regex_adapter == NULL) {
+    // TODO: Set error state (e.g., in mongory_internal_pool->error).
+    return;
+  }
+
+  mongory_internal_regex_adapter->match_func = mongory_regex_default_func;
+  mongory_internal_regex_adapter->stringify_func = mongory_regex_default_stringify_func;
+}
+
+/**
+ * @brief Sets the global regex matching function.
+ * Initializes the regex adapter if it's not already.
+ * @param func The custom regex function to use.
+ */
+void mongory_regex_func_set(mongory_regex_func func) {
+  if (mongory_internal_regex_adapter == NULL) {
+    mongory_internal_regex_adapter_init();
+  }
+  if (mongory_internal_regex_adapter != NULL) {
+    mongory_internal_regex_adapter->match_func = func;
+  }
+  // TODO: What if mongory_internal_regex_adapter is still NULL after init?
+  // (e.g. pool alloc failed)
+}
+
+/**
+ * @brief Sets the global regex stringify function.
+ * Initializes the regex adapter if it's not already.
+ * @param func The custom regex stringify function to use.
+ */
+void mongory_regex_stringify_func_set(mongory_regex_stringify_func func) {
+  if (mongory_internal_regex_adapter == NULL) {
+    mongory_internal_regex_adapter_init();
+  }
+  if (mongory_internal_regex_adapter != NULL) {
+    mongory_internal_regex_adapter->stringify_func = func;
+  }
+}
+/**
+ * @brief Initializes the matcher mapping table if it hasn't been already.
+ * This table stores registrations of matcher names to their constructor
+ * functions.
+ */
+static inline void mongory_matcher_mapping_init() {
+  if (mongory_matcher_mapping != NULL) {
+    return; // Already initialized.
+  }
+
+  // Ensure the internal pool is initialized first.
+  mongory_internal_pool_init();
+  if (mongory_internal_pool == NULL) {
+    return; // Cannot proceed if pool initialization failed.
+  }
+
+  mongory_matcher_mapping = mongory_table_new(mongory_internal_pool);
+  if (mongory_matcher_mapping == NULL) {
+    // TODO: Set error state.
+    return;
+  }
+}
+
+/**
+ * @brief Registers a matcher build function with a given name.
+ * The build function is stored in the global matcher mapping table.
+ * @param name The name of the matcher (e.g., "$eq", "$in").
+ * @param build_func A function pointer to the matcher's constructor.
+ */
+void mongory_matcher_register(char *name, mongory_matcher_build_func build_func) {
+  // Ensure mapping is initialized.
+  if (mongory_matcher_mapping == NULL) {
+    mongory_matcher_mapping_init();
+    if (mongory_matcher_mapping == NULL) {
+      // TODO: Set error: Cannot register if mapping init failed.
+      return;
+    }
+  }
+
+  // Wrap the function pointer in a mongory_value to store in the table.
+  mongory_value *value = mongory_value_wrap_ptr(mongory_internal_pool, build_func);
+  if (value == NULL) {
+    // TODO: Set error: Failed to wrap pointer.
+    return;
+  }
+
+  mongory_matcher_mapping->set(mongory_matcher_mapping, name, value);
+  // TODO: Check return value of set?
+}
+
+/**
+ * @brief Retrieves a matcher build function by its name from the global
+ * mapping.
+ * @param name The name of the matcher to retrieve.
+ * @return mongory_matcher_build_func A function pointer to the matcher's
+ * constructor, or NULL if not found.
+ */
+mongory_matcher_build_func mongory_matcher_build_func_get(char *name) {
+  if (mongory_matcher_mapping == NULL) {
+    return NULL; // Mapping not initialized or init failed.
+  }
+
+  mongory_value *value = mongory_matcher_mapping->get(mongory_matcher_mapping, name);
+  if (value == NULL || value->type != MONGORY_TYPE_POINTER) {
+    return NULL; // Not found or not a pointer type as expected.
+  }
+
+  return (mongory_matcher_build_func)value->data.ptr;
+}
+
+/**
+ * @brief Initializes the internal value converter if it hasn't been already.
+ * This converter holds function pointers for custom data type conversions.
+ */
+static inline void mongory_internal_value_converter_init() {
+  if (mongory_internal_value_converter != NULL) {
+    return; // Already initialized.
+  }
+
+  mongory_internal_pool_init();
+  if (mongory_internal_pool == NULL) {
+    return; // Cannot proceed if pool init failed.
+  }
+
+  mongory_internal_value_converter = MG_ALLOC_PTR(mongory_internal_pool, mongory_value_converter);
+  if (mongory_internal_value_converter == NULL) {
+    // TODO: Set error state.
+    return;
+  }
+  // Initialize function pointers to NULL or default no-op functions if desired.
+  mongory_internal_value_converter->deep_convert = NULL;
+  mongory_internal_value_converter->shallow_convert = NULL;
+  mongory_internal_value_converter->recover = NULL;
+}
+
+/**
+ * @brief Sets the function for deep conversion of external values.
+ * Initializes the value converter if necessary.
+ * @param deep_convert The deep conversion function.
+ */
+void mongory_value_converter_deep_convert_set(mongory_deep_convert_func deep_convert) {
+  if (mongory_internal_value_converter == NULL) {
+    mongory_internal_value_converter_init();
+  }
+  if (mongory_internal_value_converter != NULL) {
+    mongory_internal_value_converter->deep_convert = deep_convert;
+  }
+  // TODO: Handle case where converter is still NULL after init.
+}
+
+/**
+ * @brief Sets the function for shallow conversion of external values.
+ * Initializes the value converter if necessary.
+ * @param shallow_convert The shallow conversion function.
+ */
+void mongory_value_converter_shallow_convert_set(mongory_shallow_convert_func shallow_convert) {
+  if (mongory_internal_value_converter == NULL) {
+    mongory_internal_value_converter_init();
+  }
+  if (mongory_internal_value_converter != NULL) {
+    mongory_internal_value_converter->shallow_convert = shallow_convert;
+  }
+  // TODO: Handle case where converter is still NULL after init.
+}
+
+/**
+ * @brief Sets the function for recovering external values from mongory_value.
+ * Initializes the value converter if necessary.
+ * @param recover The recovery function.
+ */
+void mongory_value_converter_recover_set(mongory_recover_func recover) {
+  if (mongory_internal_value_converter == NULL) {
+    mongory_internal_value_converter_init();
+  }
+  if (mongory_internal_value_converter != NULL) {
+    mongory_internal_value_converter->recover = recover;
+  }
+  // TODO: Handle case where converter is still NULL after init.
+}
+
+/**
+ * @brief Initializes the custom matcher adapter if it hasn't been already.
+ * This adapter holds function pointers for custom matchers.
+ */
+static void mongory_custom_matcher_adapter_init() {
+  if (mongory_custom_matcher_adapter != NULL) {
+    return; // Already initialized.
+  }
+  mongory_custom_matcher_adapter = MG_ALLOC_PTR(mongory_internal_pool, mongory_matcher_custom_adapter);
+  if (mongory_custom_matcher_adapter == NULL) {
+    // TODO: Set error state.
+    return;
+  }
+  mongory_custom_matcher_adapter->build = NULL;
+  mongory_custom_matcher_adapter->lookup = NULL;
+  mongory_custom_matcher_adapter->match = NULL;
+}
+
+void mongory_custom_matcher_match_func_set(bool (*match)(void *external_matcher, mongory_value *value)) {
+  if (mongory_custom_matcher_adapter == NULL) {
+    mongory_custom_matcher_adapter_init();
+  }
+  mongory_custom_matcher_adapter->match = match;
+}
+
+void mongory_custom_matcher_build_func_set(mongory_matcher_custom_context *(*build)(char *key, mongory_value *condition, void *extern_ctx)) {
+  if (mongory_custom_matcher_adapter == NULL) {
+    mongory_custom_matcher_adapter_init();
+  }
+  mongory_custom_matcher_adapter->build = build;
+}
+
+void mongory_custom_matcher_lookup_func_set(bool (*lookup)(char *key)) {
+  if (mongory_custom_matcher_adapter == NULL) {
+    mongory_custom_matcher_adapter_init();
+  }
+  mongory_custom_matcher_adapter->lookup = lookup;
+}
+
+/**
+ * @brief Creates a copy of a string using the specified memory pool.
+ * @param pool The memory pool to use for allocation.
+ * @param str The null-terminated string to copy.
+ * @return A pointer to the newly allocated copy, or NULL if str is NULL or
+ * allocation fails.
+ */
+char *mongory_string_cpy(mongory_memory_pool *pool, char *str) {
+  if (str == NULL) {
+    return NULL;
+  }
+
+  size_t len = strlen(str);
+  char *new_str = (char *)MG_ALLOC(pool, len + 1); // +1 for null terminator.
+  if (new_str == NULL) {
+    pool->error = &MONGORY_ALLOC_ERROR;
+    return NULL;
+  }
+
+  strcpy(new_str, str);
+  return new_str;
+}
+
+char *mongory_string_cpyf(mongory_memory_pool *pool, char *format, ...) {
+  va_list args;
+  va_start(args, format);
+  int len = vsnprintf(NULL, 0, format, args);
+  va_end(args);
+  char *new_str = (char *)MG_ALLOC(pool, len + 1);
+  if (new_str == NULL) {
+    pool->error = &MONGORY_ALLOC_ERROR;
+    return NULL;
+  }
+  va_start(args, format);
+  vsnprintf(new_str, len + 1, format, args);
+  va_end(args);
+  new_str[len] = '\0';
+  return new_str;
+}
+
+/**
+ * @brief Initializes all core Mongory library components.
+ * This includes the internal memory pool, regex adapter, matcher mapping table,
+ * and value converter. It then registers all standard matcher types.
+ * This function MUST be called before using most other library features.
+ */
+void mongory_init() {
+  // Initialize all global components. Order can be important if one init
+  // depends on another (e.g., most depend on the pool).
+  mongory_internal_pool_init();
+  mongory_internal_regex_adapter_init();
+  mongory_matcher_mapping_init();
+  mongory_internal_value_converter_init();
+  mongory_custom_matcher_adapter_init();
+
+  // Register all standard matchers.
+  // Note: These registrations rely on mongory_internal_pool and
+  // mongory_matcher_mapping being successfully initialized.
+  // TODO: Add checks to ensure initializations were successful before
+  // proceeding.
+  mongory_matcher_register("$in", mongory_matcher_in_new);
+  mongory_matcher_register("$nin", mongory_matcher_not_in_new);
+  mongory_matcher_register("$eq", mongory_matcher_equal_new);
+  mongory_matcher_register("$ne", mongory_matcher_not_equal_new);
+  mongory_matcher_register("$gt", mongory_matcher_greater_than_new);
+  mongory_matcher_register("$gte", mongory_matcher_greater_than_or_equal_new);
+  mongory_matcher_register("$lt", mongory_matcher_less_than_new);
+  mongory_matcher_register("$lte", mongory_matcher_less_than_or_equal_new);
+  mongory_matcher_register("$exists", mongory_matcher_exists_new);
+  mongory_matcher_register("$present", mongory_matcher_present_new);
+  mongory_matcher_register("$regex", mongory_matcher_regex_new);
+  mongory_matcher_register("$and", mongory_matcher_and_new);
+  mongory_matcher_register("$or", mongory_matcher_or_new);
+  mongory_matcher_register("$elemMatch", mongory_matcher_elem_match_new);
+  mongory_matcher_register("$every", mongory_matcher_every_new);
+  mongory_matcher_register("$not", mongory_matcher_not_new);
+  mongory_matcher_register("$size", mongory_matcher_size_new);
+}
+
+/**
+ * @brief Cleans up all resources allocated by the Mongory library.
+ * This primarily involves freeing the internal memory pool, which should, in
+ * turn, release all memory allocated from it. It also resets global pointers
+ * to NULL. This should be called when the library is no longer needed to
+ * prevent memory leaks.
+ */
+void mongory_cleanup() {
+  if (mongory_internal_pool != NULL) {
+    // Freeing the pool should handle all allocations made from it,
+    // including the regex_adapter, matcher_mapping table (and its contents if
+    // they were allocated from this pool), and value_converter.
+    mongory_internal_pool->free(mongory_internal_pool);
+    mongory_internal_pool = NULL;
+  }
+
+  // Set other global pointers to NULL to indicate they are no longer valid.
+  // The memory they pointed to should have been managed by the internal pool.
+  mongory_internal_regex_adapter = NULL;
+  mongory_matcher_mapping = NULL; // The table itself and its nodes.
+  mongory_internal_value_converter = NULL;
+}