Discussion of Scoped Mixins API

[likern]

• Start Date: 2019-06-24
• Target Major Version: 3.x
• Reference Issues: (fill in existing related issues, if any)
• Implementation PR: (leave this empty)

Note

I opened this Issue to discuss ideas of scoped mixins API and gather ideas and feedback about it. The main idea is, instead of completely change the way how components are written, update mixins semantic to make it more composable and reusable.

Summary

Unify logic-composition patterns under scoped mixins.

Basic example

export default {
  data() {
    return {
      value: 0
    };
  },
  methods: {
    increment() {
      this.value++
    }
  },
  computed: {
    plusOne: function () {
      return this.value + 1
    }
  },
  watch: {
    value: function (newVal, old) {
      console.log(`count * 2 is ${newVal * 2}`)
    }
  },
  mounted() {
    console.log(`mounted`)
  }
}

<template>
  <div>
    <span>count is {{ count.value }}</span>
    <span>plusOne is {{ count.plusOne }}</span>
    <button @click="increment">count.value++</button>
  </div>
</template>

<script>
import Count from "@/mixins/Count";

export default {
  mixins: {
    count: Count
  },
  data() {
    return {
    };
  }
}
</script>

Motivation

Logic Composition

One of the key aspects of the component API is how to encapsulate and reuse logic across multiple components. With Vue 2.x's current API, there are a number of common patterns we've seen in the past, each with its own drawbacks. These include:

• Mixins as array of mixin objects (via the mixins option)
• Higher-order components (HOCs)
• Renderless components (via scoped slots)

Mixins drawbacks

Mixins in its current state have several major drawbacks making it difficult to reason about them and compose.

• One of the main complains about mixins is it's difficult to figure out sources the properties come from. When several mixins are used it becomes problematic to understand which mixin contains property and how properties are grouped by mixins.
• Namespace clashing. Mixins can potentially clash on property and method names.
• Unexpected merging strategy for mixins
• Order of mixins in array is important and mixins can overwrite each other's functionality

<template>
  <h1>Problem 1 with mixins</h1>
</template>

<script>
// Mixins are composed in unexpected way
// Why is called only secondMixin and why it is called twice?
const firstMixin = {
  created: function() {
    this.hello();
  },
  methods: {
    hello: function() {
      console.log("I'm from first mixin!");
    }
  }
};

const secondMixin = {
  created: function() {
    this.hello();
  },
  methods: {
    hello: function() {
      console.log("I'm from second mixin!");
    }
  }
};

export default {
  name: "problem1",
  mixins: [firstMixin, secondMixin]
};
</script>

The new scoped-mixins API presents a clean and flexible way to compose logic inside and between components without any of these drawbacks. This can be achieved by extracting code related to a piece of logic into what we call a "scoped mixin" which can be easily injected into component. Here is an example of using a scoped mixin to extract the logic of listening to the mouse position:

export default {
  data() {
    return {
      x: 0,
      y: 0
    };
  },
  methods: {
    update(e) {
      this.x = e.pageX
      this.y = e.pageY
    }
  },
  mounted() {
    window.addEventListener('mousemove', this.update)
  },
  unmounted() {
    window.removeEventListener('mousemove', this.update)
  }
}

// in consuming component

<template>
  <div>{{ mouse.x }} {{ mouse.y }} {{ other.z }}</div>
</template>

<script>
import mouseMixin from "./mixins/mouse"
import otherMixin from "./mixins/other"

export default {
  name: "app",
  mixins: {
    mouse: mouseMixin,
    other: otherMixin
  }
};
</script>

Note in the example above:

• Properties exposed to the template have clear sources since they are nested object properties, where parent object is used as namespace;
• Mixin objects can be registered at arbitrary name (used as namespace) so there is no namespace collision;
• There are no unnecessary component instances created just for logic reuse purposes.

Type Inference

TypeScript type inference support is out of scope of this RFC. This RFC solely focuses on better logic composability / reusability and tries to be better mixins / HOC / renderless components alternative.

[posva]

TLDR: With the function api, any possible naming conflict can be fully controlled and overridden. The typescript inference would be a problem though, making this solution far inferior to the function api in terms of Development experiences, so to me it doesn't make sense to add this new API (even though the surface is very small) because it suffers from the same problems as regular mixins

---

The main complain you mention (where do things come from) remains unsolved with the namespacing. At the end, namespacing will only solve name clashing, all other problems still remain because they are inherent to mixins themselves and how they are designed to work

