@vrtmrz/livesync-commonlib 0.1.0-rc.0

package/dist/services/lib/HandlerUtils.js

@@ -0,0 +1,412 @@
+import { promiseWithResolvers } from "octagonal-wheels/promises";
+import { LOG_LEVEL_VERBOSE, Logger } from "../../common/logger.js";
+class Binder {
+  _name;
+  /**
+   * Creates a new Binder instance.
+   * @param name  The name of the handler.
+   * @param initialCallback An optional initial callback function to assign.
+   */
+  constructor(name, initialCallback) {
+    this._name = name;
+    if (initialCallback) {
+      this._callback = initialCallback;
+    }
+  }
+  _callback = null;
+  /**
+   * Assigns a new handler function.
+   * @param callback The new handler function to assign.
+   */
+  assign(callback, override = false) {
+    if (this._callback && !override) {
+      throw new Error(`Handler ${this._name} is already assigned.`);
+    }
+    this._callback = callback;
+    return () => {
+      this._callback = null;
+    };
+  }
+  /**
+   * Invokes the assigned handler function with the provided arguments.
+   * @param args  The arguments to pass to the handler function.
+   * @returns The result of the handler function.
+   */
+  invoke(...args) {
+    if (this._callback) {
+      return this._callback(...args);
+    }
+    throw new Error(`Handler ${this._name} is not assigned.`);
+  }
+}
+class LazyBinder {
+  _name;
+  _callbackPromise = promiseWithResolvers();
+  _callback = null;
+  /**
+   * Creates a new LazyBinder instance.
+   * @param name  The name of the handler.
+   * @param initialCallback An optional initial callback function to assign.
+   */
+  constructor(name, initialCallback) {
+    this._name = name;
+    if (initialCallback) {
+      this._callback = initialCallback;
+      this._callbackPromise.resolve();
+    }
+  }
+  assign(callback, override = false) {
+    if (this._callback && !override) {
+      throw new Error(`Handler ${this._name} is already assigned.`);
+    }
+    this._callback = callback;
+    this._callbackPromise.resolve();
+    return () => {
+      this._callback = null;
+      this._callbackPromise = promiseWithResolvers();
+    };
+  }
+  /**
+   * Invokes the assigned handler function with the provided arguments.
+   * @param args The arguments to pass to the handler function.
+   * @returns The result of the handler function.
+   */
+  async invoke(...args) {
+    await this._callbackPromise.promise;
+    if (this._callback) {
+      return await this._callback(...args);
+    }
+    throw new Error(`Handler ${this._name} is not assigned.`);
+  }
+}
+class MultiBinder {
+  _name;
+  /**
+   * Creates a new MultiBinder instance.
+   * @param name  The name of the handler.
+   */
+  constructor(name) {
+    this._name = name;
+  }
+  _callbackMap = /* @__PURE__ */ new Map();
+  _isCallbackDirty = false;
+  _maxUsedPriority = 0;
+  /**
+   * Adds a handler function.
+   * Note: The same function is only added once.
+   * @param callback The handler function to add.
+   * @param priority The priority of the handler, Do not use floating numbers to prevent confusion.
+   * @returns A function to unregister the added handler.
+   *
+   */
+  addHandler(callback, priority = 0, allowSwap = false) {
+    this._callbackMap.set(callback, [priority, this._maxUsedPriority++]);
+    this._isCallbackDirty = true;
+    const unregister = () => {
+      this.removeHandler(callback);
+      this._isCallbackDirty = true;
+    };
+    return unregister;
+  }
+  /**
+   * Removes a handler function.
+   * @param callback The handler function to remove.
+   */
+  removeHandler(callback) {
+    this._callbackMap.delete(callback);
+    this._isCallbackDirty = true;
+  }
+  /**
+   * Adds a handler function (alias of addHandler, but more semantic).
+   * @param callback
+   * @returns
+   */
+  use(callback, priority = 0) {
+    return this.addHandler(callback, priority);
+  }
+  _sortedCallbacks = [];
+  get _callbacks() {
+    if (this._isCallbackDirty) {
+      this._sortedCallbacks = Array.from(this._callbackMap.entries()).sort((a, b) => {
+        const [priorityA, registerOrderA] = a[1];
+        const [priorityB, registerOrderB] = b[1];
+        if (priorityA !== priorityB) {
+          return priorityA - priorityB;
+        }
+        return registerOrderA - registerOrderB;
+      }).map((entry) => entry[0]);
+      this._isCallbackDirty = false;
+    }
+    return this._sortedCallbacks;
+  }
+}
+class Dispatch extends MultiBinder {
+  /**
+   * Dispatches the event to all registered handlers sequentially.
+   * @param args The arguments to pass to the handlers.
+   * @returns An array of results or errors from each handler.
+   */
+  async dispatch(...args) {
+    const results = [];
+    const _callbacks = [...this._callbacks];
+    for (const callback of _callbacks) {
+      try {
+        const result = await Promise.resolve(callback(...args));
+        results.push(result);
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        results.push(err);
+      }
+    }
+    return results;
+  }
+}
+class DispatchParallel extends MultiBinder {
+  /**
+   * Dispatches the event to all registered handlers in parallel.
+   * @param args The arguments to pass to the handlers.
+   * @returns An array of results or errors from each handler.
+   */
+  dispatch(...args) {
+    const callbacks = [...this._callbacks];
+    const promises = callbacks.map(async (callback) => {
+      try {
+        const result = await Promise.resolve(callback(...args));
+        return result;
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        return err;
+      }
+    });
+    const results = Promise.all(promises);
+    return results;
+  }
+}
+class BooleanHandlerBase extends MultiBinder {
+}
+class AllHandler extends BooleanHandlerBase {
+  /**
+   * Invoke all handlers sequentially until one returns false.
+   * @param args The arguments to pass to the handlers.
+   * @returns A Promise that resolves to true if all handlers return true, otherwise false.
+   */
+  async invoke(...args) {
+    const _callbacks = [...this._callbacks];
+    for (const callback of _callbacks) {
+      try {
+        const result = await Promise.resolve(callback(...args));
+        if (result === false) {
+          return false;
+        }
+      } catch (error) {
+        Logger(`AllHandler ${this._name} treated error as failure!`, LOG_LEVEL_VERBOSE);
+        Logger(error, LOG_LEVEL_VERBOSE);
+        return false;
+      }
+    }
+    return true;
+  }
+}
+class ParallelAllHandler extends BooleanHandlerBase {
+  /**
+   * Invoke all handlers in parallel
+   * @param args The arguments to pass to the handlers.
+   * @returns True if all handlers return true, otherwise false.
+   */
+  async invoke(...args) {
+    const callbacks = [...this._callbacks];
+    const promises = callbacks.map(async (callback) => {
+      try {
+        const result = await Promise.resolve(callback(...args));
+        return result;
+      } catch (error) {
+        Logger(`ParallelAllHandler ${this._name} treated error as failure!`, LOG_LEVEL_VERBOSE);
+        Logger(error, LOG_LEVEL_VERBOSE);
+        return false;
+      }
+    });
+    const results = await Promise.all(promises);
+    return results.every((res) => res === true);
+  }
+}
+class AnySuccessHandler extends BooleanHandlerBase {
+  /**
+   * Invokes handlers sequentially until one returns true.
+   * @param args The arguments to pass to the handlers.
+   * @returns True if any handler returns true, otherwise false.
+   */
+  async invoke(...args) {
+    const _callbacks = [...this._callbacks];
+    for (const callback of _callbacks) {
+      try {
+        const result = await Promise.resolve(callback(...args));
+        if (result === true) {
+          return true;
+        }
+      } catch (error) {
+        Logger(`FirstSuccessHandler ${this._name} ignored error!`, LOG_LEVEL_VERBOSE);
+        Logger(error, LOG_LEVEL_VERBOSE);
+      }
+    }
+    return false;
+  }
+}
+class FirstResultHandler extends MultiBinder {
+  /**
+   * Invokes handlers sequentially until one returns a non-falsy value.
+   * @param args The arguments to pass to the handlers.
+   * @returns The first non-falsy result from the handlers, or false if none found.
+   */
+  async invoke(...args) {
+    const _callbacks = [...this._callbacks];
+    for (const callback of _callbacks) {
+      try {
+        const result = await Promise.resolve(callback(...args));
+        if (result !== void 0 && result !== false) {
+          return result;
+        }
+      } catch (error) {
+        Logger(`FirstResultHandler ${this._name} ignored error!`, LOG_LEVEL_VERBOSE);
+        Logger(error, LOG_LEVEL_VERBOSE);
+      }
+    }
+    return false;
+  }
+}
+function getMultipleBound(handler) {
+  const _handler = "invoke" in handler ? handler.invoke : handler.dispatch;
+  const __handler = _handler.bind(handler);
+  const func = (...args) => {
+    return __handler(...args);
+  };
+  func.addHandler = handler.addHandler.bind(handler);
+  func.removeHandler = handler.removeHandler.bind(handler);
+  func.use = handler;
+  return func;
+}
+function allFunction(name) {
+  const handler = new AllHandler(name ?? "handleAllFunc");
+  return getMultipleBound(handler);
+}
+function bailFirstFailureFunction(name) {
+  const handler = new AllHandler(name ?? "bailFirstFailureFunction");
+  return getMultipleBound(handler);
+}
+function allParallelFunction(name) {
+  const handler = new ParallelAllHandler(name ?? "allParallelFunction");
+  return getMultipleBound(handler);
+}
+function anySuccessFunction(name) {
+  const handler = new AnySuccessHandler(name ?? "anySuccessFunction");
+  return getMultipleBound(handler);
+}
+function firstResultFunction(name) {
+  const handler = new FirstResultHandler(name ?? "firstResultFunction");
+  return getMultipleBound(handler);
+}
+function dispatchParallelFunction(name) {
+  const handler = new DispatchParallel(
+    name ?? "dispatchParallelFunction"
+  );
+  return getMultipleBound(handler);
+}
+function bindableFunction(name) {
+  const handler = new Binder(name ?? "bindableFunction");
+  const func = (...args) => {
+    return handler.invoke(...args);
+  };
+  func.setHandler = handler.assign.bind(handler);
+  return func;
+}
+function lazyBindableFunction(name) {
+  const handler = new LazyBinder(name ?? "lazyBindableFunction");
+  const func = async (...args) => {
+    return await handler.invoke(...args);
+  };
+  func.setHandler = handler.assign.bind(handler);
+  return func;
+}
+function handlers() {
+  return {
+    /**
+     * Create a handler that invokes all added handler functions sequentially until one returns false.
+     * @param name
+     * @returns
+     */
+    all(name) {
+      return allFunction(String(name));
+    },
+    /**
+     * Create a handler that invokes all added handler functions in parallel and returns true only if all return true.
+     * @param name
+     * @returns
+     */
+    allParallel(name) {
+      return allParallelFunction(String(name));
+    },
+    /**
+     * Create a handler that invokes all added handler functions sequentially until one returns false.
+     * @param name
+     * @returns
+     */
+    bailFirstFailure(name) {
+      return bailFirstFailureFunction(String(name));
+    },
+    /**
+     * Create a handler that invokes all added handler functions sequentially until one returns true.
+     * @param name
+     * @returns
+     */
+    anySuccess(name) {
+      return anySuccessFunction(String(name));
+    },
+    /**
+     * Create a handler that invokes all added handler functions sequentially until one returns a non-falsy value.
+     * @param name
+     * @returns
+     */
+    firstResult(name) {
+      return firstResultFunction(String(name));
+    },
+    /**
+     * Create a handler that invokes all added handler functions in parallel.
+     * @param name
+     * @returns
+     */
+    dispatchParallel(name) {
+      return dispatchParallelFunction(String(name));
+    },
+    /**
+     * Create a binder handler that can assign a single handler function.
+     * @param name
+     * @returns
+     */
+    binder(name) {
+      return bindableFunction(String(name));
+    },
+    lazyBinder(name) {
+      return lazyBindableFunction(String(name));
+    }
+  };
+}
+export {
+  AllHandler,
+  AnySuccessHandler,
+  Binder,
+  BooleanHandlerBase,
+  Dispatch,
+  DispatchParallel,
+  FirstResultHandler,
+  LazyBinder,
+  MultiBinder,
+  ParallelAllHandler,
+  allFunction,
+  allParallelFunction,
+  anySuccessFunction,
+  bailFirstFailureFunction,
+  bindableFunction,
+  dispatchParallelFunction,
+  firstResultFunction,
+  handlers,
+  lazyBindableFunction
+};

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

