[breaking change] Discontinue deprecated core library APIs, part II

[mit-mit]

trafficstars

The following Dart core library APIs, which are all currently deprecated, are now being fully removed.

This is the continuation of previous discontinuation work tracked in https://github.com/dart-lang/sdk/issues/34233

NOTE: This plan is tentative and not yet fully signed off.

Phase II, scheduled for Dart 3.0

The following APIs are planned to be removed in 3.0, as some breakage is to be expected.

dart:core

• [ ] proxy constant: https://dart-review.googlesource.com/c/sdk/+/258004
• [ ] Provisional class and associated constant: https://dart-review.googlesource.com/c/sdk/+/258004
• [ ] onError argument to int.parse: https://dart-review.googlesource.com/c/sdk/+/259042
• [ ] IntegerDivisionByZeroException exception (use UnsupportedError ): https://github.com/dart-lang/sdk/issues/30743
• [ ] List constructor (use List.Filled): https://dart-review.googlesource.com/c/sdk/+/258920
• [ ] Errors:
  • [ ] CastError class (use TypeError): https://dart-review.googlesource.com/c/sdk/+/259041
  • [ ] AbstractClassInstantiationError class (no longer relevant): https://dart-review.googlesource.com/c/sdk/+/259041
  • [ ] FallThroughError class (Unused since Dart 2.0): https://dart-review.googlesource.com/c/sdk/+/259041
  • [ ] NoSuchMethodError exception (use NoSuchMethod.withInvocation): TODO

dart:async

• [ ] DeferredLibrary class
• [ ] runZoned's onError: CL: https://dart-review.googlesource.com/c/sdk/+/248002

dart:developer

• [ ] MAX_USER_TAGS in UserTag

dart:mirrors

None?

dart:html

• [ ] discontinue document.registerElement & registerElement2 in Dart 2.19

[mit-mit]

@sigmundch is the NoSuchMethodError constructor ready to be removed? There is a comment about dart2js here: https://github.com/dart-lang/sdk/blob/main/sdk/lib/core/errors.dart#L492

[sigmundch]

Our dependency is still there, but probably can easily be refactored by updating the dart2js patch files without changing the compiler directly /cc @rakudrama

[srawlins]

If we want to ship dart migrate in Dart 3.0, is it ok if that tool does not understand these removed APIs?

For example, if someone installs Dart 3.0, and uses that Dart's dart migrate to try to migrate code which refers to CastError, is it ok if dart migrate fails in some way? Crashes or something like that on the unresolved element.

FWIW, dart migrate is implemented in pkg/dartdev, which has a simple import of pkg/nnbd_migration. It does not currently shell out to a separate snapshot.

[sigmundch]

@mit-mit https://github.com/dart-lang/sdk/commit/efb509c114dcaf54d0a011f717b48893d71ec9c3 should address the dependency from dart2js, I think the constructor is now ready to be removed.

[mit-mit]

If we want to ship dart migrate in Dart 3.0, is it ok if that tool does not understand these removed APIs?

@srawlins I think that is OK. If a developer wants support for migrating away from discontinued APIs, they can use the 2.19 SDK.

[mit-mit]

