Framework Configuration

/**
 * Manages configuring the aurelia framework instance
 */
class FrameworkConfiguration {
  /** The root DI container used by the application */
  container: Container;
  /** The aurelia instance */
  aurelia: Aurelia;

  /**
   * Creates an instance of FrameworkConfiguration
   * @param aurelia - An instance of Aurelia
   */
  constructor(aurelia: Aurelia);

  /**
   * Adds an existing object to the framework's dependency injection container
   * @param type - The object type of the dependency that the framework will inject
   * @param instance - The existing instance of the dependency that the framework will inject
   * @returns The current FrameworkConfiguration instance
   */
  instance(type: any, instance: any): FrameworkConfiguration;

  /**
   * Adds a singleton to the framework's dependency injection container
   * @param type - The object type of the dependency that the framework will inject
   * @param implementation - The constructor function of the dependency that the framework will inject
   * @returns The current FrameworkConfiguration instance
   */
  singleton(type: any, implementation?: Function): FrameworkConfiguration;

  /**
   * Adds a transient to the framework's dependency injection container
   * @param type - The object type of the dependency that the framework will inject
   * @param implementation - The constructor function of the dependency that the framework will inject
   * @returns The current FrameworkConfiguration instance
   */
  transient(type: any, implementation?: Function): FrameworkConfiguration;

  /**
   * Adds an async function that runs before the plugins are run
   * @param task - The function to run before start
   * @returns The current FrameworkConfiguration instance
   */
  preTask(task: Function): FrameworkConfiguration;

  /**
   * Adds an async function that runs after the plugins are run
   * @param task - The function to run after start
   * @returns The current FrameworkConfiguration instance
   */
  postTask(task: Function): FrameworkConfiguration;

  /**
   * Configures an internal feature plugin before Aurelia starts
   * @param plugin - The folder for the internal plugin to configure (expects an index.js in that folder)
   * @param config - The configuration for the specified plugin
   * @returns The current FrameworkConfiguration instance
   */
  feature(plugin: string | ((config: FrameworkConfiguration, pluginConfig?: any) => any), config?: any): FrameworkConfiguration;

  /**
   * Adds globally available view resources to be imported into the Aurelia framework
   * @param resources - The relative module id to the resource (Relative to the plugin's installer)
   * @returns The current FrameworkConfiguration instance
   */
  globalResources(resources: string | Function | Array<string | Function>): FrameworkConfiguration;

  /**
   * Renames a global resource that was imported
   * @param resourcePath - The path to the resource
   * @param newName - The new name
   * @returns The current FrameworkConfiguration instance
   */
  globalName(resourcePath: string, newName: string): FrameworkConfiguration;

  /**
   * Configures an external, 3rd party plugin before Aurelia starts
   * @param plugin - The ID of the 3rd party plugin to configure
   * @param pluginConfig - The configuration for the specified plugin
   * @returns The current FrameworkConfiguration instance
   */
  plugin(plugin: string | ((frameworkConfig: FrameworkConfiguration) => any) | FrameworkPluginInfo, pluginConfig?: any): FrameworkConfiguration;

  /**
   * Loads and configures the plugins registered with this instance
   * @returns Promise which resolves when all plugins are loaded and configured
   */
  apply(): Promise<void>;
}

import { Aurelia } from "aurelia-framework";

const aurelia = new Aurelia();

// Basic configuration chaining
aurelia.use
  .standardConfiguration()
  .developmentLogging()
  .plugin('aurelia-dialog')
  .globalResources([
    './resources/custom-element',
    './resources/value-converter'
  ]);

// Custom service registration
aurelia.use
  .singleton(ApiService, HttpApiService)
  .instance(AppConfig, { apiUrl: 'https://api.example.com' });

/**
 * Adds an existing object to the framework's dependency injection container
 * @param type - The object type/token for dependency injection
 * @param instance - The existing instance to inject
 * @returns The current FrameworkConfiguration instance
 */
instance(type: any, instance: any): FrameworkConfiguration;

/**
 * Adds a singleton to the framework's dependency injection container
 * @param type - The object type/token for dependency injection
 * @param implementation - The constructor function (optional, defaults to type)
 * @returns The current FrameworkConfiguration instance
 */
singleton(type: any, implementation?: Function): FrameworkConfiguration;

/**
 * Adds a transient to the framework's dependency injection container
 * @param type - The object type/token for dependency injection
 * @param implementation - The constructor function (optional, defaults to type)
 * @returns The current FrameworkConfiguration instance
 */
transient(type: any, implementation?: Function): FrameworkConfiguration;

// Register existing instances
const config = { apiUrl: 'https://api.example.com', timeout: 5000 };
aurelia.use.instance('AppConfiguration', config);
aurelia.use.instance(AppConfig, config);

// Register singletons (one instance shared across app)
aurelia.use.singleton(DataService);
aurelia.use.singleton(ApiService, HttpApiService);

// Register transients (new instance each time)
aurelia.use.transient(Logger, ConsoleLogger);

/**
 * Adds an async function that runs before the plugins are run
 * @param task - The function to run before start
 * @returns The current FrameworkConfiguration instance
 */
preTask(task: Function): FrameworkConfiguration;

/**
 * Adds an async function that runs after the plugins are run
 * @param task - The function to run after start
 * @returns The current FrameworkConfiguration instance
 */
