sembast 1.7.0

  • README.md
  • CHANGELOG.md
  • Installing
  • Versions
  • 88

sembast.dart

sembast db stands for Simple Embedded Application Store database

Build Status

General

Yet another persistent store database solution for single process io applications. The whole database resides in a single file and is loaded in memory when opened. Changes are appended right away to the file and the file is automatically compacted when needed.

Inspired from IndexedDB, DataStore, WebSql, NeDB, Lawndart...

Usage

Sample usage are given using the experimental async/await feature for clarity. Same code can be done using Future

Opening a database

A database is a single file represented by a path in the file system

// File path to a file in the same directory than the current script
String dbPath = join(dirname(Platform.script.toFilePath()), "sample.db");
DatabaseFactory dbFactory = ioDatabaseFactory;

// We use the database factory to open the database
Database db = await dbFactory.openDatabase(dbPath);

The db object is ready for use.

Simple put/get records

For quick usage, data can be written and read quickly using the put/get/delete api on the database object

// Easy to put/get simple values or map
// A key can be anything (int, String) as long is it can
// be properly JSON encoded/decoded
await db.put('Simple application', 'title');
await db.put(10, 'version');
await db.put({'offline': true}, 'settings');

// read values
String title = await db.get('title'); 
int version = await db.get('version');
Map settings = await db.get('settings');
  
// ...and delete
await db.delete('version');

Auto increment

If no key is provided, the object is inserted with an auto-increment value

// Auto incrementation is built-in
int key1 = await db.put('value1');
int key2 = await db.put('value2');
// key1 = 1, key2 = 2...

Transaction

Actions can be group in transaction for consistency and optimization (single write on the file system). If an error is thrown, the transaction is cancelled and the changes reverted

await db.inTransaction(() async {
  await db.put('value1');
  await db.put('value2');
});

Simple wrapping into a Record object

A record object holds the record content and key

int key = await db.put({'offline': true});
Record record = await db.getRecord(key);
  
// A record can be accessed like a map
expect(record['offline'], isTrue);
// and has the key in it
expect(record.key, key);

Simple find mechanism

(Work in progress) Filtering and sorting can be done on any field

// Store some objects
await db.inTransaction(() async {
  await db.put({'name': 'fish'});
  await db.put({'name': 'cat'});
  await db.put({'name': 'dog'});
});
  
// Look for any animal "greater than" (alphabetically) 'cat'
// ordered by name
Finder finder = new Finder();
finder.filter = new Filter.greaterThan('name', 'cat');
finder.sortOrder = new SortOrder('name');
List<Record> records = await db.findRecords(finder);
  
expect(records.length, 2);
expect(records[0]['name'], 'dog');
expect(records[1]['name'], 'fish');

Store

The store has some similarities with IndexedDB store and DataStore entities. The database always has a main store for easy access (like in the example aboves or typically to save singletons) and allows for an infinite number of stores where a developer would store entity specific data (such as list of record of the same 'type')

// Access the "animal" store
Store animalStore = db.getStore("animal");
// create animals in the store
Record cat = new Record(animalStore, {'name': 'cat'});
Record dog = new Record(animalStore, {'name': 'dog'});
// save them
await db.putRecords([cat, dog]);
  
// get all animals
await animalStore.records.listen((Record animal) {
  // here we know we have a single record
  // .. you'll get dog and cat here
}).asFuture();

idb_shim

The project idb_shim provides a shim allowing accessing it using the IndexedDB api. The benefit is to be able to write the logic/synchronization part of the database layer and test its algorithms using Dart VM and not Dartium

// Idb factory based on sembast
IdbSembastFactory idbFactory = new IdbSembastFactory(ioDatabaseFactory);

String store = "my_store";

// Here the indexed db API can be used
void _initializeDatabase(VersionChangeEvent e) {
  Database db = e.database;
  // create a store
  ObjectStore objectStore = db.createObjectStore(store);
}
Database db = await idbFactory.open(dbPath, version: 1, onUpgradeNeeded: _initializeDatabase);