@sigmundch @kevmoo is the comment above about the dart:html change accurate (i.e. we're removing that in 2.19)?

[sigmundch]

@mit-mit, can you clarify which comment are you referring to?

We landed changes to mark the APIs deprecated in late July. Those haven't been released yet in the stable channel, so it will first get broad visibility with the 2.19 stable release. Given that, we wont be removing it entirely in 2.19, but the release that follows.

[mit-mit]

@sigmundch I was looking at an older, stale version, sorry.

Given that, we wont be removing it entirely in 2.19, but the release that follows.

sgtm, we'll track that as a 3.0 removal then

[dcharkes]

AbstractClassInstantiationError class (no longer relevant)

The class may be irrelevant when running normal Dart code, but not when using mirrors:

https://github.com/dart-lang/sdk/blob/636232628bfb9f8aa1d8b16656d647c8c3cc2205/tests/lib/mirrors/instantiate_abstract_class_test.dart#L40-L44

Should classMirror.newInstance(decl.constructorName, args) start throwing a different type of exception, or should we move AbstractClassInstantiationError to dart:mirrors as per https://dart-review.googlesource.com/c/sdk/+/259041/16/sdk/lib/mirrors/mirrors.dart ? @mit-mit

[mit-mit]

The class may be irrelevant when running normal Dart code, but not when using mirrors:

The text was unclear. It's no longer relevant in the dart:core libraries. But, yes mirrors can still throw it, and now have their own definition of it: https://dart-review.googlesource.com/c/sdk/+/259041/16/sdk/lib/mirrors/mirrors.dart

[nshahan]

@mit-mit Are you expecting there will be tracking issues for the removal of CyclicInitializationError and NullThrownError. Is there already discussion happening somewhere?

[mit-mit]

Those are expected to be removed next few days; CLs will be linked from the top comment.

[mit-mit]

All done, closing

[dupuchba]

hey @mit-mit you forgot MapEntry in your list which cannot be extends anymore (it breaks ClojureDart btw).

[lrhn]

Making MapEntry a final class will, like all other now-final classes in the platform libraries, only affect code when it migrates to Dart 3.0.

It's not, technically, considered breaking, even though it prevents some uses from being continued. The existing code, running at language version 2.19, will keep working until support for pre-3.0 code is removed, which is unlikely to be soon.

The list of classes which have become final are (lifted directly from the source code):

dart:async

• final class AsyncError
• final class DeferredLoadException
• abstract final class ZoneSpecification
• abstract final class ZoneDelegate
• abstract final class Zone

dart:collection

• abstract final class HashMap
• abstract final class HashSet
• final class HasNextIterator
• abstract final class LinkedHashMap
• abstract final class LinkedHashSet
• final class DoubleLinkedQueue
• final class ListQueue
• final class SplayTreeMap
• final class SplayTreeSet

dart:convert

• final class AsciiCodec
• final class Base64Codec
• final class Base64Encoder
• final class Base64Decoder
• final class HtmlEscapeMode
• final class HtmlEscape
• final class JsonCodec
• final class JsonEncoder
• final class JsonUtf8Encoder
• final class JsonDecoder
• final class Latin1Codec
• final class Latin1Encoder
• final class Latin1Decoder
• final class LineSplitter
• final class Utf8Codec
• final class Utf8Encoder
• final class Utf8Decoder

dart:core

• abstract final class BigInt
• final class OutOfMemoryError
• final class StackOverflowError
• abstract final class Function
• final class MapEntry
• final class Null
• abstract final class Record
• abstract final class String
• final class Expando
• abstract final class WeakReference
• abstract final class Finalizer

dart:developer

• abstract final class NativeRuntime
• final class ServiceExtensionResponse
• abstract final class UserTag
• final class ServiceProtocolInfo
• final class Service
• final class Flow
• abstract final class Timeline
• final class TimelineTask

dart:ffi

• final class AbiSpecificIntegerMapping
• final class DartRepresentationOf
• final class Unsized
• final class Char
• final class SignedChar
• final class UnsignedChar
• final class Short
• final class UnsignedShort
• final class Int
• final class UnsignedInt
• final class Long
• final class UnsignedLong
• final class LongLong
• final class UnsignedLongLong
• final class IntPtr
• final class UintPtr
• final class Size
• final class WChar
• final class DynamicLibrary
• final class Pointer
• final class Array
• final class Dart_CObject
• abstract final class NativeApi
• final class FfiNative
• final class Native
• final class DefaultAsset
• abstract final class NativeFinalizer
• abstract final class NativeType
• final class Int8
• final class Int16
• final class Int32
• final class Int64
• final class Uint8
• final class Uint16
• final class Uint32
• final class Uint64
• final class Float
• final class Double
• final class Bool
• abstract final class Void
• abstract final class Handle
• abstract final class NativeFunction
• abstract final class VarArgs
• final class Packed

dart:io and dart:html

• abstract final class HttpClientBasicCredentials
• abstract final class HttpClientDigestCredentials
• final class HttpProfiler

dart:io

• abstract final class ZLibOption
• final class ZLibCodec
• final class GZipCodec
• final class ZLibEncoder
• final class ZLibDecoder
• final class FileSystemEntityType
• final class FileSystemEvent
• final class FileSystemCreateEvent
• final class FileSystemModifyEvent
• final class FileSystemDeleteEvent
• final class FileSystemMoveEvent
• abstract final class Platform
• abstract final class ProcessInfo
• final class ProcessStartMode
• final class ProcessResult
• final class InternetAddressType
• final class SocketDirection
• final class SocketOption
• final class RawSocketOption
• final class ConnectionTask
• final class Datagram
• final class SocketMessage
• final class StdioType
• final class SystemEncoding

dart:isolate

• final class Isolate
• final class RemoteError
• abstract final class TransferableTypedData

dart:typed_data

• abstract final class ByteBuffer
• abstract final class TypedData
• final class Endian
• abstract final class ByteData
• abstract final class Int8List
• abstract final class Uint8List
• abstract final class Uint8ClampedList
• abstract final class Int16List
• abstract final class Uint16List
• abstract final class Int32List
• abstract final class Uint32List
• abstract final class Int64List
• abstract final class Uint64List
• abstract final class Float32List
• abstract final class Float64List
• abstract final class Float32x4List
• abstract final class Int32x4List
• abstract final class Float64x2List
• abstract final class Float32x4
• abstract final class Int32x4
• abstract final class Float64x2
• abstract final class UnmodifiableByteBufferView
• abstract final class UnmodifiableByteDataView
• abstract final class UnmodifiableUint8ListView
• abstract final class UnmodifiableInt8ListView
• abstract final class UnmodifiableUint8ClampedListView
• abstract final class UnmodifiableUint16ListView
• abstract final class UnmodifiableInt16ListView
• abstract final class UnmodifiableUint32ListView
• abstract final class UnmodifiableInt32ListView
• abstract final class UnmodifiableUint64ListView
• abstract final class UnmodifiableInt64ListView
• abstract final class UnmodifiableInt32x4ListView
• abstract final class UnmodifiableFloat32x4ListView
• abstract final class UnmodifiableFloat64x2ListView
• abstract final class UnmodifiableFloat32ListView
• abstract final class UnmodifiableFloat64ListView

It's possible, dart:mirrors might also be made entirely final, if time permits.

[dupuchba]

@lrhn I appreciate your perspective, but I must disagree with the assertion that It's not, technically, considered breaking.... Allow me to share my viewpoint:

As a library creator, supporting all major Dart version updates is crucial to prevent the library from becoming obsolete. What occurred to libraries that failed to transition from Dart 1 to 2.X?

The final class example is an excellent illustration. Introducing final class in Dart standard libraries disrupts all code dependent on those classes when transitioning to Dart 3, generating unplanned work for library authors. When I examine the decision to make MapEntry a final class, it appears to be final for the sake of precaution rather than necessity.

Please don't misunderstand me; I adore Dart and the team behind it, and I will always be thankful for the impact it had on my life when I chose it for ClojureDart.

I would simply prefer minimal Breaking Changes.

Thanks for all your work 🙇