art-class-system/source/Art.ClassSystem/BaseClass.js

// Generated by CoffeeScript 1.12.7
(function() {
  "use strict";
  var BaseClass, ExtendablePropertyMixin, Log, MinimalBaseObject, StandardLib, Unique, WebpackHotLoader, callStack, capitalize, concatInto, decapitalize, functionName, getModuleBeingDefined, getSuperclass, inspectedObjectLiteral, isFunction, isPlainArray, isPlainObject, isString, log, merge, mergeInto, neq, nextUniqueObjectId, object, objectName,
    extend = function(child, parent) { for (var key in parent) { if (hasProp.call(parent, key)) child[key] = parent[key]; } function ctor() { this.constructor = child; } ctor.prototype = parent.prototype; child.prototype = new ctor(); child.__super__ = parent.prototype; return child; },
    hasProp = {}.hasOwnProperty,
    indexOf = [].indexOf || function(item) { for (var i = 0, l = this.length; i < l; i++) { if (i in this && this[i] === item) return i; } return -1; };

  StandardLib = require('art-standard-lib');

  WebpackHotLoader = require('./WebpackHotLoader');

  capitalize = StandardLib.capitalize, decapitalize = StandardLib.decapitalize, log = StandardLib.log, isFunction = StandardLib.isFunction, objectName = StandardLib.objectName, isPlainObject = StandardLib.isPlainObject, functionName = StandardLib.functionName, isString = StandardLib.isString, isPlainArray = StandardLib.isPlainArray, Unique = StandardLib.Unique, callStack = StandardLib.callStack, Log = StandardLib.Log, log = StandardLib.log, inspectedObjectLiteral = StandardLib.inspectedObjectLiteral, MinimalBaseObject = StandardLib.MinimalBaseObject, getModuleBeingDefined = StandardLib.getModuleBeingDefined, concatInto = StandardLib.concatInto, mergeInto = StandardLib.mergeInto, merge = StandardLib.merge, neq = StandardLib.neq, isString = StandardLib.isString, object = StandardLib.object, getSuperclass = StandardLib.getSuperclass;

  nextUniqueObjectId = Unique.nextUniqueObjectId;

  ExtendablePropertyMixin = require('./ExtendablePropertyMixin');

  module.exports = BaseClass = (function(superClass) {
    var createWithPostCreate, getSingleton, imprintObject, nonImprintableProps, thoroughDeleteProperty, warnedAboutIncludeOnce;

    extend(BaseClass, superClass);

    BaseClass.resetStats = function() {
      BaseClass.objectsCreated = 0;
      return BaseClass.objectsCreatedByType = {};
    };

    BaseClass.resetStats();

    BaseClass._name = null;


    /*
    NOTE: only hasOwnProperties are considered! Inherited properties are not touched.
    IN:
      targetObject:   object will be altered to be an "imprint" of fromObject
      fromObject: object pattern used to imprint targetObject
      preserveState:
        false:
          targetObject has every property updated to exactly match fromObject
    
          This includes:
            1. delete properties in targetObject that are not in fromObject
            2. add every property in fromObject but not in targetObject
            3. overwriting every property in targetObject also in fromObject
    
        true:
          Attempts to preserve the state of targetObject while updating its functionality.
          This means properties which are functions in either object are updated.
    
          WARNING: This is a grey area for JavaScript. It is not entirely clear what is
            state and what is 'functionality'. I, SBD, have made the following heuristic decisions:
    
          Imprint actions taken when preserving State:
    
          1. DO NOTHING to properties in targetObject that are not in fromObject
          2. add every property in fromObject but not in targetObject
          3. properties in targetObject that are also in fromObject are updated
            if one of the following are true:
            - isFunction fromObject[propName]
            - isFunction targetObject[propName]
            - propName does NOT start with "_"
            NOTE: property existance is detected using Object.getOwnPropertyDescriptor
     */

    thoroughDeleteProperty = function(object, propName) {
      Object.defineProperty(object, propName, {
        configurable: true,
        writable: false,
        value: 1
      });
      return delete object[propName];
    };

    nonImprintableProps = ["__proto__", "prototype"];

    BaseClass.imprintObject = imprintObject = function(targetObject, sourceObject, preserveState, returnActionsTaken) {
      var addedProps, changedProps, i, j, len, len1, neqResult, removedProps, sourcePropDescriptor, sourcePropName, sourcePropertyNames, sourceValue, sourceValueIsFunction, targetPropDescriptor, targetPropName, targetPropertyNames, targetValue, targetValueIsFunction;
      if (preserveState == null) {
        preserveState = false;
      }
      targetPropertyNames = Object.getOwnPropertyNames(targetObject);
      sourcePropertyNames = Object.getOwnPropertyNames(sourceObject);
      if (returnActionsTaken) {
        addedProps = removedProps = changedProps = void 0;
      }
      if (!preserveState) {
        for (i = 0, len = targetPropertyNames.length; i < len; i++) {
          targetPropName = targetPropertyNames[i];
          if (!(!(indexOf.call(sourcePropertyNames, targetPropName) >= 0))) {
            continue;
          }
          if (returnActionsTaken) {
            (removedProps != null ? removedProps : removedProps = []).push(targetPropName);
          }
          thoroughDeleteProperty(targetObject, targetPropName);
        }
      }
      for (j = 0, len1 = sourcePropertyNames.length; j < len1; j++) {
        sourcePropName = sourcePropertyNames[j];
        if (!(!(indexOf.call(nonImprintableProps, sourcePropName) >= 0))) {
          continue;
        }
        targetPropDescriptor = Object.getOwnPropertyDescriptor(targetObject, sourcePropName);
        sourcePropDescriptor = Object.getOwnPropertyDescriptor(sourceObject, sourcePropName);
        sourceValueIsFunction = isFunction(sourceValue = sourcePropDescriptor.value);
        targetValueIsFunction = isFunction(targetValue = targetPropDescriptor != null ? targetPropDescriptor.value : void 0);
        if (!preserveState || !targetPropDescriptor || sourceValueIsFunction || targetValueIsFunction || !sourcePropName.match(/^_/)) {
          if (returnActionsTaken) {
            if (!targetPropDescriptor) {
              if (sourcePropName !== "_name") {
                (addedProps != null ? addedProps : addedProps = []).push(sourcePropName);
              }
            } else {
              if (neqResult = neq(sourceValue, targetValue, true)) {
                (changedProps != null ? changedProps : changedProps = []).push(sourcePropName);
              }
            }
          }
          Object.defineProperty(targetObject, sourcePropName, sourcePropDescriptor);
        }
      }
      if (returnActionsTaken) {
        return (removedProps || changedProps || addedProps) && merge({
          removedProps: removedProps,
          changedProps: changedProps,
          addedProps: addedProps
        });
      } else {
        return sourceObject;
      }
    };


    /*
    imprints both the class and its prototype.
    
    preserved in spite of imprintObject's rules:
      @namespace
      @::constructor
     */

    BaseClass.imprintFromClass = function(updatedKlass, returnActionsTaken) {
      var _name, classUpdates, namespace, namespacePath, oldConstructor, prototypeUpdates, ref;
      if (updatedKlass !== this) {
        ref = this, namespace = ref.namespace, namespacePath = ref.namespacePath, _name = ref._name;
        oldConstructor = this.prototype.constructor;
        classUpdates = imprintObject(this, updatedKlass, true, returnActionsTaken);
        prototypeUpdates = imprintObject(this.prototype, updatedKlass.prototype, false, returnActionsTaken);
        this.prototype.constructor = oldConstructor;
        this.namespace = namespace;
        this.namespacePath = namespacePath;
        this._name = _name;
      }
      if (returnActionsTaken) {
        return merge({
          "class": classUpdates,
          prototype: prototypeUpdates
        });
      } else {
        return this;
      }
    };

    BaseClass.getHotReloadKey = function() {
      return this.getName();
    };


    /*
    IN:
      _module should be the CommonJS 'module'
      klass: class object which extends BaseClass
    
    liveClass:
      On the first load, liveClass gets set.
      Each subsequent hot-load UPDATES liveClass,
      but liveClass always points to the initially created class object.
    
    OUT: the result of the call to liveClass.postCreate()
    
    postCreate is passed:
      hotReloaded:            # true if this is anything but the initial load
      classModuleState:
        liveClass:            # the original liveClass
        hotUpdatedFromClass:  # the most recently hot-loaded class
        hotReloadVersion:     # number starting at 0 and incremented with each hot reload
      _module:                # the CommonJs module
    
    EFFECTS:
      The following two methods are invoked on liveClass:
    
        if hot-reloading
          liveClass.imprintFromClass klass
    
         * always:
        liveClass.postCreate hotReloaded, classModuleState, _module
     */

    BaseClass.createWithPostCreate = createWithPostCreate = function(a, b) {
      var _module, klass;
      klass = b ? (_module = a, b) : a;
      _module || (_module = getModuleBeingDefined() || global.__definingModule);
      if (!(klass != null ? klass.postCreate : void 0)) {
        return klass;
      }
      if (!(_module != null ? _module.hot : void 0)) {
        return klass.postCreate({
          hotReloadEnabled: false,
          hotReloaded: false,
          classModuleState: {},
          module: _module
        }) || klass;
      }
      return WebpackHotLoader.runHot(_module, function(moduleState) {
        var classModuleState, hotReloadKey, hotReloaded, liveClass, obj1, updates;
        hotReloadKey = klass.getHotReloadKey();
        if (classModuleState = moduleState[hotReloadKey]) {
          liveClass = classModuleState.liveClass;
          hotReloaded = true;
          classModuleState.hotReloadVersion++;
          classModuleState.hotUpdatedFromClass = klass;
          liveClass.namespace._setChildNamespaceProps(liveClass.getName(), klass);
          klass._name = liveClass._name;
          liveClass.classModuleState = classModuleState;
          updates = liveClass.imprintFromClass(klass, true);
          log((
            obj1 = {},
            obj1["Art.ClassSystem.BaseClass " + (typeof liveClass.getName === "function" ? liveClass.getName() : void 0) + " HotReload"] = {
              version: classModuleState.hotReloadVersion,
              updates: updates
            },
            obj1
          ));
        } else {
          hotReloaded = false;
          klass._hotClassModuleState = moduleState[hotReloadKey] = klass.classModuleState = classModuleState = {
            liveClass: liveClass = klass,
            hotUpdatedFromClass: null,
            hotReloadVersion: 0
          };
        }
        return liveClass.postCreate({
          hotReloadEnabled: true,
          hotReloaded: hotReloaded,
          classModuleState: classModuleState,
          module: _module
        });
      });
    };

    BaseClass.createHotWithPostCreate = function(a, b) {
      log.error("createHotWithPostCreate is DEPRICATED");
      return createWithPostCreate(a, b);
    };


    /*
    called every load
    IN: options:
      NOTE: hot-loading inputs are only set if this class created as follows:
        createHotWithPostCreate module, class Foo extends BaseClass
    
      hotReload: true/false
        true if this class was hot-reloaded
    
      hotReloadEnabled: true/false
    
      classModuleState:
        liveClass:            the first-loaded version of the class.
                              This is the official version of the class at all times.
                              The hot-reloaded version of the class is "imprinted" onto the liveClass
                              but otherwise is not used (but can be accessed via classModuleState.hotUpdatedFromClass)
        hotUpdatedFromClass:  The most recently loaded version of the class.
        hotReloadVersion:     number, starting at 1, and counting up each load
    
        classModuleState is a plain-object specific to the class and its CommonJS module. If there is
        more than one hot-loaded class in the same module, each will have its own classModuleState.
    
        SBD NOTE: Though we could allow clients to add fields to classModuleState, I think it works
        just as well, and is cleaner, if any state is stored in the actual class objects and
        persisted via postCreate.
    
      module: the CommonJs module object.
    
    {hotReloadEnabled, hotReloaded, classModuleState, module} = options
     */

    BaseClass.postCreate = function(options) {
      if (this.getIsAbstractClass()) {
        return this.postCreateAbstractClass(options);
      } else {
        return this.postCreateConcreteClass(options);
      }
    };

    BaseClass.setNamespace = function(ns) {
      return this._namespace = ns;
    };

    BaseClass.postCreateAbstractClass = function(options) {
      return this;
    };

    BaseClass.postCreateConcreteClass = function(options) {
      return this;
    };

    function BaseClass() {
      this.__uniqueId = null;
    }

    BaseClass.implementsInterface = function(object, methods) {
      var i, len, method;
      for (i = 0, len = methods.length; i < len; i++) {
        method = methods[i];
        if (typeof object[method] !== "function") {
          return false;
        }
      }
      return true;
    };


    /*
    mix-in class methods
    Define getters/setters example:
      class MyMixin
        included: ->
          @getter foo: -> @_foo
          @setter foo: (v) -> @_foo = v
    
    NOTE! This will NOT include any properties you defined with getter or setter!
    NOTE! This only copies over values if there aren't already values in the included-into class
      This somewhat mirrors Ruby's include where the included-into-class's methods take precidence.
      However, if you include two modules in a row, the first module gets priority here.
      In ruby the second module gets priority (I believe).
    
    DEPRICATED!!!
    Time to do it "right" - and it's just a simple pattern:
      Justin Fagnani figured this out. Thanks!
      Read More:
        http://justinfagnani.com/2015/12/21/real-mixins-with-javascript-classes/
    
    To define a mixin:
    
      MyMixin = (superClass) ->
        class MyMixin extends superClass
          ... write your mixin as-if it were part of the normal inheritance hierachy
    
    To use a mixin:
    
      class MyClass extends MyMixin MySuperClass
    
    To use two mixins:
    
      class MyClass extends MyMixin1 MyMixin2 MySuperClass
     */

    warnedAboutIncludeOnce = false;

    BaseClass.include = function(obj) {
      var key, ref, value;
      log.error("DEPRICATED: BaseClass.include. Use pattern.");
      if (!warnedAboutIncludeOnce) {
        warnedAboutIncludeOnce = true;
        console.warn("Mixin pattern:\n\n  To define a mixin:\n\n    MyMixin = (superClass) ->\n      class MyMixin extends superClass\n        ... write your mixin as-if it were part of the normal inheritance hierachy\n\n  To use a mixin:\n\n    class MyClass extends MyMixin MySuperClass\n\n  To use two mixins:\n\n    class MyClass extends MyMixin1 MyMixin2 MySuperClass");
      }
      for (key in obj) {
        value = obj[key];
        if (key !== 'included') {
          if (!this[key]) {
            this[key] = value;
          }
        }
      }
      ref = obj.prototype;
      for (key in ref) {
        value = ref[key];
        if (key) {
          if (!this.prototype[key]) {
            this.prototype[key] = value;
          }
        }
      }
      if (typeof obj.included === "function") {
        obj.included(this);
      }
      return this;
    };

    BaseClass.getNamespacePath = function() {
      var ref;
      if ((ref = this.namespacePath) != null ? ref.match(this.getName()) : void 0) {
        return this.namespacePath;
      } else {
        return this.namespacePath = "(no parent namespace)." + (this.getName());
      }
    };

    BaseClass.getNamespacePathWithExtendsInfo = function() {
      return (this.getNamespacePath()) + " extends " + (getSuperclass(this).getNamespacePath());
    };

    BaseClass.getClassName = function(klass) {
      if (klass == null) {
        klass = this;
      }
      return (typeof klass.getName === "function" ? klass.getName() : void 0) || klass.name;
    };


    /*
    inspect: ->
    IN: ()
    OUT: string
    
    Can override with same or alternate, recursion-block-supported signature:
      IN: (inspector) ->
      OUT: if inspector then null else string
    
      To handle the case where the inspector is not set, we
      recommneded declaring your 'inspect' as follows:
        inspect: (inspector) ->
          return StandardLib.inspect @ unless inspector
           * ...
           * custom code which writes all output to inspector.put
           * and uses inspector.inspect for inspecting sub-objects
           * ...
          null
    
      EFFECT:
        call inspector.put one or multiple times with strings to add to the inspected output
        call inspector.inspect foo to sub-inspect other objects WITH RECURSION BLOCK
    
     * Example 1:
    inspect: (inspector) ->
      return StandardLib.inspect @ unless inspector
      inspector.put @getNamespacePath()
    
     * Example 2:
    inspect: ->
      @getNamespacePath()
     */

    BaseClass.inspect = function() {
      return this.getNamespacePath();
    };

    BaseClass.prototype.inspect = function() {
      return "<" + this["class"].namespacePath + ">";
    };


    /*
    getInspectedObjects: -> plainObjects
    
    usually implemented this way:
    @getter inspectedObjects: -> plainObjects or objects which implement "inspect"
    
    TODO: I think I want to refactor inspectedObjects to ONLY return near-JSON-compatible objects:
      1. strings
      2. maps
      3. arrays
    
      Everything else should be rendered to a string. In general, strings should Eval to the object
      they represent:
    
        toInspectedObject(null):                    'null' # null becomes a string
        toInspectedObject(true):                    'true' # true becomes a string
        toInspectedObject(false):                   'false' # false becomes a string
        toInspectedObject(undefined):               'undefined' # undefined becomes a string
        toInspectedObject('hi'):                    '"hi"' # ESCAPED
        toInspectedObject((a) -> a):                'function(a){return a;}'
        toInspectedObject(rgbColor())               "rgbColor('#000000')"
    
      NOTE: inspectedObjects differs from plainObjects. The latter should be 100% JSON,
        and should return actual values where JSON allows, otherwise, return JSON data structures
        that encode the object's information in a human-readable format, ideally one that can be
        used as an input to the constructor of the object's class to recreate the original object.
    
        plainObjects:
          null:         null
          true:         true
          false:        false
          'str':        'str' # NOT escaped
          undefined:    null
          ((a) -> a):   'function(a){return a;}'
          rgbColor():   r: 0, g: 0, b: 0, a: 0
    
    You can provide this function for fine-grained control of what Inspector2 outputs and hence
    what DomConsole displays.
    
    If you would like for a string to appear without quotes, use:
      {inspect: -> 'your string without quotes here'}
     */

    BaseClass.getter({
      inspectObjects: function() {
        console.warn("inspectObjects/getInspectObjects is DEPRICATED. Use: inspectedObjects/getInspectedObjects");
        return this.getInspectedObjects();
      },
      inspectedObjects: function() {
        var ref;
        return inspectedObjectLiteral("<" + ((ref = this["class"]) != null ? ref.getNamespacePath() : void 0) + ">");
      }
    });

    BaseClass.classGetter({
      inspectedObjects: function() {
        return inspectedObjectLiteral("class " + (this.getNamespacePath()));
      }
    });


    /*
    Define this class as an abstract class. Implicitly it means
    any class it extends is also abstract, at least in this context.
    
    Definition: Abstract classes are not intended to every be instantiated.
      i.e.: never do: new MyAbstractClass
    
    TODO: in Debug mode, in the constructor:
      throw new Error "cannot instantiate abstract classes" if @class.getIsAbstractClass()
     */

    BaseClass.abstractClass = function() {
      if (this.getIsSingletonClass()) {
        throw new Error("abstract classes cannot also be singleton");
      }
      return this._firstAbstractAncestor = this;
    };

    BaseClass.classGetter({
      superclass: function() {
        return getSuperclass(this);
      },
      isAbstractClass: function() {
        return !(this.prototype instanceof this._firstAbstractAncestor);
      },
      isConcreteClass: function() {
        return !this.getIsAbstractClass();
      },
      abstractPrototype: function() {
        return this._firstAbstractAncestor.prototype;
      },
      firstAbstractAncestor: function() {
        return this._firstAbstractAncestor;
      },
      isSingletonClass: function() {
        var ref;
        return ((ref = this._singleton) != null ? ref["class"] : void 0) === this;
      },
      concretePrototypeProperties: function() {
        var abstractClassPrototype;
        abstractClassPrototype = this.getAbstractClass().prototype;
        return object(this.prototype, {
          when: function(v, k) {
            return k !== "constructor" && abstractClassPrototype[k] !== v;
          }
        });
      }
    });

    BaseClass.getAbstractClass = function() {
      return this._firstAbstractAncestor;
    };

    BaseClass.abstractClass();

    BaseClass.propertyIsAbstract = function(propName) {
      return this.getAbstractClass().prototype[propName] === this.prototype[propName];
    };

    BaseClass.propertyIsConcrete = function(propName) {
      return this.getAbstractClass().prototype[propName] !== this.prototype[propName];
    };


    /*
    SBD2017: this is the new path for singleton classes.
    WHY: We can elliminate the need to DECLARE classes singleton.
      Instead, we can just access the singleton for any class, if needed.
    TODO: once we are 100% CaffeineScript, switch this to a @classGetter
     */

    BaseClass.getSingleton = getSingleton = function() {
      var ref;
      if (((ref = this._singleton) != null ? ref["class"] : void 0) === this) {
        return this._singleton;
      } else {
        if (this.getIsAbstractClass()) {
          throw new Error("singleton classes cannot be abstract");
        }
        return this._singleton = new this;
      }
    };


    /*
    creates the classGetter "singleton" which returns a single instance of the current class.
    
    IN: args are passed to the singleton constructor
    OUT: null
    
    The singleton instance is created on demand the first time it is accessed.
    
    SBD2017: Possibly depricated; maybe we just need a singleton getter for everyone?
      The problem is coffeescript doesn't properly inherit class getters.
      BUT ES6 and CaffeineScript DO. So, when we switch over, I think we can do this.
     */

    BaseClass.singletonClass = function() {
      var obj1;
      if (this.getIsAbstractClass()) {
        throw new Error("singleton classes cannot be abstract");
      }
      this.classGetter((
        obj1 = {
          singleton: getSingleton
        },
        obj1["" + (decapitalize(functionName(this)))] = function() {
          return this.getSingleton();
        },
        obj1
      ));
      return null;
    };

    BaseClass.getter({
      className: function() {
        return this["class"].getClassName();
      },
      "class": function() {
        return this.constructor;
      },
      keys: function() {
        return Object.keys(this);
      },
      namespacePath: function() {
        return this["class"].getNamespacePath();
      },
      classPathName: function() {
        return this.namespacePath;
      },
      classPathNameAndId: function() {
        return this.classPathName + ":" + this.objectId;
      },
      uniqueId: function() {
        return this.__uniqueId || (this.__uniqueId = nextUniqueObjectId());
      },
      objectId: function() {
        return this.__uniqueId || (this.__uniqueId = nextUniqueObjectId());
      }
    });

    BaseClass.prototype.freeze = function() {
      this.getUniqueId();
      Object.freeze(this);
      return this;
    };

    BaseClass.prototype.implementsInterface = function(methods) {
      return Function.BaseClass.implementsInterface(this, methods);
    };

    BaseClass.prototype.tap = function(f) {
      f(this);
      return this;
    };

    return BaseClass;

  })(ExtendablePropertyMixin(MinimalBaseObject));

}).call(this);

//# sourceMappingURL=BaseClass.js.map