// -----------------------------------------------------------------------------
// file="IStaticModule"
// Project: StgSharp
// Copyright (c) Nitload.
// SPDX-License-Identifier: MIT
// -----------------------------------------------------------------------------

using System;
using System.Collections;
using System.Collections.Generic;

namespace Nitload
{
    /// <summary>
    ///   Represents a statically activated module that can be registered and initialized as part of
    ///   the application startup sequence, and gracefully torn down on shutdown.
    /// </summary>
    public interface IStaticModule
    {

        /// <summary>
        ///   Gets the display name of this module, used for logging and diagnostics.
        /// </summary>
        string ModuleName { get; }

        /// <summary>
        ///   Performs all initialization work for this module using the provided profile.
        /// </summary>
        /// <param name="profile">
        ///   The configuration profile supplied at registration time. Use <see ///  
        ///   cref="IModuleInitializeConfiguration.Empty" /> if no configuration is required.
        /// </param>
        void InitializeModule(
             IModuleInitializeConfiguration profile
        );

        /// <summary>
        ///   Releases all resources acquired during <see cref="InitializeModule" />. Implementations should
        ///   be idempotent: calling this method more than once must not throw.
        /// </summary>
        void UninitializeModule();

    }

    /// <summary>
    ///   Marker interface for module initialization configuration. Implementations are plain data
    ///   carriers; no static factory is required.
    /// </summary>
    public interface IModuleInitializeConfiguration
    {

        /// <summary>
        ///   A shared, allocation-free empty profile for modules that require no configuration.
        /// </summary>
        static readonly IModuleInitializeConfiguration Empty = EmptyModuleInitializeProfile.Instance;

        private sealed class EmptyModuleInitializeProfile : IModuleInitializeConfiguration
        {

            public static readonly EmptyModuleInitializeProfile Instance = new();

            private EmptyModuleInitializeProfile() { }

        }

    }

    /// <summary>
    ///   Pairs an <see cref="IStaticModule" /> with its <see cref="IModuleInitializeConfiguration"
    ///   />, ensuring the two are never stored or iterated independently.
    /// </summary>
    /// <remarks>
    ///   Using a <see langword="readonly struct" /> avoids the boxing overhead that would occur if
    ///   the pair were stored as two parallel lists of reference types.
    /// </remarks>
    public readonly struct ModuleDescriptor
    {

        /// <summary>
        ///   Initializes a new <see cref="ModuleDescriptor" /> using <see ///  
        ///   cref="IModuleInitializeConfiguration.Empty" /> as the profile.
        /// </summary>
        public ModuleDescriptor(
               IStaticModule module
        )
            : this(module, IModuleInitializeConfiguration.Empty) { }

        /// <summary>
        ///   Initializes a new <see cref="ModuleDescriptor" /> with an explicit profile.
        /// </summary>
        public ModuleDescriptor(
               IStaticModule module,
               IModuleInitializeConfiguration profile
        )
        {
            Module = module;
            Profile = profile;
        }

        /// <summary>
        ///   Gets the configuration profile associated with the module.
        /// </summary>
        public IModuleInitializeConfiguration Profile { get; }

        /// <summary>
        ///   Gets the module to be initialized.
        /// </summary>
        public IStaticModule Module { get; }

        /// <summary>
        ///   Calls <see cref="IStaticModule.InitializeModule" /> with the stored profile.
        /// </summary>
        public void Initialize()
        {
            Module.InitializeModule(Profile);
        }

        /// <summary>
        ///   Calls <see cref="IStaticModule.UninitializeModule" /> on the stored module.
        /// </summary>
        public void Uninitialize()
        {
            Module.UninitializeModule();
        }

    }

    /// <summary>
    ///   An ordered collection of modules to be initialized during application startup and
    ///   uninitialized on shutdown. Supports three registration strategies so that the <c>new()
    ///   ///</c> generic constraint is never a hard requirement.
    /// </summary>
    public sealed class ModuleToInitializeCollection : IEnumerable<IStaticModule>, IStaticModule
    {

        private readonly List<ModuleDescriptor> _descriptors = [];

        internal ModuleToInitializeCollection(
                 World.Initializer init,
                 World.InitializeConfiguration config
        )
        {
            _descriptors.Add(new ModuleDescriptor(init, config));
        }

        // ── IEnumerable<IStaticModule> ───────────────────────────────────────────

