mirror of https://github.com/AMT-Cheif/drift.git
Add dartdoc comments
This commit is contained in:
parent
0b52bee48c
commit
0c6cd109ee
|
@ -79,14 +79,22 @@ Future<bool> checkIndexedDbSupport() async {
|
||||||
return true;
|
return true;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Constructs the path used by drift to store a database in the origin-private
|
||||||
|
/// section of the agent's file system.
|
||||||
String pathForOpfs(String databaseName) {
|
String pathForOpfs(String databaseName) {
|
||||||
return 'drift_db/$databaseName';
|
return 'drift_db/$databaseName';
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Manages drift servers.
|
||||||
|
///
|
||||||
|
/// When using a shared worker, multiple clients may want to use different drift
|
||||||
|
/// databases. This server keeps track of drift servers by their database names
|
||||||
|
/// to allow that.
|
||||||
class DriftServerController {
|
class DriftServerController {
|
||||||
/// Running drift servers by the name of the database they're serving.
|
/// Running drift servers by the name of the database they're serving.
|
||||||
final Map<String, DriftServer> _servers = {};
|
final Map<String, DriftServer> _servers = {};
|
||||||
|
|
||||||
|
/// Serves a drift connection as requested by the [message].
|
||||||
void serve(ServeDriftDatabase message) {
|
void serve(ServeDriftDatabase message) {
|
||||||
final server = _servers.putIfAbsent(message.databaseName, () {
|
final server = _servers.putIfAbsent(message.databaseName, () {
|
||||||
return DriftServer(LazyDatabase(() async {
|
return DriftServer(LazyDatabase(() async {
|
||||||
|
|
|
@ -3,7 +3,6 @@ import 'dart:async';
|
||||||
import 'dart:html';
|
import 'dart:html';
|
||||||
|
|
||||||
import 'package:drift/wasm.dart';
|
import 'package:drift/wasm.dart';
|
||||||
import 'package:js/js.dart';
|
|
||||||
import 'package:js/js_util.dart';
|
import 'package:js/js_util.dart';
|
||||||
|
|
||||||
import '../wasm_setup.dart';
|
import '../wasm_setup.dart';
|
||||||
|
|
|
@ -71,6 +71,7 @@ class WasmDatabase extends DelegatedDatabase {
|
||||||
_WasmDelegate(sqlite3, null, setup, null), logStatements);
|
_WasmDelegate(sqlite3, null, setup, null), logStatements);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// For an in-depth
|
||||||
static Future<WasmDatabaseResult> open({
|
static Future<WasmDatabaseResult> open({
|
||||||
required String databaseName,
|
required String databaseName,
|
||||||
required Uri sqlite3Uri,
|
required Uri sqlite3Uri,
|
||||||
|
@ -83,6 +84,15 @@ class WasmDatabase extends DelegatedDatabase {
|
||||||
).open();
|
).open();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// The entrypoint for a web worker suitable for use with [open].
|
||||||
|
///
|
||||||
|
/// Generally, you can grab a pre-compiled worker file from a
|
||||||
|
/// [drift release](https://github.com/simolus3/drift/releases) and don't need
|
||||||
|
/// to call this method in your app.
|
||||||
|
///
|
||||||
|
/// If you prefer to compile the worker yourself, write a simple Dart program
|
||||||
|
/// that calls this method in its `main()` function and compile that with
|
||||||
|
/// `dart2js`.
|
||||||
static void workerMainForOpen() {
|
static void workerMainForOpen() {
|
||||||
final self = WorkerGlobalScope.instance;
|
final self = WorkerGlobalScope.instance;
|
||||||
|
|
||||||
|
@ -216,12 +226,14 @@ enum WasmStorageImplementation {
|
||||||
/// [cross-origin isolation]: https://developer.mozilla.org/en-US/docs/Web/API/crossOriginIsolated
|
/// [cross-origin isolation]: https://developer.mozilla.org/en-US/docs/Web/API/crossOriginIsolated
|
||||||
opfsLocks,
|
opfsLocks,
|
||||||
|
|
||||||
|
/// Emulates a file system over `IndexedDB` in a shared worker.
|
||||||
sharedIndexedDb,
|
sharedIndexedDb,
|
||||||
|
|
||||||
/// Uses the asynchronous IndexedDB API outside of any worker to persist data.
|
/// Uses the asynchronous IndexedDB API outside of any worker to persist data.
|
||||||
///
|
///
|
||||||
/// Unlike [opfsShared] or [opfsLocks], this storage implementation can't
|
/// Unlike [opfsShared], [opfsLocks] or [sharedIndexedDb], this storage
|
||||||
/// prevent two tabs from accessing the same data.
|
/// implementation can't prevent data races if your app is opened in multiple
|
||||||
|
/// tabs at the same time, which is why it's declared as as unsafe.
|
||||||
unsafeIndexedDb,
|
unsafeIndexedDb,
|
||||||
|
|
||||||
/// A fallback storage implementation that doesn't store anything.
|
/// A fallback storage implementation that doesn't store anything.
|
||||||
|
@ -232,22 +244,67 @@ enum WasmStorageImplementation {
|
||||||
inMemory,
|
inMemory,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// An enumeration of features not supported by the current browsers.
|
||||||
|
///
|
||||||
|
/// While this information may not be useful to end users, it can be used to
|
||||||
|
/// understand why drift has chosen a particular storage implementation in
|
||||||
|
/// [WasmDatabaseResult].
|
||||||
enum MissingBrowserFeature {
|
enum MissingBrowserFeature {
|
||||||
|
/// The browser is missing support for [shared workers].
|
||||||
|
///
|
||||||
|
/// [shared workers]: https://developer.mozilla.org/en-US/docs/Web/API/SharedWorker
|
||||||
sharedWorkers,
|
sharedWorkers,
|
||||||
|
|
||||||
|
/// The browser is missing support for [web workers] in general.
|
||||||
|
///
|
||||||
|
/// [web workers]: https://developer.mozilla.org/en-US/docs/Web/API/Worker
|
||||||
dedicatedWorkers,
|
dedicatedWorkers,
|
||||||
|
|
||||||
|
/// The browser doesn't allow shared workers to spawn dedicated workers in
|
||||||
|
/// their context.
|
||||||
|
///
|
||||||
|
/// While the specification for web workers explicitly allows this, this
|
||||||
|
/// feature is only implemented by Firefox at the time of writing.
|
||||||
dedicatedWorkersInSharedWorkers,
|
dedicatedWorkersInSharedWorkers,
|
||||||
nestedDedicatedWorkers,
|
|
||||||
|
/// The browser does not support a synchronous version of the [File System API]
|
||||||
|
///
|
||||||
|
/// [File System API]: https://developer.mozilla.org/en-US/docs/Web/API/File_System_Access_API
|
||||||
fileSystemAccess,
|
fileSystemAccess,
|
||||||
|
|
||||||
|
/// The browser does not support IndexedDB.
|
||||||
indexedDb,
|
indexedDb,
|
||||||
|
|
||||||
|
/// The browser does not support shared array buffers and `Atomics.wait`.
|
||||||
|
///
|
||||||
|
/// To enable this feature in most browsers, you need to serve your app with
|
||||||
|
/// two [special headers](https://web.dev/coop-coep/).
|
||||||
sharedArrayBuffers,
|
sharedArrayBuffers,
|
||||||
notCrossOriginIsolated,
|
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// The result of opening a WASM database.
|
||||||
class WasmDatabaseResult {
|
class WasmDatabaseResult {
|
||||||
|
/// The drift database connection to pass to the [GeneratedDatabase.new]
|
||||||
|
/// constructor of your database class to use the opened database.
|
||||||
final DatabaseConnection resolvedExecutor;
|
final DatabaseConnection resolvedExecutor;
|
||||||
|
|
||||||
|
/// For your reference, the chosen storage implementation.
|
||||||
|
///
|
||||||
|
/// Depending on the features available in the browser your app runs on, drift
|
||||||
|
/// will use the most reliable implementation in [WasmStorageImplementation].
|
||||||
|
///
|
||||||
|
/// If the implementation can't store data reliably ([WasmStorageImplementation.unsafeIndexedDb])
|
||||||
|
/// or not at all ([WasmStorageImplementation.inMemory]), you may want to show
|
||||||
|
/// a warning to the user if persistence is important in your app.
|
||||||
final WasmStorageImplementation chosenImplementation;
|
final WasmStorageImplementation chosenImplementation;
|
||||||
|
|
||||||
|
/// An enumeration of missing browser features probed by drift.
|
||||||
|
///
|
||||||
|
/// The lack of support of features listed here contributed to the
|
||||||
|
/// [chosenImplementation] for the virtual file system used to store databases.
|
||||||
final Set<MissingBrowserFeature> missingFeatures;
|
final Set<MissingBrowserFeature> missingFeatures;
|
||||||
|
|
||||||
WasmDatabaseResult(
|
/// Default constructor from the invidiual fields.
|
||||||
|
const WasmDatabaseResult(
|
||||||
this.resolvedExecutor, this.chosenImplementation, this.missingFeatures);
|
this.resolvedExecutor, this.chosenImplementation, this.missingFeatures);
|
||||||
}
|
}
|
||||||
|
|
Loading…
Reference in New Issue