@difizen/libro-common 0.3.4 → 1.0.0

package/src/common/vscode-uri/utils.ts

@@ -0,0 +1,101 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import { posix } from 'path-browserify';
+
+import { CharCode } from './char-code.js';
+import type { URI } from './uri.js';
+
+const posixPath = posix;
+const slash = '/';
+
+export namespace Utils {
+  /**
+   * Joins one or more input paths to the path of URI.
+   * '/' is used as the directory separation character.
+   *
+   * The resolved path will be normalized. That means:
+   *  - all '..' and '.' segments are resolved.
+   *  - multiple, sequential occurences of '/' are replaced by a single instance of '/'.
+   *  - trailing separators are preserved.
+   *
+   * @param uri The input URI.
+   * @param paths The paths to be joined with the path of URI.
+   * @returns A URI with the joined path. All other properties of the URI (scheme, authority, query, fragments, ...) will be taken from the input URI.
+   */
+  export function joinPath(uri: URI, ...paths: string[]): URI {
+    return uri.with({ path: posixPath.join(uri.path, ...paths) });
+  }
+
+  /**
+   * Resolves one or more paths against the path of a URI.
+   * '/' is used as the directory separation character.
+   *
+   * The resolved path will be normalized. That means:
+   *  - all '..' and '.' segments are resolved.
+   *  - multiple, sequential occurences of '/' are replaced by a single instance of '/'.
+   *  - trailing separators are removed.
+   *
+   * @param uri The input URI.
+   * @param paths The paths to resolve against the path of URI.
+   * @returns A URI with the resolved path. All other properties of the URI (scheme, authority, query, fragments, ...) will be taken from the input URI.
+   */
+  export function resolvePath(uri: URI, ...paths: string[]): URI {
+    let path = uri.path;
+    let slashAdded = false;
+    if (path[0] !== slash) {
+      path = slash + path; // make the path abstract: for posixPath.resolve the first segments has to be absolute or cwd is used.
+      slashAdded = true;
+    }
+    let resolvedPath = posixPath.resolve(path, ...paths);
+    if (slashAdded && resolvedPath[0] === slash && !uri.authority) {
+      resolvedPath = resolvedPath.substring(1);
+    }
+    return uri.with({ path: resolvedPath });
+  }
+
+  /**
+   * Returns a URI where the path is the directory name of the input uri, similar to the Unix dirname command.
+   * In the path, '/' is recognized as the directory separation character. Trailing directory separators are ignored.
+   * The orignal URI is returned if the URIs path is empty or does not contain any path segments.
+   *
+   * @param uri The input URI.
+   * @return The last segment of the URIs path.
+   */
+  export function dirname(uri: URI): URI {
+    if (uri.path.length === 0 || uri.path === slash) {
+      return uri;
+    }
+    let path = posixPath.dirname(uri.path);
+    if (path.length === 1 && path.charCodeAt(0) === CharCode.Period) {
+      path = '';
+    }
+    return uri.with({ path });
+  }
+
+  /**
+   * Returns the last segment of the path of a URI, similar to the Unix basename command.
+   * In the path, '/' is recognized as the directory separation character. Trailing directory separators are ignored.
+   * The empty string is returned if the URIs path is empty or does not contain any path segments.
+   *
+   * @param uri The input URI.
+   * @return The base name of the URIs path.
+   */
+  export function basename(uri: URI): string {
+    return posixPath.basename(uri.path);
+  }
+
+  /**
+   * Returns the extension name of the path of a URI, similar to the Unix extname command.
+   * In the path, '/' is recognized as the directory separation character. Trailing directory separators are ignored.
+   * The empty string is returned if the URIs path is empty or does not contain any path segments.
+   *
+   * @param uri The input URI.
+   * @return The extension name of the URIs path.
+   */
+  export function extname(uri: URI): string {
+    return posixPath.extname(uri.path);
+  }
+}

package/src/common/wait-until-event.spec.ts

