mixin and components #491

jannyHou · 2017-10-17T03:43:07Z

connect to loopbackio/loopback-next#580

Add mixin doc in Mixin.md
Also add a section for javascript/typescript related concepts as mixin's parent section
Add how a component interact with mixin in Creating-component.md

crandmck · 2017-10-17T17:49:51Z

@jannyHou I'll wait til this is a bit further along to review it OK? Pls ping me when it's ready for review.

jannyHou · 2017-10-17T20:11:36Z

@crandmck yeah I am still adding stuff on local, thanks!

bajtos · 2017-10-18T14:31:49Z

_data/sidebars/lb4_sidebar.yml

@@ -98,6 +98,15 @@ children:
  url: Crafting-LoopBack-4.html
  output: 'web, pdf'

+- title: 'Language Related Concepts'


Is it worth starting a new top-level section instead of nesting this new "Mixin" page under "Key concepts"? I don't know what's the right answer, just something to consider.

@bajtos I feel at least now Mixin is not a LB core concept, we don't have mixin level context, and don't reply on it to scaffold the app, it is more like a JS/TS strategy to extend class, which make other concepts extendable, like application, controller, as long as it's a class.

there is some context of this discussion, I pinged Raymond about moving mixin.ts from @loopback/repository to @loopback/core, and he suggests we can have a @loopback/lang or @loopback/common module for JS/TS related stuff.

I created an issue for this idea: loopbackio/loopback-next#660

S/be
Language-related concepts

jannyHou · 2017-10-18T15:21:28Z

Regarding new category Lang, there are some context in story loopbackio/loopback-next#660

crandmck · 2017-10-18T18:03:02Z

pages/en/lb4/Lang-concepts.md

@@ -0,0 +1,13 @@
+---
+lang: en
+title: 'Language Related Concepts'


Language-related concepts

crandmck · 2017-10-18T18:03:19Z

_data/sidebars/lb4_sidebar.yml

@@ -98,6 +98,15 @@ children:
  url: Crafting-LoopBack-4.html
  output: 'web, pdf'

+- title: 'Language Related Concepts'


S/be
Language-related concepts

crandmck · 2017-10-18T18:07:30Z

pages/en/lb4/Creating-components.md

@@ -228,6 +230,33 @@ export class AuthenticationProvider {
 }
 ```

+## Extends Application


This section has many grammatical and stylistic errors. Rather than go through them laboriously here, I'd prefer to either edit the text in thebranch directly or wait til the PR lands and then edit the text (none of the changes would require technical review) in master (ie. gh-pages). @jannyHou LMK which you'd prefer.

hi @crandmck I think now this PR is still waiting for technical review, I will let you know when it's done but before merging.

dhmlau · 2017-10-18T18:09:49Z

pages/en/lb4/Creating-components.md

@@ -228,6 +230,33 @@ export class AuthenticationProvider {
 }
 ```

+## Extends Application
+
+When bind a component to an app, you may want to mount the component's propertis 


When bind a component to an app --> When binding a component to an app

typo: propertis --> properties

dhmlau · 2017-10-18T18:13:16Z

pages/en/lb4/Creating-components.md

+
+When bind a component to an app, you may want to mount the component's propertis 
+and methods to application level context. 
+A stragety to do that is using mixin, which extends a class with new properties and methods.


typo: stragety --> strategy

Not sure if i understand what it means.. Is it sth like:
a strategy is to use mixin to extends a class with new properties and methods ?

@dhmlau yep.

dhmlau · 2017-10-18T18:17:44Z

pages/en/lb4/Creating-components.md

+An example scenario would be an app has multiple components with repositories bound to each of them, 
+you can use a `RepositoryMixin` to mount all of the repositories to the app.
+
+If you are not familiar with concept `mixin`, check [Mixin](Mixin.htm) to know more, 


suggested change.. simply say sth like:
For more details, see Mixin.

I would like to have the current version since that document is not a must read for people who already knows JS mixin. A simplified version implies Mixin.mdcontains something additional/different to the JS concept, but it doesn't :)

dhmlau · 2017-10-18T18:19:16Z

pages/en/lb4/Mixin.md

+## Define Mixin
+
+By defining a mixin, you create a mixin function that takes in a base class, 
+and returns a new class extends the base class with new properties and methods mixed to it.


perhaps: "returns a new class extends the base class.." --> "returns a new class extending the base class..."

kjdelisle

I know you said focus on the technical aspects, but the typos I left comments about are code style errors or outright syntax errors.

kjdelisle · 2017-10-18T19:09:19Z

