mongory 0.6.3 → 0.7.1

data/examples/benchmark.rb

@@ -8,12 +8,12 @@ Mongory.register(Array)
 Mongory.enable_symbol_snippets!
 
 def gc_handler
-  # GC.disable
+  GC.disable
   before = GC.stat
   yield
+  GC.start
   after = GC.stat
-  # GC.enable
-
+  GC.enable
   created = after[:total_allocated_objects] - before[:total_allocated_objects]
   freed   = after[:total_freed_objects] - before[:total_freed_objects]
   alive   = after[:heap_live_slots] - before[:heap_live_slots]
@@ -29,17 +29,18 @@ end
   # Generate test data
   records = (1..size).map do |_|
     {
-      'age' => rand(1..100),
+      'age' => [nil, rand(1..100)].sample,
       'status' => ['active', 'inactive'].sample
     }
   end
 
+  count_of_simple_query = records.count { |r| r['age'].is_a?(Numeric) && r['age'] >= 18 }
   # Simple query (Plain Ruby) test
   puts "\nSimple query (Plain Ruby) (#{size} records):"
   gc_handler do
     5.times do
       result = Benchmark.measure do
-        records.select { |r| r.key?('age') && r['age'] >= 18 }
+        records.select { |r| r['age'].is_a?(Numeric) && r['age'] >= 18 }
       end
       puts result
     end
@@ -48,12 +49,40 @@ end
   # Simple query (Mongory) test
   puts "\nSimple query (Mongory) (#{size} records):"
   gc_handler do
+    builder = records.mongory.where(:age.gte => 18)
+    5.times do
+      result = Benchmark.measure do
+        builder.to_a
+      end
+      puts result
+    end
+    raise "count mismatch" if builder.to_a.count != count_of_simple_query
+  end
+
+  # Simple query (Mongory::CMatcher) test
+  puts "\nSimple query (Mongory::CMatcher) (#{size} records):"
+  gc_handler do
+    matcher = Mongory::CMatcher.new(:age.gte => 18)
     5.times do
       result = Benchmark.measure do
-        records.mongory.where(:age.gte => 18).to_a
+        records.select { |r| matcher.match?(r) }
       end
       puts result
     end
+    raise "count mismatch" if records.count { |r| matcher.match?(r) } != count_of_simple_query
+  end
+
+  # Simple query (Mongory::CQueryBuilder) test
+  puts "\nSimple query (Mongory::CQueryBuilder) (#{size} records):"
+  gc_handler do
+    builder = Mongory::CQueryBuilder.new(records).where(:age.gte => 18)
+    5.times do
+      result = Benchmark.measure do
+        builder.to_a
+      end
+      puts result
+    end
+    raise "count mismatch" if builder.count != count_of_simple_query
   end
 
   # Complex query (Plain Ruby) test
@@ -64,42 +93,92 @@ end
         records.select do |r|
           next false unless r.key?('age') && r.key?('status')
 
-          r['age'] >= 18 || r['status'] == 'active'
+          r['age'].is_a?(Numeric) && r['age'] >= 18 ||  r['status'] == 'active'
         end
       end
       puts result
     end
   end
 
+  count_of_complex_query = records.count do |r|
+    r.key?('age') && r.key?('status') && (r['age'].is_a?(Numeric) && r['age'] >= 18 || r['status'] == 'active')
+  end
+
   # Complex query (Mongory) test
   puts "\nComplex query (Mongory) (#{size} records):"
   gc_handler do
+    builder = records.mongory.or(
+      { :age.gte => 18 },
+      { status: 'active' }
+    )
     5.times do
       result = Benchmark.measure do
-        records.mongory.where(
-          :$or => [
-            { :age.gte => 18 },
-            { status: 'active' }
-          ]
-        ).to_a
+        builder.to_a
       end
       puts result
     end
+    raise "count mismatch" if builder.count != count_of_complex_query
   end
 
   # Complex query (Mongory) test
   puts "\nComplex query (Mongory) fast mode (#{size} records):"
   gc_handler do
+    builder = records.mongory.or(
+      { :age.gte => 18 },
+      { status: 'active' }
+    ).fast
     5.times do
       result = Benchmark.measure do
-        records.mongory.where(
-          :$or => [
-            { :age.gte => 18 },
-            { status: 'active' }
-          ]
-        ).fast.to_a
+        builder.to_a
       end
       puts result
     end
