@teambit/harmony 0.2.9 → 0.3.0

package/package.json

@@ -1,42 +1,55 @@
 {
   "name": "@teambit/harmony",
-  "version": "0.2.9",
-  "description": "abstract extension system",
+  "version": "0.3.0",
   "main": "dist/index.js",
-  "scripts": {
-    "test": "mocha --require ts-node/register/transpile-only --require source-map-support/register --recursive src/**/*.spec.ts src/**/**/*.spec.ts",
-    "start": "node dist/index.js",
-    "build": "tsc -d",
-    "clean": "rm -rf dist",
-    "watch": "tsc -d -w",
-    "prepublishOnly": "npm run clean && npm run build"
+  "componentId": {
+    "scope": "teambit.harmony",
+    "name": "harmony",
+    "version": "0.3.0"
   },
-  "files": [
-    "/dist"
-  ],
-  "keywords": [],
-  "author": "Ran Mizrahi <ran@bit.dev>",
-  "license": "MIT",
   "dependencies": {
+    "reflect-metadata": "^0.1.13",
     "cleargraph": "^5.6.0",
     "comment-json": "^3.0.3",
     "fs-extra": "^8.1.0",
-    "lodash": "^4.17.20",
-    "loud-rejection": "^1.6.0",
-    "reflect-metadata": "^0.1.13",
     "user-home": "^2.0.0"
   },
   "devDependencies": {
     "@types/comment-json": "^1.1.1",
     "@types/fs-extra": "^8.1.0",
-    "@types/chai": "^4.1.7",
-    "@types/lodash": "^4.14.159",
-    "@types/loud-rejection": "^1.6.0",
-    "@types/node": "^11.9.4",
-    "@types/semver": "^6.0.1",
-    "chai": "^4.2.0",
-    "mocha": "^6.2.2",
-    "ts-node": "^8.0.2",
-    "typescript": "^3.8.3"
-  }
+    "@babel/runtime": "7.12.18",
+    "@types/node": "12.20.4",
+    "@types/jest": "26.0.20"
+  },
+  "peerDependencies": {},
+  "license": "Apache-2.0",
+  "bit": {
+    "bindingPrefix": "@teambit",
+    "env": {},
+    "overrides": {
+      "devDependencies": {
+        "@babel/runtime": "7.12.18",
+        "@types/node": "12.20.4",
+        "@types/jest": "26.0.20"
+      }
+    }
+  },
+  "private": false,
+  "engines": {
+    "node": ">=12.22.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/teambit/harmony"
+  },
+  "description": "abstract extension system",
+  "keywords": [
+    "bit",
+    "bit-aspect",
+    "components",
+    "collaboration",
+    "harmony",
+    "aspects",
+    "extensions"
+  ]
 }

package/preview-1649080456374.js

@@ -0,0 +1 @@
+export const overview = [require('/Users/giladshoham/Library/Caches/Bit/capsules/0c2e8decf63b913c66a649e2a025161ea05f3ab6/teambit.harmony_harmony@0.3.0/dist/harmony.docs.mdx')]

package/readme.md

@@ -1,159 +1,80 @@
-# Harmony 
-
-Plugin
-Module
-Extension
-* Feature
-Plugin
-Trait
-* Component (could be a composition of other components)
-
-Plugability
-- Hook
-- Slot
-
-Harmony is the engine that drives Bit extensibility and composability.  
-It's an abstract extension system you can use to make any software extendable and composable.
-
-## composition model
-Harmony proposes a graph composition model.
-compoisiton model should allow:
-- full control over composition including dependency composition.
-- easy overrides mechanaism 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
-    [FlowScehmaPlugin, {
-
-    }],
-    [ReactSchemaPlugin, {
-      eslintrc: './.eslintrc'
-    }]
-  ];
-}
-```
+# Harmony
+Harmony is the engine that drives Bit extensibility and composability.
+It's an abstract extension system indended to make any software extendable and composable.
 
-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": ""
-  }
-}
+Harmony takes a "micro-kernel" approach and implements the near-minimum amount of software required to build any JavaScript system from independent components through composition.
+
+## Installation
+```bash
+$ bit install @teambit/harmony
 ```
 
-### 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?
+## Quick start
+```ts
+import { Harmony, Extension } from 'harmony';
 
-## extension registration
-```js
-import { register } from 'harmony';
-import { DocGen } from '@bit/bit.exts.docgen';
+@Extensioin
+class Person {
+  sayHello(name = 'world') {
+    return `hello ${name}!`;
+  }
+}
 
-const extensions = register([DocGen]);
+const person = Harmony.load(Person); 
+helloWorld.sayHello(); // returns 'hello world!'
 ```
 
