@teambit/harmony 0.0.0-19ea14143ef7d5f4e4daa6e8ac8a8c97c9d683d5

package/dist/utils/async-for-each.d.ts

@@ -0,0 +1,5 @@
+/**
+ * asynchronously iterate an array.
+ * :TODO improve function singature
+ */
+export declare function asyncForEach(array: any[], callback: any): Promise<void>;

package/dist/utils/async-for-each.js

@@ -0,0 +1,25 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asyncForEach = asyncForEach;
+/**
+ * asynchronously iterate an array.
+ * :TODO improve function singature
+ */
+function asyncForEach(array, callback) {
+    return __awaiter(this, void 0, void 0, function* () {
+        for (let index = 0; index < array.length; index += 1) {
+            // eslint-disable-next-line no-await-in-loop
+            yield callback(array[index], index, array);
+        }
+    });
+}
+//# sourceMappingURL=async-for-each.js.map

package/dist/utils/async-for-each.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-for-each.js","sourceRoot":"","sources":["../../utils/async-for-each.ts"],"names":[],"mappings":";;;;;;;;;;;AAIA,oCAKC;AATD;;;GAGG;AACH,SAAsB,YAAY,CAAC,KAAY,EAAE,QAAa;;QAC5D,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YACrD,4CAA4C;YAC5C,MAAM,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;CAAA"}

package/dist/utils/index.d.ts

@@ -0,0 +1 @@
+export { asyncForEach } from './async-for-each';

package/dist/utils/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asyncForEach = void 0;
+var async_for_each_1 = require("./async-for-each");
+Object.defineProperty(exports, "asyncForEach", { enumerable: true, get: function () { return async_for_each_1.asyncForEach; } });
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../utils/index.ts"],"names":[],"mappings":";;;AAAA,mDAAgD;AAAvC,8GAAA,YAAY,OAAA"}

package/exceptions/extension-init-error.ts

@@ -0,0 +1 @@
+export class ExtensionInstantiationException extends Error {}

package/exceptions/extension-load-error.ts

@@ -0,0 +1,28 @@
+import { Extension } from '../extension/extension';
+
+export default class ExtensionLoadError extends Error {
+  constructor(
+    /**
+     * failed extension
+     */
+    private extension: Extension,
+
+    /**
+     * extension error
+     */
+    private originalError: Error,
+
+    /**
+     * extension formatted / handled error message
+     */
+    private msg?: string
+  ) {
+    super();
+  }
+
+  toString() {
+    return `failed to load extension: ${this.extension.name} with error:
+
+${this.msg || this.originalError.stack}`;
+  }
+}

package/exceptions/extension-potential-circular.ts

@@ -0,0 +1,24 @@
+import { Extension } from '../extension/extension';
+import { HarmonyError } from './harmony-error';
+
+export default class ExtensionPotentialCircular extends HarmonyError {
+  constructor(
+    /**
+     * failed extension
+     */
+    private extension: Extension,
+
+    /**
+     * valid extensions dependencies
+     */
+    private validDeps: Extension[]
+  ) {
+    super();
+  }
+
+  toString() {
+    return `Failed to load the dependencies for extension . 
+This may result from a wrong import or from circular dependencies in imports. 
+The following dependencies succeeded loading:`;
+  }
+}

package/exceptions/harmony-already-running.ts

@@ -0,0 +1 @@
+export class HarmonyAlreadyRunning extends Error {}

package/exceptions/harmony-error.ts

@@ -0,0 +1 @@
+export class HarmonyError extends Error {}

package/exceptions/hook-not-found.ts

@@ -0,0 +1 @@
+export class HookNotFound extends Error {}

package/exceptions/index.ts

@@ -0,0 +1,5 @@
+export { default as ExtensionLoadError } from './extension-load-error';
+export { default as ExtensionPotentialCircular } from './extension-potential-circular';
+export { HarmonyAlreadyRunning } from './harmony-already-running';
+export { HookNotFound } from './hook-not-found';
+export { ExtensionInstantiationException } from './extension-init-error';

