document-drive 1.0.0-alpha.90 → 1.0.0-alpha.92

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "document-drive",
-    "version": "1.0.0-alpha.90",
+    "version": "1.0.0-alpha.92",
     "license": "AGPL-3.0-only",
     "type": "module",
     "module": "./src/index.ts",
@@ -35,7 +35,7 @@
         "test:watch": "vitest watch"
     },
     "peerDependencies": {
-        "document-model": "^1.7.0",
+        "document-model": "^1.8.0",
         "document-model-libs": "^1.57.0"
     },
     "optionalDependencies": {
@@ -65,9 +65,10 @@
         "@types/uuid": "^9.0.8",
         "@typescript-eslint/eslint-plugin": "^6.21.0",
         "@typescript-eslint/parser": "^6.21.0",
+        "@vitest/browser": "^2.0.5",
         "@vitest/coverage-v8": "^2.0.5",
         "document-model": "^1.7.0",
-        "document-model-libs": "^1.70.0",
+        "document-model-libs": "^1.83.0",
         "eslint": "^8.57.0",
         "eslint-config-prettier": "^9.1.0",
         "fake-indexeddb": "^5.0.2",
@@ -80,7 +81,8 @@
         "sequelize": "^6.37.2",
         "sqlite3": "^5.1.7",
         "typescript": "^5.5.3",
-        "vitest": "^2.0.5"
+        "vitest": "^2.0.5",
+        "webdriverio": "^9.0.9"
     },
     "packageManager": "pnpm@9.1.4+sha256.30a1801ac4e723779efed13a21f4c39f9eb6c9fbb4ced101bce06b422593d7c9"
 }

package/src/index.ts

@@ -1,3 +1,4 @@
 export * from './server';
+export * from './server/error';
 export * from './storage';
 export * from './utils';

package/src/queue/base.ts

@@ -4,7 +4,7 @@ import {
 } from 'document-model-libs/document-drive';
 import { Action } from 'document-model/document';
 import { Unsubscribe, createNanoEvents } from 'nanoevents';
