@difizen/libro-common 0.3.4 → 1.0.0

package/src/app/tree/tree-impl.ts

@@ -0,0 +1,182 @@
+import { getOrigin, equals } from '../../observable/index.js';
+
+import type { Mutable, Event, CancellationToken } from '../../common/index.js';
+import { timeout } from '../../common/index.js';
+import { CancellationTokenSource } from '../../common/index.js';
+import { DisposableCollection } from '../../common/index.js';
+import { Emitter, WaitUntilEvent } from '../../common/index.js';
+import { singleton } from '../../ioc/index.js';
+
+import type { TreeNode } from './tree.js';
+import { Tree, CompositeTreeNode } from './tree.js';
+
+/**
+ * A default implementation of the tree.
+ */
+@singleton({ token: Tree })
+export class TreeImpl implements Tree {
+  protected _root: TreeNode | undefined;
+  protected readonly onChangedEmitter = new Emitter<void>();
+  protected readonly onNodeRefreshedEmitter = new Emitter<
+    CompositeTreeNode & WaitUntilEvent
+  >();
+  protected readonly toDispose = new DisposableCollection();
+
+  protected readonly onDidChangeBusyEmitter = new Emitter<TreeNode>();
+  readonly onDidChangeBusy = this.onDidChangeBusyEmitter.event;
+
+  protected nodes: Record<string, Mutable<TreeNode> | undefined> = {};
+
+  constructor() {
+    this.toDispose.push(this.onChangedEmitter);
+    this.toDispose.push(this.onNodeRefreshedEmitter);
+    this.toDispose.push(this.onDidChangeBusyEmitter);
+  }
+
+  dispose(): void {
+    this.nodes = {};
+    this.toDispose.dispose();
+  }
+
+  get root(): TreeNode | undefined {
+    return this._root;
+  }
+
+  set root(root: TreeNode | undefined) {
+    this.nodes = {};
+    this._root = root;
+    this.addNode(root);
+    this.refresh();
+  }
+
+  get onChanged(): Event<void> {
+    return this.onChangedEmitter.event;
+  }
+
+  protected fireChanged(): void {
+    this.onChangedEmitter.fire(undefined);
+  }
+
+  get onNodeRefreshed(): Event<CompositeTreeNode & WaitUntilEvent> {
+    return this.onNodeRefreshedEmitter.event;
+  }
+
+  protected async fireNodeRefreshed(parent: CompositeTreeNode): Promise<void> {
+    await WaitUntilEvent.fire(this.onNodeRefreshedEmitter, parent);
+    this.fireChanged();
+  }
+
+  getNode = (id: string | undefined): TreeNode | undefined => {
+    return id !== undefined ? this.nodes[id] : undefined;
+  };
+
+  validateNode = (node: TreeNode | undefined): TreeNode | undefined => {
+    const id = node ? node.id : undefined;
+    return this.getNode(id);
+  };
+
+  async refresh(raw?: CompositeTreeNode): Promise<CompositeTreeNode | undefined> {
+    const parent = !raw ? this._root : this.validateNode(raw);
+    let result: CompositeTreeNode | undefined;
+    if (CompositeTreeNode.is(parent)) {
+      const busySource = new CancellationTokenSource();
+      this.doMarkAsBusy(parent, 800, busySource.token);
+      try {
+        result = parent;
+        const children = await this.resolveChildren(parent);
+        result = await this.setChildren(parent, children);
+      } finally {
+        busySource.cancel();
+      }
+    }
+    this.fireChanged();
+    return result;
+  }
+
+  protected resolveChildren(parent: CompositeTreeNode): Promise<TreeNode[]> {
+    return Promise.resolve(Array.from(parent.children));
+  }
+
+  protected setChildren = async (
+    parent: CompositeTreeNode,
+    children: TreeNode[],
+  ): Promise<CompositeTreeNode | undefined> => {
+    const root = this.getRootNode(parent);
+    if (this.nodes[root.id] && !equals(this.nodes[root.id], root)) {
+      console.error(
+        `Child node '${parent.id}' does not belong to this '${root.id}' tree.`,
+      );
+      return undefined;
+    }
+    this.removeNode(parent);
+    parent.children = children;
+    this.addNode(parent);
+    await this.fireNodeRefreshed(parent);
+    return parent;
+  };
+
+  protected removeNode = (node: TreeNode | undefined): void => {
+    if (CompositeTreeNode.is(node)) {
+      node.children.forEach((child) => this.removeNode(child));
+    }
+    if (node) {
+      delete this.nodes[node.id];
+    }
+  };
+
+  protected getRootNode(node: TreeNode): TreeNode {
+    if (node.parent === undefined) {
+      return node;
+    }
+    return this.getRootNode(node.parent);
+  }
+
+  protected addNode(node: TreeNode | undefined): void {
+    if (node) {
+      this.nodes[node.id] = node;
+    }
+    if (CompositeTreeNode.is(node)) {
+      const { children } = getOrigin(node);
+      children.forEach((child, index) => {
+        CompositeTreeNode.setParent(child, index, node);
+        this.addNode(child);
+      });
+    }
+  }
+
+  async markAsBusy(raw: TreeNode, ms: number, token: CancellationToken): Promise<void> {
+    const node = this.validateNode(raw);
+    if (node) {
+      await this.doMarkAsBusy(node, ms, token);
+    }
+  }
+  protected async doMarkAsBusy(
+    node: Mutable<TreeNode>,
+    ms: number,
+    token: CancellationToken,
+  ): Promise<void> {
+    try {
+      await timeout(ms, token);
+      this.doSetBusy(node);
+      token.onCancellationRequested(() => this.doResetBusy(node));
+    } catch {
+      /* no-op */
+    }
+  }
+  protected doSetBusy(node: Mutable<TreeNode>): void {
+    const oldBusy = node.busy || 0;
+    node.busy = oldBusy + 1;
+    if (oldBusy === 0) {
+      this.onDidChangeBusyEmitter.fire(node);
+    }
+  }
+  protected doResetBusy(node: Mutable<TreeNode>): void {
+    const oldBusy = node.busy || 0;
+    if (oldBusy > 0) {
+      node.busy = oldBusy - 1;
+      if (node.busy === 0) {
+        this.onDidChangeBusyEmitter.fire(node);
+      }
+    }
+  }
+}

