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

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

/**
 * Applies `mixin` to `superclass`.
 *
 * `apply` stores a reference from the mixin application to the unwrapped mixin
 * to make `isApplicationOf` and `hasMixin` work.
 */
export const apply = (superclass, mixin) => {
  let application = mixin(superclass);
 * // M now works with `hasMixin` and `isApplicationOf`
 * const M = Applier((superclass) => class extends superclass {});
 *
 * class C extends M(Object) {}
 * let i = new C();
 * hasMixin(i, M); // true
 *
 *
 * `isApplicationOf` works by checking that `proto` has a reference to `mixin`
 * as created by `apply`.
 */
export const isApplicationOf = (proto, mixin) =>
  proto.hasOwnProperty(_appliedMixin) && proto[_appliedMixin] === unwrap(mixin);

/**
 * Returns `true` iff `proto` is a prototype created by the application of
 * `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}.
 *      `mixin` inherited by `wrapper`.
 *   2. Sets a special property on `mixin` that points back to `mixin` so that
 *      it can be retreived from `wrapper`
 */
export const wrap = (mixin, wrapper) => {
  Object.setPrototypeOf(wrapper, mixin);
 * @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) => {
 * 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.
 */
export const unwrap = (wrapper) => wrapper[_wrappedMixin] || wrapper;

const _wrappedMixin = '__mixwith_wrappedMixin';
/**
 * Returns `true` iff `o` has an application of `mixin` on its prototype
 * chain.
 */
export const hasMixin = (o, mixin) => {
  while (o != null) {
 *      it can be retreived from `wrapper`
 *
 * @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);
  if (!mixin[_wrappedMixin]) {
    mixin[_wrappedMixin] = mixin;
  }
  return wrapper;
};
 * 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.
 */
export const Cached = (mixin) => wrap(mixin, (superclass) => {
  // Get or create a symbol used to look up a previous application of mixin
 */
export const unwrap = (wrapper) => wrapper[_wrappedMixin] || wrapper;

const _cachedApplications = '__mixwith_cachedApplications';

/**
 * Decorates `mixin` so that it caches its applications. When applied multiple
 * times to the same superclass, `mixin` will only create one subclass, memoize
 * 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
/**
 * Decorates `mixin` so that it only applies if it's not already on the
 * prototype chain.
 */
export const DeDupe = (mixin) => wrap(mixin, (superclass) => {
  if (hasMixin(superclass.prototype, mixin)) return superclass;
    cachedApplications = superclass[_cachedApplications] = new Map();
});

/**

/**
 * Decorates `mixin` so that it only applies if it's not already on the
 * prototype chain.
 *
 * @function
 * @param {MixinFunction} mixin The mixin to wrap with deduplication behavior
 * @return {MixinFunction} a new mixin function
 */
export const DeDupe = (mixin) => wrap(mixin, (superclass) =>
    (hasMixin(superclass.prototype, mixin))
};

/**
 * A basic mixin decorator that sets up a reference from mixin applications
 * to the mixin defintion for use by other mixin decorators.
 */
export const BareMixin = (mixin) => wrap(mixin, (s) => apply(s, mixin));

/**
 * Decorates a mixin function to add application caching and instanceof
 * support.
 */
export const Mixin = (mixin) => DeDupe(Cached(BareMixin(mixin)));

/**
 * A basic mixin decorator that applies the mixin with {@link apply} so that it
 * can be used with {@link isApplicationOf}, {@link hasMixin} and the other
 * mixin decorator functions.
 *
 * @function
 * @param {MixinFunction} mixin The mixin to wrap
 * @return {MixinFunction} a new mixin function
 */
export const BareMixin = (mixin) => wrap(mixin, (s) => apply(s, mixin));
 * This is purely a convenience function. The above example is equivalent to:
 *
 *    class X extends C(B(A(Object))) {}
 */
export const mix = (superclass) => new MixinBuilder(superclass);

export const Mixin = (mixin) => DeDupe(Cached(BareMixin(mixin)));

/**
    this.superclass = superclass;
  }

  with(...mixins) {
    return mixins.reduce((c, m) => m(c), this.superclass);
  }
 * ```javascript
 * class X extends C(B(A(Object))) {}
 * ```
 *
 * @function
 * @param {Function} [superclass=Object]
 * @return {MixinBuilder}
 */
export const mix = (superclass) => new MixinBuilder(superclass);

class MixinBuilder {

  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 jsdoc annotations and update README
<DFF> @@ -3,11 +3,30 @@
 // 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";
+ *       }
+ *     }
+ *
+ * @callback Mixin
+ * @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 {Mixin} mixin The mixin to apply
  */
 export const apply = (superclass, mixin) => {
   let application = mixin(superclass);
@@ -21,6 +40,10 @@ export const apply = (superclass, mixin) => {
  *
  * `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 {Mixin} mixin A mixin function used with {@link apply}.
  */
 export const isApplicationOf = (proto, mixin) =>
   proto.hasOwnProperty(_appliedMixin) && proto[_appliedMixin] === unwrap(mixin);
@@ -38,6 +61,10 @@ const _wrappedMixin = '__mixwith_wrappedMixin';
  *      `mixin` inherited by `wrapper`.
  *   2. Sets a special property on `mixin` that points back to `mixin` so that
  *      it can be retreived from `wrapper`
+ *
+ * @function
+ * @param {Mixin} mixin A mixin function
+ * @param {Mixin} wrapper A function that wraps {@link mixin}
  */
 export const wrap = (mixin, wrapper) => {
   Object.setPrototypeOf(wrapper, mixin);
@@ -51,6 +78,9 @@ export const wrap = (mixin, 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 {Mixin} wrapper A wrapped mixin produced by {@link wrap}
  */
 export const unwrap = (wrapper) => wrapper[_wrappedMixin] || wrapper;
 
@@ -58,6 +88,10 @@ export const unwrap = (wrapper) => wrapper[_wrappedMixin] || wrapper;
 /**
  * Returns `true` iff `o` has an application of `mixin` on its prototype
  * chain.
+ *
+ * @function
+ * @param {Object} o An object
+ * @param {Mixin} mixin A mixin applied with {@link apply}
  */
 export const hasMixin = (o, mixin) => {
   while (o != null) {
@@ -78,6 +112,9 @@ const _cachedApplications = '__mixwith_cachedApplications';
  * 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 {Mixin} 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
@@ -102,6 +139,9 @@ export const Cached = (mixin) => wrap(mixin, (superclass) => {
 /**
  * Decorates `mixin` so that it only applies if it's not already on the
  * prototype chain.
+ *
+ * @function
+ * @param {Mixin} mixin The mixin to wrap with deduplication behavior
  */
 export const DeDupe = (mixin) => wrap(mixin, (superclass) => {
   if (hasMixin(superclass.prototype, mixin)) return superclass;
@@ -109,7 +149,10 @@ export const DeDupe = (mixin) => wrap(mixin, (superclass) => {
 });
 
 /**
- * Adds [@@hasInstance] (ES2015 instanceof support) to `mixin`.
+ * Adds [Symbol.hasInstance] (ES2015 custom instanceof support) to `mixin`.
+ *
+ * @function
+ * @param {Mixin} mixin The mixin to add [Symbol.hasInstance] to
  */
 export const HasInstance = (mixin) => {
   if (Symbol && Symbol.hasInstance && !mixin[Symbol.hasInstance]) {
@@ -123,14 +166,21 @@ export const HasInstance = (mixin) => {
 };
 
 /**
- * A basic mixin decorator that sets up a reference from mixin applications
- * to the mixin defintion for use by other mixin decorators.
+ * A basic mixin decorator that applies the mixin with {@link apply} so that it
+ * can be used with {@link isApplicationOf}, {@link hasMixin} and the other
+ * mixin decorator functions.
+ *
+ * @function
+ * @param {Mixin} mixin The mixin to wrap
  */
 export const BareMixin = (mixin) => wrap(mixin, (s) => apply(s, mixin));
 
 /**
- * Decorates a mixin function to add application caching and instanceof
- * support.
+ * Decorates a mixin function to add deduplication, application caching and
+ * instanceof support.
+ *
+ * @function
+ * @param {Mixin} mixin The mixin to wrap
  */
 export const Mixin = (mixin) => DeDupe(Cached(BareMixin(mixin)));
 
@@ -147,6 +197,9 @@ export const Mixin = (mixin) => DeDupe(Cached(BareMixin(mixin)));
  * This is purely a convenience function. The above example is equivalent to:
  *
  *    class X extends C(B(A(Object))) {}
+ *
+ * @function
+ * @param {Function} superclass
  */
 export const mix = (superclass) => new MixinBuilder(superclass);
 
@@ -156,6 +209,11 @@ class MixinBuilder {
     this.superclass = superclass;
   }
 
+  /**
+   * 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);
   }

Add jsdoc annotations and update README