local_shared 3.0.0

Lightweight cross-platform secure local storage for Flutter. Native-safe JSON collections and documents with tested CRUD, batch operations, migration semantics, and stream updates.

Local Shared | View Demo

A secure wrapper for JSON file-based storage, providing an alternative to Localstore. Safely execute CRUD operations across all platforms with built‑in support for sensitive data handling.

Install

Add this line to your pubspec.yaml.

dependencies:
  local_shared: ^3.0.0

Initialize

Start by initializing the LocalShared instance in your main function, after ensuring Flutter is properly initialized.

import 'package:local_shared/local_shared.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await LocalShared('db').initialize();
}

and next, interact with collections and documents using either the LocalShared or Shared prefix. You can even create a custom definition for added convenience.

typedef DB = LocalShared;

Collection | View Code

SharedCollection organizes documents in a JSON map. Use Shared.col(id) or Shared.collection(id), then operate with the following methods.

Create

final result = await Shared.col('myCollection').create();
// SharedMany(success: true, message: ..., data: [])

• replace: true can overwrite existing collection.

Read

final response = await Shared.col('myCollection').read();
// SharedMany(success: true, message: ..., data: [ ... ])

Update

final response = await Shared.col('myCollection').update({
  'doc1': {'k': 'v'},
  'doc2': {'k': 'v2'},
});
// SharedMany(success: true, message: ..., data: [ ... ])

• force: true creates missing collection if it does not exist.

Migrate

final response = await Shared.col('myCollection').migrate('targetCollection');
// SharedMany(success: true, message: ..., data: [ ... ])

• merge: true merges existing target collection data.
• force: true allows migration from non-existing source.

Delete

final response = await Shared.col('myCollection').delete();
// SharedNone(success: true, message: ...)

Document | View Code

This guide elaborates on the essential CRUD (Create, Read, Update, Delete) operations for document management within collections. Interacting with document can be achieved through the following methods: Shared.col(id).doc(id) or Shared.collection(id).document(id).

Create

To initiate the creation of a new document, leverage this method:

final result = await Shared.col('myCollection').doc('documentId').create({'key': 'value'});
print(result); // SharedOne(success: true, message: '...', data: JSON)

Read

To retrieve the contents of a document within a collection, use this method:

final response = await Shared.col('myCollection').doc('documentId').read();
print(response); // SharedOne(success: true, message: '...', data: JSON)

Update

To modify the contents of a document within a collection, invoke this method:

final response = await Shared.col('myCollection').doc('documentId').update({'newKey': 'newValue'});
print(response); // SharedOne(success: true, message: '...', data: JSON)

Delete

To delete a document within a collection, implement this method:

final response = await Shared.col('myCollection').doc('documentId').delete();
print(response): // SharedNone(success: true, message: '...')

Many Document | View Code

This guide details the fundamental CRUD (Create, Read, Update, Delete) operations for the management of multiple documents within collections. Interacting with this can be achieved through the following methods: Shared.col(id).docs([id1, id2]) or Shared.collection(id).documents([id1, id2]).

Create

Initiate the creation of multiple documents with this method:

final result = await Shared.col('myCollection').docs(['docId1', 'docId2']).create((index) => {'key': 'value'});
print(result); // SharedMany(success: true, message: '...', data: <JSON>[])

Read

Retrieve the contents of multiple documents within a collection using this method:

final response = await Shared.col('myCollection').docs(['docId1', 'docId2']).read();
print(response); // SharedMany(success: true, message: '...', data: <JSON>[])

Update

Modify the contents of multiple documents within a collection with this method:

final response = await Shared.col('myCollection').docs(['docId1', 'docId2']).update((index) => {'newKey': 'newValue'});
print(response); // SharedMany(success: true, message: '...', data: <JSON>[])

Delete

Delete multiple documents within a collection using this method;

final response = await Shared.col('myCollection').docs(['docId1', 'docId2']).delete();
print(response); // SharedNone(success: true, message: '...')

Stream

LocalShared offers a JSON stream for observing changes in collections when we access those collection through Shared.col or Shared.collection syntax. And if you interact with multiple collections, the stream exclusively displays data from the latest collection you engage with.

LocalShared.stream.listen(print);

await Shared.col('myCollection').docs(['A','B']).create((index) => {'desc': 'test'});

Result:

{id: myCollection, documents: [

{id: A, data: {desc: test}}, {id: B, data: {desc: test}} ]}

Custom Stream

If you only want to observe changes in a specific collection, you can use the following approach:

final controller = StreamController<JSON>.broadcast();
final collection = SharedCollection('myCertainCollection', controller: controller);

controller.stream.listen(print);

await collection.docs(['A','B']).create((index) => {'desc': 'test'});

Result:

{id: myCertainCollection, documents: [

{id: A, data: {desc: test}}, {id: B, data: {desc: test}} ]}

Extension

To simplify matters, there's an extension to handle response data from SharedResponse. If you're expecting SharedResponse to return JSON?, call this method:

JSON? result = await Shared.col(id).doc(id).read().one();

Alternatively, if you're expecting SharedResponse to return a List<JSON>?, call this method:

List<JSON>? result = await Shared.col(id).read().many();

Example

• local_shared/example/lib/main.dart