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

// Generated by CoffeeScript 1.12.7
(function() {
  var cloneStructure, concatInto, defineModule, each, formattedInspect, isBoolean, isFunction, isNumber, isPlainArray, isPlainObject, isString, log, lowerCamelCase, merge, mergeInto, object, ref, upperCamelCase,
    extend1 = 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,
    slice = [].slice;

  ref = require('art-standard-lib'), defineModule = ref.defineModule, log = ref.log, object = ref.object, upperCamelCase = ref.upperCamelCase, lowerCamelCase = ref.lowerCamelCase, each = ref.each, isPlainObject = ref.isPlainObject, isPlainArray = ref.isPlainArray, isFunction = ref.isFunction, isNumber = ref.isNumber, isBoolean = ref.isBoolean, cloneStructure = ref.cloneStructure, isString = ref.isString, mergeInto = ref.mergeInto, concatInto = ref.concatInto, formattedInspect = ref.formattedInspect, merge = ref.merge;


  /*
  Todo:
    validatedDeclarable / validatedExtendableProperty
      Which use Art.Validation
  
  TODO:
    When we switch to ES6, we should make the
    class API look identical to the current instance API.
  
    That means declarable API looks like this:
      @extendableProperty foo: {}
  
       * extend:
      @foo: hi: 123
  
    The differnce is we add a ":".
  
    The benefit is it's a normal getter/setter pair:
  
      @foo = hi: 123
  
      log @foo
  
    The one diference is the "setter" is really an
    "extender"
   */

  defineModule(module, function() {
    return function(superClass) {
      var ExtendablePropertyMixin;
      return ExtendablePropertyMixin = (function(superClass1) {
        var arrayPropertyExtender, defaultExtender, getOwnProperty, noOptions, objectPropertyExtender, optimizedInitFunction;

        extend1(ExtendablePropertyMixin, superClass1);

        function ExtendablePropertyMixin() {
          return ExtendablePropertyMixin.__super__.constructor.apply(this, arguments);
        }


        /*
        IN
          object: any object
          property: string, property name
          init:
            (object) -> returning initial value for object
            OR
              initial value is computed by:
              cloneStructure object[property] || init
        
        EFFECT:
          if object.hasOwnProperty property, return its current value
          otherwise, initialize and return it with init()
         */

        ExtendablePropertyMixin.getOwnProperty = getOwnProperty = function(object, internalName, init) {
          if (object.hasOwnProperty(internalName)) {
            return object[internalName];
          } else {
            return object[internalName] = init(object, internalName);
          }
        };

        optimizedInitFunction = function(internalName, init) {
          switch (false) {
            case !isFunction(init):
              return init;
            case !(isString(init) || isNumber(init) || isBoolean(init)):
              return function(object) {
                var ref1;
                return (ref1 = object[internalName]) != null ? ref1 : init;
              };
            default:
              return function(object) {
                var ref1;
                return cloneStructure((ref1 = object[internalName]) != null ? ref1 : init);
              };
          }
        };


        /*
        objectPropertyExtender
        
        IN: @ is set to the property-value to extend
        
        API 1:
          IN: map
          EFFECT: mergeInto propValue, map
        
        API 2:
          IN: key, value
          EFFECT: propValue[key] = valuee
        
        OUT: ignore
         */

        ExtendablePropertyMixin.objectPropertyExtender = objectPropertyExtender = function(toExtend, mapOrKey, value) {
          if (mapOrKey === void 0 || mapOrKey === null) {
            return toExtend;
          }
          if (isString(mapOrKey)) {
            toExtend[mapOrKey] = value;
          } else if (isPlainObject(mapOrKey)) {
            mergeInto(toExtend, mapOrKey);
          } else {
            log({
              mapOrKey: mapOrKey,
              value: value,
              type: mapOrKey != null ? mapOrKey.constructor : void 0
            });
            throw new Error("first value argument must be a plain object or string: " + (formattedInspect({
              key: mapOrKey,
              value: value
            })));
          }
          return toExtend;
        };


        /*
        arrayPropertyExtender
        
        IN: valueToExtend, value
          value:
            array: concatInto propValue, array
            non-array: propValue.push value
        
        NOTE: if you want to concat an array-as-a-value to the end of propValue, do this:
          arrayPropertyExtender.call propValue, [arrayAsValue]
        
        OUT: ignore
         */

        ExtendablePropertyMixin.arrayPropertyExtender = arrayPropertyExtender = function(toExtend, arrayOrValue) {
          if (isPlainArray(arrayOrValue)) {
            concatInto(toExtend, arrayOrValue);
          } else {
            toExtend.push(arrayOrValue);
          }
          return toExtend;
        };


        /*
        Extendable Properties
        
        EXAMPLE:
          class Foo extends BaseClass
            @extendableProperty foo: {}
        
        Extendable properties work like inheritance:
        
          When any subclass or instance extends an extendable property, they
          inherit a cloneStructure of the property from up the inheritance tree, and then
          add their own extensions without effecting the parent copy.
        
          With Object property types, this can just be a parallel prototype chain.
          (It isn't currently: if you modify a parent after extending it to a child,
          the child won't get updates.)
        
          BUT, you can also have array or other types of extend-properties, which
          JavaScript doesn't have any built-in mechanisms for inheriting.
        
        BASIC API:
        @extendableProperty: (map, options) -> ...
        
        IN:
          map: name: defaultValue
          options:
            declarable: true/false
              if true, slightly alters the created functions:
                for: @extendableProperty foo: ...
                generates:
                  @foo
        
            extend:
              DEFAULTS:
                switch defaultValue
                when is Object then objectPropertyExtender
                when is Array  then arrayPropetyExtender
                else                defaultExtender
        
              (extendable, extendWithValues...) -> newExtendedOwnPropertyValue
                IN:
                  extendable: the current, extended value, already cloned, so direct mutation is OK
                  extendWithValues: 1 or more values passed into the extend funtion by the client.
                    Ex: for an array, this is either a single value or an array
                    Ex: for an object, this is either a single object or two args: key, value
                OUT: new property value to set own-property to
                EFFECT:
                  Can be pure functional and just return the new, extended data.
                  OR
                  Can modify extendable directly, since it is an object/array/atomic value unique to the current class/instance.
                    If modifying extendable directly, be sure to return extendable.
                  Regardless, the returned value becomes the new extendable prop's value.
        
        
        
        EFFECT: for each {foo: defaultValue} in map, extendableProperty:
          WARNING:
            !!! Don't modify the object returned by a getter !!!
        
            Getters only return the current, most-extended property value. It may not be extended to the
            current subclass or instance! Instead, call @extendFoo() if you wish to manually modify
            the extended property.
        
          declarable:
            getters:
              @getFoo:
              getFoo:
        
            extenders:
              @foo:
              foo:
        
          non-declarable:
        
            getters:
              @getFoo:
              @getter foo:
        
            extenders:
              @foo:
              @extendFoo:
              extendFoo:
        
              IN:
                0-args: nothing happens beyond the standard EFFECT
                1+args: passed to the "extend" function
        
              EFFECT: creates a extension (cloneStructure) of the property for the currnet class, subclass or instance
              OUT: the current, extendedPropValue
        
              API 1: IN: 0 args
                NO ADDITIONAL EFFECT - just returns the extended property
              API 2: IN: 1 or more args
                In addition to extending and returning the extended property:
                calls: propExtender extendedPropValue, args...
        
            NOTE: gthe prototype getters call the class getter for extension purposes.
              The result is each instance won't get its own version of the property.
              E.G. Interitance is done at the Class level, not the Instance level.
         */

        defaultExtender = function(toExtend, v) {
          if (v === void 0) {
            throw new Error("not expecting undefined");
          }
          return v;
        };

        noOptions = {};

        ExtendablePropertyMixin.extendableProperty = function(map, options) {
          var declarable, extend, noSetter, oldExtender;
          if (options == null) {
            options = noOptions;
          }
          if (isFunction(oldExtender = options)) {
            log.error("DEPRICATED customPropertyExtender not supported, use extend: option ");
            options = {
              extend: function() {
                var args, extendable;
                extendable = arguments[0], args = 2 <= arguments.length ? slice.call(arguments, 1) : [];
                return oldExtender.apply(extendable, args);
              }
            };
          }
          extend = options.extend, declarable = options.declarable, noSetter = options.noSetter;
          return each(map, (function(_this) {
            return function(defaultValue, name) {
              var extenderName, getterName, instanceExtender, instanceGetter, internalName, propertyExtender, ucProp;
              name = lowerCamelCase(name);
              ucProp = upperCamelCase(name);
              internalName = _this.propInternalName(name);
              getterName = "get" + ucProp;
              extenderName = "extend" + ucProp;
              propertyExtender = (function() {
                if (extend != null) {
                  return extend;
                } else if (isPlainObject(defaultValue)) {
                  return objectPropertyExtender;
                } else if (isPlainArray(defaultValue)) {
                  return arrayPropertyExtender;
                } else {
                  if (defaultValue === void 0) {
                    throw new Error("defaultValue must not be undefined");
                  }
                  return defaultExtender;
                }
              })();
              _this[getterName] = function() {
                var ref1;
                return (ref1 = this.prototype[internalName]) != null ? ref1 : defaultValue;
              };
              _this[name] = _this[extenderName] = function(value) {
                var extendablePropValue;
                extendablePropValue = getOwnProperty(this.prototype, internalName, optimizedInitFunction(internalName, defaultValue));
                if (arguments.length > 0 && value !== void 0) {
                  this.prototype[internalName] = propertyExtender.apply(null, [extendablePropValue].concat(slice.call(arguments)));
                }
                return extendablePropValue;
              };
              instanceGetter = function() {
                var ref1;
                return (ref1 = this[internalName]) != null ? ref1 : defaultValue;
              };
              instanceExtender = _this.prototype[extenderName] = function(value) {
                var extendablePropValue;
                extendablePropValue = getOwnProperty(this, internalName, optimizedInitFunction(internalName, defaultValue));
                if (arguments.length > 0 && value !== void 0) {
                  this[internalName] = propertyExtender.apply(null, [extendablePropValue].concat(slice.call(arguments)));
                }
                return extendablePropValue;
              };
              if (declarable) {
                _this.prototype[getterName] = instanceGetter;
                return _this.prototype[name] = instanceExtender;
              } else {
                if (!noSetter) {
                  _this.addSetter(name, instanceExtender);
                }
                return _this.addGetter(name, instanceGetter);
              }
            };
          })(this));
        };

        ExtendablePropertyMixin.declarable = function(map, options) {
          return this.extendableProperty(map, merge(options, {
            declarable: true
          }));
        };

        return ExtendablePropertyMixin;

      })(superClass);
    };
  });

}).call(this);

//# sourceMappingURL=ExtendablePropertyMixin.js.map