pages/en/lb4/Creating-components.md

 const request = require('request-promise-native');
 const weatherUrl =
  'http://samples.openweathermap.org/data/2.5/weather?appid=b1b15e88fa797225412429c1c50c122a1'

-export class CurrentTemperatureProvider {
-  async value() {
+export class CurrentTemperatureProvider implement Provider<number>{


typo here in the code snippet, should be "implements"

horrible typo :(

kjdelisle · 2017-10-18T19:09:28Z

pages/en/lb4/Creating-components.md

 const uuid = require('uuid/v4');

-class CorrelationIdProvider {
+class CorrelationIdProvider implement Provider<any>{


kjdelisle · 2017-10-18T19:10:54Z

pages/en/lb4/Creating-components.md

-export class CurrentTemperatureProvider {
-  async value() {
+export class CurrentTemperatureProvider implement Provider<number>{
+  async value():number {


missing a space: async value(): number

kjdelisle · 2017-10-18T19:11:12Z

pages/en/lb4/Creating-components.md

  constructor(@inject('http.request') request) {
    this.request = request;
  }

-  value() {
+  value():any {


missing a space: value(): any

bajtos

Please see my comments below.

In addition to them, please include reference to the following materials explaining ES2015 and TypeScript mixins in more details:

bajtos · 2017-10-18T14:34:54Z

pages/en/lb4/Creating-components.md

-export class MyValueProvider {
-  value() {
+export class MyValueProvider implements Provider<string>{
+  value(): string {


I think this should not be strictly necessary, I believe TypeScript is able to infer the return type from Provider definition and/or the actual value returned by the code of this method. Unless I am mistaken?

❗️ actually, the code examples in this file are all using JavaScript, not TypeScript - see js after three backticks. I think you should revert type-related changes in this file.

@bajtos good catch...I thought the doc is out-of-date so update it according to our latest tsdoc in provider.ts. But didn't think it in the JS compatible direction.

Let me verify it.

bajtos · 2017-10-18T14:38:34Z

pages/en/lb4/Creating-components.md

 const request = require('request-promise-native');
 const weatherUrl =
  'http://samples.openweathermap.org/data/2.5/weather?appid=b1b15e88fa797225412429c1c50c122a1'

-export class CurrentTemperatureProvider {
-  async value() {
+export class CurrentTemperatureProvider implement Provider<number>{


implements?

bajtos · 2017-10-18T14:38:42Z

pages/en/lb4/Creating-components.md

 const uuid = require('uuid/v4');

-class CorrelationIdProvider {
+class CorrelationIdProvider implement Provider<any>{


implements?

bajtos · 2017-10-19T12:29:02Z

pages/en/lb4/Using-components.md

@@ -35,4 +35,4 @@ In general, components can contribute the following items:
 In the future (before the GA release), components will be able to contribute additional items:

 - Models
- - [Repositories](Repositories.html)
+ - [Repositories](Repositories.html)


Unrelated whitespace change, could you please revert?

weird...I could not see where is the whitespace(difference), I copy paste the original file but diff is still here...

Sounds like a character formatting problem (was this file made on Windows or something? :P)

bajtos · 2017-10-19T12:44:24Z

pages/en/lb4/Mixin.md

+import {BaseClass} from '<path_exports_BaseClass>';
+import {FooMixin, BarMixin} from '<path_exports_Mixins>';
+
+let newClass = MixinBuilder.mix(baseClass).with(FooMixin, BarMixin);


This example has an important problem: it's assigning a class constructor to a variable newClass. The usual convention is to start class names with a capital letter, e.g. NewClass. However, because we are using let + assignment instead of class, the name NewClass will trigger a tslint error about violating naming conventions for variables.

IMO, we should not promote MixinBuilder and tell people to compose mixins directly via regular JS/TS function invocation and class inheritance:

class NewClass extends FooMixin(BarMixin(baseClass)) { }

Another important difference to consider:

In my proposed approach, the javascript runtime see a correct class name (NewClass) and NewClass.toString() operator returns class NewClass...:

> NewClass.name "NewClass" > NewClass.toString() "class NewClass extends Mixin1(Mixin2(BaseClass)) { }"

Compare it with the result of MixinBuilder.mix().with(), which incorrectly sets the constructor name to BaseClass and where newClass.toString() returns a fully mixed class definition that makes it difficult to see what have been added by what mixin:

> newClass.name "BaseClass" > newClass.toString() "class extends superClass { constructor() { super(...arguments); this.mixinProp2 = 'mixinProp2'; } static staticMixinMethod2() { return 'mixin2.static'; } mixinMethod2() { return 'mixin2'; } }"

I am using the following unit-test code to verify my assumptions and produce sample output: https://github.com/strongloop/loopback-next/blob/568c6e2e7242949e1e5ece040bc3a54d83ff1411/packages/repository/test/unit/mixin/mixin.ts#L53

cc @raymondfeng as the author of MixinBuilder

we should not promote MixinBuilder and tell people to compose mixins directly via regular JS/TS function invocation and class inheritance:

I wonder if one of the objectives of our MixinBuilder is to compose mixins for this use case. If that's the case, IMO shouldn't the constructor name and class def be preserved by MixinBuilder? (unless there is a reason I'm not aware of)

@raymondfeng Could you take a look of comment https://github.com/strongloop/loopback.io/pull/491/files#r145687471? Thanks!

My understanding of MixinBuilder is it provides a prettier syntax to compose mixins to a class, but @bajtos has a good point in comment above.

I borrowed the idea from http://justinfagnani.com/2015/12/21/real-mixins-with-javascript-classes/

FYI

Compare it with the result of MixinBuilder.mix().with(), which incorrectly sets the constructor name to BaseClass and where newClass.toString() returns a fully mixed class definition that makes it difficult to see what have been added by what mixin:

This could be solved by defining newClass as
newClass = class extends MixinBuilder.mix(BaseClass).with(Mixin1, Mixin2) {};

Then print out:

console.log(newClass.name); // newClass console.log(newClass.toString()); // class extends _1.MixinBuilder.mix(BaseClass).with(Mixin1, Mixin2) {}

The problem of MixinBuilder from my test is: function with() doesn't set its returned type as a class extends the BaseClass:
click to see example test

let AppWithRepoMixin = class extends MixinBuilder.mix(Application).with(RepositoryMixin){}; const myApp = new AppWithRepoMixin(); const boundComponentsBefore = myApp.find('components.*').map(b => b.key);

fails when compiling, because compiler doesn't know myApp is an instance of Application, therefore doesn't know it has a prototype function find() returning an Array. The code calls map with any instead of Array and fails.

This looks like a stop for people wanting to use it...

I am going to defer writing doc for MixinBuilder and create an issue for it. I still love the fluent api and would like to dig more ⭐

I am going to defer writing doc for MixinBuilder and create an issue for it. I still love the fluent api and would like to dig more ⭐️

@jannyHou could you please paste a link to that new issue here for posterity?

@bajtos sure, sorry forgot to link it here: loopbackio/loopback-next#673

bajtos · 2017-10-19T12:46:59Z

pages/en/lb4/Mixin.md

+
+It is a commonly used JavaScript/TypeScript strategy to extend a class with new properties and methods.
+
+*question: does our mixinBuilder allow interface extends classes?*


I am not sure if I understand this question. Interfaces are compile-time things that are used by TypeScript compiler to verify type correctness. They are omitted from the transpiled javascript output and they are not available at runtime.

I think it's possible to declare that an interface extends a class, which means that the interface must have all prototype members (properties & methods) of the class being extended. However, no implementation details (no JS code) from the class is inherited this way, it's all about compile-time shape of objects (the type system) only.

I should have removed this, it is a question I am curious to know when reading typescript's class docuemnt:
search "Interfaces Extending Classes" on page https://www.typescriptlang.org/docs/handbook/interfaces.html

MixinBuilder's input is typed to Class(we defined in common-types.ts)

constructor(public baseClass: Class<any>) {}

So I am wondering would Interface work as well.

bajtos · 2017-10-19T12:49:23Z

pages/en/lb4/Mixin.md

+import {Class} from "@loopback/repository";
+
+export function timeStampMixin<T extends Class<any>> (baseClass: T) {
+  return class newClass extends baseClass {


I think the usual convention for creating mixins is to use anonymous class:

return class extends baseClass { // ... };

I think V8 is smart enough to infer a better class name in such case, most likely use baseClass's name. E.g. timeStampMixin(UserController) returns a class called UserController and timeStampMixin(ProductController) returns a class called ProductController, which is much better than having both calls return classes with the same name newClass.

bajtos · 2017-10-19T12:49:35Z

pages/en/lb4/Mixin.md

+import {Class} from "@loopback/repository";
+
+function loggerMixin<T extends Class<any>> (baseClass: T) {
+  return class newClass extends baseClass {


Ditto, just return class extends baseClass

bajtos · 2017-10-19T12:50:20Z

pages/en/lb4/Mixin.md

+    }
+}
+
+let AdvancedController = MixinBuilder.mix(SimpleController).with(timeStampMixin, loggerMixin);


As I commented above, for cases where the list of mixins is known at compile time, we should not be using MixinBuilder.

bajtos · 2017-10-19T12:50:51Z

pages/en/lb4/Mixin.md

+function loggerMixin<T extends Class<any>> (baseClass: T) {
+  return class newClass extends baseClass {
+    // add a new method `logger()`
+    logger(str: string) {


It's a good practice to give methods names that start with a verb, i.e. log(str: string) in this case.

b-admike · 2017-10-19T13:47:29Z

pages/en/lb4/Creating-components.md

+
+From Janny:
+
+I am going to add a Lite version of `RepositoryMixin`'s code as the end of this section


Here I think you have some options. You could:

Give an overview of RepositoryMixin and point to its implementation

Give a brief overview of RepositoryMixin with code snippets like you said, and point to the source code at the end

I think the first option might suffice, given that Mixins are described in detail in their own page. IMO, the main points this section should cover would be:

How component developers can leverage mixins

Guideline on how they should use mixins

other considerations that they should take into account

b-admike · 2017-10-19T13:49:59Z

pages/en/lb4/Mixin.md

+let newClass = MixinBuilder.mix(baseClass).with(FooMixin, BarMixin);
+```
+
+## Define Mixin


I wonder if we should walk readers through this section first before Mixin Builder section. IMO I see it as introducing the concept first, then showing them how we make their lives easier with our MixinBuilder :)

I also think of the sequence when wrote it. Eventually decided to introduce MixinBuilder first:

MixinBuilder.mix(baseClass).with(FooMixin, BarMixin) is a very straight forward syntax to give a new mixin learner a big picture of what is the relation between class and mixin, then they go into section#define-mixin to dig more into implementation and usage. And to tell people already know mixin how MixinBuilder provides a prettier syntax to apply mixins.

jannyHou · 2017-10-25T18:26:51Z

Apply feedback in 8b43c0f:

rename sidebar title to Lauguage-related concepts
removed document of MixinBuilder, details see discussion mixin and components #491 (comment) and issue Fix and document MixinBuilder loopback-next#673
complete the creating component doc

jannyHou · 2017-10-26T15:04:42Z

@bajtos @kjdelisle feedback applied, PTAL again, thanks!

kjdelisle

Minor nits.

kjdelisle · 2017-10-26T19:03:43Z

pages/en/lb4/Creating-components.md

@@ -228,6 +228,66 @@ export class AuthenticationProvider {
 }
 ```

+## Extends Application with Mixin
+
+When binding a component to an app, you may want to extend the app with component's 


components

@kjdelisle I think it should be the component's

whole sentence is:
When binding a component to an app, you may want to extend the app with the *component's* properties and methods.

I don't see with the component's in the existing snippet. ;)
I'm alright with that change as well.

kjdelisle · 2017-10-26T19:05:00Z

pages/en/lb4/Mixin.md

+```
+
+Check article [real mixins with javascript classes](http://justinfagnani.com/2015/12/21/real-mixins-with-javascript-classes/) 
+to know more about it.


to learn more.

kjdelisle · 2017-10-26T20:39:59Z

pages/en/lb4/Mixin.md

+
+Now let's add mixins to it:
+
+- A time stamp mixin that adds a property `createdAt` to record when a controller instance get created.


to a record when a controller instance is created

kjdelisle · 2017-10-26T20:40:30Z

pages/en/lb4/Mixin.md

+
+- A time stamp mixin that adds a property `createdAt` to record when a controller instance get created.
+
+- A logger mixin that adds a method `log` to log the `string` you provide.


A logger mixin to provide logging tools

kjdelisle · 2017-10-26T20:41:26Z

pages/en/lb4/Using-components.md

@@ -35,4 +35,4 @@ In general, components can contribute the following items:
 In the future (before the GA release), components will be able to contribute additional items:

 - Models
- - [Repositories](Repositories.html)
+ - [Repositories](Repositories.html)


Sounds like a character formatting problem (was this file made on Windows or something? :P)

jannyHou · 2017-10-26T21:04:56Z

@kjdelisle thank you :) 8c8890d

Really couldn't figure out how - [Repositories](Repositories.html) differs from the original file... so I leave it like this :(

kjdelisle

Two more tiny fixes

kjdelisle · 2017-10-26T22:00:42Z

pages/en/lb4/Creating-components.md

+properties and methods. 
+This can be achieved by using mixin. 
+
+If you are not familiar with concept `mixin`, check [Mixin](Mixin.htm) to know more.


If you are not familiar with the mixin concept, see [Mixin](Mixin.htm) to learn more.

kjdelisle · 2017-10-26T22:00:50Z

pages/en/lb4/Creating-components.md

+
+When binding a component to an app, you may want to extend the app with the component's 
+properties and methods. 
+This can be achieved by using mixin. 


by using mixins

jannyHou · 2017-10-27T15:45:27Z

@slnode test please

jannyHou · 2017-10-27T17:57:35Z

@slnode test please

jannyHou · 2017-10-27T20:07:51Z

@slnode test please

jannyHou requested review from bschrammIBM and crandmck as code owners October 17, 2017 03:43

jannyHou self-assigned this Oct 17, 2017

jannyHou added needs-priority review and removed needs-priority labels Oct 17, 2017

crandmck removed the request for review from bschrammIBM October 17, 2017 17:49

jannyHou changed the title ~~mixin and components[WIP]~~ mixin and components Oct 18, 2017

bajtos reviewed Oct 18, 2017

View reviewed changes

crandmck suggested changes Oct 18, 2017

View reviewed changes

dhmlau reviewed Oct 18, 2017

View reviewed changes

kjdelisle suggested changes Oct 18, 2017

View reviewed changes

jannyHou force-pushed the mixin/component branch from 51f7019 to 907a715 Compare October 18, 2017 20:59

bajtos suggested changes Oct 19, 2017

View reviewed changes

bajtos mentioned this pull request Oct 19, 2017

Move shared types and other primitives to a standalone module loopbackio/loopback-next#660

Closed

b-admike reviewed Oct 19, 2017

View reviewed changes

jannyHou mentioned this pull request Oct 25, 2017

Fix and document MixinBuilder loopbackio/loopback-next#673

Closed

4 tasks

jannyHou force-pushed the mixin/component branch 5 times, most recently from 4790edb to 8b43c0f Compare October 25, 2017 18:22

crandmck approved these changes Oct 25, 2017

View reviewed changes

b-admike approved these changes Oct 25, 2017

View reviewed changes

kjdelisle suggested changes Oct 26, 2017

View reviewed changes

jannyHou force-pushed the mixin/component branch from 8b43c0f to 8c8890d Compare October 26, 2017 21:00

kjdelisle suggested changes Oct 26, 2017

View reviewed changes

bajtos approved these changes Oct 27, 2017

View reviewed changes

jannyHou added 3 commits October 27, 2017 11:11

mixin and components

68c442b

Add mixin doc

ae869f4

Apply feedback

837ee53

jannyHou force-pushed the mixin/component branch from be52102 to 837ee53 Compare October 27, 2017 15:12

kjdelisle approved these changes Oct 27, 2017

View reviewed changes

jannyHou merged commit 38760d5 into gh-pages Oct 30, 2017

jannyHou removed the review label Oct 30, 2017

jannyHou mentioned this pull request Oct 30, 2017

Updating Docs for Using / Writing Components loopbackio/loopback-next#580

Closed

3 tasks

jannyHou deleted the mixin/component branch October 31, 2017 18:11


		It is a commonly used JavaScript/TypeScript strategy to extend a class with new properties and methods.

		question: does our mixinBuilder allow interface extends classes?


		From Janny:

		I am going to add a Lite version of `RepositoryMixin`'s code as the end of this section


		Now let's add mixins to it:

		- A time stamp mixin that adds a property `createdAt` to record when a controller instance get created.


		- A time stamp mixin that adds a property `createdAt` to record when a controller instance get created.

		- A logger mixin that adds a method `log` to log the `string` you provide.

mixin and components #491

mixin and components #491

Conversation

jannyHou commented Oct 17, 2017 • edited by b-admike Loading

crandmck commented Oct 17, 2017

jannyHou commented Oct 17, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jannyHou commented Oct 18, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jannyHou Oct 18, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kjdelisle left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bajtos left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jannyHou Oct 19, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

b-admike Oct 19, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jannyHou Oct 24, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jannyHou Oct 27, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

b-admike Oct 19, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jannyHou commented Oct 25, 2017 • edited Loading

jannyHou commented Oct 26, 2017

kjdelisle left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jannyHou commented Oct 26, 2017

kjdelisle left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jannyHou commented Oct 27, 2017

jannyHou commented Oct 27, 2017

jannyHou commented Oct 27, 2017

jannyHou commented Oct 17, 2017 •

edited by b-admike

Loading

jannyHou Oct 18, 2017 •

edited

Loading

jannyHou Oct 19, 2017 •

edited

Loading

b-admike Oct 19, 2017 •

edited

Loading

jannyHou Oct 24, 2017 •

edited

Loading

jannyHou Oct 27, 2017 •

edited

Loading

b-admike Oct 19, 2017 •

edited

Loading

jannyHou commented Oct 25, 2017 •

edited

Loading