@teambit/harmony 0.2.10 → 0.3.1

package/harmony-config/harmony-config.ts

@@ -0,0 +1,49 @@
+import { stringify, assign } from 'comment-json';
+import { join } from 'path';
+import { readConfigFile } from './config-reader';
+
+const userHome = require('user-home');
+
+export type ConfigOptions = {
+  cwd?: string;
+  global?: GlobalConfigOpts;
+  shouldThrow?: boolean;
+};
+
+export type GlobalConfigOpts = {
+  dir?: string;
+  name: string;
+};
+
+const defaultConfig = {
+  cwd: process.cwd(),
+  shouldThrow: true,
+};
+
+export class HarmonyConfig {
+  constructor(private raw: Record<string, any>) {}
+
+  toObject() {
+    return this.raw;
+  }
+
+  toString() {
+    return stringify(this.raw);
+  }
+
+  static load(fileName: string, opts?: ConfigOptions) {
+    const mergedOpts = Object.assign(defaultConfig, opts);
+    const config = readConfigFile(join(mergedOpts.cwd, fileName), mergedOpts.shouldThrow);
+
+    if (mergedOpts.global) {
+      return HarmonyConfig.loadGlobal(mergedOpts.global, config);
+    }
+
+    return new HarmonyConfig(config);
+  }
+
+  static loadGlobal(globalOpts: GlobalConfigOpts, config: any = {}) {
+    const globalConfig = readConfigFile(join(globalOpts.dir || userHome, globalOpts.name), false);
+    return new HarmonyConfig(assign(config, globalConfig));
+  }
+}

package/harmony-config/index.ts

@@ -0,0 +1 @@
+export { HarmonyConfig as Config } from './harmony-config';

package/harmony.docs.mdx