-import { generateUUID } from '../utils';
+import { generateUUID, runAsap } from '../utils';
 import { logger } from '../utils/logger';
 import {
     IJob,
@@ -212,10 +212,10 @@ export class BaseQueueManager implements IQueueManager {
     private retryNextJob(timeout?: number) {
         const _timeout = timeout !== undefined ? timeout : this.timeout;
         const retry =
-            _timeout === 0 && typeof setImmediate !== 'undefined'
-                ? setImmediate
-                : (fn: () => void) => setTimeout(fn, _timeout);
-        return retry(() => this.processNextJob());
+            _timeout > 0
+                ? (fn: () => void) => setTimeout(fn, _timeout)
+                : runAsap;
+        retry(() => this.processNextJob());
     }
 
     private async findFirstNonEmptyQueue(

package/src/server/error.ts

@@ -51,3 +51,12 @@ export class DriveNotFoundError extends Error {
         this.driveId = driveId;
     }
 }
+
+export class SynchronizationUnitNotFoundError extends Error {
+    syncUnitId: string;
+
+    constructor(message: string, syncUnitId: string) {
+        super(message);
+        this.syncUnitId = syncUnitId;
+    }
+}

package/src/server/index.ts

@@ -41,7 +41,13 @@ import type {
     DocumentStorage,
     IDriveStorage
 } from '../storage/types';
-import { generateUUID, isBefore, isDocumentDrive } from '../utils';
+import {
+    generateUUID,
+    isBefore,
+    isDocumentDrive,
+    RunAsap,
+    runAsapAsync
+} from '../utils';
 import { DefaultDrivesManager } from '../utils/default-drives-manager';
 import {
     attachBranch,
@@ -58,7 +64,8 @@ import { logger } from '../utils/logger';
 import {
     ConflictOperationError,
     DriveAlreadyExistsError,
-    OperationError
+    OperationError,
+    SynchronizationUnitNotFoundError
 } from './error';
 import { ListenerManager } from './listener/manager';
 import {
@@ -72,9 +79,11 @@ import {
 import {
     AddOperationOptions,
     BaseDocumentDriveServer,
+    DefaultListenerManagerOptions,
     DocumentDriveServerOptions,
     DriveEvents,
     GetDocumentOptions,
+    GetStrandsOptions,
     IOperationResult,
     ListenerState,
     RemoteDriveOptions,
@@ -111,6 +120,8 @@ export class DocumentDriveServer extends BaseDocumentDriveServer {
 
     private defaultDrivesManager: DefaultDrivesManager;
 
+    protected options: Required<DocumentDriveServerOptions>;
+
     constructor(
         documentModels: DocumentModel[],
         storage: IDriveStorage = new MemoryStorage(),
@@ -119,7 +130,27 @@ export class DocumentDriveServer extends BaseDocumentDriveServer {
         options?: DocumentDriveServerOptions
     ) {
         super();
-        this.listenerStateManager = new ListenerManager(this);
+        this.options = {
+            defaultRemoteDrives: [],
+            removeOldRemoteDrives: {
+                strategy: 'preserve-all'
+            },
+            ...options,
+            listenerManager: {
+                ...DefaultListenerManagerOptions,
+                ...options?.listenerManager
+            },
+            taskQueueMethod:
+                options?.taskQueueMethod === undefined
+                    ? RunAsap.runAsap
+                    : options.taskQueueMethod
+        };
+
+        this.listenerStateManager = new ListenerManager(
+            this,
+            undefined,
+            options?.listenerManager
+        );
         this.documentModels = documentModels;
         this.storage = storage;
         this.cache = cache;
@@ -559,6 +590,11 @@ export class DocumentDriveServer extends BaseDocumentDriveServer {
     }
 
     private async _initialize() {
+        await this.queueManager.init(this.queueDelegate, error => {
+            logger.error(`Error initializing queue manager`, error);
+            errors.push(error);
+        });
+
         try {
             await this.defaultDrivesManager.removeOldremoteDrives();
         } catch (error) {
@@ -574,11 +610,6 @@ export class DocumentDriveServer extends BaseDocumentDriveServer {
             });
         }
 
-        await this.queueManager.init(this.queueDelegate, error => {
-            logger.error(`Error initializing queue manager`, error);
-            errors.push(error);
-        });
-
         await this.defaultDrivesManager.initializeDefaultRemoteDrives();
 
         // if network connect comes back online
@@ -819,10 +850,7 @@ export class DocumentDriveServer extends BaseDocumentDriveServer {
     async getOperationData(
         driveId: string,
         syncId: string,
-        filter: {
-            since?: string | undefined;
-            fromRevision?: number | undefined;
-        },
+        filter: GetStrandsOptions,
         loadedDrive?: DocumentDriveDocument
     ): Promise<OperationUpdate[]> {
         const syncUnit =
@@ -845,6 +873,7 @@ export class DocumentDriveServer extends BaseDocumentDriveServer {
 
         const operations =
             document.operations[syncUnit.scope as OperationScope] ?? []; // TODO filter by branch also
+
         const filteredOperations = operations.filter(
             operation =>
                 Object.keys(filter).length === 0 ||
@@ -854,7 +883,11 @@ export class DocumentDriveServer extends BaseDocumentDriveServer {
                         operation.index > filter.fromRevision))
         );
 
-        return filteredOperations.map(operation => ({
+        const limitedOperations = filter.limit
+            ? filteredOperations.slice(0, filter.limit)
+            : filteredOperations;
+
+        return limitedOperations.map(operation => ({
             hash: operation.hash,
             index: operation.index,
             timestamp: operation.timestamp,
@@ -1135,6 +1168,7 @@ export class DocumentDriveServer extends BaseDocumentDriveServer {
     ) {
         const operationsApplied: Operation<A | BaseAction>[] = [];
         const signals: SignalResult[] = [];
+
         const documentStorageWithState = await this._addDocumentResultingStage(
             documentStorage,
             drive,
@@ -1192,13 +1226,19 @@ export class DocumentDriveServer extends BaseDocumentDriveServer {
                 }
 
                 try {
-                    const appliedResult = await this._performOperation(
-                        drive,
-                        documentId,
-                        document,
-                        nextOperation,
-                        skipHashValidation
-                    );
+                    // runs operation on next available tick, to avoid blocking the main thread
+                    const taskQueueMethod = this.options.taskQueueMethod;
+                    const task = () =>
+                        this._performOperation(
+                            drive,
+                            documentId,
+                            document,
+                            nextOperation,
+                            skipHashValidation
+                        );
+                    const appliedResult = await (taskQueueMethod
+                        ? runAsapAsync(task, taskQueueMethod)
+                        : task());
                     document = appliedResult.document;
                     signals.push(...appliedResult.signals);
                     operationsApplied.push(appliedResult.operation);
@@ -2304,11 +2344,15 @@ export class DocumentDriveServer extends BaseDocumentDriveServer {
         return this.listenerStateManager.getListener(driveId, listenerId);
     }
 
-    getSyncStatus(drive: string): SyncStatus {
-        const status = this.syncStatus.get(drive);
+    getSyncStatus(
+        syncUnitId: string
+    ): SyncStatus | SynchronizationUnitNotFoundError {
+        const status = this.syncStatus.get(syncUnitId);
         if (!status) {
-            logger.error(`Sync status not found for drive ${drive}`);
-            throw new Error(`Sync status not found for drive ${drive}`);
+            return new SynchronizationUnitNotFoundError(
+                `Sync status not found for syncUnitId: ${syncUnitId}`,
+                syncUnitId
+            );
         }
         return this.getCombinedSyncUnitStatus(status);
     }

package/src/server/listener/manager.ts

@@ -8,6 +8,7 @@ import { OperationError } from '../error';
 import {
     BaseListenerManager,
     ErrorStatus,
+    GetStrandsOptions,
     Listener,
     ListenerState,
     ListenerUpdate,
@@ -45,7 +46,6 @@ function debounce<T extends unknown[], R>(
         });
     };
 }
-
 export class ListenerManager extends BaseListenerManager {
     static LISTENER_UPDATE_DELAY = 250;
 
@@ -252,49 +252,51 @@ export class ListenerManager extends BaseListenerManager {
                 );
 
                 const strandUpdates: StrandUpdate[] = [];
-
                 // TODO change to push one after the other, reusing operation data
-                await Promise.all(
-                    syncUnits.map(async syncUnit => {
-                        const unitState = listener.syncUnits.get(
-                            syncUnit.syncId
-                        );
+                const tasks = syncUnits.map(syncUnit => async () => {
+                    const unitState = listener.syncUnits.get(syncUnit.syncId);
 
-                        if (
-                            unitState &&
-                            unitState.listenerRev >= syncUnit.revision
-                        ) {
-                            return;
-                        }
+                    if (
+                        unitState &&
+                        unitState.listenerRev >= syncUnit.revision
+                    ) {
+                        return;
+                    }
 
-                        const opData: OperationUpdate[] = [];
-                        try {
-                            const data = await this.drive.getOperationData(
-                                // TODO - join queries, DEAL WITH INVALID SYNC ID ERROR
-                                driveId,
-                                syncUnit.syncId,
-                                {
-                                    fromRevision: unitState?.listenerRev
-                                }
-                            );
-                            opData.push(...data);
-                        } catch (e) {
-                            logger.error(e);
-                        }
+                    const opData: OperationUpdate[] = [];
+                    try {
+                        const data = await this.drive.getOperationData(
+                            // TODO - join queries, DEAL WITH INVALID SYNC ID ERROR
+                            driveId,
+                            syncUnit.syncId,
+                            {
+                                fromRevision: unitState?.listenerRev
+                            }
+                        );
+                        opData.push(...data);
+                    } catch (e) {
+                        logger.error(e);
+                    }
 
-                        if (!opData.length) {
-                            return;
-                        }
+                    if (!opData.length) {
+                        return;
+                    }
 
-                        strandUpdates.push({
-                            driveId,
-                            documentId: syncUnit.documentId,
-                            branch: syncUnit.branch,
-                            operations: opData,
-                            scope: syncUnit.scope as OperationScope
-                        });
-                    })
-                );
+                    strandUpdates.push({
+                        driveId,
+                        documentId: syncUnit.documentId,
+                        branch: syncUnit.branch,
+                        operations: opData,
+                        scope: syncUnit.scope as OperationScope
+                    });
+                });
+                if (this.options.sequentialUpdates) {
+                    for (const task of tasks) {
+                        await task();
+                    }
+                } else {
+                    await Promise.all(tasks.map(task => task()));
+                }
 
                 if (strandUpdates.length == 0) {
                     continue;
@@ -478,7 +480,7 @@ export class ListenerManager extends BaseListenerManager {
     async getStrands(
         driveId: string,
         listenerId: string,
-        since?: string
+        options?: GetStrandsOptions
     ): Promise<StrandUpdate[]> {
         // fetch listenerState from listenerManager
         const listener = await this.getListener(driveId, listenerId);
@@ -493,46 +495,63 @@ export class ListenerManager extends BaseListenerManager {
             drive
         );
 
-        await Promise.all(
-            syncUnits.map(async syncUnit => {
-                if (syncUnit.revision < 0) {
-                    return;
-                }
-                const entry = listener.syncUnits.get(syncUnit.syncId);
-                if (entry && entry.listenerRev >= syncUnit.revision) {
-                    return;
-                }
+        const limit = options?.limit; // maximum number of operations to send across all sync units
+        let operationsCount = 0; // total amount of operations that have been retrieved
 
-                const { documentId, driveId, scope, branch } = syncUnit;
-                try {
-                    const operations = await this.drive.getOperationData(
-                        // DEAL WITH INVALID SYNC ID ERROR
-                        driveId,
-                        syncUnit.syncId,
-                        {
-                            since,
-                            fromRevision: entry?.listenerRev
-                        },
-                        drive
-                    );
+        const tasks = syncUnits.map(syncUnit => async () => {
+            if (limit && operationsCount >= limit) {
+                // break;
+                return;
+            }
+            if (syncUnit.revision < 0) {
+                return;
+            }
+            const entry = listener.syncUnits.get(syncUnit.syncId);
+            if (entry && entry.listenerRev >= syncUnit.revision) {
+                return;
+            }
 
-                    if (!operations.length) {
-                        return;
-                    }
+            const { documentId, driveId, scope, branch } = syncUnit;
+            try {
+                const operations = await this.drive.getOperationData(
+                    // DEAL WITH INVALID SYNC ID ERROR
+                    driveId,
+                    syncUnit.syncId,
+                    {
+                        since: options?.since,
+                        fromRevision:
+                            options?.fromRevision ?? entry?.listenerRev,
+                        limit: limit ? limit - operationsCount : undefined
+                    },
+                    drive
+                );
 
-                    strands.push({
-                        driveId,
-                        documentId,
-                        scope: scope as OperationScope,
-                        branch,
-                        operations
-                    });
-                } catch (error) {
-                    logger.error(error);
+                if (!operations.length) {
                     return;
                 }
-            })
-        );
+
+                operationsCount += operations.length;
+
+                strands.push({
+                    driveId,
+                    documentId,
+                    scope: scope as OperationScope,
+                    branch,
+                    operations
+                });
+            } catch (error) {
+                logger.error(error);
+                return;
+            }
+        });
+
+        if (this.options.sequentialUpdates) {
+            for (const task of tasks) {
+                await task();
+            }
+        } else {
+            await Promise.all(tasks.map(task => task()));
+        }
 
         return strands;
     }

package/src/server/listener/transmitter/pull-responder.ts

@@ -7,6 +7,7 @@ import { logger as defaultLogger } from '../../../utils/logger';
 import { OperationError } from '../../error';
 import {
     BaseDocumentDriveServer,
+    GetStrandsOptions,
     IOperationResult,
     Listener,
     ListenerRevision,
@@ -41,7 +42,7 @@ export type StrandUpdateGraphQL = Omit<StrandUpdate, 'operations'> & {
 };
 
 export interface IPullResponderTransmitter extends ITransmitter {
-    getStrands(since?: string): Promise<StrandUpdate[]>;
+    getStrands(options?: GetStrandsOptions): Promise<StrandUpdate[]>;
 }
 
 export class PullResponderTransmitter implements IPullResponderTransmitter {
@@ -59,11 +60,11 @@ export class PullResponderTransmitter implements IPullResponderTransmitter {
         this.manager = manager;
     }
 
-    getStrands(since?: string | undefined): Promise<StrandUpdate[]> {
+    getStrands(options?: GetStrandsOptions): Promise<StrandUpdate[]> {
         return this.manager.getStrands(
             this.listener.driveId,
             this.listener.listenerId,
-            since
+            options
         );
     }
 
@@ -135,7 +136,7 @@ export class PullResponderTransmitter implements IPullResponderTransmitter {
         driveId: string,
         url: string,
         listenerId: string,
-        since?: string // TODO add support for since
+        options?: GetStrandsOptions // TODO add support for since
     ): Promise<StrandUpdate[]> {
         const {
             system: {

package/src/server/types.ts

@@ -20,8 +20,9 @@ import type {
     State
 } from 'document-model/document';
 import { Unsubscribe } from 'nanoevents';
+import { RunAsap } from '../utils';
 import { DriveInfo } from '../utils/graphql';
-import { OperationError } from './error';
+import { OperationError, SynchronizationUnitNotFoundError } from './error';
 import {
     ITransmitter,
     PullResponderTrigger,
@@ -235,6 +236,18 @@ export type RemoveOldRemoteDrivesOption =
 export type DocumentDriveServerOptions = {
     defaultRemoteDrives?: Array<DefaultRemoteDriveInput>;
     removeOldRemoteDrives?: RemoveOldRemoteDrivesOption;
+    /* method to queue heavy tasks that might block the event loop.
+     * If set to null then it will queued as micro task.
+     * Defaults to the most appropriate method according to the system
+     */
+    taskQueueMethod?: RunAsap.RunAsap<unknown> | null;
+    listenerManager?: ListenerManagerOptions;
+};
+
+export type GetStrandsOptions = {
+    limit?: number;
+    since?: string;
+    fromRevision?: number;
 };
 
 export abstract class BaseDocumentDriveServer {
@@ -361,7 +374,9 @@ export abstract class BaseDocumentDriveServer {
         options?: AddOperationOptions
     ): Promise<IOperationResult<DocumentDriveDocument>>;
 
-    abstract getSyncStatus(drive: string): SyncStatus;
+    abstract getSyncStatus(
+        syncUnitId: string
+    ): SyncStatus | SynchronizationUnitNotFoundError;
 
     /** Synchronization methods */
     abstract getSynchronizationUnits(
@@ -390,10 +405,7 @@ export abstract class BaseDocumentDriveServer {
     abstract getOperationData(
         driveId: string,
         syncId: string,
-        filter: {
-            since?: string;
-            fromRevision?: number;
-        },
+        filter: GetStrandsOptions,
         loadedDrive?: DocumentDriveDocument
     ): Promise<OperationUpdate[]>;
 
@@ -430,8 +442,17 @@ export abstract class BaseDocumentDriveServer {
     ): Promise<PullResponderTrigger>;
 }
 
+export type ListenerManagerOptions = {
+    sequentialUpdates?: boolean;
+};
+
+export const DefaultListenerManagerOptions = {
+    sequentialUpdates: true
+};
+
 export abstract class BaseListenerManager {
     protected drive: BaseDocumentDriveServer;
+    protected options: ListenerManagerOptions;
     protected listenerState = new Map<string, Map<string, ListenerState>>();
     protected transmitters: Record<
         DocumentDriveState['id'],
@@ -440,10 +461,12 @@ export abstract class BaseListenerManager {
 
     constructor(
         drive: BaseDocumentDriveServer,
-        listenerState = new Map<string, Map<string, ListenerState>>()
+        listenerState = new Map<string, Map<string, ListenerState>>(),
+        options: ListenerManagerOptions = DefaultListenerManagerOptions
     ) {
         this.drive = drive;
         this.listenerState = listenerState;
+        this.options = { ...DefaultListenerManagerOptions, ...options };
     }
 
     abstract initDrive(drive: DocumentDriveDocument): Promise<void>;
@@ -466,8 +489,9 @@ export abstract class BaseListenerManager {
     ): Promise<ITransmitter | undefined>;
 
     abstract getStrands(
+        driveId: string,
         listenerId: string,
-        since?: string
+        options?: GetStrandsOptions
     ): Promise<StrandUpdate[]>;
 
     abstract updateSynchronizationRevisions(

package/src/utils/index.ts

@@ -10,9 +10,15 @@ import {
     Operation,
     OperationScope
 } from 'document-model/document';
+// import setAsap from 'setasap';
 import { v4 as uuidv4 } from 'uuid';
 import { OperationError } from '../server/error';
 import { DocumentDriveStorage, DocumentStorage } from '../storage';
+import { RunAsap } from './run-asap';
+export * from './run-asap';
+
+export const runAsap = RunAsap.runAsap;
+export const runAsapAsync = RunAsap.runAsapAsync;
 
 export function isDocumentDriveStorage(
     document: DocumentStorage

package/src/utils/run-asap.ts

@@ -0,0 +1,159 @@
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace RunAsap {
+    export type Task<T = void> = () => T;
+    export type AbortTask = () => void;
+    export type RunAsap<T> = (task: Task<T>) => AbortTask;
+
+    export const useMessageChannel = (() => {
+        if (typeof MessageChannel === 'undefined') {
+            return new Error('MessageChannel is not supported');
+        }
+
+        return (task: Task) => {
+            const controller = new AbortController();
+            const signal = controller.signal;
+            const mc = new MessageChannel();
+            mc.port1.postMessage(null);
+            mc.port2.addEventListener(
+                'message',
+                () => {
+                    task();
+                    mc.port1.close();
+                    mc.port2.close();
+                },
+                { once: true, signal: signal }
+            );
+            mc.port2.start();
+            return () => controller.abort();
+        };
+    })();
+
+    export const usePostMessage = (() => {
+        const _main: unknown =
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            (typeof window === 'object' && window) ||
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            (typeof global === 'object' && global) ||
+            (typeof self === 'object' && self);
+        if (!_main) {
+            return new Error('No global object found');
+        }
+
+        const main = _main as Window;
+        if (
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            !main.postMessage ||
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            !main.addEventListener ||
+            (main as { importScripts?: unknown }).importScripts // web workers can't this method
+        ) {
+            return new Error('postMessage is not supported');
+        }
+
+        let index = 0;
+        const tasks = new Map<number, Task>();
+
+        function getNewIndex() {
+            if (index === 9007199254740991) {
+                return 0;
+            }
+            return ++index;
+        }
+
+        const MESSAGE_PREFIX = 'com.usePostMessage' + Math.random();
+
+        main.addEventListener(
+            'message',
+            e => {
+                const event = e as MessageEvent<string>;
+                if (typeof event.data !== 'string') {
+                    return;
+                }
+                if (
+                    event.source !== main ||
+                    !event.data.startsWith(MESSAGE_PREFIX)
+                ) {
+                    return;
+                }
+                const index = event.data.split(':').at(1);
+                if (index === undefined) {
+                    return;
+                }
+                const i = +index;
+                const task = tasks.get(i);
+                if (task) {
+                    task();
+                    tasks.delete(i);
+                }
+            },
+            false
+        );
+
+        return (task: Task) => {
+            const i = getNewIndex();
+            tasks.set(i, task);
+            main.postMessage(MESSAGE_PREFIX + ':' + i, { targetOrigin: '*' });
+            return () => {
+                tasks.delete(i);
+            };
+        };
+    })();
+
+    export const useSetImmediate = (() => {
+        if (typeof window !== 'undefined') {
+            return new Error('setImmediate is not supported on the browser');
+        }
+        if (typeof setImmediate === 'undefined') {
+            return new Error('setImmediate is not supported');
+        }
+
+        return (task: Task) => {
+            const id = setImmediate(task);
+            return () => clearImmediate(id);
+        };
+    })();
+
+    export const useSetTimeout = (() => {
+        return (task: Task) => {
+            const id = setTimeout(task, 0);
+            return () => clearTimeout(id);
+        };
+    })();
+
+    // queues the task in the macro tasks queue, so it doesn't
+    // prevent the event loop from movin on the next tick
+    export function runAsap<T = void>(task: Task<T>): AbortTask {
+        // if on node use setImmediate
+        if (!(useSetImmediate instanceof Error)) {
+            return useSetImmediate(task);
+        }
+        // on browser use MessageChannel if available
+        else if (!(useMessageChannel instanceof Error)) {
+            return useMessageChannel(task);
+        }
+        // otherwise use window.postMessage
+        else if (!(usePostMessage instanceof Error)) {
+            return usePostMessage(task);
+        }
+        // fallback to setTimeout with 0 delay
+        else {
+            return useSetTimeout(task);
+        }
+    }
+
+    export function runAsapAsync<T = void>(
+        task: RunAsap.Task<Promise<T>>,
+        queueMethod: RunAsap<void> = runAsap
+    ): Promise<T> {
+        if (queueMethod instanceof Error) {
+            throw new Error('queueMethod is not supported', {
+                cause: queueMethod
+            });
+        }
+        return new Promise((resolve, reject) => {
+            queueMethod(() => {
+                task().then(resolve).catch(reject);
+            });
+        });
+    }
+}