SpacetimeDB/crates/bindings-cpp/include/spacetimedb.h

#pragma once

/**
 * SpacetimeDB C++20 Module API - Single Include Header
 * 
 * Complete, optimized API for building SpacetimeDB modules with support for:
 * - Tables with field constraints
 * - BSATN serialization
 * - Reducers (user-defined and lifecycle)
 * - Database operations
 * - Logging and debugging
 * 
 * =============================================================================
 * USAGE EXAMPLES
 * =============================================================================
 * 
 * Table Definition:
 *    struct User {
 *        uint32_t id;
 *        std::string username;
 *        std::string email;
 *    };
 *    SPACETIMEDB_STRUCT(User, id, username, email)
 *    SPACETIMEDB_TABLE(User, "users", Public,
 *        PrimaryKeyAutoInc(id),
 *        Unique(email)
 *    )
 * 
 * Lifecycle Reducers:
 *    SPACETIMEDB_INIT(init_module, ReducerContext ctx) {
 *        LOG_INFO("Module initialized!");
 *        return Ok();
 *    }
 * 
 * User Reducers:
 *    void add_user(ReducerContext ctx, std::string username, std::string email) {
 *        User user{0, username, email}; // id auto-generated
 *        ctx.db.table<User>("users").insert(user);
 *    }
 *    REGISTER_REDUCER(add_user, add_user)
 */

// =============================================================================
// STANDARD LIBRARY DEPENDENCIES
// =============================================================================

#include <cstdint>
#include <string>
#include <vector>
#include <optional>
#include <array>
#include <string_view>
#include <concepts>
#include <functional>
#include <type_traits>
#include <span>

// =============================================================================
// CORE SPACETIMEDB TYPE SYSTEM
// =============================================================================

// Core types and BSATN support
#include "spacetimedb/bsatn/types.h"
#include "spacetimedb/bsatn/timestamp.h"
#include "spacetimedb/bsatn/time_duration.h"
#include "spacetimedb/bsatn/uuid.h"
#include "spacetimedb/bsatn/result.h"
#include "spacetimedb/bsatn/writer.h"
#include "spacetimedb/bsatn/reader.h"
#include "spacetimedb/bsatn/algebraic_type.h"
#include "spacetimedb/bsatn/traits.h"
#include "spacetimedb/bsatn/sum_type.h"
#include "spacetimedb/bsatn/schedule_at.h"

// Autogenerated types for module definition
#include "spacetimedb/internal/autogen/SumType.g.h"  // Complete SumType definition first
#include "spacetimedb/internal/autogen/RawModuleDefV9.g.h"
#include "spacetimedb/internal/autogen/RawTableDefV9.g.h"
#include "spacetimedb/internal/autogen/Typespace.g.h"
#include "spacetimedb/internal/autogen/ProductType.g.h"
#include "spacetimedb/internal/autogen/ProductTypeElement.g.h"
#include "spacetimedb/internal/autogen/TableAccess.g.h"
#include "spacetimedb/internal/autogen/TableType.g.h"

// =============================================================================
// MODULE SYSTEM INFRASTRUCTURE
// =============================================================================

// Core module infrastructure
#include "spacetimedb/internal/Module.h"
#include "spacetimedb/internal/field_registration.h"

// Logging system
#include "spacetimedb/logger.h"

// =============================================================================
// TABLE AND CONSTRAINT SYSTEM
// =============================================================================

// Type extensions for special types
#include "spacetimedb/bsatn/type_extensions.h"

// Table operations and constraint support
#include "spacetimedb/table.h"
#include "spacetimedb/database.h"
#include "spacetimedb/table_with_constraints.h"

// Range queries
#include "spacetimedb/range_queries.h"

// =============================================================================
// REDUCER SYSTEM
// =============================================================================

// Reducer context and macros
#include "spacetimedb/reducer_context.h"
#include "spacetimedb/reducer_macros.h"
#include "spacetimedb/reducer_error.h"

// Client visibility filters
#include "spacetimedb/client_visibility_filter.h"

// =============================================================================
// PROCEDURE SYSTEM
// =============================================================================

// Procedure context and macros
#include "spacetimedb/procedure_macros.h"
#ifdef SPACETIMEDB_UNSTABLE_FEATURES
#include "spacetimedb/handler_context.h"
#include "spacetimedb/router.h"
#include "spacetimedb/http_handler_macros.h"
#endif

// =============================================================================
// VIEW SYSTEM
// =============================================================================

// View context and macros
#include "spacetimedb/view_macros.h"
#include "spacetimedb/query_builder.h"

// =============================================================================
// CONVENIENCE ALIASES AND COMPATIBILITY
// =============================================================================

// Convenience aliases for table access levels
namespace SpacetimeDB {
    // Re-export table access constants for convenience
    constexpr auto Public = Internal::TableAccess::Public;
    constexpr auto Private = Internal::TableAccess::Private;
}

// =============================================================================
// UNIFIED MACRO SYSTEM
// =============================================================================

// Use unified macro system
#include "spacetimedb/macros.h"


// =============================================================================
// MODULE DEFINITION UTILITIES
// =============================================================================

// Forward declarations for module system compatibility
namespace spacetimedb {
    // Template specialization support
    template<typename T> struct table_metadata;
    
    namespace internal {
        /**
         * @brief Serialize the current module definition to BSATN
         * @return Serialized module definition
         */
        inline std::vector<uint8_t> serialize_module_def() {
            return SpacetimeDB::Internal::Module::SerializeModuleDef();
        }
    }

    // =============================================================================
    // CONVENIENCE TYPE ALIASES
    // =============================================================================
    
    // Vector type aliases for SpacetimeDB types
    using VecTimeDuration = std::vector<::SpacetimeDB::TimeDuration>;
}

// =============================================================================
// DOCUMENTATION AND USAGE NOTES
// =============================================================================

/**
 * CONSTRAINT TYPES REFERENCE:
 * 
 * Basic Constraints:
 * - PrimaryKey(field) - Primary key constraint (unique, non-null)
 * - Unique(field) - Unique constraint (allows null)
 * - Index(field) - Index for fast lookups
 * - AutoInc(field) - Auto-incrementing field
 * 
 * Combination Constraints:
 * - PrimaryKeyAutoInc(field) - Primary key with auto-increment
 * - UniqueAutoInc(field) - Unique field with auto-increment  
 * - IndexAutoInc(field) - Indexed field with auto-increment
 * 
 * LIFECYCLE REDUCERS:
 * - SPACETIMEDB_INIT(name, ReducerContext ctx) - Called when module is initialized
 * - SPACETIMEDB_CLIENT_CONNECTED(name, ReducerContext ctx) - Called when client connects
 * - SPACETIMEDB_CLIENT_DISCONNECTED(name, ReducerContext ctx) - Called when client disconnects
 * 
 * LOGGING LEVELS:
 * - LOG_DEBUG(msg) - Debug information
 * - LOG_INFO(msg) - General information
 * - LOG_WARN(msg) - Warning messages
 * - LOG_ERROR(msg) - Error messages
 * - LOG_PANIC(msg) - Critical errors (may terminate)
 */

// =============================================================================
// BSATN IMPLEMENTATION INCLUDES
// =============================================================================

// Include BSATN implementation files after all headers are defined
#include "spacetimedb/bsatn/types_impl.h"
#include "spacetimedb/bsatn/schedule_at_impl.h"
#include "spacetimedb/enum_macro.h"