To me, this namespacing can be achieved by having a function (very common behavior for customizing mixins):

export function mouseTracking(namespace = 'mouse') {
  const x = namespace + 'X'
  const y = namespace + 'Y'
  const listener = Symbol()

  return {
    data: => ({ [x]: 0, [y]: 0 }),
    mounted() {
      this[listener] = ({ pageX, pageY }) => {
        this[x] = pageX
        this[y] = pageY
      }
      window.addEventListener('mousemove', this[listener])
    },
    unmounted() {
      window.removeEventListener('mousemove', this[listener])
    }
}

it does fail as well in type inference though, which to be fair cannot be ignored.

about

// Why is called only secondMixin and why it is called twice?

It's because methods override each other but created hooks stack and get called in order (you can search for merging strategy in docs for more info). So only one of the methods is taken into account

[likern]

The main complain you mention (where do things come from) remains unsolved with the namespacing. At the end, namespacing will only solve name clashing, all other problems still remain because they are inherent to mixins themselves and how they are designed to work
The main complain you mention (where do things come from) remains unsolved with the namespacing. At the end, namespacing will only solve name clashing, all other problems still remain because they are inherent to mixins themselves and how they are designed to work

I don't understand this. Could you, please, clarify? What exacty is not solved with namespacing? And what can't be controlled?

any possible naming conflict can be fully controlled and overridden

The same with scoped mixins, because you control how scoped mixins are registered and at what namespace. They are not expected to be overwritten by each other, they are not merged into Vue component directly, scoped mixins can't have arbitrary access to Vue component (only with special restrictive context)

[privatenumber]

As @posva said, it looks like the function API solves all the problems you highlight and even more. I'm interested to hear your perspective on the function API in comparison to your scoped mixin proposal --how is this better?

[posva]

The namespacing (which is what you call scoped mixins, but it really is namespacing by wrapping in an object) doesn't solve 2 of 3 of the points (the unexpected merging strategy was a question, but it really is expected and can even be customized!):

• One of the main complains about mixins is it's difficult to figure out sources the properties come from. When several mixins are used it becomes problematic to understand which mixin contains property and how properties are grouped by mixins -> this remains the same as it's completely implicit what properties exist inside of the count object (taking it from one of your examples)
• Order of mixins in array is important and mixins can overwrite each other's functionality -> they can still clash for props (because it cannot be <comp :mixin.prop="..."/> that would be a modifier) so props will still override, and still merge for hooks like created

Mixins are not going away and aren't replaced by the function api anyway (thinking about props, which cannot be added with the function api)

[likern]

this remains the same as it's completely implicit what properties exist inside of the count object (taking it from one of your examples)

Ok, let's look at @yyx990803 proposal:

function useMouse() {
  const x = value(0)
  const y = value(0)
  const update = e => {
    x.value = e.pageX
    y.value = e.pageY
  }
  onMounted(() => {
    window.addEventListener('mousemove', update)
  })
  onUnmounted(() => {
    window.removeEventListener('mousemove', update)
  })
  return { x, y }
}

// in consuming component
const Component = {
  setup() {
    const { x, y } = useMouse()
    const { z } = useOtherLogic()
    return { x, y, z }
  },
  template: `<div>{{ x }} {{ y }} {{ z }}</div>`
}

As Functional API claims to be composable and reusable, useMouse() function will be definitely imported into this component from other file.
I have a few questions:

1. How do you know what is returned from useMouse() without looking at external file?
2. How do you know what variables to destructure from object, returned from useMouse()?
3. How it differs from that you don't know beforehand what Count mixins contains?

they can still clash for props (because it cannot be that would be a modifier) so props will still override, and still merge for hooks like created

And they shouldn't be overrideable outside of the component - it is part of data encapsulation principle. The same way you can't override props passed to component children from outside of component like <comp :child.prop="..."/>. This breaks whole encapsulation.

When it comes to

so props will still override
how is it possible, if component fully controls properties - which it accepts, at what name and type?

Component can easily register mixin as another name, if that clash happens - and this will be done automatically with IDE support.

Scoped mixins do not have access to internals of Vue component. It is not possible to modify props in Vue component, it's own data, etc. And they do not merge so that you no more can understand what is called.

Let's look at official documentation example:

var mixin = {
  methods: {
    foo: function () {
      console.log('foo')
    },
    conflicting: function () {
      console.log('from mixin')
    }
  }
}

var vm = new Vue({
  mixins: [mixin],
  methods: {
    bar: function () {
      console.log('bar')
    },
    conflicting: function () {
      console.log('from self')
    }
  }
})

vm.foo() // => "foo"
vm.bar() // => "bar"
vm.conflicting() // => "from self"

That's a problem - after mixin merge, you don't know which function is called. From mixin, or from component? To understand that you have both to look at source code of component and mixin.

Here is scoped mixins:

var mixin = {
  methods: {
    foo: function () {
      console.log('foo')
    },
    conflicting: function () {
      console.log('from mixin')
    }
  }
}

var vm = new Vue({
  mixins: {
     mixin: mixin
  },
  methods: {
    bar: function () {
      console.log('bar')
    },
    conflicting: function () {
      console.log('from self')
    }
  }
})

vm.foo() // => "foo" // Error! Mixins are not merged directly to root component
vm.bar() // => "bar" // Easy to see where it comes from
vm.conflicting() // => "from self"
vm.mixin.conflicting() // Easy to see where it comes from

[backbone87]

How do you know what is returned from useMouse() without looking at external file?

Documentation and typing. Documentation via JSDoc doesnt work too well with the options based API, but that is reasonably solveable by extra tooling. The dealmaker is typing and developing a typing system "just for Vue option API" is beyond reasonable cost. There are 2 JS typing systems (TS and flow), both backed and driven by 2 of the largest software companys with considerable investments. So reusing/supporting one or both of them is the only road available. And imho TS "won" (correct me if i am wrong, but didnt facebook even discontinued flow?), so this decision was already made for us.

How do you know what variables to destructure from object, returned from useMouse()?

Its basically the same question as above: Documentation and typing.

Edit: Ofc you can always look at the code (which i highly recommend), but you are not forced to do it, just to reuse the logic, given its properly typed and documented.

[LinusBorg]

Your namespaced count object is definitely an improvement over normal mixins insofar as it shows which pieces of data came from the same mixin.

How it differs from that you don't know beforehand what Count mixins contains?

It's an inherent principle of modularized code that we need to be aware of the API they expose once we import them somewhere and make use of them.

The difference is that once we have looked that up, we can destructure the exported props from a function so we clearly can see everything that is coming from this functon:

const { x, y } = useMouse()

And everytime we want to know all of the stuff that came from this mixin, we can come back to this one line and find it all right there.

For a "scoped mixin", we don't get this information in such a compact form. We would have to scan all of the component's code for occurrences of this.mouse.* to find out all of the properties that the mouse object from the mixin provides (and that we actually make use of).

So it's better than normal mixins in that we can see which properties came from where since the scoped mixin groups them in one object, agreed. But the information what properties this object actually contains is still scattered throughout the component, which is a small disadvantage over the function-based API in my book.

[posva]

About the 3 questions: explicit and automatic typings. Typing inference with mixins can be achieved for static mixins. for functions returning mixins, the user would have to explicitly write types in most scenarios. With functions, it's almost automatic inference thanks to typescript even if you are doing javascript: your editor will figure it out, improving discoverability

And they shouldn't be overrideable outside of the component - it is part of data encapsulation principle. The same way you can't override props passed to component children from outside of component like . This breaks whole encapsulation.

I think I wasn't clear, I'm saying that props will still get overridden when clashing into multiple namespaces/scoped mixins unless the outside name is prefixed and camel cased like count.value => countValue

It's absolutely possible to define props through a mixin, you can define any option, even custom ones, so it's something that should be taken into consideration when thinking about a namespaced version of mixins

To understand that you have both to look at source code of component and mixin

Exactly, but the same happens with namespaces mixins because it still is implicit like regular mixins: props, method or data are not declared in the component whereas with the function api, they are returned in the setup

[Meekohi]

I asked a similar question in Discord:

[7:25 PM] meekohi: Q: Has anyone ever considered explicitly namespacing mixins, to solve both the typescript and namespace problems? I'm not deep enough to know what might go wrong but curious about:

  mixins: {
    animal: FlyingMammals,
    sport: WoodenSticks
  },
  computed: {
    pet_name(): {
      return this.animal.bat.name // namespaced data/prop
    },
    weapon(): {
      return this.sport.bat // namespaced data/prop
    }
  }

[7:26 PM] meekohi: I would think it's much easier to pass type information along if you can reuse the mixin's type definitions verbatim (vs trying to merge it into the component's, which seemed like the problem Class API ran into?)
[11:15 AM] gusto: @Meekohi so here's what I got as a response:

In that case, I think it would be better to just instantiate mixin instance in data hook.

Vue.extend({
  data() {
    return {
      animal: new FlyingMammals(),
      sport: new WoodenSticks()
    }
  },
  // ...
})

Type inference of namespaced mixin may work well but that means we will need another type parameter to Vue interface and component options. We already have many type parameters and it complicates our type declaration. https://github.com/vuejs/vue/blob/dev/types/options.d.ts#L68-L73

So I guess it would be difficult to extend our typing with that kind of approach unfortunately...
In fact, there are PRs which is pending now because of this problem.

• fix(types): support accessing inject as string array (#8969) vue#9732
• feat(types): add DOM type definition for JSX element vue#9369

[boonyasukd]

• How do you know what is returned from useMouse() without looking at external file?
• How do you know what variables to destructure from object, returned from useMouse()?
• How it differs from that you don't know beforehand what Count mixins contains?

The answer is full 100% type inference support: in a function-based API that vue team proposed, in a capable editor like VSCode, you just press Ctrl + Space inside { } to have an auto-complete window listing all of the exported elements from useMouse() (in this case, x and y). If useMouse() happens to export a function, such function will also be shown in an auto-complete window, and selecting it with an arrow key should show its complete method signature. And with an upcoming version Vetur extension, AFAIU type inference will work all the way to <template> section of SFC as well. So, with a function-based API, you can definitely know what's returned without looking at an external file. This is the main reason why people are enthusiastic about full typing support: it allows you to discover API on-the-fly in the way statically typed language developers have enjoyed for years.

Also, in the case of namespace clashing, the reason why people like function-based API is because you can always reassign variables during destructure should variable names ever collide. Thus you have a flexibility in your hand to rename variables to maximize code readability:

// in a consuming component

const Component = {
  setup() {
    // suppose each useXXX() returns a 'state' variable;
    // we simply rename them in the way that ease maintenance/reduce confusion
    const { state: mouseState } = useMouse()
    const { state: otherState } = useOther()
    return { mouseState, otherState }
  },
  // here we use 'mouseState.XXX', 'otherState.XXX', similar to your 'mixin.XXX'
  template: `<div>{{ mouseState.x }} {{ mouseState.y }} {{ otherState.z }}</div>`
}

I know that the original RFC doesn't do a great job explaining this, but this is definitely what it meant when it says:

Returned values from composition functions can be arbitrarily named so there is no namespace collision;

[yyx990803]

Aside from type inference support, another important thing this proposal misses is the ability for mixins to interact with one another.

With the scoped approach you are suggesting, scoped mixins are completely isolated from each other - there is no way for one mixin to somehow leverage the state of another mixin, because they won't know under what name the other mixin is going to be registered by the consuming component.

With function-based API this is as simple as passing the returned state of one composition function into another:

export default {
  setup(props) {
    const valueA = useFeatureA(props)
    const valueB = useFeatureB(valueA)
  }
}

Note there is no need for implicit coupling between the two features because composition happens in the consuming component.

BTW, I sketched around with almost the exact same idea before I decided to go with the function API instead. I hope at this point you can see that going down the mixin route is like battling with a constraint we imposed on ourselves - while with the function approach, you can leverage the full flexibility of JavaScript to compose logic anyway you want.

[marceloadsj]

To solve that, mixins should be a function, like data, and the mixins instantiated:

mixins() {
  const count = new Count();
  const mouse = new Mouse(count);

  return { count, mouse };
}

But what I see is, using the functional API we can easily implement a "useMixin", of course, with just small changes on mixin code (the way we change the data/state for ex) but I think don't impact the design:

setup() {
  return {
    count: useMixin(Count)
  };
}

But with the mixin scoped RFC, you can't implement the functional API. This means, the functional API is more flexible, and provides mechanisms to support a bunch of use cases, even the ones we are not thinking now.

Well, this is what I think. I'm a heavily React user but the way the functional API was proposed here, for me, solve even some React Hooks problems I'm facing today.
Maybe I can create something like useNewVueApi() for React, hahaha!

[martinsotirov]

As much as I dislike mixins, this RFC seems a lot saner than completely changing the API by reimplementing React hooks, so full support from me for scoped mixins, even though I would never use them.