@@ -0,0 +1,70 @@
+import assert from 'assert';
+
+import { WaitUntilEvent } from '.';
+import { Emitter } from '.';
+import { Deferred } from '.';
+
+describe('wait until event', () => {
+  it('#wait until', async () => {
+    let did = false;
+    const deferred = new Deferred<void>();
+    const emitter = new Emitter<WaitUntilEvent>();
+    emitter.event((e) => {
+      if (e.waitUntil) {
+        e.waitUntil(deferred.promise);
+      }
+      setTimeout(() => {
+        deferred.resolve();
+        did = true;
+      }, 100);
+    });
+    await WaitUntilEvent.fire(emitter, {}, 50);
+    assert(!did);
+  });
+  it('#wait until without waitable', async () => {
+    let did = false;
+    const emitter = new Emitter<WaitUntilEvent>();
+    emitter.event(() => {
+      did = true;
+    });
+    await WaitUntilEvent.fire(emitter, {}, 50);
+    assert(did);
+  });
+  it('#wait until without timeout', async () => {
+    let did = false;
+    const deferred = new Deferred<void>();
+    const emitter = new Emitter<WaitUntilEvent>();
+    emitter.event((e) => {
+      if (e.waitUntil) {
+        e.waitUntil(deferred.promise);
+      }
+      setTimeout(() => {
+        deferred.resolve();
+        did = true;
+      }, 100);
+    });
+    await WaitUntilEvent.fire(emitter, {});
+    assert(did);
+  });
+});
+it('#wait until can not called asynchronously', async () => {
+  const deferred = new Deferred<void>();
+  const emitter = new Emitter<WaitUntilEvent>();
+  emitter.event((e) => {
+    const { waitUntil } = e;
+    if (waitUntil) {
+      waitUntil(deferred.promise);
+    }
+    setTimeout(() => {
+      try {
+        if (waitUntil) {
+          waitUntil(deferred.promise);
+        }
+      } catch (ex) {
+        assert(ex);
+      }
+      deferred.resolve();
+    }, 100);
+  });
+  WaitUntilEvent.fire(emitter, {});
+});

package/src/common/wait-until-event.ts

@@ -0,0 +1,49 @@
+import type { Emitter } from './event';
+
+export type WaitUntilEvent = {
+  /**
+   * Allows to pause the event loop until the provided thenable resolved.
+   * *Note:* It can only be called during event dispatch and not in an asynchronous manner
+   * @param thenable A thenable that delays execution.
+   */
+  waitUntil?: (thenable: Promise<any>) => void;
+};
+export namespace WaitUntilEvent {
+  /**
+   * Fire all listeners in the same tick.
+   * Use `AsyncEmitter.fire` to fire listeners async one after another.
+   */
+  export async function fire<T extends WaitUntilEvent>(
+    emitter: Emitter<T>,
+    event: Omit<T, 'waitUntil'>,
+    timeout: number | undefined = undefined,
+  ): Promise<void> {
+    const waitables: Promise<void>[] = [];
+    const asyncEvent = Object.assign(event, {
+      waitUntil: (thenable: Promise<any>) => {
+        if (Object.isFrozen(waitables)) {
+          throw new Error('waitUntil cannot be called asynchronously.');
+        }
+        waitables.push(thenable);
+      },
+    }) as T;
+    try {
+      emitter.fire(asyncEvent);
+      // Asynchronous calls to `waitUntil` should fail.
+      Object.freeze(waitables);
+    } finally {
+      delete asyncEvent.waitUntil;
+    }
+    if (!waitables.length) {
+      return;
+    }
+    if (timeout !== undefined) {
+      await Promise.race([
+        Promise.all(waitables),
+        new Promise((resolve) => setTimeout(resolve, timeout)),
+      ]);
+    } else {
+      await Promise.all(waitables);
+    }
+  }
+}

package/src/core/application/application-protocol.ts

@@ -0,0 +1,20 @@
+import type { Event } from '../../common/index.js';
+
+/**
+ * Service for opening new browser windows.
+ */
+export const WindowService = Symbol('WindowService');
+export type WindowService = {
+  /**
+   * Called when the `window` is about to `unload` its resources.
+   * At this point, the `document` is still visible and the [`BeforeUnloadEvent`](https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event)
+   * event will be canceled if the return value of this method is `false`.
+   */
+  canUnload: () => boolean;
+
+  /**
+   * Fires when the `window` unloads. The unload event is inevitable. On this event, the frontend application can save its state and release resource.
+   * Saving the state and releasing any resources must be a synchronous call. Any asynchronous calls invoked after emitting this event might be ignored.
+   */
+  readonly onUnload: Event<void>;
+};

package/src/core/application/application-state.ts

