@serwist/window/dist/index.d.mts

Simplifies communications with Serwist packages running in the service worker

//#region src/messageSW.d.ts
/**
 * Sends a data object to a service worker via `postMessage` and resolves with
 * a response (if any).
 *
 * A response can be sent by calling `event.ports[0].postMessage(...)`, which will
 * resolve the promise returned by `messageSW()`. If no response is sent, the promise
 * will never resolve.
 *
 * @param sw The service worker to send the message to.
 * @param data An object to send to the service worker.
 * @returns
 */
declare const messageSW: (sw: ServiceWorker, data: any) => Promise<any>;
//#endregion
//#region src/utils/SerwistEvent.d.ts
/**
 * A minimal `Event` subclass shim.
 * This doesn't *actually* subclass `Event` because not all browsers support
 * constructable `EventTarget`, and using a real `Event` will error.
 * @private
 */
declare class SerwistEvent<K extends keyof SerwistEventMap> {
  type: K;
  target?: SerwistEventTarget;
  sw?: ServiceWorker;
  originalEvent?: Event;
  isExternal?: boolean;
  constructor(type: K, props: Omit<SerwistEventMap[K], "target" | "type">);
}
interface SerwistMessageEvent extends SerwistEvent<"message"> {
  data: any;
  originalEvent: Event;
  ports: readonly MessagePort[];
}
interface SerwistLifecycleEvent extends SerwistEvent<keyof SerwistLifecycleEventMap> {
  isUpdate?: boolean;
}
interface SerwistLifecycleWaitingEvent extends SerwistLifecycleEvent {
  wasWaitingBeforeRegister?: boolean;
}
interface SerwistLifecycleEventMap {
  installing: SerwistLifecycleEvent;
  installed: SerwistLifecycleEvent;
  waiting: SerwistLifecycleWaitingEvent;
  activating: SerwistLifecycleEvent;
  activated: SerwistLifecycleEvent;
  controlling: SerwistLifecycleEvent;
  redundant: SerwistLifecycleEvent;
}
interface SerwistEventMap extends SerwistLifecycleEventMap {
  message: SerwistMessageEvent;
}
//#endregion
//#region src/utils/SerwistEventTarget.d.ts
/**
 * A minimal `EventTarget` shim.
 * This is necessary because not all browsers support constructable
 * `EventTarget`, so using a real `EventTarget` will error.
 * @private
 */
declare class SerwistEventTarget {
  private readonly _eventListenerRegistry;
  /**
   * @param type
   * @param listener
   * @private
   */
  addEventListener<K extends keyof SerwistEventMap>(type: K, listener: (event: SerwistEventMap[K]) => any): void;
  /**
   * @param type
   * @param listener
   * @private
   */
  removeEventListener<K extends keyof SerwistEventMap>(type: K, listener: (event: SerwistEventMap[K]) => any): void;
  /**
   * @param event
   * @private
   */
  dispatchEvent(event: SerwistEvent<any>): void;
  /**
   * Returns a Set of listeners associated with the passed event type.
   * If no handlers have been registered, an empty Set is returned.
   *
   * @param type The event type.
   * @returns An array of handler functions.
   * @private
   */
  private _getEventListenersByType;
}
//#endregion
//#region src/Serwist.d.ts
/**
 * A class to aid in handling service worker registration, updates, and
 * reacting to service worker lifecycle events.
 *
 * @fires `@serwist/window.Serwist.message`
 * @fires `@serwist/window.Serwist.installed`
 * @fires `@serwist/window.Serwist.waiting`
 * @fires `@serwist/window.Serwist.controlling`
 * @fires `@serwist/window.Serwist.activated`
 * @fires `@serwist/window.Serwist.redundant`
 */