@@ -0,0 +1,250 @@
+---
+description: Harmony is an abstract extension system you can use to make any software extendable and composable. It is the engine that drives Bit extensibility and composability.
+labels: ['aspect', 'composition', 'extendability']
+---
+
+## Basic features
+
+Harmony allows you to implement Aspects as the main building blocks that compose your software. Each Aspect has:
+
+* Dependency declaration - Where you declare other Aspects as dependencies.
+* Dependency injection - An Aspect gets providers for all its dependencies.
+* Slots - An easy way for an Aspect to provide API for another aspect to hook into any of its processes.
+* Multiple runtimes - Aspect can annotate in which runtimes it can run (for example providing functionality to run on the server and on the browser).
+
+## Harmony config file
+
+Use a config file to describe your desired composition of Aspects and their configuration. Harmony uses a basic JSON syntax, where each key is an aspect.
+
+```json
+{
+  "teambit.dependencies/dependency-resolver": {}, // load an Aspect without providing configuration
+  "teambit.workspace/workspace": {                // Load an Aspect with configuration
+    "name": "bit",
+    "icon": "https://static.bit.dev/bit-logo.svg",
+}
+```
+
+## Define an aspect
+
+Harmony Aspect is  an object that implements the `ExtensionManifest` interface
+
+```js
+export type ExtensionManifest = {
+  /**
+   * Aspect's name.
+   */
+  name: string;
+
+  /**
+   * Aspect unique ID.
+   */
+  id?: string;
+
+  /**
+   * Array of dependencies.
+   * These other Aspects to be installed and resolved prior to this Aspect activation.
+   */
+  dependencies?: ExtensionManifest[];
+
+  /**
+   * Reference to the Aspect factory function.
+   */
+  provider?: ProviderFn;
+
+  /**
+   * Default Aspect configuration. 
+   */
+  defaultConfig?: object;
+
+  /**
+   * Alias to the provider.
+   */
+  provide?: ProviderFn;
+
+  /**
+   * Array of slots the Aspect exposes.
+   */
+  slots?: SlotProvider<unknown>[],
+
+  /**
+   * Additional keys which might be expected by other Aspects.
+   */
+  [key: string]: any;
+}
+```
+
+## Programmatic API
+
+### Static API
+
+```js
+// Create instance of harmony with the provided aspects, on specific runtime, with provided config
+static async load(aspects: Aspect[], runtime: string, globalConfig: GlobalConfig) {
+```
+
+### Instance API
+
+```js
+// load an Aspect into the dependency graph
+async load(extensions: ExtensionManifest[])
+
+// set extensions during Harmony runtime.
+async set(extensions: ExtensionManifest[])
+
+export type RequireFn = (aspect: Extension, runtime: RuntimeDefinition) => Promise<void>;
+
+// Start harmony. 
+// The require function is a function that get's the aspect and its runtime, and knows to require/load it
+async run(requireFn?: RequireFn) 
+```
+
+## Assumptions
+
+* Harmony does not allow circular dependencies between Aspects.
+
+<!--
+
+-------------------------for reference only - to remove ------------------
+
+## composition model
+Harmony proposes a graph composition model.
+composition model should allow:
+
+- full control over composition including dependency composition.
+- easy overrides mechanism for configs.
+- full encapsulation of an extension. 
+
+bit.config.js
+```js
+import FlowSchemaPlugin from '@bit/plugins.flow-schema';
+
+export default () => {
+  return [ // returns an array of PluginInstance
+    [FlowSchemaPlugin, {
+
+    }],
+    [ReactSchemaPlugin, {
+      eslintrc: './.eslintrc'
+    }]
+  ];
+}
+```
+
+configured extensions in bit.json
+```json
+{
+  "extensions": {
+    "bit.envs/eslint@0.0.4": {
+      "eslintrc": "./.eslintrc"
+    },
+    "bit.envs/babel@0.0.1": {
+      "babelrc": "./.babelrc",
+      "strict": true,
+      "__alias": "compile"
+    },
+    "bit.envs/webpack@0.0.1": {
+      "config": "./webpack.config.js",
+      "mode": "prod",
+      "__alias": "bundle"
+    },
+    "bit.envs/mocha@0.0.1": {
+      "reporter": "json",
+      "mochaOptions": "./mocha.opts",
+      "__alias": "test-mocha"
+    }
+  },
+  "pipes": {
+    "tag": [""]
+  },
+  "dist": {
+    "target": "",
+    "entry": ""
+  }
+}
+```
+
+### Open questions
+- How do I install a Bit extensions? Where the component is configured?
+- Is the extension installed with Bit/NPM?
+- What's the impl. behind `bit use <plugin/extension name>`
+- maybe an composition model can co-exist as json and js? what are the tradeoffs?
+
+## extension registration
+```js
+import { register } from 'harmony';
+import { DocGen } from '@bit/bit.exts.doc-gen';
+
+const extensions = register([DocGen]);
+```
+
+## lifecycle event invocation
+
+```js
+import { invoke } from 'harmony';
+
+invoke('tag', ...data);
+```
+
+## lifecycle event registration
+```js
+import { Lifecycle } from 'harmony';
+
+@Lifecycle(Tag);
+function tag() {
+  
+}
+```
+
+## state / schema management
+```ts
+@Lifecycle(Tag)
+function tag(component: Component) {
+  const docs = component.get('docs'); // returns `Maybe` type?
+  const docs: Docs = docs.get();
+}
+```
+
+## function extension 
+
+```js
+export default function foo() {
+  context.a
+}
+```
+
+## configuration
+an extension can declaratively ask for configuration type. this can be reflected
+- extensions can be configured during instantiation.
+- configuration types can be built from multiple sources
+
+## context
+- standard context can be shared between all extensions in the same instance.
+
+## extension composition
+- hook invocation from an extension
+- extension dependencies? how can an extension declare a dependency as part of its execution? 
+- contextual/namespaced hooks
+- config api
+
+## extension resolution
+```js
+import { resolve } from 'harmony';
+
+const extension = resolve('doc-gen');
+```
+
+## Questions (?)
+- can extensions be added/configured during runtime? DI
+- is there a difference between extension composition to registration?
+- how to make autocomplete work for hooks?
+- how to avoid unintentional hook invocation (decorators?) 
+- how to declare a new hook..
+- schema validator
+- dev experience of an extension.
+- how do manage different runtime environments? should I? Why is that relevant?
+- runtime capsules?
+- how can one extension run from both server and client? how capsule is related?
+- in which process extensions will run from? also, what will happen from the backend?
+- 
+-->

