Skip to content

Commit 4f907c6

Browse files
authored
refactor: Add Flutter code documentation and resolve StreamController warning (#915)
1 parent d61d704 commit 4f907c6

9 files changed

+138
-81
lines changed

packages/flutter/lib/parse_server_sdk_flutter.dart

Lines changed: 10 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import 'dart:convert';
44
import 'dart:async';
55
import 'dart:io';
66
import 'dart:math';
7+
import 'dart:ui';
78
import 'package:awesome_notifications/awesome_notifications.dart';
89
import 'package:connectivity_plus/connectivity_plus.dart';
910
import 'package:flutter/foundation.dart';
@@ -12,14 +13,14 @@ import 'package:package_info_plus/package_info_plus.dart';
1213
import 'package:parse_server_sdk/parse_server_sdk.dart' as sdk;
1314
import 'package:parse_server_sdk_flutter/src/storage/core_store_directory_io.dart'
1415
if (dart.library.html) 'package:parse_server_sdk_flutter/src/storage/core_store_directory_web.dart';
15-
import 'package:path/path.dart' as path;
1616
import 'package:sembast/sembast.dart';
1717
import 'package:shared_preferences/shared_preferences.dart';
1818

1919
export 'package:parse_server_sdk/parse_server_sdk.dart'
2020
hide Parse, CoreStoreSembastImp;
2121

22-
part 'src/storage/core_store_sp_impl.dart';
22+
part 'src/storage/core_store_shared_preferences.dart';
23+
part 'src/storage/core_store_sembast.dart';
2324
part 'src/utils/parse_live_grid.dart';
2425
part 'src/utils/parse_live_list.dart';
2526
part 'src/notification/parse_notification.dart';
@@ -91,7 +92,7 @@ class Parse extends sdk.Parse
9192
sessionId: sessionId,
9293
autoSendSessionId: autoSendSessionId,
9394
securityContext: securityContext,
94-
coreStore: coreStore ?? await CoreStoreSharedPrefsImp.getInstance(),
95+
coreStore: coreStore ?? await CoreStoreSharedPreferences.getInstance(),
9596
registeredSubClassMap: registeredSubClassMap,
9697
parseUserConstructor: parseUserConstructor,
9798
parseFileConstructor: parseFileConstructor,
@@ -137,77 +138,12 @@ class Parse extends sdk.Parse
137138

138139
@override
139140
void didChangeAppLifecycleState(AppLifecycleState state) {
140-
_appResumedStreamController.sink.add(null);
141-
}
142-
}
143-
144-
Future<String> dbDirectory() async {
145-
String dbDirectory = '';
146-
dbDirectory = await CoreStoreDirectory().getDatabaseDirectory();
147-
return path.join('$dbDirectory/parse', 'parse.db');
148-
}
149-
150-
class CoreStoreSembastImp implements sdk.CoreStoreSembastImp {
151-
CoreStoreSembastImp._();
152-
153-
static sdk.CoreStore? _sembastImp;
154-
155-
static Future<CoreStoreSembastImp> getInstance(
156-
{DatabaseFactory? factory, String? password}) async {
157-
_sembastImp ??= await sdk.CoreStoreSembastImp.getInstance(
158-
await dbDirectory(),
159-
factory: factory,
160-
password: password);
161-
return CoreStoreSembastImp._();
162-
}
141+
if (state == AppLifecycleState.resumed) {
142+
_appResumedStreamController.sink.add(null);
143+
}
163144

164-
@override
165-
Future<bool> clear() async {
166-
await _sembastImp!.clear();
167-
return true;
145+
if (state == AppLifecycleState.paused) {
146+
_appResumedStreamController.close();
147+
}
168148
}
169-
170-
@override
171-
Future<bool> containsKey(String key) => _sembastImp!.containsKey(key);
172-
173-
@override
174-
Future<dynamic> get(String key) => _sembastImp!.get(key);
175-
176-
@override
177-
Future<bool?> getBool(String key) => _sembastImp!.getBool(key);
178-
179-
@override
180-
Future<double?> getDouble(String key) => _sembastImp!.getDouble(key);
181-
182-
@override
183-
Future<int?> getInt(String key) => _sembastImp!.getInt(key);
184-
185-
@override
186-
Future<String?> getString(String key) => _sembastImp!.getString(key);
187-
188-
@override
189-
Future<List<String>?> getStringList(String key) =>
190-
_sembastImp!.getStringList(key);
191-
192-
@override
193-
Future<void> remove(String key) => _sembastImp!.remove(key);
194-
195-
@override
196-
Future<void> setBool(String key, bool value) =>
197-
_sembastImp!.setBool(key, value);
198-
199-
@override
200-
Future<void> setDouble(String key, double value) =>
201-
_sembastImp!.setDouble(key, value);
202-
203-
@override
204-
Future<void> setInt(String key, int value) => _sembastImp!.setInt(key, value);
205-
206-
@override
207-
Future<void> setString(String key, String value) =>
208-
_sembastImp!.setString(key, value);
209-
210-
@override
211-
Future<void> setStringList(String key, List<String> values) =>
212-
_sembastImp!.setStringList(key, values);
213149
}

