@openmrs/esm-offline 3.1.15-pre.892 → 3.2.1-pre.1012

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-offline",
-  "version": "3.1.15-pre.892",
+  "version": "3.2.1-pre.1012",
   "license": "MPL-2.0",
   "description": "Helper utilities for OpenMRS",
   "browser": "dist/openmrs-esm-offline.js",
@@ -36,10 +36,10 @@
     "access": "public"
   },
   "devDependencies": {
-    "@openmrs/esm-api": "^3.1.15-pre.892",
-    "@openmrs/esm-globals": "^3.1.15-pre.892",
-    "@openmrs/esm-state": "^3.1.15-pre.892",
-    "@openmrs/esm-styleguide": "^3.1.15-pre.892",
+    "@openmrs/esm-api": "^3.2.1-pre.1012",
+    "@openmrs/esm-globals": "^3.2.1-pre.1012",
+    "@openmrs/esm-state": "^3.2.1-pre.1012",
+    "@openmrs/esm-styleguide": "^3.2.1-pre.1012",
     "@types/uuid": "^8.3.0",
     "rxjs": "^6.5.3"
   },
@@ -56,5 +56,5 @@
     "uuid": "^8.3.2",
     "workbox-window": "^6.1.5"
   },
-  "gitHead": "bb0cbb2387f66d9b5b8470e87284b7c7e3d612ac"
+  "gitHead": "96acf2eb0cf6d8d83d7ce12280bbf445c34c5672"
 }

package/src/index.ts

@@ -3,6 +3,7 @@ export * from "./service-worker-http-headers";
 export * from "./service-worker-messaging";
 export * from "./service-worker-events";
 export * from "./events";
+export * from "./mode";
 export * from "./patches";
 export * from "./sync";
 export * from "./uuid";

package/src/mode.ts