package/harmony.spec.old.ts

@@ -0,0 +1,177 @@
+import { Harmony } from './harmony';
+// import { BitExt } from '../../bit/dist/extensions/bit';
+// import { BaseCompiler } from './fixtures/base-compiler';
+// import { TypeScript } from './fixtures/typescript/typescript';
+// import { Babel } from './fixtures/babel/babel.extension';
+// import { Slot, SlotRegistry } from './slots';
+// import { start } from 'repl';
+// import { ExtensionManifest } from './extension';
+import { ReactAspect } from './fixtures/aspects/react/react.aspect';
+import { ReactCLI } from './fixtures/aspects/react/react.cli';
+import { ReactUI } from './fixtures/aspects/react/react.ui';
+
+describe('Harmony', () => {
+  describe('run()', () => {
+  //   it('should return a string', async () => {
+  //     const manifest = {
+  //       name: 'HelloWorld',
+  //       provider: async () => 'hello world'
+  //     };
+  //     await harmony.run(manifest);
+  //     expect(harmony.get('HelloWorld')).eql('hello world');
+  //   });
+
+  //   it('should load an array of different extensions', async () => {
+  //     await harmony.run([BaseCompiler, TypeScript]);
+  //     const compiler = harmony.get<BaseCompiler>('BaseCompiler')
+  //     const typescript = harmony.get<TypeScript>('typescript')      
+
+  //     expect(typescript.compile()).to.eq('hello world');
+  //     expect(compiler.compile()).to.eq('hello world');
+  //   });
+
+  //   it('should load extensions with slots', async () => {
+  //     class Env {
+  //       build () {
+  //         return 'react built';
+  //       }
+  //     }
+
+  //     it('extension instance should include an ID', async () => {
+  //       const React = { 
+  //         name: '@teambit/react', 
+  //         dependencies: [],
+  //         provide: async () => {} 
+  //       };      
+  
+  //       await harmony.run([React]);
+  //       const react = harmony.get<any>(React.name);  
+  //       expect(react.id).to.eq(React.name);
+  //     });
+
+  //     const Envs: ExtensionManifest = { 
+  //       name: '@teambit/envs', 
+  //       slots: [Slot.withType<Env>()],
+  //       provider: async ([], config: {env: string}, [envSlot]: [SlotRegistry<Env>]) => {
+  //         return {
+  //           register: (env: Env) => {
+  //             envSlot.register(env);
+  //           },
+
+  //           start() {
+  //             const instance = envSlot.get(config.env);
+  //             if (!instance) throw new Error('could not find envs');
+  //             return instance.build();
+  //           }
+  //         };
+  //       }
+  //     };
+
+  //     const React = { 
+  //       name: '@teambit/react', 
+  //       dependencies: [Envs],
+  //       provide: async ([envs]: [{ register: (env: Env) => void }], config: {}) => {
+  //         envs.register(new Env());
+  //       } 
+  //     };      
+
+  //     const harmony = Harmony.load([Envs, React], {
+  //       '@teambit/envs': {
+  //         env: '@teambit/react'
+  //       }
+  //     });
+
+  //     await harmony.run([Envs, React]);
+
+  //     const envs = harmony.get<any>(Envs.name);
+  //     expect(envs.start()).to.eq('react built');
+  //   });
+
+  //   it('should load extensions with config', async () => {
+  //     const e1 = { 
+  //       name: '@teambit/typescript', 
+
+  //       provider: async ([], config: { declarations: boolean }) => {
+  //         return {
+  //           get: () => {
+  //             return config.declarations || false
+  //           }
+  //         };
+  //       }
+  //     };
+
+  //     const e2 = { name: '@teambit/react', defaultConfig: {ts: false}, provide: async ([], config: any) => {
+  //        return {
+  //          config: config.ts
+  //        };
+  //       } 
+  //     };
+
+  //     const harmony = Harmony.load([e1], {
+  //       '@teambit/typescript': {
+  //         declarations: true
+  //       },
+  //     });
+  //     await harmony.run([e1]);
+
+  //     const ts = harmony.get<{get: () => {}}>('@teambit/typescript');
+  //     expect(ts.get()).to.eq(true);
+
+  //     harmony.config.set('@teambit/react', {ts: true});
+  //     await harmony.set([e2]);
+  //     const react = harmony.get<{[key: string]: object}>('@teambit/react');
+  //     expect(react.config).to.eq(true);
+  //   });
+  
+  //   it('should invoke a class extension method', async () => {
+  //     await harmony.run(BaseCompiler);
+  //     const compiler = harmony.get<BaseCompiler>('BaseCompiler')
+  //     expect(compiler.compile()).to.eq('hello world');
+  //   });
+
+  //   it('should invoke a class extension with configured dependencies', async () => {
+  //     await harmony.run(TypeScript);
+  //     const typescript = harmony.get<TypeScript>('typescript')      
+  //     expect(typescript.compile()).to.eq('hello world');
+  //   });
+
+  //   it('should use prefer id over name', async () => {
+  //     const dependency = {
+  //       name: 'dependencyName',
+  //       id: 'dependencyId',
+  //       provider: async () => 'hello world'
+  //     };
+  //     const dependent = {
+  //       name: 'dependentName',
+  //       id: 'dependentId',
+  //       dependencies: [dependency],
+  //       provider: async () => 'hello world'
+  //     };
+  //     await harmony.run(dependent);
+  //     const ids = harmony.extensionsIds;  
+  //     expect(ids).to.contain('dependencyId');
+  //     expect(ids).to.contain('dependentId');
+  //   });
+
+  //   it('should execute bit core extension graph', async () => {
+  //     // const bit = await Harmony.run(BitExt);
+  //   });
+
+  //   it('should register during run', async () => {
+  //     const compiler = await harmony.run(Babel);
+  //   });
+
+    // it('should execute an aspect in the cli runtime', async() => {
+    //   const harmony = await Harmony.load([ReactAspect], 'cli', {});
+    //   await harmony.run();
+    //   const react = harmony.get<ReactCLI>('@teambit/react');
+    // })
+
+    // it('should execute an aspect in the ui runtime', async() => {
+    //   const harmony = await Harmony.load([ReactAspect], 'ui', {});
+    //   await harmony.run();
+    //   const react = harmony.get<ReactUI>('@teambit/react');
+    //   expect(react.render()).toBeTruthy;
+    // })
+  });
+});