+    raise "count mismatch" if builder.count != count_of_complex_query
+  end
+
+  puts "\nComplex query (Mongory) use CMatcher (#{size} records):"
+  gc_handler do
+    matcher = Mongory::CMatcher.new(
+      '$or' => [
+        { :age.gte => 18 },
+        { status: 'active' }
+      ]
+    )
+    5.times do
+      result = Benchmark.measure do
+        records.select { |r| matcher.match?(r) }
+      end
+      puts result
+    end
+    raise "count mismatch" if records.count { |r| matcher.match?(r) } != count_of_complex_query
+  end
+
+  puts "\nComplex query (Mongory) use CQueryBuilder (#{size} records):"
+  gc_handler do
+    builder = records.mongory.c.or(
+      { :age.gte => 18 },
+      { status: 'active' }
+    )
+    5.times do
+      result = Benchmark.measure do
+        builder.to_a
+      end
+      puts result
+    end
+    raise "count mismatch" if builder.count != count_of_complex_query
+  end
+
+  puts "\nTest Mongory::CMatcher#trace"
+  matcher = Mongory::CMatcher.new(
+    '$or' => [
+      { :age.gte => 18 },
+      { status: 'active' }
+    ]
+  )
+  # matcher.enable_trace
+  records.sample(30).each do |r|
+    matcher.trace(r)
   end
+  # matcher.print_trace
+  # matcher.disable_trace
 end

data/ext/mongory_ext/extconf.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# rubocop:disable Style/GlobalVars
+
+require 'mkmf'
+require 'rbconfig'
+
+# Set the path to mongory-core
+core_dir = File.expand_path('mongory-core', __dir__)
+core_src_dir = File.join(core_dir, 'src')
+core_include_dir = File.join(core_dir, 'include')
+
+# Check if mongory-core submodule exists
+unless Dir.exist?(core_dir)
+  puts "Error: mongory-core submodule not found at #{core_dir}"
+  puts 'Please run: git submodule update --init --recursive'
+  exit 1
+end
+
+# mongory-rb does not require cJSON; only mongory-core's tests use it, so we don't check cJSON here
+
+# Normalize compiler flags across GCC/Clang on CI (Ruby 2.6 on Ubuntu may inject clang-only warn flags)
+def scrub_flags_from_config!(keys, patterns)
+  [RbConfig::CONFIG, RbConfig::MAKEFILE_CONFIG].uniq.each do |cfg|
+    keys.each do |k|
+      next unless cfg[k]
+
+      patterns.each do |pat|
+        cfg[k] = cfg[k].gsub(/\b#{Regexp.escape(pat)}\b/, '')
+      end
+      cfg[k] = cfg[k].squeeze(' ').strip
+    end
+  end
+end
+
+gcc_like = RbConfig::CONFIG['GCC'] == 'yes' || RbConfig::CONFIG['CC'].to_s =~ /(gcc|cc)/
+if gcc_like
+  scrub_flags_from_config!(%w(warnflags cflags optflags debugflags), [
+    '-Wno-self-assign',
+    '-Wno-parentheses-equality',
+    '-Wno-constant-logical-operand'
+  ])
+end
+
+# Add include paths
+$INCFLAGS << " -I#{core_include_dir}"
+
+# Collect source files to compile directly into the extension
+foundations_src = Dir.glob(File.join(core_src_dir, 'foundations', '*.c'))
+matchers_src = Dir.glob(File.join(core_src_dir, 'matchers', '*.c'))
+
+$CFLAGS << ' -std=c99 -Wall -Wextra -Wno-incompatible-pointer-types -Wno-int-conversion'
+# Silence C90-style warnings on older GCC when standard flags are not fully applied by toolchains
+$CFLAGS << ' -Wno-declaration-after-statement -Wno-discarded-qualifiers'
+$CFLAGS << ' -O2' unless ENV['DEBUG']
+$CFLAGS << ' -g -O0 -DDEBUG' if ENV['DEBUG']
+
+# Let mkmf generate rules by listing all sources and corresponding objects
+$INCFLAGS << ' -I.'
+$INCFLAGS << " -I#{File.join(core_src_dir, 'foundations')}"
+$INCFLAGS << " -I#{File.join(core_src_dir, 'matchers')}"
+all_sources = ['mongory_ext.c'] + foundations_src + matchers_src
+$srcs = all_sources
+$objs = all_sources.map { |src| "#{File.basename(src, '.c')}.o" }
+
+# Generate Makefile
+create_makefile('mongory_ext')
+
+puts 'extconf.rb completed successfully'
+puts "Found #{foundations_src.length} foundation sources"
+puts "Found #{matchers_src.length} matcher sources"
+puts "Use 'make' to build the extension"
+
+# Append Makefile rules: explicit compilation rules for submodule sources to avoid copying/linking files
+mk = File.read('Makefile')
+
+# rubocop:disable Layout/HeredocIndentation
+rules = +"\n# --- custom rules for mongory-core submodule sources ---\n"
+(foundations_src + matchers_src).each do |src|
+  obj = "#{File.basename(src, '.c')}.o"
+  rules << <<~MAKE
+  #{obj}: #{src}
+	$(ECHO) compiling $<
+	$(Q) $(CC) $(INCFLAGS) $(CPPFLAGS) $(CFLAGS) $(COUTFLAG)$@ -c $(CSRCFLAG)$<
+
+  MAKE
+end
+
+File.write('Makefile', mk + rules)
+# rubocop:enable Layout/HeredocIndentation
+# rubocop:enable Style/GlobalVars

data/ext/mongory_ext/mongory-core/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c)

