universal_io 1.0.1

  • Readme
  • Changelog
  • Example
  • Installing
  • 97

Pub Package Github Actions CI Build Status

Overview #

A cross-platform dart:io that works in all platforms (browsers, Flutter, and VM).

Licensed under the Apache License 2.0. Much of the source code is derived from Dart SDK, which was obtained under the BSD-style license of Dart SDK. See LICENSE file for details.

Similar packages #

Getting started #

pubspec.yaml #

dependencies:
  universal_io: ^1.0.1

The may also consider chrome_os_io (if you use Chrome OS) and nodejs_io (if you use Node.JS).

main.dart #

import 'package:universal_io/io.dart';

Future<void> main() async {
  final httpClient = HttpClient();
  final request = await httpClient.getUrl(Uri.parse("http://google.com"));
  final response = await request.close();
}

Getting warnings? In some situations, Dart development tools (your IDE) may give warnings, but your application should compile normally. It's possible to eliminate such warnings by importing 'package:universal_io/prefer_universal/io.dart', but we recommend that you always stick to 'package:universal_io/io.dart'.

Browser driver #

HTTP client #

HTTP client is implemented using XMLHttpRequest (XHR) (in dart:html, the class is HttpRequest). In future, we may support Fetch API too.

XHR causes the following differences with dart:io:

  • HTTP connection is created only after request.close() has been called.
  • Same-origin policy limitations. For making cross-origin requests, see documentation below.

CORS #

If the HTTP request is cross-origin and Authorization header is present, the request will automatically use CORS credentials mode. For other requests, you can manually enable credentials mode using:

import 'package:universal_io/io.dart';

Future<void> main() async {
  final request = HttpClient().getUrl(Uri.parse('https://example.com/path'));

  if (request is BrowserHttpClientRequest) {
    request.credentialsMode = BrowserHttpClientCredentialsMode.include;
  }

  final response = await request.close();
  // ...
}

If any cross-origin request fails, error message contains a detailed description how to fix possible issues like missing cross-origin headers. The error messages look like:

BrowserHttpClient received an error from XMLHttpRequest (which doesn't tell
reason for the error).

HTTP method:   PUT
URL:           http://destination.com/path/example
Origin:        http://source.com

Cross-origin request!
CORS 'credentials mode' is disabled (the browser will not send cookies).
You can enable 'credentials mode' with:

    if (httpRequest is BrowserHttpClientRequest) {
      httpRequest.credentialsMode = BrowserHttpClientCredentialsMode.include;
    }

Did the server send the following mandatory headers?
  * Access-Control-Allow-Origin: http://source.com
    * OR '*'
  * Access-Control-Allow-Methods: PUT

Streaming responses #

XHR in browsers supports streaming HTTP response when the response type is 'text'.

You can enable this behavior with the following trick:

import 'package:universal_io/io.dart';

Future<void> main() async {
    final request = HttpClient().getUrl(Uri.parse('https://example.com/path'));

    // Define response type in browsers
    if (request is BrowserHttpClientRequest) {
      request.responseType = BrowserHttpClientResponseType.text;
    }

    // Listen streaming response
    final response = await request.close();
    response.listen((chunk) {
      // ...
    });
}

Platform #

The implementation supports APIs such as:

  • Platform.isWindows
  • Platform.operatingSystem
  • Platform.locale

1.0.1 #

  • Fixes bugs related to imports and improves tests for such bugs.
  • Improves documentation.

1.0.0 #

  • Implements recent changes in 'dart:io' (Dart SDK 2.8).
  • HttpDriver is replaced by 'dart:io' HttpOverrides.
  • FileSystemDriver is replaced by 'dart:io' IOOverrides.
  • Various other driver APIs are renamed or removed.
  • BrowserLikeHttpClientRequest is now BrowserHttpClientRequest.
  • BrowserHttpClientRequest implementation is improved.

0.8.6 #

  • Fixed documentation and small fixes related to nodejs_io.

0.8.5 #

  • Raised minimum SDK to 2.6 and upgraded dependencies.
  • Changed how CORS credentials mode is enabled. It was previously enabled with a header, but now we introduced subclasses for HttpClient and HttpClientRequest. This is a breaking change, but we decided not to bump the major version number.
  • Improved analysis and test settings.

0.8.4 #

  • Added 'prefer_sdk/io.dart' and 'prefer_universal/io.dart' libraries for dealing with conditional export issues.
  • Library 'package:universal_io/io.dart' now exports SDK version by default.

0.8.3 #

  • Replaced IP address parsing with the new Uri.parseIPv4Address / Uri.parseIPv6Address.
  • Fixed missing HTTP status codes.

0.8.2 #

  • Fixed problems introduced by Dart SDK 2.5.0-dev-2.0.

0.8.1 #

  • Fixed pubspec.yaml and documented Dart SDK 2.5 breaking changes.

0.8.0 #

  • Updated classes to Dart 2.5. See Dart SDK documentation about the changes.
    • Various APIs now return Uint8List instead of List<int>. Examples: File, Socket, HttpClientResponse.
    • Various other breaking changes such as Cookie constructor.

0.7.3 #

  • Fixed the following error thrown by the Dart build system in some cases: "Unsupported conditional import of dart:io found in universal_io|lib/io.dart".

0.7.2 #

  • Small fixes.

0.7.1 #

  • Fixed various bugs.
  • Improved the test suite.

0.7.0 #

  • Improved driver base classes and the test suite.

0.6.0 #

  • Major refactoring of IODriver API.

0.5.1 #

  • Fixed small bugs.

0.5.0 #

  • Fixed various bugs.
  • Re-organized source code.
  • Eliminated dependencies by doing IP parsing in this package.
  • Improved the test suite for drivers.

example/example.dart

import 'package:universal_io/io.dart';

void main() async {
  // Use 'dart:io' HttpClient API.
  final httpClient = HttpClient();
  final request = await httpClient.getUrl(Uri.parse('http://google.com'));
  final response = await request.close();
  print(response.toString());
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  universal_io: ^1.0.1

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:universal_io/driver.dart';
import 'package:universal_io/driver_base.dart';
import 'package:universal_io/io.dart';
import 'package:universal_io/prefer_sdk/io.dart';
import 'package:universal_io/prefer_universal/io.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
93
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
97
Learn more about scoring.

We analyzed this package on Apr 3, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.7.1
  • pana: 0.13.6

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.7.0 <3.0.0
meta ^1.1.0 1.1.8
zone_local >=0.1.1 <2.0.0 0.1.2
Dev dependencies
async ^2.4.0
pedantic ^1.9.0
stream_channel ^2.0.0
test ^1.8.0