packages/flutter/lib/src/notification/parse_notification.dart

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
part of flutter_parse_sdk_flutter;
22

3+
/// A class that provides a mechanism for showing system notifications in the app.
34
class ParseNotification {
45
static final ParseNotification instance = ParseNotification._internal();
56
static String keyNotificationChannelName = "parse";

packages/flutter/lib/src/push/parse_push.dart

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
part of flutter_parse_sdk_flutter;
22

3+
/// A class that provides a mechanism for handling push notifications in the app.
34
class ParsePush {
45
static final ParsePush instance = ParsePush._internal();
56

@@ -48,6 +49,7 @@ class ParsePush {
4849
_handlePush(pushId, timestamp, channel, data);
4950
}
5051

52+
/// Processes the incoming push notification message.
5153
void _handlePush(String pushId, String timestamp, String channel,
5254
Map<String, dynamic>? data) {
5355
if (pushId.isEmpty || timestamp.isEmpty) {

packages/flutter/lib/src/storage/core_store_directory_io.dart

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,13 @@ import 'package:flutter/foundation.dart';
44
import 'package:path_provider/path_provider.dart' as path_provider;
55
import 'package:path/path.dart' as path;
66

7+
/// A storage directories
78
class CoreStoreDirectory {
9+
/// Returns the library directory path for the database file on iOS, or
10+
/// the documents directory path for other platforms. If the application is
11+
/// running on iOS, this function also migrates the database file from the
12+
/// documents directory to the library directory. This is done to prevent
13+
/// issues with Parse SDK Flutter on iOS.
814
Future<String> getDatabaseDirectory() async {
915
if (defaultTargetPlatform == TargetPlatform.iOS) {
1016
await _migrateDBFileToLibraryDirectory();
@@ -15,6 +21,16 @@ class CoreStoreDirectory {
1521
return (await path_provider.getApplicationDocumentsDirectory()).path;
1622
}
1723

24+
/// Returns the database directory.
25+
Future<String> dbDirectory() async {
26+
String dbDirectory = '';
27+
dbDirectory = await CoreStoreDirectory().getDatabaseDirectory();
28+
return path.join('$dbDirectory/parse', 'parse.db');
29+
}
30+
31+
/// A migration algorithm for the internal SDK database file on iOS. This
32+
/// function moves the database file from the documents directory to the
33+
/// library directory to prevent issues with Parse SDK Flutter on iOS.
1834
/// Migrate SDK internal database file on iOS, see:
1935
/// https://github.com/parse-community/Parse-SDK-Flutter/issues/791
2036
/// TODO: Remove this migration algorithm in the future.
@@ -26,6 +42,8 @@ class CoreStoreDirectory {
2642
}
2743
}
2844

45+
/// Returns the database file from the application documents directory if it
46+
/// exists, otherwise returns null.
2947
Future<File?> _getDBFileIfExistsInAppDocDir() async {
3048
final appDocDirPath =
3149
(await path_provider.getApplicationDocumentsDirectory()).path;
@@ -45,6 +63,7 @@ class CoreStoreDirectory {
4563
return null;
4664
}
4765

66+
/// Moves the given database file to the library directory.
4867
Future<void> _moveDatabaseFileToLibraryDirectory(
4968
File databaseFileToMove,
5069
) async {
@@ -61,6 +80,7 @@ class CoreStoreDirectory {
6180
await databaseFileToMove.rename(libraryDirectoryDatabaseFilePath);
6281
}
6382

83+
/// Returns the path to the application temporary directory.
6484
Future<String> getTempDirectory() async {
6585
return (await path_provider.getTemporaryDirectory()).path;
6686
}

packages/flutter/lib/src/storage/core_store_directory_web.dart

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,11 @@
1+
/// A storage directories for web
12
class CoreStoreDirectory {
3+
/// Returns the library directory path for the database file
24
Future<String> getDatabaseDirectory() async {
35
return '';
46
}
57

8+
/// Returns the path to the application temporary directory.
69
Future<String?> getTempDirectory() async {
710
return '';
811
}
Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
part of flutter_parse_sdk_flutter;
2+
3+
/// provides database operations using Sembast
4+
class CoreStoreSembast implements sdk.CoreStoreSembastImp {
5+
CoreStoreSembast._();
6+
7+
static sdk.CoreStore? _sembastImp;
8+
9+
static Future<CoreStoreSembast> getInstance(
10+
{DatabaseFactory? factory, String? password}) async {
11+
_sembastImp ??= await sdk.CoreStoreSembastImp.getInstance(
12+
await CoreStoreDirectory().dbDirectory(),
13+
factory: factory,
14+
password: password);
15+
return CoreStoreSembast._();
16+
}
17+
18+
@override
19+
Future<bool> clear() async {
20+
await _sembastImp!.clear();
21+
return true;
22+
}
23+
24+
@override
25+
Future<bool> containsKey(String key) => _sembastImp!.containsKey(key);
26+
27+
@override
28+
Future<dynamic> get(String key) => _sembastImp!.get(key);
29+
30+
@override
31+
Future<bool?> getBool(String key) => _sembastImp!.getBool(key);
32+
33+
@override
34+
Future<double?> getDouble(String key) => _sembastImp!.getDouble(key);
35+
36+
@override
37+
Future<int?> getInt(String key) => _sembastImp!.getInt(key);
38+
39+
@override
40+
Future<String?> getString(String key) => _sembastImp!.getString(key);
41+
42+
@override
43+
Future<List<String>?> getStringList(String key) =>
44+
_sembastImp!.getStringList(key);
45+
46+
@override
47+
Future<void> remove(String key) => _sembastImp!.remove(key);
48+
49+
@override
50+
Future<void> setBool(String key, bool value) =>
51+
_sembastImp!.setBool(key, value);
52+
53+
@override
54+
Future<void> setDouble(String key, double value) =>
55+
_sembastImp!.setDouble(key, value);
56+
57+
@override
58+
Future<void> setInt(String key, int value) => _sembastImp!.setInt(key, value);
59+
60+
@override
61+
Future<void> setString(String key, String value) =>
62+
_sembastImp!.setString(key, value);
63+
64+
@override
65+
Future<void> setStringList(String key, List<String> values) =>
66+
_sembastImp!.setStringList(key, values);
67+
}

packages/flutter/lib/src/storage/core_store_sp_impl.dart renamed to packages/flutter/lib/src/storage/core_store_shared_preferences.dart

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,21 @@
11
part of flutter_parse_sdk_flutter;
22

3-
class CoreStoreSharedPrefsImp implements sdk.CoreStore {
4-
CoreStoreSharedPrefsImp._internal(this._store);
5-
6-
static CoreStoreSharedPrefsImp? _instance;
7-
8-
static Future<CoreStoreSharedPrefsImp> getInstance(
3+
/// A class that implements the `sdk.CoreStore` interface using `SharedPreferences`.
4+
class CoreStoreSharedPreferences implements sdk.CoreStore {
5+
CoreStoreSharedPreferences._internal(this._store);
6+
7+
static CoreStoreSharedPreferences? _instance;
8+
9+
/// Returns a new instance of `CoreStoreSharedPrefsImp`.
10+
///
11+
/// If no instance exists, this function creates a new instance of
12+
/// `SharedPreferences` and passes it as a parameter to the constructor of
13+
/// `CoreStoreSharedPrefsImp`.
14+
static Future<CoreStoreSharedPreferences> getInstance(
915
{SharedPreferences? store}) async {
1016
if (_instance == null) {
1117
store ??= await SharedPreferences.getInstance();
12-
_instance = CoreStoreSharedPrefsImp._internal(store);
18+
_instance = CoreStoreSharedPreferences._internal(store);
1319
}
1420

1521
return _instance!;

packages/flutter/lib/src/utils/parse_live_grid.dart

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,14 @@
11
part of flutter_parse_sdk_flutter;
22

3+
/// A widget that displays a live grid of Parse objects.
4+
///
5+
/// The `ParseLiveGridWidget` is initialized with a `query` that retrieves the
6+
/// objects to display in the grid. The `gridDelegate` is used to specify the
7+
/// layout of the grid, and the `itemBuilder` function is used to specify how
8+
/// each object in the grid should be displayed.
9+
///
10+
/// The `ParseLiveGridWidget` also provides support for error handling and
11+
/// refreshing the live list of objects.
312
class ParseLiveGridWidget<T extends sdk.ParseObject> extends StatefulWidget {
413
const ParseLiveGridWidget({
514
Key? key,

packages/flutter/lib/src/utils/parse_live_list.dart

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,23 @@
11
part of flutter_parse_sdk_flutter;
22

3+
/// The type of function that builds a child widget for a ParseLiveList element.
34
typedef ChildBuilder<T extends sdk.ParseObject> = Widget Function(
45
BuildContext context, sdk.ParseLiveListElementSnapshot<T> snapshot);
56

7+
/// The type of function that returns the stream to listen for updates from.
68
typedef StreamGetter<T extends sdk.ParseObject> = Stream<T> Function();
9+
10+
/// The type of function that returns the loaded data for a ParseLiveList element.
711
typedef DataGetter<T extends sdk.ParseObject> = T? Function();
812

13+
/// A widget that displays a live list of Parse objects.
14+
///
15+
/// The `ParseLiveListWidget` is initialized with a `query` that retrieves the
16+
/// objects to display in the list. The `childBuilder` function is used to
17+
/// specify how each object in the list should be displayed.
18+
///
19+
/// The `ParseLiveListWidget` also provides support for error handling and
20+
/// lazy loading of objects in the list.
921
class ParseLiveListWidget<T extends sdk.ParseObject> extends StatefulWidget {
1022
const ParseLiveListWidget({
1123
Key? key,
@@ -53,6 +65,7 @@ class ParseLiveListWidget<T extends sdk.ParseObject> extends StatefulWidget {
5365
@override
5466
State<ParseLiveListWidget<T>> createState() => _ParseLiveListWidgetState<T>();
5567

68+
/// The default child builder function used to display a ParseLiveList element.
5669
static Widget defaultChildBuilder<T extends sdk.ParseObject>(
5770
BuildContext context, sdk.ParseLiveListElementSnapshot<T> snapshot) {
5871
Widget child;

0 commit comments

Comments
 (0)