From 620410fb08797d10351cb449521b249be14cb390 Mon Sep 17 00:00:00 2001 From: Anthony Sansone Date: Thu, 8 Feb 2024 23:48:36 -0600 Subject: [PATCH] Add HTTP libraries (#5511) Adds links to platform-specific HTTP packages. Fixes #4175 --- src/_data/site.yml | 2 + .../guides/libraries/useful-libraries.md | 102 ++++++++++++------ src/content/tutorials/server/fetch-data.md | 14 +++ src/content/tutorials/server/httpserver.md | 35 +++--- 4 files changed, 105 insertions(+), 48 deletions(-) diff --git a/src/_data/site.yml b/src/_data/site.yml index 2fde4a6a06..14fde924e6 100644 --- a/src/_data/site.yml +++ b/src/_data/site.yml @@ -26,6 +26,8 @@ gh-dart: sdk: https://github.com/dart-lang/sdk lang: https://github.com/dart-lang/language site: https://github.com/dart-lang/site-www +android-dev: https://developer.android.com +apple-dev: https://developer.apple.com show_banner: true diff --git a/src/content/guides/libraries/useful-libraries.md b/src/content/guides/libraries/useful-libraries.md index 48787d2989..edd922c422 100644 --- a/src/content/guides/libraries/useful-libraries.md +++ b/src/content/guides/libraries/useful-libraries.md @@ -3,10 +3,13 @@ title: Commonly used packages description: Some of the most useful and popular packages, and where you can learn more. --- +{% assign pub = site.pub %} +{% assign pubpkg = site.pub-pkg %} + This page lists some of the most popular and useful [packages](/guides/packages) that Dart developers have published. To find more packages—and search [core libraries](/libraries) -as well—use the [pub.dev site.]({{site.pub}}) +as well—use the [pub.dev site.]({{pub}}) Commonly used packages fall into three groups: @@ -16,59 +19,94 @@ Commonly used packages fall into three groups: ## General-purpose packages -The following packages are useful for a wide range of projects. - -| **Package** | **Description** | **Commonly used APIs** | -|-------------|-----------------|------------------------| -| [archive]({{site.pub-pkg}}/archive) | Encodes and decodes various archive and compression formats. | Archive, ArchiveFile, TarEncoder, TarDecoder, ZipEncoder, ZipDecoder | -| [characters]({{site.pub-pkg}}/characters) | String manipulation for user-perceived characters (Unicode grapheme clusters). | String.characters, Characters, CharacterRange | -| [http]({{site.pub-pkg}}/http) | A set of high-level functions and classes that make it easy to consume HTTP resources. | delete(), get(), post(), read() | -| [intl]({{site.pub-pkg}}/intl) | Internationalization and localization facilities, with support for plurals and genders, date and number formatting and parsing, and bidirectional text. | Bidi, DateFormat, MicroMoney, TextDirection | -| [json_serializable]({{site.pub-pkg}}/json_serializable) | An easy-to-use code generation package. For more information, see [JSON Support](/guides/json). | @JsonSerializable | -| [logging]({{site.pub-pkg}}/logging) | A configurable mechanism for adding message logging to your application. | LoggerHandler, Level, LogRecord | -| [mockito]({{site.pub-pkg}}/mockito) | A popular framework for mocking objects in tests. Especially useful if you are writing tests for dependency injection. Used with the [test]({{site.pub-pkg}}/test) package. | Answering, Expectation, Verification | -| [path]({{site.pub-pkg}}/path) | Common operations for manipulating different types of paths. For more information, see [Unboxing Packages: path.]({{site.news}}/2016/06/unboxing-packages-path.html) | absolute(), basename(), extension(), join(), normalize(), relative(), split() | -| [quiver]({{site.pub-pkg}}/quiver) | Utilities that make using core Dart libraries more convenient. Some of the libraries where Quiver provides additional support include async, cache, collection, core, iterables, patterns, and testing. | CountdownTimer (quiver.async); MapCache (quiver.cache); MultiMap, TreeSet (quiver.collection); EnumerateIterable (quiver.iterables); center(), compareIgnoreCase(), isWhiteSpace() (quiver.strings) | -| [shelf]({{site.pub-pkg}}/shelf) | Web server middleware for Dart. Shelf makes it easy to create and compose web servers, and parts of web servers. | Cascade, Pipeline, Request, Response, Server | -| [stack_trace]({{site.pub-pkg}}/stack_trace) | Methods for parsing, inspecting, and manipulating stack traces produced by the underlying Dart implementation. Also provides functions to produce string representations of stack traces in a more readable format than the native StackTrace implementation. For more information, see [Unboxing Packages: stack_trace.]({{site.news}}/2016/01/unboxing-packages-stacktrace.html) | Trace.current(), Trace.format(), Trace.from() | -| [test]({{site.pub-pkg}}/test) | A standard way of writing and running tests in Dart. | expect(), group(), test() | -| [yaml]({{site.pub-pkg}}/yaml) | A parser for YAML. | loadYaml(), loadYamlStream() | +Use these packages for a wide range of projects. + +| Package | Description | Commonly used APIs | +|----|----|----| +| [archive][] | Encodes and decodes various archive and compression formats. | Archive, ArchiveFile, TarEncoder, TarDecoder, ZipEncoder, ZipDecoder | +| [characters][] | Manipulates strings for user-perceived characters (Unicode grapheme clusters). | String.characters, Characters, CharacterRange | +| [cronet_http][] | Provides access to the Android [Cronet][cronet] HTTP client using the same interface as `package:http`. | | +| [cupertino_http][] | Provides access to Apple's [Foundation URL Loading System][furl] using the same interface as `package:http`. | | +| [http][] | Provides set of high-level functions and classes to simplify consuming HTTP resources. | delete(), get(), post(), read() | +| [intl][] | Internationalization and localization facilities, with support for plurals and genders, date and number formatting and parsing, and bidirectional text. | Bidi, DateFormat, MicroMoney, TextDirection | +| [json_serializable][] | Generates JSON manipulation code. To learn more, consult [JSON Support](/guides/json). | @JsonSerializable | +| [logging][] | Adds message logging to your application. | LoggerHandler, Level, LogRecord | +| [mockito][] | Mocks objects in tests. Helps when you write tests for dependency injection. Use with the [test][] package. | Answering, Expectation, Verification | +| [path][] | Manipulates different types of paths. To learn more, consult [Unboxing Packages: path.]({{site.news}}/2016/06/unboxing-packages-path.html) | absolute(), basename(), extension(), join(), normalize(), relative(), split() | +| [quiver][] | Simplifies using core Dart libraries. Some of the libraries where Quiver provides additional support include async, cache, collection, core, iterables, patterns, and testing. | CountdownTimer (quiver.async); MapCache (quiver.cache); MultiMap, TreeSet (quiver.collection); EnumerateIterable (quiver.iterables); center(), compareIgnoreCase(), isWhiteSpace() (quiver.strings) | +| [shelf][] | Provides web server middleware for Dart. Shelf makes it easy to create and compose web servers, and parts of web servers. | Cascade, Pipeline, Request, Response, Server | +| [stack_trace][] | Parses, inspects, and manipulates stack traces that Dart produces. Also transforms stack traces into a more readable format than the native StackTrace implementation. To learn more, consult [Unboxing Packages: stack_trace.]({{site.news}}/2016/01/unboxing-packages-stacktrace.html) | Trace.current(), Trace.format(), Trace.from() | +| [test][] | Standardizes writing and running tests in Dart. | expect(), group(), test() | +| [yaml][] | Parses YAML markup. | loadYaml(), loadYamlStream() | {:.table .table-striped .nowrap} +[archive]: {{pubpkg}}/archive +[characters]: {{pubpkg}}/characters +[cronet_http]: {{pubpkg}}/cronet_http +[cupertino_http]: {{pubpkg}}/cupertino_http +[http]: {{pubpkg}}/http +[intl]: {{pubpkg}}/intl +[json_serializable]: {{pubpkg}}/json_serializable +[logging]: {{pubpkg}}/logging +[mockito]: {{pubpkg}}/mockito +[path]: {{pubpkg}}/path +[quiver]: {{pubpkg}}/quiver +[shelf]: {{pubpkg}}/shelf +[stack_trace]: {{pubpkg}}/stack_trace +[test]: {{pubpkg}}/test +[yaml]: {{pubpkg}}/yaml +[Cronet]: {{site.android-dev}}guide/topics/connectivity/cronet/reference/org/chromium/net/package-summary +[furl]: {{site.apple-dev}}/documentation/foundation/url_loading_system ## Packages that expand on Dart core libraries {:#packages-that-correspond-to-sdk-libraries} Each of the following packages builds upon a [core library](/libraries), adding functionality and filling in missing features: -| **Package** | **Description** | **Commonly used APIs** | -|-------------|-----------------|------------------------| -| [async]({{site.pub-pkg}}/async) | Expands on dart:async, adding utility classes to work with asynchronous computations. For more information, see [Unboxing Packages: async part 1]({{site.news}}/2016/03/unboxing-packages-async-part-1.html), [part 2]({{site.news}}/2016/03/unboxing-packages-async-part-2.html), and [part 3.]({{site.news}}/2016/04/unboxing-packages-async-part-3.html) | AsyncMemoizer, CancelableOperation, FutureGroup, LazyStream, Result, StreamCompleter, StreamGroup, StreamSplitter | -| [collection]({{site.pub-pkg}}/collection) | Expands on dart:collection, adding utility functions and classes to make working with collections easier. For more information, see [Unboxing Packages: collection.]({{site.news}}/2016/01/unboxing-packages-collection.html) | Equality, CanonicalizedMap, MapKeySet, MapValueSet, PriorityQueue, QueueList | -|[convert]({{site.pub-pkg}}/convert) | Expands on dart:convert, adding encoders and decoders for converting between different data representations. One of the data representations is _percent encoding_, also known as _URL encoding_. | HexDecoder, PercentDecoder | -|[io]({{site.pub-pkg}}/io) | Contains two libraries, ansi and io, to simplify working with files, standard streams, and processes. Use the ansi library to customize terminal output. The io library has APIs for dealing with processes, stdin, and file duplication. | copyPath(), isExecutable(), ExitCode, ProcessManager, sharedStdIn | +| Package | Description | Commonly used APIs | +|----|----|----| +| [async][] | Expands on dart:async, adding utility classes to work with asynchronous computations. To learn more, consult [Unboxing Packages: async part 1][async-1], [part 2][async-2], and [part 3][async-3]. | AsyncMemoizer, CancelableOperation, FutureGroup, LazyStream, Result, StreamCompleter, StreamGroup, StreamSplitter | +| [collection][] | Expands on dart:collection, adding utility functions and classes to make working with collections easier. To learn more, consult [Unboxing Packages: collection][collect]. | Equality, CanonicalizedMap, MapKeySet, MapValueSet, PriorityQueue, QueueList | +| [convert][] | Expands on dart:convert, adding encoders and decoders for converting between different data representations. One of the data representations is _percent encoding_, also known as _URL encoding_. | HexDecoder, PercentDecoder | +| [io][] | Contains two libraries, ansi and io, to simplify working with files, standard streams, and processes. Use the ansi library to customize terminal output. The io library has APIs for dealing with processes, stdin, and file duplication. | copyPath(), isExecutable(), ExitCode, ProcessManager, sharedStdIn | {:.table .table-striped .nowrap} +[async]: {{pubpkg}}/async +[collection]: {{pubpkg}}/collection +[convert]: {{pubpkg}}/convert +[io]: {{pubpkg}}/io +[async-1]: {{site.news}}/2016/03/unboxing-packages-async-part-1.html +[async-2]: {{site.news}}/2016/03/unboxing-packages-async-part-2.html +[async-3]: {{site.news}}/2016/04/unboxing-packages-async-part-3.html +[collect]: {{site.news}}/2016/01/unboxing-packages-collection.html ## Specialized packages -Here are some tips for finding packages that are more specialized, -such as packages for mobile (Flutter) and web development. +To find specialized packages such as packages for Flutter and web development, +consult the following sections. ### Flutter packages -See [Using packages]({{site.flutter-docs}}/development/packages-and-plugins/using-packages) -on the Flutter site. -Or use the pub.dev site to [search for Flutter packages.]({{site.pub}}/flutter) +To learn more about Flutter packages, +consult [Using packages][flutterpkg] in the Flutter documentation +or search the pub.dev site for [Flutter packages][fluttersearch]. + +[flutterpkg]: {{site.flutter-docs}}/development/packages-and-plugins/using-packages +[fluttersearch]: {{pub}}/flutter ### Web packages -See [Web libraries and packages](/web/libraries). -Or use the pub.dev site to [search for web packages.]({{site.pub}}/web) +To learn more about web packages, +consult [Web libraries and packages][webpkg] +or search the pub.dev site for [web packages][pkgsearch]. + +[webpkg]: /web/libraries +[pkgsearch]: {{pub}}/web ### Command-line and server packages +To learn more about CLI or server packages, See [Command-line and server libraries and packages](/server/libraries). -Or use the pub.dev site to [search for other packages.]({{site.pub}}) +Or use the pub.dev site to [search for other packages.]({{pub}}) diff --git a/src/content/tutorials/server/fetch-data.md b/src/content/tutorials/server/fetch-data.md index 161bce3091..7b3bc9b3f1 100644 --- a/src/content/tutorials/server/fetch-data.md +++ b/src/content/tutorials/server/fetch-data.md @@ -69,6 +69,20 @@ For more information about the JSON format, see [Introducing JSON][]. To learn more about working with JSON in Dart, see the [Using JSON][] guide. +:::secondary +Two other packages exist with platform-specific implementations for mobile. + +* [cronet_http]({{site.pub-pkg}}/cronet_http) + provides access to the Android [Cronet][] HTTP client. +* [cupertino_http]({{site.pub-pkg}}/cupertino_http) + provides access to Apple's [Foundation URL Loading System][furl]. + +To learn more about their capabilities, +consult the package documentation. +::: + +[Cronet]: {{site.android-dev}}guide/topics/connectivity/cronet/reference/org/chromium/net/package-summary +[furl]: {{site.apple-dev}}/documentation/foundation/url_loading_system [Introducing JSON]: https://www.json.org/ ### HTTP requests diff --git a/src/content/tutorials/server/httpserver.md b/src/content/tutorials/server/httpserver.md index de7cdfaeca..a6f5ffd9df 100644 --- a/src/content/tutorials/server/httpserver.md +++ b/src/content/tutorials/server/httpserver.md @@ -7,23 +7,26 @@ prevpage: title: Fetch data from the internet --- -Here are some resources for writing servers using Dart: +Dart resources for writing HTTP servers include: -* Documentation - * [Using Google Cloud][] has information on Google Cloud products - that Dart servers can use, such as Cloud Run. - * [Using Google APIs][] points to resources to help you - use Firebase and Google client APIs from a Dart app. -* Samples - * [A simple Dart HTTP server][simple-sample] - * Uses the [`shelf`][] package. - * Also uses the [`shelf_router`][] and [`shelf_static`][] packages. - * Is deployable on Cloud Run. - * [A Dart HTTP server that uses Cloud Firestore][cloud-sample] - * Uses the Cloud Firestore features in the [`googleapis`][] package. - * Also uses the [`googleapis_auth`][], [`shelf`][], and - [`shelf_router`][] packages. - * Is deployable on Cloud Run. +## Documentation + +* [Using Google Cloud][] has information on Google Cloud products + that Dart servers can use, such as Cloud Run. +* [Using Google APIs][] points to resources to help you + use Firebase and Google client APIs from a Dart app. + +## Samples + +* [A simple Dart HTTP server][simple-sample] + * Uses the [`shelf`][] package. + * Also uses the [`shelf_router`][] and [`shelf_static`][] packages. + * Is deployable on Cloud Run. +* [A Dart HTTP server that uses Cloud Firestore][cloud-sample] + * Uses the Cloud Firestore features in the [`googleapis`][] package. + * Also uses the [`googleapis_auth`][], [`shelf`][], and + [`shelf_router`][] packages. + * Is deployable on Cloud Run. [cloud-sample]: https://github.com/dart-lang/samples/tree/main/server/google_apis [`googleapis`]: {{site.pub-pkg}}/googleapis