@@ -0,0 +1,79 @@
+async function isSafariPrivateBrowsing() {
+  const storage = window.sessionStorage;
+
+  try {
+    storage.setItem("someKeyHere", "test");
+    storage.removeItem("someKeyHere");
+  } catch (e) {
+    if (e.code === DOMException.QUOTA_EXCEEDED_ERR && storage.length === 0) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+async function isEdgePrivateBrowsing() {
+  return !window.indexedDB;
+}
+
+async function isFirefoxPrivateBrowsing() {
+  return new Promise<boolean>((resolve) => {
+    const db = indexedDB.open("test");
+    db.onerror = () => resolve(true);
+    db.onsuccess = () => resolve(false);
+  });
+}
+
+async function isPrivateBrowsing() {
+  return (
+    (await isFirefoxPrivateBrowsing()) ||
+    (await isEdgePrivateBrowsing()) ||
+    (await isSafariPrivateBrowsing())
+  );
+}
+
+export type OfflineMode = "on" | "off" | "unavailable";
+
+export interface OfflineModeResult {
+  current: OfflineMode;
+  notAvailable: boolean;
+  active: boolean;
+}
+
+const offlineModeStorageKey = "openmrs3:offline-mode";
+let offlineMode: OfflineMode = "unavailable";
+
+export function getCurrentOfflineMode(): OfflineModeResult {
+  return {
+    current: offlineMode,
+    notAvailable: offlineMode === "unavailable",
+    active: offlineMode === "on",
+  };
+}
+
+export function setCurrentOfflineMode(mode: OfflineMode) {
+  if (offlineMode !== "unavailable" && mode !== "unavailable") {
+    localStorage.setItem(
+      offlineModeStorageKey,
+      mode === "on" ? "active" : "disabled"
+    );
+    offlineMode = mode;
+  }
+}
+
+export async function activateOfflineCapability() {
+  const isPrivate = await isPrivateBrowsing();
+
+  if (!isPrivate) {
+    if (localStorage.getItem(offlineModeStorageKey) === "active") {
+      offlineMode = "on";
+    } else {
+      offlineMode = "off";
+    }
+  }
+
+  if (navigator.onLine && offlineMode === "on") {
+    //TODO trigger here --> update cycle
+  }
+}

package/src/sync.ts

@@ -2,11 +2,16 @@ import Dexie, { Table } from "dexie";
 import { getLoggedInUser } from "@openmrs/esm-api";
 import { createGlobalStore } from "@openmrs/esm-state";
 
-export interface SyncItem {
+/**
+ * Defines an item queued up in the offline synchronization queue.
+ * A `SyncItem` contains both meta information about the item in the sync queue, as well as the
+ * actual data to be synchronized (i.e. the item's `content`).
+ */
+export interface SyncItem<T = any> {
   id?: number;
   userId: string;
   type: string;
-  content: any;
+  content: T;
   createdOn: Date;
   descriptor: QueueItemDescriptor;
   lastError?: {
@@ -15,6 +20,12 @@ export interface SyncItem {
   };
 }
 
+/**
+ * Contains information about the sync item which has been provided externally by the caller
+ * who added the item to the queue.
+ * This information is all optional, but, when provided while enqueuing the item, can be used in other
+ * locations to better represent the sync item, e.g. in the UI.
+ */
 export interface QueueItemDescriptor {
   id?: string;
   dependencies?: Array<{
@@ -25,19 +36,69 @@ export interface QueueItemDescriptor {
   displayName?: string;
 }
 
+/**
+ * A function which, when invoked, performs the actual client-server synchronization of the given
+ * `item` (which is the actual data to be synchronized).
+ * The function receives additional `options` which provide additional data that can be used
+ * for synchronizing.
+ */
 export type ProcessSyncItem<T> = (
   item: T,
   options: SyncProcessOptions<T>
 ) => Promise<any>;
 
-interface SyncResultBag {
-  [type: string]: Record<string, any>;
+/**
+ * Additional data which can be used for synchronizing data in a {@link ProcessSyncItem} function.
+ */
+export interface SyncProcessOptions<T> {
+  abort: AbortController;
+  userId: string;
+  index: number;
+  items: Array<T>;
+  dependencies: Array<any>;
 }
 
+/**
+ * Defines additional options which can optionally be provided when setting up a synchronization callback
+ * for a specific synchronization item type.
+ * These are not required, but, when set, allow further
+ */
+interface SetupOfflineSyncOptions<T> {
+  /**
+   * Invoked when the user requests to edit a sync item.
+   * The typical behavior for such a callback is to launch a UI which allows editing the content
+   * encapsulated by the sync item.
+   * @param syncItem The sync item to be edited.
+   */
+  onBeginEditSyncItem?(syncItem: SyncItem<T>): void;
+}
+
+/**
+ * Represents a synchronization handler which has been globally registered by the
+ * {@link setupOfflineSync} function.
+ * These handlers are used for synchronizing queued data.
+ */
 interface SyncHandler {
-  type: string;
-  dependsOn: Array<string>;
-  process: ProcessSyncItem<unknown>;
+  readonly type: string;
+  readonly dependsOn: ReadonlyArray<string>;
+  readonly process: ProcessSyncItem<unknown>;
+  readonly options: Readonly<SetupOfflineSyncOptions<any>>;
+}
+
+/**
+ * Represents the data inside the global offline synchronization store.
+ * Provides information about a currently ongoing synchronization.
+ */
+export interface OfflineSynchronizationStore {
+  synchronization?: {
+    totalCount: number;
+    pendingCount: number;
+    abortController: AbortController;
+  };
+}
+
+interface SyncResultBag {
+  [type: string]: Record<string, any>;
 }
 
 class OfflineDb extends Dexie {
@@ -64,14 +125,6 @@ export function getOfflineDb() {
   return db;
 }
 
-export interface OfflineSynchronizationStore {
-  synchronization?: {
-    totalCount: number;
-    pendingCount: number;
-    abortController: AbortController;
-  };
-}
-
 const syncStore = createGlobalStore<OfflineSynchronizationStore>(
   "offline-synchronization",
   {}
@@ -81,6 +134,9 @@ export function getOfflineSynchronizationStore() {
   return syncStore;
 }
 
+/**
+ * Runs a full synchronization of **all** queued synchronization items.
+ */
 export async function runSynchronization() {
   if (syncStore.getState().synchronization) {
     return;
@@ -192,6 +248,13 @@ async function getUserId() {
   return user?.uuid || "*";
 }
 
+/**
+ * Enqueues a new item in the sync queue for a specific user.
+ * @param userId The user with whom the sync item should be associated with.
+ * @param type The identifying type of the synchronization item.
+ * @param content The actual data to be synchronized.
+ * @param descriptor An optional descriptor providing additional metadata about the sync item.
+ */
 export async function queueSynchronizationItemFor<T>(
   userId: string,
   type: string,
@@ -220,6 +283,12 @@ export async function queueSynchronizationItemFor<T>(
   return id;
 }
 
+/**
+ * Enqueues a new item in the sync queue and associates the item with the currently signed in user.
+ * @param type The identifying type of the synchronization item.
+ * @param content The actual data to be synchronized.
+ * @param descriptor An optional descriptor providing additional metadata about the sync item.
+ */
 export async function queueSynchronizationItem<T>(
   type: string,
   content: T,
@@ -229,6 +298,11 @@ export async function queueSynchronizationItem<T>(
   return await queueSynchronizationItemFor(userId, type, content, descriptor);
 }
 
+/**
+ * Returns all currently queued up sync items of a given user.
+ * @param userId The ID of the user whose synchronization items should be returned.
+ * @param type The identifying type of the synchronization items to be returned..
+ */
 export async function getSynchronizationItemsFor<T>(
   userId: string,
   type: string
@@ -243,31 +317,85 @@ export async function getSynchronizationItemsFor<T>(
   return items;
 }
 
+/**
+ * Returns all currently queued up sync items of the currently signed in user.
+ * @param type The identifying type of the synchronization items to be returned.
+ */
 export async function getSynchronizationItems<T>(type: string) {
   const userId = await getUserId();
   return await getSynchronizationItemsFor<T>(userId, type);
 }
 
-export async function deleteSynchronizationItem(id: number) {
-  await db.syncQueue.delete(id);
+/**
+ * Returns a queued sync item with the given ID or `undefined` if no such item exists.
+ * @param id The ID of the requested sync item.
+ */
+export async function getSynchronizationItem<T = any>(
+  id: number
+): Promise<SyncItem<T> | undefined> {
+  return await db.syncQueue.get(id);
 }
 
-export interface SyncProcessOptions<T> {
-  abort: AbortController;
-  userId: string;
-  index: number;
-  items: Array<T>;
-  dependencies: Array<any>;
+/**
+ * Returns whether editing synchronization items of the given type is supported by the currently
+ * registered synchronization handlers.
+ * @param type The identifying type of the synchronization item which should be edited.
+ */
+export function canBeginEditSynchronizationItemsOfType(type: string) {
+  // Editing an item can be requested as long as callback for this flow exists on the associated handler.
+  return !!handlers[type]?.options.onBeginEditSyncItem;
+}
+
+/**
+ * Triggers an edit flow for the given synchronization item.
+ * If this is not possible, throws an error.
+ * @param id The ID of the synchronization item to be edited.
+ */
+export async function beginEditSynchronizationItem(id: number) {
+  const item = await getSynchronizationItem(id);
+  if (!item) {
+    throw new Error(`No sync item with the ID ${id} exists.`);
+  }
+
+  const editCallback = handlers[item.type]?.options.onBeginEditSyncItem;
+  if (!editCallback) {
+    throw new Error(
+      `A sync item with the ID ${id} exists, but the associated handler (if one exists) doesn't support editing the item. You can avoid this error by either verifying that sync items of this type can be edited via the "canEditSynchronizationItemsOfType(type: string)" function or alternatively ensure that the synchronizaton handler for sync items of type "${item.type}" supports editing items.`
+    );
+  }
+
+  editCallback(item);
+}
+
+/**
+ * Deletes a queued up sync item with the given ID.
+ * @param id The ID of the synchronization item to be deleted.
+ */
+export async function deleteSynchronizationItem(id: number) {
+  await db.syncQueue.delete(id);
 }
 
+/**
+ * Registers a new synchronization handler which is able to synchronize data of a specific type.
+ * @param type The identifying type of the synchronization items which can be handled by this handler.
+ * @param dependsOn An array of other sync item types which must be synchronized before this handler
+ *   can synchronize its own data. Items of these types are effectively dependencies of the data
+ *   synchronized by this handler.
+ * @param process A function which, when invoked, performs the actual client-server synchronization of the given
+ *   `item` (which is the actual data to be synchronized).
+ * @param options Additional options which can optionally be provided when setting up a synchronization callback
+ *   for a specific synchronization item type.
+ */
 export function setupOfflineSync<T>(
   type: string,
   dependsOn: Array<string>,
-  process: ProcessSyncItem<T>
+  process: ProcessSyncItem<T>,
+  options: SetupOfflineSyncOptions<T> = {}
 ) {
   handlers[type] = {
     type,
     dependsOn,
     process,
+    options,
   };
 }