package/extension/any-extension.ts

@@ -0,0 +1,8 @@
+import { Extension } from '../index';
+
+/**
+ * Class extension of type any. this class is indended for use inside Harmony
+ * where extension generics type relevance is low.
+ */
+
+// export class AnyExtension extends Extension {}

package/extension/decorator.ts

@@ -0,0 +1,126 @@
+import { HookNotFound } from '../exceptions';
+import { ExtensionManifest } from "./extension-manifest";
+// :TODO refactor this file asap
+
+export type ExtensionOptions = { 
+  dependencies?: ExtensionManifest[], 
+  name?: string 
+}
+
+const map: any = {};
+
+/**
+ * decorator for an Harmony extension.
+ */
+export function ExtensionDecorator({ name, dependencies }: ExtensionOptions = {}) {
+  function classDecorator<T extends {new(...args:any[]): {}}>(constructor:T) {
+    Reflect.defineMetadata('harmony:name', name || constructor.name, constructor);
+    Reflect.defineMetadata('harmony:dependencies', calculateDependnecies(constructor, dependencies), constructor)
+  }
+  
+  return classDecorator;
+}
+
+export function provider() {
+  return function(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
+    const keys = Reflect.getMetadata('design:paramtypes', descriptor);
+  }
+}
+
+// @hack todo: must be defined and assigned from a single location
+function providerFn(classExtension: any) {
+  return classExtension.provide ? classExtension.provide : classExtension.provider;
+}
+
+function calculateDependnecies(classExtension: any, deps?: ExtensionManifest[]): ExtensionManifest[] {
+  function fromMetadata() {
+    const provider = providerFn(classExtension)
+    if (provider) {
+    //   // TODO: check why Reflect.getMetadataKeys(provider) is empty and how to access method param types.
+    //   console.log(Reflect.getMetadataKeys(classExtension.provide))
+      return [];
+    }
+
+    return Reflect.getMetadata('design:paramtypes', classExtension);
+  }
+
+  const dependnecies = deps ? deps : fromMetadata() || [];
+  const hookDeps = classExtension.__hookDeps ? classExtension.__hookDeps : [];
+  return dependnecies.concat(hookDeps) || [];
+}
+
+// :TODO refactor this asap to handle harmony objects properly
+export function register(extension: ExtensionManifest, name?: string) {
+  return function(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
+    // if (!target.constructor.__hookDeps) Reflect.defineMetadata('harmony:subscriptions', [extension], target.constructor);
+    // else target.constructor.__hookDeps.push(extension);
+
+    const extensionName = Reflect.getMetadata('harmony:name', extension);
+    if (!map[extensionName]) {
+      map[extensionName] = {};
+    }
+
+    const hook = map[extensionName][name || propertyKey];
+    // if (!hook) throw new HookNotFound();
+    if (!hook) return;
+    hook.register(target[propertyKey]);
+  }
+}
+
+export function createHook() {
+  const randomId = Math.random().toString(36).substring(2);
+  map[randomId] = HookRegistry.create();
+  const decorator = function(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
+    const registry = map[randomId];
+    registry.register(descriptor.value);
+  }
+
+  decorator.hash = randomId;
+
+  return decorator;
+}
+
+export function hook(name?: string) {
+  return function(target: any, propertyKey: string) {
+    let instance = HookRegistry.create();
+    const extensionName = Reflect.getMetadata('harmony:name', target.constructor);
+    const hookName = name || propertyKey;
+
+    if (!map[extensionName]) map[extensionName] = {[hookName]: instance};
+    else map[extensionName][hookName] = instance;
+  
+    Object.defineProperty(target, propertyKey, {
+      get: () => {
+        return instance;
+      },
+      set: (value) => {
+        instance = value;
+      }
+    });
+  }
+}
+
+export class HookRegistry<T> {
+  constructor(
+    private fillers: T[],
+    readonly hash?: string
+  ) {}
+
+  register(filler: T) {
+    this.fillers.push(filler);
+  }
+
+  list() {
+    // return map[this.name][name] || [];
+    return this.fillers;
+  }
+
+  static of<T>(hook: any): HookRegistry<T> {
+    return map[hook.hash];
+  }
+
+  // hack due to https://github.com/microsoft/TypeScript/issues/4881
+  static create<T>() {
+    return new HookRegistry<T>([]);
+  }
+}