@@ -0,0 +1,68 @@
+import type { Event } from '../../common/index.js';
+import { Emitter, Deferred } from '../../common/index.js';
+import { prop } from '../../observable/index.js';
+import { inject, singleton } from '../../ioc/index.js';
+import { DebugService } from '../common/debug';
+
+export enum ApplicationState {
+  Default = 'Default',
+  Initialized = 'Initialized',
+  Started = 'Started',
+  ViewStarted = 'ViewStarted',
+  Ready = 'Ready',
+  Closing = 'Closing',
+}
+
+@singleton()
+export class ApplicationStateService {
+  @prop()
+  state: ApplicationState = ApplicationState.Default;
+
+  protected readonly debugService: DebugService;
+
+  constructor(
+    @inject(DebugService)
+    debugService: DebugService,
+  ) {
+    this.debugService = debugService;
+  }
+
+  protected deferred: Record<string, Deferred<void>> = {};
+  protected readonly stateChanged = new Emitter<ApplicationState>();
+
+  setState(state: ApplicationState) {
+    if (state !== this.state) {
+      const oldState = this.state;
+      const oldDeferred = this.getStateDeferred(oldState);
+      oldDeferred.resolve();
+      const deferred = this.getStateDeferred(state);
+      this.state = state;
+      deferred.resolve();
+      this.deferred[state].resolve();
+      this.debugService(
+        `Changed application state from '${oldState}' to '${this.state}'.`,
+      );
+    }
+  }
+
+  get onStateChanged(): Event<ApplicationState> {
+    return this.stateChanged.event;
+  }
+
+  protected getStateDeferred(state: ApplicationState): Deferred<void> {
+    let deferred = this.deferred[state];
+    if (deferred === undefined) {
+      deferred = new Deferred();
+      this.deferred[state] = deferred;
+    }
+    return deferred;
+  }
+
+  reachedState(state: ApplicationState): Promise<void> {
+    return this.getStateDeferred(state).promise;
+  }
+
+  reachedAnyState(...states: ApplicationState[]): Promise<void> {
+    return Promise.race(states.map((s) => this.reachedState(s)));
+  }
+}

package/src/core/application/application.ts

