cfprotected 0.1.0

package/.vscode/launch.json

@@ -0,0 +1,19 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "Jest Tests",
+            "program": "${workspaceRoot}/node_modules/jest/bin/jest.js",
+            "internalConsoleOptions": "openOnSessionStart",
+            "outFiles": [
+                "${workspaceRoot}/dist/**/*"
+            ],
+            "envFile": "${workspaceRoot}/.env"
+        }
+    ]
+}

package/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "cmake.configureOnOpen": false
+}

package/README.md

@@ -0,0 +1,152 @@
+# CFProtected
+This project provides a simple and straight forward means of sharing private
+fields between classes, providing a facility similar to protected members in
+other languages. This project also provides a few other convenience functions
+to work around some the issues inherent in using private fields.
+
+## How to use
+Let's just start with a simple example:
+
+```js
+const { share, accessor } = require("cfprotected");
+
+class Example {
+    //shared static private fields
+    static #shared = share(this, {
+        //Data fields
+        theAnswer: 42,
+        //Methods
+        callMe: () => {
+            console.log("Arrow notation simplifies things.");
+        },
+        //Accessor properties
+        prop: accessor({
+            get: () => { return "An ordinary getter."; },
+            set: (v) => { /* set something here */ }
+        })
+    });
+
+    //shared instance private fields
+    #shared = share(this, Example, {
+        data: "HHGTTG",
+        method: () => { /* do whatever */ },
+        readOnly: accessor({
+            get: () => { return "Nothing to see here!" }
+        })
+    });
+
+    whatIsTheAnswer() {
+        return this.#shared.theAnswer;
+    }
+}
+
+class Derived extends Example {
+    static #shared = share(this, {});
+
+    #shared = share(this, Derived, {});
+
+    test() {
+        console.log(`the Answer is ${this.cla$$.#shared.theAnswer}`);
+        console.log(`Why use arrow notation?`);
+        this.#shared.callMe();
+        this.#shared.theAnswer /= 2;
+        console.log(`What is the answer? ${this.whatIsTheAnswer()}`);
+    }
+}
+```
+
+There are 5 API functions:
+
+* share
+* accessor
+* saveSelf
+* abstract
+* final
+
+The first provides the actual sharing feature. The next 2 provide for work arounds to issues related to this sharing feature as well as Proxy support. The last 2 are just helper functions providing the corresponding limitation to the class.
+
+## **share(instance, class?, memberObject)**
+This function does all the leg work in setting up sharing between a given class and those derived from it. It follows the following general steps.
+
+1. Verify the parameters.
+2. Find any shared member left for the instance.
+3. Create/modify the protected data structure.
+4. Construct and store the shared member record.
+5. Create a class specific accessor object and return it.
+
+The object returned by this function contains an accessor for each of the properties described in the `memberObject` as well as accessors for each of the members that were listed in the shared member record. Any members re-defined on the derived class shadow the same member from the base class **<sup>+</sup>**. As a result, functions of the base class that access this member when used from an instance of the derived class will access the derived class version of that member.
+
+### Notes:
+**+** There is 1 caveat when it comes to shadowing base members. Accessors need to be handled specially. If an accessor is defined directly in `memberObject`, it cannot be properly shadowed. The methods of each class will only be able to access the version  of the member defined in that class. To ensure accessors can properly be shadowed across the entire inheritance chain, use the following API function.
+
+## **accessor(descriptor)**
+The property descriptor passed to this function is a limited version of the standard ES property descriptor object, only allowing `get` and `set` members. All other members of this object are ignored. A new property descriptor is created and tagged so that the `share` function will use it as the accessor descriptor for the corresponding property in the accessor object. It is this relocation that allows for proper shadowing of shared accessors. 
+
+### Notes:
+There is a secondary purpose for this `accessor` method. The biggest "gotcha" related to this approach to sharing members is that the members are all owned by an object other than `this`. At the same time, if the member is a function or accessor, it needs to be bound to `this`. Only runtime assignment can guarantee this, so creating such methods as field initializers is the only simple way to do it without resorting to the constructor.
+
+## **saveSelf(self, name)**
+This method provides a means to work around the issue that comes along with using private fields together with Proxy. Since Proxy does not pass through access to private fields without a full membrane setup, the most straight forward solution is to provide a "self" property on the instance. This function is a convenience function that allows you to create and name that property. Use this function in the static block and/or constructor.
+```js
+class Example {
+    static {
+        saveSelf(this, "shared");
+    }
+
+    constructor() {
+        saveSelf(this, "shared");
+    }
+
+    ...
+}
+```
+
+As a bonus, when used on the constructor, it creates an additional property named "cla\$\$" on the prototype. This "cla\$\$" property gives instances a means to reference the class constructor even when the class itself is anonymous. This is a fill-in feature for one of the TC39 proposals offering syntax for the same.
+
+## **abstract(klass)**
+This method is a class wrapper that prevents instances of the class from being constructed directly. To construct an instance of the class you must extend it. This should be nearly identical to the same functionality that exists in some compiled languages.
+```js
+const Example = abstract(class {
+    ...
+});
+```
+
+### Note:
+This method uses a proxy internally to keep things consistent. However, the Proxy is not a membrane. So it's best if any use of static private fields is accessed through the property created by using `saveSelf(...)`.
+
+## **final(klass)**
+This method is a class wrapper that prevents instances of the class from being created using descendant classes.
+```js
+const Example = final(class {
+    ...
+});
+```
+
+### Note:
+Just as with `abstract(...)`, this method uses a proxy internally to keep things consistent. However, the Proxy is not a membrane. So it's best if any use of static private fields is accessed through the property created by using `saveSelf(...)`. Unfortunately, there's also a limitation with final. Normally in compiled languages, it is a syntax error to even create a class that extends from a final class. However, without taking over the means of building the class (as can be done with Babel or my ClassicJS library) it's just not possible to restrict that event. As a result, the only thing left to check for is construction of instances of such an error.
+
+## Other features
+There will be occasions when a shared function that shadows an ancestor function needs to call the ancestor's function. Unfortunately, `super` cannot give you access to these. There is a similar problem when accessing accessors and data properties. To satisfy this need, the class-specific accessor option is given an additional property: `$uper`. Using this property, it is possible to reach the ancestor version of any shared member.
+
+```js
+class A {
+    #shared = share(this, A, {
+        doSomething: () => { console.log(`Called A::doSomething`); }
+    });
+
+    ...
+}
+
+class B extends A {
+    #shared = share(this, B, {
+        doSomething: () => {
+            console.log(`Called B::doSomething`);
+            this.#shared.$uper.doSomething();
+        }
+    });
+
+    test() {
+        this.#shared.doSomething();
+    }
+}
+```

package/index.js

@@ -0,0 +1,183 @@
+const memos = new WeakMap();
+const ACCESSOR = Symbol();
+
+function getAllOwnKeys(o) {
+    return Object.getOwnPropertyNames(o)
+        .concat(Object.getOwnPropertySymbols(o));
+}
+
+/**
+ * Used to both store inherited property information as well as retrieve it.
+ * @param {Object} inst The instance object that will own the shared members.
+ * @param {Function?} klass The constructor function of the class sharing
+ * members. Optional. If omitted, defaults to inst.
+ * @param {Object} members The object containing the properties being shared.
+ * @returns {Object} The fully constructed inheritance object.
+ */
+module.exports.share = function share(inst, klass, members) {
+    let retval = {};
+
+    if ((typeof(inst) == "function") 
+        && klass && (typeof(klass) == "object")
+        && (members === void 0)) {
+        members = klass;
+        klass = inst;
+    }
+
+    if (!inst || !["function", "object"].includes(typeof(inst))) {
+        throw new TypeError(`Expected inst to be a function or an object.`);
+    }
+    if (!klass || (typeof(klass) != "function")) {
+        throw new TypeError(`Expected klass to be a function.`);
+    }
+    if (!members || (typeof(members) != "object")) {
+        throw new TypeError(`Expected members to be an object.`);
+    }
+
+    
+    /*
+    * Each class' memo entry has the following structure:
+    * 
+    * inst: {
+    *   data: <Object> - the actual protected data object
+    *   inheritance: <Object> - the object of accessor properties to share
+    *                           with descendant classes.
+    * }
+    */
+   
+    //Find the nearest known registered ancestor
+    let ancestor = Object.getPrototypeOf(klass);
+    while (ancestor && !memos.has(ancestor)) {
+        ancestor = Object.getPrototypeOf(ancestor);
+    }
+
+    //Get the memo from that ancestor
+    let ancestorMemo = memos.get(ancestor) || new WeakMap();
+
+    //Create a memo for the current class
+    if (!memos.has(klass)) {
+        memos.set(klass, new WeakMap());
+    }
+
+    //Get the protected data object.
+    let memo = ancestorMemo.get(inst) || {data: {}, $uper: {}, inheritance: null};
+    let protData = memo.data;
+    
+    //Get the details of the protected properties.
+    let mDesc = Object.getOwnPropertyDescriptors(members);
+    let mKeys = getAllOwnKeys(members);
+
+    //Change the prototype of protoData using the new members.
+    let prototype = Object.getPrototypeOf(protData);
+    let proto = Object.create(prototype,
+        Object.fromEntries(mKeys
+            .filter(k => !mDesc[k].value?.hasOwnProperty(ACCESSOR))
+            .map(k => [k, mDesc[k]])));
+    Object.setPrototypeOf(protData, proto);
+
+    //Build the accessors for this class.
+    mKeys.forEach(m => {
+        let desc = (mDesc[m].value?.hasOwnProperty(ACCESSOR))
+            ? {
+                enumerable: true,
+                get: mDesc[m].value.get,
+                set: mDesc[m].value.set
+            }
+            : mDesc[m];
+        
+        Object.defineProperty(retval, m, desc);
+    });
+    
+    //Define the "super" accessors
+    Object.defineProperty(retval, "$uper", { value: {} });
+
+    for (let key of mKeys) {
+        if (key in prototype) {
+            let obj = prototype;
+            while (!obj.hasOwnProperty(key)) {
+                obj = Object.getPrototypeOf(obj);
+            }
+            Object.defineProperty(retval.$uper, key, Object.getOwnPropertyDescriptor(obj, key));
+        }
+    }
+
+    //Attach the super inheritance
+    Object.setPrototypeOf(retval.$uper, memo.$uper);
+
+    //Inherit the inheritance
+    Object.setPrototypeOf(retval, memo.inheritance);
+
+    //Save the inheritance & protected data
+    memos.get(klass).set(inst, {
+        data: protData,
+        inheritance: retval,
+        $uper: retval.$uper
+    });    
+
+    return retval;
+}
+
+/**
+ * Binds the class instance to itself to allow code to selectively avoid Proxy
+ * issues, especially ones involving private fields. Also binds the class
+ * constructor to the instance for static referencing as "cla$$".
+ * @param {Object} self The current class instance as seen from the constructor.
+ * @param {String} name The name of the field on which to bind the instance.
+ */
+ module.exports.saveSelf = function(self, name) {
+    Object.defineProperty(self, name, {value: self});
+    if (typeof(self) == "function") {
+        Object.defineProperty(self.prototype, "cla$$", {value: self});
+    }
+}
+
+/**
+ * Marks the property as a shared, overrideable accessor and defines the 
+ * getter and setter methods for it.
+ * @param {Object} desc Object containing get and/or set definitions for the
+ * accessor.
+ * @returns {Object} A tagged object that will be used to create the access
+ * bindings for the property.
+ */
+module.exports.accessor = function(desc) {
+    if ((typeof(desc) == "object") &&
+        (("get" in desc) || ("set" in desc))) {
+        return {
+            [ACCESSOR]: undefined,
+            get: desc.get,
+            set: desc.set
+        }
+    }
+}
+
+/**
+ * A class wrapper that blocks construction of an instance if the class being
+ * instantiated is not a descendant of the current class.
+ * @param {Function} klass The constructor of the current class.
+ */
+module.exports.abstract = function(klass) {
+    return new Proxy(klass, {
+        construct(target, args, newTarget) {
+            if (newTarget.prototype === klass.prototype)
+                throw new TypeError(`Cannot construct instance of abstract class.`);
+
+            return Reflect.construct(target, args, newTarget);
+        }
+    });
+};
+
+/**
+ * A class wrapper that blocks construction of an instance if the class being
+ * constructed is a descendant of the current class.
+ * @param {Function} klass The constructor of the current class.
+ */
+module.exports.final = function(klass) {
+    return new Proxy(klass, {
+        construct(target, args, newTarget) {
+            if (newTarget.prototype !== klass.prototype)
+                throw new TypeError(`Cannot extend final class.`);
+
+            return Reflect.construct(target, args, newTarget);
+        }
+    });
+};

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "cfprotected",
+  "version": "0.1.0",
+  "description": "An implementation of protected fields on top of class fields.",
+  "main": "index.js",
+  "scripts": {
+    "test": "jest"
+  },
+  "keywords": [
+    "class",
+    "private",
+    "protected",
+    "inheritance"
+  ],
+  "author": "Ranando D. King",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rdking/CFProtected.git"
+  },
+  "devDependencies": {
+    "jest": "^27.4.3"
+  }
+}

package/test/test.js

@@ -0,0 +1,138 @@
+const { TestWatcher } = require("@jest/core");
+const { share, saveSelf, accessor } = require("../index"); //require("cfprotected");
+
+class Base {
+    #prot = share(this, Base, {
+        num: 42,
+        name: "John Jacob Jingleheimerschmidt",
+        method: () => {
+            return "It works.";
+        },
+        prop: accessor({
+            get: () => this.propTestVal
+        }),
+        superTest: () => {
+            console.log(`Called Base::superTest() ...`);
+            return 1;
+        }
+    });
+
+    constructor() {
+        saveSelf(this, "pvt");
+    }
+
+    testName = "John Jacob Jingleheimerschmidt";
+    propTestVal = "I can make this return anything!";
+
+    checkProp(proxied) {
+        expect((proxied?this.pvt:this).#prot.prop).toBe(this.propTestVal);
+    }
+
+    run() {
+        test(`Access to shared members should just work on the instance`, () => {
+            expect(this.#prot.num).toBe(42);
+            expect(this.#prot.name).toBe(this.testName);
+            expect(this.#prot.method()).toBe("It works.");
+            this.checkProp();
+        });
+        
+        test(`Access to shared members should work even through a Proxy`, () => {
+            let that = new Proxy(this, {});
+            expect(that.pvt.#prot.num).toBe(42);
+            expect(that.pvt.#prot.name).toBe(this.testName);
+            expect(that.pvt.#prot.method()).toBe("It works.");
+            this.checkProp(true);
+        });
+    }
+}
+
+class Derived extends Base {
+    #prot = share(this, Derived, {
+        otherMethod: () => {
+            this.#prot.name = this.testName;
+        },
+        prop: accessor({
+            get: () => this.propTestVal2
+        })
+    });
+
+    constructor() {
+        super();
+        saveSelf(this, "pvt");
+        this.propTestVal2 = this.propTestVal;
+    }
+
+    run() {
+        super.run();
+
+        test(`Should be able to change a shared property value`, () => {
+            this.testName = "A. Nony Mouse";
+            expect(() => { this.#prot.otherMethod(); }).not.toThrow();
+            this.checkProp();
+        });
+    }
+}
+
+class NonParticipant extends Base {}
+
+class GrandChild extends NonParticipant {
+    #prot = share(this, GrandChild, {
+        otherMethod: () => {
+            this.#prot.name = this.testName;
+        },
+        superTest: () => {
+            console.log(`Called GrandChild::superTest() ...`);
+            return 1 + this.pvt.#prot.$uper.superTest();
+        }
+    });
+
+    constructor() {
+        super();
+        saveSelf(this, "pvt");
+    }
+
+    run() {
+        super.run();
+
+        test(`Should be able to change a shared property value`, () => {
+            this.testName = "A. Nony Mouse 1";
+            expect(() => { this.#prot.otherMethod(); }).not.toThrow();
+            this.checkProp();
+        });
+    }
+}
+
+class SuperTest extends GrandChild {
+    #prot = share(this, SuperTest, {
+        superTest: () => {
+            console.log(`Called SuperTest::superTest() ...`);
+            return 1 + this.pvt.#prot.$uper.superTest();
+        }
+    });
+
+    constructor() {
+        super();
+        saveSelf(this, "pvt");
+    }
+
+    run() {
+        test(`Should be able to call super through the entire inheritance chain`, () => {
+            expect(this.pvt.#prot.superTest()).toBe(3);
+        });
+    }
+}
+
+describe(`Testing shared elements in the base class`, () => {
+    (new Base).run();
+});
+describe(`Testing shared elements in a direct descendant`, () => {
+    (new Derived).run();
+});
+
+describe(`Testing shared elements inherited from a non-participant`, () => {
+    (new GrandChild).run();
+});
+
+describe(`Testing that $uper works in all cases`, () => {
+    (new SuperTest).run();
+})