package/extension/extension-manifest.ts

@@ -0,0 +1,51 @@
+import { ProviderFn } from '../types';
+import { Slot, SlotProvider } from '../slots';
+
+export type ExtensionManifest = {
+  /**
+   * extension name.
+   */
+  name: string;
+
+  /**
+   * extension unique ID.
+   */
+  id?: string;
+
+  /**
+   * version of the extension
+   */
+  // version: string;
+
+  /**
+   * array of extension dependencies.
+   * these other extensions will be installed and resolved prior to this extension activation.
+   */
+  dependencies?: ExtensionManifest[];
+
+  /**
+   * reference to the extension factory function.
+   */
+  provider?: ProviderFn;
+
+  /**
+   * 
+   * default config of the extension. 
+   */
+  defaultConfig?: object;
+
+  /**
+   * alias to provider.
+   */
+  provide?: ProviderFn;
+
+  /**
+   * array of slots the extension is exposing.
+   */
+  slots?: SlotProvider<unknown>[],
+
+  /**
+   * any further keys which might be expected by other extensions.
+   */
+  [key: string]: any;
+}

package/extension/extension.ts

@@ -0,0 +1,142 @@
+import { ProviderFn } from '../types';
+import { Harmony } from '../harmony';
+import { ExtensionManifest } from './extension-manifest';
+import { ExtensionInstantiationException } from '../exceptions/extension-init-error';
+import { RuntimeDefinition } from '../runtimes';
+
+export type ExtensionProps = {
+  name: string;
+  // TODO: changes from any to something meaningful
+  dependencies: any[];
+  provider: ProviderFn;
+};
+
+/**
+ * harmony's extension definition. this can be used to define and extend `Harmony` applications.
+ */
+export class Extension {
+  constructor(
+    /**
+     * manifest of the extension.
+     */
+    readonly manifest: ExtensionManifest
+  ) {}
+
+  private _instance = null;
+
+  private _loaded = false;
+
+  /**
+   * returns the instance of the extension
+   */
+  get instance() {
+    return this._instance;
+  }
+
+  get name() {
+    const metadata = Reflect.getMetadata('harmony:name', this.manifest);
+    return metadata || this.manifest.id || this.manifest.name;
+  }
+
+  get id() {
+    return this.name;
+  }
+
+  get dependencies(): Extension[] {
+    const metadata = Reflect.getMetadata('harmony:dependencies', this.manifest);
+    return metadata || this.manifest.dependencies || [];
+  }
+
+  get provider() {
+    const metadata = Reflect.getMetadata('harmony:provider', this.manifest);
+    return metadata || this.manifest.provider;
+  }
+
+  get files() {
+    return this.manifest.files;
+  }
+
+  /**
+   * returns an indication of the extension already loaded (the provider run)
+   * We don't rely on the instance since an extension provider might return null
+   */
+  get loaded() {
+    return this._loaded;
+  }
+
+  toString(): string {
+    return JSON.stringify(this.name);
+  }
+
+  private buildSlotRegistries(slots: ((registerFn: () => void) => any)[], context: Harmony) {
+    return slots.map((slot) => {
+      return slot(() => {
+        return context.current;
+      });
+    });
+  }
+
+  get declareRuntime() {
+    return this.manifest.declareRuntime;
+  }
+
+  getRuntime(runtime: RuntimeDefinition) {
+    return this.manifest.getRuntime(runtime);
+  }
+
+  getRuntimes() {
+    return this.manifest.getRuntimes();
+  }
+
+  getSlots(extensionRuntime: any) {
+    if (extensionRuntime.slots && extensionRuntime.slots.length) {
+      return extensionRuntime.slots;
+    }
+
+    return this.manifest.slots || [];
+  }
+
+  getConfig(context: Harmony, extensionRuntime: any) {
+    const defaultConfig = extensionRuntime.defaultConfig || this.manifest.defaultConfig || {};
+    const config = context.config.get(this.name) || {};
+    return Object.assign({}, defaultConfig, config);
+  }
+
+  /**
+   * initiate Harmony in run-time.
+   */
+  async __run(dependencies: any[], context: Harmony, runtime: RuntimeDefinition) {
+    const name = this.name;
+    context.initExtension(name);
+    const extensionRuntime = this.getRuntime(runtime);
+    
+    if (!extensionRuntime) {
+      return undefined;
+    }
+
+    // @ts-ignore
+    const registries = this.buildSlotRegistries(this.getSlots(extensionRuntime), context);
+    const config = this.getConfig(context, extensionRuntime);
+
+    if (!this.loaded) {
+      if (extensionRuntime.provider) this._instance = await extensionRuntime.provider(dependencies, config, registries, context);
+      else {
+        try {
+          // @ts-ignore
+          this._instance = new extensionRuntime.manifest(...dependencies);
+        } catch(err) {
+          throw new ExtensionInstantiationException(err instanceof Error ? err.toString() : String(err));
+        }
+      };
+      // @ts-ignore adding the extension ID to the instance.
+      // this._instance.id = this.manifest.name;
+      // @ts-ignore adding the extension ID to the instance.
+      // this._instance.config = config;
+      this._loaded = true;
+      return this._instance;
+    }
+
+    context.endExtension();
+    return Promise.resolve(this.instance);
+  }
+}