data/ext/mongory_ext/mongory-core/include/mongory-core/foundations/array.h

@@ -0,0 +1,105 @@
+#ifndef MONGORY_ARRAY
+#define MONGORY_ARRAY
+
+/**
+ * @file array.h
+ * @brief Defines the mongory_array structure and its associated operations.
+ *
+ * mongory_array is a dynamic array implementation that stores mongory_value
+ * pointers. It handles its own memory management for the array storage using a
+ * provided mongory_memory_pool. The array can grow automatically as new
+ * elements are added.
+ */
+
+#include "mongory-core/foundations/memory_pool.h"
+#include "mongory-core/foundations/value.h"
+#include <stdbool.h>
+
+/**
+ * @brief Forward declaration for the mongory_array structure.
+ */
+typedef struct mongory_array mongory_array;
+
+/**
+ * @brief Callback function type used by mongory_array_each_func.
+ *
+ * This function is called for each item in the array during an iteration.
+ *
+ * @param item A pointer to the current mongory_value item in the array.
+ * @param acc An accumulator or context pointer passed through the iteration.
+ * @return bool Return true to continue iteration, false to stop.
+ */
+typedef bool (*mongory_array_callback_func)(mongory_value *item, void *acc);
+
+/**
+ * @brief Function pointer type for iterating over the array.
+ * @param self A pointer to the mongory_array instance.
+ * @param acc An accumulator or context pointer to be passed to the callback.
+ * @param func The callback function to be executed for each item.
+ * @return bool Returns true if the iteration completed fully, false if it was
+ * stopped by a callback.
+ */
+typedef bool (*mongory_array_each_func)(mongory_array *self, void *acc, mongory_array_callback_func func);
+
+/**
+ * @brief Function pointer type for adding an element to the end of the array.
+ * @param self A pointer to the mongory_array instance.
+ * @param value A pointer to the mongory_value to add.
+ * @return bool Returns true if the value was successfully added, false
+ * otherwise (e.g., memory allocation failure).
+ */
+typedef bool (*mongory_array_push_func)(mongory_array *self, mongory_value *value);
+
+/**
+ * @brief Function pointer type for retrieving an element at a specific index.
+ * @param self A pointer to the mongory_array instance.
+ * @param index The index of the element to retrieve.
+ * @return mongory_value* A pointer to the mongory_value at the given index, or
+ * NULL if the index is out of bounds.
+ */
+typedef mongory_value *(*mongory_array_get_func)(mongory_array *self, size_t index);
+
+/**
+ * @brief Function pointer type for setting or replacing an element at a
+ * specific index.
+ *
+ * If the index is beyond the current count, the array will be grown, and
+ * intermediate elements will be initialized to NULL.
+ *
+ * @param self A pointer to the mongory_array instance.
+ * @param index The index at which to set the value.
+ * @param value A pointer to the mongory_value to set.
+ * @return bool Returns true if the value was successfully set, false otherwise
+ * (e.g., memory allocation failure).
+ */
+typedef bool (*mongory_array_set_func)(mongory_array *self, size_t index, mongory_value *value);
+
+/**
+ * @brief Creates a new mongory_array instance.
+ *
+ * The array is initialized with a default capacity and will use the provided
+ * memory pool for all its internal allocations related to storing elements.
+ *
+ * @param pool A pointer to the mongory_memory_pool to be used for allocations.
+ * @return mongory_array* A pointer to the newly created mongory_array, or NULL
+ * if creation fails (e.g., memory allocation failure).
+ */
+mongory_array *mongory_array_new(mongory_memory_pool *pool);
+
+/**
+ * @struct mongory_array
+ * @brief Represents a dynamic array of mongory_value pointers.
+ *
+ * This structure provides function pointers for common array operations,
+ * allowing for a somewhat object-oriented interface in C.
+ */
+struct mongory_array {
+  size_t count;                 /**< The current number of elements in the array. */
+  mongory_memory_pool *pool;    /**< The memory pool used for allocations. */
+  mongory_array_each_func each; /**< Function to iterate over elements in the array. */
+  mongory_array_push_func push; /**< Function to add an element to the end of the array. */
+  mongory_array_get_func get;   /**< Function to retrieve an element by index. */
+  mongory_array_set_func set;   /**< Function to set or replace an element at an index. */
+};
+
+#endif /* MONGORY_ARRAY */