package/src/app/tree/tree-iterator.ts

@@ -0,0 +1,243 @@
+import { equals } from '../../observable/index.js';
+
+import type { TreeNode } from './tree.js';
+import { CompositeTreeNode } from './tree.js';
+import { ExpandableTreeNode } from './tree-expansion.js';
+
+export type TreeIterator = {
+  //
+} & Iterator<TreeNode>;
+
+export namespace TreeIterator {
+  export type Options = {
+    readonly pruneCollapsed: boolean;
+    readonly pruneSiblings: boolean;
+  };
+
+  export const DEFAULT_OPTIONS: Options = {
+    pruneCollapsed: false,
+    pruneSiblings: false,
+  };
+}
+
+export namespace Iterators {
+  /**
+   * Generator for depth first, pre-order tree traversal iteration.
+   */
+  export function* depthFirst<T>(
+    root: T,
+    children: (node: T) => T[] | undefined,
+    include: (node: T) => boolean = () => true,
+  ): IterableIterator<T> {
+    const stack: T[] = [];
+    stack.push(root);
+    while (stack.length > 0) {
+      const top = stack.pop()!;
+      yield top;
+      stack.push(...(children(top) || []).filter(include).reverse());
+    }
+  }
+
+  /**
+   * Generator for breadth first tree traversal iteration.
+   */
+  export function* breadthFirst<T>(
+    root: T,
+    children: (node: T) => T[] | undefined,
+    include: (node: T) => boolean = () => true,
+  ): IterableIterator<T> {
+    const queue: T[] = [];
+    queue.push(root);
+    while (queue.length > 0) {
+      const head = queue.shift()!;
+      yield head;
+      queue.push(...(children(head) || []).filter(include));
+    }
+  }
+
+  /**
+   * Returns with the iterator of the argument.
+   */
+  export function asIterator<T>(elements: readonly T[]): IterableIterator<T> {
+    return elements.slice()[Symbol.iterator]();
+  }
+
+  /**
+   * Returns an iterator that cycles indefinitely over the elements of iterable.
+   *  - If `start` is given it starts the iteration from that element. Otherwise, it starts with the first element of the array.
+   *  - If `start` is given, it must contain by the `elements` array. Otherwise, an error will be thrown.
+   *
+   * **Warning**: Typical uses of the resulting iterator may produce an infinite loop. You should use an explicit break.
+   */
+  export function* cycle<T>(elements: readonly T[], start?: T): IterableIterator<T> {
+    const copy = elements.slice();
+    let index = start ? copy.indexOf(start) : 0;
+    if (index === -1) {
+      throw new Error(`${start} is not contained in ${copy}.`);
+    }
+    while (true) {
+      yield copy[index];
+      index++;
+      if (index === copy.length) {
+        index = 0;
+      }
+    }
+  }
+}
+export abstract class AbstractTreeIterator implements TreeIterator, Iterable<TreeNode> {
+  protected readonly delegate: IterableIterator<TreeNode>;
+  protected readonly options: TreeIterator.Options;
+  protected readonly root: TreeNode;
+
+  constructor(root: TreeNode, options?: Partial<TreeIterator.Options>) {
+    this.root = root;
+    this.options = {
+      ...TreeIterator.DEFAULT_OPTIONS,
+      ...options,
+    };
+    this.delegate = this.iterator(this.root);
+  }
+
+  // tslint:disable-next-line:typedef
+  [Symbol.iterator]() {
+    return this.delegate;
+  }
+
+  next(): IteratorResult<TreeNode> {
+    return this.delegate.next();
+  }
+
+  protected abstract iterator(node: TreeNode): IterableIterator<TreeNode>;
+
+  protected children(node: TreeNode): TreeNode[] | undefined {
+    if (!CompositeTreeNode.is(node)) {
+      return undefined;
+    }
+    if (this.options.pruneCollapsed && this.isCollapsed(node)) {
+      return undefined;
+    }
+    return node.children.slice();
+  }
+
+  protected isCollapsed(node: TreeNode): boolean {
+    return ExpandableTreeNode.isCollapsed(node);
+  }
+
+  protected isEmpty(nodes: TreeNode[] | undefined): boolean {
+    return nodes === undefined || nodes.length === 0;
+  }
+}
+
+export class DepthFirstTreeIterator extends AbstractTreeIterator {
+  protected iterator(root: TreeNode): IterableIterator<TreeNode> {
+    return Iterators.depthFirst(root, this.children.bind(this));
+  }
+}
+
+export class BreadthFirstTreeIterator extends AbstractTreeIterator {
+  protected iterator(root: TreeNode): IterableIterator<TreeNode> {
+    return Iterators.breadthFirst(root, this.children.bind(this));
+  }
+}
+
+/**
+ * This tree iterator visits all nodes from top to bottom considering the following rules.
+ *
+ * Let assume the following tree:
+ * ```
+ *   R
+ *   |
+ *   +---1
+ *   |   |
+ *   |   +---1.1
+ *   |   |
+ *   |   +---1.2
+ *   |   |
+ *   |   +---1.3
+ *   |   |    |
+ *   |   |    +---1.3.1
+ *   |   |    |
+ *   |   |    +---1.3.2
+ *   |   |
+ *   |   +---1.4
+ *   |
+ *   +---2
+ *       |
+ *       +---2.1
+ * ```
+ * When selecting `1.2` as the root, the normal `DepthFirstTreeIterator` would stop on `1.2` as it does not have children,
+ * but this iterator will visit the next sibling (`1.3` and `1.4` but **not** `1.1`) nodes. So the expected traversal order will be
+ * `1.2`, `1.3`, `1.3.1`, `1.3.2`,  and `1.4` then jumps to `2` and continues with `2.1`.
+ */
+export class TopDownTreeIterator extends AbstractTreeIterator {
+  protected iterator(root: TreeNode): IterableIterator<TreeNode> {
+    const doNext = this.doNext.bind(this);
+    return (function* (): IterableIterator<TreeNode> {
+      let maybeNext: TreeNode | undefined = root;
+      let next = maybeNext;
+      while (maybeNext) {
+        next = maybeNext;
+        yield next;
+        maybeNext = doNext(next);
+      }
+    })();
+  }
+
+  protected doNext(node: TreeNode): TreeNode | undefined {
+    return this.findFirstChild(node) || this.findNextSibling(node);
+  }
+
+  protected findFirstChild(node: TreeNode): TreeNode | undefined {
+    return (this.children(node) || [])[0];
+  }
+
+  protected findNextSibling(node: TreeNode | undefined): TreeNode | undefined {
+    if (!node) {
+      return undefined;
+    }
+    if (this.options.pruneSiblings && equals(node, this.root)) {
+      return undefined;
+    }
+    if (node.nextSibling) {
+      return node.nextSibling;
+    }
+    return this.findNextSibling(node.parent);
+  }
+}
+
+/**
+ * Unlike other tree iterators, this does not visit all the nodes, it stops once it reaches the root node
+ * while traversing up the tree hierarchy in an inverse pre-order fashion. This is the counterpart of the `TopDownTreeIterator`.
+ */
+export class BottomUpTreeIterator extends AbstractTreeIterator {
+  protected iterator(root: TreeNode): IterableIterator<TreeNode> {
+    const doNext = this.doNext.bind(this);
+    return (function* (): IterableIterator<TreeNode> {
+      let maybeNext: TreeNode | undefined = root;
+      let next = maybeNext;
+      while (maybeNext) {
+        next = maybeNext;
+        yield next;
+        maybeNext = doNext(next);
+      }
+    })();
+  }
+
+  protected doNext(node: TreeNode): TreeNode | undefined {
+    const { previousSibling } = node;
+    const lastChild = this.lastChild(previousSibling);
+    return lastChild || node.parent;
+  }
+
+  protected lastChild(node: TreeNode | undefined): TreeNode | undefined {
+    const children = node ? this.children(node) : [];
+    if (this.isEmpty(children)) {
+      return node;
+    }
+    if (CompositeTreeNode.is(node)) {
+      const lastChild = CompositeTreeNode.getLastChild(node);
+      return this.lastChild(lastChild);
+    }
+    return undefined;
+  }
+}

package/src/app/tree/tree-label-provider.ts

@@ -0,0 +1,23 @@
+import { singleton } from '../../ioc/index.js';
+
+import { LabelProviderContribution } from '../label/label-provider.js';
+
+import { TreeNode } from './tree.js';
+
+@singleton({ contrib: LabelProviderContribution })
+export class TreeLabelProvider implements LabelProviderContribution {
+  canHandle(element: Record<any, any>): number {
+    return TreeNode.is(element) ? 50 : 0;
+  }
+
+  getIcon(node: TreeNode): string {
+    return node.icon || '';
+  }
+
+  getName(node: TreeNode): string {
+    return node.name || '';
+  }
+  getLongName(node: TreeNode): string {
+    return node.description || '';
+  }
+}