@vrtmrz/livesync-commonlib 0.2.0 → 0.2.1

package/dist/services/base/ControlService.js

@@ -40,7 +40,9 @@ class ControlService extends ServiceBase {
     await this.services.appLifecycleService.onSuspending();
     await this.services.settingService.onBeforeRealiseSetting();
     this.services.databaseService.localDatabase.refreshSettings();
-    await this.services.fileProcessingService.commitPendingFileEvents();
+    if (!await this.services.fileProcessingService.commitPendingFileEvents()) {
+      throw new Error("Pending local file operations could not be completed before applying settings");
+    }
     await this.services.settingService.onRealiseSetting();
     if (this.services.appLifecycleService.isSuspended()) return;
     await this.services.appLifecycleService.onResuming();
@@ -49,7 +51,8 @@ class ControlService extends ServiceBase {
   }
   async _onLiveSyncUnload() {
     this.context.events.emitEvent(EVENT_PLUGIN_UNLOADED);
-    await this.services.appLifecycleService.onBeforeUnload();
+    const prepared = await this.services.appLifecycleService.onBeforeUnload();
+    if (!prepared) this._log("Unload preparation failed; pending storage work may require recovery", LOG_LEVEL_URGENT);
     await Promise.resolve(this.services.appLifecycleService.onAppUnload());
     cancelAllPeriodicTask();
     cancelAllTasks();
@@ -64,6 +67,7 @@ class ControlService extends ServiceBase {
     this.context.events.emitEvent(EVENT_PLATFORM_UNLOADED);
     this.context.events.offAll();
     this._log(this.context.translate("moduleLiveSyncMain.logUnloadingPlugin"));
+    if (!prepared) throw new Error("Unload preparation failed");
     return;
   }
   /**

package/dist/services/base/FileProcessingService.d.ts

@@ -9,10 +9,16 @@ export declare class FileProcessingService<T extends ServiceContext = ServiceCon
      */
     readonly processFileEvent: import("../lib/HandlerUtils.js").BooleanMultipleHandlerFunction<(item: import("../../common/types.js").FileEventItem) => Promise<boolean>>;
     /**
-     * Process a file event item optionally, if any handler is registered.
+     * Dispatch a legacy optional notification, without confirming persistence.
      * i.e., hidden files synchronisation or customisation sync.
      */
     readonly processOptionalFileEvent: import("../lib/HandlerUtils.js").BooleanMultipleHandlerFunction<(path: import("../../common/types.js").FilePath) => Promise<boolean>>;
+    /**
+     * Complete optional file operations through the first applicable handler.
+     * Hosts migrate all optional providers together. Once any typed provider is
+     * registered, dispatch uses this contract exclusively.
+     */
+    readonly processOptionalFileEventWithResult?: import("../lib/HandlerUtils.js").FirstHandledFunction<(path: import("../../common/types.js").FilePath, options?: import("./IService.js").OptionalFileEventOptions) => Promise<import("../lib/HandlerUtils.js").HandlerOutcome<void, string>>>;
     /**
      * Commit any pending file events that have been queued for processing.
      */

package/dist/services/base/FileProcessingService.js

@@ -7,10 +7,18 @@ class FileProcessingService extends ServiceBase {
    */
   processFileEvent = handlers().anySuccess("processFileEvent");
   /**
-   * Process a file event item optionally, if any handler is registered.
+   * Dispatch a legacy optional notification, without confirming persistence.
    * i.e., hidden files synchronisation or customisation sync.
    */
   processOptionalFileEvent = handlers().anySuccess("processOptionalFileEvent");
+  /**
+   * Complete optional file operations through the first applicable handler.
+   * Hosts migrate all optional providers together. Once any typed provider is
+   * registered, dispatch uses this contract exclusively.
+   */
+  processOptionalFileEventWithResult = handlers().firstHandled(
+    "processOptionalFileEventWithResult"
+  );
   /**
    * Commit any pending file events that have been queued for processing.
    */

package/dist/services/base/IService.d.ts

@@ -16,7 +16,7 @@ import type { OwnedCouchDBConnection, RemoteConnectionOpenOptions } from "./Remo
 import type { ActiveReplicatorContext, ContinuousReplicationRequest, ReplicationAttemptFailure, ReplicationFailureRequest, ReplicatorProviderDefinitionMap, ReplicationOutcome, ReplicationReadinessRequirements, UnattendedOneShotRequest, UserInitiatedOneShotRequest } from "../../replication/ReplicatorProvider.js";
 import type { RemoteResourceKind, RemoteResourceMap } from "../../replication/RemoteResource.js";
 import type { CentralRemoteAdministrationRequest, CentralRemoteAdministrationResult } from "../../replication/CentralRemoteAdministration.js";
-import type { MultipleHandlerFunction } from "../lib/HandlerUtils.js";
+import type { HandlerOutcome, MultipleHandlerFunction } from "../lib/HandlerUtils.js";
 import type { VaultScanResult } from "./VaultScanResult.js";
 import type { UICommandRegistry } from "../../uiCommands.js";
 declare global {
@@ -97,9 +97,17 @@ export interface IKeyValueDBService {
     openSimpleStore<T>(kind: string): SimpleStore<T>;
     simpleStore: SimpleStore<unknown>;
 }
+/** Options for completing an admitted optional file event. */
+export interface OptionalFileEventOptions {
+    /** Resolves when a finite flush needs this event to finish without its debounce delay. */
+    whenFlushRequested?: Promise<void>;
+}
 export interface IFileProcessingService {
     processFileEvent(item: FileEventItem): Promise<boolean>;
+    /** Legacy notification contract; its boolean does not confirm persistence. */
     processOptionalFileEvent(path: FilePath): Promise<boolean>;
+    /** Complete the actual optional file operation, or explain why it is not completed. */
+    processOptionalFileEventWithResult?(path: FilePath, options?: OptionalFileEventOptions): Promise<HandlerOutcome<void, string>>;
     commitPendingFileEvents(): Promise<boolean>;
     batched: ReactiveSource<number>;
     processing: ReactiveSource<number>;

package/dist/services/base/ReplicatorService.d.ts

@@ -125,5 +125,6 @@ export declare abstract class ReplicatorService<T extends ServiceContext = Servi
         lastSyncPullSeq: number;
         lastSyncPushSeq: number;
         syncStatus: import("../../common/types.js").DatabaseConnectingStatus;
+        couchDB?: import("../../common/models/shared.definition.js").CouchDBReplicationProgress;
     }>;
 }

package/dist/services/lib/HandlerUtils.d.ts

@@ -2,6 +2,27 @@
  * A function type that can be used as a handler.
  */
 type HandlerFunc<TArg extends unknown[], TResult> = (...args: TArg) => TResult | Promise<TResult>;
+/**
+ * The outcome of a handler.
+ *
+ * A completed outcome carries a value when `TValue` is not void, and a veto
+ * carries a reason when `TVetoReason` is not void. Not-applicable outcomes
+ * always continue to the next registered handler.
+ */
+export type HandlerOutcome<TValue = void, TVetoReason = void> = {
+    kind: "not-applicable";
+} | ([TValue] extends [void] ? {
+    kind: "completed";
+} : {
+    kind: "completed";
+    value: TValue;
+}) | ([TVetoReason] extends [void] ? {
+    kind: "veto";
+} : {
+    kind: "veto";
+    value: TVetoReason;
+});
+type AnyHandlerOutcome = HandlerOutcome | HandlerOutcome<unknown, unknown>;
 /**
  * A function type that returns a boolean or a Promise of boolean.
  */
@@ -244,6 +265,29 @@ export declare class FirstResultHandler<T extends unknown[], U> extends MultiBin
      */
     invoke(...args: T): Promise<U | false>;
 }
+/**
+ * Invokes registered handlers in priority and registration order until one
+ * completes or vetoes. Each invocation uses a snapshot of registrations.
+ * Callback errors and rejections propagate unchanged, and registrations are
+ * owned by this handler.
+ */
+export declare class FirstHandledHandler<T extends unknown[], U extends AnyHandlerOutcome = HandlerOutcome> extends MultiBinder<HandlerFunc<T, U>> implements InvokableHandler<T, U | {
+    kind: "not-applicable";
+}> {
+    /**
+     * Whether at least one callback is currently registered.
+     */
+    get hasHandlers(): boolean;
+    /**
+     * Invokes handlers until one returns a completed or veto outcome.
+     * @param args The arguments to pass to the handlers.
+     * @returns The first handled outcome, or a not-applicable outcome when no handler applies.
+     * @throws Any synchronous callback error or rejected callback value, unchanged.
+     */
+    invoke(...args: T): Promise<U | {
+        kind: "not-applicable";
+    }>;
+}
 /**
  * A function type that can be used as a handler with assignable functionality.
  */
@@ -297,6 +341,11 @@ export interface MultipleHandlerFunction<TFunc extends (...args: any[]) => U | P
      */
     removeHandler: (callback: TFunc) => void;
 }
+export type FirstHandledFunction<TFunc extends (...args: any[]) => AnyHandlerOutcome | Promise<AnyHandlerOutcome>> = ((...args: Parameters<TFunc>) => Promise<Awaited<ReturnType<TFunc>> | {
+    kind: "not-applicable";
+}>) & Pick<MultipleHandlerFunction<TFunc>, "addHandler" | "removeHandler"> & {
+    readonly hasHandlers: boolean;
+};
 /**
  * A function type that can be used as a value-collecting handler with add/remove functionality.
  */
@@ -351,12 +400,16 @@ export declare function bailFirstFailureWithResultFunction<TFunc extends (...arg
 export declare function allParallelFunction<TFunc extends (...args: any[]) => Promise<boolean>>(name?: string): BooleanMultipleHandlerFunction<TFunc>;
 export declare function anySuccessFunction<TFunc extends (...args: any[]) => Promise<boolean>>(name?: string): BooleanMultipleHandlerFunction<TFunc>;
 export declare function firstResultFunction<TFunc extends (...args: any[]) => Promise<unknown>>(name?: string): MultipleHandlerFunction<TFunc>;
+export declare function firstHandledFunction<TFunc extends (...args: any[]) => AnyHandlerOutcome | Promise<AnyHandlerOutcome>>(name?: string): FirstHandledFunction<TFunc>;
 export declare function dispatchParallelFunction<TFunc extends (...args: any[]) => Promise<unknown[]>>(name?: string): CollectiveHandlerFunction<TFunc>;
 export declare function bindableFunction<TFunc extends (...args: any[]) => any>(name?: string): HandlerFunction<TFunc>;
 export declare function lazyBindableFunction<TFunc extends (...args: any[]) => any>(name?: string): LazyHandlerFunction<TFunc>;
 type FunctionKeys<T> = Extract<{
     [K in keyof T]: T[K] extends (...args: any[]) => any ? K : never;
 }[keyof T], string>;
+type FirstHandledFunctionKeys<T> = Extract<{
+    [K in keyof T]: [NonNullable<T[K]>] extends [never] ? never : NonNullable<T[K]> extends (...args: any[]) => AnyHandlerOutcome | Promise<AnyHandlerOutcome> ? K : never;
+}[keyof T], string>;
 export declare function handlers<T extends object>(): {
     /**
      * Create a handler that invokes all added handler functions sequentially until one returns false.
@@ -403,6 +456,13 @@ export declare function handlers<T extends object>(): {
      * @returns
      */
     firstResult<K extends FunctionKeys<T>>(name: K): MultipleHandlerFunction<Extract<T[K], (...args: any[]) => Promise<unknown>>>;
+    /**
+     * Create a handler that invokes registered handlers until one completes or vetoes.
+     * Callback errors and rejections propagate unchanged.
+     * @param name The name of the callback on `T`.
+     * @returns A bound handler with a live `hasHandlers` property.
+     */
+    firstHandled<K extends FirstHandledFunctionKeys<T>>(name: K): FirstHandledFunction<Extract<NonNullable<T[K]>, (...args: any[]) => AnyHandlerOutcome | Promise<AnyHandlerOutcome>>>;
     /**
      * Create a handler that invokes all added handler functions in parallel.
      * @param name

package/dist/services/lib/HandlerUtils.js

@@ -326,6 +326,30 @@ class FirstResultHandler extends MultiBinder {
     return false;
   }
 }
+class FirstHandledHandler extends MultiBinder {
+  /**
+   * Whether at least one callback is currently registered.
+   */
+  get hasHandlers() {
+    return this._callbackMap.size > 0;
+  }
+  /**
+   * Invokes handlers until one returns a completed or veto outcome.
+   * @param args The arguments to pass to the handlers.
+   * @returns The first handled outcome, or a not-applicable outcome when no handler applies.
+   * @throws Any synchronous callback error or rejected callback value, unchanged.
+   */
+  async invoke(...args) {
+    const callbacks = [...this._callbacks];
+    for (const callback of callbacks) {
+      const outcome = await Promise.resolve(callback(...args));
+      if (outcome.kind !== "not-applicable") {
+        return outcome;
+      }
+    }
+    return { kind: "not-applicable" };
+  }
+}
 function getMultipleBound(handler) {
   const _handler = "invoke" in handler ? handler.invoke : handler.dispatch;
   const __handler = _handler.bind(handler);
@@ -367,6 +391,17 @@ function firstResultFunction(name) {
   const handler = new FirstResultHandler(name ?? "firstResultFunction");
   return getMultipleBound(handler);
 }
+function firstHandledFunction(name) {
+  const handler = new FirstHandledHandler(
+    name ?? "firstHandledFunction"
+  );
+  const toHandlerCallback = (callback) => callback;
+  const bound = (...args) => handler.invoke(...args);
+  bound.addHandler = (callback, priority) => handler.addHandler(toHandlerCallback(callback), priority);
+  bound.removeHandler = (callback) => handler.removeHandler(toHandlerCallback(callback));
+  Object.defineProperty(bound, "hasHandlers", { get: () => handler.hasHandlers });
+  return bound;
+}
 function dispatchParallelFunction(name) {
   const handler = new DispatchParallel(
     name ?? "dispatchParallelFunction"
@@ -452,6 +487,15 @@ function handlers() {
     firstResult(name) {
       return firstResultFunction(String(name));
     },
+    /**
+     * Create a handler that invokes registered handlers until one completes or vetoes.
+     * Callback errors and rejections propagate unchanged.
+     * @param name The name of the callback on `T`.
+     * @returns A bound handler with a live `hasHandlers` property.
+     */
+    firstHandled(name) {
+      return firstHandledFunction(String(name));
+    },
     /**
      * Create a handler that invokes all added handler functions in parallel.
      * @param name
@@ -481,6 +525,7 @@ export {
   BooleanHandlerBase,
   Dispatch,
   DispatchParallel,
+  FirstHandledHandler,
   FirstResultHandler,
   LazyBinder,
   MultiBinder,
@@ -494,6 +539,7 @@ export {
   bailFirstFailureWithResultFunction,
   bindableFunction,
   dispatchParallelFunction,
+  firstHandledFunction,
   firstResultFunction,
   handlers,
   lazyBindableFunction