@@ -0,0 +1,294 @@
+import type { MaybePromise } from '../../common/index.js';
+import { Disposable } from '../../common/index.js';
+import { Emitter, DisposableCollection } from '../../common/index.js';
+import { inject, singleton, Syringe, contrib, Utils } from '../../ioc/index.js';
+import type { Decorator, Contribution } from '../../ioc/index.js';
+
+import { DebugService } from '../common/debug';
+
+import { WindowService } from './application-protocol';
+import { ApplicationStateService, ApplicationState } from './application-state';
+
+export const ApplicationContribution = Syringe.defineToken('ApplicationContribution');
+export type ApplicationContribution = {
+  /**
+   * Called on application startup.
+   */
+  initialize?: () => void;
+
+  /**
+   * Called before the start of the contributions to complete asynchronous initialization.
+   */
+  onWillStart?: (app: Application) => MaybePromise<void>;
+
+  /**
+   * Called when the application is starting.
+   */
+  onStart?: (app: Application) => MaybePromise<void>;
+
+  /**
+   * Called when the application is started and after the root view has been created.
+   */
+  onViewStart?: (app: Application) => MaybePromise<void>;
+  /**
+   * Called on `beforeunload` event, return `true` in order to prevent exit.
+   */
+  onWillStop?: (app: Application) => boolean;
+
+  /**
+   * Called when an application is stopped.
+   * Note: this is the last tick.
+   */
+  onStop?: (app: Application) => void;
+};
+
+export function application<T = any>(
+  option: Syringe.DecoratorOption<T> = {},
+): Decorator<T> {
+  return singleton({
+    ...option,
+    contrib: [ApplicationContribution, ...Utils.toArray(option.contrib)],
+    lifecycle: Syringe.Lifecycle.singleton,
+  });
+}
+
+const TIMER_WARNING_THRESHOLD = 100;
+
+@singleton()
+export class Application {
+  protected _host?: HTMLElement;
+  started = false;
+
+  protected onKeyDownEmitter = new Emitter<KeyboardEvent>();
+  protected onHostChangedEmitter = new Emitter<HTMLElement | undefined>();
+
+  protected unmountToDispose = new DisposableCollection();
+
+  protected readonly windowsService: WindowService;
+  protected readonly contributions: Contribution.Provider<ApplicationContribution>;
+  protected readonly stateService: ApplicationStateService;
+  protected readonly debugService: DebugService;
+
+  get host(): HTMLElement | undefined {
+    return this._host;
+  }
+
+  set host(v: HTMLElement | undefined) {
+    this._host = v;
+    this.onHostChangedEmitter.fire(v);
+  }
+
+  get onKeyDown() {
+    return this.onKeyDownEmitter.event;
+  }
+  get onHostChanged() {
+    return this.onHostChangedEmitter.event;
+  }
+
+  constructor(
+    @inject(WindowService)
+    windowsService: WindowService,
+    @contrib(ApplicationContribution)
+    contributions: Contribution.Provider<ApplicationContribution>,
+    @inject(ApplicationStateService)
+    stateService: ApplicationStateService,
+    @inject(DebugService)
+    debugService: DebugService,
+  ) {
+    this.windowsService = windowsService;
+    this.contributions = contributions;
+    this.stateService = stateService;
+    this.debugService = debugService;
+  }
+
+  /**
+   * Start the frontend application.
+   *
+   * Start up consists of the following steps:
+   * - start frontend contributions
+   * - create root view and render it
+   * - restore or create other views and render them
+   */
+  async start(): Promise<void> {
+    if (this.started) {
+      return;
+    }
+    this.started = true;
+    await this.initialize();
+    this.stateService.setState(ApplicationState.Initialized);
+    await this.onStart();
+    this.stateService.setState(ApplicationState.Started);
+    await this.viewStart();
+    this.mount();
+    this.stateService.setState(ApplicationState.ViewStarted);
+    this.stateService.setState(ApplicationState.Ready);
+    this.windowsService.onUnload(() => {
+      this.stateService.setState(ApplicationState.Closing);
+      this.onStop();
+    });
+  }
+
+  public inComposition = false;
+
+  /**
+   * Register composition related event listeners.
+   */
+  protected registerCompositionEventListeners(): Disposable {
+    const compositionStart = () => {
+      this.inComposition = true;
+    };
+    const compositionEnd = () => {
+      this.inComposition = false;
+    };
+    document.addEventListener('compositionstart', compositionStart);
+    document.addEventListener('compositionend', compositionEnd);
+    return Disposable.create(() => {
+      document.removeEventListener('compositionstart', compositionStart);
+      document.removeEventListener('compositionend', compositionEnd);
+    });
+  }
+
+  protected registerKeyDownListener(): Disposable {
+    const fireKeyDown = (e: KeyboardEvent) => {
+      this.onKeyDownEmitter.fire(e);
+    };
+    document.addEventListener('keydown', fireKeyDown);
+    return Disposable.create(() => {
+      document.removeEventListener('keydown', fireKeyDown);
+    });
+  }
+
+  mount() {
+    this.unmountToDispose.push(this.registerCompositionEventListeners());
+    this.unmountToDispose.push(this.registerKeyDownListener());
+  }
+
+  unmount() {
+    this.unmountToDispose.dispose();
+  }
+
+  /**
+   * Initialize and start the frontend application contributions.
+   */
+  protected async initialize(): Promise<void> {
+    for (const contribution of this.contributions.getContributions()) {
+      if (contribution.initialize) {
+        try {
+          await this.measure(`${contribution.constructor.name}.initialize`, () => {
+            if (contribution.initialize) {
+              contribution.initialize();
+            }
+          });
+        } catch (error) {
+          console.error('contribution initialize', error);
+        }
+      }
+    }
+  }
+
+  /**
+   * Initialize and start the frontend application contributions.
+   */
+  protected async onStart(): Promise<void> {
+    for (const contribution of this.contributions.getContributions()) {
+      if (contribution.onWillStart) {
+        try {
+          await this.measure(`${contribution.constructor.name}.onWillStart`, () => {
+            if (contribution.onWillStart) {
+              return contribution.onWillStart(this);
+            }
+          });
+        } catch (error) {
+          console.error('contribution onWillStart', error);
+        }
+      }
+    }
+
+    for (const contribution of this.contributions.getContributions()) {
+      if (contribution.onStart) {
+        try {
+          await this.measure(`${contribution.constructor.name}.onStart`, () => {
+            if (contribution.onStart) {
+              return contribution.onStart!(this);
+            }
+          });
+        } catch (error) {
+          console.error('contribution onStart', error);
+        }
+      }
+    }
+  }
+
+  protected async viewStart(): Promise<void> {
+    for (const contribution of this.contributions.getContributions()) {
+      if (contribution.onViewStart) {
+        try {
+          await this.measure(
+            `${contribution.constructor.name}.initializeLayout`,
+            () => {
+              if (contribution.onViewStart) {
+                return contribution.onViewStart(this);
+              }
+            },
+          );
+        } catch (error) {
+          console.error('contribution initializeLayout', error);
+        }
+      }
+    }
+  }
+
+  onWillStop(): boolean {
+    let shouldConfirm = false;
+    for (const contribution of this.contributions.getContributions()) {
+      if (contribution.onWillStop) {
+        try {
+          if (contribution.onWillStop) {
+            if (contribution.onWillStop(this)) {
+              shouldConfirm = true;
+            }
+          }
+        } catch (error) {
+          console.error('contribution onWillStop', error);
+        }
+      }
+    }
+    return shouldConfirm;
+  }
+
+  /**
+   * Stop the frontend application contributions. This is called when the window is unloaded.
+   */
+  protected onStop(): void {
+    this.debugService('>>> Stopping contributions...');
+    for (const contribution of this.contributions.getContributions()) {
+      if (contribution.onStop) {
+        try {
+          contribution.onStop(this);
+        } catch (error) {
+          console.error('contribution onStop', error);
+        }
+      }
+    }
+    this.debugService('<<< All contributions have been stopped.');
+  }
+
+  protected async measure<T>(name: string, fn: () => MaybePromise<T>): Promise<T> {
+    const startMark = `${name}-start`;
+    const endMark = `${name}-end`;
+    performance.mark(startMark);
+    const result = await fn();
+    performance.mark(endMark);
+    performance.measure(name, startMark, endMark);
+    for (const item of performance.getEntriesByName(name)) {
+      const contribution = `${item.name}`;
+      if (item.duration > TIMER_WARNING_THRESHOLD) {
+        console.warn(`${contribution} is slow, took: ${item.duration.toFixed(1)} ms`);
+      } else {
+        this.debugService(`${contribution} took: ${item.duration.toFixed(1)} ms`);
+      }
+    }
+    performance.clearMeasures(name);
+    return result;
+  }
+}