package/harmony.ts

@@ -0,0 +1,146 @@
+import 'reflect-metadata';
+import ExtensionGraph from './extension-graph/extension-graph';
+import { ExtensionLoadError } from './exceptions';
+import { Extension, ExtensionManifest } from './extension';
+import { asyncForEach } from './utils';
+import { Config } from './config';
+import { Aspect } from './aspect';
+import { Runtimes } from './runtimes/runtimes';
+import { RuntimeDefinition } from './runtimes/runtime-definition';
+import { RuntimeNotDefined } from './runtimes/exceptions';
+
+export type GlobalConfig = {
+  [key: string]: object
+};
+
+export type RequireFn = (aspect: Extension, runtime: RuntimeDefinition) => Promise<void>;
+
+export class Harmony {
+  constructor(
+    /**
+     * extension graph
+     */
+    readonly graph: ExtensionGraph,
+
+    /**
+     * harmony top level config
+     */
+    readonly config: Config,
+
+    readonly runtimes: Runtimes,
+
+    readonly activeRuntime: string
+  ) {}
+
+  public current: string|null = null;
+
+  private runtime: RuntimeDefinition | undefined;
+
+  /**
+   * list all registered extensions
+   */
+  get extensions() {
+    return this.graph.nodes;
+  }
+
+  /**
+   * list all registered extensions ids
+   */
+  get extensionsIds() {
+    return [...this.graph.nodes.keys()];
+  }
+
+  /**
+   * load an Aspect into the dependency graph.
+   */
+  async load(extensions: ExtensionManifest[]) {
+    return this.set(extensions);
+  }
+
+  /**
+   * set extensions during Harmony runtime.
+   * hack!
+   */
+  async set(extensions: ExtensionManifest[]) {
+    this.graph.load(extensions);
+    // Only load new extensions and their dependencies
+    const extensionsToLoad = extensions.map((ext) => { 
+      // @ts-ignore
+      return Reflect.getMetadata('harmony:name', ext) || ext.id || ext.name; 
+    });
+  
+    // @ts-ignore
+    await this.graph.enrichRuntime(this.runtime, this.runtimes, () => {});
+    // @ts-ignore
+    const subgraphs = this.graph.successorsSubgraph(extensionsToLoad);
+    if (subgraphs) {
+      const executionOrder = subgraphs.toposort(true);
+      await asyncForEach(executionOrder, async (ext: Extension) => {
+        if (!this.runtime) throw new RuntimeNotDefined(this.activeRuntime);
+        await this.runOne(ext, this.runtime);
+      });
+    }
+  }
+
+  private async runOne(extension: Extension, runtime: RuntimeDefinition) {
+    if (extension.loaded) return;
+    // create an index of all vertices in dependency graph
+    const deps = this.graph.getRuntimeDependencies(extension, runtime);
+    const instances = deps.map(extension => extension.instance);
+
+    try {
+      return extension.__run(instances, this, runtime);
+    } catch (err) {
+      throw new ExtensionLoadError(extension, err);
+    }
+  }
+
+  getDependencies(aspect: Extension) {
+    if (!this.runtime) throw new RuntimeNotDefined(this.activeRuntime);
+    return this.graph.getRuntimeDependencies(aspect, this.runtime);
+  }
+
+  initExtension(id: string) {
+    this.current = id;
+  }
+
+  endExtension() {
+    this.current = null;
+  }
+
+  /**
+   * get an extension from harmony.
+   */
+  get<T>(id: string): T {
+    const extension = this.graph.get(id);
+    if (!extension || !extension.instance) throw new Error(`failed loading extension ${id}`);
+    return extension.instance;
+  }
+
+  resolveRuntime(name: string): RuntimeDefinition {
+    return this.runtimes.get(name);
+  }
+
+  async run(requireFn?: RequireFn) {
+    const runtime = this.resolveRuntime(this.activeRuntime);
+    this.runtime = runtime;
+    const defaultRequireFn: RequireFn = async (aspect: Extension, runtime: RuntimeDefinition) => {
+      const runtimeFile = runtime.getRuntimeFile(aspect.files);
+      if (!runtimeFile) return;
+      // runtime.require(runtimeFile);
+    };
+    // requireFn ? await requireFn(aspect, runtime) : defaultRequireFn(this.graph);
+    await this.graph.enrichRuntime(runtime, this.runtimes, requireFn || defaultRequireFn);
+    
+    const executionOrder = this.graph.byExecutionOrder();
+    await asyncForEach(executionOrder, async (ext: Extension) => {
+      await this.runOne(ext, runtime);
+    });
+  }
+  
+  static async load(aspects: Aspect[], runtime: string, globalConfig: GlobalConfig) {
+    const aspectGraph = ExtensionGraph.from(aspects as any);
+    const runtimes = await Runtimes.load(aspectGraph);
+    return new Harmony(aspectGraph, Config.from(globalConfig), runtimes, runtime);
+  }
+}

package/index.ts

@@ -0,0 +1,10 @@
+export { ExtensionDecorator as Extension, register, HookRegistry, hook, provider, createHook } from './extension';
+export { Harmony } from './harmony';
+export { Slot, SlotRegistry } from './slots';
+export { ProviderFn } from './types';
+export { ExtensionManifest } from './extension/extension-manifest';
+export { HarmonyError } from './exceptions/harmony-error';
+export { Aspect } from './aspect';
+export { RuntimeDefinition, RuntimeManifest } from './runtimes';
+export { default as AspectGraph } from './extension-graph/extension-graph';
+export { GlobalConfig } from './harmony';