Make time zone databases available via Dart imports, greatly simplifying the process for Flutter and similar environments.

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 - Time zone database updated to 2019c. For your convenience here is the
   announcement for [2019c].
+- Dart-importable databases made available in `lib/data`. README.md has more
+  details.
 
 [2019c]: http://mm.icann.org/pipermail/tz-announce/2019-September/000057.html
 

README.md

@@ -12,8 +12,22 @@ details.
 [`TimeZone`] objects require time zone data, so the first step is to load
 one of our [time zone databases](#databases).
 
-We provide two different APIs to load a database: one for browsers and one
-standalone environments.
+We provide three different APIs to load a database: one which is base64-encoded
+into a Dart library, one for browsers, and one for standalone environments.
+
+### Initialization from Dart library
+
+This is the recommended way to initialize a time zone database for non-browser
+environments. Each Dart libary found in `lib/data`, for example
+`lib/data/latest.dart`, contains a single no-argument function,
+`initializeTimeZones`.
+
+```dart
+import 'package:timezone/data/latest.dart';
+void main() {
+  initializeTimeZones();
+}
+```
 
 ### Initialization for browser environment
 
@@ -60,45 +74,6 @@ Future<void> setup() async {
 }
 ```
 
-### Initialization for Flutter Apps
-
-Flutter apps need to be initialized slightly differently, as the timezone
-database file needs to be bundled with your application assets.
-
-### Add the database to your pubspec.yaml
-
-Under the `assets` section of your application's `pubspec.yaml`, add
-a reference to the timezone database file:
-
-```yaml
-assets:
-  - packages/timezone/data/latest.tzf
-```
-
-If you don't want to have to change the bundled filename when this
-library updates, you can have flutter bundle the directory instead:
-
-```yaml
-assets:
-  - packages/timezone/data/
-```
-
-### Initialize the library in your application startup
-
-The database needs to be loaded before using the library. A good place
-to do this is in your app's main function before running the Flutter app.
-Here we load the database file from assets, and initialize the library.
-
-```dart
-import 'package:timezone/timezone.dart';
-
-void main() async {
-  var byteData = await rootBundle
-      .load('packages/timezone/data/${tzDataDefaultFilename}');
-  initializeDatabase(byteData.buffer.asUint8List());
-  runApp(MyApp());
-}
-```
 
 ## API
 

lib/data/latest.tzf

@@ -1 +1 @@
-lib/data/2019c.tzf
+2019c.tzf

lib/data/latest_2015-2025.tzf

@@ -1 +1 @@
-lib/data/2019c_2015-2025.tzf
+2019c_2015-2025.tzf

lib/data/latest_all.tzf

@@ -1 +1 @@
-lib/data/2019c_all.tzf
+2019c_all.tzf

lib/src/env.dart

@@ -4,6 +4,9 @@
 
 library timezone.src.env;
 
+import 'dart:convert';
+
+import 'exceptions.dart';
 import 'location.dart';
 import 'location_database.dart';
 import 'tzdb.dart';
@@ -60,3 +63,17 @@ void initializeDatabase(List<int> rawData) {
     _local = _UTC;
   }
 }
+
+/// Initialize Time Zone database from [encodedDatabase].
+///
+/// Throws [TimeZoneInitException] when something is wrong.
+///
+/// This function is private to this package.
+void initializeTimeZonesFromBase64(String encodedDatabase) {
+  try {
+    var rawData = base64Decode(encodedDatabase);
+    initializeDatabase(rawData);
+  } catch (e) {
+    throw TimeZoneInitException(e.toString());
+  }
+}

lib/timezone.dart

@@ -11,4 +11,4 @@ export 'src/location.dart';
 export 'src/location_database.dart';
 export 'src/exceptions.dart';
 export 'src/date_time.dart';
-export 'src/env.dart';
+export 'src/env.dart' hide initializeTimeZonesFromBase64;

pubspec.yaml

@@ -1,12 +1,12 @@
 name: timezone
-version: 0.5.5
+version: 0.5.6
 authors:
 - Boris Kaul <localvoid@gmail.com>
 - Sam Rawlins <sam.rawlins@gmail.com>
 description: Time zone database and time zone aware DateTime.
 homepage: https://github.com/srawlins/timezone
 environment:
-  sdk: '>=2.0.0-dev.36.0 <3.0.0'
+  sdk: '>=2.1.0 <3.0.0'
 dependencies:
   path: '^1.3.0'
 dev_dependencies:

test/datetime_test.dart

@@ -1,9 +1,10 @@
 @TestOn('vm')
 import 'package:test/test.dart';
-import 'package:timezone/standalone.dart';
+import 'package:timezone/timezone.dart';
+import 'package:timezone/data/latest.dart';
 
 main() async {
-  await initializeTimeZone();
+  initializeTimeZones();
   final detroit = getLocation('America/Detroit');
   final la = getLocation('America/Los_Angeles');
   final newYork = getLocation('America/New_York');

tool/encode.dart

@@ -0,0 +1,23 @@
+import 'dart:convert' show base64Encode;
+import 'dart:io';
+
+import 'package:path/path.dart' as p;
+
+Future<void> main(List<String> args) async {
+  final tzDataPath = args[0];
+  final dartLibraryPath = args[1];
+  final bytes = File(tzDataPath).readAsBytesSync();
+  final encodedString = base64Encode(bytes);
+  final buffer = StringBuffer();
+  buffer.write('''
+// This is a generated file. Do not edit.
+//
+// This file contains a base64-encoded timezone database, generated from
+// $tzDataPath by ${p.basename(Platform.script.path)} on ${DateTime.now()}.
+import "package:timezone/src/env.dart" show initializeTimeZonesFromBase64;
+''');
+  buffer.writeln('const _encodedTzData = "$encodedString";');
+  buffer.writeln('void initializeTimeZones() =>\n'
+      '    initializeTimeZonesFromBase64(_encodedTzData);');
+  File(dartLibraryPath).writeAsStringSync(buffer.toString());
+}