package/extension/index.ts

@@ -0,0 +1,3 @@
+export { Extension, ExtensionProps } from './extension';
+export { ExtensionManifest } from './extension-manifest';
+export { ExtensionDecorator, register, hook, HookRegistry, provider, createHook } from './decorator';

package/extension-graph/extension-graph.ts

@@ -0,0 +1,165 @@
+import { Graph } from 'cleargraph';
+import { fromExtension, fromExtensions } from './from-extension';
+import { ExtensionManifest } from '../extension';
+import { Extension } from '../extension';
+import { RuntimeDefinition, Runtimes } from '../runtimes';
+import { RequireFn } from '../harmony';
+
+export type DependencyGraphOptions = {
+  getName?: (manifest: any) => string;
+};
+
+function getName(manifest: any) {
+  return Reflect.getMetadata('harmony:name', manifest) || manifest.id || manifest.name;
+}
+
+export type Edge = {
+  type: string,
+  runtime?: string
+};
+
+export default class DependencyGraph extends Graph<Extension, Edge> {
+  private cache = new Map<string, Extension>();
+
+  getRuntimeDependencies(aspect: Extension, runtime: RuntimeDefinition, options: DependencyGraphOptions = {}): Extension[] {
+    const dependencies = this.successors(aspect.name);
+    const runtimeDeps = this.successors(aspect.name, (edge) => {
+      if (!edge.runtime) return false;
+      return edge.runtime === runtime.name;
+    });
+    const runtimeManifest = aspect.getRuntime(runtime);
+    if (!runtimeManifest) return Array.from(dependencies.values());
+
+    if (runtimeDeps && runtimeDeps.size) return this.sortDeps(runtimeManifest.dependencies, Array.from(runtimeDeps.values()), options);
+    return this.sortDeps(runtimeManifest.dependencies, Array.from(dependencies.values()), options);
+  }
+
+  private sortDeps(originalDependencies: any[], targetDependencies: any[], options: DependencyGraphOptions = {}) {
+    const _originalDependencies = options.getName ? originalDependencies?.map((aspect) => {
+      if (!options.getName) return aspect;
+      aspect.id = options.getName(aspect);
+      return aspect;
+    }) || [] : originalDependencies;
+
+    return targetDependencies.sort((a, b) => {
+      return _originalDependencies.findIndex(item => item.id === a.id) - _originalDependencies.findIndex(item => item.id === b.id);
+    });
+  }
+
+  byExecutionOrder() {
+    return this.toposort(true);
+  }
+
+  private async enrichRuntimeExtension(id: string, aspect: Extension, runtime: RuntimeDefinition, runtimes: Runtimes, requireFn: RequireFn, options: DependencyGraphOptions = {}) {
+    await requireFn(aspect, runtime);
+    const runtimeManifest = aspect.getRuntime(runtime)
+    if (!runtimeManifest) return;
+    const deps = runtimeManifest.dependencies;
+    if (!deps) return;
+    const promises = deps.map(async (dep: any) => {
+      const depId = options.getName ? options.getName(dep): dep.id;
+      if (!this.hasNode(depId)) {
+        this.add(dep);
+        if (dep.declareRuntime) {
+          runtimes.add(dep.declareRuntime);
+        }
+        
+        const node = this.get(depId);
+        if (!node) return;
+        await requireFn(node, runtime);
+        await this.enrichRuntimeExtension(depId, this.get(depId), runtime, runtimes, requireFn);
+      }
+
+      this.setEdge(id, depId, {
+        runtime: runtime.name,
+        type: 'runtime-dependency'
+      });
+    });
+
+    return Promise.all(promises);
+  }
+
+  async enrichRuntime(runtime: RuntimeDefinition, runtimes: Runtimes, requireFn: RequireFn, options: DependencyGraphOptions = {}) {
+    const promises = Array.from(this.nodes.entries()).map(async ([id, aspect]) => {
+      return this.enrichRuntimeExtension(id, aspect, runtime, runtimes, requireFn, options);
+    });
+
+    return Promise.all(promises);
+  }
+
+  add(manifest: ExtensionManifest) {
+    const { vertices, edges } = fromExtension(manifest);
+    this.setNodes(vertices);
+    this.setEdges(edges);
+
+    return this;
+  }
+
+  load(extensions: ExtensionManifest[]) {
+    const newExtensions = extensions.filter((extension) => {
+      if (!extension.id) return false;
+      return !this.get(extension.id);
+    });
+    const { vertices, edges } = fromExtensions(newExtensions);
+    // Only set new vertices
+    this.setNodes(vertices, false); // false because we don't want to override already-loaded extensions
+    this.setEdges(edges);
+
+    return this;
+  }
+
+  // :TODO refactor this asap
+  getExtension(manifest: ExtensionManifest) {
+    const id = getName(manifest);
+    const cachedVertex = this.cache.get(id);
+    if (cachedVertex) return cachedVertex;
+
+    const res = this.node(id);
+    if (res) {
+      this.cache.set(res.name, res);
+      return res;
+    }
+
+    return null;
+  }
+
+  get extensions(): ExtensionManifest[] {
+    return Array.from(this.nodes.values());
+  }
+
+  get aspects() {
+    return this.extensions;
+  }
+
+  get(id: string): any {
+    const cachedVertex = this.cache.get(id);
+    if (cachedVertex) return cachedVertex;
+
+    const res = this.node(id);
+    if (res) {
+      this.cache.set(res.name, res);
+      return res;
+    }
+
+    return null;
+  }
+
+  /**
+   * build Harmony from a single extension.
+   */  
+  static fromRoot(extension: ExtensionManifest) {
+    const { vertices, edges } = fromExtension(extension);
+
+    return new DependencyGraph(vertices, edges);
+  }
+
+  /**
+   * build Harmony from set of extensions
+   */
+  static from(extensions: ExtensionManifest[], options: DependencyGraphOptions = {}) {
+    const { vertices, edges } = fromExtensions(extensions, options);
+
+    return new DependencyGraph(vertices, edges);
+  }
+}
+