LocalPersist class

This will save/load objects into the local disk, as a '.json' file.

=========================================================

  1. Save a simple object in UTF-8 Json format.

Use saveJson to save as Json:

var persist = LocalPersist("xyz");
var simpleObj = "Hello";
await persist.saveJson(simpleObj);

Use loadJson to load from Json:

var persist = LocalPersist("xyz");
Object? decoded = await persist.loadJson();

Examples of valid JSON includes: 42 42.5 "abc" 1, 2, 3 "42", 123 {"42": 123}

Examples of invalid JSON includes: 4, 5, 6 // Not valid because Json does not allow two separate objects. 1, 2, 3 // Not valid because Json does not allow comma separated objects. 'abc' // Not valid because string must use double quotes. {42: "123"} // Not valid because a map key must be of type string.

=========================================================

  1. Save multiple simple objects in a concatenation of UTF-8 Json sequence. Note: A Json sequence is NOT valid Json.

Use save to save a list of objects as a Json sequence:

var persist = LocalPersist("xyz");
List<Object> simpleObjs = ['"Hello"', '"How are you?"', [1, 2, 3], 42];
await persist.save();

The save method has an append parameter. If append is false (the default), the file will be overwritten. If append is true, it will write to the end of the file. Being able to append is the only advantage of saving as a Json sequence instead of saving in regular Json. If you don't need to append, use saveJson instead of save.

Also, a limitation is that, in a json sequence, each object may have at most 65.536 bytes. Note this refers to a single json object, not to the total json sequence file, which may contain many objects.

Use load to load a list of objects from a Json sequence:

var persist = LocalPersist("xyz");
List<Object> decoded = await persist.load();

Constructors

LocalPersist(Object dbName, {String? dbSubDir, List<Object>? subDirs})
Saves to appDocsDir/db/${dbName}.db
LocalPersist.from(File file)
Saves to the given file.

Properties

dbName String?
final
dbSubDir String?
final
hashCode int
The hash code for this object.
no setterinherited
runtimeType Type
A representation of the runtime type of the object.
no setterinherited
subDirs List<String>?
final

Methods

delete() Future<bool>
Deletes the file. If the file was deleted, returns true. If the file did not exist, return false.
exists() Future<bool>
Returns true if the file exist. False, otherwise.
file() Future<File>
Gets the file.
length() Future<int>
Returns the file length. If the file doesn't exist, or exists and is empty, returns 0.
load() Future<List<Object?>?>
Loads the simple objects from the file. If the file doesn't exist, returns null. If the file exists and is empty, returns an empty list.
loadAsObj() Future<Map<String, dynamic>?>
Same as load, but expects the file to be a Map<String, dynamic> representing a single object. Will fail if it's not a map, or if contains more than one single object. It may return null.
loadJson() Future<Object?>?
Loads an object from a JSON file ('.db' file). If the file doesn't exist, returns null. Note: The file must contain a single JSON, which is NOT the default file-format for LocalPersist.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
save(List<Object> simpleObjs, {bool append = false}) Future<File>
Saves the given simple objects. If append is false (the default), the file will be overwritten. If append is true, it will write to the end of the file.
saveJson(Object? simpleObj) Future<File>
Saves the given simple object as JSON (but in a '.db' file). If the file exists, it will be overwritten.
toString() String
A string representation of this object.
inherited

Operators

operator ==(Object other) bool
The equality operator.
inherited

Static Properties

appDocDir Directory?
no setter
defaultDbSubDir String
The default is saving/loading to/from "appDocsDir/db/". This is not final, so you can change it. Make it an empty string to remove it.
getter/setter pair
defaultTermination String
The default is adding a ".db" termination to the file name. This is not final, so you can change it.
getter/setter pair
useBaseDirectory Future<void> Function()
If running from Flutter, the default base directory is the application's documents dir. If running from tests (detected by the LocalFileSystem not being present), it will use the system's temp directory.
getter/setter pair

Static Methods

bytesToUint8Lists(Uint8List bytes) List<Uint8List>
concatUint8Lists(List<Uint8List> chunks) Uint8List
decode(Uint8List bytes) List<Object?>
decodeJson(Uint8List bytes) Object?
Decodes a single JSON into a simple object, from the given bytes.
encode(List<Object> simpleObjs) Uint8List
encodeJson(Object? simpleObj) Uint8List
Decodes a single simple object into a JSON, from the given simpleObj.
getFileSystem() → FileSystem
jsonsToUint8Lists(Iterable<String> jsons) List<Uint8List>
objsToJsons(List<Object> simpleObjs) Iterable<String>
pathName(String? dbName, {String? dbSubDir, List<String>? subDirs}) String
resetFileSystem() → void
setFileSystem(FileSystem fileSystem) → void
You can set a memory file-system in your tests. For example:
simpleObjsToString(List<Object?>? simpleObjs) String?
toSimpleObjs(Iterable<String> jsons) Iterable<Object?>
uint8ListsToJsons(Iterable<Uint8List> chunks) Iterable<String>
useAppCacheDir() Future<void>
If running from Flutter, the base directory will be the application's cache directory. If running from tests, it will use the system's temp directory.
useAppDocumentsDir() Future<void>
If running from Flutter, the base directory will be the application's documents directory. If running from tests, it will use the system's temp directory.
useAppDownloadsDir() Future<void>
If running from Flutter, the base directory will be the application's downloads directory. If running from tests, it will use the system's temp directory.
useCustomBaseDirectory({required Directory baseDirectory, Directory? testDirectory}) Future<void>
If running from Flutter, the base directory will be the given baseDirectory. If running from tests, it will use the optional testDirectory, or if this is not provided, it will use the system's temp directory.

Constants

maxJsonSize → const int