postTask(task: Function): FrameworkConfiguration;

// Pre-task: setup before plugins load
aurelia.use.preTask(async () => {
  console.log('Initializing application...');
  await loadConfiguration();
});

// Post-task: cleanup after plugins load
aurelia.use.postTask(async () => {
  console.log('All plugins loaded');
  initializeAnalytics();
});

/**
 * Configures an internal feature plugin before Aurelia starts
 * @param plugin - The folder for the internal plugin or configuration function
 * @param config - The configuration for the specified plugin
 * @returns The current FrameworkConfiguration instance
 */
feature(plugin: string | ((config: FrameworkConfiguration, pluginConfig?: any) => any), config?: any): FrameworkConfiguration;

/**
 * Configures an external, 3rd party plugin before Aurelia starts
 * @param plugin - The plugin ID, configuration function, or FrameworkPluginInfo
 * @param pluginConfig - The configuration for the specified plugin
 * @returns The current FrameworkConfiguration instance
 */
plugin(plugin: string | ((frameworkConfig: FrameworkConfiguration) => any) | FrameworkPluginInfo, pluginConfig?: any): FrameworkConfiguration;

// Internal features
aurelia.use.feature('resources/index');
aurelia.use.feature('validation', { enableEmailValidation: true });

// External plugins
aurelia.use.plugin('aurelia-dialog');
aurelia.use.plugin('aurelia-http-client', { baseUrl: 'https://api.example.com' });

// Function-based plugin configuration
aurelia.use.plugin((config) => {
  config.globalResources('./my-element');
});

/**
 * Adds globally available view resources to be imported into the Aurelia framework
 * @param resources - Module ID(s) or constructor function(s) for resources
 * @returns The current FrameworkConfiguration instance
 */
globalResources(resources: string | Function | Array<string | Function>): FrameworkConfiguration;

/**
 * Renames a global resource that was imported
 * @param resourcePath - The path to the resource
 * @param newName - The new name for the resource
 * @returns The current FrameworkConfiguration instance
 */
globalName(resourcePath: string, newName: string): FrameworkConfiguration;

// String resources
aurelia.use.globalResources([
  './elements/custom-button',
  './attributes/tooltip',
  './value-converters/date-format'
]);

// Mixed string and function resources
import { CustomElement } from './custom-element';
aurelia.use.globalResources([
  './some-element',
  CustomElement
]);

// Rename imported resource
aurelia.use
  .globalResources('./elements/my-button')
  .globalName('./elements/my-button', 'super-button');

/**
 * Plugs in the default binding language from aurelia-templating-binding
 * @returns The current FrameworkConfiguration instance
 */
defaultBindingLanguage(): FrameworkConfiguration;

/**
 * Plugs in the router from aurelia-templating-router
 * @returns The current FrameworkConfiguration instance
 */
router(): FrameworkConfiguration;

/**
 * Plugs in the default history implementation from aurelia-history-browser
 * @returns The current FrameworkConfiguration instance
 */
history(): FrameworkConfiguration;

/**
 * Plugs in the default templating resources from aurelia-templating-resources
 * @returns The current FrameworkConfiguration instance
 */
defaultResources(): FrameworkConfiguration;

/**
 * Plugs in the event aggregator from aurelia-event-aggregator
 * @returns The current FrameworkConfiguration instance
 */
eventAggregator(): FrameworkConfiguration;

/**
 * Sets up a basic Aurelia configuration: defaultBindingLanguage + defaultResources + eventAggregator
 * @returns The current FrameworkConfiguration instance
 */
basicConfiguration(): FrameworkConfiguration;

/**
 * Sets up the standard Aurelia configuration: basicConfiguration + history + router
 * @returns The current FrameworkConfiguration instance
 */
standardConfiguration(): FrameworkConfiguration;

/**
 * Plugs in the ConsoleAppender and sets the log level to debug
 * @param level - The log level (none/error/warn/info/debug), defaults to 'debug'
 * @returns The current FrameworkConfiguration instance
 */
developmentLogging(level?: string): FrameworkConfiguration;

// Standard web application setup
aurelia.use.standardConfiguration();

// Equivalent to:
aurelia.use
  .defaultBindingLanguage()
  .defaultResources()
  .eventAggregator()
  .history()
  .router();

// Basic setup without routing
aurelia.use.basicConfiguration();

// Development logging
aurelia.use.developmentLogging('info');

/**
 * Loads and configures the plugins registered with this instance
 * @returns Promise which resolves when all plugins are loaded and configured
 * @throws Error if configuration instance has already been applied
 */
apply(): Promise<void>;

// Manual application of configuration (normally done by aurelia.start())
await aurelia.use
  .standardConfiguration()
  .plugin('aurelia-dialog')
  .apply();

interface FrameworkPluginInfo {
  /** Module ID of the plugin */
  moduleId?: string;
  /** Resources relative path information */
  resourcesRelativeTo?: string[];
  /** Plugin configuration function */
  configure?: (config: FrameworkConfiguration, pluginConfig?: any) => any;
  /** Plugin configuration object */
  config?: any;
}

try {
  await aurelia.use
    .standardConfiguration()
    .plugin('invalid-plugin')
    .apply();
} catch (error) {
  console.error('Configuration failed:', error.message);
}