data/ext/mongory_ext/mongory-core/include/mongory-core/foundations/config.h

@@ -0,0 +1,206 @@
+#ifndef MONGORY_FOUNDATIONS_CONFIG_H
+#define MONGORY_FOUNDATIONS_CONFIG_H
+
+/**
+ * @file config.h
+ * @brief Defines global configuration functions and types for the Mongory
+ * library.
+ *
+ * This includes initialization and cleanup routines, as well as functions
+ * for setting up custom behaviors like regex matching and value conversion.
+ * It also provides a string copying utility that uses the library's memory
+ * pool.
+ */
+
+#include "mongory-core/foundations/memory_pool.h"
+#include "mongory-core/foundations/value.h"
+#include <stdbool.h>
+
+/**
+ * @brief Function pointer type for custom regex matching.
+ *
+ * This function is called when a regex match is required.
+ *
+ * @param pool The memory pool to use for any allocations during the match.
+ * @param pattern The regex pattern (as a mongory_value, typically a string or
+ * regex type).
+ * @param value The value to match against (as a mongory_value, typically a
+ * string).
+ * @return bool True if the value matches the pattern, false otherwise.
+ */
+typedef bool (*mongory_regex_func)(mongory_memory_pool *pool, mongory_value *pattern, mongory_value *value);
+
+/**
+ * @brief Function pointer type for stringifying a regex pattern.
+ *
+ * This function is called when a regex pattern needs to be stringified.
+ *
+ * @param pool The memory pool to use for any allocations during the
+ * stringification.
+ * @param pattern The regex pattern (as a mongory_value, typically a string or
+ * regex type).
+ * @return char* A stringified representation of the regex pattern, or NULL on failure.
+ */
+typedef char* (*mongory_regex_stringify_func)(mongory_memory_pool *pool, mongory_value *pattern);
+
+/**
+ * @brief Function pointer type for deep conversion of an external value to a
+ * mongory_value.
+ *
+ * "Deep" implies that if the external value is a complex type (e.g., a struct
+ * representing a document or array), its contents should also be converted.
+ *
+ * @param pool The memory pool to use for allocating the new mongory_value and
+ * its data.
+ * @param value A pointer to the external value to convert.
+ * @return mongory_value* A new mongory_value representing the converted data,
+ * or NULL on failure.
+ */
+typedef mongory_value *(*mongory_deep_convert_func)(mongory_memory_pool *pool, void *value);
+
+/**
+ * @brief Function pointer type for shallow conversion of an external value to a
+ * mongory_value.
+ *
+ * "Shallow" implies that if the external value is complex, only a wrapper or
+ * pointer might be stored in the mongory_value, without deeply converting its
+ * contents.
+ *
+ * @param pool The memory pool to use for allocating the new mongory_value.
+ * @param value A pointer to the external value to convert.
+ * @return mongory_value* A new mongory_value, or NULL on failure.
+ */
+typedef mongory_value *(*mongory_shallow_convert_func)(mongory_memory_pool *pool, void *value);
+
+/**
+ * @brief Function pointer type for recovering an external value from a
+ * mongory_value.
+ *
+ * This is the reverse of a conversion, intended to get back the original
+ * external data representation if it was stored or wrapped.
+ *
+ * @param pool The memory pool (can be used if recovery involves allocation,
+ * though often it might just retrieve a stored pointer).
+ * @param value The mongory_value from which to recover the external data.
+ * @return void* A pointer to the recovered external value, or NULL if not
+ * possible.
+ */
+typedef void *(*mongory_recover_func)(mongory_memory_pool *pool, mongory_value *value);
+
+/**
+ * @brief Initializes the Mongory library.
+ *
+ * Sets up internal structures, including the global memory pool,
+ * regex adapter, matcher mapping, and value converter. This function
+ * should be called before any other Mongory library functions are used.
+ * It also registers the default set of matchers (e.g., $in, $eq).
+ */
+void mongory_init();
+
+/**
+ * @brief Cleans up resources used by the Mongory library.
+ *
+ * Frees the internal memory pool and resets global pointers. This should
+ * be called when the library is no longer needed to prevent memory leaks.
+ */
+void mongory_cleanup();
+
+/**
+ * @brief Sets the custom regex matching function.
+ *
+ * If not called, a default function that always returns false is used.
+ *
+ * @param func The custom regex function to use.
+ */
+void mongory_regex_func_set(mongory_regex_func func);
+
+/**
+ * @brief Sets the custom regex stringify function.
+ *
+ * If not called, a default function that always returns NULL is used.
+ *
+ * @param func The custom regex stringify function to use.
+ */
+void mongory_regex_stringify_func_set(mongory_regex_stringify_func func);
+
+/**
+ * @brief Sets the custom deep value conversion function.
+ * @param deep_convert The function to use for deep conversions.
+ */
+void mongory_value_converter_deep_convert_set(mongory_deep_convert_func deep_convert);
+
+/**
+ * @brief Sets the custom shallow value conversion function.
+ * @param shallow_convert The function to use for shallow conversions.
+ */
+void mongory_value_converter_shallow_convert_set(mongory_shallow_convert_func shallow_convert);
+
+/**
+ * @brief Sets the custom value recovery function.
+ * @param recover The function to use for recovering external values.
+ */
+void mongory_value_converter_recover_set(mongory_recover_func recover);
+
+/**
+ * @brief Function pointer type for matching a value against an external matcher.
+ * @param external_matcher The external reference to the matcher.
+ * @param value The value to match against.
+ * @return bool True if the value matches the matcher, false otherwise.
+ */
+typedef struct mongory_matcher_custom_context {
+  char *name; // Name of the custom matcher.
+  void *external_matcher; // External reference to the custom matcher.
+} mongory_matcher_custom_context;
+
+/**
+ * @brief Function pointer type for matching a value against an external matcher.
+ *
+ * This function is called when a value needs to be matched against an external
+ * matcher.
+ *
+ * @param external_matcher The external reference to the matcher.
+ * @param value The value to match against.
+ * @return bool True if the value matches the matcher, false otherwise.
+ */
+typedef struct mongory_matcher_custom_adapter {
+  bool (*match)(void *external_matcher, mongory_value *value); // Match a value against an external matcher.
+  mongory_matcher_custom_context *(*build)(char *key, mongory_value *condition, void *extern_ctx); // Build an external matcher reference.
+  bool (*lookup)(char *key); // Lookup a matcher reference by key.
+} mongory_matcher_custom_adapter;
+
+extern mongory_matcher_custom_adapter *mongory_custom_matcher_adapter;
+
+void mongory_custom_matcher_match_func_set(bool (*match)(void *external_matcher, mongory_value *value));
+void mongory_custom_matcher_build_func_set(mongory_matcher_custom_context *(*build)(char *key, mongory_value *condition, void *extern_ctx));
+void mongory_custom_matcher_lookup_func_set(bool (*lookup)(char *key));
+
+/**
+ * @brief Copies a string using the Mongory library's memory pool.
+ *
+ * Allocates memory from the given pool and copies the source string into it.
+ * The returned string is null-terminated.
+ *
+ * @param pool The memory pool to use for allocating the new string.
+ * @param str The source string to copy. If NULL, returns NULL.
+ * @return char* A pointer to the newly allocated and copied string, or NULL
+ * if allocation fails or str is NULL. The caller does not own this memory
+ * directly; it will be freed when the pool is freed.
+ */
+char *mongory_string_cpy(mongory_memory_pool *pool, char *str);
+
+/**
+ * @brief Copies a formatted string using the Mongory library's memory pool.
+ *
+ * Allocates memory from the given pool and copies the formatted string into it.
+ * The returned string is null-terminated.
+ *
+ * @param pool The memory pool to use for allocating the new string.
+ * @param format The format string to copy.
+ * @param ... The arguments to be formatted into the string.
+ * @return char* A pointer to the newly allocated and copied string, or NULL
+ * if allocation fails or format is NULL. The caller does not own this memory
+ * directly; it will be freed when the pool is freed.
+ */
+char *mongory_string_cpyf(mongory_memory_pool *pool, char *format, ...);
+
+#endif /* MONGORY_FOUNDATIONS_CONFIG_H */

