0.4.0 (#11)

Author: simc

.travis.yml

@@ -1,24 +1,43 @@
 language: dart
 os:
-  - linux
-sudo: false
-dart:
-  - stable
-script:
-  - cd hive_generator
-  - pub get
-  - pub run test
+  - osx
+addons:
+  chrome: stable
+  firefox: latest
+jobs:
+  include:
+    - name: hive
+      script:
+        - cd hive
+        - pub get
+        - pub run test
 
-  - cd ../hive
-  - pub get
-  - pub run test -p "vm,chrome"
-  
-  - dartfmt -n --set-exit-if-changed ./lib ./test ./example || travis_terminate 1
+    - name: hive chrome
+      script:
+        - cd hive
+        - pub get
+        - pub run test -p "chrome"
+
+    - name: hive firefox
+      script:
+        - cd hive
+        - pub get
+        - pub run test -p "firefox"
+        
+    - name: hive_generator
+      script:
+        - cd hive_generator
+        - pub get
+        - pub run test
+      
+    - name: format
+      script:
+        - dartfmt -n --set-exit-if-changed ./lib ./test ./example || travis_terminate 1
+      
 
-  - pub global activate test_coverage
-  - test_coverage --exclude "**_js_test.dart"
-after_success:
-  - bash <(curl -s https://codecov.io/bash)
-cache:
-  directories:
-    - $HOME/.pub-cache
+    - stage: coverage
+      script:
+        - pub global activate test_coverage
+        - test_coverage --exclude "**_js_test.dart"
+      after_success:
+        - bash <(curl -s https://codecov.io/bash)

docs/_sidebar.md

@@ -4,11 +4,10 @@
     * [Encrypted box](encrypted_box.md)
 
 * Using boxes
-    * [Read](read.md)
     * [Write](write.md)
+    * [Read](read.md)
     * [Delete](delete.md)
     * [Watch changes](watch_changes.md)
-    * [Transactions](transactions.md)
     * [Compaction](compaction.md)
 
 * TypeAdapters

docs/auto_increment.md

@@ -0,0 +1,31 @@
+# Auto increment & indices
+
+We already know that Hive supports integer keys. You can use auto increment keys if you like. This is very useful for storing and accessing multiple objects. You can use a Box like a list.
+
+```dart
+var friends = Hive.box('friends');
+
+friends.add('Lisa');       //index 0, key 0
+
+friends.add('Dave');       //index 1, key 1
+
+friends.put(123, 'Marco'); //index 2, key 123
+
+print(friends.values); // Lisa, Dave, Marco
+```
+
+There are also `getAt()`, `putAt()` and `deleteAt()` methods to access or change values by their index.
+
+It is important to understand the difference of integer keys and indices.
+
+```dart
+friends.putAt(2, 'Ben');
+
+frinds.put(123, 'Ben');
+```
+
+Both of these operations do the same thing. They replace the `Marco` with `Ben`. `putAt()` uses the index (in this case `2`), `put()` uses the key (in this case `123`).
+
+This also works with String keys.
+
+?> Even if you only use auto increment keys, you should not rely on keys and indices being the same.

docs/boxes.md

@@ -10,7 +10,7 @@ Boxes can also be encrypted to store sensitive data.
 Before a box can be used, you have to open it:
 
 ```dart
-var box = await Hive.box('testBox');
+var box = await Hive.openBox('testBox');
 ```
 
 If the box is already open, it will be returned immediately. All supplied parameters will be ignored.
@@ -22,22 +22,21 @@ Once you obtained a box instance, you can read, write and delete entries.
 Hive stores a reference to all open boxes. If you want to get an already opened box, you can use 
 
 ```dart
-var box = Hive['myBox'];
+var box = Hive.box('myBox');
 ```
 
-This is especially useful for Flutter apps because you don't need a `FutureBuilder` to get a box.
+This is especially useful for Flutter apps because you don't need to pass the box between widgets.
 
 ## Close box
 
 If you don't need a box again, you should close it. All cached keys and values of the box will be dropped from memory and the box file will be closed after all active read and write operations finished.
 
-?> It is not recommended to open and close the same box frequently because this leads to unnecessary disk access and takes time. If you need a box again in the future, just leave it open.
+?> It is perfectly fine to leave a box open for the runtime of the app. If you need a box again in the future, just leave it open.
 
 ```dart
-var box = await Hive.open('myBox');
+var box = await Hive.openBox('myBox');
 await box.put('hello', 'world');
 await box.close();
 ```
 
 Before your application exits, you should call `Hive.close()` to close all open boxes.
-

docs/compaction.md

@@ -5,14 +5,15 @@ Hive is an append-only data store. When you change or delete a value, the change
 It may benefit the start time of your app if you induce compaction manually before you close a box.
 
 ```dart
+var box = Hive.box('myBox');
 await box.compact();
 await box.close();
 ```
 
 You can specify your own rules for automatic compaction. Just pass the `compactionStrategy` parameter when you open a box:
 
 ```dart
-var box = await Hive.box('myBox', compactionStrategy: (entries, deletedEntries) {
+var box = await Hive.openBox('myBox', compactionStrategy: (entries, deletedEntries) {
   return deletedEntries > 50;
 });
 ```

docs/create_adapter_manually.md

@@ -2,7 +2,7 @@
 
 Sometimes it might be necessary to create a custom `TypeAdapter`. You can do that by extending the `TypeAdapter` class. Make sure to specify the generic argument.
 
-!> Test your custom `TypeAdapter` thoroughly. If one does not work correctly, it may corrupt your box.
+!> Test your custom `TypeAdapter`s thoroughly. If one does not work correctly, it may corrupt your box.
 
 It is very easy to implement a `TypeAdapter`. Here is the `DataTimeAdapter` used by Hive internally:
 

docs/delete.md

@@ -1,9 +1,11 @@
 # Delete key
 
-If you want to change an existing value, you can either override it using `put()` or delete it:
+If you want to change an existing value, you can either override it using for example `put()` or delete it:
 
 ```dart
-var deleted = await box.delete('key');
+var box = Hive.box('testBox');
+
+box.delete('key');
 ```
 
 If the key does not exist, no disk access is needed and the returned `Future` finishes immediately.

docs/encrypted_box.md

@@ -11,7 +11,7 @@ var key = Hive.generateSecureKey();
 Just pass the key when you open a box:
 
 ```dart
-var encryptedBox = await Hive.box('vaultBox', encryptionKey: key);
+var encryptedBox = await Hive.openBox('vaultBox', encryptionKey: key);
 ```
 
 !> Make sure you store the key securely when your application is closed. With Flutter you can use the [flutter_secure_storage](https://pub.dev/packages/flutter_secure_storage) or a similar package.

docs/generate_adapter.md

@@ -30,7 +30,7 @@ class Person {
 }
 ```
 
-As you can see, each field has a **unique** number. These field numbers are used to identify the fields in the hive binary format, and should not be changed once your class is in use.
+As you can see, each field has a **unique** number (unique per class). These field numbers are used to identify the fields in the hive binary format, and should not be changed once your class is in use.
 
 *Field numbers can be in the range 0-255*.
 

docs/lazy_box.md

@@ -5,13 +5,13 @@ By default, the whole content of a box is stored in memory as soon as it is open
 For larger boxes or very memory critical applications, it may be useful to load values lazily. When a lazy box is being opened, all of its keys are read and stored in memory. Once you access a value, Hive knows its exact position on the disk and gets the value.
 
 ```dart
-var lazyBox = await Hive.box('myLazyBox', lazy: true);
+var lazyBox = await Hive.openBox('myLazyBox', lazy: true) as LazyBox;
 
 var value = await lazyBox.get('lazyVal');
 ```
 
-You can use lazy boxes like any other box, but you can't access keys using the list access operator `[]`.
+To get an already opened lazy box call:
 
 ```dart
-var value = lazyBox['lazyVal']; // ERROR
+var lazyBox = Hive.box('myLazyBox') as LazyBox;
 ```

docs/limitations.md

@@ -1,8 +1,9 @@
 # Limitations
 
 - **HIVE IS NOT READY FOR PRODUCTION YET**
-- Keys have to be ASCII Strings with a max length of 255 chars.
+- Keys have to be 32 bit unsigned integers or ASCII Strings with a max length of 255 chars.
 - The supported integer values include all integers between -2^53 and 2^53, and some integers with larger magnitude
 - Strings can have a maximum of 65535 **bytes**. Mind that a Unicode chars may be longer than one byte.
 - Lists and Maps cannot have more than 65535 elements.
+- Objects are not allowed to contain cycles. Hive will not detect them and storing will result in an infinite loop.
 - Only one process can access a box at any time. Bad things happen otherwise.

docs/read.md

@@ -1,23 +1,15 @@
 # Read from box
 
-Reading from a box is almost like accessing a Map:
+Reading from a box is very straightforward:
 
 ```dart
-String name = box['name'];
+String name = box.get('name');
 
-DateTime birthday = box['birthday'];
-```
-
-If your box is [lazy](lazy_box.md) the above code will not work. You have to access the box using `get()`:
-
-```dart
-String name = await box.get('name');
-
-DateTime birthday = await box.get('birthday');
+DateTime birthday = box.get('birthday');
 ```
 
 If the key does not exist, `null` is returned. Optionally you can specify a `defaultValue` which will be returned in case the key does not exist.
 
 ```dart
-double height = await box.get('randomKey', defaultValue: 17.5);
+double height = box.get('randomKey', defaultValue: 17.5);
 ```

docs/transactions.md

@@ -5,23 +5,23 @@ If you want to get notified about changes in a box, you can subscribe to the `St
 This can be very useful for Flutter apps: You can rebuild widgets every time the box changes.
 
 ```dart
-var box = await Hive.get('myBox');
-box.watch().listen((key, val) {
-  if (val == null) {
-    print('$key has been deleted');
+var box = Hive.box('myBox');
+box.watch().listen((event) {
+  if (event.deleted) {
+    print('${event.key} has been deleted');
   } else {
-    print('$key is now assigned to $val');
+    print('${event.key} is now assigned to ${event.value}');
   }
 });
 
-await box.put('someKey', 123); // > someKey is now assigned to 123
-await box.delete('someKey'); // > someKey has been deleted
+box.put('someKey', 123); // > someKey is now assigned to 123
+box.delete('someKey'); // > someKey has been deleted
 ```
 
 If you specify the `key` parameter, you will be notified about all changes of a specific key.
 
 ```dart
-box.watch(key: 'someKey').listen((key, val) {
+box.watch(key: 'someKey').listen((event) {
     // ...
 });
 ```

docs/watch_changes.md

@@ -1,11 +1,22 @@
 # Write to box
 
-Writing is just as easy as reading. All keys have to be ASCII Strings with a max lenght of 255 chars.
+Writing to a box is almost like writing to a map. All keys have to be ASCII Strings with a max lenght of 255 chars or integers.
 
 ```dart
-await box.put('name', 'Paul');
+var box = Hive.box('myBox');
 
-await box.put('friends', ['Dave', 'Simon', 'Lisa']);
+box.put('name', 'Paul');
+
+box.put('friends', ['Dave', 'Simon', 'Lisa']);
+
+box.put(123, 'test');
+
+box.putAll({'key1': 'value1', 42: 'life'})
 ```
 
-?> Writing `null` is the same as [deleting](delete.md) a value.
+You may wonder why writing works without async code. This is one of the main strengths of Hive.<br>
+The changes are written to the disk as soon as possible in the background but all listeners are notified immediately. If the async operation fails (which it should not), all listeners are notified again with the old values.
+
+This does not work for [lazy](lazy_box.md) boxes. As long as the `put()` Future did not finish, `get()` will return the old values.
+
+?> Writing `null` is **NOT** the same as [deleting](delete.md) a value.

docs/write.md

@@ -0,0 +1,8 @@
+#!/bin/sh
+# This is a generated file; do not edit or check into version control.
+export "FLUTTER_ROOT=C:\Users\simon\flutter"
+export "FLUTTER_APPLICATION_PATH=C:\Users\simon\Documents\GitHub\hive\examples\basic_flutter"
+export "FLUTTER_TARGET=lib\main.dart"
+export "FLUTTER_BUILD_DIR=build"
+export "SYMROOT=${SOURCE_ROOT}/../build\ios"
+export "FLUTTER_FRAMEWORK_DIR=C:\Users\simon\flutter\bin\cache\artifacts\engine\ios"

examples/basic_flutter/ios/Flutter/flutter_export_environment.sh

@@ -10,7 +10,7 @@ class MyApp extends StatelessWidget {
   Future<Box> _openBox() async {
     final directory = await getApplicationDocumentsDirectory();
     Hive.init(directory.path);
-    return await Hive.box('myBox');
+    return await Hive.openBox('myBox');
   }
 
   @override
@@ -40,7 +40,7 @@ class IceCreamPage extends StatefulWidget {
 }
 
 class _IceCreamPageState extends State<IceCreamPage> {
-  var box = Hive['myBox'];
+  var box = Hive.box('myBox');
 
   @override
   void initState() {
@@ -53,7 +53,7 @@ class _IceCreamPageState extends State<IceCreamPage> {
 
   @override
   Widget build(BuildContext context) {
-    var userLikesIceCream = box['userLikesIceCream'] ?? false;
+    var userLikesIceCream = box.get('userLikesIceCream', defaultValue: false);
     return Center(
       child: Row(
         mainAxisSize: MainAxisSize.min,