/// Generates an [AppContext] value.
typedef dynamic Generator();

/// The current [AppContext], as determined by the [Zone] hierarchy.
///
/// This will be the first context found as we scan up the zone hierarchy, or
/// the "root" context if a context cannot be found in the hierarchy. The root
/// context will not have any values associated with it.
AppContext get context;

/// A lookup table (mapping types to values) and an implied scope, in which
/// code is run.
///
/// [AppContext] is used to define a singleton injection context for code that
/// is run within it. Each time you call [run], a child context (and a new
/// scope) is created.
///
/// Child contexts are created and run using zones. To read more about how
/// zones work, see https://www.dartlang.org/articles/libraries/zones.
class AppContext {
  /// Gets the value associated with the specified [type], or `null` if no
  /// such value has been associated.
  dynamic operator[](Type type);

  /// Runs [method] in a child context and returns the value.
  ///
  /// If [overrides] is specified, the child context will include the associated
  /// type mappings, overriding any conflicting mappings in this (the parent)
  /// context.
  ///
  /// If [fallbacks] is specified, the child context will include the associated
  /// type mappings only for those types not already contained in this (the
  /// parent) context.
  ///
  /// If [name] is specified, the child context will be assigned the given name.
  /// This is useful for debugging purposes and is analogous to naming a thread
  /// in Java.
  ///
  /// If [onError] is specified, the zone is considered an error zone. All
  /// uncaught errors (synchronous or asynchronous) in the zone are caught and
  /// handled by the callback.
  FutureOr<dynamic> run({
    @required FutureOr<dynamic> method(),
    Map<Type, dynamic> overrides,
    Map<Type, Generator> fallbacks,
    String name,
    ZoneBinaryCallback<dynamic, dynamic, StackTrace> onError,
  });
}