-## lifecycle event invocation
-
-```js
-import { invoke } from 'harmony';
+## Component composition
 
-invoke('tag', ...data);
-```
+### DI
+```ts
+class Dude {
+  constructor(
+    private person: Person
+  ) {}
 
-## lifecycle event registration
-```js
-import { Lifecycle } from 'harmony';
+  sayHello() {
+    return this.person.sayHello('dude');
+  }
+};
 
-@Lifecycle(Tag);
-function tag() {
-  
-}
+Harmony.load([Dude]).sayHello(); // echos 'hello dude!'
 ```
 
-## state / schema management
+### Hooks
 ```ts
-@Lifecycle(Tag)
-function tag(component: Component) {
-  const docs = component.get('docs'); // returns `Maybe` type?
-  const docs: Docs = docs.get();
-}
-```
-
+@Extension()
+class CLI {
+  // @hook('command') commands = Hook.create<Command>();
+  static command() {
+    return Hook.create<Command>();
+  }
 
-## function extension 
+  run() {
+    const allCommands = this.commands.list(); // outputs all hook subscribers
+  }
+} 
 
-```js
-export default function foo() {
-  context.a
+@Extension()
+class Compiler {
+  
+  @command()
+  main() {
+    return {
+      synopsis: 'compile <path>',
+      render: () => <Box></Box>
+    };
+  }
 }
 ```
 
-## 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 configuration
 
-## 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');
-```
+## Extension metadata
 
-## 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 expereience of an extension.
-- how do manage different runtime environments? should I? Why is that relavent?
-- 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?
-- 
+## API reference
 
+## License
+Apache License, Version 2.0
 
+Made with ❤ to open software by Team Bit.

package/runtimes/exceptions/index.ts

@@ -0,0 +1,2 @@
+export { RuntimeNotDefined } from './runtime-not-defined';
+export { RuntimeModuleError } from './runtime-module-error';

package/runtimes/exceptions/runtime-module-error.ts

@@ -0,0 +1,9 @@
+export class RuntimeModuleError extends Error {
+  constructor(
+    private err: Error
+  ) { super(`failed to load Harmony aspect with error message: ${err.message}`) }
+
+  get stack() {
+    return this.err.stack;
+  }
+}

package/runtimes/exceptions/runtime-not-defined.ts

@@ -0,0 +1,5 @@
+export class RuntimeNotDefined extends Error {
+  constructor(
+    name: string
+  ) { super(`runtime: '${name}' was not defined by any aspect`) }
+}

package/runtimes/index.ts

@@ -0,0 +1,3 @@
+export { RuntimeManifest } from './runtime-manifest';
+export { Runtimes } from './runtimes';
+export { RuntimeDefinition } from './runtime-definition';

package/runtimes/runtime-definition.ts

@@ -0,0 +1,32 @@
+import { RuntimeModuleError } from './exceptions';
+
+export type RuntimeDefProps = {
+  name: string
+};
+
+const DEFAULT_PREDICATE = (filePath: string, name: string) => {
+  return filePath.includes(`.${name}.`);
+}
+
+export class RuntimeDefinition {
+  constructor(
+    readonly name: string,
+    readonly filePredicate: (filePath: string, name: string) => boolean = DEFAULT_PREDICATE
+  ) {}
+
+  getRuntimeFile(paths: string[]): string|undefined {
+    return paths.find(path => this.filePredicate(path, this.name));
+  }
+
+  require(file: string) {
+    // try {
+    //   require(file);
+    // } catch(err) {
+    //   throw new RuntimeModuleError(err);
+    // }
+  }
+
+  static create(def: RuntimeDefProps) {
+    return new RuntimeDefinition(def.name);
+  }
+}

package/runtimes/runtime-manifest.ts

@@ -0,0 +1,12 @@
+import { RuntimeDefinition } from './runtime-definition';
+import { ProviderFn } from '../types';
+import { Aspect } from '../aspect';
+import { SlotProvider } from '../slots';
+
+export interface RuntimeManifest {
+  runtime: RuntimeDefinition|string
+  provider: ProviderFn,
+  dependencies?: Aspect[],
+  slots?: SlotProvider<unknown>[],
+  defaultConfig?: {[key: string]: any},
+}

package/runtimes/runtimes.ts

@@ -0,0 +1,34 @@
+import { RuntimeDefinition } from './runtime-definition';
+import DependencyGraph from '../extension-graph/extension-graph';
+import { RuntimeNotDefined } from './exceptions';
+
+export class Runtimes {
+  constructor(
+    readonly runtimeDefinition: {[key: string]: RuntimeDefinition}
+  ) {}  
+
+  add(runtime: RuntimeDefinition) {
+    this.runtimeDefinition[runtime.name] = runtime;
+    return this;
+  }
+
+  get(name: string): RuntimeDefinition {
+    const runtime = this.runtimeDefinition[name];
+    if (!runtime) throw new RuntimeNotDefined(name);
+    return this.runtimeDefinition[name];
+  }
+
+  dispose() {
+
+  }
+
+  static async load(graph: DependencyGraph) {
+    const runtimes: { [key: string]: RuntimeDefinition } = {};
+    graph.extensions.forEach(manifest => {
+      if (!manifest.declareRuntime) return;
+      runtimes[manifest.declareRuntime.name] = manifest.declareRuntime;
+    });
+
+    return new Runtimes(runtimes);
+  }
+}

package/slots/index.ts

@@ -0,0 +1,2 @@
+export { Slot, SlotProvider } from './slot';
+export { SlotRegistry } from './registry';

package/slots/registry.ts

@@ -0,0 +1,36 @@
+
+export class SlotRegistry<T> {
+  constructor(
+    private registerFn: () => string,
+    readonly map = new Map<string, T>()
+  ) {}
+
+  /**
+   * get a slot value by extension id.
+   */
+  get(id: string): T|undefined {
+    return this.map.get(id);
+  }
+
+  /**
+   * return an array of all slots.
+   */
+  toArray() {
+    return Array.from(this.map.entries());
+  }
+
+  /**
+   * get all registered values.
+   */
+  values() {
+    return Array.from(this.map.values());
+  }
+
+  /**
+   * register a new entry to the slot registry
+   */
+  register(value: T) {
+    const id = this.registerFn();
+    this.map.set(id, value);
+  }
+}

package/slots/slot.ts

@@ -0,0 +1,11 @@
+import { SlotRegistry } from './registry';
+
+export class Slot {
+  static withType<T>() {
+    return (registerFn: () => string) => {
+      return new SlotRegistry<T>(registerFn);
+    }
+  }
+}
+
+export type SlotProvider<T> = (registerFn: () => string) => SlotRegistry<T>;

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "lib": [
+      "es2019",
+      "DOM",
+      "ES6",
+      "DOM.Iterable"
+    ],
+    "target": "es2015",
+    "module": "commonjs",
+    "jsx": "react",
+    "allowJs": true,
+    "composite": true,
+    "declaration": true,
+    "sourceMap": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "rootDir": ".",
+    "resolveJsonModule": true
+  },
+  "exclude": [
+    "dist"
+  ]
+}

