@readme/oas-to-har 16.1.0 → 17.0.2

package/CHANGELOG.md

@@ -1,3 +1,35 @@
+## <small>17.0.2 (2022-04-25)</small>
+
+* test: adding some clearer test coverage for raw string payloads ([a47ebc1](https://github.com/readmeio/oas-to-har/commit/a47ebc1))
+* feat: adding support for RAW_BODY payloads when not on JSON-like content types (#81) ([ca2d395](https://github.com/readmeio/oas-to-har/commit/ca2d395)), closes [#81](https://github.com/readmeio/oas-to-har/issues/81)
+
+
+
+## <small>17.0.1 (2022-04-22)</small>
+
+* fix: issue where a lowercase `Accept` header may be duplicated (#80) ([cb9e1b4](https://github.com/readmeio/oas-to-har/commit/cb9e1b4)), closes [#80](https://github.com/readmeio/oas-to-har/issues/80)
+
+
+
+## 17.0.0 (2022-04-22)
+
+> **BREAKING RELEASE**
+>
+> Node 12 is no longer supported.
+
+* chore: adding some more exclusions into the npmignore list ([25b3121](https://github.com/readmeio/oas-to-har/commit/25b3121))
+* chore(deps-dev): bump @readme/oas-examples from 4.5.0 to 5.0.0 (#75) ([845535b](https://github.com/readmeio/oas-to-har/commit/845535b)), closes [#75](https://github.com/readmeio/oas-to-har/issues/75)
+* chore(deps-dev): bump eslint from 8.11.0 to 8.12.0 (#73) ([c26d37c](https://github.com/readmeio/oas-to-har/commit/c26d37c)), closes [#73](https://github.com/readmeio/oas-to-har/issues/73)
+* chore(deps-dev): bump prettier from 2.6.0 to 2.6.1 (#72) ([24613fc](https://github.com/readmeio/oas-to-har/commit/24613fc)), closes [#72](https://github.com/readmeio/oas-to-har/issues/72)
+* chore(deps): bump actions/checkout from 2.4.0 to 3 (#71) ([38c66a7](https://github.com/readmeio/oas-to-har/commit/38c66a7)), closes [#71](https://github.com/readmeio/oas-to-har/issues/71)
+* chore(deps): bump oas from 18.0.6 to 18.1.0 (#74) ([93c2bc4](https://github.com/readmeio/oas-to-har/commit/93c2bc4)), closes [#74](https://github.com/readmeio/oas-to-har/issues/74)
+* fix: code cleanup (#79) ([245dcbb](https://github.com/readmeio/oas-to-har/commit/245dcbb)), closes [#79](https://github.com/readmeio/oas-to-har/issues/79)
+* fix: support for allowReserved (#76) ([f609297](https://github.com/readmeio/oas-to-har/commit/f609297)), closes [#76](https://github.com/readmeio/oas-to-har/issues/76)
+* fix: support for multi-level deepObjects (#77) ([b287f68](https://github.com/readmeio/oas-to-har/commit/b287f68)), closes [#77](https://github.com/readmeio/oas-to-har/issues/77)
+* feat: browser testing! (#78) ([5ebe4d4](https://github.com/readmeio/oas-to-har/commit/5ebe4d4)), closes [#78](https://github.com/readmeio/oas-to-har/issues/78)
+
+
+
 ## 16.1.0 (2022-03-23)
 
 * chore: removing some docs from the repo as they're in our .github/ repo now ([f3d81c3](https://github.com/readmeio/oas-to-har/commit/f3d81c3))

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright © 2021 ReadMe
+Copyright © 2022 ReadMe
 
 Permission to use, copy, modify, and/or distribute this software for any purpose
 with or without fee is hereby granted, provided that the above copyright notice

package/README.md

@@ -15,14 +15,37 @@ npm install --save @readme/oas-to-har
 ## Usage
 
 ```js
-const Oas = require('oas');
+const Oas = require('oas').default;
 const oasToHar = require('@readme/oas-to-har');
 
-const spec = new Oas('petstore.json');
-console.log(oasToHar(spec, { path: '/pets', method: 'post'}));
+const petstore = require('./petstore.json');
+
+const spec = new Oas(petstore);
+console.log(oasToHar(spec, spec.operation('/pets', 'post')));
+```
+
+```json
+{
+  log: {
+    entries: [
+      {
+        request: {
+          cookies: [],
+          headers: [],
+          headersSize: 0,
+          queryString: [],
+          bodySize: 0,
+          method: 'POST',
+          url: 'http://petstore.swagger.io/v2/pets',
+          httpVersion: 'HTTP/1.1'
+        }
+      }
+    ]
+  }
+}
 ```
 
-### `oasToHar(har, operationSchema, values, auth, opts) => Object`
+### `oasToHar(oas, operationSchema, values, auth, opts) => Object`
 
 - `oas` *{Oas}*: Instance of our [oas/tooling](https://npm.im/oas) class.
 - `operationSchema` *{Object\|Operation}*: Can either be an object with `path` and `method` properties (that exist in the supplied OAS), or an instance of our `Operation` class from [oas/tooling](https://npm.im/oas) - accessed through `new Oas(spec).operation(path, method)`.
@@ -36,10 +59,3 @@ console.log(oasToHar(spec, { path: '/pets', method: 'post'}));
   - `server` — If the supplied OAS has multiple severs or server variables you can use this to set which server and variables to use. Shape of it should be: `{ selected: Integer, variables: { ...key-values }}`. `selected` should coorespond to index of the `servers` array in your OAS.
 - `auth` *{Object}*: Authentication information for the request.
 - `opts.proxyUrl` *{Boolean}*: Boolean to toggle if composed HAR objects should have their `url` be sent through our CORS-friendly proxy. Defaults to `false`.
-
-## Credits
-[Jon Ursenbach](https://github.com/erunion)
-
-## License
-
-ISC

package/karma.conf.js

@@ -0,0 +1,14 @@
+const { karmaConfig } = require('@jsdevtools/karma-config');
+const { host } = require('@jsdevtools/host-environment');
+
+module.exports = karmaConfig({
+  sourceDir: '.',
+  fixtures: ['test/__datasets__/*.json'],
+  browsers: {
+    chrome: true,
+    firefox: true,
+    safari: host.os.mac,
+    edge: false,
+    ie: false,
+  },
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@readme/oas-to-har",
   "description": "Utility to transform an OAS operation into a HAR representation",
-  "version": "16.1.0",
+  "version": "17.0.2",
   "main": "src/index.js",
   "author": "Jon Ursenbach <jon@ursenba.ch>",
   "license": "ISC",
@@ -10,34 +10,39 @@
     "url": "git://github.com/readmeio/oas-to-har.git"
   },
   "engines": {
-    "node": "^12 || ^14 || ^16"
+    "node": ">=14"
   },
   "scripts": {
     "lint": "eslint .",
-    "lint:docs": "alex . .github/",
     "prepare": "husky install",
-    "pretest": "npm run lint && npm run lint:docs",
+    "pretest": "npm run lint",
     "prettier": "prettier --list-different --write \"./**/**.{js}\"",
     "release": "npx conventional-changelog-cli -i CHANGELOG.md -s && git add CHANGELOG.md",
-    "test": "jest --coverage"
+    "test:browser": "karma start --single-run",
+    "test:browser:chrome": "karma start --browsers=Chrome --single-run=false",
+    "test:browser:debug": "karma start --single-run=false",
+    "test": "nyc mocha"
   },
   "dependencies": {
     "@readme/oas-extensions": "^14.2.0",
     "oas": "^18.0.6",
     "parse-data-url": "^4.0.1",
+    "qs": "^6.10.3",
     "remove-undefined-objects": "^1.1.0"
   },
   "devDependencies": {
     "@commitlint/cli": "^16.2.3",
     "@commitlint/config-conventional": "^16.0.0",
+    "@jsdevtools/host-environment": "^2.1.2",
+    "@jsdevtools/karma-config": "^3.1.7",
     "@readme/eslint-config": "^8.5.1",
-    "@readme/oas-examples": "^4.5.0",
-    "alex": "^10.0.0",
-    "datauri": "^4.1.0",
+    "@readme/oas-examples": "^5.1.1",
+    "chai": "^4.3.6",
     "eslint": "^8.11.0",
+    "har-validator": "^5.1.5",
     "husky": "^7.0.4",
-    "jest": "^27.4.7",
-    "jest-expect-har": "^3.0.1",
+    "mocha": "^9.2.2",
+    "nyc": "^15.1.0",
     "prettier": "^2.6.0"
   },
   "prettier": "@readme/eslint-config/prettier",

package/src/index.js

@@ -11,8 +11,8 @@ const { jsonSchemaTypes } = utils;
 function formatter(values, param, type, onlyIfExists) {
   if (param.style) {
     const value = values[type][param.name];
-    // Note: Technically we could send everything through the format style and choose the proper default for each
-    //  `in` type (e.g. query defaults to form).
+    // Note: Technically we could send everything through the format style and choose the proper
+    // default for each `in` type (e.g. query defaults to form).
     return formatStyle(value, param);
   }
 
@@ -26,18 +26,20 @@ function formatter(values, param, type, onlyIfExists) {
   } else if (param.required && param.schema && param.schema.default) {
     value = param.schema.default;
   } else if (type === 'path') {
-    // If we don't have any values for the path parameter, just use the name of the parameter as the value so we don't
-    // try try to build a URL to something like `https://example.com/undefined`.
+    // If we don't have any values for the path parameter, just use the name of the parameter as the
+    // value so we don't try try to build a URL to something like `https://example.com/undefined`.
     return param.name;
   }
 
-  // Handle file uploads. Specifically arrays of file uploads which need to be formatted very specifically.
+  // Handle file uploads. Specifically arrays of file uploads which need to be formatted very
+  // specifically.
   if (param.schema && param.schema.type === 'array' && param.schema.items && param.schema.items.format === 'binary') {
     return JSON.stringify(value);
   }
 
   if (value !== undefined) {
-    // Query params should always be formatted, even if they don't have a `style` serialization configured.
+    // Query params should always be formatted, even if they don't have a `style` serialization
+    // configured.
     if (type === 'query') {
       return formatStyle(value, param);
     }
@@ -77,7 +79,8 @@ function multipartBodyToFormatterParams(multipartBody, oasMediaTypeObject) {
       .filter(Boolean);
   }
 
-  // Pretty sure that we'll never have anything but an object for multipart bodies, so returning empty array if we get anything else.
+  // Pretty sure that we'll never have anything but an object for multipart bodies, so returning
+  // empty array if we get anything else.
   return [];
 }
 
@@ -118,12 +121,14 @@ function appendHarValue(harParam, name, value, addtlData = {}) {
   if (typeof value === 'undefined') return;
 
   if (Array.isArray(value)) {
-    // If the formatter gives us an array, we're expected to add each array value as a new parameter item with the same parameter name
+    // If the formatter gives us an array, we're expected to add each array value as a new
+    // parameter item with the same parameter name
     value.forEach(singleValue => {
       appendHarValue(harParam, name, singleValue);
     });
   } else if (typeof value === 'object' && value !== null) {
-    // If the formatter gives us an object, we're expected to add each property value as a new parameter item, each with the name of the property
+    // If the formatter gives us an object, we're expected to add each property value as a new
+    // parameter item, each with the name of the property
     Object.keys(value).forEach(key => {
       appendHarValue(harParam, key, value[key]);
     });
@@ -143,8 +148,8 @@ module.exports = (
   values = {},
   auth = {},
   opts = {
-    // If true, the operation URL will be rewritten and prefixed with https://try.readme.io/ in order to funnel requests
-    // through our CORS-friendly proxy.
+    // If true, the operation URL will be rewritten and prefixed with https://try.readme.io/ in
+    // order to funnel requests through our CORS-friendly proxy.
     proxyUrl: false,
   }
 ) => {
@@ -196,7 +201,8 @@ module.exports = (
     // Find the path parameter or set a default value if it does not exist
     const parameter = parameters.find(param => param.name === key) || { name: key };
 
-    // The library that handles our style processing already encodes uri elements. For everything else we need to handle it here.
+    // The library that handles our style processing already encodes uri elements. For everything
+    // else we need to handle it here.
     if (!parameter.style) {
       return encodeURIComponent(formatter(formData, parameter, 'path'));
     }
@@ -226,8 +232,9 @@ module.exports = (
     Object.keys(operation.schema.responses).some(response => {
       if (!operation.schema.responses[response].content) return false;
 
-      // if there is an Accept header specified in the form, we'll use that instead.
-      if (formData.header.Accept) return true;
+      // If there's no `Accept` header present we should add one so their eventual code snippet
+      // follows best practices.
+      if (Object.keys(formData.header).find(h => h.toLowerCase() === 'accept')) return true;
 
       har.headers.push({
         name: 'Accept',
@@ -272,11 +279,14 @@ module.exports = (
   }
 
   // Do we have an `Accept` header set up in the form, but it hasn't been added yet?
-  if (formData.header && formData.header.Accept && har.headers.find(hdr => hdr.name === 'Accept') === undefined) {
-    har.headers.push({
-      name: 'Accept',
-      value: String(formData.header.Accept),
-    });
+  if (formData.header) {
+    const acceptHeader = Object.keys(formData.header).find(h => h.toLowerCase() === 'accept');
+    if (acceptHeader && !har.headers.find(hdr => hdr.name.toLowerCase() === 'accept')) {
+      har.headers.push({
+        name: 'Accept',
+        value: String(formData.header[acceptHeader]),
+      });
+    }
   }
 
   let requestBody = false;
@@ -316,8 +326,9 @@ module.exports = (
             har.postData.mimeType = 'multipart/form-data';
             har.postData.params = [];
 
-            // Discover all `{ type: string, format: binary }` properties the schema. If there are any, then that means
-            // that we're dealing with a `multipart/form-data` request and need to treat the payload as `postData.params`.
+            // Discover all `{ type: string, format: binary }` properties the schema. If there are
+            // any, then that means that we're dealing with a `multipart/form-data` request and
+            // need to treat the payload as `postData.params`.
             const binaryTypes = Object.keys(requestBody.schema.properties).filter(
               key => requestBody.schema.properties[key].format === 'binary'
             );
@@ -333,9 +344,10 @@ module.exports = (
 
                 const value = formatter(formData, param, 'body', true);
 
-                // If we're dealing with a binary type, and the value is a valid data URL we should parse out any
-                // available filename and content type to send along with the parameter to interpreters like `fetch-har`
-                // can make sense of it and send a usable payload.
+                // If we're dealing with a binary type, and the value is a valid data URL we should
+                // parse out any available filename and content type to send along with the
+                // parameter to interpreters like `fetch-har` can make sense of it and send a usable
+                // payload.
                 const addtlData = {};
 
                 if (binaryTypes.includes(name)) {
@@ -355,17 +367,21 @@ module.exports = (
             har.postData.mimeType = contentType;
 
             // Handle arbitrary JSON input via a string.
-            // In OAS you usually find this in an application/json content type.
-            //   with a schema type=string, format=json.
-            // In the UI this is represented by an arbitrary text input
-            // This ensures we remove any newlines or tabs and use a clean json block in the example
+            //
+            // In OAS you usually find this in an `application/json` content type with a schema
+            // `type=string, format=json`. In the UI this is represented by an arbitrary text input.
+            //
+            // This ensures we remove any newlines or tabs and use a clean JSON block in the
+            // example.
             if (requestBody.schema.type === 'string') {
               har.postData.text = JSON.stringify(JSON.parse(cleanBody));
             } else {
-              // Handle formatted JSON objects that have properties that accept arbitrary JSON
-              // Find all `{ type: string, format: json }` properties in the schema because we need to manually JSON.parse
-              // them before submit, otherwise they'll be escaped instead of actual objects.
-              // We also only want values that the user has entered, so we drop any undefined cleanBody keys
+              // Handle formatted JSON objects that have properties that accept arbitrary JSON.
+              //
+              // Find all `{ type: string, format: json }` properties in the schema because we need
+              // to manually `JSON.parse` them before submit, otherwise they'll be escaped instead
+              // of actual objects. We also only want values that the user has entered, so we drop
+              // any `undefined` `cleanBody` keys
               const jsonTypes = Object.keys(requestBody.schema.properties).filter(
                 key => requestBody.schema.properties[key].format === 'json' && cleanBody[key] !== undefined
               );
@@ -380,7 +396,8 @@ module.exports = (
                     }
                   });
 
-                  // `RAW_BODY` is a ReadMe-specific thing where we'll interpret its contents as raw JSON.
+                  // `RAW_BODY` is a ReadMe-specific thing where we'll interpret the entire payload
+                  // as a raw string. https://docs.readme.com/docs/raw-body-content
                   if (typeof cleanBody.RAW_BODY !== 'undefined') {
                     cleanBody = cleanBody.RAW_BODY;
                   }
@@ -395,16 +412,23 @@ module.exports = (
             }
           }
         } catch (e) {
-          // you should log this error if you're debugging why data is showing up in text, when it  should show up in params
-          // console.log('catching ', e);
-          // If anything above fails for whatever reason, assume that whatever we had is invalid JSON and just treat it
-          // as raw text.
+          // If anything above fails for whatever reason, assume that whatever we had is invalid
+          // JSON and just treat it as raw text.
           har.postData.text = stringify(formData.body);
         }
       } else {
         har.postData.mimeType = contentType;
         if (isPrimitive(formData.body)) {
           har.postData.text = formData.body;
+        } else if (
+          typeof formData.body === 'object' &&
+          formData.body !== null &&
+          !Array.isArray(formData.body) &&
+          typeof formData.body.RAW_BODY !== 'undefined'
+        ) {
+          // `RAW_BODY` is a ReadMe-specific thing where we'll interpret the entire payload as a
+          // raw string. https://docs.readme.com/docs/raw-body-content
+          har.postData.text = formData.body.RAW_BODY;
         } else {
           har.postData.text = stringify(formData.body);
         }
@@ -412,8 +436,9 @@ module.exports = (
     }
   }
 
-  // Add a `Content-Type` header if there are any body values setup above or if there is a schema defined, but only do
-  // so if we don't already have a `Content-Type` present as it's impossible for a request to have multiple.
+  // Add a `Content-Type` header if there are any body values setup above or if there is a schema
+  // defined, but only do so if we don't already have a `Content-Type` present as it's impossible
+  // for a request to have multiple.
   if ((har.postData.text || (requestBody && Object.keys(requestBody.schema).length)) && !hasContentType) {
     har.headers.push({
       name: 'Content-Type',

package/src/lib/style-formatting/index.js

@@ -1,6 +1,7 @@
+const qs = require('qs');
 const stylize = require('./style-serializer');
 
-// Certain styles don't support empty values, This function tracks that list
+// Certain styles don't support empty values.
 function shouldNotStyleEmptyValues(parameter) {
   return ['simple', 'spaceDelimited', 'pipeDelimited', 'deepObject'].includes(parameter.style);
 }
@@ -9,9 +10,12 @@ function shouldNotStyleReservedHeader(parameter) {
   return ['accept', 'authorization', 'content-type'].includes(parameter.name.toLowerCase());
 }
 
-// Note: This isn't necessarily part of the spec. Behavior for the value 'undefined' is, well, undefined.
-//   This code makes our system look better. If we wanted to be more accurate, we might want to remove this,
-//   restore the un-fixed behavior for undefined and have our UI pass in empty string instead of undefined.
+/**
+ * Note: This isn't necessarily part of the spec. Behavior for the value 'undefined' is, well,
+ * undefined. This code makes our system look better. If we wanted to be more accurate, we might
+ * want to remove this, restore the un-fixed behavior for undefined and have our UI pass in empty
+ * string instead of undefined.
+ */
 function removeUndefinedForPath(value) {
   let finalValue = value;
 
@@ -41,35 +45,43 @@ function stylizeValue(value, parameter) {
 
   // Some styles don't work with empty values. We catch those there
   if (shouldNotStyleEmptyValues(parameter) && (typeof finalValue === 'undefined' || finalValue === '')) {
-    // Paths need return an unstyled empty string instead of undefined so it's ignored in the final path string
+    // Paths need return an unstyled empty string instead of undefined so it's ignored in the final
+    // path string.
     if (parameter.in === 'path') {
       return '';
     }
-    // Everything but path should return undefined when unstyled so it's ignored in the final parameter array
+
+    // Everything but path should return undefined when unstyled so it's ignored in the final
+    // parameter array.
     return undefined;
   }
 
-  // Every style that adds their style to empty values should use emptystring for path parameters instead of undefined to avoid the string 'undefined'
+  // Every style that adds their style to empty values should use emptystring for path parameters
+  // instead of undefined to avoid the string `undefined`.
   if (parameter.in === 'path') {
     finalValue = removeUndefinedForPath(finalValue);
   }
 
-  // Eventhough `Accept`, `Authorization`, and `Content-Type` headers can be defined as parameters, they should be
-  // completely ignored when it comes to serialization.
-  //
-  //  > If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition
-  //  > SHALL be ignored.
-  //
-  // https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#fixed-fields-10
+  /**
+   * Eventhough `Accept`, `Authorization`, and `Content-Type` headers can be defined as parameters,
+   * they should be completely ignored when it comes to serialization.
+   *
+   *  > If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the
+   *  > parameter definition SHALL be ignored.
+   *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#fixed-fields-10}
+   */
   if (parameter.in === 'header' && shouldNotStyleReservedHeader(parameter)) {
     return value;
   }
 
-  // All parameter types have a default `style` format so if they don't have one prescribed we should still conform to
-  // what the spec defines.
-  //
-  // https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-parameterstyle
-  // https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#user-content-parameterstyle
+  /**
+   * All parameter types have a default `style` format so if they don't have one prescribed we
+   * should still conform to what the spec defines.
+   *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-parameterstyle}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#user-content-parameterstyle}
+   */
   let style = parameter.style;
   if (!style) {
     if (parameter.in === 'query') {
@@ -85,10 +97,12 @@ function stylizeValue(value, parameter) {
 
   let explode = parameter.explode;
   if (explode === undefined && style === 'form') {
-    // Per the spec if no `explode` is present but `style` is `form` then `explode` should default to `true`.
-    //
-    // https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-parameterexplode
-    // https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#user-content-parameterexplode
+    /**
+     * Per the spec if no `explode` is present but `style` is `form` then `explode` should default to `true`.
+     *
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-parameterexplode}
+     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#user-content-parameterexplode}
+     */
     explode = true;
   }
 
@@ -98,15 +112,49 @@ function stylizeValue(value, parameter) {
     key: parameter.name,
     style,
     explode,
-    /*
-      TODO: this parameter is optional to stylize. It defaults to false, and can accept falsy, truthy, or "unsafe".
-      I do not know if it is correct for query to use this. See style-serializer for more info
-    */
+    /**
+     * @todo this parameter is optional to stylize. It defaults to false, and can accept falsy, truthy, or "unsafe".
+     *  I do not know if it is correct for query to use this. See style-serializer for more info
+     */
     escape: true,
+    ...(parameter.in === 'query' ? { isAllowedReserved: parameter.allowReserved || false } : {}),
   });
 }
 
-// Explode is handled on its own, because style-serializer doesn't return what we expect for proper HAR output
+function handleDeepObject(value, parameter) {
+  return qs
+    .stringify(value, {
+      // eslint-disable-next-line consistent-return
+      encoder(str, defaultEncoder, charset, type) {
+        if (type === 'key') {
+          // `str` will be here as `dog[treats][0]` but because the `qs` library doesn't have any
+          // awareness of our OpenAPI parameters we need to rewrite it to slap the `parameter.name`
+          // to the top, like `pets[dog][treats][0]`.
+          const prefixedKey = str
+            .split(/[[\]]/g)
+            .filter(Boolean)
+            .map(k => `[${k}]`)
+            .join('');
+
+          return `${parameter.name}${prefixedKey}`;
+        } else if (type === 'value') {
+          return stylizeValue(str, parameter);
+        }
+      },
+    })
+    .split('&')
+    .map(item => {
+      const split = item.split('=');
+      return {
+        label: split[0],
+        // `qs` will coerce null values into being `undefined` string but we want to preserve them.
+        value: split[1] === 'undefined' ? null : split[1],
+      };
+    });
+}
+
+// Explode is handled on its own, because style-serializer doesn't return what we expect for proper
+// HAR output.
 function handleExplode(value, parameter) {
   if (Array.isArray(value)) {
     return value.map(val => {
@@ -118,12 +166,13 @@ function handleExplode(value, parameter) {
     const newObj = {};
 
     Object.keys(value).forEach(key => {
-      const stylizedValue = stylizeValue(value[key], parameter);
-
       if (parameter.style === 'deepObject') {
-        newObj[`${parameter.name}[${key}]`] = stylizedValue;
+        const deepObjs = handleDeepObject(value, parameter);
+        deepObjs.forEach(obj => {
+          newObj[obj.label] = obj.value;
+        });
       } else {
-        newObj[key] = stylizedValue;
+        newObj[key] = stylizeValue(value[key], parameter);
       }
     });
 
@@ -148,10 +197,15 @@ module.exports = function formatStyle(value, parameter) {
     return undefined;
   }
 
-  // This custom explode logic allows us to bubble up arrays and objects to be handled differently by our HAR transformer
-  //  We need this because the stylizeValue function assumes we're building strings, not richer data types
-  // The first part of this conditional checks if explode is enabled. Explode is disabled for everything by default except for forms.
-  // The second part of this conditional bypasses the custom explode logic for headers, because they work differently, and stylizeValue is accurate
+  // This custom explode logic allows us to bubble up arrays and objects to be handled differently
+  // by our HAR transformer. We need this because the `stylizeValue` function assumes we're building
+  // strings, not richer data types.
+  //
+  // The first part of this conditional checks if `explode` is enabled. Explode is disabled for
+  // everything by default except for forms.
+  //
+  // The second part of this conditional bypasses the custom explode logic for headers, because they
+  // work differently, and `stylizeValue` is accurate.
   if (shouldExplode(parameter)) {
     return handleExplode(value, parameter);
   }

package/src/lib/style-formatting/style-serializer.js

@@ -16,8 +16,8 @@ function isURIEncoded(value) {
   try {
     return decodeURIComponent(value) !== value;
   } catch (err) {
-    // `decodeURIComponent` will throw an exception if a string that has an un-encoded percent sign in it (like 20%),
-    // so if it's throwing we can just assume that the value hasn't been encoded.
+    // `decodeURIComponent` will throw an exception if a string that has an un-encoded percent sign
+    //  in it (like 20%), o if it's throwing we can just assume that the value hasn't been encoded.
     return false;
   }
 }
@@ -36,7 +36,7 @@ module.exports = function stylize(config) {
 
 module.exports.encodeDisallowedCharacters = function encodeDisallowedCharacters(
   str,
-  { escape, returnIfEncoded = false } = {}, // eslint-disable-line default-param-last
+  { escape, returnIfEncoded = false, isAllowedReserved } = {}, // eslint-disable-line default-param-last
   parse
 ) {
   if (typeof str === 'number') {
@@ -61,17 +61,16 @@ module.exports.encodeDisallowedCharacters = function encodeDisallowedCharacters(
     return JSON.parse(str);
   }
 
-  // In ES6 you can do this quite easily by using the new ... spread operator.
-  // This causes the string iterator (another new ES6 feature) to be used internally,
-  // and because that iterator is designed to deal with
-  // code points rather than UCS-2/UTF-16 code units.
+  // In ES6 you can do this quite easily by using the new ... spread operator. This causes the
+  // string iterator (another new ES6 feature) to be used internally, and because that iterator is
+  // designed to deal with code points rather than UCS-2/UTF-16 code units.
   return [...str]
     .map(char => {
       if (isRfc3986Unreserved(char)) {
         return char;
       }
 
-      if (isRfc3986Reserved(char) && escape === 'unsafe') {
+      if (isRfc3986Reserved(char) && (escape === 'unsafe' || isAllowedReserved)) {
         return char;
       }
 
@@ -86,162 +85,255 @@ module.exports.encodeDisallowedCharacters = function encodeDisallowedCharacters(
     .join('');
 };
 
-function encodeArray({ location, key, value, style, explode, escape }) {
+/**
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#style-examples}
+ */
+function encodeArray({ location, key, value, style, explode, escape, isAllowedReserved = false }) {
   const valueEncoder = str =>
     module.exports.encodeDisallowedCharacters(str, {
       escape,
       returnIfEncoded: location === 'query',
+      isAllowedReserved,
     });
 
-  if (style === 'simple') {
-    return value.map(val => valueEncoder(val)).join(',');
-  }
-
-  if (style === 'label') {
-    return `.${value.map(val => valueEncoder(val)).join('.')}`;
-  }
-
-  if (style === 'matrix') {
-    return value
-      .map(val => valueEncoder(val))
-      .reduce((prev, curr) => {
-        if (!prev || explode) {
-          return `${prev || ''};${key}=${curr}`;
-        }
-        return `${prev},${curr}`;
-      }, '');
-  }
-
-  if (style === 'form') {
-    const after = explode ? `&${key}=` : ',';
-    return value.map(val => valueEncoder(val)).join(after);
-  }
-
-  if (style === 'spaceDelimited') {
-    const after = explode ? `${key}=` : '';
-    return value.map(val => valueEncoder(val)).join(` ${after}`);
+  switch (style) {
+    /**
+     * @example <caption>`style: simple`</caption>
+     * `["blue","black","brown"]` → `blue,black,brown`
+     */
+    case 'simple':
+      return value.map(val => valueEncoder(val)).join(',');
+
+    /**
+     * @example <caption>`style: label`</caption>
+     * `["blue","black","brown"]` → `.blue.black.brown`
+     */
+    case 'label':
+      return `.${value.map(val => valueEncoder(val)).join('.')}`;
+
+    /**
+     * @example <caption>`style: matrix` + `explode: true`</caption>
+     * `["blue","black","brown"]` → `;color=blue;color=black;color=brown`
+     *
+     * @example <caption>`style: matrix` + `explode: false` (the default behavior)</caption>
+     * `["blue","black","brown"]` → `;color=blue,black,brown	`
+     */
+    case 'matrix':
+      return value
+        .map(val => valueEncoder(val))
+        .reduce((prev, curr) => {
+          if (!prev || explode) {
+            return `${prev || ''};${key}=${curr}`;
+          }
+          return `${prev},${curr}`;
+        }, '');
+
+    /**
+     * @example <caption>`style: form` + `explode: true`</caption>
+     * `["blue","black","brown"]` → `color=blue&color=black&color=brown`
+     *
+     * @example <caption>`style: form` + `explode: false` (the default behavior)</caption>
+     * `["blue","black","brown"]` → `ccolor=blue,black,brown`
+     */
+    case 'form':
+      return value.map(val => valueEncoder(val)).join(explode ? `&${key}=` : ',');
+
+    /**
+     * @example <caption>`style: spaceDelimited`</caption>
+     * `["blue","black","brown"]` → `blue%20black%20brown`
+     */
+    case 'spaceDelimited':
+      return value.map(val => valueEncoder(val)).join(` ${explode ? `${key}=` : ''}`);
+
+    /**
+     * @example <caption>`style: pipeDelimited`</caption>
+     * `["blue","black","brown"]` → `blue|black|brown`
+     */
+    case 'pipeDelimited':
+      return value.map(val => valueEncoder(val)).join(`|${explode ? `${key}=` : ''}`);
+
+    default:
+      return undefined;
   }
-
-  if (style === 'pipeDelimited') {
-    const after = explode ? `${key}=` : '';
-    return value.map(val => valueEncoder(val)).join(`|${after}`);
-  }
-
-  return undefined;
 }
 
-function encodeObject({ location, key, value, style, explode, escape }) {
+/**
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#style-examples}
+ */
+function encodeObject({ location, key, value, style, explode, escape, isAllowedReserved = false }) {
   const valueEncoder = str =>
     module.exports.encodeDisallowedCharacters(str, {
       escape,
       returnIfEncoded: location === 'query',
+      isAllowedReserved,
     });
 
   const valueKeys = Object.keys(value);
 
-  if (style === 'simple') {
-    return valueKeys.reduce((prev, curr) => {
-      const val = valueEncoder(value[curr]);
-      const middleChar = explode ? '=' : ',';
-      const prefix = prev ? `${prev},` : '';
-
-      return `${prefix}${curr}${middleChar}${val}`;
-    }, '');
-  }
-
-  if (style === 'label') {
-    return valueKeys.reduce((prev, curr) => {
-      const val = valueEncoder(value[curr]);
-      const middleChar = explode ? '=' : '.';
-      const prefix = prev ? `${prev}.` : '.';
+  switch (style) {
+    /**
+     * @example <caption>`style: simple` + `explode: true`</caption>
+     * `{ "R": 100, "G": 200, "B": 150 }` → `R=100,G=200,B=150`
+     *
+     * @example <caption>`style: simple` + `explode: false` (the default behavior)</caption>
+     * `{ "R": 100, "G": 200, "B": 150 }` → `R,100,G,200,B,150`
+     */
+    case 'simple':
+      return valueKeys.reduce((prev, curr) => {
+        const val = valueEncoder(value[curr]);
+        const middleChar = explode ? '=' : ',';
+        const prefix = prev ? `${prev},` : '';
+
+        return `${prefix}${curr}${middleChar}${val}`;
+      }, '');
 
-      return `${prefix}${curr}${middleChar}${val}`;
-    }, '');
-  }
+    /**
+     * @example <caption>`style: label` + `explode: true`</caption>
+     * `{ "R": 100, "G": 200, "B": 150 }` → `.R=100.G=200.B=150`
+     *
+     * @example <caption>`style: label` + `explode: false` (the default behavior)</caption>
+     * `{ "R": 100, "G": 200, "B": 150 }` → `.R.100.G.200.B.150`
+     */
+    case 'label':
+      return valueKeys.reduce((prev, curr) => {
+        const val = valueEncoder(value[curr]);
+        const middleChar = explode ? '=' : '.';
+        const prefix = prev ? `${prev}.` : '.';
+
+        return `${prefix}${curr}${middleChar}${val}`;
+      }, '');
 
-  if (style === 'matrix' && explode) {
-    return valueKeys.reduce((prev, curr) => {
-      const val = valueEncoder(value[curr]);
-      const prefix = prev ? `${prev};` : ';';
+    /**
+     * @example <caption>`style: matrix` + `explode: true`</caption>
+     * `{ "R": 100, "G": 200, "B": 150 }` → `;R=100;G=200;B=150`
+     *
+     * @example <caption>`style: matrix` + `explode: false` (the default behavior)</caption>
+     * `{ "R": 100, "G": 200, "B": 150 }` → `;color=R,100,G,200,B,150`
+     */
+    case 'matrix':
+      if (explode) {
+        return valueKeys.reduce((prev, curr) => {
+          const val = valueEncoder(value[curr]);
+          const prefix = prev ? `${prev};` : ';';
+
+          return `${prefix}${curr}=${val}`;
+        }, '');
+      }
 
-      return `${prefix}${curr}=${val}`;
-    }, '');
-  }
+      return valueKeys.reduce((prev, curr) => {
+        const val = valueEncoder(value[curr]);
+        const prefix = prev ? `${prev},` : `;${key}=`;
 
-  if (style === 'matrix') {
-    // no explode
-    return valueKeys.reduce((prev, curr) => {
-      const val = valueEncoder(value[curr]);
-      const prefix = prev ? `${prev},` : `;${key}=`;
+        return `${prefix}${curr},${val}`;
+      }, '');
 
-      return `${prefix}${curr},${val}`;
-    }, '');
-  }
+    /**
+     * @example <caption>`style: form` + `explode: true`</caption>
+     * `{ "R": 100, "G": 200, "B": 150 }` → `R=100&G=200&B=150`
+     *
+     * @example <caption>`style: form` + `explode: false` (the default behavior)</caption>
+     * `{ "R": 100, "G": 200, "B": 150 }` → `color=R,100,G,200,B,150`
+     */
+    case 'form':
+      return valueKeys.reduce((prev, curr) => {
+        const val = valueEncoder(value[curr]);
+        const prefix = prev ? `${prev}${explode ? '&' : ','}` : '';
+        const separator = explode ? '=' : ',';
+
+        return `${prefix}${curr}${separator}${val}`;
+      }, '');
 
-  if (style === 'form') {
-    return valueKeys.reduce((prev, curr) => {
-      const val = valueEncoder(value[curr]);
-      const prefix = prev ? `${prev}${explode ? '&' : ','}` : '';
-      const separator = explode ? '=' : ',';
+    /**
+     * @example <caption>`style: spaceDelimited`</caption>
+     * `{ "R": 100, "G": 200, "B": 150 }` → `R%20100%20G%20200%20B%20150`
+     */
+    case 'spaceDelimited':
+      return valueKeys.reduce((prev, curr) => {
+        const val = valueEncoder(value[curr]);
+        const prefix = prev ? `${prev} ` : '';
 
-      return `${prefix}${curr}${separator}${val}`;
-    }, '');
-  }
+        return `${prefix}${curr} ${val}`;
+      }, '');
 
-  // Supported in 3.1, added by Readme
-  if (style === 'spaceDelimited') {
-    return valueKeys.reduce((prev, curr) => {
-      const val = valueEncoder(value[curr]);
-      const prefix = prev ? `${prev} ` : '';
+    /**
+     * @example <caption>`style: pipeDelimited`</caption>
+     * `{ "R": 100, "G": 200, "B": 150 }` → `R|100|G|200|B|150`
+     */
+    case 'pipeDelimited':
+      return valueKeys.reduce((prev, curr) => {
+        const val = valueEncoder(value[curr]);
+        const prefix = prev ? `${prev}|` : '';
 
-      return `${prefix}${curr} ${val}`;
-    }, '');
-  }
+        return `${prefix}${curr}|${val}`;
+      }, '');
 
-  // Supported in 3.1, added by Readme
-  if (style === 'pipeDelimited') {
-    return valueKeys.reduce((prev, curr) => {
-      const val = valueEncoder(value[curr]);
-      const prefix = prev ? `${prev}|` : '';
+    /**
+     * @example <caption>`style: deepObject`</caption>
+     * `{ "R": 100, "G": 200, "B": 150 }` → `color[R]=100&color[G]=200&color[B]=150`
+     */
+    case 'deepObject':
+      return valueKeys.reduce(curr => {
+        const val = valueEncoder(value[curr], {}, true);
+        return `${val}`;
+      }, '');
 
-      return `${prefix}${curr}|${val}`;
-    }, '');
+    default:
+      return undefined;
   }
-
-  return undefined;
 }
 
-function encodePrimitive({ location, key, value, style, escape }) {
+/**
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#style-examples}
+ */
+function encodePrimitive({ location, key, value, style, escape, isAllowedReserved = false }) {
   const valueEncoder = str =>
     module.exports.encodeDisallowedCharacters(str, {
       escape,
       returnIfEncoded: location === 'query' || location === 'body',
+      isAllowedReserved,
     });
 
-  if (style === 'simple') {
-    return valueEncoder(value);
-  }
-
-  if (style === 'label') {
-    return `.${valueEncoder(value)}`;
-  }
+  switch (style) {
+    /**
+     * @example <caption>`style: simple`</caption>
+     * `blue` → `blue`
+     */
+    case 'simple':
+      return valueEncoder(value);
+
+    /**
+     * @example <caption>`style: label`</caption>
+     * `blue` → `.blue`
+     */
+    case 'label':
+      return `.${valueEncoder(value)}`;
+
+    /**
+     * @example <caption>`style: matrix`</caption>
+     * `blue` → `;color=blue`
+     */
+    case 'matrix':
+      if (value === '') {
+        return `;${key}`;
+      }
 
-  if (style === 'matrix') {
-    // This conditional added by Aaron to be more accurate to the spec
-    if (value === '') {
-      return `;${key}`;
-    }
+      return `;${key}=${valueEncoder(value)}`;
 
-    return `;${key}=${valueEncoder(value)}`;
-  }
+    /**
+     * @example <caption>`style: form`</caption>
+     * `blue` → `color=blue`
+     */
+    case 'form':
+      return valueEncoder(value);
 
-  if (style === 'form') {
-    return valueEncoder(value);
-  }
+    /**
+     * @example <caption>`style: deepObject`</caption>
+     * `blue` → n/a
+     */
+    case 'deepObject':
+      return valueEncoder(value, {}, true);
 
-  if (style === 'deepObject') {
-    return valueEncoder(value, {}, true);
+    default:
+      return undefined;
   }
-
-  return undefined;
 }

package/.github/dependabot.yml

@@ -1,26 +0,0 @@
-version: 2
-updates:
-  - package-ecosystem: github-actions
-    directory: "/"
-    schedule:
-      interval: monthly
-    reviewers:
-      - erunion
-    labels:
-      - dependencies
-    commit-message:
-      prefix: chore(deps)
-      prefix-development: chore(deps-dev)
-
-  - package-ecosystem: npm
-    directory: "/"
-    schedule:
-      interval: monthly
-    open-pull-requests-limit: 10
-    reviewers:
-      - erunion
-    labels:
-      - dependencies
-    commit-message:
-      prefix: chore(deps)
-      prefix-development: chore(deps-dev)

package/.github/workflows/ci.yml

@@ -1,24 +0,0 @@
-name: CI
-
-on: [push]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [12.x, 14.x, 16.x]
-
-    steps:
-      - uses: actions/checkout@v2.4.0
-
-      - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v3
-        with:
-          node-version: ${{ matrix.node-version }}
-
-      - name: Install deps
-        run: npm ci
-
-      - name: Run tests
-        run: npm test

package/.github/workflows/codeql-analysis.yml

@@ -1,35 +0,0 @@
-name: "CodeQL"
-
-on:
-  push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
-  schedule:
-    - cron: '0 0 1 * *'
-
-jobs:
-  analyze:
-    name: Analyze
-    runs-on: ubuntu-latest
-    permissions:
-      actions: read
-      contents: read
-      security-events: write
-
-    strategy:
-      fail-fast: false
-      matrix:
-        language: [ 'javascript' ]
-
-    steps:
-    - name: Checkout repository
-      uses: actions/checkout@v2.4.0
-
-    - name: Initialize CodeQL
-      uses: github/codeql-action/init@v1
-      with:
-        languages: ${{ matrix.language }}
-
-    - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v1

package/.husky/commit-msg

@@ -1,4 +0,0 @@
-#!/bin/sh
-. "$(dirname "$0")/_/husky.sh"
-
-npx commitlint --edit $1