From a6d02239f7fe8da6fc7e4b0c03f59c5221232597 Mon Sep 17 00:00:00 2001
From: Paul Melnikow <github@paulmelnikow.com>
Date: Wed, 6 Mar 2019 22:04:08 -0500
Subject: [PATCH] Document queryParams + rename example module (#3170)

This file does more than transform, and `examples` seems is a bit more consistent with e.g. `trace.js` and `route.js`.
---
 core/base-service/base.js                     | 22 ++++++++++++++++---
 core/base-service/base.spec.js                |  2 +-
 .../{transform-example.js => examples.js}     |  0
 ...sform-example.spec.js => examples.spec.js} |  2 +-
 4 files changed, 21 insertions(+), 5 deletions(-)
 rename core/base-service/{transform-example.js => examples.js} (100%)
 rename core/base-service/{transform-example.spec.js => examples.spec.js} (98%)

diff --git a/core/base-service/base.js b/core/base-service/base.js
index 0e9e9a756f..f4c4f0f58f 100644
--- a/core/base-service/base.js
+++ b/core/base-service/base.js
@@ -14,6 +14,7 @@ const {
   InvalidParameter,
   Deprecated,
 } = require('./errors')
+const { validateExample, transformExample } = require('./examples')
 const {
   makeFullUrl,
   assertValidRoute,
@@ -23,7 +24,6 @@ const {
 } = require('./route')
 const { assertValidServiceDefinition } = require('./service-definitions')
 const trace = require('./trace')
-const { validateExample, transformExample } = require('./transform-example')
 const validate = require('./validate')
 
 const defaultBadgeDataSchema = Joi.object({
@@ -106,7 +106,22 @@ module.exports = class BaseService {
    *  - capture: Array of names for the capture groups in the regular
    *             expression. The handler will be passed an object containing
    *             the matches.
-   *  - queryParamSchema: Joi schema for valid query params.
+   *  - queryParamSchema: (Optional) A Joi schema (`Joi.object({ ... }).required()`)
+   *                      for the query param object. If you know a parameter
+   *                      will never receive a numeric string, you can use
+   *                      `Joi.string()`. Because of quirks in Scoutcamp and Joi,
+   *                      alphanumeric strings should be declared using
+   *                      `Joi.alternatives().try(Joi.string(), Joi.number())`,
+   *                      otherwise a value like `?success_color=999` will fail.
+   *                      A parameter requiring a numeric string can use
+   *                      `Joi.number()`. A parameter that receives only non-numeric
+   *                      strings can use `Joi.string()`. A parameter that never
+   *                      receives numeric can use `Joi.string()`. A boolean
+   *                      parameter should use `Joi.equal('')` and will receive an
+   *                      empty string on e.g. `?compact_message` and undefined
+   *                      when the parameter is absent. (Note that in,
+   *                      `examples.queryParams` boolean query params should be given
+   *                      `null` values.)
    */
   static get route() {
     throw new Error(`Route not defined for ${this.name}`)
@@ -142,7 +157,8 @@ module.exports = class BaseService {
    * namedParams: An object containing the values of named parameters to
    *   substitute into the compiled route pattern.
    * queryParams: An object containing query parameters to include in the
-   *   example URLs.
+   *   example URLs. For alphanumeric query parameters, specify a string value.
+   *   For boolean query parameters, specify `null`.
    * pattern: The route pattern to compile. Defaults to `this.route.pattern`.
    * staticPreview: A rendered badge of the sort returned by `handle()` or
    *   `render()`: an object containing `message` and optional `label` and
diff --git a/core/base-service/base.spec.js b/core/base-service/base.spec.js
index 6cd39c5bcd..8721ab03dd 100644
--- a/core/base-service/base.spec.js
+++ b/core/base-service/base.spec.js
@@ -397,7 +397,7 @@ describe('BaseService', function() {
           queryParams: ['queryParamA', 'legacyQueryParamA'],
         },
       })
-      // The in-depth tests for examples reside in transform-example.spec.js
+      // The in-depth tests for examples reside in examples.spec.js
       expect(examples).to.have.lengthOf(1)
     })
   })
diff --git a/core/base-service/transform-example.js b/core/base-service/examples.js
similarity index 100%
rename from core/base-service/transform-example.js
rename to core/base-service/examples.js
diff --git a/core/base-service/transform-example.spec.js b/core/base-service/examples.spec.js
similarity index 98%
rename from core/base-service/transform-example.spec.js
rename to core/base-service/examples.spec.js
index 52a767e6db..3e4d254698 100644
--- a/core/base-service/transform-example.spec.js
+++ b/core/base-service/examples.spec.js
@@ -2,7 +2,7 @@
 
 const { expect } = require('chai')
 const { test, given } = require('sazerac')
-const { validateExample, transformExample } = require('./transform-example')
+const { validateExample, transformExample } = require('./examples')
 
 describe('validateExample function', function() {
   it('passes valid examples', function() {