@@ -0,0 +1,13 @@
+import { type LOG_LEVEL } from "octagonal-wheels/common/logger";
+import type { IAPIService } from "../base/IService.js";
+export declare const MARK_LOG_SEPARATOR = "\u200A";
+export declare const MARK_LOG_NETWORK_ERROR = "\u200B";
+/**
+ * Creates a log function that prefixes messages with the service name and uses the provided APIService's addLog method if available.
+ * If APIService is not provided, it falls back to using the global Logger function.
+ * @param serviceName The name of the service to prefix log messages with.
+ * @param APIService An optional APIService instance to use for logging.
+ * @returns A log function that can be used to log messages with the specified service name and APIService.
+ */
+export declare function createInstanceLogFunction(serviceName: string, APIService?: IAPIService): (msg: unknown, level?: LOG_LEVEL, key?: string) => void;
+export type LogFunction = ReturnType<typeof createInstanceLogFunction>;

package/dist/services/lib/logUtils.js

@@ -0,0 +1,28 @@
+import {
+  LOG_LEVEL_INFO,
+  LOG_LEVEL_NOTICE,
+  LOG_LEVEL_VERBOSE,
+  Logger
+} from "octagonal-wheels/common/logger";
+const MARK_LOG_SEPARATOR = "\u200A";
+const MARK_LOG_NETWORK_ERROR = "\u200B";
+function createInstanceLogFunction(serviceName, APIService) {
+  const logFunc = APIService?.addLog.bind(APIService) ?? Logger;
+  return (msg, level = LOG_LEVEL_INFO, key = "") => {
+    const isError = msg instanceof Error;
+    if (isError && level <= LOG_LEVEL_VERBOSE) {
+      logFunc(msg, level, key);
+      return;
+    }
+    let formattedMsg = typeof msg === "string" ? msg : isError ? msg.message : JSON.stringify(msg);
+    if (level < LOG_LEVEL_NOTICE) {
+      formattedMsg = `[${serviceName}]${MARK_LOG_SEPARATOR} ${formattedMsg}`;
+    }
+    logFunc(formattedMsg, level, key);
+  };
+}
+export {
+  MARK_LOG_NETWORK_ERROR,
+  MARK_LOG_SEPARATOR,
+  createInstanceLogFunction
+};

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

