meta 1.17.0

meta: ^1.17.0 copied to clipboard

Introduce @awaitNotRequired to annotate Future-returning functions and Future-typed fields and top-level variables whose value does not necessarily need to be awaited. This annotation can be used to suppress unawaited_futures and discarded_futures lint diagnostics at call sites.

For example, this log function returns a Future, but maybe the return value is typically not important, and is only useful in tests or while debugging:

@awaitNotRequired Future<LogMessage> log(String message) { ... }

void fn() {
  log('Message'); // Not important to wait for logging to complete.
}

Without the annotation on log, the analyzer may report a lint diagnostic at the call to log, such as unawaited_futures or discarded_futures regarding the danger of not awaiting the function call, depending on what lint rules are enabled.

Mark Required and required as @Deprecated.

Update SDK constraints to ^3.5.0.

Add TargetKinds to a few annotations to match custom-wired behavior that the Dart analyzer has been providing:

• Require that @factory is only used on methods.
• Require that @Immutable is only used on classes, extensions, and mixins.
• Require that @mustBeOverridden and @mustCallSuper are only used on overridable members.
• Require that @sealed is only used on classes.

Updated @doNotSubmit to (1) disallow same-library access (unlike other visibility annotation), (2) allow parameters marked with @doNotSubmit to be used in nested functions, and (3) disallowed @doNotSubmit on required parameters:

import 'package:meta/meta.dart';

@doNotSubmit
void a() {}

void b() {
  // HINT: invalid_use_of_do_not_submit: ...
  a();
}

import 'package:meta/meta.dart';

void test({
  @doNotSubmit bool solo = false
}) {
  void nested() {
    // OK
    if (solo) { /*...*/ }
  }
}

import 'package:meta/meta.dart';

void test({
  // HINT: Cannot use on required parameters.
  @doNotSubmit required bool solo
}) {}

See https://github.com/dart-lang/sdk/issues/55558 for more information.

TargetKind.parameter is now allowed on a representation type, such as:

// Ok, because `int _actual` is similar to a parameter declaration.
extension type const FancyInt(@mustBeConst int _actual) {}

Renamed @ResourceIdentifier to @RecordUse.

Updated @mustBeOverridden to only flag missing overrides in concrete classes; in other words, abstract classes (including implicitly abstract, i.e sealed) and mixin declarations are no longer required to provide an implementation:

import 'package:meta/meta.dart';

abstract class Base {
  @mustBeOverridden
  void foo() {}
}

class Derived extends Base {
  // ERROR: Missing implementation of `foo`.
}

abstract class Abstract extends Base {
  // No error.
}

sealed class Sealed extends Base {
  // No error.
}

mixin Mixin on Base {
  // No error.
}

See https://github.com/dart-lang/sdk/issues/52965 for more information.

Introduce TargetKind.optionalParameter, to indicate that an annotation is valid on any optional parameter declaration.

Introduce TargetKind.overridableMember, to indicate that an annotation is valid on any instance member declaration.

Introduce TargetKind.instanceMember, to indicate that an annotation is valid on any instance member declaration.

Updated @doNotSubmit to (1) disallow same-library access (unlike other visibility annotation), (2) allow parameters marked with @doNotSubmit to be used in nested functions, and (3) disallowed @doNotSubmit on required parameters:

import 'package:meta/meta.dart';

@doNotSubmit
void a() {}

void b() {
  // HINT: invalid_use_of_do_not_submit: ...
  a();
}

import 'package:meta/meta.dart';

void test({
  @doNotSubmit bool solo = false
}) {
  void nested() {
    // OK
    if (solo) { /*...*/ }
  }
}

import 'package:meta/meta.dart';

void test({
  // HINT: Cannot use on required parameters.
  @doNotSubmit required bool solo
}) {}

See https://github.com/dart-lang/sdk/issues/55558 for more information.

Introduce TargetKind.constructor, to indicate that an annotation is valid on any constructor declaration.

Introduce TargetKind.directive, to indicate that an annotation is valid on any directive.

Introduce TargetKind.enumValue, to indicate that an annotation is valid on any enum value declaration.

Introduce TargetKind.typeParameter, to indicate that an annotation is valid on any type parameter declaration.

Introduce @doNotSubmit to annotate members that should not be accessed in checked-in code, typically because they are intended to be used ephemerally during development.

One example is package:test's solo: ... parameter, which skips all other tests in a test suite when set to true. This parameter is useful during development, but should be prevented from being submitted:

import 'package:meta/meta.dart';

void test(
  String name,
  void Function() body, {
  @doNotSubmit bool solo = false
}) {
  // ...
}

import 'package:test/test.dart';

void main() {
  test(
    'my test', () {
      // ...
    },
    // HINT: invalid_use_of_do_not_submit: ...
    solo: true,
  );
}

Introduce @mustBeConst to annotate parameters which only accept constant arguments.

Introduce @sealed to declare that a class or mixin is not allowed as a super-type.

Only classes in the same package as a class or mixin annotated with @sealed may extend, implement or mix-in the annotated class or mixin. (SDK issue 27372).

Introduce @alwaysThrows to declare that a function always throws (SDK issue 17999). This is first available in Dart SDK 1.25.0-dev.1.0.

import 'package:meta/meta.dart';

// Without knowing that [failBigTime] always throws, it looks like this
// function might return without returning a bool.
bool fn(expected, actual) {
  if (expected != actual)
    failBigTime(expected, actual);
  else
    return True;
}

@alwaysThrows
void failBigTime(expected, actual) {
  throw new StateError('Expected $expected, but was $actual.');
}

Introduce @virtual to allow field overrides in strong mode (SDK issue 27384).

import 'package:meta/meta.dart' show virtual;
class Base {
  @virtual int x;
}
class Derived extends Base {
  int x;

  // Expose the hidden storage slot:
  int get superX => super.x;
  set superX(int v) { super.x = v; }
}

Introduce @checked to override a method and tighten a parameter type (SDK issue 25578).

import 'package:meta/meta.dart' show checked;
class View {
  addChild(View v) {}
}
class MyView extends View {
  // this override is legal, it will check at runtime if we actually
  // got a MyView.
  addChild(@checked MyView v) {}
}
main() {
  dynamic mv = new MyView();
  mv.addChild(new View()); // runtime error
}