import { Bundle } from 'apprt/api';

/**
 * A ConfigFragmentInterpreter interprets one of the keys of the `domain-config` json of a bundle.
 *
 * ConfigFragmentInterpreters are responsible for cleaning up the created resources, if a domain bundle is stopped.
 * Stopping a domain-bundle will result in a call to `dispose` on the result object of the interpret function
 * by the DomainSystem.
 *
 * *Interpretation order*:
 *  * The domain bundles are interpreted by the domain system, after the app start, as soon as a map becomes available.
 *  * First all bundles configured by `domains-system/Config/domainBundleOrder` are interpreted in the listed order,
 *    one after the other.
 *  * After that the life cycle hook `allInitialOrderedBundlesInterpreted` is called on each interpreter.
 *  * Then all remaining active domain bundles are interpreted. One after the other.
 *  * After that the life cycle hook `allInitialBundlesInterpreted` is called on each interpreter.
 *  * If a new domain-bundle is started then it will interpreted immediately.
 *
 * @example
 *
 * ```ts
 * export class MyInterpreter implements ConfigFragmentInterpreter {
 *     allInitialOrderedBundlesInterpreted(): void {}
 *
 *     allInitialBundlesInterpreted(): void {}
 *
 *     async interpret(
 *         configFragment: ConfigFragment,
 *         options: InterpretationOptions
 *     ): Promise<Disposable | void> {
 *         const myConfig = configFragment.getConfig("my-custom-key");
 *         if (!myConfig) {
 *             // nothing to do
 *             return Promise.resolve();
 *         }
 *         // interpret the config
 *         ...
 *         // e.g. create a resource
 *         const resource = ...;
 *         // interpretation is finished
 *         return Promise.resolve({
 *             // this is called if the interpreted domain bundle is stopped
 *             dispose() {
 *                 // ensure created resources are cleaned
 *                 resource.cleanup();
 *             }
 *         });
 *     }
 * }
 * ```
 */
interface ConfigFragmentInterpreter {
    /**
     * Called by domain system if a domain bundle should be interpreted.
     * @param bundleConfig the 'domain-config' element to interpret.
     * @param options additional information for the interpreter.
     * @returns a disposable. This is responsible to clean up resources on domain-bundle stop.
     */
    interpret(bundleConfig: ConfigFragment, options: InterpretationOptions): Promise<Disposable | void>;
    /** Called by the domain system to inform the interpreter that all ordered domain bundles are interpreted.
     *  After that the option.isInInitialOrderedBundle will never be true.
     */
    allInitialOrderedBundlesInterpreted?(): void;
    /** Called by domain system to inform the interpreter that all initial available domain bundles are interpreted.
     */
    allInitialBundlesInterpreted?(): void;
}
/**
 * Allows access to a configuration section.
 */
interface ConfigFragment {
    /**
     * Checks if configuration options are provided by this fragment.
     */
    isEmpty(): boolean;
    /**
     * Provides access to a configuration section, e.g. `map-layers`.
     * An interpreter defines what can be available there.
     * @param key configuration key
     */
    getConfig<T>(key: string): T | undefined;
}
/**
 * Additional options provided by the DomainSystem during `interpret` of a bundle.
 */
interface InterpretationOptions {
    /**
     * An abort signal. This can be used to react to a domain bundle stop, if the interpretation is not finished.
     */
    signal: AbortSignal;
    /**
     * The current bundle.
     */
    bundle: Bundle;
    /**
     * Flag if the current bundle is part of the ordered bundle list.
     */
    isInInitialOrderedBundle: boolean;
    /**
     * Provides access to global configuration options, defined at the `domain-system/Config` element.
     */
    domainSystemConfig: ConfigFragment;
}
/**
 * A disposable is a cleanup handle.
 * It will be triggered by the domain system if a domain bundle is stopped.
 */
interface Disposable {
    /**
     * Triggers cleanup of the resources associated with this disposable.
     */
    dispose(): void;
}

export type { ConfigFragment, ConfigFragmentInterpreter, Disposable, InterpretationOptions };