data/ext/mongory_ext/mongory-core/include/mongory-core/foundations/error.h

@@ -0,0 +1,82 @@
+#ifndef MONGORY_ERROR
+#define MONGORY_ERROR
+
+/**
+ * @file error.h
+ * @brief Defines error types and structures for the Mongory library.
+ *
+ * This file provides an enumeration of possible error codes and a structure
+ * for representing error information, typically consisting of an error type
+ * and an associated message.
+ */
+
+#include <stdbool.h>
+
+/**
+ * @def MONGORY_ERROR_TYPE_MAGIC
+ * @brief A magic number used in generating enum values for error types.
+ * Helps in creating somewhat unique integer values for the enums.
+ */
+#define MONGORY_ERROR_TYPE_MAGIC 107
+
+/**
+ * @def MONGORY_ERROR_TYPE_MACRO
+ * @brief X-Macro for defining error types.
+ * This macro allows defining the error enum, string conversion, etc.,
+ * from a single list, promoting consistency.
+ * Each entry takes the enum name, a numeric suffix, and a string description.
+ */
+#define MONGORY_ERROR_TYPE_MACRO(_)                                                                                    \
+  _(MONGORY_ERROR_NONE, 10, "No Error")                                                                                \
+  _(MONGORY_ERROR_MEMORY, 11, "Memory Allocation Error")                                                               \
+  _(MONGORY_ERROR_INVALID_TYPE, 12, "Invalid Type Error")                                                              \
+  _(MONGORY_ERROR_OUT_OF_BOUNDS, 13, "Out of Bounds Error")                                                            \
+  _(MONGORY_ERROR_UNSUPPORTED_OPERATION, 14, "Unsupported Operation Error")                                            \
+  _(MONGORY_ERROR_INVALID_ARGUMENT, 15, "Invalid Argument Error")                                                      \
+  _(MONGORY_ERROR_IO, 16, "I/O Error")                                                                                 \
+  _(MONGORY_ERROR_PARSE, 17, "Parse Error")                                                                            \
+  _(MONGORY_ERROR_UNKNOWN, 99, "Unknown Error")
+
+/**
+ * @enum mongory_error_type
+ * @brief Enumerates the types of errors that can occur within the Mongory
+ * library. Values are generated using MONGORY_ERROR_TYPE_MACRO and
+ * MONGORY_ERROR_TYPE_MAGIC.
+ */
+typedef enum mongory_error_type {
+#define DEFINE_ERROR_ENUM(name, num, str) name = num * MONGORY_ERROR_TYPE_MAGIC,
+  MONGORY_ERROR_TYPE_MACRO(DEFINE_ERROR_ENUM)
+#undef DEFINE_ERROR_ENUM
+} mongory_error_type;
+
+/**
+ * @brief Converts a mongory_error_type enum to its string representation.
+ *
+ * @param type The error type enum value.
+ * @return const char* A string describing the error type. Returns "Unknown
+ * Error Type" if the type is not recognized.
+ */
+const char *mongory_error_type_to_string(enum mongory_error_type type);
+
+/**
+ * @struct mongory_error
+ * @brief Structure to hold error information.
+ *
+ * Contains the type of error and an optional descriptive message.
+ * The message string is expected to be a literal or have a lifetime
+ * managed elsewhere (e.g., allocated from a memory pool).
+ */
+typedef struct mongory_error {
+  mongory_error_type type; /**< The type of the error. */
+  const char *message;     /**< A descriptive message for the error. This message
+                                might be a string literal or allocated from a
+                                memory pool. Its lifetime should be considered
+                                carefully. */
+} mongory_error;
+
+static mongory_error MONGORY_ALLOC_ERROR = {
+  .type = MONGORY_ERROR_MEMORY,
+  .message = "Memory Allocation Failed",
+};
+
+#endif /* MONGORY_ERROR */