postman-collection - npm Package Compare versions

Comparing version 0.0.6-prealpha.1 to 0.0.6

examples/collection-v2.json

@@ -80,3 +80,3 @@ {
           ],
-          "data": "response body"
+          "body": "response body"
         }
@@ -114,3 +114,3 @@ ],
         ],
-        "data": {
+        "body": {
           "mode": "urlencoded",
@@ -146,3 +146,3 @@ "urlencoded": [
           ],
-          "data": "response body"
+          "body": "response body"
         }
@@ -175,3 +175,3 @@ ],
             "method": "PUT",
-            "data": {
+            "body": {
               "mode": "urlencoded",
@@ -193,3 +193,3 @@ "urlencoded": [
             "url": "http://echo.getpostman.com/post",
-            "data": {
+            "body": {
               "mode": "raw",
@@ -196,0 +196,0 @@ "raw": "blahblah"

examples/digest.json

@@ -34,3 +34,3 @@ {
             "header": "Content-Type: application/json\nAuthorization: Hawk id=\"dh37fgj492je\", ts=\"1448549987\", nonce=\"eOJZCd\", mac=\"O2TFlvAlMvKVSKOzc6XkfU6+5285k5p3m5dAjxumo2k=\"\n",
-            "data": {
+            "body": {
               "mode": "formdata",
@@ -93,3 +93,3 @@ "formdata": [
               ],
-              "data": "response body"
+              "body": "response body"
             }
@@ -134,3 +134,3 @@ ]
             ],
-            "data": {
+            "body": {
               "mode": "formdata",
@@ -137,0 +137,0 @@ "formdata": []

examples/hawk.json

@@ -38,3 +38,3 @@ {
                 ],
-                "data": {
+                "body": {
                     "mode": "formdata",
@@ -41,0 +41,0 @@ "formdata": []

examples/oauth1.json

@@ -49,3 +49,3 @@ {
                 ],
-                "data": {
+                "body": {
                     "mode": "formdata",
@@ -52,0 +52,0 @@ "formdata": []

lib/collection/description.js

@@ -31,2 +31,8 @@ var _ = require('../util').lodash,
 
+/**
+ * This property provides a convenient way to represent the description of a Property.
+ *
+ * @param def {Object|String} Definition of this Description object
+ * @constructor
+ */
 Description = function PostmanPropertyDescription (def) {
@@ -42,4 +48,23 @@ // in case definition object is missing, there is no point moving forward
 
+    /**
+     * The raw content of the description
+     *
+     * @type {String}
+     * @lends Description.prototype
+     */
     this.content = def.content;
+    /**
+     * The mime-type of the description.
+     *
+     * @type {String}
+     * @lends Description.prototype
+     */
     this.type = def.type || DEFAULT_MIMETYPE;
+    /**
+     * A description can have multiple versions associated with it.
+     *
+     * @private
+     * @type {*}
+     * @lends Description.prototype
+     */
     this.version = def.version;
@@ -49,2 +74,8 @@ };
 _.extend(Description.prototype, /** @lends Description.prototype */ {
+
+    /**
+     * Processes the Description with the appropriate formatter as defined by {@link Description.type}
+     *
+     * @returns {String}
+     */
     toString: function () {
@@ -55,2 +86,7 @@ var formatter = Description.format[_.isString(this.type) && this.type.toLowerCase()];
 
+    /**
+     * Creates a JSON representation of the Description (as a plain Javascript object).
+     *
+     * @returns {{content: *, type: *, version: (string|*|string)}}
+     */
     toJSON: function () {
@@ -75,8 +111,13 @@ var version = this.version;
     /**
-     * Stores all the formatters
-     * @private
-     *
-     * @type {Object<function>}
+     * The default and supported description format handlers.
+     * @readOnly
+     * @enum {Function}
      */
     format: {
+        /**
+         * Escapes HTML characters in the description content, and returns the result.
+         *
+         * @param content
+         * @returns {String}
+         */
         'text/plain': function (content) {
@@ -86,2 +127,8 @@ return escapeHtml(content); // do not allow HTML
 
+        /**
+         * Returns HTML string generated after rendering raw markdown.
+         *
+         * @param content
+         * @returns {String}
+         */
         'text/markdown': function (content) {
@@ -91,2 +138,8 @@ return marked(content); // it is sanitised html anyway!
 
+        /**
+         * Removes blacklisted HTML tags from the Description.
+         *
+         * @param content
+         * @returns {String}
+         */
         'text/html': function (content) {
@@ -93,0 +146,0 @@ return sanitizeHtml(content, HTML_DEFAULT_OPTIONS);

lib/collection/event-list.js

@@ -8,2 +8,10 @@ var _ = require('../util').lodash,
 _.inherit((
+    /**
+     * A type of {@link PropertyList}, EventList handles resolving events from parents. If an {@link ItemGroup} contains
+     * a set of events, each {@link Item} in that group will inherit those events from its parent, and so on.
+     * @constructor
+     * @extends {PropertyList}
+     *
+     * This is useful when we need to have a common test across all requests.
+     */
     EventList = function PostmanEventList (parent, populate) {
@@ -56,2 +64,9 @@ // this constructor is intended to inherit and as such the super constructor is required to be executed
 _.extend(EventList, /** @lends EventList */ {
+
+    /**
+     * Checks if the given object is an EventList.
+     *
+     * @param obj
+     * @returns {boolean}
+     */
     isEventList: function (obj) {
@@ -58,0 +73,0 @@ return obj instanceof EventList;

lib/collection/item-group.js

 var _ = require('../util').lodash,
-    uuid = require('node-uuid'),
     Property = require('./property').Property,
@@ -13,3 +12,11 @@ PropertyList = require('./property-list').PropertyList,
     /**
-     * Defines a group of PostmanItems from a definition of items.
+     * An ItemGroup represents a composite list of {@link Item} or ItemGroup. In terms of Postman App, ItemGroup
+     * represents a "Folder". This allows one to group Items into subsets that can have their own meaning. An
+     * ItemGroup also allows one to define a subset of common properties to be applied to each Item within it. For
+     * example, a `test` event defined on an ItemGroup is executed while testing any Item that belongs to that group.
+     * Similarly, ItemGroups can have a common {@RequestAuth} defined so that every {@link Request}, when processed,
+     * requires to be authenticated using the `auth` defined in the group.
+     *
+     * Essentially, {@link Collection} too is a special type of ItemGroup ;-).
+     *
      * @constructor
@@ -27,4 +34,24 @@ * @extends {Property}
             /**
-             * The list of child items or groups within this group.
-             * @type {PropertyList<Item|ItemGroup>}
+             * This is a {@link PropertyList} that holds the list of {@link Item}s or {@link ItemGroup}s belonging to a
+             * {@link Collection} or to an {@link ItemGroup}. Operation on an individual item in this list can be
+             * performed using various functions available to a {@link PropertyList}.
+             *
+             * @type {PropertyList<(Item|ItemGroup)>}
+             *
+             * @example <caption>Fetch empty ItemGroups in a list loaded from a file</caption>
+             * var fs = require('fs'), // needed to read JSON file from disk
+             *     Collection = require('postman-collection').Collection,
+             *     myCollection,
+             *     emptyGroups;
+
+             * // Load a collection to memory from a JSON file on disk (say, sample-collection.json)
+             * myCollection = new Collection(JSON.stringify(fs.readFileSync('sample-collection.json').toString()));
+             *
+             * // Filter items in Collection root that is an empty ItemGroup
+             * emptyGroups = myCollection.items.filter(function (item) {
+             *     return item && item.items && (item.items.count() === 0);
+             * });
+             *
+             * // Log the emptyGroups array to check it's contents
+             * console.log(emptyGroups);
              */
@@ -34,4 +61,27 @@ items: new PropertyList(ItemGroup._createNewGroupOrItem, this, options.item),
             /**
-             * Authentication required for all items in this group.
+             * One can define the default authentication method required for every item that belongs to this list.
+             * Individual {@link Request}s can override this in their own definitions. More on how to define an
+             * authentication method is outlined in the {@link RequestAuth} property.
+             *
              * @type {RequestAuth}
+             *
+             * @example <caption>Define an entire ItemGroup (folder) or Collection to follow Basic Auth</caption>
+             * var fs = require('fs'),
+             *     Collection = require('postman-collection').Collection,
+             *     RequestAuth = require('postman-collection').RequestAuth,
+             *     mycollection;
+             *
+             * // Create a collection having two requests
+             * myCollection = new Collection();
+             * myCollection.items.add([
+             *     { name: 'GET Request', request: 'https://echo.getpostman.com/get?auth=basic' },
+             *     { name: 'PUT Request', request: 'https://echo.getpostman.com/put?auth=basic' }
+             * ]);
+             *
+             * // Add basic auth to the Collection, to be applied on all requests.
+             * myCollection.auth = new RequestAuth({
+             *     type: 'basic',
+             *     username: 'postman',
+             *     password: 'password'
+             * });
              */
@@ -41,18 +91,35 @@ auth: _.createDefined(options, 'auth', RequestAuth),
             /**
-             * List of global events
+             * In this list, one can define the {@link Script}s to be executed when an event is triggered. Events are
+             * triggered before certain actions are taken on a Collection, Request, etc. For example, executing a
+             * request causes the `prerequest` and the `test` events to be triggered.
+             *
              * @type {EventList}
              * @memberOf Collection.prototype
+             *
+             * @example <caption>Executing a common test script for all requests in a collection</caption>
+             * var fs = require('fs'), // needed to read JSON file from disk
+             *     Collection = require('postman-collection').Collection,
+             *     myCollection;
+             *
+             * // Load a collection to memory from a JSON file on disk (say, sample-collection.json)
+             * myCollection = new Collection(JSON.stringify(fs.readFileSync('sample-collection.json').toString()));
+             *
+             * // Add an event listener to the collection that listens to the `test` event.
+             * myCollection.events.add({
+             *     listen: 'test',
+             *     script: {
+             *         exec: 'tests["Status code is 200"] = (responseCode.code === 200)'
+             *     }
+             * });
              */
             events: new EventList(this, options.event)
         });
-
-        // if id is not defined, then we create a new one
-        !this.id && (this.id = uuid.v4());
     }), Property);
 
 _.extend(ItemGroup.prototype, /** @lends ItemGroup.prototype */ {
+    _postman_requiresId: true,
     /**
      * Calls the callback for each item belonging to itself. If any ItemGroups are encountered,
      * they will call the callback on their own Items.
-     * @draft - to decide whether to return recursive items
+     * @private
      *
@@ -59,0 +126,0 @@ * @param {Function} callback

lib/collection/item.js

 var _ = require('../util').lodash,
-    uuid = require('node-uuid'),
     Property = require('./property').Property,
@@ -24,3 +23,3 @@ PropertyList = require('./property-list').PropertyList,
 
-        _.merge(this, {
+        _.merge(this, /** @lends Item.prototype */ {
             /**
@@ -42,8 +41,7 @@ * The request in this item
         });
-
-        // if id is not defined (by virtue of inheriting PostmanProperty), then we create a new one
-        !this.id && (this.id = uuid.v4());
     }), Property);
 
 _.extend(Item.prototype, /** @lends Item.prototype */ {
+    _postman_requiresId: true,
+
     // TODO: Think about this name @shamasis
@@ -50,0 +48,0 @@ processAuth: function () {

lib/collection/property-base.js

@@ -28,3 +28,4 @@ var _ = require('../util').lodash,
         /**
-         * Description of the property
+         * A detailed description of this property. The description can be written in plain text, html or markdown as
+         * mentioned in {@link Description}.format enumeration.
          * @type {Description}
@@ -31,0 +32,0 @@ */

lib/collection/property.js

 var _ = require('../util').lodash,
+    uuid = require('node-uuid'),
     PropertyBase = require('./property-base').PropertyBase,
@@ -16,2 +17,3 @@ Version = require('./version').Version,
      * @constructor
+     * @private
      * @extends {PropertyBase}
@@ -33,9 +35,10 @@ *
             /*jshint -W069 */
-            // @todo: this is not a good way to create id if duplication check is required. decide.
             /**
-             * Store the id of this property.
+             * The `id` of the property is a unique string that identifies this property and can be used to refer to
+             * this property from relevant other places. It is a good practice to define the id or let the system
+             * auto generate a UUID if one is not defined for properties that require an `id`.
+             * @type {String}
              *
              * @note The property can also be present in the `postman_id` meta in case it is not specified in the
              * object. An auto-generated property is used wherever one is not specified
-             * @type {String}
              */
@@ -45,3 +48,6 @@ id: src.id || (this._ ? this._['postman_id'] : undefined),
             /**
-             * Name of the property
+             * A property can have a distinctive and human-readable name. This is to be used to display the name of the
+             * property within Postman, Newman or other runtimes that consume collection. In certain cases, the absence
+             * of name might cause the runtime to use the `id` as a fallback.
+             *
              * @type {String}
@@ -51,4 +57,7 @@ */
             /**
-             * A flag for properties that can be disabled when put within a list
+             * This (optional) flag denotes whether this property is disabled or not. Usually, this is helpful when a
+             * property is part of a {@link PropertyList}. For example, in a PropertyList of {@link Header}s, the ones
+             * that are disabled can be filtered out and not processed.
              * @type {Boolean}
+             * @optional
              */
@@ -58,7 +67,12 @@ disabled: (options && _.has(options, 'disabled')) ? !!options.disabled : undefined,
             /**
-             * If a version exists in an info block, it is set here
-             * @type {*}
+             * The (optional) version of this property, expressed in [semver](http://semver.org/) format.
+             * @type {Version}
+             * @optional
              */
             version: version
         });
+
+        // @todo: this is not a good way to create id if duplication check is required. decide.
+        // If this property is marked to require an ID, we generate one if not found.
+        this._postman_requiresId && !this.id && (this.id = uuid.v4());
     }), PropertyBase);
@@ -65,0 +79,0 @@

lib/collection/request-auth.js

@@ -10,5 +10,6 @@ var _ = require('../util').lodash,
      * @readonly
-     * @enum {string} AuthTypes
+     * @enum {string}
+     * @memberOf RequestAuth
      */
-    authTypes = {
+    authenticationTypes = {
         /**
@@ -164,3 +165,3 @@ * Handler used for the AWS Signature v4 authentication.
 // validate each authentication type and add them to auth
-_.each(authTypes, RequestAuth.addType.bind(RequestAuth));
+_.each(authenticationTypes, RequestAuth.addType.bind(RequestAuth));
 
@@ -167,0 +168,0 @@ module.exports = {

lib/collection/request-auth/awsv4.js

 var _ = require('../../util').lodash,
-    RequestData = require('../request-data').RequestData,
+    RequestBody = require('../request-body').RequestBody,
     signer = require('aws4'),
@@ -41,3 +41,3 @@
                 key: 'Content-Type',
-                value: (mode === RequestData.MODES.formdata) ?
+                value: (mode === RequestBody.MODES.formdata) ?
                     'multipart/form-data' : 'application/x-www-form-urlencoded'
@@ -44,0 +44,0 @@ });

lib/collection/request-auth/oauth1.js

 var _ = require('../../util').lodash,
-    RequestData = require('../request-data').RequestData,
+    RequestBody = require('../request-body').RequestBody,
     oAuth1 = require('node-oauth1'),
@@ -75,3 +75,3 @@
             bodyParams: (request.data &&
-                request.data.mode === RequestData.MODES.urlencoded &&
+                request.data.mode === RequestBody.MODES.urlencoded &&
                 request.data.urlencoded &&
@@ -105,3 +105,3 @@ request.data.urlencoded.count &&
             if (/PUT|POST/.test(request.method) &&
-                    (request.data && request.data.mode === RequestData.MODES.urlencoded)) {
+                    (request.data && request.data.mode === RequestBody.MODES.urlencoded)) {
                 request.data.urlencoded.add([].concat(signatureParams));
@@ -108,0 +108,0 @@ }

lib/collection/request.js

@@ -6,3 +6,3 @@ var _ = require('../util').lodash,
     Header = require('./header').Header,
-    RequestData = require('./request-data').RequestData,
+    RequestBody = require('./request-body').RequestBody,
     RequestAuth = require('./request-auth').RequestAuth,
@@ -46,5 +46,5 @@
             /**
-             * @type {RequestData|undefined}
+             * @type {RequestBody|undefined}
              */
-            data: _.createDefined(options, 'data', RequestData),
+            body: _.createDefined(options, 'body', RequestBody),
             /**
@@ -57,3 +57,3 @@ * @type {RequestAuth}
 
-_.extend(Request.prototype, /** @lends ItemGroup.prototype */ {
+_.extend(Request.prototype, /** @lends Request.prototype */ {
 
@@ -167,3 +167,3 @@ /**
         var headers,
-            data,
+            body,
             auth;
@@ -178,3 +178,3 @@
         auth = (this.auth && this.auth.type) ? this.auth.toJSON() : undefined;
-        data = this.data ? this.data.toJSON() : undefined;
+        body = this.body ? this.body.toJSON() : undefined;
         return {
@@ -184,3 +184,3 @@ url: this.url.getRaw(),
             header: headers,
-            data: data,
+            body: body,
             auth: auth
@@ -187,0 +187,0 @@ };

lib/collection/response.js

@@ -54,3 +54,3 @@ var _ = require('../util').lodash,
              */
-            data: options.data,
+            body: options.body,
 
@@ -79,3 +79,3 @@ /**
             }) : undefined,
-            data: this.data,
+            body: this.body,
             cookie: PropertyList.isPropertyList(this.cookies) ? this.cookies.map(function (cookie) {
@@ -82,0 +82,0 @@ return cookie.toJSON();

lib/collection/url.js

@@ -261,3 +261,3 @@ var _ = require('../util').lodash,
 
-_.extend(Url, {
+_.extend(Url, /** @lends Url */ {
     /**
@@ -264,0 +264,0 @@ * Parses a string to a PostmanUrl, decomposing the URL into it's constitutent parts, such as

lib/collection/variable-list.js

@@ -7,2 +7,3 @@ var _ = require('../util').lodash,
      * Maintain a list of types that are native
+     * @private
      * @enum {String}
@@ -9,0 +10,0 @@ */

lib/index.js

@@ -16,3 +16,3 @@ module.exports = {
     RequestAuth: require('./collection/request-auth').RequestAuth,
-    RequestData: require('./collection/request-data').RequestData,
+    RequestBody: require('./collection/request-body').RequestBody,
     Response: require('./collection/response').Response,
@@ -19,0 +19,0 @@ Script: require('./collection/script').Script,

package.json

@@ -5,3 +5,3 @@ {
   "author": "Postman Labs <[e-mail]>",
-  "version": "0.0.6-prealpha.1",
+  "version": "0.0.6",
   "keywords": [
@@ -8,0 +8,0 @@ "postman"

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

166988

increased by4.56%

Lines of code

3781

increased by4.05%

No dependency changes