package/types/asset.d.ts

@@ -0,0 +1,29 @@
+declare module '*.png' {
+  const value: any;
+  export = value;
+}
+declare module '*.svg' {
+  import type { FunctionComponent, SVGProps } from 'react';
+
+  export const ReactComponent: FunctionComponent<SVGProps<SVGSVGElement> & { title?: string }>;
+  const src: string;
+  export default src;
+}
+
+// @TODO Gilad
+declare module '*.jpg' {
+  const value: any;
+  export = value;
+}
+declare module '*.jpeg' {
+  const value: any;
+  export = value;
+}
+declare module '*.gif' {
+  const value: any;
+  export = value;
+}
+declare module '*.bmp' {
+  const value: any;
+  export = value;
+}

package/types/style.d.ts

@@ -0,0 +1,42 @@
+declare module '*.module.css' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+declare module '*.module.scss' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+declare module '*.module.sass' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.module.less' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.less' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.css' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.sass' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.scss' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.mdx' {
+  const component: any;
+  export default component;
+}

package/types.ts

@@ -0,0 +1,7 @@
+import { Harmony } from './harmony';
+import { SlotRegistry } from './slots';
+
+/**
+ * type definition for the extension provider function.
+ */
+export type ProviderFn = (deps: any, config: any, slots: any, harmony: Harmony) => Promise<any>;

package/utils/async-for-each.ts

@@ -0,0 +1,10 @@
+/**
+ * asynchronously iterate an array.
+ * :TODO improve function singature
+ */
+export async function asyncForEach(array: any[], callback: any) {
+  for (let index = 0; index < array.length; index += 1) {
+    // eslint-disable-next-line no-await-in-loop
+    await callback(array[index], index, array);
+  }
+}

package/utils/index.ts

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

package/dist/extension/extension.spec.js

@@ -1 +0,0 @@
-"use strict";

package/dist/extension-graph/extension-graph.spec.js

@@ -1 +0,0 @@
-"use strict";

package/dist/factory/extension-factory.spec.js

@@ -1,6 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-describe('extensionFactory', () => {
-    it('should return new extension from a manifest', () => {
-    });
-});

package/dist/harmony-config/harmony-config.spec.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/harmony-config/harmony-config.spec.js

@@ -1,8 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const harmony_config_1 = require("./harmony-config");
-describe('HarmonyConfig', () => {
-    it('should parse both files', () => {
-        harmony_config_1.HarmonyConfig.load('workspace.json');
-    });
-});

package/dist/harmony.spec.d.ts

@@ -1 +0,0 @@
-export {};