<NME> mixwith.js
<BEF> 'use strict';

// used by apply() and isApplicationOf()
const _appliedMixin = '__mixwith_appliedMixin';

/**
 * A function that returns a subclass of its argument.
 *
 * @example
 * const M = (superclass) => class extends superclass {
 *   getMessage() {
 *     return "Hello";
 *   }
 * }
 *
 * @typedef {Function} MixinFunction
 * @param {Function} superclass
 */

/**
 * Applies `mixin` to `superclass`.
 *
 * `apply` stores a reference from the mixin application to the unwrapped mixin
 * to make `isApplicationOf` and `hasMixin` work.
 *
 * @function
 * @param {Function} superclass A class or constructor function
 * @param {MixinFunction} mixin The mixin to apply
 */
export const apply = (superclass, mixin) => {
  let application = mixin(superclass);
 * const M = Applier((superclass) => class extends superclass {});
 *
 * class C extends M(Object) {}
 * let i = new C();
 * hasMixin(i, M); // true
 *
 * @function
 * @param {Function} superclass A class or constructor function
 * @param {MixinFunction} mixin The mixin to apply
 * @return {Function} A subclass of `superclass` produced by `mixin`
 */
 * @function
 * @param {Object} proto A prototype object created by {@link apply}.
 * @param {MixinFunction} mixin A mixin function used with {@link apply}.
 */
export const isApplicationOf = (proto, mixin) =>
  proto.hasOwnProperty(_appliedMixin) && proto[_appliedMixin] === unwrap(mixin);
 * `mixin` to a superclass.
 *
 * `isApplicationOf` works by checking that `proto` has a reference to `mixin`
 * as created by `apply`.
 *
 * @function
 * @param {Object} proto A prototype object created by {@link apply}.
 * @param {MixinFunction} mixin A mixin function used with {@link apply}.
 * @return {boolean} whether `proto` is a prototype created by the application of
 * `mixin` to a superclass
 */
export const isApplicationOf = (proto, mixin) =>
  proto.hasOwnProperty(_appliedMixin) && proto[_appliedMixin] === unwrap(mixin);

/**
 * @function
 * @param {MixinFunction} mixin A mixin function
 * @param {MixinFunction} wrapper A function that wraps {@link mixin}
 */
export const wrap = (mixin, wrapper) => {
  Object.setPrototypeOf(wrapper, mixin);
 * chain
 */
export const hasMixin = (o, mixin) => {
  while (o != null) {
    if (isApplicationOf(o, mixin)) return true;
    o = Object.getPrototypeOf(o);
  }
  return false;
}

 *
 * @function
 * @param {MixinFunction} wrapper A wrapped mixin produced by {@link wrap}
 */
export const unwrap = (wrapper) => wrapper[_wrappedMixin] || wrapper;

 * `wrapper` to be unwrapped to get to the original function.
 *
 * `wrap` does two things:
 *   1. Sets the prototype of `mixin` to `wrapper` so that properties set on
 *      `mixin` inherited by `wrapper`.
 * @function
 * @param {Object} o An object
 * @param {MixinFunction} mixin A mixin applied with {@link apply}
 */
export const hasMixin = (o, mixin) => {
  while (o != null) {
export const wrap = (mixin, wrapper) => {
  Object.setPrototypeOf(wrapper, mixin);
  if (!mixin[_wrappedMixin]) {
    mixin[_wrappedMixin] = mixin;
  }
  return wrapper;
};

/**
 * Unwraps the function `wrapper` to return the original function wrapped by
 * one or more calls to `wrap`. Returns `wrapper` if it's not a wrapped
 * function.
 *
 * @function
 * @param {MixinFunction} wrapper A wrapped mixin produced by {@link wrap}
 * @return {MixinFunction} The originally wrapped mixin
 */
 *
 * @function
 * @param {MixinFunction} mixin The mixin to wrap with caching behavior
 */
export const Cached = (mixin) => wrap(mixin, (superclass) => {
  // Get or create a symbol used to look up a previous application of mixin
 * it and return it for each application.
 *
 * Note: If `mixin` somehow stores properties its classes constructor (static
 * properties), or on its classes prototype, it will be shared across all
 * applications of `mixin` to a super class. It's reccomended that `mixin` only
 * access instance state.
 *
 * @function
 * @param {MixinFunction} mixin The mixin to wrap with caching behavior
 * @return {MixinFunction} a new mixin function
 */
export const Cached = (mixin) => wrap(mixin, (superclass) => {
  // Get or create a symbol used to look up a previous application of mixin
  // to the class. This symbol is unique per mixin definition, so a class will have N
  // applicationRefs if it has had N mixins applied to it. A mixin will have
  // exactly one _cachedApplicationRef used to store its applications.

  let cachedApplications = superclass[_cachedApplications];
  if (!cachedApplications) {
    cachedApplications = superclass[_cachedApplications] = new Map();
  }
 *
 * @function
 * @param {MixinFunction} mixin The mixin to wrap with deduplication behavior
 */
export const DeDupe = (mixin) => wrap(mixin, (superclass) => {
  if (hasMixin(superclass.prototype, mixin)) return superclass;
  return application;
});

/**
 * Decorates `mixin` so that it only applies if it's not already on the
 *
 * @function
 * @param {MixinFunction} mixin The mixin to add [Symbol.hasInstance] to
 */
export const HasInstance = (mixin) => {
  if (Symbol && Symbol.hasInstance && !mixin[Symbol.hasInstance]) {
    (hasMixin(superclass.prototype, mixin))
      ? superclass
      : mixin(superclass));

/**
 * Adds [Symbol.hasInstance] (ES2015 custom instanceof support) to `mixin`.
 *
 * @function
 * @param {MixinFunction} mixin The mixin to add [Symbol.hasInstance] to
 * @return {MixinFunction} the given mixin function
 */
export const HasInstance = (mixin) => {
  if (Symbol && Symbol.hasInstance && !mixin[Symbol.hasInstance]) {
 *
 * @function
 * @param {MixinFunction} mixin The mixin to wrap
 */
export const BareMixin = (mixin) => wrap(mixin, (s) => apply(s, mixin));

};

/**
 *
 * @function
 * @param {MixinFunction} mixin The mixin to wrap
 */
export const Mixin = (mixin) => DeDupe(Cached(BareMixin(mixin)));

 */
export const BareMixin = (mixin) => wrap(mixin, (s) => apply(s, mixin));

/**
 * Decorates a mixin function to add deduplication, application caching and
 * instanceof support.
 *
 * @function
 * @param {MixinFunction} mixin The mixin to wrap
 * @return {MixinFunction} a new mixin function
 */
export const Mixin = (mixin) => DeDupe(Cached(BareMixin(mixin)));

/**
 * A fluent interface to apply a list of mixins to a superclass.
 *
 * @function
 * @param {Function} superclass
 */
export const mix = (superclass) => new MixinBuilder(superclass);

 *
 * This is purely a convenience function. The above example is equivalent to:
 *
 * ```javascript
 * class X extends C(B(A(Object))) {}
 * ```
 *
   * Applies `mixins` in order to the superclass given to `mix()`.
   *
   * @param {Array.<Mixin>} mixins
   */
  with(...mixins) {
    return mixins.reduce((c, m) => m(c), this.superclass);

  constructor(superclass) {
    this.superclass = superclass || class {};
  }

  /**
   * Applies `mixins` in order to the superclass given to `mix()`.
   *
   * @param {Array.<Mixin>} mixins
   * @return {Function} a subclass of `superclass` with `mixins` applied
   */
  with(...mixins) {
    return mixins.reduce((c, m) => m(c), this.superclass);
  }
}

<MSG> Add @return annotations
<DFF> @@ -15,6 +15,7 @@ const _appliedMixin = '__mixwith_appliedMixin';
  *
  * @typedef {Function} MixinFunction
  * @param {Function} superclass
+ * @return {Function} A subclass of `superclass`
  */
 
 /**
@@ -26,6 +27,7 @@ const _appliedMixin = '__mixwith_appliedMixin';
  * @function
  * @param {Function} superclass A class or constructor function
  * @param {MixinFunction} mixin The mixin to apply
+ * @return {Function} A subclass of `superclass` produced by `mixin`
  */
 export const apply = (superclass, mixin) => {
   let application = mixin(superclass);
@@ -43,6 +45,8 @@ export const apply = (superclass, mixin) => {
  * @function
  * @param {Object} proto A prototype object created by {@link apply}.
  * @param {MixinFunction} mixin A mixin function used with {@link apply}.
+ * @return {boolean} whether `proto` is a prototype created by the application of
+ * `mixin` to a superclass
  */
 export const isApplicationOf = (proto, mixin) =>
   proto.hasOwnProperty(_appliedMixin) && proto[_appliedMixin] === unwrap(mixin);
@@ -64,6 +68,7 @@ const _wrappedMixin = '__mixwith_wrappedMixin';
  * @function
  * @param {MixinFunction} mixin A mixin function
  * @param {MixinFunction} wrapper A function that wraps {@link mixin}
+ * @return {MixinFunction} `wrapper`
  */
 export const wrap = (mixin, wrapper) => {
   Object.setPrototypeOf(wrapper, mixin);
@@ -80,6 +85,7 @@ export const wrap = (mixin, wrapper) => {
  *
  * @function
  * @param {MixinFunction} wrapper A wrapped mixin produced by {@link wrap}
+ * @return {MixinFunction} The originally wrapped mixin
  */
 export const unwrap = (wrapper) => wrapper[_wrappedMixin] || wrapper;
 
@@ -91,6 +97,8 @@ export const unwrap = (wrapper) => wrapper[_wrappedMixin] || wrapper;
  * @function
  * @param {Object} o An object
  * @param {MixinFunction} mixin A mixin applied with {@link apply}
+ * @return {boolean} whether `o` has an application of `mixin` on its prototype
+ * chain
  */
 export const hasMixin = (o, mixin) => {
   while (o != null) {
@@ -114,6 +122,7 @@ const _cachedApplications = '__mixwith_cachedApplications';
  *
  * @function
  * @param {MixinFunction} mixin The mixin to wrap with caching behavior
+ * @return {MixinFunction} a new mixin function
  */
 export const Cached = (mixin) => wrap(mixin, (superclass) => {
   // Get or create a symbol used to look up a previous application of mixin
@@ -141,6 +150,7 @@ export const Cached = (mixin) => wrap(mixin, (superclass) => {
  *
  * @function
  * @param {MixinFunction} mixin The mixin to wrap with deduplication behavior
+ * @return {MixinFunction} a new mixin function
  */
 export const DeDupe = (mixin) => wrap(mixin, (superclass) => {
   if (hasMixin(superclass.prototype, mixin)) return superclass;
@@ -152,6 +162,7 @@ export const DeDupe = (mixin) => wrap(mixin, (superclass) => {
  *
  * @function
  * @param {MixinFunction} mixin The mixin to add [Symbol.hasInstance] to
+ * @return {MixinFunction} the given mixin function
  */
 export const HasInstance = (mixin) => {
   if (Symbol && Symbol.hasInstance && !mixin[Symbol.hasInstance]) {
@@ -171,6 +182,7 @@ export const HasInstance = (mixin) => {
  *
  * @function
  * @param {MixinFunction} mixin The mixin to wrap
+ * @return {MixinFunction} a new mixin function
  */
 export const BareMixin = (mixin) => wrap(mixin, (s) => apply(s, mixin));
 
@@ -180,6 +192,7 @@ export const BareMixin = (mixin) => wrap(mixin, (s) => apply(s, mixin));
  *
  * @function
  * @param {MixinFunction} mixin The mixin to wrap
+ * @return {MixinFunction} a new mixin function
  */
 export const Mixin = (mixin) => DeDupe(Cached(BareMixin(mixin)));
 
@@ -201,6 +214,7 @@ export const Mixin = (mixin) => DeDupe(Cached(BareMixin(mixin)));
  *
  * @function
  * @param {Function} superclass
+ * @return {MixinBuilder}
  */
 export const mix = (superclass) => new MixinBuilder(superclass);
 
@@ -214,6 +228,7 @@ class MixinBuilder {
    * Applies `mixins` in order to the superclass given to `mix()`.
    *
    * @param {Array.<Mixin>} mixins
+   * @return {Function} a subclass of `superclass` with `mixins` applied
    */
   with(...mixins) {
     return mixins.reduce((c, m) => m(c), this.superclass);

Add @return annotations