package/src/core/application/default-window-service.ts

@@ -0,0 +1,66 @@
+import type { Event } from '../../common/index.js';
+import { Emitter } from '../../common/index.js';
+import { singleton } from '../../ioc/index.js';
+
+import { ApplicationContribution } from './application';
+import type { Application } from './application';
+import { WindowService } from './application-protocol';
+
+@singleton({
+  contrib: [WindowService, ApplicationContribution],
+})
+export class DefaultWindowService implements WindowService, ApplicationContribution {
+  protected frontendApplication?: Application;
+
+  protected onUnloadEmitter = new Emitter<void>();
+  get onUnload(): Event<void> {
+    return this.onUnloadEmitter.event;
+  }
+
+  onStart(app: Application): void {
+    this.frontendApplication = app;
+    this.registerUnloadListeners();
+  }
+
+  canUnload(): boolean {
+    // eslint-disable-next-line prefer-const
+    let confirmExit = 'never';
+    // TODO: core preferrence application.confirmExit
+
+    let preventUnload = this.frontendApplication?.onWillStop();
+    preventUnload = confirmExit === 'always' || preventUnload;
+    return confirmExit === 'never' || !preventUnload;
+  }
+
+  /**
+   * Implement the mechanism to detect unloading of the page.
+   */
+  protected registerUnloadListeners(): void {
+    window.addEventListener('beforeunload', (event) => {
+      if (!this.canUnload()) {
+        return this.preventUnload(event);
+      }
+      return undefined;
+    });
+    // In a browser, `unload` is correctly fired when the page unloads, unlike Electron.
+    // If `beforeunload` is cancelled, the user will be prompted to leave or stay.
+    // If the user stays, the page won't be unloaded, so `unload` is not fired.
+    // If the user leaves, the page will be unloaded, so `unload` is fired.
+    window.addEventListener('unload', () => this.onUnloadEmitter.fire());
+  }
+
+  /**
+   * Notify the browser that we do not want to unload.
+   *
+   * Notes:
+   *  - Shows a confirmation popup in browsers.
+   *  - Prevents the window from closing without confirmation in electron.
+   *
+   * @param event The beforeunload event
+   */
+  protected preventUnload(event: BeforeUnloadEvent): string | void {
+    event.returnValue = '';
+    event.preventDefault();
+    return '';
+  }
+}

package/src/core/application/index.ts

@@ -0,0 +1,12 @@
+import { ManaModule } from '../module';
+
+import { Application, ApplicationContribution } from './application';
+import { ApplicationStateService } from './application-state';
+import { DefaultWindowService } from './default-window-service';
+
+export * from './application';
+export * from './application-state';
+
+export const ApplicationModule = ManaModule.create()
+  .contribution(ApplicationContribution)
+  .register(ApplicationStateService, Application, DefaultWindowService);