Transaction transaction = db.transaction(store, IDB_MODE_READ_WRITE);
ObjectStore objectStore = transaction.objectStore(store);

// put and read on object
await objectStore.put("value", "test");
expect(await objectStore.getObject("test"), "value");

await transaction.completed;

Build status

Travis: Build Status

1.7.0

  • mode databaseModeNeverFails is the new default
  • API cleanup and add deprecations

1.6.1

  • Add implicit-cast: false support

1.6.0

1.5.0

  • Update synchronized dependency
  • Add DatabaseMode.NEVER_FAILS that will ignore the file once a corrupted record is encountered

1.3.9

  • Add web example to test ddc support
  • Fix transaction

1.3.7

  • Strong mode support
  • support for setting record field directly
  • fix support for dart 1.24

1.3.1

  • Add support for import/export

1.2.2

  • Add for support for isNull and notNull filter
  • Add for support for sorting null last
  • Travis test integration

1.0.0

  • Initial revision

1. Depend on it

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


dependencies:
  sembast: "^1.7.0"

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter packages get

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

3. Import it

Now in your Dart code, you can use:


import 'package:sembast/sembast.dart';
        
Version Uploaded Documentation Archive
1.7.0 Mar 6, 2018 Go to the documentation of sembast 1.7.0 Download sembast 1.7.0 archive
1.6.1 Mar 1, 2018 Go to the documentation of sembast 1.6.1 Download sembast 1.6.1 archive
1.6.0 Jan 24, 2018 Go to the documentation of sembast 1.6.0 Download sembast 1.6.0 archive
1.5.0 Oct 17, 2017 Go to the documentation of sembast 1.5.0 Download sembast 1.5.0 archive
1.4.0 Jun 27, 2017 Go to the documentation of sembast 1.4.0 Download sembast 1.4.0 archive
1.3.9 Jun 20, 2017 Go to the documentation of sembast 1.3.9 Download sembast 1.3.9 archive
1.3.7 May 23, 2017 Go to the documentation of sembast 1.3.7 Download sembast 1.3.7 archive
1.3.6 May 23, 2017 Go to the documentation of sembast 1.3.6 Download sembast 1.3.6 archive
1.3.5 Oct 7, 2016 Go to the documentation of sembast 1.3.5 Download sembast 1.3.5 archive
1.3.3 Dec 15, 2015 Go to the documentation of sembast 1.3.3 Download sembast 1.3.3 archive

All 26 versions...

Analysis

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

  • Dart: 2.0.0-dev.46.0
  • pana: 0.10.6

Scores

Popularity:
Describes how popular the package is relative to other packages. [more]
77 / 100
Health:
Code health derived from static analysis. [more]
100 / 100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
95 / 100
Overall score:
Weighted score of the above. [more]
88
Learn more about scoring.

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:sembast/sembast.dart.

Suggestions

  • Use constrained dependencies.

    The pubspec.yaml contains 3 dependencies without version constraints. Specify version ranges for the following dependencies: logging, path, synchronized.

  • The description is too short.

    Add more detail about the package, what it does and what is its target use case. Try to write at least 60 characters.

  • Fix analysis and formatting issues.

    Analysis or formatting checks reported 8 hints.

    Strong-mode analysis of lib/src/database_impl.dart gave the following hint:

    line: 154 col: 23
    'JSON' is deprecated and shouldn't be used.

    Strong-mode analysis of lib/src/file_system.dart gave the following hint:

    line: 273 col: 71
    'UTF8' is deprecated and shouldn't be used.

    Similar analysis of the following files failed:

    • lib/src/io/io_file_system.dart (hint)
    • lib/src/memory/memory_file_system.dart (hint)
    • lib/src/sembast_fs.dart (hint)
  • Maintain an example.

    None of the files in your example/ directory matches a known example patterns. Common file name patterns include: main.dart, example.dart or you could also use sembast.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.24.0 <2.0.0
logging >=0.11.3 0.11.3+1
path >=1.3.9 1.5.1
synchronized >=1.2.1 1.4.0
Dev dependencies
browser any
chrome_travis
dev_test >=0.9.3
test >=0.12.5