declare class Serwist extends SerwistEventTarget {
  private readonly _scriptURL;
  private readonly _registerOptions;
  private _updateFoundCount;
  private readonly _swDeferred;
  private readonly _activeDeferred;
  private readonly _controllingDeferred;
  private _registrationTime;
  private _isUpdate?;
  private _compatibleControllingSW?;
  private _registration?;
  private _sw?;
  private readonly _ownSWs;
  private _externalSW?;
  private _waitingTimeout?;
  /**
   * Creates a new Serwist instance with a script URL and service worker
   * options. The script URL and options are the same as those used when
   * calling [navigator.serviceWorker.register(scriptURL, options)](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerContainer/register).
   *
   * @param scriptURL The service worker script associated with this instance. Using a
   * [`TrustedScriptURL`](https://developer.mozilla.org/en-US/docs/Web/API/TrustedScriptURL) is supported.
   * @param registerOptions The service worker options associated with this instance.
   */
  constructor(scriptURL: string | TrustedScriptURL, registerOptions?: RegistrationOptions);
  /**
   * Registers a service worker for this instances script URL and service
   * worker options. By default this method delays registration until after
   * the window has loaded.
   *
   * @param options
   */
  register({
    immediate
  }?: {
    /**
     * Setting this to true will register the service worker immediately,
     * even if the window has not loaded (not recommended).
     */
    immediate?: boolean;
  }): Promise<ServiceWorkerRegistration | undefined>;
  /**
   * Checks for updates of the registered service worker.
   */
  update(): Promise<void>;
  /**
   * Resolves to the service worker registered by this instance as soon as it
   * is active. If a service worker was already controlling at registration
   * time then it will resolve to that if the script URLs (and optionally
   * script versions) match, otherwise it will wait until an update is found
   * and activates.
   *
   * @returns
   */
  get active(): Promise<ServiceWorker>;
  /**
   * Resolves to the service worker registered by this instance as soon as it
   * is controlling the page. If a service worker was already controlling at
   * registration time then it will resolve to that if the script URLs (and
   * optionally script versions) match, otherwise it will wait until an update
   * is found and starts controlling the page.
   * Note: the first time a service worker is installed it will active but
   * not start controlling the page unless `clients.claim()` is called in the
   * service worker.
   *
   * @returns
   */
  get controlling(): Promise<ServiceWorker>;
  /**
   * Resolves with a reference to a service worker that matches the script URL
   * of this instance, as soon as it's available.
   *
   * If, at registration time, there's already an active or waiting service
   * worker with a matching script URL, it will be used (with the waiting
   * service worker taking precedence over the active service worker if both
   * match, since the waiting service worker would have been registered more
   * recently).
   * If there's no matching active or waiting service worker at registration
   * time then the promise will not resolve until an update is found and starts
   * installing, at which point the installing service worker is used.
   *
   * @returns
   */
  getSW(): Promise<ServiceWorker>;
  /**
   * Sends the passed data object to the service worker registered by this
   * instance (via `getSW`) and resolves with a response (if any).
   *
   * A response can be sent by calling `event.ports[0].postMessage(...)`, which will
   * resolve the promise returned by `messageSW()`. If no response is sent, the promise
   * will never resolve.
   *
   * @param data An object to send to the service worker
   * @returns
   */
  messageSW(data: any): Promise<any>;
  /**
   * Sends a `{ type: "SKIP_WAITING" }` message to the service worker that is
   * currently waiting and associated with the current registration.
   *
   * If there is no current registration, or no service worker is waiting,
   * calling this will have no effect.
   */
  messageSkipWaiting(): void;
  /**
   * Checks for a service worker already controlling the page and returns
   * it if its script URL matches.
   *
   * @private
   * @returns
   */
  private _getControllingSWIfCompatible;
  /**
   * Registers a service worker for this instances script URL and register
   * options and tracks the time registration was complete.
   *
   * @private
   */
  private _registerScript;
  /**
   * @private
   * @param originalEvent
   */
  private readonly _onUpdateFound;
  /**
   * @private
   * @param originalEvent
   */
  private readonly _onStateChange;
  /**
   * @private
   * @param originalEvent
   */
  private readonly _onControllerChange;
  /**
   * @private
   * @param originalEvent
   */
  private readonly _onMessage;
}
//#endregion
export { Serwist, SerwistEvent, SerwistEventMap, SerwistLifecycleEvent, SerwistLifecycleEventMap, SerwistLifecycleWaitingEvent, SerwistMessageEvent, messageSW };
//# sourceMappingURL=index.d.mts.map