Version two documentation

.npmignore

@@ -31,5 +31,6 @@ tests/
 .eslintrc.js
 .jsdoc.js
 .prettierrc.js
+.github/
 CODE_OF_CONDUCT.md
 .DS_Store

examples/results/client-login-example.json

@@ -1,3 +1,3 @@
 {
-  "token": "7bd9ada3c19b8af1abce977d74bd7950bb3fdbb876a77b33c1"
+  "token": "5de8f916517c531c9c731a3a314fa32a7f894013af187e848b0b"
 }

examples/results/field-data-utility-example.json

@@ -1,7 +1,7 @@
 [
   {
     "name": "yoda",
-    "image": "https://some-server.com/Streaming_SSL/MainDB/332651C476F791617118B74B1F64A731E5C6D6119F3BB4DC552AE5CF19C43E2F?RCType=EmbeddedRCFileProcessor",
+    "image": "https://some-server.com/Streaming_SSL/MainDB/C71488639D896C077F74F3B66EDBD818707AC6C61C283D955F0D21E25CBB2CB2?RCType=EmbeddedRCFileProcessor",
     "object": "",
     "array": "",
     "height": "",

examples/results/field-data-utility-original-example.json

@@ -2,7 +2,7 @@
   {
     "fieldData": {
       "name": "yoda",
-      "image": "https://some-server.com/Streaming_SSL/MainDB/4DA2FB32FD624486C5BE37662EDBAE56B448CC2F9912481EDBB08164AD38E4FF?RCType=EmbeddedRCFileProcessor",
+      "image": "https://some-server.com/Streaming_SSL/MainDB/9C3AF224D2F113F7C93345BAF6C64747BEBA5DEA0493C834B5B2A83ADE10B3B9?RCType=EmbeddedRCFileProcessor",
       "object": "",
       "array": "",
       "height": "",

examples/results/find-records-example.json

@@ -4,7 +4,7 @@
     "layout": "Heroes",
     "table": "Heroes",
     "totalRecordCount": "1977",
-    "foundCount": 135,
+    "foundCount": 136,
     "returnedCount": 1
   },
   "data": [

examples/results/get-record-example.json

@@ -11,7 +11,7 @@
     {
       "fieldData": {
         "name": "Yoda",
-        "image": "https://some-server.com/Streaming_SSL/MainDB/3366F0CD95024C7C6A52B2CA623E295B751EE52118C72CD3DAB690D6F4B2992F?RCType=EmbeddedRCFileProcessor",
+        "image": "https://some-server.com/Streaming_SSL/MainDB/679FE237F406D701A31A51E604DCD36780E4D7CF23A6194166F5BCC32006DE77?RCType=EmbeddedRCFileProcessor",
         "object": "",
         "array": "",
         "height": "",

examples/results/list-records-example.json

@@ -4,14 +4,14 @@
     "layout": "Heroes",
     "table": "Heroes",
     "totalRecordCount": "1977",
-    "foundCount": 35148,
+    "foundCount": 35994,
     "returnedCount": 2
   },
   "data": [
     {
       "fieldData": {
         "name": "George Lucas",
-        "image": "https://some-server.com/Streaming_SSL/MainDB/3D843169A9D86D5BD59B9B67BC69A466199772613B88C7F04F426866429DDA31.png?RCType=EmbeddedRCFileProcessor",
+        "image": "https://some-server.com/Streaming_SSL/MainDB/22447C0F5DD40C304A5A052445CA686B06940B7C9674825ABA2A44F43981D902.png?RCType=EmbeddedRCFileProcessor",
         "object": "",
         "array": "",
         "height": "",

examples/results/record-id-utility-example.json

@@ -1,4 +1,4 @@
 [
-  "751329",
-  "751394"
+  "751398",
+  "751465"
 ]

examples/results/record-id-utility-original-example.json

@@ -2,7 +2,7 @@
   {
     "fieldData": {
       "name": "yoda",
-      "image": "https://some-server.com/Streaming_SSL/MainDB/D6E066BD0912B601DEA2E21D7FFEC768EAACD3949D6C71FD49F8FFEBA0DBC511?RCType=EmbeddedRCFileProcessor",
+      "image": "https://some-server.com/Streaming_SSL/MainDB/8EF2E93CD508D8892C8A771608537BB2B9D20A0546B55F78FDBE4394EF6FFA0C?RCType=EmbeddedRCFileProcessor",
       "object": "",
       "array": "",
       "height": "",

src/models/agent.model.js

@@ -127,7 +127,7 @@ class Agent extends EmbeddedDocument {
 
   preInit({ agent, protocol, connection }) {
     this.connection = Connection.create(connection);
-    if (agent) this._globalize(protocol, agent);
+    if (agent) this.globalize(protocol, agent);
   }
 
   /**
@@ -144,25 +144,28 @@ class Agent extends EmbeddedDocument {
       global.FMS_API_CLIENT.AGENTS &&
       global.FMS_API_CLIENT.AGENTS[this.global]
     ) {
-      this._localize()[`${this.protocol}Agent`].destroy();
+      this.localize()[`${this.protocol}Agent`].destroy();
       delete global.FMS_API_CLIENT.AGENTS[this.global];
     }
   }
 
   /**
-   * @method _globalize
+   * @method globalize
    * @private
    * @memberof Agent
-   * @description _globalize will create the global agent scope if it does not
+   * @description globalize will create the global agent scope if it does not
    * exist. It will set a global Id for retrieval later and create a new http or
    * https module depending on the protocol passed to it.
    * @param  {String} protocol   The protocol to use when creating an Agent.
    * @param  {Object} agent      The name of the script
    * @return {Object}       returns a globalized request agent
    */
 
-  _globalize(protocol, agent) {
+  globalize(protocol, agent) {
     if (!this.global) this.global = uuidv4();
+    /**
+     * @global
+     */
     global.FMS_API_CLIENT.AGENTS[this.global] =
       protocol === 'https'
         ? {
@@ -175,23 +178,23 @@ class Agent extends EmbeddedDocument {
   }
 
   /**
-   * @method _localize
+   * @method localize
    * @private
    * @memberof Agent
-   * @description _localize will check to see if a global agent exists.
+   * @description localize will check to see if a global agent exists.
    * If the agent does not exist this method will call _globalize to add
    * it.
-   * @see _globalize
+   * @see globalize
    * @return {Object} returns a globalized request agent
    */
 
-  _localize() {
+  localize() {
     if (typeof global.FMS_API_CLIENT.AGENTS === 'undefined')
       global.FMS_API_CLIENT.AGENTS = [];
     if (global.FMS_API_CLIENT.AGENTS[this.global]) {
       return global.FMS_API_CLIENT.AGENTS[this.global];
     } else {
-      return this._globalize(this.protocol, this.agent);
+      return this.globalize(this.protocol, this.agent);
     }
   }
 
@@ -201,8 +204,14 @@ class Agent extends EmbeddedDocument {
    * @memberof Agent
    * @description request will merge agent properties with request properties
    * in order to make the request. This method removes httpAgent and httpsAgents through destructoring.
-   * @see _localize
-   * @return {Object} returns the request instance used to make the request.
+   * @see {@link localize}
+   * @see {@link push}
+   * @see {@link handleResponse}
+   * @see {@link handleRequest}
+   * @see {@link handleError}
+   * @param  {Object} data The request
+   * @param  {Object} [parameters] The request parameters. Individualized request parameters.
+   * @return {Object} request The configured axios instance to use for a request.
    */
 
   request(data, parameters = {}) {
@@ -226,16 +235,16 @@ class Agent extends EmbeddedDocument {
         data,
         this.timeout ? { timeout: this.timeout } : {},
         _.isEmpty(this.proxy) ? {} : { proxy: this.proxy },
-        _.isEmpty(this.agent) ? {} : this._localize(),
+        _.isEmpty(this.agent) ? {} : this.localize(),
         parameters.request || {}
       )
     );
   }
 
   /**
-   * @function handleResponse
-   * @public
-   * @memberof Request Service
+   * @method handleResponse
+   * @private
+   * @memberof Agent
    * @description handles request data before it is sent to the resource. This function
    * will eventually be used to cancel the request and return the configuration body.
    * This function will test the url for an http proticol and reject if none exist.
@@ -255,18 +264,10 @@ class Agent extends EmbeddedDocument {
     }
   }
 
-  logout() {
-    return this.connection.end();
-  }
-
-  login() {
-    return this.connection.start();
-  }
-
   /**
-   * @function handleRequest
-   * @public
-   * @memberof Request Service
+   * @method handleRequest
+   * @private
+   * @memberof Agent
    * @description handles request data before it is sent to the resource. This function
    * will eventually be used to cancel the request and return the configuration body.
    * This function will test the url for an http proticol and reject if none exist.
@@ -283,21 +284,64 @@ class Agent extends EmbeddedDocument {
         });
   }
 
+  /**
+   * @method push
+   * @private
+   * @memberof Agent
+   * @description the push method queues requests and begins the request watcher process. This method will also call shift to
+   * ensure a request is being processed.
+   * @param  {Object} agent The agent request configuration.
+   * @param  {Object} agent.request The agent request object.
+   * @param  {Function} agent.resolve The function to call when the request has been completed.
+   * @see  {@link Agent#watch}
+   * @see  {@link Agent#mutate}
+   * @see  {@link Agent#shift}
+   * @return {undefined} This method does not return anything.
+   */
+
   push({ request, resolve }) {
-    this.queue.push({ request: this.sanitize(request), resolve });
+    this.queue.push({
+      request: this.mutate(request, (value, key) =>
+        key.replace(/\./g, '{{dot}}')
+      ),
+      resolve
+    });
     if (this.pending.length < this.concurrency) {
       this.shift();
       this.watch();
     }
   }
 
+  /**
+   * @method shift
+   * @private
+   * @memberof Agent
+   * @description the shift method will send a request if there are less pending requests than the set limit.
+   * @see {@link agent#concurrency}
+   * @return {undefined} This method does not return anything.
+   */
+
   shift() {
     if (this.pending.length < this.concurrency) {
       this.pending.push(this.queue.shift());
     }
   }
 
-  sanitize(request) {
+  /**
+   * @method mutate
+   * @private
+   * @memberof Agent
+   * @description This method is used to modify keys in an object. This method is used by the watch and resolve methods to
+   * allow request data to be written to the datastore.
+   * @see {@link Agent#resolve}
+   * @see {@link Agent#watch}
+   * @see {@link Conversion Utilities#deepMapKeys}
+   * @param  {Object} request The agent request object.
+   * @param  {Function} mutation The function to upon each key in the request.
+   * @return {Object} This mutated request
+   */
+
+  mutate(request, mutation) {
     let {
       transformRequest,
       transformResponse,
@@ -308,7 +352,7 @@ class Agent extends EmbeddedDocument {
 
     let modified = request.url.includes('/containers/')
       ? request
-      : deepMapKeys(value, (value, key) => key.replace(/\./g, '{{dot}}'));
+      : deepMapKeys(value, mutation);
 
     return {
       ...modified,
@@ -319,30 +363,6 @@ class Agent extends EmbeddedDocument {
     };
   }
 
-  unsanitize(request) {
-    return new Promise((resolve, reject) => {
-      let {
-        transformRequest,
-        transformResponse,
-        adapter,
-        validateStatus,
-        ...value
-      } = request;
-
-      let modified = request.url.includes('/containers/')
-        ? request
-        : deepMapKeys(value, (value, key) => key.replace(/{{dot}}/g, '.'));
-
-      resolve({
-        ...modified,
-        transformRequest,
-        transformResponse,
-        adapter,
-        validateStatus
-      });
-    });
-  }
-
   /**
    * @function handleError
    * @public
@@ -375,6 +395,19 @@ class Agent extends EmbeddedDocument {
     }
   }
 
+  /**
+   * @method watch
+   * @private
+   * @memberof Agent
+   * @description This method creates a timer to check on the status of queued and resolved requests
+   * This method will queue and resolve requests based on the number of incoming requests and the availability
+   * of sessions. This method will resolve requests and create sessions based upon the agent's configured concurrency.
+   * token response.
+   * @see  {@link Agent#concurrency}
+   * @see  {@link Connection@available}
+   * @return {Undefined}      A promise rejection containing a code and a message
+   */
+
   watch() {
     const WATCHER = setInterval(() => {
       if (this.queue.length > 0) {
@@ -387,15 +420,7 @@ class Agent extends EmbeddedDocument {
 
       if (this.pending.length > 0) {
         if (this.connection.available()) {
-          let resolved = this.pending.shift();
-          this.unsanitize(resolved.request).then(request =>
-            resolved.resolve(
-              Object.assign(
-                this.connection.authentication(request),
-                _.isEmpty(this.agent) ? {} : this._localize()
-              )
-            )
-          );
+          this.resolve();
         }
         if (
           this.connection.sessions.length <= this.concurrency &&
@@ -406,6 +431,31 @@ class Agent extends EmbeddedDocument {
       }
     }, this.delay);
   }
+
+  /**
+   * @method resolve
+   * @private
+   * @memberof Agent
+   * @description This method resolves requests by sending them to FileMaker for processing. This method will
+   * resolve requests currently in the pending queue. This method will inject the available session token into the request.
+   * @see  {@link Agent#pending}
+   * @see  {@link Connection@authentication}
+   * @return {Undefined}      A promise rejection containing a code and a message
+   */
+
+  resolve() {
+    let pending = this.pending.shift();
+    pending.resolve(
+      Object.assign(
+        this.connection.authentication(
+          this.mutate(pending.request, (value, key) =>
+            key.replace(/{{dot}}/g, '.')
+          )
+        ),
+        _.isEmpty(this.agent) ? {} : this.localize()
+      )
+    );
+  }
 }
 
 module.exports = {