Add two new LocalRouter route parameter types: nullableStringParameter and nullableNumberParameter.

Author: Kai Eichinger

CHANGELOG.md

@@ -1,3 +1,9 @@
+5.20.0
+======
+
+*   (feature) Add two new `LocalRouter` route parameter types: `nullableStringParameter` and `nullableNumberParameter`.
+
+
 5.19.0
 ======
 

tests/cases/url/router-parameters.js

@@ -1,5 +1,5 @@
 import QUnit from "qunit";
-import {booleanParameter, numberParameter, stringParameter} from "../../../url/router-parameters";
+import {booleanParameter, nullableNumberParameter, nullableStringParameter, numberParameter, stringParameter} from "../../../url/router-parameters";
 
 QUnit.module("url/router-parameters");
 
@@ -143,3 +143,59 @@ QUnit.test(
         );
     }
 );
+
+QUnit.test(
+    "nullableStringParameter() valid cases",
+    (assert) =>
+    {
+        // input, defaultValue, expected
+        const cases = [
+            ["test", null, "test"],
+            ["test", undefined, "test"],
+            [null, null, null],
+            [null, undefined, null],
+            [undefined, null, null],
+            [undefined, undefined, null],
+            [null, "default", null],
+            [undefined, "default", "default"],
+            [123, null, "123"],
+            [123, undefined, "123"],
+            ["", null, null],
+            ["", undefined, null],
+        ];
+
+        cases.forEach(
+            ([input, defaultValue, expected]) =>
+            {
+                assert.strictEqual(nullableStringParameter(defaultValue)(input), expected);
+            }
+        );
+    }
+);
+
+QUnit.test(
+    "nullableNumberParameter() valid cases",
+    (assert) =>
+    {
+        // input, defaultValue, expected
+        const cases = [
+            [123, null, 123],
+            [123, undefined, 123],
+            ["123", null, 123],
+            ["123", undefined, 123],
+            [null, null, null],
+            [null, undefined, null],
+            [null, 432, 432],
+            [undefined, null, null],
+            [undefined, undefined, null],
+            [undefined, 432, 432],
+        ];
+
+        cases.forEach(
+            ([input, defaultValue, expected]) =>
+            {
+                assert.strictEqual(nullableNumberParameter(defaultValue)(input), expected);
+            }
+        );
+    }
+);

url/router-parameters.ts

@@ -6,7 +6,7 @@ import {ParameterNormalizer} from "./LocalRouter";
  *
  * @internal
  */
-function typeError (expected: string, value: any): never
+function throwTypeError (expected: string, value: any): never
 {
     throw new Error(
         undefined === value
@@ -28,7 +28,7 @@ export function stringParameter (defaultValue?: string) : ParameterNormalizer<st
         if (null == value)
         {
             return defaultValue === undefined
-                ? typeError("string", value)
+                ? throwTypeError("string", value)
                 : defaultValue;
         }
 
@@ -59,7 +59,7 @@ export function numberParameter (defaultValue?: number) : ParameterNormalizer<nu
 
         // throw if required or invalid (non-empty) value given
         return (defaultValue === undefined || null != value)
-            ? typeError("number", value)
+            ? throwTypeError("number", value)
             : defaultValue;
     };
 }
@@ -87,7 +87,69 @@ export function booleanParameter (defaultValue?: boolean) : ParameterNormalizer<
 
         // throw if required or invalid (non-empty) value given
         return (defaultValue === undefined || null != value)
-            ? typeError("boolean", value)
+            ? throwTypeError("boolean", value)
             : defaultValue;
     };
 }
+
+
+/**
+ * Normalizes the value into a nullable string.
+ *
+ * If the parameter is missing or an empty string, either the default value or `null` is returned.
+ */
+export function nullableStringParameter (defaultValue: string|null = null) : ParameterNormalizer<string|null>
+{
+    return (value) =>
+    {
+        if (typeof value === "number")
+        {
+            return "" + value;
+        }
+
+        if (null !== value && undefined !== value && typeof value !== "string")
+        {
+            throwTypeError("string or null", value);
+        }
+
+        return "" !== value && undefined !== value
+            ? value
+            : (defaultValue ?? null)
+    };
+}
+
+
+/**
+ * Normalizes the value into a nullable number.
+ *
+ * If the parameter is missing or , either the default value or `null` is returned.
+ */
+export function nullableNumberParameter (defaultValue: number|null = null) : ParameterNormalizer<number|null>
+{
+    return (value) =>
+    {
+        if (null === value)
+        {
+            return defaultValue;
+        }
+
+        if (typeof value === "number")
+        {
+            return value;
+        }
+
+        const parsed = parseInt(value, 10);
+
+        if (!isNaN(parsed))
+        {
+            return parsed;
+        }
+
+        if (defaultValue === undefined || null != value)
+        {
+            throwTypeError("number or null", value);
+        }
+
+        return defaultValue ?? null;
+    };
+}