@@ -0,0 +1,13 @@
+import type { ReactiveSource } from "octagonal-wheels/dataobject/reactive";
+export type TrackedPhysicalRequestCounters = {
+    requestCount: ReactiveSource<number>;
+    responseCount: ReactiveSource<number>;
+};
+/**
+ * Tracks one physical-request unit for status reporting.
+ *
+ * A unit may be an exact transport attempt or a higher-level SDK command. The
+ * resulting in-flight count is deliberately approximate and must not be used
+ * for protocol correctness, throttling, or completion decisions.
+ */
+export declare function runWithTrackedPhysicalRequest<T>(counters: TrackedPhysicalRequestCounters, task: () => T | PromiseLike<T>): Promise<T>;

package/dist/services/lib/remoteActivity.js

@@ -0,0 +1,11 @@
+async function runWithTrackedPhysicalRequest(counters, task) {
+  counters.requestCount.value++;
+  try {
+    return await task();
+  } finally {
+    counters.responseCount.value++;
+  }
+}
+export {
+  runWithTrackedPhysicalRequest
+};

package/dist/string_and_binary/chunks.d.ts

@@ -0,0 +1,10 @@
+export declare function splitPiecesTextV2(dataSrc: string | string[], pieceSize: number, minimumChunkSize: number): () => Generator<string>;
+export declare function binaryTextSplit(data: string, pieceSize: number, minimumChunkSize: number): () => Generator<string>;
+export declare function splitPiecesText(dataSrc: string | string[], pieceSize: number, plainSplit: boolean, minimumChunkSize: number, useSegmenter: boolean): () => Generator<string>;
+export declare function splitPiecesTextV1(dataSrc: string | string[], pieceSize: number, plainSplit: boolean, minimumChunkSize: number): () => Generator<string>;
+export declare function collectGenAll(strGen: AsyncGenerator<string, unknown, unknown> | Generator<string>): Promise<string[]>;
+export declare function concatGeneratedAll(strGen: AsyncGenerator<string, unknown, unknown> | Generator<string>): Promise<string>;
+export declare function splitPieces2V2(dataSrc: Blob, pieceSize: number, plainSplit: boolean, minimumChunkSize: number, filename?: string, useSegmenter?: boolean): Promise<(() => Generator<string>) | (() => AsyncGenerator<string>)>;
+export declare function splitPieces2(dataSrc: Blob, pieceSize: number, plainSplit: boolean, minimumChunkSize: number, filename?: string, useSegmenter?: boolean): Promise<(() => Generator<string>) | (() => AsyncGenerator<string>)>;
+export declare function splitPiecesRabinKarp(dataSrc: Blob, absoluteMaxPieceSize: number, doPlainSplit: boolean, minimumChunkSize: number, _filename?: string, _useSegmenter?: boolean): Promise<() => AsyncGenerator<string, void, unknown>>;
+export declare function splitPiecesRabinKarpOld(dataSrc: Blob, absoluteMaxPieceSize: number, doPlainSplit: boolean, minimumChunkSize: number, _filename?: string, _useSegmenter?: boolean): Promise<() => AsyncGenerator<string, void, unknown>>;