mythix-orm 1.11.6 → 1.12.0

package/lib/proxy-class/proxy-class.js

@@ -4,27 +4,27 @@
 
 'use strict';
 
-const APPLY                       = Symbol.for('@_apply');
-const CALLABLE                    = Symbol.for('@_callable');
-const CONSTRUCT                   = Symbol.for('@_construct');
-const DEFINE_PROPERTY             = Symbol.for('@_defineProperty');
-const DELETE_PROPERTY             = Symbol.for('@_deleteProperty');
-const GET                         = Symbol.for('@_get');
-const GET_OWN_PROPERTY_DESCRIPTOR = Symbol.for('@_getOwnPropertyDescriptor');
-const GET_PROTOTYPEOF             = Symbol.for('@_getPrototypeOf');
-const HAS                         = Symbol.for('@_has');
-const IS_EXTENSIBLE               = Symbol.for('@_isExtensible');
-const MISSING                     = Symbol.for('@_missing');
-const OWN_KEYS                    = Symbol.for('@_ownKeys');
-const PREVENT_EXTENSIONS          = Symbol.for('@_preventExtensions');
-const SET                         = Symbol.for('@_set');
-const SET_PROTOTYPEOF             = Symbol.for('@_setPrototypeOf');
-const PROXY                       = Symbol.for('@__proxy');
-const TARGET                      = Symbol.for('@__target');
-const SELF                        = Symbol.for('@__rootInstance');
-const AUTO_CALL_CALLER            = Symbol.for('@__autoCallCaller');
-const AUTO_CALL_CALLED            = Symbol.for('@__autoCallCalled');
-const AUTO_CALL                   = Symbol.for('@__autoCall');
+const APPLY                       = Symbol.for('@_mythix/orm/ProxyClass/apply');
+const CALLABLE                    = Symbol.for('@_mythix/orm/ProxyClass/callable');
+const CONSTRUCT                   = Symbol.for('@_mythix/orm/ProxyClass/construct');
+const DEFINE_PROPERTY             = Symbol.for('@_mythix/orm/ProxyClass/defineProperty');
+const DELETE_PROPERTY             = Symbol.for('@_mythix/orm/ProxyClass/deleteProperty');
+const GET                         = Symbol.for('@_mythix/orm/ProxyClass/get');
+const GET_OWN_PROPERTY_DESCRIPTOR = Symbol.for('@_mythix/orm/ProxyClass/getOwnPropertyDescriptor');
+const GET_PROTOTYPEOF             = Symbol.for('@_mythix/orm/ProxyClass/getPrototypeOf');
+const HAS                         = Symbol.for('@_mythix/orm/ProxyClass/has');
+const IS_EXTENSIBLE               = Symbol.for('@_mythix/orm/ProxyClass/isExtensible');
+const MISSING                     = Symbol.for('@_mythix/orm/ProxyClass/missing');
+const OWN_KEYS                    = Symbol.for('@_mythix/orm/ProxyClass/ownKeys');
+const PREVENT_EXTENSIONS          = Symbol.for('@_mythix/orm/ProxyClass/preventExtensions');
+const SET                         = Symbol.for('@_mythix/orm/ProxyClass/set');
+const SET_PROTOTYPEOF             = Symbol.for('@_mythix/orm/ProxyClass/setPrototypeOf');
+const PROXY                       = Symbol.for('@__mythix/orm/ProxyClass/proxy');
+const TARGET                      = Symbol.for('@__mythix/orm/ProxyClass/target');
+const SELF                        = Symbol.for('@__mythix/orm/ProxyClass/rootInstance');
+const AUTO_CALL_CALLER            = Symbol.for('@__mythix/orm/ProxyClass/autoCallCaller');
+const AUTO_CALL_CALLED            = Symbol.for('@__mythix/orm/ProxyClass/autoCallCalled');
+const AUTO_CALL                   = Symbol.for('@__mythix/orm/ProxyClass/autoCall');
 
 function shouldSkipProxy(prop) {
   if (prop === 'bind' || prop === 'call' || prop === 'apply')
@@ -39,6 +39,26 @@ function shouldSkipProxy(prop) {
   return false;
 }
 
+/// This is essentially a [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)
+/// converted into class form. What that means is that instead of defining a
+/// proxy by passing it a "handlers" object to it, this instead *is* the handler
+/// for all classes that inherit from it. Just like a `Proxy`, inheriting from
+/// this class will allow the child-class to intercept property gets and sets,
+/// intercept method calls, property deletion, etc...
+///
+/// It works by returning `this` inside the `constructor` wrapped in a
+/// `Proxy`. The `Proxy` it creates is then managed by the class instance itself.
+/// For example, during key access, if a key the user is requesting is not found,
+/// the proxy will call the instance method `MISSING` on the class. This allows
+/// the child class to provide a method for `MISSING`, and then respond to key
+/// access for keys that don't actually exist on the instance.
+///
+/// That is just one example of many. This class provides full `Proxy` support,
+/// and so has methods (or stubs) for every feature available natively to a `Proxy`.
+/// Instance methods are keyed by symbols. This is to try and reduce the chance
+/// of a name collision... keeping this class useful for many scenarios. For example,
+/// the `MISSING` method above is actually `Symbol.for('@_mythix/orm/ProxyClass/missing')`,
+/// that is assigned to the constant <see>ProxyClass.MISSING</see>.
 class ProxyClass {
   static APPLY = APPLY;
   static CALLABLE = CALLABLE;
@@ -175,6 +195,8 @@ class ProxyClass {
     return proxy;
   }
 
+  /// Construct the class instance, with
+  /// `this` returned wrapped in a `Proxy`.
   constructor() {
     Object.defineProperties(this, {
       [AUTO_CALL_CALLER]: {
@@ -195,6 +217,65 @@ class ProxyClass {
     return proxy;
   }
 
+  /// Any method of the instance wrapped in an
+  /// `__autoCall` factory will be automatically
+  /// called by the engine if not called by the user.
+  ///
+  /// This works by the `ProxyClass` pushing the auto-call
+  /// into a queue when the method key is accessed. If another
+  /// key is accessed (any other key), then the `ProxyClass` will
+  /// check if the auto-call method has been called yet. If it
+  /// hasn't, then the `ProxyClass` will call it, providing no
+  /// arguments, and using the return value of the call for the
+  /// pending key access. If the auto-call method is simply called,
+  /// then the queue is cleared, and the return value simply returned
+  /// to the user.
+  ///
+  /// Example:
+  ///   class Greeter extends ProxyClass {
+  ///     greet = this.__autoCall((name) => {
+  ///       if (arguments.length === 0) {
+  ///         // An auto-call, or the user didn't
+  ///         // provide any arguments.
+  ///         console.log('Hello whoever you are!');
+  ///       } else {
+  ///         // Was definitely called by the user
+  ///         console.log(`Hello ${name}!`);
+  ///       }
+  ///     });
+  ///
+  ///     finish() {
+  ///       // finish operation
+  ///     }
+  ///   }
+  ///
+  ///   // Example 1
+  ///   let greeter = new Greeter();
+  ///   greeter.greet.finish();
+  ///   //           ^---- Auto call happens here
+  ///   // output: Hello whoever you are!
+  ///
+  ///   // Example 2
+  ///   greeter.greet('Wyatt Greenway').finish();
+  ///   // No auto-call happens... this is a manual call.
+  ///   // output: Hello Wyatt Greenway!
+  ///
+  /// Note:
+  ///   For an auto-call to work, a key access attempt must happen
+  ///   after the auto-call method is accessed. This is almost always
+  ///   the case, because in interacting with the object you are almost
+  ///   guaranteed to access a key again, i.e. `.toString` if converting
+  ///   to a string, `.toJSON` if converting to JSON, iterator access,
+  ///   or even debugging the object.
+  ///
+  /// Arguments:
+  ///   caller: Function
+  ///     The method implementation for the class. This method will
+  ///     be used by the factory to create an auto-call method for
+  ///     the class.
+  ///
+  /// Return: Function
+  ///   The `caller` method provided, wrapped into an auto-call factory method.
   __autoCall(caller) {
     this[AUTO_CALL_CALLER] = caller;
     this[AUTO_CALL_CALLED] = false;
@@ -202,6 +283,60 @@ class ProxyClass {
     return this;
   }
 
+  /// This is a factory much like <see>ProxyClass.__autoCall</see>
+  /// for creating instance methods. It differs however in that
+  /// the method returned by this factory isn't auto-called, but
+  /// instead an *optional* call.
+  ///
+  /// The way it works is that the method provided is returned,
+  /// itself wrapped in a `Proxy`. If it is called, then the
+  /// `Proxy` will pass the call through to the method, and return
+  /// the result. Being a `Proxy`, it passes all key access back
+  /// to the original class instance, allowing the method itself
+  /// to mimic the class instance. This allows for instance methods
+  /// that can *optionally* be called, but if they aren't called,
+  /// will act as though you are still interacting with the instance
+  /// of the class itself.
+  ///
+  /// Example:
+  ///   class Greeter extends ProxyClass {
+  ///     constructor() {
+  ///       super();
+  ///
+  ///       this.greetName = undefined;
+  ///     }
+  ///
+  ///     name = this.__call((name) => {
+  ///       this.greetName = name;
+  ///     });
+  ///
+  ///     greet() {
+  ///       if (this.greetName) {
+  ///         console.log(`Hello ${this.greetName}!`);
+  ///       } else {
+  ///         console.log('Hello whoever you are!');
+  ///       }
+  ///     }
+  ///   }
+  ///
+  ///   // Example 1
+  ///   let greeter = new Greeter();
+  ///   greeter.name.greet();
+  ///   //          ^---- optional call here
+  ///   // output: Hello whoever you are!
+  ///
+  ///   // Example 2
+  ///   greeter.name('Wyatt Greenway').greet();
+  ///   // output: Hello Wyatt Greenway!
+  ///
+  /// Arguments:
+  ///   caller: Function
+  ///     The method implementation for the class. This method will
+  ///     be used by the factory to create an optional call method for
+  ///     the class.
+  ///
+  /// Return: Function
+  ///   The `caller` method provided, wrapped into an optional call factory method.
   __call(caller) {
     return ProxyClass.createProxy.call(this, caller.bind(this[PROXY]));
   }