        /// <inheritdoc />
        public IEnumerator<IStaticModule> GetEnumerator()
        {
            foreach (ModuleDescriptor d in _descriptors) {
                yield return d.Module;
            }
        }

        // ── Initialization / Uninitialization ────────────────────────────────────

        /// <summary>
        ///   Initializes all registered modules in the order they were registered. Each module
        ///   receives the profile that was supplied at registration time.
        /// </summary>
        public void InitializeModule()
        {
            for (int i = 0; i < _descriptors.Count; i++) {
                _descriptors[i].Initialize();
            }
        }

        /// <summary>
        ///   Uninitializes all registered modules in <b> reverse </b> registration order, mirroring
        ///   the typical LIFO teardown convention (e.g., GLFW must be unloaded after all subsystems
        ///   that depend on it).
        /// </summary>
        public void UninitializeModule()
        {
            for (int i = _descriptors.Count - 1; i >= 0; i--) {
                _descriptors[i].Uninitialize();
            }
        }

        // ── Registration API ─────────────────────────────────────────────────────

        /// <summary>
        ///   Registers a module of type <typeparamref name="T" /> using its default constructor.
        ///   This is the most concise overload for simple modules that expose a public
        ///   parameterless constructor.
        /// </summary>
        /// <typeparam name="T">
        ///   A concrete module type that implements <see cref="IStaticModule" /> and exposes a
        ///   public parameterless constructor.
        /// </typeparam>
        /// <param name="profile">
        ///   Optional initialization profile. Defaults to <see ///  
        ///   cref="IModuleInitializeConfiguration.Empty" /> when <see langword="null" />.
        /// </param>
        public ModuleToInitializeCollection UseModule<T>(
                                            IModuleInitializeConfiguration? profile = null
        ) where T : IStaticModule, new()
        {
            return UseModule(static() => new T(), profile);
        }

        /// <summary>
        ///   Registers a module produced by a factory delegate. This overload imposes no generic
        ///   constraints and supports any construction strategy, including dependency injection and
        ///   parameterized constructors.
        /// </summary>
        /// <param name="factory">
        ///   A delegate that constructs and returns the module instance. The delegate is invoked
        ///   once, immediately at registration time. If <paramref name="factory" /> is <see ///  
        ///   langword="null" /> or returns <see langword="null" />, the call is silently ignored
        ///   and the collection is returned unchanged.
        /// </param>
        /// <param name="profile">
        ///   Optional initialization profile. Defaults to <see ///  
        ///   cref="IModuleInitializeConfiguration.Empty" /> when <see langword="null" />.
        /// </param>
        public ModuleToInitializeCollection UseModule(
                                            Func<IStaticModule> factory,
                                            IModuleInitializeConfiguration? profile = null
        )
        {
            if (factory is null) {
                return this;
            }
            IStaticModule? mod = factory();
            if (mod is null) {
                return this;
            }
            _descriptors.Add(new ModuleDescriptor(
                mod,
                profile ?? IModuleInitializeConfiguration.Empty));
            return this;
        }

        /// <summary>
        ///   Registers a pre-existing module instance. Use this overload when the module is
        ///   provided externally, such as from a DI container, an object pool, or a singleton.
        /// </summary>
        /// <param name="module">
        ///   The module instance to register.
        /// </param>
        /// <param name="profile">
        ///   Optional initialization profile. Defaults to <see ///  
        ///   cref="IModuleInitializeConfiguration.Empty" /> when <see langword="null" />.
        /// </param>
        public ModuleToInitializeCollection UseModule(
                                            IStaticModule module,
                                            IModuleInitializeConfiguration? profile = null
        )
        {
            _descriptors.Add(new ModuleDescriptor(
                module,
                profile ?? IModuleInitializeConfiguration.Empty));
            return this;
        }

        /// <inheritdoc />
        IEnumerator IEnumerable.GetEnumerator()
        {
            return GetEnumerator();
        }

        // ── IStaticModule explicit implementation ────────────────────────────────

        /// <summary>
        ///   Explicit <see cref="IStaticModule" /> implementation. Delegates to <see ///  
        ///   cref="InitializeModule()" />, ignoring the supplied profile because each contained module uses
        ///   its own registered profile.
        /// </summary>
        void IStaticModule.InitializeModule(
                           IModuleInitializeConfiguration profile
        )
        {
            InitializeModule();
        }

        /// <inheritdoc />
        string IStaticModule.ModuleName => "Module Initializer";

    }
}