Merge branch 'DelegatorsParam' into develop

Adds in the Delegators Parameter from RFC 5545 section 3.2.4.

There are a couple TODO's left behind for when I get to later sections
of the RFC. It doesn't make sense to work out an implementation until
I'm working on those actual features that will use it.
Signed-off-by: Mark Stenglein <mark@stengle.in>

package.json

@@ -8,7 +8,7 @@
     "dist/"
   ],
   "scripts": {
-    "test": "NODE_ENV=test nyc --reporter=text mocha -R nyan --recursive --compilers ts:ts-node/register --bail",
+    "test": "NODE_ENV=test nyc --reporter=text mocha -R nyan --recursive --compilers ts:ts-node/register",
     "glabCLI": "mocha -R mochawesome -r ts-node/register test/**/*.spec.ts",
     "lint": "tslint -r tslint.json src/**/*.ts",
     "cover": "NODE_ENV=test nyc --reporter=text-summary npm run glabCLI",

src/DelegatorsParam.ts

@@ -17,23 +17,100 @@
  */
 import Parameter from "./Parameter";
 
+/**
+ * DelegatorsParam Class (Chapter 3.2.4)
+ *
+ * - Purpose: To specify the calendar users that have delegated their
+ *   participation to the calendar user specified by the property.
+ *
+ * - Format Definition: This property parameter is defined by the following
+ *   notation:
+ *
+ *     - delfromparam  = "DELEGATED-FROM" "=" DQUOTE cal-address
+ *                       DQUOTE *("," DQUOTE cal-address DQUOTE)
+ *
+ * - Description:
+ *     - The parameter is specified on properties of the CAL-ADDRESS value
+ *       type.
+ *     - TODO: Enforce this restriction on the type allowed to hold this parameter
+ *     - This parameter specified those calendar users that have delegated their
+ *       participation in a group-scheduled event or to-do to the calendar user
+ *       specified by the property.
+ *     - The individual calendar address parameter values MUST each be specified
+ *       in a quoted-string.
+ *
+ * - Example:
+ *
+ *     ATTENDEE;DELEGATED-FROM="mailto:jsmith@example.com":mailto:
+ *      jdoe@example.com
+ *
+ *   - Note: The Param here ends with the DQUOTE, the rest is part of ATTENDEE
+ *
+ * @since 0.1.0
+ * @author Mark Stenglein <mark@stengle.in>
+ */
 export default class DelegatorsParam extends Parameter {
     private _delegators: string[];
 
+    /**
+     * Takes either one email or an array of emails as string or string[]
+     *
+     * - There is really no need to require that "mailto:" be included here,
+     *   as it can be easilly added by the set method.
+     *
+     * @since 0.1.0
+     * @author Mark Stenglein <mark@stengle.in>
+     */
     constructor(delegators: string | string[]) {
         super("DELEGATED-FROM", []);
 
         // Converts single string object to an array.
         delegators = (delegators instanceof Array) ? delegators : [delegators];
-        this._delegators = delegators;
+        this.delegators = delegators;
     }
 
+    /**
+     * Simply returns the current delegators, as a string array.
+     *
+     * @since 0.1.0
+     * @author Mark Stenglein <mark@stengle.in>
+     */
     get delegators(): string[] {
         return this._delegators;
     }
 
+    /**
+     * Sets the private _delegators and also writes the "mailto:" to the
+     * front of each delegator before writing super.paramValues
+     *
+     * DONE: Add proper testing to make sure that only valid delegators
+     *       are added
+     *
+     * @since 0.1.0
+     * @author Mark Stenglein <mark@stengle.in>
+     */
     set delegators(newDelegators: string[]) {
+        // Empty array to build the parent paramValues from newDelegators
+        const paramValues: string[] = [];
+
+        /*
+         * Checks to make sure that each individual Delegator
+         *  consists only of QSafeChars before wrapping it in DQUOTEs
+         *  and adding the `mailto:`
+         */
+        newDelegators.forEach((newDelegator: string) => {
+            if (!Parameter.isQSafeChar(newDelegator)) {
+                throw new TypeError("Delegator must be QSafeChars");
+            } else {
+                paramValues.push("\"mailto:" + newDelegator + "\"");
+            }
+        });
+
+        // Passes the built paramValues to the Parent class
+        this.paramValues = paramValues;
+
+        // Saves the given values for the getter funciton
         this._delegators = newDelegators;
-        this.paramValues = this._delegators;
     }
 }
+

src/Parameter.ts

@@ -132,25 +132,19 @@ export default class Parameter implements ICalElement {
      * @throws TypeError if any of the input values are not valid param-value's
      */
     set paramValues(newValues: string[]) {
-        let valid: boolean = true;
         newValues.forEach(newValue => {
             if (
                 !((Parameter.isParamText(newValue)) ||
                 (Parameter.isQuotedString(newValue)))
             ) {
-                valid = false;
+                throw new TypeError(
+                    "param-value must either be valid paramtext or" +
+                        " quoted-string"
+                );
             }
         });
 
-        if (!valid) {
-            throw new TypeError(
-                "param-value must either be valid paramtext or" +
-                " quoted-string"
-            );
-        }
-        else {
-            this._paramValues = newValues;
-        }
+        this._paramValues = newValues;
     }
 
 

test/DelegatorsParam.spec.ts

@@ -22,45 +22,97 @@ import "mocha";
 /**
  * Test the DelegatorsParam class.
  */
-describe("DelegatorsParam", () => {
+describe("DelegatorsParam:", () => {
     it("Should exist", () => {
         expect(DelegatorsParam).to.exist;
     });
 
-    describe("Constructor", () => {
+    describe("Constructor:", () => {
         it("Should create an object", () => {
             const delegator: string = "Mark Stenglein";
             const delegatorParam: DelegatorsParam = new DelegatorsParam(delegator);
+
             expect(delegatorParam).to.exist;
         });
 
         it("Should convert string to string[]", () => {
             const delegator: string = "Mark Stenglein";
             const testParam: DelegatorsParam = new DelegatorsParam(delegator);
+
             expect(testParam.delegators).to.be.deep.equal([delegator]);
         });
 
         it("Should not add extra layer to input array", () => {
             const delegators: string[] = ["Mark", "Stenglein"];
             const testParam: DelegatorsParam = new DelegatorsParam(delegators);
+
             expect(testParam.delegators).to.not.deep.equal([delegators]);
             expect(testParam.delegators).to.deep.equal(delegators);
         });
     });
 
-    describe("Setter/Getter", () => {
+    describe("Setter/Getter:", () => {
+        it("Sets delegators", () => {
+            const delegators: string[] = ["mark@stengle.in"];
+            const testParam: DelegatorsParam = new DelegatorsParam("te@s.t");
+            testParam.delegators = delegators;
+
+            expect(testParam.delegators).to.exist;
+        });
+
+        it("Sets delegators with no change", () => {
+            const delegators: string[] = ["mark@stengle.in"];
+            const testParam: DelegatorsParam = new DelegatorsParam("te@s.t");
+            testParam.delegators = delegators;
+
+            expect(testParam.delegators).to.be.deep.equal(delegators);
+        });
+
         it("Sets paramValues as well", () => {
-            const delegators: string[] = ["Mark", "Stenglein"];
-            const testParam: DelegatorsParam = new DelegatorsParam("test");
+            const delegators: string[] = ["mark@stengle.in"];
+            const testParam: DelegatorsParam = new DelegatorsParam("te@s.t");
             testParam.delegators = delegators;
+
             expect(testParam.paramValues).to.exist;
         });
 
         it("Sets paramValues correctly", () => {
-            const delegators: string[] = ["Mark", "Stenglein"];
-            const testParam: DelegatorsParam = new DelegatorsParam("test");
+            const delegators: string[] = ["mark@stengle.in", "te@s.t"];
+            const testParam: DelegatorsParam = new DelegatorsParam("diff@ema.il");
             testParam.delegators = delegators;
-            expect(testParam.paramValues).to.be.deep.equal(delegators);
+
+            const expected: string[] = ["\"mailto:mark@stengle.in\"",
+                                        "\"mailto:te@s.t\""];
+            expect(testParam.paramValues).to.be.deep.equal(expected);
+        });
+
+        describe("Rejects invalid delegator params:", () => {
+            it("DQUOTES", () => {
+                const delegators: string[] = ["mark\"@stengle.in"];
+
+                expect(() => {
+                    new DelegatorsParam(delegators);
+                }).to.throw("Delegator must be QSafeChars");
+            });
+        });
+    });
+
+    describe("Generator:", () => {
+        it("Properly Generates output for single delegator", () => {
+            const delegators: string[] = ["mark@stengle.in"];
+            const testParam: DelegatorsParam = new DelegatorsParam(delegators);
+
+            const actual: string = "DELEGATED-FROM=\"mailto:mark@stengle.in\"";
+            expect(testParam.generate()).to.be.equal(actual);
+        });
+
+        it("Properly Generates output for multiple delegators", () => {
+            const delegators: string[] = ["one@one.com", "two@two.com"];
+            const testParam: DelegatorsParam = new DelegatorsParam(delegators);
+
+            const actual: string = "DELEGATED-FROM=\"mailto:one@one.com\"," +
+                "\"mailto:two@two.com\"";
+            expect(testParam.generate()).to.be.equal(actual);
         });
     });
 });